band-ai · yoni-bagelman-thenvoi · May 31, 2026 · May 31, 2026 · May 31, 2026 · May 31, 2026
diff --git a/.gitignore b/.gitignore
@@ -217,3 +217,7 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# Codeband — agent credentials (contains API keys)
+agent_config.yaml
+AGENTS.md
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -28,13 +28,13 @@ All LLM calls — including the `cb prs --smart` / `cb issues --smart` CLI helpe
 ### Auth policy (asymmetric by design)
 
 - **Claude is subscription-first.** `cli.py:_resolve_claude_auth` strips `ANTHROPIC_API_KEY` at startup whenever any OAuth source exists: `CLAUDE_CODE_OAUTH_TOKEN`, macOS Keychain (`security -s "Claude Code-credentials"`), or `$CLAUDE_CONFIG_DIR/.credentials.json` (default `~/.claude/.credentials.json`). This is because the Claude CLI's own precedence puts API key *above* OAuth — without intervention, a user with `claude` logged in locally would silently pay per token.
-- **Codex is API-key-first.** When both `OPENAI_API_KEY` and a `~/.codex/auth.json` ChatGPT session exist, the API key wins (per OpenAI's own automation guidance and `docker/entrypoint.sh`). Parallel Codex workers exhaust subscription quotas quickly.
+- **Codex is subscription-first** (mirrors Claude). `cli.py:_resolve_codex_auth` strips `OPENAI_API_KEY` at startup when `~/.codex/auth.json` carries a valid ChatGPT subscription credential — the API key is stashed as `CODEBAND_FALLBACK_OPENAI_API_KEY` so preflight can restore it only if the subscription path reports usage-limit exhaustion. Parallel Codex workers exhaust subscription quotas quickly, so the intent is the same as Claude: avoid silently burning API credits while a subscription is active.
 - **Preflight in `cb run`** (`preflight.py`) makes one tiny call through each CLI before spawning agents. It pattern-matches known error text ("Credit balance is too low", "usage limit reached", "rate_limit_error", "please log in", etc.) and fails fast with a remediation hint. Without this, auth/billing errors surface as plain assistant text posted into chat rooms — the watchdog stays happy and the whole swarm idles silently. `--skip-preflight` bypasses for CI/offline. The Codex preflight only runs when the config has at least one Codex agent.
 - **Doctor** (`doctor.check_claude_auth`) warns when `ANTHROPIC_API_KEY` is set alongside host subscription OAuth — Codeband auto-prefers at run-time, but the WARN flags the suboptimal `.env` for cleanup.
 
 ### Worker pool architecture
 
-Coders, Code Reviewers, Planners, and Plan Reviewers are **pool roles** — each is declared in `codeband.yaml` as `{framework: {count, model}}` under `agents.{coders, reviewers, planners, plan_reviewers}`. Conductor and Mergemaster are **singletons**. Pool member identities follow `{role}-{framework}-{index}` (e.g., `coder-claude_sdk-0`); Band.ai display names are title-cased (`Coder-Claude-0`). The default `cb init` config is 8 agents total — fits Band.ai's free-tier 10-agent cap.
+Coders, Code Reviewers, Planners, Plan Reviewers, and Verifiers are **pool roles** — each is declared in `codeband.yaml` as `{framework: {count, model}}` under `agents.{coders, reviewers, planners, plan_reviewers, verifiers}`. Conductor and Mergemaster are **singletons**. Pool member identities follow `{role}-{framework}-{index}` (e.g., `coder-claude_sdk-0`); Band.ai display names are title-cased (`Coder-Claude-0`). The default `cb init` config is 10 agents total — the 8 coordination/coder/reviewer seats plus one Verifier per vendor — exactly Band.ai's free-tier 10-agent cap. The Verifier is the evidence-integrity acceptance gate that runs after code review and before merge: its `verify_acceptance` verdict is a SHA-pinned merge requirement whenever a verifier is configured. Fresh installs default to `required_verdicts: ["review"]` plus `verify_acceptance` when verifiers are configured; the local `verify` verdict is opt-in via `agents.handoff_verify_command`. Setting `agents.verifiers` to count 0 per vendor opts back out, dropping to 8 agents and merging straight from review.
 
 The `codeband/workers/pool.py:WorkerPool` is a thread-safe in-memory allocator with `acquire(role, framework)`, `release(worker_id)`, and `pair_for_task(coder_role, coder_framework)` which atomically reserves a coder and an opposite-framework reviewer (adversarial cross-model review is the primary value prop — a Claude coder's PR routes to a Codex reviewer, and vice versa). The allocator is defined but not yet wired into the Conductor's LLM prompt — allocation is currently prompt-enforced via `runner._build_worker_roster()` which surfaces the pool to the Conductor. Code-backed allocation is on the roadmap.
 
@@ -44,6 +44,8 @@ The `codeband/workers/pool.py:WorkerPool` is a thread-safe in-memory allocator w
 
 Every agent runs under a reconnect-forever loop: both crashes and clean exits from `agent.run()` trigger another cycle. Unsupervised roles (Conductor, Mergemaster, Planner, Plan Reviewer, Code Reviewer) use the module-level `_run_agent_forever` in `orchestration/runner.py` with exponential backoff capped at 60s. Coders additionally run under `WorkerSupervisor` (`session/supervisor.py`), which rebuilds recovery context from git log + uncommitted changes + `TASK.md` on each restart; identity is persisted as JSON in `workspace/state/<worker-id>.json` (`session/identity.py:WorkerIdentity`). Only SIGINT/SIGTERM ends the process. `PoolEntry.restart_delay_seconds` in `config.py` controls the base supervisor delay; `PoolEntry.max_restarts` is deprecated and no longer honored.
 
+**Reconnect ownership.** Local mode: the outer reconnect loop is the *sole* lifecycle owner — `_patch_band_local_runtime()` disables the SDK's PHX auto-reconnect, so socket death is detected by the websockets keepalive (~40s), which exits the routing task and triggers a fresh cycle; the SDK's idle resync (`agents.idle_resync_seconds`, default 30) is the delivery backstop for missed pushes — with a known upstream defect: the backstop self-disables per room once any one message exhausts its retry budget (client-side permafail pins the head of the `/next` queue); `agents.max_message_retries` (default 3, vs the SDK's 1) reduces how often that fires but does not eliminate it; on each (re)start agents subscribe to existing rooms scoped to active tasks in the StateStore (`cb run --fresh` opts out; a store failure subscribes everything — fail toward connectivity). Teardown between cycles (`_safe_stop_agent`, supervisor `_close_agent`) fails loud at ERROR and verifies the websocket actually closed. Distributed mode (`run_agent`) is intentionally unpatched: SDK-native reconnect and subscribe-existing.
+
 ### Communication: three-channel model
 
 The system uses three channels: **chat** (Band.ai @mentions) for content delivery and coordination, **memory** (Band.ai memory API) for protocol state tracking, and **GitHub PR comments** for code review artifacts. Memory has a 1000-char content limit — full plans, reviews, and logs flow through chat and GitHub, while memory stores lightweight state envelopes.
@@ -87,3 +89,34 @@ Agent system prompts live in `src/codeband/prompts/*.md` and are loaded directly
 - `from __future__ import annotations` in every file
 - Band.ai SDK imports are deferred (inside functions) to keep import time fast and avoid hard dependency when only config/workspace code is used
 - Tests use `tmp_path` fixtures for filesystem isolation; git integration tests create real repos with `subprocess`
+
+---
+
+## Determinism fleet (fork-local coordination)
+
+> This section coordinates the multi-session build of the determinism RFC in this **fork**. It is not part of upstream codeband — exclude it when upstreaming phase branches.
+
+We are implementing [`docs/rfc-deterministic-orchestration.md`](docs/rfc-deterministic-orchestration.md) as **one independent Claude Code session per phase**, each in its own git worktree, each landing **one PR**. Before writing code, read your phase's RFC workstream in full.
+
+**Guiding principle:** the LLM decides, code enforces and remembers — the FSM gates EFFECTS (transitions/merges), not the Conductor's creative routing.
+
+| Phase / worktree | RFC workstream | Owns (new files) | May edit | Depends on |
+|---|---|---|---|---|
+| `phase-1-state-store` | WS1 | `state/__init__.py`, `state/store.py`, `tests/test_state_store.py` | `orchestration/runner.py` (`_install_memory_backend`), `orchestration/kickoff.py` (`send_task`) | — (**blocks all**) |
+| `phase-2-fsm-gates` | WS2+WS3 | `state/fsm.py`, `cli/__init__.py` (move from `cli.py`), `cli/handoff.py`, `tests/test_fsm.py`, `tests/test_handoff.py` | `pyproject.toml`, `config.py` (`AgentsConfig`) | Phase 1 |
+| `phase-3-watchdog` | WS4 | `tests/test_watchdog_upgrade.py` | `agents/watchdog.py`, `config.py` (`WatchdogConfig`), maybe `orchestration/runner.py` | Phase 1 |
+| `phase-4-rehydration` | WS5 | `state/rehydration.py`, `tests/test_rehydration.py` | `orchestration/runner.py` (5 factories + `_run_agent_forever`), `agents/{conductor,planner,plan_reviewer,code_reviewer,mergemaster}.py`, `orchestration/agent_main.py` | Phase 1 |
+
+**Merge order:** Phase 1 first (everything imports `state.store`). Then Phase 2 ∥ Phase 3. Phase 4 last (heaviest `runner.py` edits). Overlap to rebase around: `config.py` (P2 vs P3, different classes) and `runner.py` (P1/P3/P4).
+
+**Rules for every session:**
+- Stay in your lane — implement exactly your phase; do not touch other phases' files. If you need to, STOP and report.
+- Branch + PR always; never commit to `main`; Conventional Commits.
+- Run the suite before push; add **no new failures**. Self-review (`git diff main...HEAD`) — scope must match the phase only.
+
+**Dev env (per worktree — `.venv` is not shared):**
+```
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+```
+**Baseline on `main`: the full suite passes** (the 3 `CliRunner` failures previously listed here have been fixed). Acceptance for any phase = the suite stays fully green and your new tests pass.
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ It is built for headless operation: local terminals, Linux servers, CI, Docker,
 ## Why Codeband?
 
 - **Cross-model review by default**: Claude-written PRs are routed to Codex reviewers, and Codex-written PRs are routed to Claude reviewers.
-- **A real orchestration loop**: planner, plan reviewer, coders, code reviewers, mergemaster, and watchdog coordinate through Band.ai.
+- **A real orchestration loop**: planner, plan reviewer, coders, code reviewers, verifiers, mergemaster, and watchdog coordinate through Band.ai.
 - **Safe workspace isolation**: each coder works in a separate git worktree and opens a PR.
 - **Risk-aware merging**: low-risk PRs can auto-merge; medium, high, and critical changes wait for approval.
 - **Human-friendly and headless**: use the interactive shell locally, or run the same orchestrator in CI and Docker.
@@ -29,7 +29,7 @@ Codeband's main advantage is not raw parallelism; it is adversarial pairing. A t
 
 Parallel coders are useful when the Planner can split a task into independent subtasks with little file overlap. Each coder gets its own git worktree and branch, so separate subtasks can run at the same time without sharing a working directory. Parallel planners and plan reviewers are useful mostly for throughput across multiple queued tasks; for one task, a single Planner plus one opposite-framework Plan Reviewer is usually enough.
 
-The default configuration is the recommended shape: one Claude Coder, one Codex Coder, one Reviewer from each framework, one Planner, and one opposite-framework Plan Reviewer. You can scale pools with `/scale` in the shell or `cb scale`, then run `cb setup-agents` so Band.ai has matching agents.
+The default configuration is the recommended shape: one Claude Coder, one Codex Coder, one Reviewer from each framework, one Planner, one opposite-framework Plan Reviewer, and one Verifier from each framework. You can scale pools with `/scale` in the shell or `cb scale`, then run `cb setup-agents` so Band.ai has matching agents.
 
 For collision-free parallel review, keep opposite-framework reviewer capacity at least as large as coder capacity: Claude coders need Codex reviewers, and Codex coders need Claude reviewers. Today first-dispatch reviewer selection is prompt-enforced from the Worker Pool Roster using deterministic worker-index pairing; full code-backed arbitration is on the roadmap.
 
@@ -138,7 +138,7 @@ Inside the shell:
 
 Slash commands take the rest of the line as their argument, so `/task Add JWT authentication with tests` does not need quotes. In a normal terminal command, quote multi-word descriptions: `cb task "Add JWT authentication with tests"`.
 
-On free-tier Band.ai, `cb setup-agents` may not be available. Create the eight default agents manually and write `agent_config.yaml`; the exact keys are documented in [Configuration](docs/CONFIGURATION.md).
+On free-tier Band.ai, `cb setup-agents` may not be available. Create the ten default agents manually and write `agent_config.yaml`; the exact keys are documented in [Configuration](docs/CONFIGURATION.md).
 
 For credential precedence, Docker auth, and subscription-vs-API-key behavior, see [Authentication](docs/AUTHENTICATION.md).
 
@@ -180,10 +180,12 @@ Conductor
    |                                                  |
    +--> Codex Coder   -----> Claude Code Reviewer ---+--> Mergemaster
    |
+   +--> Verifiers (Claude + Codex acceptance gate)
+   |
    +--> Watchdog
 ```
 
-The default config uses eight Band.ai agents: Conductor, Mergemaster, one Planner, one Plan Reviewer, two Coders, and two Reviewers. The Watchdog is an in-process daemon and does not consume a Band.ai agent seat.
+The default config uses ten Band.ai agents: Conductor, Mergemaster, one Planner, one Plan Reviewer, two Coders, two Reviewers, and two Verifiers. The Watchdog is an in-process daemon and does not consume a Band.ai agent seat.
 
 For the full design, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
@@ -201,6 +203,8 @@ For the full design, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 Codeband is alpha software. The current architecture is prompt-driven: agents follow structured prompts, and the Conductor relies on model context plus memory state to track protocol progress. The roadmap is to move more protocol state and branch enforcement into deterministic Python code.
 
+The state-store schema is not migrated across structural changes: after upgrading past the task-scoped subtask-identity change, delete any pre-existing `{workspace}/state/orchestration.db` before the next run. The same applies after the task-registration change (tasks now carry a required owner and an `owner_handle` column, and re-seeding supersedes the previous task): delete pre-existing dev DBs so stale ownerless or duplicate-active task rows don't linger.
+
 Pool scaling is supported, but first-dispatch worker arbitration is still prompt-enforced. For best results, scale coders and their opposite-framework reviewers together, keep planner/plan-reviewer pools small, and avoid configurations where several coders must share one reviewer unless you are comfortable with queued or overlapping review turns.
 
 Current planned work: