Struct LoopContext 

pub struct LoopContext { /* private fields */ }

Context for resolving paths within a Ralph loop.

Encapsulates the working directory and loop identity, providing consistent path resolution for all loop-local state files.

Implementations

impl LoopContext

pub fn primary(workspace: PathBuf) -> Self

Creates context for the primary loop running in the main workspace.

The primary loop holds the loop lock and runs directly in the repository root without filesystem isolation.

pub fn worktree( loop_id: impl Into<String>, worktree_path: PathBuf, repo_root: PathBuf, ) -> Self

Creates context for a worktree-based loop.

Worktree loops run in isolated git worktrees with their own .ralph/ directory, but share memories, specs, and code tasks via symlink.

Arguments

• loop_id - Unique identifier for this loop (e.g., “loop-1234-abcd”)
• worktree_path - Path to the worktree directory
• repo_root - Path to the main repository root (for symlinks)

pub fn loop_id(&self) -> Option<&str>

Returns the loop identifier, if any.

Primary loops return None; worktree loops return their unique ID.

pub fn is_primary(&self) -> bool

Returns true if this is the primary loop.

pub fn workspace(&self) -> &Path

Returns the workspace root for this loop.

This is the directory where the loop executes:

• Primary: the repo root
• Worktree: the worktree directory

pub fn repo_root(&self) -> &Path

Returns the main repository root.

For worktree loops, this is different from workspace() and is used to locate shared resources like the main memories file.

pub fn ralph_dir(&self) -> PathBuf

Path to the .ralph/ directory for this loop.

pub fn agent_dir(&self) -> PathBuf

Path to the .ralph/agent/ directory for this loop.

This directory contains agent state: memories, tasks, scratchpad, etc.

pub fn events_path(&self) -> PathBuf

Path to the events JSONL file.

Each loop has its own isolated events file.

pub fn current_events_marker(&self) -> PathBuf

Path to the current-events marker file.

This file contains the path to the active events file.

pub fn urgent_steer_path(&self) -> PathBuf

Path to the urgent-steer marker file.

This file is created when ! arrives during an active iteration so ralph emit can block handoff until the current model turn has seen it.

pub fn tasks_path(&self) -> PathBuf

Path to the tasks JSONL file.

Each loop has its own isolated tasks file.

pub fn scratchpad_path(&self) -> PathBuf

Path to the scratchpad markdown file.

Each loop has its own isolated scratchpad.

pub fn memories_path(&self) -> PathBuf

Path to the memories markdown file.

For primary loops, this is the actual memories file. For worktree loops, this is a symlink to the main repo’s memories.

pub fn main_memories_path(&self) -> PathBuf

Path to the main repository’s memories file.

Used to create symlinks in worktree loops.

pub fn context_path(&self) -> PathBuf

Path to the context markdown file.

This file contains worktree metadata (loop ID, workspace, branch, etc.) and is only created in worktree loops.

pub fn specs_dir(&self) -> PathBuf

Path to the specs directory for this loop.

For primary loops, this is the actual specs directory. For worktree loops, this is a symlink to the main repo’s specs.

pub fn code_tasks_dir(&self) -> PathBuf

Path to the code tasks directory for this loop.

For primary loops, this is the actual code tasks directory. For worktree loops, this is a symlink to the main repo’s code tasks. Note: This is different from tasks_path() which is for runtime task tracking.

pub fn main_specs_dir(&self) -> PathBuf

Path to the main repository’s specs directory.

Used to create symlinks in worktree loops.

pub fn main_code_tasks_dir(&self) -> PathBuf

Path to the main repository’s code tasks directory.

Used to create symlinks in worktree loops.

pub fn summary_path(&self) -> PathBuf

Path to the summary markdown file.

Each loop has its own isolated summary.

pub fn handoff_path(&self) -> PathBuf

Path to the handoff markdown file.

Generated on loop completion to provide context for the next session. Contains completed tasks, remaining work, and a ready-to-paste prompt.

pub fn diagnostics_dir(&self) -> PathBuf

Path to the diagnostics directory.

Each loop has its own diagnostics output.

pub fn history_path(&self) -> PathBuf

Path to the loop history JSONL file.

Event-sourced history for crash recovery and debugging.

pub fn loop_lock_path(&self) -> PathBuf

Path to the loop lock file (only meaningful for primary loop detection).

pub fn merge_queue_path(&self) -> PathBuf

Path to the merge queue JSONL file.

The merge queue is shared across all loops (in main repo).

pub fn loop_registry_path(&self) -> PathBuf

Path to the loop registry JSON file.

The registry is shared across all loops (in main repo).

pub fn planning_sessions_dir(&self) -> PathBuf

Path to the planning sessions directory.

Contains all planning session subdirectories.

pub fn planning_session_dir(&self, id: &str) -> PathBuf

Path to a specific planning session directory.

Arguments

• id - The session ID (e.g., “20260127-143022-a7f2”)

pub fn planning_conversation_path(&self, id: &str) -> PathBuf

Path to the conversation file for a planning session.

Arguments

• id - The session ID

pub fn planning_session_metadata_path(&self, id: &str) -> PathBuf

Path to the session metadata file for a planning session.

Arguments

• id - The session ID

pub fn planning_artifacts_dir(&self, id: &str) -> PathBuf

Path to the artifacts directory for a planning session.

Arguments

• id - The session ID

pub fn ensure_ralph_dir(&self) -> Result<()>

Ensures the .ralph/ directory exists.

pub fn ensure_agent_dir(&self) -> Result<()>

Ensures the .ralph/agent/ directory exists.

pub fn ensure_specs_dir(&self) -> Result<()>

Ensures the .ralph/specs/ directory exists.

pub fn ensure_code_tasks_dir(&self) -> Result<()>

Ensures the .ralph/tasks/ directory exists.

pub fn ensure_directories(&self) -> Result<()>

Ensures all required directories exist.

pub fn setup_memory_symlink(&self) -> Result<bool>

Creates the memory symlink in a worktree pointing to main repo.

This is only relevant for worktree loops. For primary loops, this is a no-op.

Returns

• Ok(true) - Symlink was created
• Ok(false) - Already exists or is primary loop
• Err(_) - Symlink creation failed

pub fn setup_specs_symlink(&self) -> Result<bool>

Creates the specs symlink in a worktree pointing to main repo.

This allows worktree loops to access specs from the main repo, even when they are untracked (not committed to git).

Returns

• Ok(true) - Symlink was created
• Ok(false) - Already exists or is primary loop
• Err(_) - Symlink creation failed

pub fn setup_code_tasks_symlink(&self) -> Result<bool>

Creates the code tasks symlink in a worktree pointing to main repo.

This allows worktree loops to access code task files from the main repo, even when they are untracked (not committed to git).

Returns

• Ok(true) - Symlink was created
• Ok(false) - Already exists or is primary loop
• Err(_) - Symlink creation failed

pub fn generate_context_file(&self, branch: &str, prompt: &str) -> Result<bool>

Generates a context.md file in the worktree with metadata.

This file tells the agent it’s running in a worktree and provides information about the worktree context (loop ID, workspace, branch, etc.)

Arguments

• branch - The git branch name for this worktree
• prompt - The prompt that started this loop

Returns

• Ok(true) - Context file was created
• Ok(false) - Already exists or is primary loop
• Err(_) - File creation failed

pub fn setup_worktree_symlinks(&self) -> Result<()>

Sets up all worktree symlinks (memories, specs, code tasks).

Convenience method that calls all setup_*_symlink methods. Only relevant for worktree loops - no-op for primary loops.

Trait Implementations

impl Clone for LoopContext

fn clone(&self) -> LoopContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LoopContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.