@cluesmith/codev 3.2.4 → 3.3.1

package/skeleton/resources/commands/agent-farm.md

@@ -342,6 +342,41 @@ afx send [builder] [message] [options]
 - `--interrupt` - Send Ctrl+C first
 - `--raw` - Skip structured message formatting
 - `--no-enter` - Do not send Enter after message
+- `--delay <seconds>` - Deliver after N seconds instead of immediately
+
+**Delayed delivery (`--delay`):**
+
+Tower holds the message and delivers it after the stated delay, so the sending process is
+free to exit in the meantime. That is the point: a session can schedule a message to
+*itself* for after something that destroys it.
+
+- **Authorised at request time, delivered later.** Target resolution and the
+  builder-spoofing check run when the command is issued, exactly as for an immediate send.
+  A delayed send cannot defer a check past the conditions that would fail it.
+- **Bounds:** a whole number of seconds, 1–3600, rejected at both the CLI and server
+  boundaries — a bad value silently changes *when* (or whether) a message arrives rather
+  than failing loudly.
+- **Persisted and durable (Spec 1313).** The message is written to Tower's durable mailbox at
+  request time with a due time (`not_before`), so a pending delayed send **survives a Tower
+  restart** — the render gate still guarantees it only lands on a clean, verified-empty prompt
+  when it comes due (this reverses Spec 1307's original drop-on-restart behaviour; the gate now
+  provides the protection that behaviour wanted). A pre-due delayed send is listable — and
+  cancellable — via `afx inbox`.
+- **Ordering:** a delayed message never overtakes one already queued for that session — its
+  durable row is created at request time, and the mailbox delivers the oldest *eligible* row
+  first, so a pre-due message does not block a later message that is already due, and concurrent
+  deliveries to one agent do not interleave. Request order across *differing* delays is **not**
+  preserved — `--delay 30` then `--delay 5` delivers the 5-second one first, because that is what
+  `--delay` means.
+- **Reporting:** the CLI says "scheduled", not "sent", and returns the mailbox id of the
+  persisted row.
+- `--interrupt` is combinable (the Ctrl+C defers *with* the message); the API's `escape`
+  option is not (an ESC bypasses buffering precisely so it interrupts the *current* turn).
+
+```bash
+# Deliver in 15 seconds; this shell can exit immediately
+afx send architect:main --delay 15 --raw '/arch-init main'
+```
 
 **Description:**
 
@@ -350,6 +385,18 @@ Sends text to a builder's terminal. Useful for:
 - Interrupting long-running processes
 - Sending instructions or context
 
+**Outcome (Spec 1313 — mailbox-first delivery):**
+
+`afx send` reports the real first outcome instead of an unconditional "delivered":
+
+- **delivered** — the message was written to the recipient's prompt after a clean render-gate pass (an empty, render-verified prompt).
+- **held** — the prompt was not clear, so the message is persisted in Tower's durable mailbox and **delivers automatically** the moment the recipient's prompt is clean (after a submit, on output quiescence, or a poll backstop). The response carries a **why-held reason** and a mailbox id:
+  - `busy` — a draft, menu, dialog, or wrapper screen occupies the prompt;
+  - `no-profile` — the target app has no render-gate classifier profile (only `claude`, `codex`, and `agy` are modeled);
+  - `no-live-pty` — the recipient agent has no live terminal right now (it delivers when the agent respawns — rows address agents, not PTYs).
+
+A held message is **never force-injected** onto a busy line: a message body is only ever written to a verified-empty prompt, so it cannot fuse with a half-typed draft, and held rows survive Tower restart/shutdown (no shutdown force-flush). See held mail with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>`. `--interrupt` is the explicit, deliberate bypass: it interrupts the agent and writes without holding (unchanged semantics).
+
 **Examples:**
 
 ```bash
@@ -368,6 +415,167 @@ afx send 42 --file src/api.ts "Review this implementation"
 
 ---
 
+### afx inbox
+
+List, inspect, and dismiss **held** (undelivered) messages — the human-facing visibility surface for Spec 1313's mailbox. `afx send` persists a message it can't deliver immediately as a held row that delivers automatically once the recipient's prompt is clear; `afx inbox` lets a human see what is still waiting, read a specific message body, and clear rows — without reading Tower logs.
+
+```bash
+afx inbox [options]
+afx inbox show <id> [options]
+afx inbox dismiss <id> [options]
+```
+
+**`afx inbox`** — list every currently-held message in the workspace. Metadata only — message bodies are never shown in the list (or in logs); use `afx inbox show <id>` to read one:
+
+| Column | Meaning |
+|---|---|
+| `ID` | Mailbox row id (pass to `show` / `dismiss`) |
+| `AGE` | How long the message has been held (`5s`, `3m`, `2h`, `1d`) |
+| `REASON` | Why-held: `busy`, `no-profile`, or `no-live-pty`; a trailing `!` marks a row past the escalation age |
+| `FROM → TO` | Sender → recipient agent |
+| `WORKSPACE` | Owning workspace |
+
+**Options:**
+- `-w, --workspace <path>` - Workspace to list (default: current workspace — `afx inbox` is workspace-scoped, not Tower-wide)
+- `-p, --port <port>` - Tower port (default: 4100)
+
+**`afx inbox show <id>`** — display a single message by id, **including its body**. This is the one CLI surface that surfaces a body: the redaction rule keeps bodies out of logs, diagnostics, and telemetry — not out of this local operator view, which travels over the same local Tower connection the message already uses. `show` works on a row of **any** status (held / delivered / superseded / dismissed), so a resolved row stays inspectable by id for audit until it is pruned. Prints the metadata (status, why-held reason, from → to, workspace, timestamps) followed by the raw body.
+
+**Options:**
+- `-p, --port <port>` - Tower port (default: 4100)
+
+**`afx inbox dismiss <id>`** — mark a held message dismissed. A soft, auditable transition (the row is marked `dismissed`, not deleted) that **never delivers** the message. Any workspace operator may dismiss any held row (same local-human trust level as `afx send`).
+
+**Options:**
+- `-p, --port <port>` - Tower port (default: 4100)
+
+**Examples:**
+
+```bash
+# List held messages in the current workspace
+afx inbox
+
+# Show one message including its body (works for any status, held or resolved)
+afx inbox show 5f3c9a2b-1e4d-4c7a-9f21-8b6d0e2a1c33
+
+# Dismiss a held message by id (never delivers it)
+afx inbox dismiss 5f3c9a2b-1e4d-4c7a-9f21-8b6d0e2a1c33
+```
+
+Dismissal is CLI-only; the dashboard and VSCode held-count indicators surface the count but are read-only (Spec 1313 decision 8).
+
+---
+
+### afx interrupt
+
+Interrupt a builder mid-turn by sending an ESC keystroke to its PTY.
+
+```bash
+afx interrupt <builder> [options]
+```
+
+**Arguments:**
+- `builder` - Target builder. Same addressing as `afx send`.
+
+**Options:**
+- `--no-enter` - Send ESC alone, without the trailing Enter
+
+**Description:**
+
+This is the only recovery that reaches a builder **mid-turn**. When a builder chains foreground waits
+inside a single turn, every `afx send` — including your order to stop — queues unread until that turn
+ends. ESC interrupts the running tool and ends the turn, after which the queued messages process. The
+trailing Enter (default) is what lets them through.
+
+Distinct from `afx send --interrupt`, which sends Ctrl+C.
+
+**Examples:**
+
+```bash
+# Builder is wedged on a foreground wait and not reading messages
+afx interrupt 0042
+
+# Then the queued instruction lands
+afx send 0042 "That producer died — stop waiting and report."
+```
+
+---
+
+### afx refresh
+
+Refresh a builder's context: have it save its working state, clear the conversation, then re-orient it.
+
+```bash
+afx refresh <builder> [options]
+```
+
+**Arguments:**
+- `builder` - Target builder. Same addressing as `afx send`.
+
+**Options:**
+- `--note <text>` - Extra context appended to the re-orientation
+- `--file <path>` - Append file content to the re-orientation (48KB max, read from *your* filesystem)
+- `--dry-run` - Print the save request and both re-orientation payloads; write nothing to the builder
+- `--interrupt-first` - Send ESC before the save request, for a builder already wedged mid-turn
+- `--mode <strict|soft>` - Override the builder mode if it cannot be detected
+- `--timeout <seconds>` - How long to wait for the save-state receipt (default 300)
+- `--min-bytes <n>` - Minimum state-file size to accept as substantive (default 1000)
+- `--quiet-window <ms>` - Terminal silence that counts as turn-ended (default 1500)
+
+**Deprecated alias:** `afx reset` still runs this command and prints a one-line notice to stderr.
+It will be removed in a future release — use `afx refresh`.
+
+**Description:**
+
+Long-running builders exhaust their context window. `afx spawn --resume` reattaches the *same*
+conversation, so a deep session resumes deep — it does not give the builder a fresh window. `afx refresh`
+does, without losing what the builder knows.
+
+The sequence:
+
+1. Assemble the re-orientation and write it to `.builder-reorient.md` in the worktree.
+2. Ask the builder to write its complete working state to `.builder-state.md`, stamped with a one-time
+   nonce.
+3. Wait for that file and **verify** it: correct nonce (not a stale file from an earlier refresh),
+   substantive size, and stable across two observations (not still being written).
+4. Wait for the terminal to fall silent, so the clear is not typed mid-turn. If it does not settle, send
+   **one** ESC and wait again.
+5. Send `/clear`.
+6. Deliver the re-orientation: role, protocol, mode, project, worktree, branch, the porch re-entry
+   instruction, and a pointer to the state file.
+
+**Every gate fails safe.** If the state file never arrives, carries the wrong nonce, is a stub, is still
+growing, or the builder will not go quiet — the command **aborts without clearing** and exits non-zero,
+naming the gate that failed. A builder whose context was not cleared has lost nothing.
+
+Both worktree artifacts use the `.builder-` prefix, so `afx cleanup` still classifies the worktree as
+clean, and both are untracked so `porch done`'s staged-file sweep cannot pick them up.
+
+Requires a harness with in-session context reset (Claude Code). Other harnesses abort loudly rather than
+substituting a different mechanism — use the boundary-recycle pattern instead (let the builder finish,
+then `afx spawn <id> --resume`).
+
+**Examples:**
+
+```bash
+# See exactly what would be sent, without touching the builder
+afx refresh 0042 --dry-run
+
+# Standard refresh
+afx refresh 0042
+
+# Add context that post-dates the builder's saved state
+afx refresh 0042 --note "PR #90 merged while you were mid-phase. Rebase before continuing."
+
+# The builder is wedged mid-turn and not reading messages
+afx refresh 0042 --interrupt-first
+
+# A builder that legitimately needs longer to write its state
+afx refresh 0042 --timeout 600
+```
+
+---
+
 ### afx open
 
 Open file annotation viewer.
@@ -537,6 +745,42 @@ afx tower status [options]
 
 ---
 
+### afx cron
+
+Manage scheduled tasks defined as YAML files in `.af-cron/` at the workspace root. The Tower scheduler loads these every tick, runs due commands, and delivers messages through the normal send pipeline.
+
+```bash
+afx cron list                   # List all cron tasks
+afx cron status <name>          # Check task status
+afx cron run <name>             # Run immediately
+afx cron enable <name>          # Enable
+afx cron disable <name>         # Disable
+```
+
+There is NO `afx cron add` — create YAML files in `.af-cron/` directly.
+
+**Task YAML format:**
+
+```yaml
+name: Service Health Check      # required, unique per workspace
+schedule: "*/15 * * * *"        # required, cron expression (or @hourly/@daily/@startup)
+command: ./health-check.sh      # required, run via shell
+message: "Health alert: ${output}"  # required, ${output} = trimmed command output
+condition: "exitCode != 0"      # optional JS expression, see below
+target: architect               # optional, default architect
+timeout: 30                     # optional, seconds, default 30
+enabled: true                   # optional, default true
+```
+
+**Condition environment:** `condition` is a JavaScript expression evaluated with two variables in scope:
+
+- `output` (string) — the command's trimmed output
+- `exitCode` (number) — `0` on success, the command's exit code on non-zero exit, `124` on timeout, `-1` on spawn failure
+
+With a `condition`, the message is delivered exactly when the expression evaluates truthy — including on failed runs, so `condition: "exitCode != 0"` alerts when the command fails. Without a `condition`, the message is delivered only when the command exits 0.
+
+---
+
 ### afx db
 
 Database debugging and maintenance commands.
@@ -645,6 +889,24 @@ afx workspace start --architect-cmd "claude --model opus"
 afx spawn 42 --protocol spir --builder-cmd "claude --model haiku"
 ```
 
+### Mailbox retention and escalation
+
+`afx send`'s mailbox (Spec 1313) has two Tower-global knobs under a `mailbox` key:
+
+```json
+{
+  "mailbox": {
+    "retentionDays": 30,
+    "escalationSeconds": 60
+  }
+}
+```
+
+- `mailbox.retentionDays` (default `30`) — how long a **terminal** mailbox row (delivered, superseded, or dismissed) is retained before Tower prunes it. **Held** rows are never pruned — they persist until they deliver, are superseded, or are dismissed via `afx inbox`.
+- `mailbox.escalationSeconds` (default `60`) — how long a row may stay **held** before it crosses the escalation age. At that point the drainer marks the row `escalated`, emits the escalation broadcast, and moves the dashboard / VSCode held-count indicator into its attention state. This is **visibility only** — crossing the escalation age never triggers delivery (there is no force path; a held message still delivers only onto a verified-empty prompt).
+
+Both are Tower-global (they apply to the whole Tower, not per-project) and optional — omit them to use the defaults above.
+
 ---
 
 ## Files

package/skeleton/resources/commands/consult.md

@@ -15,14 +15,214 @@ consult stats [options]
 -m, --model <model>    Model to use (required for all modes except stats)
 ```
 
+## Model Selection Options
+
+```
+--model-id <id>        Override the provider model id for THIS invocation
+```
+
+`-m/--model` picks the **lane** (`claude`, `codex`, `gemini`, `hermes`); `--model-id` picks the
+**model that lane runs**. The two are independent — see [Configuration](#configuration) for setting
+an id persistently instead.
+
+```bash
+consult -m codex --model-id gpt-5.6-sol --prompt "Review this design"
+```
+
+- **Precedence**: `--model-id` > `consult.models.<lane>` > the lane's shipped default.
+- **Supported lanes**: `claude`, `codex`, `gemini`. Using it with `hermes` is an **error**, not a
+  silent no-op — `hermes chat -q` has no model selector, so accepting the flag there would mean
+  ignoring it.
+- **Validation is syntax-only.** Whether the id exists is the provider's call; a rejection fails
+  loudly with no fallback to the default. See
+  [the fail-fast contract](#the-fail-fast-contract-and-where-it-stops).
+
 ## Models
 
-| Model | Alias | Backend | Notes |
-|-------|-------|---------|-------|
-| `gemini` | `pro` | Antigravity CLI (`agy`) | Agentic file access (`--sandbox --add-dir`), OAuth/subscription login. Skips non-blockingly if `agy` is missing/unauthed. |
-| `codex` | `gpt` | @openai/codex | Read-only sandbox, thorough |
-| `claude` | `opus` | Claude Agent SDK | Balanced analysis with tool use |
-| `hermes` | - | hermes CLI (`hermes chat -q`) | Uses Hermes agent as consult backend |
+| Model | Alias | Backend | Shipped default model id | Notes |
+|-------|-------|---------|--------------------------|-------|
+| `gemini` | `pro` | Antigravity CLI (`agy`) | *(agy's own default — no pinned id)* | Agentic file access (`--sandbox --add-dir`), OAuth/subscription login. Skips non-blockingly if `agy` is missing/unauthed. |
+| `codex` | `gpt` | @openai/codex | `gpt-5.6-sol` (medium reasoning effort) | Read-only sandbox, thorough |
+| `claude` | `opus` | Claude Agent SDK | `claude-opus-5` | Balanced analysis with tool use |
+| `hermes` | - | hermes CLI (`hermes chat -q`) | *(hermes' own default)* | Uses Hermes agent as consult backend |
+
+> **The codex lane's `-sol` suffix is load-bearing.** Plain `gpt-5.6` and `gpt-5.6-codex` are both
+> rejected by Codex when running on a ChatGPT account (`The '<id>' model is not supported when
+> using Codex with a ChatGPT account.`). Don't "simplify" the id — a unit test pins it.
+
+### Cost reporting
+
+Codex consultation cost is computed from OpenAI's published per-1M-token rates for the lane's
+model. If a model has no rates recorded in Codev, the consultation still runs and its token counts
+are still recorded, but `cost_usd` is stored as `null` rather than billed at some other model's
+rates. Only OpenAI's standard pricing tier is modelled — costs for consultations large enough to
+enter the long-context tier are under-reported.
+
+Supply rates for a model Codev doesn't know with [`consult.pricing.codex`](#consultpricingcodex).
+
+## Configuration
+
+Everything below lives in `.codev/config.json` and flows through the standard five-layer config
+stack, lowest priority to highest:
+
+1. built-in defaults
+2. `<cache>/config.json` — remote framework base config
+3. `~/.codev/config.json` — global, per-user, across all projects
+4. `.codev/config.json` — project, checked in
+5. `.codev/config.local.json` — project, per-engineer, gitignored
+
+So any key can be set globally and narrowed per project, and an individual engineer can override
+either without touching a checked-in file.
+
+**Two independent axes**, easy to confuse:
+
+| Axis | Key | Answers |
+|------|-----|---------|
+| *Which model* a lane runs | `consult.models` | "run `claude-opus-5` on the claude lane" |
+| *Which lanes* run at all | `porch.consultation.*` | "review PIR with two lanes, not three" |
+
+### `consult.models`
+
+Per-lane model id. Absent → the shipped default in the [Models](#models) table. Outranked for a
+single invocation by [`--model-id`](#model-selection-options).
+
+```json
+{ "consult": { "models": { "claude": "claude-opus-5", "codex": "gpt-5.6-sol" } } }
+```
+
+Valid lanes: `claude`, `codex`, `gemini`. **`hermes` is rejected** — it is invoked as
+`hermes chat -q` and exposes no model selector, so configuring one would silently do nothing.
+(`hermes` remains valid in `porch.consultation` lane lists; the two key spaces differ on purpose.)
+
+The `gemini` lane passes the id to `agy --model`, so the id space is agy's, not Google's API's.
+
+### `consult.reasoningEffort`
+
+```json
+{ "consult": { "reasoningEffort": { "codex": "high" } } }
+```
+
+Only `codex` exposes this. Values: `minimal`, `low`, `medium`, `high`, `xhigh` (default `medium`).
+Unlike model ids, this **is** a closed set Codev validates locally — see the asymmetry below.
+
+### `consult.pricing.codex`
+
+Per-1M-token rates for the codex lane. Set this when Codev has no rates for the model you run
+(otherwise `cost_usd` is `null`), or to correct rates that have gone stale.
+
+**It outranks the shipped rate table for every model, not only unknown ones** — once set, it is
+used for whatever the codex lane runs, so it is worth revisiting if you later change the model.
+
+```json
+{ "consult": { "pricing": { "codex": { "inputPer1M": 5.00, "cachedInputPer1M": 0.50, "outputPer1M": 30.00 } } } }
+```
+
+> **Take the numbers from the provider, not from here.** Those are the rates Codev ships for
+> `gpt-5.6-sol` at the time of writing, shown so the shape is concrete — they are not right for
+> whatever model you are configuring, and published rates change. Copying a plausible-looking wrong
+> rate produces a confidently wrong cost, which is the exact failure this key exists to prevent;
+> a `null` cost is the better outcome of the two.
+
+- **`codex` is the only accepted lane.** Claude reports its own cost directly and the gemini/agy
+  lane reports no usage data at all, so a pricing override for either would be inert. Any other
+  lane key is an error.
+- **All three rates are required together**, and each must be a finite, non-negative number. A
+  partial object is an error, not a half-priced estimate: defaulting any one rate to a stale
+  built-in would reintroduce exactly the wrong-cost problem this override exists to fix.
+
+### `porch.consultation` — which lanes run
+
+Lane lists accept a single name (`"codex"`), an array (`["codex", "claude"]`), or a whole-value
+special mode: `"none"` (skip consultation) or `"parent"` (emit a gate for the architect instead).
+An **empty array is rejected** — use `"none"`, so there is exactly one way to say it.
+
+`models` is the workspace-wide default, `modelsByType` narrows by review type, and `byProtocol`
+scopes either of those to one protocol:
+
+```json
+{
+  "porch": {
+    "consultation": {
+      "models": ["gemini", "codex", "claude"],
+      "modelsByType": { "pr": ["codex", "claude"] },
+      "byProtocol": {
+        "pir": {
+          "models": ["gemini", "codex"],
+          "modelsByType": { "impl": ["codex"] }
+        }
+      }
+    }
+  }
+}
+```
+
+Review-type keys are the protocol's own `verify.type` values (`spec`, `plan`, `impl`, `pr`, …);
+protocol keys are protocol names, and aliases are canonicalized so `byProtocol.spider` matches a
+project running as `spir`. Unknown keys in either space are **errors, not warnings** — a typo that
+merely warned would silently leave you on the defaults you were trying to override.
+
+#### Precedence
+
+Highest first. The first level that is present wins outright; levels do not merge.
+
+1. `porch.consultation.byProtocol[<protocol>].modelsByType[<type>]`
+2. `porch.consultation.byProtocol[<protocol>].models`
+3. `porch.consultation.modelsByType[<type>]`
+4. `porch.consultation.models`
+5. the protocol's own `verify.models` (i.e. no config at all)
+
+Both `porch next` and `porch done` resolve through this one ladder, so the lanes porch asks you to
+run are exactly the lanes it will require review files for.
+
+#### Worked example: keeping PIR cheap while widening the default
+
+PIR is deliberately a 2-lane (CMAP-2) protocol. A workspace-wide 3-lane default silently inflates
+it, because config outranks protocol. Scope PIR back down explicitly:
+
+```json
+{
+  "porch": {
+    "consultation": {
+      "models": ["gemini", "codex", "claude"],
+      "byProtocol": { "pir": { "models": ["gemini", "codex"] } }
+    }
+  }
+}
+```
+
+`["gemini", "codex"]` is PIR's own shipped pair, so this restores exactly what the protocol declares
+rather than substituting a different two. SPIR and ASPIR reviews run three lanes; PIR runs two.
+Without the `byProtocol` entry, PIR would run three and cost 50% more per review with no change to
+the protocol file.
+
+### The fail-fast contract, and where it stops
+
+Config errors are raised when config is **loaded** — before any consultation starts — and name the
+offending key and the valid alternatives. Nothing falls back to a default on error.
+
+**The asymmetry worth knowing about:** these two are validated very differently.
+
+| | Validated by | When you find out |
+|---|---|---|
+| `reasoningEffort` | **Codev**, against a closed enum | Config load, before anything runs |
+| Model ids | **The provider** | When the lane runs |
+
+Codev checks a model id's *syntax* only (ASCII alphanumerics plus `. _ : / @ + -`, 1–200 characters,
+no leading punctuation) — never its existence. **There is no allowlist of model ids anywhere in
+Codev, by design**: a new model must work the day the provider ships it, without a Codev release.
+
+So a typo'd model id is not caught at config time. It reaches the backend, which rejects it; that
+lane exits non-zero, the provider's error text is surfaced, the config key that supplied the id is
+named, and **no review file is written** — so porch cannot advance on a lane that never ran. What
+you do *not* get is a silent substitution of the default model.
+
+One deliberate exception: a `gemini` lane **with no model id resolved** still skips non-blockingly
+when `agy` is missing or unauthenticated (consultation is best-effort there). Once an id *is*
+resolved — from either `consult.models.gemini` **or** `--model-id` — a rejected model becomes a hard
+failure for that lane, because you asked for a specific model and did not get it. What still skips
+rather than fails, even with an id, are causes that are not the model's fault: `agy` absent,
+unauthenticated, timed out, killed by a signal, or exiting **successfully** having produced no
+output at all.
 
 ## Modes
 
@@ -78,10 +278,11 @@ consult -m codex --type integration --issue 42 --base ci
 - `--base <ref>` — **`--type integration` only.** Anchor the diff on this base branch (e.g. `ci`), computed locally as `git diff origin/<base>...origin/<head>` (three-dot, merge-base anchored). Use in repos with a long-lived integration branch ahead of the default branch so the review sees only the PR's actual change, not the whole integration-over-trunk delta. Unresolvable refs fail loudly with a `git fetch` hint (no silent fallback to the local checkout). Defaults to config `consult.integrationBranch`; with neither set, the integration review uses the PR's host-recorded base (`gh pr diff`), unchanged.
 
 **Config (`.codev/config.json`):**
-```jsonc
+`integrationBranch` is the repo-wide default base for `--type integration`, overridden by `--base`.
+
+```json
 {
   "consult": {
-    // Repo-wide default base for `--type integration` (overridden by --base).
     "integrationBranch": "ci"
   }
 }
@@ -196,6 +397,33 @@ through to a normal spawn.
 | `CODEV_AGY_AUTH_CACHE_DIR` | `~/.cache/codev` | Cache location (mainly for tests). |
 | `CODEV_AGY_AUTH_CACHE_DISABLE` | unset | `1` restores the always-spawn behaviour. |
 
+#### Test isolation
+
+The cache above protects *production* runs. It did not protect test runs: the
+cache disables itself under `VITEST` unless a cache directory is named, and any
+test that reached the gemini lane without pinning `CODEV_AGY_BIN` resolved the
+real binary — so a suite run could still open a login window per spawn (#1323).
+Consult now treats a test runner as a hard boundary. Under `VITEST` (or
+`CODEV_TEST_ISOLATION`) it refuses to resolve an unpinned `agy` and refuses to open the
+user-global metrics database, failing loudly instead of reaching either. Codev's
+own suites pin a fake `agy`, a sandbox auth cache, and a sandbox metrics DB for
+every test; spawned `codev` / `consult` children inherit the pins through the
+environment.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CODEV_AGY_BIN` | auto-resolved | Pin the agy binary. The harness sets this to a fake for every test. |
+| `CODEV_ALLOW_REAL_AGY` | unset | `1` opts a test run into the REAL agy binary — the guarded integration smoke and real-AI e2e runs. Expect a browser window if agy's login has lapsed. |
+| `CODEV_METRICS_DB` | `~/.codev/metrics.db` | Redirect the consult metrics database. Required under a test runner; the harness points it at a temp dir so suite runs stop skewing `consult stats`. |
+| `CODEV_TEST_ISOLATION` | unset | `1` applies the same guards to a harness that is not vitest. |
+
+**Adopters:** `VITEST` is exported by *any* vitest run, including yours. If your
+project's own suite deliberately shells out to `consult -m gemini`, that call now
+throws until you set `CODEV_ALLOW_REAL_AGY=1` (and `CODEV_METRICS_DB` if you want
+the metrics recorded somewhere). This is intentional — a suite reaching the real
+agy is what #1323 was about — but it is a behaviour change, not a silent one: the
+error names the variable to set.
+
 ### Claude auth: subscription vs. metered API
 
 `consult -m claude` runs on the Claude Agent SDK. When `CLAUDE_CODE_OAUTH_TOKEN`

package/skeleton/resources/commands/overview.md

@@ -59,6 +59,7 @@ See [codev.md](codev.md) for full documentation.
 | `afx status` | Show status of all agents |
 | `afx cleanup` | Clean up a builder worktree |
 | `afx send` | Send instructions to a builder |
+| `afx inbox` | List/show/dismiss held (undelivered) messages |
 | `afx open` | Open file annotation viewer |
 | `afx shell` | Spawn a utility shell |
 | `afx tower` | Cross-project dashboard |