paircode 0.13.1__tar.gz → 0.13.2__tar.gz

{paircode-0.13.1 → 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.13.1 → paircode-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paircode
-Version: 0.13.1
+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.13.1 → paircode-0.13.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paircode"
-version = "0.13.1"
+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.13.1 → 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.13.0"
+__version__ = "0.13.1"

{paircode-0.13.1 → 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

{paircode-0.13.1 → 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.13.1 → 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"),

{paircode-0.13.1 → paircode-0.13.2}/src/paircode/templates/peers.yaml

@@ -10,7 +10,11 @@
 # Fields:
 #   id              — peer-a, peer-b, peer-c, ... (unique, immutable)
 #   cli             — the command-line binary used to invoke this peer (claude/codex/gemini/ollama/aider/...)
-#   model           — specific model string (optional; CLI default if omitted)
+#   model           — specific model string. Optional but RECOMMENDED. If omitted,
+#                     the CLI picks its own default — which on a free/misconfigured
+#                     login can silently be a weak flash-tier model that just agrees
+#                     with you. Pin a Pro tier for real fork weight (e.g. gemini: a
+#                     *-pro* model; claude: sonnet/opus). Empty = CLI default.
 #   priority        — high | medium | low (used when budget is tight)
 #   daily_budget    — advisory only for now; paircode logs when a peer sits out
 #

paircode-0.13.2/tests/test_handshake.py

@@ -0,0 +1,28 @@
+"""Handshake roster shape — guards the silent free-tier downgrade fix.
+
+Diary 004: an unpinned gemini peer on a free/oauth login silently ran a weak
+flash model and rubber-stamped a consensus. The fix makes the `model` field
+present in every generated roster so pinning is discoverable, and keeps an
+empty pin safely falsy downstream (cli.py treats "" as "CLI default").
+"""
+from __future__ import annotations
+
+from paircode.handshake import ProposedPeer, proposed_as_yaml_dicts
+
+
+def test_generated_roster_exposes_model_key_for_pinning():
+    """Every proposed peer must surface a `model` key, even when unpinned,
+    so users see the lever instead of falling into the silent-flash trap."""
+    peers = [ProposedPeer(id="peer-a-gemini", cli="gemini", priority="low", notes="x")]
+    dicts = proposed_as_yaml_dicts(peers)
+    assert "model" in dicts[0]
+    assert dicts[0]["model"] == ""  # empty = CLI default; falsy, so no -m flag is passed
+
+
+def test_model_pin_round_trips_into_roster_dict():
+    """A pinned model survives into the yaml dict that gets written to peers.yaml."""
+    p = ProposedPeer(
+        id="peer-a-gemini", cli="gemini", priority="high",
+        notes="", model="gemini-3.1-pro-preview",
+    )
+    assert proposed_as_yaml_dicts([p])[0]["model"] == "gemini-3.1-pro-preview"