paircode 0.12.4__tar.gz → 0.13.2__tar.gz

{paircode-0.12.4 → paircode-0.13.2}/.gitignore

@@ -38,3 +38,7 @@ dist/
 
 # paircode runtime state (focuses, peer workspaces, etc.)
 .paircode/
+.peerlab/
+
+# local agent state (Claude Code settings + lock files)
+.claude/

{paircode-0.12.4 → paircode-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paircode
-Version: 0.12.4
+Version: 0.13.2
 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.3
+Requires-Dist: cliworker>=0.8.5
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Description-Content-Type: text/markdown

paircode-0.13.2/diary/004-gemini-silent-flash-downgrade.md

@@ -0,0 +1,44 @@
+# Diary 004 — The silent free-flash downgrade: an unpinned peer rubber-stamped a consensus
+
+**Stardate:** 2026-06-17
+**Verified state:** `main`, 81 tests passing. Changes this entry: `handshake.py` (add `ProposedPeer.model`, correct the stale gemini note), `templates/peers.yaml` (model-field warning), `tests/test_handshake.py` (new).
+**TL;DR:** paircode *already* supports per-peer model pinning end-to-end. The bug was that pinning is optional and invisible, and a misconfigured CLI fails **silently** — so a `peer-b-gemini` ran `gemini-2.0-flash-001` for an entire plan consensus while masquerading as a real fork peer.
+
+---
+
+## What triggered this
+
+During an awali working session, `/paircode` was used to review an implementation plan. The Gemini peer "converged" enthusiastically with alpha — suspiciously agreeable. The maintainer's instinct: *"I don't think it's running Gemini Pro... I needed the best model possible instead of small models that just agree with you."*
+
+He was right. Investigation found the peer was running **`gemini-2.0-flash-001`** — the free-tier default — not a Pro model. Its "agreement" was flash-tier noise that polluted the consensus. The only load-bearing peer that session was Codex.
+
+## Why it happened — four silent failures stacked
+
+1. **gemini-cli auth was `oauth-personal`.** That ignores any API key entirely and uses the free Google login → flash. The paid key in the env was never consulted.
+2. **The account was free tier.** `gemini-2.5-pro` returned `limit: 0` — free tier grants *zero* Pro requests, not "rate-limited," literally none. (Fixed by the maintainer adding $25 credit → tier-1 paid.)
+3. **No model was pinned.** paircode passes no `-m` unless a peer has a `model:` field; the awali roster had none, so the CLI default (flash) won.
+4. **Nothing surfaced any of it.** The file-trace header read `<!-- model: (default) -->` — technically honest, operationally a lie. A weak model rubber-stamping consensus is the worst silent failure for an adversarial-review tool.
+
+## Key discoveries (the plumbing was already right)
+
+- **paircode supports per-peer model pinning, fully wired:** `peers.yaml model:` → `cli.py:309 peer.get("model")` → `runner.run_peer(model=...)` → `cliworker.get_spec("gemini", model=...)` → `gemini -m <model>`. Proven by `cliworker/tests/test_registry.py:64-67`. No code was missing — only discoverability and a sane default.
+- **cliworker already strips the stale key.** `registry.py` gemini spec: `env_strip=["GOOGLE_API_KEY", "GEMINI_API_KEY"]`. So even with a dead `AIza` key baked into the running Claude Code session, cliworker removes it before invoking gemini, which then falls through to `~/.gemini/.env`. **No shell restart or `~/.zshenv` edit is needed** — an earlier "you must restart" hypothesis was wrong and is retracted here.
+- **gemini-cli env loader has two traps** (`chunk-*.js` `loadEnvironment`/`findEnvFile`): (a) dotenv **never overrides** an existing `process.env` var; (b) discovery returns the **first** `.env` walking up — a Laravel repo root `.env` wins unless `advanced.ignoreLocalEnv: true`. Both matter for getting the key to land.
+- **There is no Gemini 3.5 Pro.** Pro and Flash version independently: Flash reached 3.5 (`gemini-3.5-flash`); the newest *Pro* is `gemini-3.1-pro-preview`. Cost magnitude (paid, /1M tok in/out, ≤200k): 3.1 Pro Preview $2/$12 · 2.5 Pro $1.25/$10 · 3.5 Flash $1.50/$9 (Flash output now near-Pro!) · 2.5 Flash $0.30/$2.50. A paircode peer call ≈ 1–5¢ regardless — cost is not the constraint, quality is.
+
+## The fix (this repo)
+
+The systemic root cause lived in `handshake.py`: `ProposedPeer` had no `model` field, so every auto-generated roster was born unpinned, and `_PEER_RANK` hardcoded the now-false belief *"gemini = Free tier, not for full forks."*
+
+- `ProposedPeer` gains `model: str = ""`. Because `asdict()` includes defaulted fields, **every generated roster now emits `model: ''`** — the lever is visible instead of hidden. Empty stays safely falsy downstream (`cli.py` passes no `-m`).
+- The stale gemini note is corrected to: *"Pin model: to a Pro tier — unpinned + a free/oauth login silently runs weak flash."* No model version is hardcoded (they rot fast — see "no 3.5 Pro").
+- `templates/peers.yaml` documents the `model` field with the silent-downgrade warning.
+- `tests/test_handshake.py` guards the new surface (model key present + pin round-trips).
+
+External (not this repo, recorded for trace): the maintainer's gemini-cli was reconfigured — `settings.json` auth → `gemini-api-key`, `advanced.ignoreLocalEnv: true`, `~/.gemini/.env` holding the paid key. The awali `.paircode/peers.yaml` should add `model: gemini-3.1-pro-preview` to its gemini peer — that is the per-peer, paircode-native pin and supersedes any global settings.json model.
+
+## Open paper cuts
+
+- **Resolved model is still not surfaced.** The header shows `(default)` when unpinned; paircode can't report the model the CLI actually chose because cliworker doesn't return it. A future improvement: have cliworker echo the resolved model back in `CLIResult` so the file-trace records what *ran*, not what was *requested*. That would have caught this in seconds.
+- **No preflight auth/tier check.** paircode can't tell a Pro peer from a free-flash one before spending a fork on it. A `paircode doctor`-style probe (cheap 1-token call asking tier) could warn "peer-b-gemini resolves to flash — pin a model?" at roster time.
+- **`propose_roster()` still emits `model: ''` for all CLIs.** It does not suggest a concrete Pro default per CLI (deliberately, to avoid version rot). If model-name stability ever improves, a per-CLI recommended default could be added behind `_PEER_RANK`.

{paircode-0.12.4 → paircode-0.13.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paircode"
-version = "0.12.4"
+version = "0.13.2"
 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.3",
+    "cliworker>=0.8.5",
 ]
 
 [project.urls]

{paircode-0.12.4 → paircode-0.13.2}/src/paircode/__init__.py

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

{paircode-0.12.4 → paircode-0.13.2}/src/paircode/cli.py

@@ -28,6 +28,7 @@ from paircode.handshake import propose_roster, proposed_as_yaml_dicts
 from paircode.installer import install_all, uninstall_all
 from paircode.runner import run_peer
 from paircode.state import (
+    ensure_gitignore,
     ensure_peer_dirs,
     find_paircode,
     init_paircode,
@@ -108,6 +109,9 @@ def ensure_scaffold() -> None:
     if state is None:
         state = init_paircode()
         did_init = True
+    else:
+        # Retroactively protect projects whose .paircode/ predates this guard.
+        ensure_gitignore(state.project_root)
 
     peers = read_peers(state)
     proposed_count = 0
@@ -324,12 +328,15 @@ def peerlab() -> None:
 @peerlab.command("ensure")
 def peerlab_ensure() -> None:
     """Scaffold .peerlab/<peer-id>/ per peer; seed from project root on first
-    creation; git init per lab; add .peerlab/ to outer .gitignore. Idempotent."""
-    from paircode.peerlab import ensure_peer_labs
+    creation; git init per lab; add .peerlab/ to outer .gitignore. Idempotent.
 
-    state = find_paircode()
+    Uses .peerlab/peers.yaml (peerlab's own roster), not .paircode/.
+    """
+    from paircode.peerlab import ensure_peer_labs, find_peerlab, init_peerlab
+
+    state = find_peerlab()
     if state is None:
-        state = init_paircode()
+        state = init_peerlab()
     results = ensure_peer_labs(state)
     for r in results:
         if r.status == "created":
@@ -350,14 +357,14 @@ def peerlab_ensure() -> None:
               help="Apply cliworker speed flags")
 def peerlab_invoke(peer_id: str, prompt: str, out_path: str | None, timeout: int, fast: bool) -> None:
     """Fire a peer CLI with cwd set to its lab. Peer works in-place."""
-    from paircode.peerlab import peer_lab_path
+    from paircode.peerlab import find_peerlab, peer_lab_path, read_peerlab_peers
 
-    state = find_paircode()
+    state = find_peerlab()
     if state is None:
         raise click.ClickException(
-            "No .paircode/ found. Run `paircode ensure-scaffold` + `paircode peerlab ensure` first."
+            "No .peerlab/ found. Run `paircode peerlab ensure` first."
         )
-    peers = read_peers(state)
+    peers = read_peerlab_peers(state)
     peer = next((p for p in peers if p.get("id") == peer_id), None)
     if peer is None:
         known = [p.get("id") for p in peers]
@@ -368,14 +375,21 @@ def peerlab_invoke(peer_id: str, prompt: str, out_path: str | None, timeout: int
             f"Lab dir missing: {lab}. Run `paircode peerlab ensure` first."
         )
 
-    # Preamble so the peer knows it's in a lab with its own git
+    # Preamble: peer knows where its lab is + that cross-reads outside the
+    # lab are allowed when the task says so (cross-review reads alpha's
+    # project root at ../../ and sibling peer labs at ../).
     framed_prompt = (
-        f"You are the {peer_id} peer working in your own lab at {lab}.\n"
-        f"Your cwd is already this lab. You have your own `.git/` here — commit\n"
-        f"your work (stage + commit) before finishing so the team lead can read\n"
-        f"the diff. Don't worry about alpha's repo; your lab is fully independent.\n"
+        f"You are the {peer_id} peer in a paircode peerlab run.\n"
+        f"Your own lab is at {lab} — that is your cwd. You have your own `.git/`\n"
+        f"here; commit your work in this lab before finishing so the team lead\n"
+        f"can read the diff. Modify files ONLY inside your own lab.\n"
+        f"\n"
+        f"The task below may instruct you to READ outside your lab — e.g.,\n"
+        f"alpha's project root at `../../` (alpha's lab) or sibling peer labs\n"
+        f"at `../<other-peer-id>/`. Read-only cross-reads are expected during\n"
+        f"cross-review rounds. Do not write outside your own lab.\n"
         f"\n"
-        f"Work:\n"
+        f"Task:\n"
         f"{prompt}"
     )
 
@@ -423,15 +437,15 @@ def peerlab_invoke(peer_id: str, prompt: str, out_path: str | None, timeout: int
 @peerlab.command("list")
 def peerlab_list() -> None:
     """Show peer labs with creation status + HEAD commit (if any)."""
-    from paircode.peerlab import peer_lab_path
+    from paircode.peerlab import find_peerlab, peer_lab_path, read_peerlab_peers
 
-    state = find_paircode()
+    state = find_peerlab()
     if state is None:
-        click.echo("No .paircode/ found. Nothing to list.")
+        click.echo("No .peerlab/ found. Run `paircode peerlab ensure` first.")
         return
-    peers = read_peers(state)
+    peers = read_peerlab_peers(state)
     if not peers:
-        click.echo("No peers in roster.")
+        click.echo("No peers in .peerlab/peers.yaml roster.")
         return
     ptable = Table(show_header=True, header_style="bold")
     ptable.add_column("peer")
@@ -458,6 +472,51 @@ def peerlab_list() -> None:
     console.print(ptable)
 
 
+@peerlab.command("roster")
+@click.option("--alpha", "alpha_cli", default=None,
+              help="CLI acting as alpha (excluded from peers unless last resort).")
+@click.option("--peer", "peer_filter", default=None,
+              help="Narrow to a single peer id. Silently falls back if missing.")
+@click.option("--peers", "peers_filter", default=None,
+              help="Comma-separated peer ids. Silently falls back if none match.")
+def peerlab_roster(alpha_cli: str | None, peer_filter: str | None, peers_filter: str | None) -> None:
+    """Print peerlab peer ids, one per line — best-effort, never errors.
+
+    Reads .peerlab/peers.yaml (peerlab's own roster, fully independent of
+    .paircode/). Same filter semantics as `paircode roster`.
+    """
+    from paircode.peerlab import find_peerlab, read_peerlab_peers
+
+    state = find_peerlab()
+    if state is None:
+        return
+    all_peers = [p for p in read_peerlab_peers(state) if p.get("id")]
+
+    if peers_filter:
+        wanted = [s.strip() for s in peers_filter.split(",") if s.strip()]
+        filtered = [p for p in all_peers if p.get("id") in wanted]
+    elif peer_filter:
+        filtered = [p for p in all_peers if p.get("id") == peer_filter]
+    else:
+        filtered = list(all_peers)
+
+    def _exclude_alpha(peers: list[dict]) -> list[dict]:
+        if not alpha_cli:
+            return peers
+        return [p for p in peers if p.get("cli") != alpha_cli]
+
+    result = _exclude_alpha(filtered)
+    if not result and (peer_filter or peers_filter):
+        result = _exclude_alpha(all_peers)
+    if not result:
+        result = list(all_peers)
+
+    for p in result:
+        pid = p.get("id")
+        if pid:
+            click.echo(pid)
+
+
 # ---------------------------------------------------------------------------
 # Bare paircode — show state
 # ---------------------------------------------------------------------------

{paircode-0.12.4 → paircode-0.13.2}/src/paircode/handshake.py

@@ -16,6 +16,11 @@ class ProposedPeer:
     cli: str
     priority: str
     notes: str = ""
+    # Empty = let the CLI pick its own default model. Pin a specific model string
+    # (e.g. a Pro tier) to avoid the silent free-tier trap: an unpinned peer on a
+    # free/oauth login can quietly run a weak flash model and rubber-stamp consensus.
+    # Emitted into every generated roster so the field is discoverable, not hidden.
+    model: str = ""
 
 
 # Default ranking of peers when auto-proposing a roster.
@@ -25,7 +30,7 @@ _PEER_RANK: list[tuple[str, str, str]] = [
     # (cli, priority, notes)
     ("codex", "high", "Second opinion, good for silent-agreement hunts"),
     ("ollama", "medium", "Local unlimited; good if a capable model is pulled"),
-    ("gemini", "low", "Free tier — use for quick opinions, not full forks"),
+    ("gemini", "low", "Pin model: to a Pro tier — unpinned + a free/oauth login silently runs weak flash"),
 ]
 
 

{paircode-0.12.4 → paircode-0.13.2}/src/paircode/peerlab.py

@@ -1,14 +1,25 @@
 """Per-peer independent labs — each peer owns a parallel implementation
 of the project, with its own `.git/` for independent history.
 
-Laid out under `.peerlab/<peer-id>/` at the project root, gitignored from
-the outer repo. Seeding is one-time on first creation (rsync from project
-root minus a standard exclude list). After that, each peer's lab evolves
-independently — the peer commits, diffs, experiments in its own git.
-
-Used by the `/peerlab` slash command (separate concept from `/paircode`):
-team lead fires each peer with cwd = its lab, peers do real work and commit,
-team lead reads the resulting diffs and synthesizes.
+**Fully independent from `/paircode`.** `/peerlab` maintains its own state
+under `.peerlab/` at the project root:
+
+  .peerlab/
+    peers.yaml              # peerlab's own roster
+    alpha-critique.md       # alpha's cross-review output (optional, written by slash command)
+    peer-a-codex/           # external peer lab (full parallel implementation, own .git)
+    peer-b-gemini/
+    ...
+
+`/peerlab` does NOT read or write `.paircode/`. If you use both `/paircode`
+and `/peerlab`, each maintains its own roster independently. That's
+intentional — `/peerlab` is designed to be useful as a standalone concept.
+
+Architecture: **alpha (the interactive LLM session, e.g. Claude Code) is
+itself a peer**. Alpha's "lab" is the project root — alpha codes directly
+in the real repo. This module manages the EXTERNAL peer labs (codex,
+gemini, ollama, ...). During cross-review every participant reads every
+other participant's code.
 """
 from __future__ import annotations
 
@@ -18,10 +29,11 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable
 
-from paircode.state import PaircodeState, read_peers
+import yaml
 
 
 PEERLAB_DIRNAME = ".peerlab"
+PEERLAB_PEERS_FILE = "peers.yaml"
 
 SEED_EXCLUDES: tuple[str, ...] = (
     ".git",
@@ -41,10 +53,6 @@ SEED_EXCLUDES: tuple[str, ...] = (
 
 GITIGNORE_BLOCK_HEADER = "# peerlab — per-peer independent parallel labs"
 
-# Defaults dropped into each new peer lab's own .gitignore so peer commits
-# don't accidentally include Python bytecode, editor junk, OS cruft.
-# If the lab inherited a .gitignore from the project root (rsync seed), we
-# APPEND this block — user's rules win, these are a safety net.
 LAB_GITIGNORE_BLOCK = """\
 # peerlab defaults — python + editor junk (keep peer commits clean)
 __pycache__/
@@ -66,6 +74,21 @@ htmlcov/
 LAB_GITIGNORE_MARKER = "peerlab defaults"
 
 
+# ---------------------------------------------------------------------------
+# PeerlabState — independent of PaircodeState
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class PeerlabState:
+    """`.peerlab/` state. Fully independent from `.paircode/`."""
+    root: Path                    # path to .peerlab/ dir
+    peers_path: Path              # .peerlab/peers.yaml
+
+    @property
+    def project_root(self) -> Path:
+        return self.root.parent
+
+
 @dataclass(frozen=True)
 class EnsureResult:
     peer_id: str
@@ -73,16 +96,61 @@ class EnsureResult:
     status: str  # "created" | "already-exists" | "missing-id"
 
 
+def find_peerlab(start: Path | None = None) -> PeerlabState | None:
+    """Walk up from `start` (or cwd) looking for `.peerlab/`. Return None."""
+    if start is None:
+        start = Path.cwd()
+    start = start.resolve()
+    for ancestor in [start, *start.parents]:
+        root = ancestor / PEERLAB_DIRNAME
+        if root.is_dir():
+            return PeerlabState(root=root, peers_path=root / PEERLAB_PEERS_FILE)
+    return None
+
+
+def init_peerlab(project_root: Path | None = None) -> PeerlabState:
+    """Bootstrap `.peerlab/` in `project_root` (or cwd).
+
+    Creates the dir, runs handshake to detect peer CLIs, writes a fresh
+    `peers.yaml` to `.peerlab/peers.yaml` (if missing). `handshake.propose_roster`
+    is pure — reads PATH, doesn't touch any paircode state on disk.
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+    project_root = project_root.resolve()
+    root = project_root / PEERLAB_DIRNAME
+    root.mkdir(exist_ok=True)
+    peers_path = root / PEERLAB_PEERS_FILE
+    if not peers_path.exists():
+        # Pure-function import; doesn't trigger any paircode state writes.
+        from paircode.handshake import propose_roster, proposed_as_yaml_dicts
+
+        proposed = propose_roster()
+        write_peerlab_peers(peers_path, proposed_as_yaml_dicts(proposed))
+    return PeerlabState(root=root, peers_path=peers_path)
+
+
+def read_peerlab_peers(state: PeerlabState) -> list[dict]:
+    """Parse `.peerlab/peers.yaml` into list of peer dicts. `[]` if missing."""
+    if not state.peers_path.exists():
+        return []
+    data = yaml.safe_load(state.peers_path.read_text(encoding="utf-8")) or {}
+    return list(data.get("peers") or [])
+
+
+def write_peerlab_peers(peers_path: Path, peers: Iterable[dict]) -> None:
+    peers_path.write_text(
+        yaml.safe_dump({"peers": list(peers)}, sort_keys=False, default_flow_style=False),
+        encoding="utf-8",
+    )
+
+
 # ---------------------------------------------------------------------------
-# Helpers — gitignore, rsync, git init, initial commit
+# Outer-repo gitignore — keep `.peerlab/` out of alpha's git
 # ---------------------------------------------------------------------------
 
 def ensure_gitignore(project_root: Path) -> bool:
-    """Append `.peerlab/` to outer .gitignore if not already present.
-
-    Returns True if the line was added (or the file was created), False if
-    it was already there.
-    """
+    """Append `.peerlab/` to outer `.gitignore` if not already present."""
     gitignore = project_root / ".gitignore"
     existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
     for line in existing.splitlines():
@@ -95,9 +163,12 @@ def ensure_gitignore(project_root: Path) -> bool:
     return True
 
 
+# ---------------------------------------------------------------------------
+# Per-lab helpers — rsync seed, git init, initial commit, lab .gitignore
+# ---------------------------------------------------------------------------
+
 def _rsync_project(src: Path, dst: Path, excludes: Iterable[str] = SEED_EXCLUDES) -> None:
-    """Copy src → dst with standard excludes. Uses rsync if available, falls
-    back to `shutil.copytree` with an ignore function."""
+    """Copy src → dst with standard excludes. rsync if available, else shutil."""
     dst.mkdir(parents=True, exist_ok=True)
     rsync = shutil.which("rsync")
     if rsync:
@@ -108,13 +179,11 @@ def _rsync_project(src: Path, dst: Path, excludes: Iterable[str] = SEED_EXCLUDES
         subprocess.run(args, check=True)
         return
 
-    # Pure-Python fallback: copytree with an ignore func.
     exclude_set = set(excludes)
 
     def _ignore(_directory: str, names: list[str]) -> list[str]:
         ignored = []
         for n in names:
-            # Match exact name or a simple *-prefix/suffix wildcard
             if n in exclude_set:
                 ignored.append(n)
                 continue
@@ -125,23 +194,13 @@ def _rsync_project(src: Path, dst: Path, excludes: Iterable[str] = SEED_EXCLUDES
                     ignored.append(n); break
         return ignored
 
-    # copytree fails if dst exists — but our dst was just mkdir'd.
-    # Remove empty dst and let copytree re-create.
     if dst.exists() and not any(dst.iterdir()):
         dst.rmdir()
     shutil.copytree(src, dst, ignore=_ignore)
 
 
 def ensure_lab_gitignore(lab: Path) -> bool:
-    """Ensure the peer lab has Python/editor junk gitignored. Idempotent.
-
-    If the lab already has a `.gitignore` (inherited via rsync from the
-    project root), our block is appended so user rules win. If none exists
-    (greenfield), our block IS the .gitignore.
-
-    Returns True if the block was added this call, False if it was already
-    there (marker detection).
-    """
+    """Append the peerlab-defaults .gitignore block into the lab. Idempotent."""
     gitignore = lab / ".gitignore"
     existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
     if LAB_GITIGNORE_MARKER in existing:
@@ -152,10 +211,8 @@ def ensure_lab_gitignore(lab: Path) -> bool:
 
 
 def _git_init(lab: Path) -> None:
-    """`git init` inside `lab/`. No-op if already inited."""
     if (lab / ".git").exists():
         return
-    # Try modern flag first, fall back for older git.
     result = subprocess.run(
         ["git", "init", "--quiet", "--initial-branch=main", str(lab)],
         capture_output=True, text=True, check=False,
@@ -167,32 +224,22 @@ def _git_init(lab: Path) -> None:
 def _git_initial_commit(
     lab: Path, peer_id: str, message: str = "initial seed from project root"
 ) -> bool:
-    """Stage everything + commit. Returns True if a commit was made.
-
-    Authors the commit as the peer itself (`{peer_id} <{peer_id}@peerlab.local>`)
-    via lab-local git config. Every subsequent peer commit inside this lab
-    inherits that local identity — so `git log` in a peer's lab attributes
-    all work to that peer, clean replay.
-    """
+    """Stage everything + commit as peer_id. Returns True if a commit was made."""
     if not any(lab.iterdir()):
         return False
-    # Local git config — scoped to this lab, doesn't touch global identity.
     subprocess.run(["git", "-C", str(lab), "config", "user.name", peer_id], check=False)
     subprocess.run(
         ["git", "-C", str(lab), "config", "user.email", f"{peer_id}@peerlab.local"],
         check=False,
     )
     subprocess.run(["git", "-C", str(lab), "add", "-A"], check=False)
-    # Commit only if there's something staged
     diff_check = subprocess.run(
-        ["git", "-C", str(lab), "diff", "--cached", "--quiet"],
-        check=False,
+        ["git", "-C", str(lab), "diff", "--cached", "--quiet"], check=False,
     )
     if diff_check.returncode == 0:
-        return False  # nothing staged
+        return False
     subprocess.run(
-        ["git", "-C", str(lab), "commit", "--quiet", "-m", message],
-        check=False,
+        ["git", "-C", str(lab), "commit", "--quiet", "-m", message], check=False,
     )
     return True
 
@@ -201,41 +248,34 @@ def _git_initial_commit(
 # Public — ensure per-peer labs
 # ---------------------------------------------------------------------------
 
-def ensure_peer_labs(state: PaircodeState) -> list[EnsureResult]:
-    """Scaffold `.peerlab/<peer-id>/` for every peer in `peers.yaml`.
+def ensure_peer_labs(state: PeerlabState) -> list[EnsureResult]:
+    """Scaffold `.peerlab/<peer-id>/` for every peer in `.peerlab/peers.yaml`.
 
     Idempotent. On first creation of a lab:
-    - mkdir `.peerlab/<peer-id>/`
+    - mkdir
     - rsync project root → lab (minus SEED_EXCLUDES)
-    - `git init` inside lab (own repo)
-    - initial commit so HEAD exists → peers can `git diff HEAD~1` immediately
+    - drop lab .gitignore
+    - `git init` inside lab
+    - initial commit authored as peer_id so HEAD exists + log attributes clean
 
     On subsequent calls: skip labs that already have `.git/` — never re-seed.
-    Also ensures the outer `.gitignore` contains `.peerlab/` so the outer repo
-    doesn't accidentally track peer labs.
+    Also ensures the outer `.gitignore` contains `.peerlab/`.
     """
     project_root = state.project_root
-    peerlab_root = project_root / PEERLAB_DIRNAME
-    peerlab_root.mkdir(exist_ok=True)
-
     ensure_gitignore(project_root)
 
     results: list[EnsureResult] = []
-    for p in read_peers(state):
+    for p in read_peerlab_peers(state):
         pid = p.get("id") if isinstance(p, dict) else getattr(p, "id", None)
         if not pid:
-            results.append(EnsureResult(peer_id="?", lab_path=peerlab_root, status="missing-id"))
+            results.append(EnsureResult(peer_id="?", lab_path=state.root, status="missing-id"))
             continue
-        lab = peerlab_root / pid
+        lab = state.root / pid
         if (lab / ".git").exists():
             results.append(EnsureResult(peer_id=pid, lab_path=lab, status="already-exists"))
             continue
         lab.mkdir(exist_ok=True)
-        # Seed from project root (might be empty for greenfield — rsync handles fine)
         _rsync_project(project_root, lab)
-        # Drop peerlab-default .gitignore so peer commits don't pull in
-        # __pycache__, .pytest_cache, editor junk etc. Appends if the lab
-        # already inherited a .gitignore from the project root.
         ensure_lab_gitignore(lab)
         _git_init(lab)
         _git_initial_commit(lab, pid, message="initial seed from project root")
@@ -243,6 +283,6 @@ def ensure_peer_labs(state: PaircodeState) -> list[EnsureResult]:
     return results
 
 
-def peer_lab_path(state: PaircodeState, peer_id: str) -> Path:
+def peer_lab_path(state: PeerlabState, peer_id: str) -> Path:
     """Return the absolute lab path for a peer id. Does not create."""
-    return state.project_root / PEERLAB_DIRNAME / peer_id
+    return state.root / peer_id

{paircode-0.12.4 → paircode-0.13.2}/src/paircode/state.py

@@ -31,6 +31,8 @@ PEERS_FILE = "peers.yaml"
 JOURNEY_FILE = "JOURNEY.md"
 FOCUS_FILE = "FOCUS.md"
 
+GITIGNORE_BLOCK_HEADER = "# paircode — adversarial multi-LLM peer review state"
+
 
 def _now_iso() -> str:
     return _dt.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
@@ -127,6 +129,24 @@ def ensure_peer_dirs(state: PaircodeState, proposed: Iterable) -> list[Path]:
     return created
 
 
+def ensure_gitignore(project_root: Path) -> bool:
+    """Append `.paircode/` to outer `.gitignore` if not already present.
+
+    Mirrors `peerlab.ensure_gitignore`. Idempotent; returns True when a line
+    is added, False when `.paircode/` (or `.paircode`) is already listed.
+    """
+    gitignore = project_root / ".gitignore"
+    existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
+    for line in existing.splitlines():
+        s = line.strip()
+        if s in (".paircode/", ".paircode"):
+            return False
+    tail = existing.rstrip()
+    new_text = (tail + "\n\n" if tail else "") + GITIGNORE_BLOCK_HEADER + "\n.paircode/\n"
+    gitignore.write_text(new_text, encoding="utf-8")
+    return True
+
+
 def init_paircode(project_root: Path | None = None, force: bool = False) -> PaircodeState:
     """Bootstrap .paircode/ in `project_root` (or cwd). Returns the new state.
 
@@ -143,6 +163,7 @@ def init_paircode(project_root: Path | None = None, force: bool = False) -> Pair
         )
     root.mkdir(parents=True, exist_ok=True)
     (root / "sandbox").mkdir(exist_ok=True)
+    ensure_gitignore(project_root)
 
     journey = _render(
         _read_template("JOURNEY.md"),