cli-bridge-mcp 0.1.0__tar.gz

cli_bridge_mcp-0.1.0/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+## Our pledge
+
+We — contributors and maintainers — pledge to make participation in this project a harassment-free
+experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and
+expression, level of experience, nationality, personal appearance, race, religion, or sexual
+identity and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful of differing viewpoints and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Focusing on what is best for the community and the project.
+
+Unacceptable behavior includes harassment, insulting or derogatory comments, personal or political
+attacks, publishing others' private information, and other conduct that would reasonably be
+considered inappropriate.
+
+## Enforcement
+
+Instances of abusive or otherwise unacceptable behavior may be reported to the maintainer via a
+GitHub private security advisory or the contact on the maintainer's profile. All complaints will be
+reviewed and investigated and will result in a response appropriate to the circumstances.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

cli_bridge_mcp-0.1.0/.github/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to cli-bridge
+
+Thanks for helping out. cli-bridge aims to stay small, dependency-light, and predictable, so a
+few rules keep it that way.
+
+## Setup
+
+```bash
+uv venv && uv pip install -e . pytest pytest-asyncio ruff
+CLI_BRIDGE_STATE_DB=/tmp/t.sqlite pytest -q   # keep tests off your real state db
+ruff check src/ tests/
+```
+
+No real AI CLI or network is needed to develop or test — lanes are faked with `echo`/`false`
+and the state DB is a temp sqlite.
+
+## Ground rules
+
+- **Stdlib + `mcp` only.** No new runtime dependencies. (Dev tools like `pytest`/`ruff` are fine.)
+- **Keep `server.py` thin.** Business logic lives in `lanes`/`runner`/`router`/`workflows`/
+  `findings`/`telemetry`. The server routes; it doesn't decide.
+- **Every change ships a test**, and `pytest -q` + `ruff check` must stay green. Tests must not
+  require a real CLI or network.
+- **Portable**: macOS / Linux / Windows. No POSIX-only calls without a Windows branch
+  (see `runner._kill_tree`).
+- **Telemetry is best-effort** — it must NEVER raise into a delegation path.
+- **Cost safety**: a missing/empty model must never resolve to a paid model.
+- **Surgical diffs.** Match the existing style; don't reformat unrelated code.
+
+## Adding a lane (a new CLI)
+
+You usually don't need to fork: point `CLI_BRIDGE_LANES_FILE` at a JSON file
+(see `examples/lanes.example.json`), or wrap an HTTP API with `curl`
+(`examples/byo-api-lane.json`). To add a built-in lane, append a `LaneSpec` in `lanes.py` with
+its argv builder and capabilities, and ship a test. See `docs/ARCHITECTURE.md` → "Extending it".
+
+## Adding a workflow
+
+Add a function in `workflows.py` taking `(targets, args, run_lane)`, then register a tool +
+dispatch in `server.py` (and a prompt in `_PROMPTS` if it deserves a slash command). Reuse the
+injected `run_lane` so it's testable with fakes.
+
+## Commit / PR
+
+- Conventional-commit-ish subjects (`feat(...)`, `fix(...)`, `docs(...)`) are appreciated.
+- Describe the *why*, not just the *what*. Note any new env var or tool.
+- Update `CHANGELOG.md` under "Unreleased".
+
+By contributing you agree your work is licensed under the project's MIT license.

cli_bridge_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Something in cli-bridge behaves incorrectly
+title: "[bug] "
+labels: bug
+---
+
+**What happened**
+A clear description of the bug.
+
+**Steps to reproduce**
+1. Host (Claude Code / Codex / opencode / …) and version:
+2. Tool called and arguments:
+3. What you expected vs. what happened:
+
+**`doctor` output**
+Paste the output of the `doctor` tool (or `cli-bridge doctor`).
+
+**Environment**
+- cli-bridge version / commit:
+- OS:
+- Python:
+- Relevant `CLI_BRIDGE_*` env vars (redact secrets):
+
+**Logs**
+If you can, set `CLI_BRIDGE_LOG=<path>` and attach the relevant lines (redact secrets).

cli_bridge_mcp-0.1.0/.github/ISSUE_TEMPLATE/cli_flag_broken.md

@@ -0,0 +1,26 @@
+---
+name: CLI flag broken / drifted
+about: A delegate CLI changed its flags and a lane no longer works
+title: "[drift] "
+labels: drift
+---
+
+**Which lane / CLI?**
+e.g. `gemini` (agy), `gpt` (codex), `opencode` …
+
+**What broke**
+The error or wrong behavior you see (paste the `[kind] message`, e.g. `[failed] … exit 2`).
+
+**The CLI's current invocation**
+What the CLI now expects (paste the relevant `--help` excerpt):
+
+```
+<paste mycli --help here>
+```
+
+**Version**
+- CLI version:
+- cli-bridge version / commit:
+
+> The nightly `drift-check` workflow opens these automatically when the test suite breaks; feel
+> free to file one manually if you hit it first.

cli_bridge_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/JoaoBerne/cli-bridge-mcp/security/advisories/new
+    about: Please report vulnerabilities privately via a GitHub security advisory, not a public issue. See .github/SECURITY.md.

cli_bridge_mcp-0.1.0/.github/ISSUE_TEMPLATE/lane_request.md

@@ -0,0 +1,30 @@
+---
+name: Lane request
+about: Ask for a new built-in CLI lane
+title: "[lane] "
+labels: lane-request
+---
+
+**Which CLI?**
+Name + link to the official CLI.
+
+**Install + auth**
+How is it installed, and how does a user log in (subscription / free tier / API key)?
+
+**Invocation**
+The exact non-interactive command to send one prompt and get an answer, e.g.:
+
+```
+mycli --print "the prompt"
+```
+
+- Model selection flag (if any):
+- Reasoning/effort flag (if any):
+- Write/build mode flag (if any):
+- How to list models (if any):
+
+**Cost**
+Is it free, quota-limited, or paid/credits for a typical user?
+
+> Tip: you may not need a built-in lane — you can add any CLI yourself via
+> `CLI_BRIDGE_LANES_FILE` (see `examples/lanes.example.json`).

cli_bridge_mcp-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+<!-- Thanks for contributing! Keep diffs surgical and tests green. -->
+
+## What & why
+<!-- What does this change, and why? Link any issue. -->
+
+## Checklist
+- [ ] `pytest -q` is green (tests don't need a real CLI or network)
+- [ ] `ruff check src/ tests/` is clean
+- [ ] No new runtime dependency (stdlib + `mcp` only)
+- [ ] `server.py` stays thin (logic lives in lanes/runner/router/workflows/findings/telemetry)
+- [ ] Telemetry stays best-effort (never raises into a delegation)
+- [ ] Cost safety preserved (empty model never resolves to paid)
+- [ ] `CHANGELOG.md` updated under "Unreleased" (if user-facing)
+- [ ] New env var / tool documented (README / ARCHITECTURE)
+
+## Notes
+<!-- Anything reviewers should know: new env vars, behavior changes, follow-ups. -->

cli_bridge_mcp-0.1.0/.github/SECURITY.md

@@ -0,0 +1,73 @@
+# Security
+
+cli-bridge spawns official AI CLIs as subprocesses and returns their output to your host
+assistant. That puts it between two trust boundaries, so it's worth being precise about what it
+defends against and what it does not.
+
+## Reporting a vulnerability
+
+Please **do not** open a public issue for a security problem. Instead, open a
+[GitHub security advisory](https://github.com/JoaoBerne/cli-bridge-mcp/security/advisories/new)
+(or email the maintainer listed on the GitHub profile). Include repro steps and the affected
+version/commit. You'll get an acknowledgement within a few days.
+
+## Threat model
+
+cli-bridge handles two kinds of untrusted data:
+
+1. **Delegate output** — text produced by another model/CLI, returned to your host assistant.
+   It can contain prompt-injection ("ignore previous instructions"), requests to exfiltrate
+   secrets, hidden instructions in HTML comments, or shell commands disguised as guidance.
+2. **The task/diff you pass in** — may itself contain secrets or hostile content.
+
+### What cli-bridge does about it
+
+- **Ban-safe by construction.** It only ever spawns the official CLI you already run. It never
+  extracts tokens, reads credential files, or sends your API keys anywhere. (Test: `test_isolation.py`.)
+- **No pollution of your CLI config.** The only things it writes are an overflow temp file, the
+  local telemetry sqlite, and an optional log. Never to `~/.gemini`, `~/.codex`, etc.
+- **Secret redaction.** Known secret shapes (bearer tokens, `sk-…`, `ghp_…`, `AIza…`,
+  `api_key=…`) are redacted from output **before** anything is returned or logged
+  (`runner.redact`). The review prechecks redact a secret's value even while flagging it.
+- **Output guard.** `CLI_BRIDGE_GUARD=off|warn|strict` (default `warn`) scans delegate output for
+  injection / tool-poisoning signals and, in `warn`, prepends a banner telling the host to treat
+  the text as **data, not instructions**; in `strict`, it withholds the body. Runs after redaction.
+- **Read-only by default.** A delegate can only edit files with an explicit `agent: build`. The
+  recommended way to use write mode is **`ask_build_isolated`**, which runs the agent in a
+  throwaway git worktree and returns a diff — your real repository is never modified.
+- **Cost safety.** A missing/empty model never resolves to a paid model; `ask_all`/`ask_cascade`
+  exclude limited/paid lanes by default.
+- **Telemetry is local and minimal.** A task **hash + short preview** only (never the full
+  prompt/output unless you set `CLI_BRIDGE_STORE_TRANSCRIPTS=true`), in a local sqlite DB that
+  never leaves your machine. Disable with `CLI_BRIDGE_TELEMETRY=off`.
+
+### What it does NOT protect against
+
+- **It is not a sandbox.** A delegate CLI runs with your user's permissions. In `agent: build`
+  (outside `ask_build_isolated`) it can modify files; only run write mode on code you trust.
+- **The guard is heuristic.** It catches high-signal patterns, not every possible injection. In
+  `warn` mode the text still reaches the host — treat delegated output as untrusted input.
+- **It can't vet the models themselves.** A compromised or malicious model could emit harmful
+  content; that's why output is annotated and, for writes, isolated.
+- **`cwd`/path arguments are not jailed.** A delegate sees whatever directory you point it at.
+- **Delegates inherit your full environment.** Each spawned CLI gets the host process's complete
+  `os.environ` — deliberately, because official CLIs need their own `PATH`, auth caches and
+  config to work. The flip side: every secret in that environment (cloud creds, unrelated API
+  keys) is readable by any delegate process, exactly as if you ran that CLI by hand. cli-bridge
+  redacts known secret shapes from *output*, but it cannot stop a malicious CLI from reading the
+  env it was born with. If that matters, launch your MCP host from a scoped environment (e.g.
+  `env -i PATH=… HOME=…` or a shell profile without the sensitive exports).
+- **BYO-API (curl) lanes: keep the key OUT of argv.** A lane that substitutes a `${ENV}` key into
+  a `curl` command line puts that key in this machine's process list for the duration of the call
+  (it is never logged — traces redact it, and it never leaves your machine otherwise). The shipped
+  examples use the secret-safe pattern instead — `--variable %MY_KEY` + `--expand-header
+  "Authorization: Bearer {{MY_KEY}}"` (curl ≥ 8.3) imports the key *inside* curl, so `ps` only
+  ever shows the variable's name. `doctor` warns about any custom lane that still expands a
+  secret into a credential-bearing argv part.
+
+## Hardening checklist for sensitive use
+
+- Set `CLI_BRIDGE_GUARD=strict`.
+- Use `ask_build_isolated` instead of raw `agent: build`.
+- Keep `CLI_BRIDGE_STORE_TRANSCRIPTS` unset.
+- Run from a directory that contains only what the delegate should see.

cli_bridge_mcp-0.1.0/.github/workflows/drift-check.yml

@@ -0,0 +1,47 @@
+# Nightly "does it still import / do the lane builders still hold" check.
+# CLIs change their flags without warning; this catches obvious breakage early and opens
+# an issue so the lane builders can be updated before users hit it.
+name: drift-check
+
+on:
+  schedule:
+    - cron: "0 6 * * *"   # daily 06:00 UTC
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install --upgrade pip
+          pip install -e . pytest pytest-asyncio
+      - name: Import + unit tests
+        id: check
+        run: pytest -q
+      - name: Open an issue on failure
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = "drift-check failed — a CLI lane may be broken";
+            const body = "The nightly drift-check run failed. A delegate CLI may have changed its " +
+              "flags, or a dependency broke. See the failing run: " +
+              `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            const existing = await github.rest.issues.listForRepo({
+              owner: context.repo.owner, repo: context.repo.repo,
+              state: "open", labels: "drift",
+            });
+            if (existing.data.length === 0) {
+              await github.rest.issues.create({
+                owner: context.repo.owner, repo: context.repo.repo,
+                title, body, labels: ["drift"],
+              });
+            }

cli_bridge_mcp-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,35 @@
+# GitHub Pages — landing page (site/index.html + assets/).
+# Manual trigger only: Pages on the free plan needs the repo public, so this is armed for
+# launch day (run it once from the Actions tab after going public + enabling Pages → Actions).
+name: pages
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Assemble site
+        run: |
+          mkdir -p _site
+          cp site/index.html _site/
+          cp -r assets _site/assets
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+      - id: deployment
+        uses: actions/deploy-pages@v4

cli_bridge_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+# Publish to PyPI on a version tag, via Trusted Publishing (OIDC — no API token stored).
+# One-time setup on PyPI: add a "pending publisher" for project `cli-bridge-mcp`, repo
+# JoaoBerne/cli-bridge-mcp, workflow `release.yml`, environment `pypi`. Then `git tag v0.1.0 &&
+# git push --tags` builds + publishes automatically.
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Smoke-check the wheel imports + entry points
+        run: |
+          python -m pip install dist/*.whl
+          python -c "import cli_bridge, cli_bridge.cli, cli_bridge.server; print('import ok')"
+          cli-bridge --help >/dev/null && echo "cli-bridge entry ok"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

cli_bridge_mcp-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,92 @@
+name: tests
+
+on:
+  # PR-only: a rebase-merge lands the exact commits the PR already tested, so a separate
+  # push-on-main run would re-test identical commits — pure duplication. Dropped to halve CI cost.
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:   # manual full-matrix run on main when you want one (e.g. before a release)
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: python -m pip install --upgrade pip ruff
+      - name: Lint
+        run: ruff check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install
+        # mypy pinned so the gate can't pass on one version and break on another; install the
+        # package so mypy resolves mcp's own types.
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e . mypy==2.1.0
+      - name: Type check
+        run: mypy src/cli_bridge
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          # prove portability (a stated invariant). macOS minutes bill at 10× on GitHub-hosted
+          # runners, so we keep a single macOS job (newest Python) and cover both ends of the
+          # version range on Windows (2×) instead. Full cross-product on demand via workflow_dispatch.
+          - os: macos-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.10"
+          - os: windows-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e . pytest pytest-asyncio
+      - name: Run tests
+        run: pytest -q
+
+  security:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read       # gitleaks-action lists the PR's commits via the API in PR mode
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0          # gitleaks scans full history; dep-review diffs the PR base/head
+      # Fail a PR that ADDS a dependency carrying a high+ CVE. PR-scoped, native to GitHub, free,
+      # zero runtime cost — right-sized for a stdlib + `mcp` project (no Trivy: it would find ~0
+      # on a one-dependency tree and just burn CI minutes). Hard gate now that the repo is public
+      # (the dependency-graph API is on by default for public repos): a PR adding a high+ CVE dep fails.
+      - name: Dependency review
+        if: github.event_name == 'pull_request'
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high
+      # Secret scan — the real risk here: the whole pitch is "no token leak, no key extraction".
+      # gitleaks-action is free for personal-account repos (no GITLEAKS_LICENSE needed).
+      - name: Secret scan (gitleaks)
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

cli_bridge_mcp-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Secrets / local state (never commit)
+.env
+.env.*
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+
+# Test / tooling
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/
+TESTING.md

cli_bridge_mcp-0.1.0/.gitleaks.toml

@@ -0,0 +1,14 @@
+# gitleaks configuration — extends the default ruleset.
+#
+# The test tree carries INTENTIONAL synthetic secrets (fake `ghp_…`, `sk-…`, Slack-webhook
+# strings) used as fixtures to verify cli-bridge's OWN secret redaction + precheck detection.
+# They are not real credentials — policy is that tests never use real keys (see AGENTS.md/CLAUDE.md).
+# Allowlist the test tree so gitleaks doesn't flag its own bait; `src/` stays fully scanned.
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Synthetic secrets in the test suite (redaction/precheck fixtures, not real credentials)"
+paths = [
+  '''^tests/''',
+]

cli_bridge_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,124 @@
+# Agent guide — cli-bridge
+
+Guidance for AI coding agents (Claude Code, Codex, Gemini CLI, opencode…) working on this
+repo. `CLAUDE.md` is a symlink to this file.
+
+## What this is
+
+An MCP server that lets the host AI consult **other** AI CLIs as a council. Each lane spawns
+the official CLI as a subprocess (ban-safe: no token extraction, no API keys). Read-only by
+default. Pure-stdlib + `mcp` only.
+
+## Layout
+
+```
+src/cli_bridge/
+  server.py     # MCP surface: tool list, dispatch, doctor/setup. Keep thin.
+  lanes.py      # LaneSpec registry + argv builders + custom-lane JSON loader
+  runner.py     # subprocess exec, redaction, process-tree kill, error classification
+  config.py     # env parsing, cost profile, timeouts, onboarding text
+  telemetry.py  # sqlite3 run log + lane health/cooldown (best-effort, privacy-first)
+  router.py     # deterministic cascade ordering (pure)
+  council.py    # ask_all/ask_cascade/ask_best/synthesize fan-out (injected run_lane — like workflows)
+  jobs.py       # in-process async jobs (ask_all_async) + sqlite persistence
+  workflows.py  # review_diff/security_review/debate + prechecks + council recap
+  orchestrate.py # batch_run durable fan-out + presets (refine_plan/verify_repair/fanout_compare/…)
+  findings.py   # parse/merge/render structured review findings (pure)
+  guards.py     # injection/tool-poisoning output guard (CLI_BRIDGE_GUARD)
+  worktrees.py  # ask_build (isolated worktree diff | direct zone-guarded write + artifact return)
+  buildloop.py  # steerable multi-turn builds: job_tail/build_steer, executable DoD gate
+  conversations.py # round-table threads: sqlite persistence + recipient-aware replay
+  preamble.py   # terse response-style preamble prepended to delegate prompts
+  eval.py       # quality eval: council vs single + self-consistency, permutation test, scorer
+  cli.py        # human/CI entry point (cli-bridge ...) over the same internals
+  detect.py     # PATH detection
+tests/          # pytest; unit + cross-host integration (no real CLI needed)
+docs/           # COSTS.md, BENCHMARKS.md, ARCHITECTURE.md, i18n/ READMEs
+assets/         # README banner/mark/social SVGs + demo.gif (generated, do not hand-edit)
+site/           # GitHub Pages landing (deployed by .github/workflows/pages.yml)
+examples/       # custom-lane JSON recipes + GitHub Action
+```
+
+## Rules for changes
+
+- **Keep `server.py` thin** — business logic belongs in lanes/runner/router/telemetry.
+- **No new runtime deps** beyond `mcp`. Stdlib only.
+- **Every change ships tests.** `pytest -q` must stay green. Tests must not need a real AI
+  CLI or network (fake lanes via `echo`/`false`, temp sqlite via `CLI_BRIDGE_STATE_DB`).
+- **Portability**: must run on macOS/Linux/Windows. No POSIX-only calls without a Windows
+  branch (see `runner._kill_tree`).
+- **Telemetry is best-effort** — it must NEVER raise into a delegation path.
+- **Cost safety**: a missing/empty model must never resolve to a paid model. `ask_all`/
+  `ask_cascade` exclude limited/paid by default.
+- Match existing style; surgical diffs.
+
+## Commands
+
+```
+uv venv && uv pip install -e . pytest pytest-asyncio ruff
+pytest -q
+CLI_BRIDGE_STATE_DB=/tmp/t.sqlite pytest -q   # keep tests off your real state db
+ruff check src/ tests/                        # lint (CI enforces this)
+CLI_BRIDGE_LIVE_E2E=1 pytest tests/test_live_e2e.py -q   # opt-in live checks
+```
+
+## Roadmap
+
+See `CHANGELOG.md` for the shipped history. Done: config extraction, telemetry+cooldown, cascade router,
+terse preamble (+min-chars skip), response cache, trace fields, workflow tools (review_diff/
+security_review/debate), council recap, MCP prompts, opt-in write/build mode (all lanes),
+sibling-model self-consultation, in-process async jobs (ask_all_async), structured findings
+JSON + deterministic merge + prechecks + residual_risk, output guard (injection/poisoning),
+worktree-isolated write mode (ask_build_isolated), ask_best mode router + estimated token/
+credit accounting (usage_report/usage_budget), human CLI (cli-bridge), MCP resources,
+premortem/test_plan workflows, eval fixtures + no-network evaluator, ruff lint + CI lint job,
+modular tool loading (DISABLED_TOOLS/ENABLED_TOOLS), quality eval (`cli-bridge eval`: council vs
+single-model + self-consistency, deterministic scorer + calibration gate), architect/editor build
+split, debate VOTE footer + convergence early-stop, files_required grounding gate, anti-burst
+spawn pacing (per-lane MIN_INTERVAL_S), trace-footer toggle, i18n READMEs (docs/i18n/), Pages
+landing (site/), opt-in streaming runner (arun on_line/log_path + stall guard), direct builds
+(ask_build mode=isolated|direct — zone contract + per-zone lock + post-turn zone-violation check +
+greenfield init), steerable multi-turn builds (buildloop: job_tail/build_steer/interrupt, executable
+DoD gate, plan-leak warning), durable journaled fan-out (batch_run + resume_id across restart) with
+workflow presets (council_review/map_review/research_verify/refine_plan), guard NFKC/zero-width
+normalization, runtime paid-model warning, **council module extraction** (`council.py`, injected
+run_lane), **mypy gate in CI** (typed `_ann()` helper for the SDK-stub noise), **eval v3** (seeded
+permutation test replacing the 1-sigma heuristic + multi-bug fixtures + in-fixture decoys),
+**build artifact-return** (non-text files surfaced by path — capability-borrowing), **cross-model
+`verify_repair`** + **`fanout_compare`** workflow presets. **Dynamic orchestration engine (Phase 1):**
+typed result envelope + provenance, `findings.extract_json` contract, per-invocation budget caps +
+`dry_run` cost envelope, **cross-vendor `jury`** (author≠reviewer family, k-of-N fail-closed) +
+`lanes.family_of`, **disagreement-as-uncertainty** score on `ask_all`, opt-in **confidence-escalate**
+cascade, **`BRIDGE_DEPTH` re-entry guard**, **`CLI_BRIDGE_LEAN`** core surface, `role=` personas,
+Gemini `images=` vision (experimental). **Local + council quality + quota resilience:** **Ollama lane**
+(`ask_ollama`/`list_ollama_models` — local, $0, offline, read-only) + local-model custom-lane recipes
+(`examples/`), **peer-anonymized debate/council** (neutral Reviewer/Debater labels so no model favours
+a known rival), **`seat_report`** earn-their-seat (`jury_outcomes` telemetry benches dead-weight lanes
+on evidence), **discrete calibration binning** (eval bins on emitted confidences, N≥50 gate),
+**quota-empty cooldown with capped exponential backoff** (never infinite, success-resets).
+
+### Considered & deferred (rationale — not just "not yet")
+- **forced-pacing engine** — contradicts the model (cli-bridge delegates investigation to the
+  council; it doesn't force the host to slow down), big effort, low value, and only helps if the
+  host respects the gate. Dropped.
+- **warm pool** — no lane offers a daemon/server mode (the lanes are spawn-per-call), so there's
+  nothing to keep warm. Infeasible cleanly.
+- **chars/token calibration per lane** — would need real provider token counts = ban-risk fishing,
+  against the no-extraction ethos. The chars/4 figure stays honestly labeled "estimated".
+- **native build resume (`--session-id`)** — no lane exposes a reliable session id; filesystem
+  continuity (the delegate re-reads its own files each turn) already covers it. Revisit if a CLI
+  ships a stable resume handle.
+- **Big orchestration architecture** (recursive spawn trees, shared state bus, inter-agent mailbox,
+  capability passthrough hub, a wire-protocol "bus between AIs") — real directions, but vaporware-
+  prone and vendor-hostile (we build on CLIs we don't control). Roadmap only; positioned honestly
+  as a direction, never sold as a shipped protocol. See `docs/ARCHITECTURE.md` for the framing.
+
+### Next candidates (small — after real-usage soak of the engine; council-trimmed)
+- **early-stop `ask_all`** (`agree_stop`) — stop spawning once K lanes agree (reuses the agreement
+  score). Deferred: needs ask_all restructured from gather-all to incremental + cancellation, and
+  the agreement heuristic validated on real outputs first.
+- **architect/editor split** for `ask_build` (plan on a strong lane, edit on a cheap diff-precise one).
+- GATED (build on real demand, not speculatively): **planner → plan_build**, **precommit** (≈
+  `review_diff role=strict`), **MoA** preset. CUT: **debug**, **conversation_resume**, generic
+  chaining **DSL** / **recursive spawn** (the host already orchestrates; see deferred above).
+- Release track: opt-in real-CLI contract job in CI, history secrets scan, PyPI publish (GO-gated).