paircode 0.10.1__tar.gz → 0.11.1__tar.gz

{paircode-0.10.1 → paircode-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paircode
-Version: 0.10.1
+Version: 0.11.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.1/diary/002-v0.10-release-pipeline.md

@@ -0,0 +1,126 @@
+# Diary 002 — v0.10 release pipeline + cliworker split + satellite repos
+
+**Stardate:** 2026-04-18
+**From:** v0.9.1 (file-drop install for all 3 CLIs)
+**To:** v0.10.1 (native register via satellite repos, driven by `cliworker.invoke()`)
+
+---
+
+## Context — what v0.10 cracked open
+
+Between v0.1 and v0.9 paircode's installer evolved through four bad implementations (broken codex rules file, per-CLI no-ops, file-drop, correct file-drop) before landing on the right answer in v0.10: use each vendor's own registration command, not file-drop.
+
+Research (2026-04-18) confirmed both Codex and Gemini now have user-level slash-command registration:
+- Codex 0.121.0 → `codex marketplace add <owner/repo>` (git-clones a marketplace repo)
+- Gemini 0.35.3 → `gemini extensions install <url> --consent` (git-clones an extension repo)
+
+Neither is deprecated (Codex has both `marketplace` and a now-deprecated `prompts/` file-drop). Industry pattern for tools installing their own slash commands → **native register when available**. So paircode joins that pattern.
+
+## The three-repo architecture
+
+```
+~/dev/paircode              Python package (main repo, pypi)
+├── src/paircode/templates/
+│   ├── claude_slash_command.md      source of truth
+│   ├── codex_slash_command.md       ↓
+│   └── gemini_slash_command.toml    ↓
+└── scripts/release.py               auto-syncs to satellites
+
+~/dev/paircode-codex        Codex marketplace satellite (GitHub only)
+├── .agents/plugins/marketplace.json
+├── plugins/paircode/
+│   ├── .codex-plugin/plugin.json
+│   └── commands/paircode.md         copied from paircode's template
+└── README + LICENSE
+
+~/dev/paircode-gemini       Gemini extension satellite (GitHub only)
+├── gemini-extension.json
+├── commands/paircode.toml           copied from paircode's template
+└── README + LICENSE
+```
+
+**Zero Python in the satellites.** The Python `paircode` CLI lives once, on pypi. Satellites hold only the slash-command manifest each vendor expects. `/paircode` triggers a markdown/TOML prompt telling the host CLI to shell out to the `paircode` binary — which the user already installed via `pipx install paircode`.
+
+## Install flow after v0.10
+
+```bash
+pipx install paircode          # Python binary, once
+paircode install               # registers /paircode in every detected LLM CLI
+```
+
+`paircode install` does per CLI:
+- **claude** — file-drop `~/.claude/commands/paircode.md` (unchanged, it's the native pattern)
+- **codex**  — `cliworker.invoke("codex", "marketplace", "add", "starshipagentic/paircode-codex")`
+- **gemini** — `cliworker.invoke("gemini", "extensions", "install", "https://github.com/starshipagentic/paircode-gemini", "--consent")`
+
+All three idempotent:
+- claude overwrites file (harmless)
+- codex greps `~/.codex/config.toml` for `[marketplaces.paircode]` before invoking
+- gemini greps `gemini extensions list` for `paircode` before invoking
+
+All three graceful on failure:
+- If the `invoke()` call returns ok=False, installer prints the exact command for copy-paste + captured stderr
+- Never silently succeeds with a non-working state
+
+## Why `cliworker.invoke()` exists
+
+cliworker already had `run(prompt, *clis, ...)` for LLM invocation. Admin commands like `codex marketplace add` aren't LLM invocations — no prompt, no API-key stripping, no CLAUDE_FAST, no fallback chain. But they DO want cliworker's subprocess plumbing: timeout, FileNotFoundError handling, `CLIResult` dataclass, skip-cache opt-in.
+
+v0.8 of cliworker added `invoke(cli, *args, ...)` — same subprocess guts, no LLM semantics. Default `stdin=DEVNULL` so any unexpected interactive prompt fails fast instead of hanging (critical: Gemini's `extensions install` has a fallback "install via git clone?" prompt if the GitHub release is missing).
+
+Paircode uses it. Navcom can use it later. Any tool that wants "run a CLI, get a CLIResult back" gets it for free.
+
+## The release pipeline
+
+`scripts/release.py` is the only command needed to cut a paircode release:
+
+```bash
+cd ~/dev/paircode
+./scripts/release.py 0.11.0      # explicit version
+./scripts/release.py patch       # auto-bump patch segment
+./scripts/release.py minor
+./scripts/release.py --dry-run 0.11.0    # preview, write nothing
+```
+
+What it does in order:
+1. Preflight — working trees clean, tests pass, required tools present (git, starforge, gh)
+2. Bump paircode version in `pyproject.toml` + `src/paircode/__init__.py`
+3. Commit + tag + push paircode to GitHub
+4. `starforge beam --pypi` → publishes to pypi (with user's auto-approved yes pipe)
+5. For each satellite:
+   - Copy latest template from paircode's `src/paircode/templates/`
+   - Bump version in the satellite's manifest
+   - Commit + tag + push
+   - `starforge beam` (no --pypi, just GitHub)
+   - `gh release create` — **critical** for Gemini, which falls back to an interactive prompt when the release is missing
+6. Print summary with every URL
+
+One command = pypi, main GitHub repo, both satellite GitHub repos, both satellite GitHub releases, all version-locked.
+
+## Open paper cuts (not shipping blockers)
+
+- **`__version__` string drift** — starforge auto-bumps `pyproject.toml` version on publish (e.g., 0.10.0 → 0.10.1) but leaves `__init__.py` alone. Every release needs a manual follow-up commit to sync. The release.py script could detect starforge's bump and sync automatically; not implemented yet.
+- **Codex has no uninstall CLI** — paircode's `uninstall` for codex edits `~/.codex/config.toml` directly (strips the `[marketplaces.paircode]` section). Fragile. If OpenAI adds `codex marketplace remove <name>`, migrate to that.
+- **Gemini keychain warning** — on macOS Homebrew install, gemini prints `Keychain initialization encountered an error: Cannot find module '../build/Release/keytar.node'` before every command. It falls back to FileKeychain so everything still works. Not a paircode bug; noisy stderr captured in some idempotency checks. Could be suppressed.
+
+## Key files — where to look when something changes
+
+| Change this template | Edit this file | Satellites auto-sync on next release |
+|---|---|---|
+| Claude slash command | `src/paircode/templates/claude_slash_command.md` | (only Claude; no satellite) |
+| Codex slash command | `src/paircode/templates/codex_slash_command.md` | `paircode-codex/plugins/paircode/commands/paircode.md` |
+| Gemini slash command | `src/paircode/templates/gemini_slash_command.toml` | `paircode-gemini/commands/paircode.toml` |
+| Runner (subprocess → LLM) | `src/paircode/runner.py` (delegates to `cliworker.run`/`run_fast`) | — |
+| Installer behavior | `src/paircode/installer.py` (delegates to `cliworker.invoke`) | — |
+| Release steps | `scripts/release.py` | — |
+
+## Verified live (2026-04-18)
+
+- `cliworker` 0.8.1 on pypi with `invoke()`
+- `paircode` 0.10.1 on pypi, depends on `cliworker>=0.8.1`
+- `starshipagentic/paircode-codex` at tag v0.10.0, GitHub release live
+- `starshipagentic/paircode-gemini` at tag v0.10.0, GitHub release live
+- End-to-end `paircode uninstall && paircode install` on dev machine: all three CLIs cleanly register/deregister, `/paircode` appears in each tool's slash menu
+- 52 pytest green in paircode, 88 pytest green in cliworker
+
+*End of diary 002. Next milestone targets: real-data validation, cross-project orchestration.*

paircode-0.11.1/diary/003-arch-b-pivot-grappling.md

@@ -0,0 +1,133 @@
+# Diary 003 — Arch-B pivot: cold-use failure exposed Python-driven orchestrator as a regression
+
+**Stardate:** 2026-04-20
+**From:** v0.10.1 — Python-driven orchestrator (drive.py with ThreadPoolExecutor spawning fresh `claude -p` / `gemini -p` / `codex exec` subprocesses in parallel)
+**Toward:** Arch B — interactive Claude session IS the team lead; Python shrinks to filesystem scaffolding + template rendering
+
+**This diary is a preservation record, not a migration log.** No code has changed on `main` beyond this file. A companion branch `path-python-controls-stages` pins the current Python-driven state so we can return if Arch B underdelivers.
+
+---
+
+## What triggered this pivot
+
+The maintainer ran `/paircode` cold in Claude Code after weeks away, trying to get a second opinion on an unrelated engineering question. He typed:
+
+```
+/paircode use gemini for reserach only to 'i mean go look at their actual releases...'
+```
+
+Four concrete failures in one invocation:
+
+1. **Slash command pass-through failed.** `~/.claude/commands/paircode.md` instructs the LLM to pass args literally to the CLI. `paircode use gemini for research only to '...'` → `Error: No such command 'use'`. The slash command's own literal-pass-through instruction is the failing case.
+2. **Fallback picked the wrong flag.** The previous session fell back to `paircode drive "<topic>" --alpha-cli gemini --research-only`. Wrong: `--alpha-cli` swaps the driver — it replaces Claude with Gemini as alpha. The maintainer wanted Claude (this session) to keep driving and Gemini to be added as a peer. Inverted alpha/peer.
+3. **No primitive for "just get an opinion".** The architecture has `research → plan → execute`. "What does Gemini think of X" isn't any of those — it's review-of-existing. No native primitive. The previous session hacked it with `--research-only`, which is semantically wrong.
+4. **Flag soup.** `--alpha-cli`, `--alpha-model`, `--timeout`, `--research-rounds`, `--plan-rounds`, `--execute-rounds`, `--research-only`. User has to pre-classify their task into flag combinations before typing the quoted prompt.
+
+The redesign brief written mid-session (see conversation transcript 2026-04-20) names these as Gap 1–4.
+
+## What the maintainer wants
+
+Single verb CLI:
+
+```
+paircode "<whatever you want>"                      # ~95% of invocations
+paircode "<whatever>" --peer gemini                 # filter roster to one peer
+paircode "<whatever>" --peers gemini,codex          # subset
+```
+
+The LLM reads the quoted prompt and picks the right stages itself. Stages (research / plan / execute / ask-or-review) become invisible templates the LLMs consult, not CLI verbs the user types.
+
+Plus the philosophy, stated verbatim in the session: *"my philosophy is auto fucking install bro!"* — setup work like `init`, `handshake` happens silently inside the main verb. Saved as a feedback memory under `/Users/t/.claude/projects/-Users-t-dev-paircode/memory/feedback_auto_install.md`.
+
+## The architectural fork — Arch A vs Arch B
+
+The real discovery of this session is that today's `drive.py` architecture is **the opposite of what worked in the maintainer's original mlmodel repo.** Comparing the two:
+
+|  | Arch A — current paircode | Arch B — mlmodel pattern |
+|---|---|---|
+| Alpha identity | Fresh `claude -p` subprocess spawned by Python | Interactive Claude session where `/paircode` was typed |
+| Alpha's context | None (headless, no memory, no session) | Full (session + user memory + project state) |
+| Orchestrator | Python `ThreadPoolExecutor` in drive.py | The interactive Claude session itself, via its Bash + Agent tools |
+| Claude peers | Fresh `claude -p` subprocess | In-process Agent tool subagents (background) |
+| Codex/Gemini peers | `cliworker.run()` → shell subprocess | Bash subprocess |
+| Runs after user closes Claude? | Yes (headless loop) | No (dies with session) |
+| Python code surface | Large — drive.py, gates.py, ThreadPoolExecutor | Small — scaffold + template render |
+
+**Evidence for Arch B being what the maintainer originally built:**
+
+- `/Users/t/clients/syra/mlmodel/.claude/commands/peerkickoff.md` — team lead is the interactive Claude, spawns two Agent-tool subagents in parallel with `run_in_background=true`, then synthesizes.
+- `/Users/t/clients/syra/mlmodel/.claude/commands/audit-me.md` — interactive Claude spawns one subagent that shells out to codex CLI for peer review.
+- `/Users/t/clients/syra/mlmodel/.claude/commands/audit-codex.md` — interactive Claude does PART 1 (review) itself with full context, then spawns a subagent to fire codex for self-heal.
+- **Zero Python orchestrator binary in mlmodel.** Slash command markdown + Bash + Agent tool handles everything.
+
+The maintainer confirmed this was his "worked fucking great" baseline. Today's paircode drive.py is a regression introduced during vibe-coding that built a Python thread pool which spawns the very `claude -p` subprocess that strips alpha of its session context.
+
+## Decisions made in this session
+
+**CLI surface (user-facing):**
+- `paircode "<prompt>"` — the one verb.
+- `paircode` bare — prints current state (eats what `status` used to do).
+- `paircode install` / `paircode uninstall` — stay. One-time setup that writes to `~/.claude`, `~/.codex`, `~/.gemini`. Maintainer explicitly said this is fine because users self-selected into it by installing paircode.
+- **Dies as user verbs:** `init`, `handshake`, `status`, `focus`, `stage`, `seal`, `drive`.
+
+**Auto-silent preconditions inside the main verb:**
+- If `.paircode/` missing → `init_paircode()` runs silently.
+- If `peers.yaml` empty / stale → handshake runs silently.
+- Focus creation is procedural (`open_focus()` in state.py), always-new-per-invocation by default, escape hatch `--continue` to reuse the most recent unsealed focus when the previous team lead flaked.
+
+**Semantic decisions vs mechanical decisions:**
+- LLMs decide: is this a new topic? is this round converged? which focus to continue? who gets which stage?
+- Python decides: where files go on disk, how directories are scaffolded, template rendering, roster persistence.
+
+**Sealing + consensus (the maintainer's design):**
+- Team lead (interactive Claude) runs multiple rounds from the one `/paircode` invocation.
+- When the team lead has heard enough, it tells each peer to write their `{peer}-FINAL.md`.
+- Team lead then writes its own `alpha-FINAL.md`.
+- Team lead reads all FINALs and writes a **new artifact: `consensus.md`** — the very last thing before closing out the focus.
+- **Current prompts in drive.py do NOT describe any of this.** The maintainer had believed sealing logic was already in the prompts; verification showed it is not. This is a real prompt authoring task, not a memory of existing work.
+
+**Capability syntax rejected:**
+- Brief proposed `--peer gemini:opine` / `--peer codex:work` for inline capability override.
+- Maintainer explicitly dislikes this. Capability stays in `.paircode/peers.yaml` only; edit the file if you want to change it. No per-invocation override flag.
+
+## Open tensions we are grappling with
+
+1. **Headless execution.** Arch A can run for an hour unattended after the user closes Claude. Arch B dies with the session. mlmodel worked fine without headless, but this is a genuine capability loss. Does it matter for the paircode use cases? Unresolved. Preservation branch exists partly because of this.
+2. **Claude-reviewing-Claude support.** mlmodel used Agent tool subagents for claude-on-claude peer review. paircode's current thesis is cross-vendor adversarial (different engines surface different blind spots). Do we keep Claude-on-Claude as an option or cut it for simplicity? Leaning toward cut, not decided.
+3. **Consensus.md prompt authoring.** The final-round team-lead prompt needs to instruct: seal each peer, write your own FINAL, read all FINALs, write `consensus.md`, report. Not drafted yet.
+4. **Codex + Gemini as team lead.** Slash commands are installed via satellites for all three CLIs. If `/paircode` is invoked inside Codex or Gemini (not Claude), can those hosts run the Arch B orchestration? Codex has subagent primitives; Gemini's are different. Cross-host parity for Arch B is an open question. Without parity, paircode is effectively Claude-first with Codex/Gemini as peers only.
+5. **`cliworker` dependency.** If the slash command does all subprocess work via its host CLI's Bash tool, `cliworker.run()` leaves the runtime path. cliworker still matters for `paircode install` (marketplace add, extensions install via `invoke()`). The LLM-call speed-flag logic currently in cliworker.run becomes dead code from paircode's perspective.
+6. **Testability.** Today's drive.py has unit tests (`tests/test_drive.py`). Arch B moves orchestration into slash command markdown, which is untestable by pytest. Smoke tests would have to shell out through a real LLM CLI — slow, flaky, costly. Mitigation: keep the procedural Python helpers (`init_paircode`, `open_focus`, template render, seal_stage) testable in isolation, and accept that the orchestration loop itself becomes an integration-test concern.
+
+## Why we're preserving now
+
+Arch B is a bet. It matches the maintainer's philosophy, it matches the pattern that worked in mlmodel, it dissolves Gap 1–4 cleanly. But it trades away:
+
+- Headless execution
+- A testable orchestration loop
+- Cross-host parity guarantees (Codex/Gemini may not support the team-lead pattern as cleanly)
+
+If any of those turn out to matter more than they look like they do today, we come back to this branch. The Python-driven orchestrator at v0.10.1 is a working, shipped system with 52 green tests. Killing it without preservation would be a mistake.
+
+## Preservation details
+
+- Branch `path-python-controls-stages` cut from `main` immediately after this diary commits.
+- `main` continues toward the Arch B rewrite.
+- The `drive` command, `run_stage`, `run_stage_cold`, `run_review_round`, `run_alpha_revision`, and the ThreadPoolExecutor orchestration in `drive.py` are expected to be deleted from `main` during the rewrite. They remain intact on the preservation branch.
+- `state.py` (procedural scaffolding) stays on `main` unchanged — Arch B still uses it.
+- `runner.py` / `cliworker` integration: fate undecided. See tension #5.
+
+## Key files as of this diary
+
+| Concern | File | Fate in Arch B |
+|---|---|---|
+| `/paircode` slash command (Claude) | `src/paircode/templates/claude_slash_command.md` | **Rewritten** — becomes the orchestrator |
+| `/paircode` slash command (Codex) | `src/paircode/templates/codex_slash_command.md` | Rewritten; parity with Claude version tbd |
+| `/paircode` slash command (Gemini) | `src/paircode/templates/gemini_slash_command.toml` | Rewritten; parity tbd |
+| Python CLI | `src/paircode/cli.py` | Reduced to `paircode "<prompt>"`, `install`, `uninstall`, bare-state |
+| Drive loop | `src/paircode/drive.py` | **Deleted** on main, preserved on branch |
+| State scaffolding | `src/paircode/state.py` | Kept |
+| Runner | `src/paircode/runner.py` | Undecided |
+| Seal | `src/paircode/seal.py` | Kept as a helper the slash command can call silently |
+
+*End of diary 003. Next session: draft the rewritten slash command template + the trimmed Python CLI.*

{paircode-0.10.1 → paircode-0.11.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paircode"
-version = "0.10.1"
+version = "0.11.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.10.1 → paircode-0.11.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.10.0"
+__version__ = "0.11.0"

paircode-0.11.1/src/paircode/cli.py

@@ -0,0 +1,354 @@
+"""paircode CLI — thin helpers the team-lead slash command calls.
+
+Arch B (v0.11+): orchestration lives in the slash command installed inside
+each LLM CLI. This binary exposes only the mechanical helpers the team lead
+needs: scaffold, focus creation, roster listing, peer invocation, plus the
+one-time `install` / `uninstall` lifecycle.
+
+Subcommands:
+  install          — register /paircode in every detected LLM CLI
+  uninstall        — remove /paircode from LLM CLIs (idempotent)
+  ensure-scaffold  — idempotent init + handshake, silent on success
+  focus new <slug> — create a new focus dir, print its path
+  focus active     — print the active focus path
+  roster           — print peer ids, one per line
+  invoke <id> <p>  — run one peer CLI, write output file-trace to --out
+  (bare)           — print current state (what `status` used to do)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from paircode import __version__
+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_peer_dirs,
+    find_paircode,
+    init_paircode,
+    open_focus,
+    read_peers,
+    write_peers,
+)
+
+
+console = Console()
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(__version__, prog_name="paircode")
+@click.pass_context
+def main(ctx: click.Context) -> None:
+    """paircode — adversarial multi-LLM peer review.
+
+    Orchestration runs inside the /paircode slash command of whichever LLM CLI
+    you invoked it from. This binary is the helper layer the team lead calls.
+
+    First-time setup: `paircode install` registers /paircode in Claude, Codex, Gemini.
+    """
+    if ctx.invoked_subcommand is None:
+        _show_state()
+
+
+# ---------------------------------------------------------------------------
+# Install / uninstall
+# ---------------------------------------------------------------------------
+
+@main.command()
+def install() -> None:
+    """Install /paircode slash command into every detected LLM CLI."""
+    console.print("[bold]Installing paircode into detected LLM CLIs...[/bold]\n")
+    results = install_all()
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("CLI")
+    table.add_column("Action")
+    table.add_column("Details")
+    for r in results:
+        color = {"installed": "green", "skipped": "yellow",
+                 "failed": "red", "already": "cyan"}.get(r.action, "white")
+        table.add_row(r.cli_name, f"[{color}]{r.action}[/{color}]", r.message)
+    console.print(table)
+    installed = sum(1 for r in results if r.action == "installed")
+    skipped = sum(1 for r in results if r.action == "skipped")
+    failed = sum(1 for r in results if r.action == "failed")
+    already = sum(1 for r in results if r.action == "already")
+    console.print(
+        f"\n[bold]Summary:[/bold] {installed} installed, {already} already, "
+        f"{skipped} skipped, {failed} failed."
+    )
+
+
+@main.command()
+def uninstall() -> None:
+    """Remove /paircode from every LLM CLI config dir (idempotent)."""
+    console.print("[bold]Uninstalling paircode from LLM CLIs...[/bold]\n")
+    results = uninstall_all()
+    for r in results:
+        console.print(f"  [dim]{r.cli_name}:[/dim] {r.message}")
+
+
+# ---------------------------------------------------------------------------
+# Scaffold — idempotent init + handshake
+# ---------------------------------------------------------------------------
+
+@main.command(name="ensure-scaffold")
+def ensure_scaffold() -> None:
+    """Idempotent: init .paircode/ if missing, run handshake if peers empty.
+
+    Silent on success. Prints one line per action taken (init, handshake).
+    The team-lead slash command calls this before every focus.
+    """
+    state = find_paircode()
+    did_init = False
+    if state is None:
+        state = init_paircode()
+        did_init = True
+
+    peers = read_peers(state)
+    proposed_count = 0
+    if not peers:
+        proposed = propose_roster()
+        if proposed:
+            write_peers(state, proposed_as_yaml_dicts(proposed))
+            ensure_peer_dirs(state, proposed)
+            proposed_count = len(proposed)
+
+    if did_init:
+        click.echo(f"init {state.root}")
+    if proposed_count:
+        click.echo(f"handshake wrote {proposed_count} peers to {state.peers_path}")
+
+
+# ---------------------------------------------------------------------------
+# Focus — new / active
+# ---------------------------------------------------------------------------
+
+@main.group()
+def focus() -> None:
+    """Focus commands (new, active)."""
+
+
+@focus.command("new")
+@click.argument("slug")
+@click.option("--prompt", default=None, help="One-line focus prompt to embed in FOCUS.md")
+def focus_new(slug: str, prompt: str | None) -> None:
+    """Create a new focus dir, print its path to stdout."""
+    state = find_paircode()
+    if state is None:
+        state = init_paircode()
+    try:
+        focus_dir = open_focus(state, slug, prompt=prompt)
+    except FileExistsError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(str(focus_dir))
+
+
+@focus.command("active")
+def focus_active() -> None:
+    """Print the most recent focus path, or exit 1 if none exists."""
+    state = find_paircode()
+    if state is None or state.active_focus is None:
+        raise click.ClickException(
+            "No focus found. Run `paircode focus new <slug>` first."
+        )
+    click.echo(str(state.active_focus))
+
+
+# ---------------------------------------------------------------------------
+# Roster — print peer ids
+# ---------------------------------------------------------------------------
+
+@main.command()
+@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 roster(alpha_cli: str | None, peer_filter: str | None, peers_filter: str | None) -> None:
+    """Print peer ids, one per line — best-effort, never errors.
+
+    Resolution order:
+      1. Apply --peer/--peers filter to the peers.yaml roster.
+      2. If --alpha is given, drop peers whose cli matches (except as last resort).
+      3. If the result is empty, fall back to "all peers except alpha".
+      4. If still empty, re-run handshake detection in case new CLIs landed.
+      5. If still empty and an alpha-cli peer exists, emit that as last resort.
+      6. If still empty, emit nothing — team lead must handle.
+    """
+    state = find_paircode()
+    if state is None:
+        return
+
+    all_peers = [p for p in read_peers(state) if p.get("id")]
+
+    # Step 1 — apply filter
+    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)
+
+    # Step 2 — alpha exclusion
+    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)
+
+    # Step 3 — fallback to "all peers except alpha" if filter missed
+    if not result and (peer_filter or peers_filter):
+        result = _exclude_alpha(all_peers)
+
+    # Step 4 — refresh detection (maybe user installed something since last handshake)
+    if not result:
+        proposed = propose_roster()
+        if proposed:
+            fresh_dicts = proposed_as_yaml_dicts(proposed)
+            known_ids = {p.get("id") for p in all_peers}
+            added = [p for p in fresh_dicts if p.get("id") not in known_ids]
+            if added:
+                write_peers(state, all_peers + added)
+                ensure_peer_dirs(state, proposed)
+                all_peers = all_peers + added
+                result = _exclude_alpha(all_peers)
+
+    # Step 5 — last resort: include alpha-cli peer if that's all we have
+    if not result:
+        result = list(all_peers)
+
+    for p in result:
+        pid = p.get("id")
+        if pid:
+            click.echo(pid)
+
+
+# ---------------------------------------------------------------------------
+# Invoke — fire one peer
+# ---------------------------------------------------------------------------
+
+@main.command()
+@click.argument("stage")
+def converge(stage: str) -> None:
+    """Converge a stage — copy each participant's latest `vN.md` to `{id}-FINAL.md`.
+
+    Runs on the active focus. Mechanical file-copy only; the slash command
+    writes `consensus.md` afterward from the FINAL files.
+    """
+    from paircode.seal import seal_stage
+
+    state = find_paircode()
+    if state is None or state.active_focus is None:
+        raise click.ClickException(
+            "No active focus. Run `paircode focus new <slug>` first."
+        )
+    stage_dir = state.active_focus / stage
+    if not stage_dir.exists():
+        raise click.ClickException(f"Stage dir not found: {stage_dir}")
+    sealed = seal_stage(stage_dir)
+    if not sealed:
+        raise click.ClickException(
+            f"No versioned files found in {stage_dir} — nothing to converge."
+        )
+    for s in sealed:
+        click.echo(f"{s.peer_id} → {s.final.name}")
+
+
+@main.command()
+@click.argument("peer_id")
+@click.argument("prompt")
+@click.option("--out", "out_path", required=True, type=click.Path(),
+              help="Where to write the peer's file-trace markdown")
+@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 (faster, fewer tools)")
+def invoke(peer_id: str, prompt: str, out_path: str, timeout: int, fast: bool) -> None:
+    """Run one peer LLM against PROMPT; write file-trace markdown to --out.
+
+    PEER_ID must match an `id` in .paircode/peers.yaml.
+    Exits 0 on peer success, non-zero on failure. Always writes a file-trace
+    (even on failure) so every invocation leaves evidence on disk.
+    """
+    state = find_paircode()
+    if state is None:
+        raise click.ClickException(
+            "No .paircode/ found. Run `paircode ensure-scaffold` 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}"
+        )
+
+    result = run_peer(
+        peer_id=peer_id,
+        cli=str(peer.get("cli")),
+        prompt=prompt,
+        output_path=Path(out_path),
+        model=peer.get("model"),
+        timeout_s=timeout,
+        fast=fast,
+    )
+    status = "ok" if result.ok else "FAIL"
+    click.echo(f"{peer_id} {status} {result.duration_s:.1f}s", err=True)
+    if not result.ok:
+        raise SystemExit(1)
+
+
+# ---------------------------------------------------------------------------
+# Bare paircode — show state
+# ---------------------------------------------------------------------------
+
+def _show_state() -> None:
+    """Bare `paircode` prints current .paircode/ state. Former `status` output."""
+    state = find_paircode()
+    console.print(f"[bold]paircode[/bold] v{__version__}")
+    if state is None:
+        console.print(
+            "\n[yellow]No .paircode/ found in cwd or any parent.[/yellow]\n"
+            "Run [cyan]paircode install[/cyan] to register /paircode in your LLM CLIs,\n"
+            "then run [cyan]/paircode \"your prompt\"[/cyan] inside Claude / Codex / Gemini\n"
+            "to kick off a peer-review cycle."
+        )
+        return
+    console.print(f"\n[bold].paircode/[/bold] at [cyan]{state.root}[/cyan]")
+    console.print(f"  project root: {state.project_root}")
+    console.print(f"  focuses:      {state.focus_count}")
+    if state.active_focus:
+        console.print(f"  active focus: [green]{state.active_focus.name}[/green]")
+    peers = read_peers(state)
+    console.print(f"  peers:        {len(peers)} configured")
+    if peers:
+        ptable = Table(show_header=True, header_style="bold")
+        ptable.add_column("id")
+        ptable.add_column("cli")
+        ptable.add_column("priority")
+        for p in peers:
+            ptable.add_row(
+                str(p.get("id", "?")),
+                str(p.get("cli", "?")),
+                str(p.get("priority", "?")),
+            )
+        console.print(ptable)
+    if state.focus_dirs:
+        ftable = Table(show_header=True, header_style="bold")
+        ftable.add_column("#")
+        ftable.add_column("focus")
+        for i, d in enumerate(state.focus_dirs, 1):
+            ftable.add_row(str(i), d.name)
+        console.print(ftable)
+
+
+if __name__ == "__main__":
+    main()