paircode 0.11.7__tar.gz → 0.12.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paircode
-Version: 0.11.7
+Version: 0.12.1
 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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paircode"
-version = "0.11.7"
+version = "0.12.1"
 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" }

{paircode-0.11.7 → paircode-0.12.1}/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.6"
+__version__ = "0.12.0"

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

@@ -312,6 +312,152 @@ def invoke(peer_id: str, prompt: str, out_path: str, timeout: int, fast: bool) -
         raise SystemExit(1)
 
 
+# ---------------------------------------------------------------------------
+# peerlab — per-peer independent parallel labs with their own .git
+# ---------------------------------------------------------------------------
+
+@main.group()
+def peerlab() -> None:
+    """Per-peer parallel labs under .peerlab/<peer-id>/ with own .git each."""
+
+
+@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
+
+    state = find_paircode()
+    if state is None:
+        state = init_paircode()
+    results = ensure_peer_labs(state)
+    for r in results:
+        if r.status == "created":
+            click.echo(f"created {r.lab_path}")
+        elif r.status == "missing-id":
+            click.echo(f"skipped peer with no id", err=True)
+        # "already-exists" → silent, per auto-install ethos
+
+
+@peerlab.command("invoke")
+@click.argument("peer_id")
+@click.argument("prompt")
+@click.option("--out", "out_path", default=None, type=click.Path(),
+              help="Optional file-trace output (markdown). If omitted, peer stdout goes to stdout.")
+@click.option("--timeout", default=600, show_default=True,
+              help="Per-peer timeout in seconds")
+@click.option("--fast/--no-fast", default=False,
+              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
+
+    state = find_paircode()
+    if state is None:
+        raise click.ClickException(
+            "No .paircode/ found. Run `paircode ensure-scaffold` + `paircode peerlab ensure` first."
+        )
+    peers = read_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]
+        raise click.ClickException(f"Unknown peer id: {peer_id!r}. Known: {known}")
+    lab = peer_lab_path(state, peer_id)
+    if not lab.exists():
+        raise click.ClickException(
+            f"Lab dir missing: {lab}. Run `paircode peerlab ensure` first."
+        )
+
+    # Preamble so the peer knows it's in a lab with its own git
+    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"\n"
+        f"Work:\n"
+        f"{prompt}"
+    )
+
+    from cliworker import get_spec, run as cliworker_run
+
+    spec = get_spec(str(peer.get("cli")), model=peer.get("model")) if peer.get("model") else get_spec(str(peer.get("cli")))
+    results = cliworker_run(
+        framed_prompt, spec,
+        fast=True if fast else None,
+        timeout_s=timeout,
+        cwd=str(lab),
+    )
+    cli_result = results[-1] if results else None
+    if cli_result is None:
+        raise click.ClickException(f"no result from cliworker for {peer.get('cli')}")
+
+    status = "ok" if cli_result.ok else "FAIL"
+    click.echo(f"{peer_id} {status} {cli_result.duration_s:.1f}s", err=True)
+
+    body = cli_result.stdout if cli_result.ok else (
+        f"# Peer run FAILED\n\n```\n{cli_result.stderr}\n```\n\n{cli_result.stdout}"
+    )
+
+    if out_path:
+        header = (
+            f"<!-- peer_id: {peer_id} -->\n"
+            f"<!-- cli: {peer.get('cli')} -->\n"
+            f"<!-- lab: {lab} -->\n"
+            f"<!-- duration_s: {cli_result.duration_s:.1f} -->\n"
+            f"<!-- ok: {cli_result.ok} -->\n"
+        )
+        timeout_kind = getattr(cli_result, "timeout_kind", None)
+        if timeout_kind:
+            header += f"<!-- timeout_kind: {timeout_kind} -->\n"
+        header += "\n"
+        Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+        Path(out_path).write_text(header + body, encoding="utf-8")
+    else:
+        click.echo(body)
+
+    if not cli_result.ok:
+        raise SystemExit(1)
+
+
+@peerlab.command("list")
+def peerlab_list() -> None:
+    """Show peer labs with creation status + HEAD commit (if any)."""
+    from paircode.peerlab import peer_lab_path
+
+    state = find_paircode()
+    if state is None:
+        click.echo("No .paircode/ found. Nothing to list.")
+        return
+    peers = read_peers(state)
+    if not peers:
+        click.echo("No peers in roster.")
+        return
+    ptable = Table(show_header=True, header_style="bold")
+    ptable.add_column("peer")
+    ptable.add_column("lab path")
+    ptable.add_column("git HEAD")
+    import subprocess as _sub
+    for p in peers:
+        pid = p.get("id")
+        if not pid:
+            continue
+        lab = peer_lab_path(state, pid)
+        if not lab.exists():
+            ptable.add_row(pid, str(lab), "[dim](not created)[/dim]")
+            continue
+        if not (lab / ".git").exists():
+            ptable.add_row(pid, str(lab), "[yellow](no git)[/yellow]")
+            continue
+        r = _sub.run(
+            ["git", "-C", str(lab), "log", "-1", "--oneline"],
+            capture_output=True, text=True, check=False,
+        )
+        head = r.stdout.strip() if r.returncode == 0 and r.stdout.strip() else "[dim](no commits)[/dim]"
+        ptable.add_row(pid, str(lab), head)
+    console.print(ptable)
+
+
 # ---------------------------------------------------------------------------
 # Bare paircode — show state
 # ---------------------------------------------------------------------------

{paircode-0.11.7 → paircode-0.12.1}/src/paircode/installer.py

@@ -64,14 +64,19 @@ def install_claude(info: CliInfo) -> InstallResult:
         )
     commands_dir = info.config_dir / "commands"
     commands_dir.mkdir(parents=True, exist_ok=True)
-    target = commands_dir / "paircode.md"
-    target.write_text(
+    paircode_target = commands_dir / "paircode.md"
+    paircode_target.write_text(
         _read_template("claude/commands/paircode.md"),
         encoding="utf-8",
     )
+    peerlab_target = commands_dir / "peerlab.md"
+    peerlab_target.write_text(
+        _read_template("claude/commands/peerlab.md"),
+        encoding="utf-8",
+    )
     return InstallResult(
-        cli_name="claude", action="installed", path=target,
-        message=f"Wrote /paircode slash command to {target}.",
+        cli_name="claude", action="installed", path=paircode_target,
+        message=f"Wrote /paircode + /peerlab slash commands to {commands_dir}.",
     )
 
 
@@ -221,6 +226,7 @@ def uninstall_all() -> list[InstallResult]:
     claude_home = Path.home() / ".claude"
     claude_paths = [
         claude_home / "commands" / "paircode.md",
+        claude_home / "commands" / "peerlab.md",
         claude_home / "agents" / "paircode-peer.md",
     ]
     removed = []

paircode-0.12.1/src/paircode/peerlab.py

@@ -0,0 +1,194 @@
+"""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.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+from paircode.state import PaircodeState, read_peers
+
+
+PEERLAB_DIRNAME = ".peerlab"
+
+SEED_EXCLUDES: tuple[str, ...] = (
+    ".git",
+    ".peerlab",
+    ".paircode",
+    "__pycache__",
+    ".venv", "venv", "env", "ENV",
+    "node_modules",
+    ".pytest_cache", ".tox", ".mypy_cache", ".ruff_cache",
+    "build", "dist", "wheels",
+    "*.egg-info",
+    ".DS_Store",
+    ".coverage", ".coverage.*",
+    "*.pyc",
+    "htmlcov",
+)
+
+GITIGNORE_BLOCK_HEADER = "# peerlab — per-peer independent parallel labs"
+
+
+@dataclass(frozen=True)
+class EnsureResult:
+    peer_id: str
+    lab_path: Path
+    status: str  # "created" | "already-exists" | "missing-id"
+
+
+# ---------------------------------------------------------------------------
+# Helpers — gitignore, rsync, git init, initial commit
+# ---------------------------------------------------------------------------
+
+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.
+    """
+    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 (".peerlab/", ".peerlab"):
+            return False
+    tail = existing.rstrip()
+    new_text = (tail + "\n\n" if tail else "") + GITIGNORE_BLOCK_HEADER + "\n.peerlab/\n"
+    gitignore.write_text(new_text, encoding="utf-8")
+    return True
+
+
+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."""
+    dst.mkdir(parents=True, exist_ok=True)
+    rsync = shutil.which("rsync")
+    if rsync:
+        args = [rsync, "-a"]
+        for e in excludes:
+            args.extend(["--exclude", e])
+        args.extend([str(src) + "/", str(dst) + "/"])
+        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
+            for pat in exclude_set:
+                if pat.startswith("*") and n.endswith(pat[1:]):
+                    ignored.append(n); break
+                if pat.endswith("*") and n.startswith(pat[:-1]):
+                    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 _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,
+    )
+    if result.returncode != 0 or not (lab / ".git").exists():
+        subprocess.run(["git", "init", "--quiet", str(lab)], check=True)
+
+
+def _git_initial_commit(lab: Path, message: str = "initial seed from project root") -> bool:
+    """Stage everything + commit. Returns True if a commit was made.
+
+    Sets local-only user.name/email (doesn't touch global git config) so the
+    commit is authored even on machines without a global identity.
+    """
+    if not any(lab.iterdir()):
+        return False
+    # Local git config — scoped to this repo
+    subprocess.run(["git", "-C", str(lab), "config", "user.name", "paircode-peerlab"], check=False)
+    subprocess.run(["git", "-C", str(lab), "config", "user.email", "peerlab@paircode.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,
+    )
+    if diff_check.returncode == 0:
+        return False  # nothing staged
+    subprocess.run(
+        ["git", "-C", str(lab), "commit", "--quiet", "-m", message],
+        check=False,
+    )
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Public — ensure per-peer labs
+# ---------------------------------------------------------------------------
+
+def ensure_peer_labs(state: PaircodeState) -> list[EnsureResult]:
+    """Scaffold `.peerlab/<peer-id>/` for every peer in `peers.yaml`.
+
+    Idempotent. On first creation of a lab:
+    - mkdir `.peerlab/<peer-id>/`
+    - 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
+
+    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.
+    """
+    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):
+        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"))
+            continue
+        lab = peerlab_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)
+        _git_init(lab)
+        _git_initial_commit(lab, message="initial seed from project root")
+        results.append(EnsureResult(peer_id=pid, lab_path=lab, status="created"))
+    return results
+
+
+def peer_lab_path(state: PaircodeState, peer_id: str) -> Path:
+    """Return the absolute lab path for a peer id. Does not create."""
+    return state.project_root / PEERLAB_DIRNAME / peer_id

paircode-0.12.1/src/paircode/templates/claude/commands/peerlab.md

@@ -0,0 +1,71 @@
+---
+description: peerlab — each peer does real work in its own parallel lab with its own git; team lead reads the diffs and synthesizes.
+---
+
+You are the team lead for a `/peerlab` run. Each peer has its own persistent lab at `.peerlab/<peer-id>/` with its own `.git/`. Peers **own** their labs — they write code, run tests, commit as they go. Your job: fire every peer on the user's prompt, read what they actually did (the diffs), and synthesize.
+
+This is a separate concept from `/paircode` — no focus dirs, no stages, no markdown consensus files. The deliverable is real code evolution per lab + your synthesis at the end.
+
+`$ARGUMENTS` is the user's raw prompt. Pass it through verbatim.
+
+## Step 1 — Bootstrap (silent via Bash)
+
+```bash
+paircode peerlab ensure           # scaffolds + seeds + git-inits each lab (idempotent)
+PEERS=$(paircode roster --alpha claude)
+```
+
+`paircode peerlab ensure` is safe to run every time. First time: copies the project root into each peer's lab (minus standard excludes) and `git init`s it. Subsequent times: no-op.
+
+## Step 2 — Fire every peer in parallel
+
+For each peer-id in `$PEERS`, spawn one subagent via the Agent tool (`subagent_type=general-purpose`, `run_in_background=true`) — all in a single message so they run concurrently.
+
+Each subagent's prompt:
+
+```
+You are monitoring the {peer-id} peer. Run this shell command and wait:
+
+  paircode peerlab invoke {peer-id} "<the user's prompt verbatim>"
+
+That fires the peer with its cwd set to .peerlab/{peer-id}/ (its own lab).
+The peer is expected to commit its work in its own .git before finishing.
+
+After it returns, gather:
+  1. The peer's stdout (its narrative of what it did).
+  2. `git -C .peerlab/{peer-id} log --oneline -5` — recent commits.
+  3. `git -C .peerlab/{peer-id} diff HEAD~1 HEAD --stat` — what changed.
+
+Report back to team lead in under 400 words: peer-id, ok=yes/no, duration,
+1-line summary of what the peer claims it did, plus the git stat output.
+```
+
+## Step 3 — Read the actual code each peer wrote
+
+When every peer has reported, for each peer-id:
+
+```bash
+git -C .peerlab/<peer-id> log --oneline -5
+git -C .peerlab/<peer-id> diff HEAD~1 HEAD
+```
+
+Read the actual diffs (use the Read tool on the changed files inside each lab, or just the full `git diff` output). This is the real content — NOT the peer's narrative in stdout. Trust the code over the claims.
+
+## Step 4 — Synthesize (one message to user, ≤300 words)
+
+Produce a tight team-lead synthesis:
+
+- **Per-peer summary**: 1–2 lines each — files touched, LOC delta, the shape of the approach.
+- **Cross-cutting themes**: did multiple peers hit the same issue/solution? That's signal.
+- **Honest head-to-head**: which lab made the cleanest move? Which went off-track? Don't play favorites but don't hedge.
+- **What to pull into alpha**: if any peer's approach is objectively better than what alpha would do, name the files + the approach. Don't do the pull yourself — just recommend.
+
+No focus dirs. No consensus.md. No markdown artifacts on disk. Just the synthesis as your reply to the user.
+
+## Guardrails
+
+- **Alpha (this session) does NOT edit `.peerlab/<peer-id>/`.** Peers own their labs. You only read.
+- **Alpha does NOT implement the user's prompt in the project root.** That's a `/paircode` job or a direct Claude Code ask. `/peerlab` is strictly "peers go build it, I read the diffs."
+- **Fire every peer** unless the user's prompt explicitly names `--peer`/`--peers`. Watchdog protects against hangs.
+- **If a peer fails** (hung, errored, no commits), note it in the synthesis and continue. One flaky peer doesn't sink the run.
+- **No AI attribution** in anything you write — see the maintainer's CLAUDE.md.

paircode-0.12.1/tests/test_peerlab.py

@@ -0,0 +1,242 @@
+"""Tests for paircode.peerlab — per-peer parallel labs with own .git."""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from paircode.cli import main
+from paircode.handshake import ProposedPeer
+from paircode.peerlab import (
+    PEERLAB_DIRNAME,
+    ensure_gitignore,
+    ensure_peer_labs,
+    peer_lab_path,
+)
+from paircode.state import find_paircode, init_paircode
+
+
+# ---------------------------------------------------------------------------
+# ensure_peer_labs — scaffold + seed + git init + initial commit
+# ---------------------------------------------------------------------------
+
+def _seed_roster_with(tmp_path: Path, monkeypatch) -> None:
+    """Make propose_roster return codex + gemini so ensure-scaffold populates
+    peers.yaml with both, creating their sandbox dirs too."""
+    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)
+
+
+def _init_and_scaffold(tmp_path: Path, monkeypatch) -> None:
+    """Seed a .paircode/ + populated project root in tmp_path."""
+    # Simulate a small existing project at tmp_path
+    (tmp_path / "src").mkdir()
+    (tmp_path / "src" / "app.py").write_text("print('hi')\n")
+    (tmp_path / "README.md").write_text("# demo\n")
+    monkeypatch.chdir(tmp_path)
+    _seed_roster_with(tmp_path, monkeypatch)
+    runner = CliRunner()
+    runner.invoke(main, ["ensure-scaffold"])
+
+
+def test_ensure_peer_labs_creates_dirs_and_seeds_and_inits_git(tmp_path, monkeypatch):
+    """First run: each peer gets a lab, seeded from project root, with own
+    .git/ and an initial commit."""
+    _init_and_scaffold(tmp_path, monkeypatch)
+    state = find_paircode()
+    results = ensure_peer_labs(state)
+    assert len(results) == 2
+    statuses = {r.peer_id: r.status for r in results}
+    assert statuses["peer-a-codex"] == "created"
+    assert statuses["peer-b-gemini"] == "created"
+
+    peerlab_root = tmp_path / PEERLAB_DIRNAME
+    for pid in ("peer-a-codex", "peer-b-gemini"):
+        lab = peerlab_root / pid
+        assert lab.is_dir(), f"{lab} missing"
+        # Seeded contents
+        assert (lab / "src" / "app.py").is_file()
+        assert (lab / "README.md").is_file()
+        # Own git
+        assert (lab / ".git").is_dir()
+        # Initial commit exists — HEAD resolves
+        r = subprocess.run(
+            ["git", "-C", str(lab), "log", "-1", "--oneline"],
+            capture_output=True, text=True, check=False,
+        )
+        assert r.returncode == 0
+        assert r.stdout.strip(), f"no initial commit in {lab}"
+
+
+def test_ensure_peer_labs_is_idempotent(tmp_path, monkeypatch):
+    """Second call: labs already exist → status 'already-exists', no re-seed."""
+    _init_and_scaffold(tmp_path, monkeypatch)
+    state = find_paircode()
+    ensure_peer_labs(state)
+
+    # Simulate the peer evolving: write a new file, commit
+    lab = peer_lab_path(state, "peer-a-codex")
+    (lab / "new-work.py").write_text("# codex added this\n")
+    subprocess.run(["git", "-C", str(lab), "add", "-A"], check=False)
+    subprocess.run(
+        ["git", "-C", str(lab), "-c", "user.name=t", "-c", "user.email=t@t",
+         "commit", "--quiet", "-m", "codex evolution"],
+        check=False,
+    )
+
+    # Re-run ensure — should NOT wipe codex's evolution
+    results = ensure_peer_labs(state)
+    statuses = {r.peer_id: r.status for r in results}
+    assert statuses["peer-a-codex"] == "already-exists"
+    assert statuses["peer-b-gemini"] == "already-exists"
+    assert (lab / "new-work.py").exists(), "idempotent run wiped codex's work!"
+
+
+def test_ensure_gitignore_adds_peerlab_line(tmp_path):
+    """First call appends `.peerlab/` to .gitignore; second call no-ops."""
+    gitignore = tmp_path / ".gitignore"
+    gitignore.write_text("__pycache__/\n.venv/\n")
+    assert ensure_gitignore(tmp_path) is True
+    text = gitignore.read_text()
+    assert ".peerlab/" in text
+    assert "peerlab — per-peer" in text
+
+    # Second call: already there → no change
+    before = text
+    assert ensure_gitignore(tmp_path) is False
+    assert gitignore.read_text() == before
+
+
+def test_ensure_gitignore_creates_file_if_missing(tmp_path):
+    """No .gitignore → create it with the peerlab entry."""
+    gitignore = tmp_path / ".gitignore"
+    assert not gitignore.exists()
+    assert ensure_gitignore(tmp_path) is True
+    assert ".peerlab/" in gitignore.read_text()
+
+
+def test_ensure_peer_labs_greenfield_minimal_seed(tmp_path, monkeypatch):
+    """On a near-empty project, labs still get created with git. The only
+    non-git content is the `.gitignore` that ensure_peer_labs itself added
+    to the outer repo (then rsync copies it into each lab)."""
+    monkeypatch.chdir(tmp_path)
+    _seed_roster_with(tmp_path, monkeypatch)
+    runner = CliRunner()
+    runner.invoke(main, ["ensure-scaffold"])
+    state = find_paircode()
+    results = ensure_peer_labs(state)
+    statuses = {r.peer_id: r.status for r in results}
+    assert statuses["peer-a-codex"] == "created"
+    lab = peer_lab_path(state, "peer-a-codex")
+    assert lab.is_dir()
+    assert (lab / ".git").is_dir()
+    children = sorted(p.name for p in lab.iterdir() if p.name != ".git")
+    # Greenfield: only the inherited .gitignore, nothing else (no source files)
+    assert children == [".gitignore"], f"expected just .gitignore, got {children}"
+
+
+# ---------------------------------------------------------------------------
+# CLI surface — paircode peerlab ensure / list
+# ---------------------------------------------------------------------------
+
+def test_paircode_peerlab_ensure_command(tmp_path, monkeypatch):
+    _init_and_scaffold(tmp_path, monkeypatch)
+    runner = CliRunner()
+    result = runner.invoke(main, ["peerlab", "ensure"])
+    assert result.exit_code == 0, result.output
+    assert (tmp_path / ".peerlab" / "peer-a-codex").is_dir()
+    assert (tmp_path / ".peerlab" / "peer-b-gemini").is_dir()
+
+
+def test_paircode_peerlab_list_shows_head(tmp_path, monkeypatch):
+    _init_and_scaffold(tmp_path, monkeypatch)
+    runner = CliRunner()
+    runner.invoke(main, ["peerlab", "ensure"])
+    result = runner.invoke(main, ["peerlab", "list"])
+    assert result.exit_code == 0
+    assert "peer-a-codex" in result.output
+    assert "peer-b-gemini" in result.output
+
+
+def test_paircode_peerlab_help_is_reachable():
+    runner = CliRunner()
+    for argv in (["peerlab", "--help"], ["peerlab", "ensure", "--help"],
+                 ["peerlab", "invoke", "--help"], ["peerlab", "list", "--help"]):
+        result = runner.invoke(main, argv)
+        assert result.exit_code == 0, f"{argv}: {result.output}"
+
+
+# ---------------------------------------------------------------------------
+# Seed excludes honored
+# ---------------------------------------------------------------------------
+
+def test_seed_excludes_dot_paircode_and_dot_git(tmp_path, monkeypatch):
+    """Seeded labs must not contain `.paircode/` (recursion) or the outer
+    repo's `.git/` (each lab gets its own fresh git instead)."""
+    # Project has a real outer .git with real history
+    subprocess.run(["git", "-C", str(tmp_path), "init", "--quiet"], check=False)
+    subprocess.run(
+        ["git", "-C", str(tmp_path), "-c", "user.name=t", "-c", "user.email=t@t",
+         "commit", "--quiet", "--allow-empty", "-m", "outer initial"],
+        check=False,
+    )
+    # Populate via the shared helper (creates src/app.py + README.md)
+    _init_and_scaffold(tmp_path, monkeypatch)
+    state = find_paircode()
+    ensure_peer_labs(state)
+    lab = peer_lab_path(state, "peer-a-codex")
+    # Lab must not have .paircode (recursion guard)
+    assert not (lab / ".paircode").exists(), "lab should not contain .paircode/"
+    # Lab's .git exists — its OWN
+    assert (lab / ".git").exists()
+    # Critically, the outer repo's .git log must NOT have leaked into the lab's
+    # git log. They're independent histories.
+    outer_log = subprocess.run(
+        ["git", "-C", str(tmp_path), "log", "--oneline"],
+        capture_output=True, text=True, check=False,
+    ).stdout.strip()
+    lab_log = subprocess.run(
+        ["git", "-C", str(lab), "log", "--oneline"],
+        capture_output=True, text=True, check=False,
+    ).stdout.strip()
+    assert "outer initial" in outer_log
+    assert "outer initial" not in lab_log, "outer git history leaked into lab!"
+
+
+# ---------------------------------------------------------------------------
+# Installer — /peerlab.md deployed alongside /paircode.md
+# ---------------------------------------------------------------------------
+
+def test_installer_deploys_peerlab_slash_command(tmp_path, monkeypatch):
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    monkeypatch.setenv("HOME", str(fake_home))
+    import importlib
+
+    import paircode.detect as d
+    import paircode.installer as inst
+    importlib.reload(d)
+    importlib.reload(inst)
+
+    monkeypatch.setattr("shutil.which", lambda b: f"/fake/{b}")
+
+    from cliworker.core import CLIResult
+    from cliworker.registry import CLISpec
+
+    def fake_invoke(cli, *args, **kwargs):
+        return CLIResult(
+            spec=CLISpec(cli=cli), ok=True, stdout="", stderr="",
+            duration_s=0.01, returncode=0, argv=[cli, *args], skipped_reason=None,
+        )
+    monkeypatch.setattr("paircode.installer.invoke", fake_invoke)
+
+    inst.install_all()
+    peerlab_cmd = fake_home / ".claude" / "commands" / "peerlab.md"
+    assert peerlab_cmd.exists(), "install_claude must deploy /peerlab.md"
+    assert "peerlab" in peerlab_cmd.read_text()