paircode 0.11.3__tar.gz → 0.11.7__tar.gz

{paircode-0.11.3 → paircode-0.11.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paircode
-Version: 0.11.3
+Version: 0.11.7
 Summary: Adversarial journey framework — orchestrate multiple LLM peers through research, plan, and execute stages with file-trace peer review.
 Project-URL: Homepage, https://github.com/starshipagentic/paircode
 Project-URL: Repository, https://github.com/starshipagentic/paircode
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1
-Requires-Dist: cliworker>=0.8.1
+Requires-Dist: cliworker>=0.8.3
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Description-Content-Type: text/markdown
@@ -76,9 +76,9 @@ your-project/
   .paircode/
     JOURNEY.md                    # fleet log
     peers.yaml                    # roster: who's on the team
-    peers/
+    sandbox/
       peer-a-codex/               # codex's persistent sandbox (code goes here)
-      peer-b-gemini/               # gemini's persistent sandbox
+      peer-b-gemini/              # gemini's persistent sandbox
     focus-01-<slug>/
       FOCUS.md                    # this focus's prompt + metadata
       research/
@@ -97,7 +97,7 @@ your-project/
 
 **Code vs. reports.** Files inside `focus-*/` are markdown *reports* (opinions, plans, critiques, summaries of work). Actual code lives elsewhere:
 
-- **Peers** code in their sandboxed workspaces at `.paircode/peers/<peer-id>/` — persistent across focuses.
+- **Peers** code in their sandboxed workspaces at `.paircode/sandbox/<peer-id>/` — persistent across focuses.
 - **Alpha** codes directly in the project root (the real repo) — alpha *is* the project.
 
 ## Stages

{paircode-0.11.3 → paircode-0.11.7}/README.md

@@ -48,9 +48,9 @@ your-project/
   .paircode/
     JOURNEY.md                    # fleet log
     peers.yaml                    # roster: who's on the team
-    peers/
+    sandbox/
       peer-a-codex/               # codex's persistent sandbox (code goes here)
-      peer-b-gemini/               # gemini's persistent sandbox
+      peer-b-gemini/              # gemini's persistent sandbox
     focus-01-<slug>/
       FOCUS.md                    # this focus's prompt + metadata
       research/
@@ -69,7 +69,7 @@ your-project/
 
 **Code vs. reports.** Files inside `focus-*/` are markdown *reports* (opinions, plans, critiques, summaries of work). Actual code lives elsewhere:
 
-- **Peers** code in their sandboxed workspaces at `.paircode/peers/<peer-id>/` — persistent across focuses.
+- **Peers** code in their sandboxed workspaces at `.paircode/sandbox/<peer-id>/` — persistent across focuses.
 - **Alpha** codes directly in the project root (the real repo) — alpha *is* the project.
 
 ## Stages

{paircode-0.11.3 → paircode-0.11.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paircode"
-version = "0.11.3"
+version = "0.11.7"
 description = "Adversarial journey framework — orchestrate multiple LLM peers through research, plan, and execute stages with file-trace peer review."
 readme = "README.md"
 license = { text = "MIT" }
@@ -39,7 +39,7 @@ dependencies = [
     "click>=8.1",
     "pyyaml>=6.0",
     "rich>=13.0",
-    "cliworker>=0.8.1",
+    "cliworker>=0.8.3",
 ]
 
 [project.urls]

{paircode-0.11.3 → paircode-0.11.7}/src/paircode/__init__.py

@@ -2,4 +2,4 @@
 
 See README.md and diary/001-step-a-architecture.md for the full design.
 """
-__version__ = "0.11.2"
+__version__ = "0.11.6"

{paircode-0.11.3 → paircode-0.11.7}/src/paircode/cli.py

@@ -115,9 +115,15 @@ def ensure_scaffold() -> None:
         proposed = propose_roster()
         if proposed:
             write_peers(state, proposed_as_yaml_dicts(proposed))
-            ensure_peer_dirs(state, proposed)
+            peers = proposed_as_yaml_dicts(proposed)
             proposed_count = len(proposed)
 
+    # Always reconcile sandbox dirs with the roster-of-record (peers.yaml).
+    # Idempotent via mkdir(exist_ok=True); recreates any missing peer sandbox.
+    # Without this, roster peers added after first init (or dropped by a rename)
+    # never get their sandbox dir back.
+    ensure_peer_dirs(state, peers)
+
     if did_init:
         click.echo(f"init {state.root}")
     if proposed_count:

{paircode-0.11.3 → paircode-0.11.7}/src/paircode/runner.py

@@ -107,8 +107,14 @@ def run_peer(
         f"<!-- cli: {cli} -->\n"
         f"<!-- model: {model or '(default)'} -->\n"
         f"<!-- duration_s: {cli_result.duration_s:.1f} -->\n"
-        f"<!-- ok: {cli_result.ok} -->\n\n"
+        f"<!-- ok: {cli_result.ok} -->\n"
     )
+    # Surface the cliworker watchdog's reason on failure so downstream tools
+    # can tell startup-idle hangs apart from hard timeouts apart from real errors.
+    timeout_kind = getattr(cli_result, "timeout_kind", None)
+    if timeout_kind:
+        header += f"<!-- timeout_kind: {timeout_kind} -->\n"
+    header += "\n"
     if cli_result.ok:
         body = cli_result.stdout
     else:

{paircode-0.11.3 → paircode-0.11.7}/src/paircode/state.py

@@ -4,9 +4,9 @@ The .paircode/ layout (from diary/001-step-a-architecture.md):
 
   .paircode/
     JOURNEY.md              ← fleet log, focus transitions
-    peers.yaml              ← roster
-    peers/
-      peer-a-{cli}/         ← per-peer working dir (+profile.md, +code if full-fork)
+    peers.yaml              ← roster (who's on the team)
+    sandbox/
+      peer-a-{cli}/         ← per-peer persistent sandbox (code/scripts/prototypes)
     focus-01-{slug}/
       FOCUS.md
       research/
@@ -53,7 +53,7 @@ class PaircodeState:
     root: Path                       # path to .paircode/ dir itself
     journey_path: Path
     peers_path: Path
-    peers_dir: Path
+    sandbox_dir: Path
     focus_dirs: list[Path]           # sorted by name
 
     @property
@@ -90,7 +90,7 @@ def load_state(root: Path) -> PaircodeState:
         root=root,
         journey_path=root / JOURNEY_FILE,
         peers_path=root / PEERS_FILE,
-        peers_dir=root / "peers",
+        sandbox_dir=root / "sandbox",
         focus_dirs=focus_dirs,
     )
 
@@ -109,19 +109,19 @@ def _peer_id(entry) -> str | None:
 
 
 def ensure_peer_dirs(state: PaircodeState, proposed: Iterable) -> list[Path]:
-    """Create .paircode/peers/{peer.id}/ for each entry. Idempotent.
+    """Create .paircode/sandbox/{peer.id}/ for each entry. Idempotent.
 
     Accepts iterables of ProposedPeer dataclasses OR plain dicts (anything
     with an `id` attribute / key). Silently skips entries without a usable id.
-    Returns the list of peer-dir paths that now exist (created or pre-existing).
+    Returns the list of sandbox-dir paths that now exist (created or pre-existing).
     """
-    state.peers_dir.mkdir(exist_ok=True)
+    state.sandbox_dir.mkdir(exist_ok=True)
     created: list[Path] = []
     for entry in proposed:
         pid = _peer_id(entry)
         if not pid:
             continue
-        peer_dir = state.peers_dir / pid
+        peer_dir = state.sandbox_dir / pid
         peer_dir.mkdir(exist_ok=True)
         created.append(peer_dir)
     return created
@@ -130,7 +130,7 @@ def ensure_peer_dirs(state: PaircodeState, proposed: Iterable) -> list[Path]:
 def init_paircode(project_root: Path | None = None, force: bool = False) -> PaircodeState:
     """Bootstrap .paircode/ in `project_root` (or cwd). Returns the new state.
 
-    Also pre-creates a subdir per auto-detected peer under .paircode/peers/.
+    Also pre-creates a subdir per auto-detected peer under .paircode/sandbox/.
     If no peers are detected, the parent dir exists but stays empty.
     """
     if project_root is None:
@@ -142,7 +142,7 @@ def init_paircode(project_root: Path | None = None, force: bool = False) -> Pair
             f"{root} already exists. Use --force to overwrite, or `paircode status` to inspect."
         )
     root.mkdir(parents=True, exist_ok=True)
-    (root / "peers").mkdir(exist_ok=True)
+    (root / "sandbox").mkdir(exist_ok=True)
 
     journey = _render(
         _read_template("JOURNEY.md"),
@@ -162,8 +162,8 @@ def init_paircode(project_root: Path | None = None, force: bool = False) -> Pair
 
         ensure_peer_dirs(state, propose_roster())
     except Exception:
-        # Scaffolding peers is best-effort; a detect failure shouldn't
-        # block bootstrap. The peers/ parent dir is already there.
+        # Scaffolding sandboxes is best-effort; a detect failure shouldn't
+        # block bootstrap. The sandbox/ parent dir is already there.
         pass
 
     return state

{paircode-0.11.3 → paircode-0.11.7}/src/paircode/templates/claude/commands/paircode.md

@@ -18,12 +18,11 @@ Inside every `$FOCUS/{stage}/`:
 
 `N` in `vN` is the current round number, starting at 1. Only write v1 in the first round; bump to v2, v3, … if you do review rounds.
 
-**Code vs. reports.** Every file inside `$FOCUS/{stage}/` is a **markdown report** (opinion, critique, plan, or summary of work). Actual code lives elsewhere:
+**Reports vs. code — the three rules.** Files inside `$FOCUS/{stage}/` are always **markdown reports** (opinions, plans, critiques, summaries). Actual code lives elsewhere, and sandboxes are **always available, never required**:
 
-- **Peers** code in their sandboxed workspace at `.paircode/peers/{peer-id}/` — persistent across focuses, each peer builds there.
-- **Alpha** codes directly in the project root (the user's repo) — alpha IS the project, no sandbox.
-
-The `$FOCUS/execute/*-v1.md` files describe what was done; the `$FOCUS/execute/` dir is never where code is written.
+1. **Always available.** Peers can use their persistent sandbox at `.paircode/sandbox/{peer-id}/` at **any stage** — not just execute. Verifying a bug in `ask`, grounding research in real data, prototyping a tricky plan section — all fine. Alpha (this Claude session) works directly in the project root (the user's repo). **Code only when it makes your answer materially better** — a 5-line verification script is cheap insurance; a 500-line prototype during an `ask` is over-engineering.
+2. **Separation.** Markdown is the deliverable; the sandbox is the laboratory. Scripts, prototypes, dumps, evidence files live in `.paircode/sandbox/{peer-id}/`. The `$FOCUS/{stage}/*-v1.md` file summarizes what you did + what it proved. The `$FOCUS/` tree is never where code is written.
+3. **Isolation.** Peers never touch files outside their own sandbox. Alpha never touches other peers' sandboxes. The project root is alpha's.
 
 ## Step 1 — Bootstrap
 
@@ -44,34 +43,41 @@ PEERS=$(paircode roster --alpha claude <user's --peer/--peers flags if any>)
 
 `paircode roster` always returns a usable list. Trust it.
 
-## Step 2 — Pick the stage
+## Step 2 — Pick the flow (not just a stage)
+
+Read the user's quoted prompt and pick the **whole flow** you're committing to. Store it as `{flow}`. Each flow is an ordered list of stages; you run them in order.
 
-Read the user's quoted prompt and decide which stage best fits. Store your pick as `{stage}`:
+| Flow | Deliverable | Trigger phrases |
+|---|---|---|
+| `ask` | Opinion on existing work | "what do you think", "review X", "critique", "second opinion" |
+| `research` | Investigation report | "figure out", "explore", "find the right", "how should we" |
+| `research → plan` | Concrete plan | "plan the X", "design the Y", "lay out the approach" |
+| `research → plan → execute` | **Shipped code / action done** | "build", "fix", "implement", "write code for", "ship", "do", and most imperative tasks |
+| `execute` | Just do it (plan already exists) | "execute the plan at focus-NN", "run the migration from focus-05" |
 
-- **research** — explore new ground, figure something out. ("build a KISS PHQ-9 depression engine", "find the right TTS library", "how should we approach X")
-- **plan** — produce a concrete implementation plan, usually building on prior research. ("plan the refactor based on focus-02's research")
-- **execute** — do the work from an existing plan. ("execute the plan at focus-02")
-- **ask** — get opinions on existing work. ("what does codex think of this PR", "review my approach at <path>")
+**Default when ambiguous: `research → plan → execute`.** It's safer to over-deliver than to stop at research for a prompt that meant "build this." The only prompts that aren't build-shaped are explicit opinion/review requests.
 
-When unsure, pick `research` — it's the safe cold-investigation default. All four stage subdirs already exist under `$FOCUS` — no mkdir needed.
+Write `{flow}` into `$FOCUS/FOCUS.md` (append a line like `flow: research → plan → execute`) so later steps can see your commitment.
+
+The stage for **this iteration** is the first stage in `{flow}`. Store that as `{stage}`. All four stage subdirs already exist under `$FOCUS`.
 
 ## Step 3 — Fire peers in parallel
 
 For each peer id in `$PEERS`, spawn one subagent using the **Agent tool** with `subagent_type=general-purpose` and `run_in_background=true`. Send them all in a single message so they run truly concurrently.
 
-Construct a stage-appropriate peer prompt. The general shape for each `{stage}`:
+Construct a stage-appropriate peer prompt. Every prompt reminds the peer its sandbox is available; the deliverable is always the markdown report. General shape for each `{stage}`:
 
-- **research**: "Read $FOCUS/FOCUS.md. Give an honest, skeptical, specific **cold take** on the prompt. Clean markdown, no preamble."
-- **plan**: "Read $FOCUS/FOCUS.md and any `../research/*-FINAL.md` if present. Write a **concrete step-by-step plan** for this prompt: goal, scope, numbered steps, risks, success criteria. Be KISS. Clean markdown."
-- **execute**: "Read $FOCUS/FOCUS.md and the plan at `$FOCUS/plan/*-FINAL.md`. **Execute the plan IN YOUR PEER WORKSPACE at `.paircode/peers/{peer-id}/`** — that is your persistent sandbox. Write code there, run commands there. Do NOT touch files outside that workspace. Then write a markdown report to your output file summarizing: what you built, files touched (paths relative to your peer workspace), tests/verification status, what's open. The output file holds the *report*; the *code* lives in your peer workspace."
-- **ask**: "Read $FOCUS/FOCUS.md and the artifact it points to. Give your **honest critique** of that artifact — what's wrong, what's right, severity-ranked findings with file:line citations where possible. Clean markdown, no preamble."
+- **research**: "Read $FOCUS/FOCUS.md. Give an honest, skeptical, specific **cold take** on the prompt. Use your sandbox at `.paircode/sandbox/{peer-id}/` to write quick scripts grounding your claims in real data (not README marketing) if it would sharpen your take. Clean markdown report, no preamble."
+- **plan**: "Read $FOCUS/FOCUS.md and any `../research/*-FINAL.md` if present. Write a **concrete step-by-step plan**: goal, scope, numbered steps, risks, success criteria. Be KISS. Use your sandbox at `.paircode/sandbox/{peer-id}/` to prototype tricky sections and verify feasibility. Clean markdown."
+- **execute**: "Read $FOCUS/FOCUS.md and the plan at `$FOCUS/plan/*-FINAL.md`. **Carry out the plan and produce working artifacts.** For code-shipping plans: work in your peer workspace at `.paircode/sandbox/{peer-id}/`, write code there, run commands there, run tests there. For action plans (run a migration, make an API call, file a ticket): do the action and report results. Do NOT touch files outside your workspace. Your output is a markdown report summarizing what you built/ran, files touched, verification status, what's open."
+- **ask**: "Read $FOCUS/FOCUS.md and the artifact it points to. Give your **honest critique** — severity-ranked findings with file:line citations where possible. If reproducing a claim by running a quick script in your sandbox (`.paircode/sandbox/{peer-id}/`) would make your critique sharper, do it. Your output is still a critique report, not a prototype. Clean markdown, no preamble."
 
 Each subagent's prompt:
 
 ```
 You are the {peer-id} peer in a paircode {stage} cycle.
 
-Your persistent workspace: .paircode/peers/{peer-id}/
+Your persistent workspace: .paircode/sandbox/{peer-id}/
 The focus we're on: $FOCUS
 The prompt from the user: "<the quoted prompt>"
 The stage: {stage}
@@ -93,7 +99,7 @@ Do not try to "fix" the peer's output. We want the raw file-trace on disk.
 
 While the peer subagents run, you (the team lead) write your own v1 at `$FOCUS/{stage}/alpha-v1.md`. Use the Write tool. Same stage-appropriate rules as above — and your advantage over the peers is you have this session's full context (memory, recent work, the maintainer's voice).
 
-**Execute-stage asymmetry:** when `{stage}` is `execute`, peers code inside their sandboxed peer workspaces (`.paircode/peers/{peer-id}/`). You, alpha, code directly in the project root — you're working on the user's actual repo. Your `alpha-v1.md` is a report summarizing what landed in the real project files; the code itself lives in the repo, not in `$FOCUS/execute/`.
+**Execute-stage asymmetry:** when `{stage}` is `execute`, peers code inside their sandboxed peer workspaces (`.paircode/sandbox/{peer-id}/`). You, alpha, code directly in the project root — you're working on the user's actual repo. Your `alpha-v1.md` is a report summarizing what landed in the real project files; the code itself lives in the repo, not in `$FOCUS/execute/`.
 
 ## Step 5 — Wait and read
 
@@ -136,20 +142,13 @@ Then read every `*-FINAL.md` and write `$FOCUS/{stage}/consensus.md` via the Wri
 
 Adversarial-but-honest. No pile-on. No rubber-stamping either.
 
-## Step 8 — Next stage or done?
-
-After a stage converges, decide whether to transition to another stage or wrap up:
+## Step 8 — Advance the flow (mechanical)
 
-- **Done** — the user's prompt is now served. Go to Step 9.
-- **Next stage** — move to whichever stage follows naturally from what you just finished. Pick the new `{stage}`, then jump back to **Step 3** (Fire peers). Skip Step 1 — focus is still open. Skip Step 2 — you already picked. The previous stage's `*-FINAL.md` files are input for the next stage's peer prompts.
+Look at the `{flow}` you committed to in Step 2. Set `{stage}` to the **next** stage in that flow and jump back to **Step 3** (Fire peers). Skip Step 1 (focus is still open) and Step 2 (flow already chosen). The previous stage's `*-FINAL.md` files are input for the next stage's peer prompts.
 
-Typical chains:
-- `ask → done`
-- `research → done` (if research itself was the deliverable)
-- `research → plan → execute → done` (most common full-build chain)
-- `research → plan → done` (when the plan is the deliverable and the maintainer will execute manually)
+**If the last stage just finished, go to Step 9.**
 
-Back-to-Step-3 recursion is how paircode moves through multiple stages in one invocation. No round cap, no stage cap — team lead's call when to stop.
+This step is mechanical. Do not re-deliberate. Do not ask the user whether to continue. The user's prompt in `$ARGUMENTS` was implicit go-ahead for the whole flow; stopping early is an exception that only happens if **something blocked you** (a peer hard-errored and the blocker is critical, the consensus explicitly said "do not proceed", or the user interrupted). If you do stop early, say so explicitly in the final report with the reason.
 
 ## Step 9 — Final report
 
@@ -166,4 +165,7 @@ Keep it under 200 words. Brief, honest, actionable.
 - **Never skip Step 1.** The focus and roster helpers do the work Python is better at.
 - **Never invent peer commands.** Always route through `paircode invoke <id> "..." --out <path>` — that's how cliworker's speed flags, MCP strip, and output tracing work.
 - **Never pass the interactive Claude session as a peer by mistake.** `paircode roster --alpha claude` handles that for you.
+- **Fire every peer in `paircode roster`** unless the user's prompt explicitly passes `--peer`/`--peers`. don't quarantine on prior failures.
+- **Peer sandboxes are always available, never required.** Use them when it materially sharpens your answer, not by default.
+- **The user's prompt is implicit go-ahead for the whole `{flow}`.** Do not pause for permission between stages. If you must stop early, say so explicitly in the final report with the reason.
 - **No AI attribution** in any artifact you write (consensus.md, alpha-*.md). See the maintainer's CLAUDE.md.

{paircode-0.11.3 → paircode-0.11.7}/src/paircode/templates/codex/commands/paircode.md

@@ -21,7 +21,7 @@ Inside every `$FOCUS/{stage}/`:
 
 **Code vs. reports.** Every file inside `$FOCUS/{stage}/` is a **markdown report** (opinion, critique, plan, or summary of work). Actual code lives elsewhere:
 
-- **Peers** code in their sandboxed workspace at `.paircode/peers/{peer-id}/` — persistent across focuses.
+- **Peers** code in their sandboxed workspace at `.paircode/sandbox/{peer-id}/` — persistent across focuses.
 - **Alpha** codes directly in the project root (the user's repo) — alpha IS the project, no sandbox.
 
 The `$FOCUS/execute/*-v1.md` files describe what was done; the `$FOCUS/execute/` dir is never where code is written.
@@ -77,14 +77,14 @@ Construct one per stage — keep it reusable across peers:
 
 - **research**: "Read $FOCUS/FOCUS.md. Give an honest, skeptical, specific **cold take** on the prompt. Clean markdown, no preamble."
 - **plan**: "Read $FOCUS/FOCUS.md and any `../research/*-FINAL.md` if present. Write a **concrete step-by-step plan** for this prompt: goal, scope, numbered steps, risks, success criteria. Be KISS. Clean markdown."
-- **execute**: "Read $FOCUS/FOCUS.md and the plan at `$FOCUS/plan/*-FINAL.md`. **Execute the plan IN YOUR PEER WORKSPACE at `.paircode/peers/{peer-id}/`** — that is your persistent sandbox. Write code there, run commands there. Do NOT touch files outside that workspace. Then write a markdown report to your output file summarizing: what you built, files touched (paths relative to your peer workspace), tests/verification status, what's open. The output file holds the *report*; the *code* lives in your peer workspace."
+- **execute**: "Read $FOCUS/FOCUS.md and the plan at `$FOCUS/plan/*-FINAL.md`. **Execute the plan IN YOUR PEER WORKSPACE at `.paircode/sandbox/{peer-id}/`** — that is your persistent sandbox. Write code there, run commands there. Do NOT touch files outside that workspace. Then write a markdown report to your output file summarizing: what you built, files touched (paths relative to your peer workspace), tests/verification status, what's open. The output file holds the *report*; the *code* lives in your peer workspace."
 - **ask**: "Read $FOCUS/FOCUS.md and the artifact it points to. Give your **honest critique** — severity-ranked findings with file:line citations where possible. Clean markdown, no preamble."
 
 ## Step 4 — Team lead's own take
 
 After the serial peer loop completes (or right after you kick it off if your tools allow), write your own v1 at `$FOCUS/{stage}/alpha-v1.md` using the shell tool (e.g. `cat > ... <<'EOF'`). Same stage-appropriate rules as above — your advantage over the peers is session context (memory, recent work, the maintainer's voice).
 
-**Execute-stage asymmetry:** when `{stage}` is `execute`, peers code inside their sandboxed peer workspaces (`.paircode/peers/{peer-id}/`). You, alpha, code directly in the project root — the user's actual repo. Your `alpha-v1.md` is a report summarizing what landed in the real project files; the code itself lives in the repo, not in `$FOCUS/execute/`.
+**Execute-stage asymmetry:** when `{stage}` is `execute`, peers code inside their sandboxed peer workspaces (`.paircode/sandbox/{peer-id}/`). You, alpha, code directly in the project root — the user's actual repo. Your `alpha-v1.md` is a report summarizing what landed in the real project files; the code itself lives in the repo, not in `$FOCUS/execute/`.
 
 ## Step 5 — Wait and read
 

{paircode-0.11.3 → paircode-0.11.7}/src/paircode/templates/gemini/commands/paircode.toml

@@ -21,7 +21,7 @@ N in vN is the current round number, starting at 1. Only write v1 in the first r
 
 **Code vs. reports.** Every file inside $FOCUS/{stage}/ is a markdown report (opinion, critique, plan, or summary of work). Actual code lives elsewhere:
 
-- Peers code in their sandboxed workspace at .paircode/peers/{peer-id}/ — persistent across focuses.
+- Peers code in their sandboxed workspace at .paircode/sandbox/{peer-id}/ — persistent across focuses.
 - Alpha codes directly in the project root (the user's repo) — alpha IS the project, no sandbox.
 
 The $FOCUS/execute/*-v1.md files describe what was done; the $FOCUS/execute/ dir is never where code is written.
@@ -71,14 +71,14 @@ Construct one per stage — keep it reusable across peers:
 
 - research: "Read $FOCUS/FOCUS.md. Give an honest, skeptical, specific cold take on the prompt. Clean markdown, no preamble."
 - plan: "Read $FOCUS/FOCUS.md and any ../research/*-FINAL.md if present. Write a concrete step-by-step plan for this prompt: goal, scope, numbered steps, risks, success criteria. Be KISS. Clean markdown."
-- execute: "Read $FOCUS/FOCUS.md and the plan at $FOCUS/plan/*-FINAL.md. Execute the plan IN YOUR PEER WORKSPACE at .paircode/peers/{peer-id}/ — that is your persistent sandbox. Write code there, run commands there. Do NOT touch files outside that workspace. Then write a markdown report to your output file summarizing: what you built, files touched (paths relative to your peer workspace), tests/verification status, what's open. The output file holds the report; the code lives in your peer workspace."
+- execute: "Read $FOCUS/FOCUS.md and the plan at $FOCUS/plan/*-FINAL.md. Execute the plan IN YOUR PEER WORKSPACE at .paircode/sandbox/{peer-id}/ — that is your persistent sandbox. Write code there, run commands there. Do NOT touch files outside that workspace. Then write a markdown report to your output file summarizing: what you built, files touched (paths relative to your peer workspace), tests/verification status, what's open. The output file holds the report; the code lives in your peer workspace."
 - ask: "Read $FOCUS/FOCUS.md and the artifact it points to. Give your honest critique — severity-ranked findings with file:line citations where possible. Clean markdown, no preamble."
 
 ## Step 4 — Team lead's own take
 
 After the serial peer loop completes, write your own v1 to $FOCUS/{stage}/alpha-v1.md via run_shell_command (cat > ... <<'EOF' or equivalent). Same stage-appropriate rules — your advantage over the peers is session context.
 
-**Execute-stage asymmetry:** when {stage} is execute, peers code inside their sandboxed peer workspaces (.paircode/peers/{peer-id}/). You, alpha, code directly in the project root — the user's actual repo. Your alpha-v1.md is a report summarizing what landed in the real project files; the code itself lives in the repo, not in $FOCUS/execute/.
+**Execute-stage asymmetry:** when {stage} is execute, peers code inside their sandboxed peer workspaces (.paircode/sandbox/{peer-id}/). You, alpha, code directly in the project root — the user's actual repo. Your alpha-v1.md is a report summarizing what landed in the real project files; the code itself lives in the repo, not in $FOCUS/execute/.
 
 ## Step 5 — Wait and read
 

{paircode-0.11.3 → paircode-0.11.7}/src/paircode/templates/peers.yaml

@@ -5,7 +5,7 @@
 # project root.
 #
 # Every other LLM that participates is a peer. Each peer gets an entry
-# below AND a folder at .paircode/peers/peer-N-{cli}/.
+# below AND a folder at .paircode/sandbox/peer-N-{cli}/.
 #
 # Fields:
 #   id              — peer-a, peer-b, peer-c, ... (unique, immutable)

{paircode-0.11.3 → paircode-0.11.7}/tests/test_cli_smoke.py

@@ -126,6 +126,43 @@ def test_ensure_scaffold_is_idempotent(tmp_path, monkeypatch):
     assert second.output.strip() == ""
 
 
+def test_ensure_scaffold_recreates_missing_peer_sandbox(tmp_path, monkeypatch):
+    """Roster-of-record wins. If peers.yaml has a peer but its sandbox dir
+    went missing (rename, manual rm, whatever), ensure-scaffold must recreate
+    it on next run — idempotently."""
+    import shutil
+
+    from paircode.handshake import ProposedPeer
+
+    monkeypatch.chdir(tmp_path)
+    peers = [
+        ProposedPeer(id="peer-a-codex", cli="codex", priority="high", notes=""),
+        ProposedPeer(id="peer-b-gemini", cli="gemini", priority="low", notes=""),
+    ]
+    monkeypatch.setattr("paircode.cli.propose_roster", lambda: peers)
+    runner = CliRunner()
+    runner.invoke(main, ["ensure-scaffold"])
+
+    sandbox = tmp_path / ".paircode" / "sandbox"
+    assert (sandbox / "peer-a-codex").is_dir()
+    assert (sandbox / "peer-b-gemini").is_dir()
+
+    # Simulate the real-world drift: gemini's sandbox gets deleted.
+    shutil.rmtree(sandbox / "peer-b-gemini")
+    assert not (sandbox / "peer-b-gemini").exists()
+
+    # Re-running ensure-scaffold must put it back. Roster (peers.yaml) is
+    # the source of truth — propose_roster() returning the same list should
+    # NOT be required for reconciliation.
+    monkeypatch.setattr("paircode.cli.propose_roster", lambda: [])
+    result = runner.invoke(main, ["ensure-scaffold"])
+    assert result.exit_code == 0, result.output
+    assert (sandbox / "peer-b-gemini").is_dir(), (
+        "ensure-scaffold should reconcile sandbox dirs against peers.yaml, "
+        "not just on fresh handshake"
+    )
+
+
 # ---------------------------------------------------------------------------
 # focus new / focus active
 # ---------------------------------------------------------------------------

{paircode-0.11.3 → paircode-0.11.7}/tests/test_state.py

@@ -22,13 +22,13 @@ def test_init_creates_paircode_structure(tmp_path: Path):
     assert state.root.is_dir()
     assert state.journey_path.exists()
     assert state.peers_path.exists()
-    assert state.peers_dir.is_dir()
+    assert state.sandbox_dir.is_dir()
     assert state.focus_count == 0
     assert state.active_focus is None
 
 
 def test_init_scaffolds_peer_dirs_from_detected_clis(tmp_path: Path, monkeypatch):
-    """init_paircode should create .paircode/peers/{id}/ for each detected peer."""
+    """init_paircode should create .paircode/sandbox/{id}/ for each detected peer."""
     fake_proposed = [
         ProposedPeer(id="peer-a-codex", cli="codex", priority="high", notes=""),
         ProposedPeer(id="peer-b-gemini", cli="gemini", priority="low", notes=""),
@@ -36,15 +36,15 @@ def test_init_scaffolds_peer_dirs_from_detected_clis(tmp_path: Path, monkeypatch
     monkeypatch.setattr("paircode.handshake.propose_roster", lambda: fake_proposed)
 
     state = init_paircode(tmp_path)
-    assert (state.peers_dir / "peer-a-codex").is_dir()
-    assert (state.peers_dir / "peer-b-gemini").is_dir()
+    assert (state.sandbox_dir / "peer-a-codex").is_dir()
+    assert (state.sandbox_dir / "peer-b-gemini").is_dir()
 
 
-def test_init_with_no_detected_peers_leaves_peers_dir_empty(tmp_path: Path, monkeypatch):
+def test_init_with_no_detected_peers_leaves_sandbox_dir_empty(tmp_path: Path, monkeypatch):
     monkeypatch.setattr("paircode.handshake.propose_roster", lambda: [])
     state = init_paircode(tmp_path)
-    assert state.peers_dir.is_dir()
-    assert list(state.peers_dir.iterdir()) == []
+    assert state.sandbox_dir.is_dir()
+    assert list(state.sandbox_dir.iterdir()) == []
 
 
 def test_ensure_peer_dirs_accepts_dicts_and_is_idempotent(tmp_path: Path, monkeypatch):
@@ -54,7 +54,7 @@ def test_ensure_peer_dirs_accepts_dicts_and_is_idempotent(tmp_path: Path, monkey
     dicts = [{"id": "peer-a-codex", "cli": "codex"}, {"id": "peer-c-ollama"}]
     created = ensure_peer_dirs(state, dicts)
     assert len(created) == 2
-    assert (state.peers_dir / "peer-a-codex").is_dir()
+    assert (state.sandbox_dir / "peer-a-codex").is_dir()
     # Running again is a no-op (idempotent)
     created_again = ensure_peer_dirs(state, dicts)
     assert len(created_again) == 2