version: "1.0.0" name: isolate-parallel-work description: 'Use BEFORE dispatching work that touches files or requires exclusive access to a server/port. Triggered by the need to run multiple agents concurrently or to prevent clobbering. Do NOT use for verifying output, guarding runtime, or composing payloads.'

isolate-parallel-work — prevent clobbering and contention

When multiple agents (local sessions, cloud subagents, or manual edits) work on the same repo or share a server, isolation is mandatory.

Detect other running sessions

"Look for other sessions" is not actionable. Use signals, not intuition:

1. Servers and their owners: list what is actually listening before assuming a port is yours.

``bash # narrow the grep to whatever port range your launcher scans, not a guessed one lsof -nP -iTCP -sTCP:LISTEN | grep -E ':80[0-9][0-9]' ``

1. Which agent sessions are live, and where they point. Read each candidate process's environment: the

endpoint variable is the only reliable local-vs-remote tell, because a "this is local" shell flag leaks into any later process started from the same shell. ``bash ps eww <pid> | tr ' ' '\n' | grep -m1 '^ANTHROPIC_BASE_URL=' lsof -a -p <pid> -d cwd -Fn # what that session is working on ``

1. Catch sessions whose process you mis-matched: recently-modified transcript files reveal activity your

process grep missed. ``bash # <transcripts-dir> = wherever the harness writes per-session transcripts # (for Claude Code: ~/.claude/projects/<cwd-slug>/) find <transcripts-dir> -name '*.jsonl' -mmin -20 ``

1. Check the queue-admission setting before sharing a single-slot server: with admission set to wait,

concurrent requests queue instead of erroring; without it, the second request can wedge the server permanently. Verify it on the running process rather than assuming the launcher set it.

Share a single-slot server safely

If multiple agents must use the same single-slot server (e.g., vllm-mlx):

1. Queue requests: Do not dispatch simultaneously. Use a queue or sequential dispatch.
2. Monitor contention: If one agent is generating, others must wait.

Give file-touching delegates their own worktree/branch

If a delegate modifies files:

1. Create a worktree or branch: Give the delegate its own isolated workspace.

``bash git worktree add ../worktree-<id> <branch> ``

1. Dispatch to the worktree: Point the delegate’s file operations to the worktree path.
2. Merge after verification: Only merge the worktree into the main branch after verify-delegated-work passes.

Isolate parallel sessions

If launching a parallel local session:

1. Use a disjoint file set: Ensure the two agents do not touch the same files.
2. Use separate ports: If possible, run each session on its own server instance to avoid contention.