@cluesmith/codev 3.3.3 → 3.3.5

package/skeleton/.claude/skills/generate-image/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-image
-description: AI image generation via Gemini, or Atlas Cloud with `-p atlas`. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY, or ATLASCLOUD_API_KEY when using `-p atlas`.
+description: AI image generation via Gemini with optional async providers. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires the API key for the selected provider.
 ---
 
 # generate-image - AI Image Generation
@@ -22,7 +22,7 @@ Note: this is a `codev` subcommand, not standalone.
 -r, --resolution <res>     Resolution: 1K, 2K, 4K (default: 1K)
 -a, --aspect <ratio>       Aspect ratio (default: 1:1)
 --ref <image>              Reference image (repeatable, max 14)
--p, --provider <name>      Provider: gemini (default) or atlas
+-p, --provider <name>      Provider name (default: gemini)
 ```
 
 ## Aspect ratios
@@ -64,3 +64,20 @@ Measured differences on that path:
   than silently ignoring the images.
 - The model returns JPEG, so the output file is named after its actual bytes
   instead of writing JPEG into the default `output.png`.
+
+## MuAPI provider
+
+`-p muapi` uses MuAPI's Nano Banana Pro endpoint with the same aspect-ratio and
+resolution controls. Set `MUAPI_API_KEY` (or `MU_API_KEY`) using the [MuAPI
+access keys page](https://muapi.ai/access-keys). Reference images are uploaded
+to MuAPI and sent to the edit endpoint; returned media is downloaded only over
+HTTPS.
+
+```bash
+codev generate-image "A sunset over mountains" -p muapi -a 16:9
+codev generate-image "Keep the subject, change the lighting" -p muapi --ref subject.png
+```
+
+The provider submits a job, polls the [MuAPI image API](https://muapi.ai/ai-image-api),
+and writes the returned image locally. Polling and individual requests are
+bounded, and the API key is never sent to the returned media host.

package/skeleton/.claude/skills/porch/SKILL.md

@@ -45,6 +45,7 @@ porch approve 42 pr --a-human-explicitly-approved-this
 
 ```bash
 porch pending                  # List all gates waiting for approval
+porch pending --all            # Include stale records on finished/advanced projects (hidden by default)
 ```
 
 ## Critical rules
@@ -55,6 +56,23 @@ porch pending                  # List all gates waiting for approval
 - `porch run` is for strict mode only — soft mode builders follow the protocol document manually
 - When running `porch approve` from the architect, use a subshell if you need worktree context: `(cd /path/to/worktree && porch approve ...)`
 
+## Check overrides and timeouts (`porch.checks`)
+
+Override a protocol check per name in `.codev/config.json` under `porch.checks` instead of forking `protocol.json`. Each entry takes `command` (replace), `cwd` (replace), `timeout_ms` (replace), and/or `skip: true`:
+
+```jsonc
+{
+  "porch": {
+    "checks": {
+      "tests":     { "command": "uv run pytest", "timeout_ms": 900000 },
+      "e2e_tests": { "skip": true }
+    }
+  }
+}
+```
+
+A phase check is killed after 5 minutes unless it sets `timeout_ms` — in `protocol.json` or in its `porch.checks` override. On timeout porch kills the check's whole process tree.
+
 ## State storage
 
 Project state lives in `codev/projects/<id>-<name>/status.yaml`, managed automatically by porch. The status file tracks current phase, gate states, consultation results, and timestamps.

package/skeleton/.codex/skills/afx/SKILL.md

@@ -184,8 +184,23 @@ There is NO `afx tower restart` — use `afx tower stop && afx tower start`.
 ```bash
 afx workspace start             # Start workspace for current project
 afx workspace stop              # Stop workspace processes
+afx workspace add-architect --name <name>   # Add a named sibling architect terminal
+afx workspace remove-architect <name>       # Remove a sibling architect (cannot remove main)
+afx workspace recover           # Revive builders whose shellper died (e.g. after reboot)
 ```
 
+**Recreating a dead architect** (its process died while Tower kept the registration):
+re-add it under the SAME name, then re-init its identity:
+
+```bash
+afx workspace add-architect --name <name>
+afx send architect:<name> "/arch-init <name>"
+```
+
+Builder-to-architect affinity survives the death (builders keep their Owner), so a
+same-name re-add restores routing with no worktree impact and no builder disruption.
+`afx workspace recover` revives builders only, not architects.
+
 `afx dash` is a deprecated alias — use `afx workspace` instead.
 
 ## afx cron

package/skeleton/.codex/skills/arch-init/SKILL.md

@@ -46,12 +46,56 @@ name in a multi-architect workspace).
      (`codev/state/*.md`); never commit them. Builder `*_thread.md` files
      are the opposite: versioned, shipping with each builder PR.
 
-3. **Confirm identity + orient, then follow the state file.** In one tight
-   block, report: who you now are (name + one-line role from the banner, if
-   present), the file you read, and the current-state / open-loops summary
-   from the most recent dated section (or the file's leading content if it
-   has no dated sections). Then carry out whatever the state file says to do
-   on resume. Do not invent a new agenda — resume the one the state file
+3. **Confirm identity + orient.** In one tight block, report: who you now are
+   (name + one-line role from the banner, if present), the file you read, and
+   the current-state / open-loops summary from the most recent dated section
+   (or the file's leading content if it has no dated sections). If the banner
+   carries a `NEXT TASK` line, report both halves of it, as
+   `Next task from the owner at save time: <verbatim>  → resolved: <gloss>`
+   (omit `→ resolved: …` when the line carries no `[resolved at save: …]` gloss).
+
+4. **Start on the next task, if the banner carries one.** It is the **first
+   action of the resumed session**, ahead of the general resume agenda — the
+   owner wrote it at save time precisely so it would not have to be typed
+   again once you came back. Begin it without waiting for a further prompt.
+   - It carries the owner's authority the way any owner message does, **with
+     the standard limits unchanged**. A next task never by itself approves a
+     porch gate, merges a PR, cuts a release, restarts Tower, or performs any
+     other act that needs a per-occasion word. If the next task *is* such an
+     act, prepare it and ask for the word live: a saved instruction is an
+     instruction, not a pre-spent approval.
+   - **The gloss carries the word — for the items it names, and only them.**
+     Items named in a `[resolved at save: …]` gloss are approved for the act
+     the owner's words name: "merge them all [resolved at save: PRs #1710,
+     #1712]" means merge #1710 and #1712 without asking again. The owner gave
+     the word at save time, and the saving session pinned it to those items.
+     This narrows the rule above; it does not remove it — and a line with no
+     gloss pre-approves nothing:
+     - The act must be the one the owner's words say. **A gloss never widens
+       the verb** — "merge" does not also approve a release.
+     - **Anything not in the gloss still needs the word live.** A PR that
+       appeared after the save, an item the gloss did not name, a gate the
+       words did not mention → prepare and ask, exactly as above.
+     - Porch gates are still relayed to the builder, never run by you: the
+       gloss lets you *relay* the approval without re-asking; it does not
+       change who runs `porch approve`.
+     - Ordinary verification still applies: an approved merge still waits for
+       green CI, and a gloss item you find already merged, closed, or changed
+       is reported, not forced.
+     - **A line marked `[carried over — …]` is orientation only.** Its gloss
+       was written by an earlier cycle and carries no word: ask for it before
+       any gated act.
+   - **This does not narrow the gate rule.** The human decision was explicit
+     at save time, and the gloss is its record. What the rule forbids —
+     inferring approval from a gate notification, from silence, or from an
+     agent's own judgment — stays forbidden; a gloss is none of those.
+   - **Once you have started, delete the `NEXT TASK` line from the banner**
+     and record the pickup as a log entry (`picked up next task: <verbatim>
+     → resolved: <gloss>`, omitting `→ resolved: …` when there was no gloss).
+     A second re-init, or the next `/arch-save`, must not re-run it.
+
+5. **Then follow the state file.** Carry out whatever it says to do on
+   resume. Do not invent a new agenda — resume the one the state file
    describes.
 
 ## Saving your state (and knowing when to `/clear`)
@@ -118,9 +162,12 @@ Do not repeat it, and do not prompt for it at any other time.
 **`/arch-save` packages this whole loop**, and is the preferred path when the
 owner directs a refresh: it stops your monitors, writes the pruned state file,
 clears, and schedules `/arch-init` to bring you back — in that order, which is
-the part that matters. The save discipline above is what it performs at its
-step 3, so this section remains the source of truth for *how to write the
-file*; `/arch-save` is the source of truth for *the sequence*. The manual path
+the part that matters. It also accepts a **next task** as free text
+(`/arch-save file and spawn that issue`), which it writes into the banner as a
+`NEXT TASK` line for step 4 above to pick up. The save discipline above is
+what it performs at its step 3, so this section remains the source of truth
+for *how to write the file*; `/arch-save` is the source of truth for *the
+sequence*. The manual path
 (save → human clears → `/arch-init`) stays valid and is the fallback when
 Tower is unavailable.
 

package/skeleton/.codex/skills/arch-save/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: arch-save
 description: Save an architect's state, clear its context, and re-init automatically — the packaged save→clear→re-init refresh cycle. Use when the owner directs a context refresh, or says "/arch-save", "save and clear", "refresh your context". Runs on the owner's direction; an architect does not invoke it autonomously mid-task. Counterpart to /arch-init, which recovers the state this writes.
-argument-hint: "[name]   (e.g. main; omit to auto-detect via afx whoami)"
+argument-hint: "[name] [next task]   (e.g. main; or: file and spawn that issue)"
 ---
 
 # /arch-save — save state, clear, and come back as yourself
@@ -9,7 +9,18 @@ argument-hint: "[name]   (e.g. main; omit to auto-detect via afx whoami)"
 Long sessions accumulate stale context. This is the deliberate cure: you choose the
 moment, you choose what survives, and a fresh session resumes from what you wrote.
 
-`$ARGUMENTS` is the architect name (e.g. `main`). Omit it to auto-detect.
+`$ARGUMENTS` carries the architect name, a **next task** for the session that comes back,
+or both:
+
+```
+/arch-save                                  save, clear, re-init, then wait
+/arch-save file and spawn that issue        … and start on that first, unprompted
+/arch-save main file and spawn that issue   explicit name, then the next task
+```
+
+The next task is how an owner who already knows what the refreshed session should do first
+says so once, at the moment they direct the refresh, instead of watching for the re-init to
+land and typing it again.
 
 ## When NOT to run this
 
@@ -28,20 +39,51 @@ action. A mid-task snapshot resumes into confusion.
 Do these in order. **The order is the feature** — step 3 must precede step 4, because the
 context that knows what to write is the one about to be destroyed.
 
-### 1. Resolve your name
+### 1. Resolve your name, then split off the next task
 
-If `$ARGUMENTS` is non-empty, that is your name. Otherwise run `afx whoami` and use the
-reported `name` when `type: architect`.
+**Always run `afx whoami` first**, whatever `$ARGUMENTS` holds — the split below cannot
+tell a name from a task until it knows your name. The name rules are unchanged:
 
+- `type: architect` → the reported `name` is yours.
 - `type: builder` → **STOP.** This terminal is a builder. Report the mismatch.
-- Non-zero exit → **STOP** and ask which architect you are. Do **not** guess, and do not
-  default to `main` — writing another architect's state file is the exact failure
-  `/arch-init` exists to prevent (#1094).
+- Non-zero exit → you have no name yet. A single-token `$ARGUMENTS` that validates as a
+  name is still accepted as one; anything else → **STOP** and ask which architect you are.
+  Do **not** guess, and do not default to `main` — writing another architect's state file
+  is the exact failure `/arch-init` exists to prevent (#1094).
 
 **Validate the name before building any path**: `[a-z][a-z0-9-]*`, at most 64 characters.
 Reject slashes, `..`, uppercase, spaces. Never interpolate an unvalidated name into
 `codev/state/<name>.md`.
 
+Then split `$ARGUMENTS`:
+
+1. `$ARGUMENTS` is empty → name from `afx whoami`, and there is no next task.
+2. The **first whitespace-separated token** equals the whoami name (or, when whoami could
+   not resolve one, is a single token that validates as a name) → that token is the name,
+   and the **remainder** is the next-task text, which may be empty.
+3. Otherwise → the **whole** of `$ARGUMENTS` is the next-task text, and the name comes
+   from `afx whoami`.
+
+So `/arch-save` and `/arch-save main` behave exactly as they always have. The one
+ambiguity — a next task whose first word happens to be your own architect name — is
+accepted rather than worked around: lead with the explicit name
+(`/arch-save main main is stalled, look at it`) to disambiguate.
+
+**If you had to ask which architect you are, the next task still stands.** The answer
+supplies the name; `$ARGUMENTS` already supplied the task. Do not make the owner retype it.
+
+**Guard, applied after the split: a leading token that names a *different* architect stops
+you.** If the first token validates as a name, differs from the name whoami reported, and
+`codev/state/<token>.md` exists → **STOP and ask which architect you are. Write nothing.**
+whoami can be wrong (#1094), and rule 3 would otherwise bury a real name-override inside
+next-task text and save to whoami's file; a task that merely opens with a sibling's name is
+the only case this costs, and it costs one clarification.
+
+**This is not how `/arch-init` resolves a name**, and the asymmetry is deliberate:
+`/arch-init` takes no next task, so any non-empty argument there is unambiguously a name
+and overrides whoami outright. Here the first token is weighed *against* whoami, which is
+why the guard above exists — never save into a name you did not verify.
+
 ### 2. Stop your own monitors
 
 Enumerate every monitor, watcher or background task you armed, and stop it.
@@ -75,6 +117,50 @@ first (`cp codev/state/<name>.md codev/state/.<name>.bak.md`) is cheap insurance
 **Content guardrails.** No secrets — tokens, keys, credentials. No transcript dumps, no
 raw tool output. Only: current focus, open loops, and what a fresh session needs to resume.
 
+**Write the next task into the banner**, if step 1 produced one. Add a single line to the
+banner block, directly after the `⭐ THIS /clear IS INTENTIONAL` line:
+
+```
+# ⏭ NEXT TASK (owner-directed at save, 2026-09-19T02:10Z): file and spawn that issue
+```
+
+- **Verbatim.** Collapse newlines to spaces; do not paraphrase, expand, or "helpfully"
+  plan it. Those are the owner's words, and the context writing them down is the one about
+  to be destroyed — this is the last moment at which a paraphrase can be caught.
+- **New text replaces** any existing NEXT TASK line.
+- **No new text preserves an existing one.** A NEXT TASK line still in the banner means the
+  previous cycle never came back to pick it up; dropping it silently would lose an owner
+  instruction that nothing else is holding. **Mark it carried over when you preserve it:**
+  append `[carried over — gloss orients only; re-confirm before acting]` to the line (once;
+  a line already marked stays as it is). A gloss carries the owner's word only for the
+  cycle that wrote it.
+
+**Then resolve its referents — resolve, don't plan.** After the clear, "them" points at
+nothing; this context is the only one that knows what the owner meant. So pin every
+referent in the owner's words to a concrete, durable identifier, and append it to the same
+line, after the verbatim text, as a `[resolved at save: …]` gloss:
+
+```
+# ⏭ NEXT TASK (owner-directed at save, 2026-09-22T13:40Z): merge them all  [resolved at save: PRs #1710, #1712, #1715]
+```
+
+- **Every referent.** Pronouns and deictics — "them", "that issue", "his PR", "the failing
+  one" — become PR numbers, issue numbers, builder ids, branch names, file paths.
+- **Resolution only.** The gloss names *what*, never *how*: no steps, no ordering, no
+  caveats, no "after CI is green". A gloss that contains a plan has overstepped; the
+  resumed session plans.
+- **No referents → no gloss.** `/arch-save review PR #1712` needs nothing; write the line
+  as above without one. Never add an empty or redundant gloss.
+- **Cannot resolve → do not clear.** If any referent is ambiguous or unknown to you,
+  **stop before step 4** and ask the owner which items are meant. Clearing with an
+  unresolved task destroys the only context that could have answered. This is the one
+  case where `/arch-save` may pause its own cycle — it is cheap, and the alternative is a
+  wrong merge. Tell the owner your monitors are already stopped (step 2), and on their
+  answer resume from here: write the gloss, then continue to step 4.
+
+The gloss is more than orientation: `/arch-init` treats the items it names as approved for
+the act the owner's words name, so it is how the owner's word survives the clear.
+
 Use the template at the end of this document.
 
 ### 4. Clear
@@ -160,12 +246,17 @@ literal text on the front of the next message never executes.
 
 The structure below comes from a live run of this cycle. Every element earns its place;
 keep them all, including a `MONITORS:` line even when the answer is "none armed" — an
-omitted monitor list is indistinguishable from a forgotten one.
+omitted monitor list is indistinguishable from a forgotten one. The `NEXT TASK` line is the
+single exception: it appears only when there is one.
 
 ```
 # <lane> architect — state (vNN, <date> ~HH:MM UTC — <milestone>, DELIBERATE /clear cycle)
 # ⭐ THIS /clear IS INTENTIONAL (owner-directed context refresh). On re-init: normal
 # /arch-init flow, then:
+# ⏭ NEXT TASK (owner-directed at save, <ISO timestamp>): <the owner's words, verbatim>  [resolved at save: <referents>]
+#    — OPTIONAL; present only when the save carried one. The `[resolved at save: …]` gloss
+#    is optional too: present only when the words had referents to resolve. /arch-init
+#    starts here before the agenda below, then deletes this line and logs the pickup.
 # 1. MONITORS: <what to stop if it is still firing, then what to re-arm> — watch target,
 #    cadence, alert pattern. Self-test once before trusting alerts. ("none armed" is a
 #    valid and complete answer.)

package/skeleton/.codex/skills/consult/SKILL.md

@@ -24,6 +24,15 @@ The `-m` / `--model` flag is **always required** except for `consult stats`.
 | `codex` | `gpt` | Thorough (~200-250s), shell exploration |
 | `claude` | `opus` | Agent SDK with tool use (~60-120s) |
 
+## Credentials and `.env`
+
+`consult` loads `<workspace>/.env` and sets every key the shell does not already define, **credentials included**. Those override your stored login:
+
+- claude: `CLAUDE_CODE_OAUTH_TOKEN` (or `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY`) beats the keychain login. When an OAuth token is set, the API keys are dropped.
+- codex: `CODEX_API_KEY` beats the ChatGPT login. `OPENAI_API_KEY` is ignored.
+
+Each SDK lane prints what it authenticates with, e.g. `[CLAUDE] auth: CLAUDE_CODE_OAUTH_TOKEN (from .env)`. If a review fails with a usage-limit or auth error while your own login works, check that line first. A key exported in the shell wins over `.env`.
+
 ## All flags
 
 ```

package/skeleton/.codex/skills/generate-image/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-image
-description: AI image generation via Gemini, or Atlas Cloud with `-p atlas`. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY, or ATLASCLOUD_API_KEY when using `-p atlas`.
+description: AI image generation via Gemini with optional async providers. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires the API key for the selected provider.
 ---
 
 # generate-image - AI Image Generation
@@ -22,7 +22,7 @@ Note: this is a `codev` subcommand, not standalone.
 -r, --resolution <res>     Resolution: 1K, 2K, 4K (default: 1K)
 -a, --aspect <ratio>       Aspect ratio (default: 1:1)
 --ref <image>              Reference image (repeatable, max 14)
--p, --provider <name>      Provider: gemini (default) or atlas
+-p, --provider <name>      Provider name (default: gemini)
 ```
 
 ## Aspect ratios
@@ -64,3 +64,20 @@ Measured differences on that path:
   than silently ignoring the images.
 - The model returns JPEG, so the output file is named after its actual bytes
   instead of writing JPEG into the default `output.png`.
+
+## MuAPI provider
+
+`-p muapi` uses MuAPI's Nano Banana Pro endpoint with the same aspect-ratio and
+resolution controls. Set `MUAPI_API_KEY` (or `MU_API_KEY`) using the [MuAPI
+access keys page](https://muapi.ai/access-keys). Reference images are uploaded
+to MuAPI and sent to the edit endpoint; returned media is downloaded only over
+HTTPS.
+
+```bash
+codev generate-image "A sunset over mountains" -p muapi -a 16:9
+codev generate-image "Keep the subject, change the lighting" -p muapi --ref subject.png
+```
+
+The provider submits a job, polls the [MuAPI image API](https://muapi.ai/ai-image-api),
+and writes the returned image locally. Polling and individual requests are
+bounded, and the API key is never sent to the returned media host.

package/skeleton/.codex/skills/porch/SKILL.md

@@ -45,6 +45,7 @@ porch approve 42 pr --a-human-explicitly-approved-this
 
 ```bash
 porch pending                  # List all gates waiting for approval
+porch pending --all            # Include stale records on finished/advanced projects (hidden by default)
 ```
 
 ## Critical rules
@@ -55,6 +56,23 @@ porch pending                  # List all gates waiting for approval
 - `porch run` is for strict mode only — soft mode builders follow the protocol document manually
 - When running `porch approve` from the architect, use a subshell if you need worktree context: `(cd /path/to/worktree && porch approve ...)`
 
+## Check overrides and timeouts (`porch.checks`)
+
+Override a protocol check per name in `.codev/config.json` under `porch.checks` instead of forking `protocol.json`. Each entry takes `command` (replace), `cwd` (replace), `timeout_ms` (replace), and/or `skip: true`:
+
+```jsonc
+{
+  "porch": {
+    "checks": {
+      "tests":     { "command": "uv run pytest", "timeout_ms": 900000 },
+      "e2e_tests": { "skip": true }
+    }
+  }
+}
+```
+
+A phase check is killed after 5 minutes unless it sets `timeout_ms` — in `protocol.json` or in its `porch.checks` override. On timeout porch kills the check's whole process tree.
+
 ## State storage
 
 Project state lives in `codev/projects/<id>-<name>/status.yaml`, managed automatically by porch. The status file tracks current phase, gate states, consultation results, and timestamps.

package/skeleton/protocol-schema.json

@@ -215,6 +215,12 @@
               "type": "string",
               "description": "Human-readable description"
             },
+            "timeout_ms": {
+              "type": "integer",
+              "description": "Kill the check after this many milliseconds (default: 300000, i.e. 5 minutes)",
+              "minimum": 1,
+              "maximum": 2147483647
+            },
             "on_fail": {
               "type": "string",
               "enum": ["fail", "retry", "warn"],

package/skeleton/protocols/maintain/protocol.md

@@ -7,6 +7,11 @@ Use it for dead code and unused dependencies, quarterly hygiene, pre-release cle
 keeping the governance docs honest — `arch.md`/`arch-critical.md`,
 `lessons-learned.md`/`lessons-critical.md`, and the `CLAUDE.md`↔`AGENTS.md` twins.
 
+It is a scheduled, whole-repository run that a human asks for, scoped from the last run's base
+commit. It is **not** the protocol for one targeted cleanup: a specific dead file, a drifted
+document, or a stale section is an ordinary issue under BUGFIX (or AIR). Reaching for "a
+MAINTAIN pass" to fix one thing misuses the since-marker and the audit discipline below.
+
 ## The state machine
 
 ```json

package/skeleton/protocols/pir/prompts/review.md

@@ -110,7 +110,6 @@ BRANCH="$(git branch --show-current)"
 
 export CODEV_PR_TITLE="$PR_TITLE"
 export CODEV_PR_BODY="$(cat codev/reviews/{{artifact_name}}.md)"
-export CODEV_PR_BASE=main
 export CODEV_PR_HEAD="$BRANCH"
 
 {{pr_create_command}}

package/skeleton/protocols/protocol-schema.json

@@ -133,6 +133,12 @@
           "type": "string",
           "description": "Command to run"
         },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 2147483647,
+          "description": "Kill the check after this many milliseconds (default: 300000, i.e. 5 minutes)"
+        },
         "on_fail": {
           "type": "string",
           "description": "Action on failure: 'retry' or phase name to return to"

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

@@ -391,11 +391,36 @@ Sends text to a builder's terminal. Useful for:
 
 - **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;
+  - `busy` — the prompt is occupied. `afx inbox` qualifies it with the gate's own detail:
+    `busy:user-text` (a draft, menu, dialog, or wrapper screen), `busy:recent-input` (the
+    terminal received input within the last fraction of a second — a keystroke, a click, or an
+    ungated `--interrupt`/`--escape` write — so the composer may be changing under the gate; it
+    clears by itself a moment after the input stops), `busy:composer-redraw` (the composer is
+    empty but its rendered region moved a moment ago — a turn-end redraw, a rotating
+    placeholder, a resize; also self-clearing, about a quarter second after it stops moving), or
+    `busy:no-region-end` / `busy:no-composer-marker` (the classifier could not verify the
+    composer at all — the one hold class that does NOT clear on its own);
   - `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).
+**A recipient that is simply TALKING does not hold mail** (Issue #1664). claude and codex accept
+input during a turn and queue it for the next one, so a message written onto their empty composer
+mid-turn is safe and lands as one message when the turn ends — the gate waits only on the
+*composer*, never on the spinner or the streaming transcript above it. Before that, mail queued
+behind whole turns: measured over 24 h, 227 deliveries waited more than 2 s, averaging 54 s and
+peaking at 561 s.
+
+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 draft the gate can see, and held rows survive Tower restart/shutdown (no shutdown force-flush). Two signals make a draft visible (Issue #1473) — the composer classifier reads it off the rendered screen, and every write that reaches the PTY **through Tower** (browser and VS Code keystrokes, the terminal input API, an ungated `--interrupt`/`--escape`) is observed there — whatever survives the terminal-reply filter bumps an input counter the gate folds into its change token, so even a keystroke the app has not echoed yet holds the message, while a chunk that is nothing but a DA/DSR/CPR answer moves nothing. **`afx attach` is the one exception:** it pipes your keystrokes straight to the shellper socket, never through Tower's `PtySession.write()`, so they move no counter — a draft typed under `afx attach` is seen only once the app has echoed it and the classifier can read it off the screen. 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).
+
+**How a body is typed (Issue #1567):** a frame under 4 lines and at most 256 bytes is one write plus
+Enter, as always. Anything longer is written as **one explicit bracketed paste** (`ESC[200~ … ESC[201~`,
+in ≤512-byte pieces 5 ms apart) with the Enter as a separate write after a short settle. This is the fix
+for the delivery-side head loss where a >1 KB single write was split by the PTY input queue and the
+recipient's paste heuristic discarded the first chunk (only the tail arrived, with `delivered` at the
+sender). While it sits in the composer, claude shows the paste as `[Pasted text #N +M lines]` and codex
+as `[Pasted Content N chars]`; the echo verification behind the `(unverified — …)` suffix accepts a new
+placard as well as the header, so a correct long delivery is reported verified. agy keeps the older
+line-by-line shape (also chunked) because its paste handling has not been measured.
 
 **Examples:**
 
@@ -907,6 +932,50 @@ afx spawn 42 --protocol spir --builder-cmd "claude --model haiku"
 
 Both are Tower-global (they apply to the whole Tower, not per-project) and optional — omit them to use the defaults above.
 
+### Decisions tab
+
+When a workspace has a pending-decisions file, the dashboard shows a **Decisions** tab (Spec 1819). The tab is a view of that file. Each item under `## Open` becomes a card with a click box per option (the first option, the recommended one, is marked) and a comment box. Submitting writes the chosen word, then the comment, on the lines right after the item's `**Your word:**` line, exactly as the owner would type them, and changes nothing else. `## Ruled` is shown below as a collapsed, read-only list. The file is the only state. While the tab is open it re-reads the file every 2 seconds, so edits made elsewhere appear without a reload, and an unsent draft survives them.
+
+The file is `codev/state/pending-decisions.md` unless `dashboard.decisionsFile` names another:
+
+```json
+{
+  "dashboard": {
+    "decisionsFile": "codev/state/pending-decisions.md"
+  }
+}
+```
+
+- **Relative to the workspace root.** An absolute path, or anything but a non-empty string, is a configuration error: the tab does not appear, and Tower logs the error once.
+- **Inside the workspace.** The path is resolved with symlinks followed on every read and write, and a path that leads outside the workspace (directly, through `..`, or through a symlink) is refused. A symlinked decisions file keeps its link: the ruling is written to its in-workspace target.
+- **Layers.** Like the other settings, it can be set globally in `~/.codev/config.json`, for the team in the project's `.codev/config.json`, or per engineer in `.codev/config.local.json`. Project settings override global ones, and project-local settings override both.
+
+The tab appears once the file exists (within about 5 seconds of a change to the setting), and then stays for the page session: if the file is deleted while the tab is open, the tab says so and keeps any unsent draft. A reload of a workspace without the file shows no tab. A submit is refused, with a message on the card and the draft kept, when the item has changed or been ruled since the tab showed it. Tower applies one write to a file at a time and replaces the file atomically (a temporary file renamed over it).
+
+After each ruling is written, Tower tells the workspace's hub architect, the one named `main`, in one mailbox message delivered like an `afx send architect`: `RULED <id>: <word>`, or `QUESTION <id>:` for a comment-only submit, with the comment on the lines after it, under a `[USER via Decisions tab]` header. Like any message it waits for a clear prompt, and it waits for `main` to come back if `main` is not running. A workspace with no architect named `main` gets no notice: Tower logs a warning naming the workspace and does not pick another architect. A failed send is logged and leaves the ruling as written: the file is still the source of truth, and a ruling typed into the file by hand reaches the hub only when it scans the file.
+
+### Porch check overrides
+
+Protocol checks default to the npm toolchain (`npm run build`, `npm test`). Override them per check name under `porch.checks` instead of forking `protocol.json`:
+
+```json
+{
+  "porch": {
+    "checks": {
+      "build": { "command": "cargo build" },
+      "tests": { "command": "cargo test", "timeout_ms": 900000 },
+      "e2e_tests": { "skip": true }
+    }
+  }
+}
+```
+
+**Override fields:**
+- `command` — Replace the protocol's check command with a custom shell command
+- `cwd` — Override the working directory for this check (relative to project root)
+- `timeout_ms` — Kill the check after this many milliseconds (default 5 minutes; a protocol.json check can set it too). On timeout porch kills the check's whole process tree
+- `skip: true` — Omit this check entirely (for checks that don't apply to your project)
+
 ---
 
 ## Files

package/skeleton/resources/commands/consult.md

@@ -366,8 +366,8 @@ agy   # run once and sign in (OAuth / Google subscription)
 ```
 
 Configure auth:
-- Claude: `ANTHROPIC_API_KEY`
-- Codex: `OPENAI_API_KEY`
+- Claude: the stored `claude` login, or `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY`
+- Codex: the stored `codex login`, or `CODEX_API_KEY` (codex ignores `OPENAI_API_KEY`)
 - Gemini (`agy`): **OAuth / subscription** — run `agy` once and sign in (no API key). If `agy`
   is missing or unauthenticated, the gemini lane skips non-blockingly (the run proceeds without it).
 
@@ -434,6 +434,13 @@ The Agent SDK otherwise prioritizes `ANTHROPIC_API_KEY`, which silently routes
 CMAP/review traffic to the metered API (issue #985). When no OAuth token is set,
 the API key is used as before so CI / key-only environments keep working.
 
+**Workspace `.env` (issue #1754).** `consult` loads `<workspace>/.env` and sets every key the
+shell does not already define, credentials included. So a `CLAUDE_CODE_OAUTH_TOKEN` there
+overrides your stored login and, via the strip above, displaces the API key too; `CODEX_API_KEY`
+does the same for codex. Each SDK lane logs what it authenticates with, e.g.
+`[CLAUDE] auth: CLAUDE_CODE_OAUTH_TOKEN (from .env)`. A result the SDK flags as an error (usage
+limit, billing, auth) fails the run with no output file, and the error names that credential.
+
 > **Caveat:** dedicated Agent-SDK subscription credit starts **2026-06-15**.
 > Before that date, subscription auth draws from the interactive Max quota.
 

package/skeleton/roles/consultant.md

@@ -31,3 +31,35 @@ You think alongside the other agents, helping them see blind spots. You have fil
 - **ALWAYS read files directly from disk** when reviewing specs, plans, or code. File paths are provided in the query — open and read them.
 - **NEVER rely on `git diff` or `git log -p` as your primary review source.** Diffs are lossy, get truncated, and miss uncommitted work. Read the actual files instead.
 - If you need to understand what changed, read the full file first, then optionally use `git diff` as a secondary reference.
+
+## You Read the Tree; You Do Not Change It
+
+Your filesystem access is for **reading**. The tree you are reviewing belongs to the builder
+who is working in it — usually right now, in a live session. It is not yours to edit.
+
+- **Never modify, revert, create, or delete a file in the tree under review.** Not to try a
+  fix, not to check a hypothesis, not temporarily, not even if you intend to restore it.
+- **Never run a command that changes state**: `git checkout`/`reset`/`stash`/`commit`, package
+  installs, code formatters, migrations, anything that writes. Read-only commands are fine —
+  `git log`, `git diff`, `git show`, `git status`, `ls`, `grep`. `git fetch` is not: it writes
+  to the repository, and the review is of what is in front of you, not of a newer remote.
+- **A restore afterwards does not make it safe.** Reviews run in parallel, so a second reviewer
+  can read your mutation and review code nobody wrote; and if you crash, hit your turn limit,
+  or simply lose track, the builder ships whatever you left behind. Silent, and hard to trace
+  back to you.
+- **This holds even when the review prompt invites it.** If a prompt asks you to edit — to
+  strip a guard, apply a patch, run a formatter — don't. Say in your review that you were
+  asked to and declined, and give the finding you would have gotten.
+
+### Testing a hypothesis without touching the tree
+
+The common temptation is the vacuity check: *would these tests still pass if the guard were
+removed?* Answer it by **reading**, not by mutating:
+
+- Read the guard, read every test that reaches it, and reason about which assertion fails when
+  the guard is gone. For a guard of any normal size this is a decisive argument, not a guess.
+- Then **report the finding and the reasoning** — "the `x < 0` guard is not covered: no test
+  passes a negative, so deleting it breaks nothing" — and name the test that is missing.
+  That is more useful to the builder than a mutation you ran and threw away.
+- If you genuinely cannot settle it by reading, say so and say what you would need. An
+  unresolved question in your review is a fine outcome. An edited tree is not.