@cluesmith/codev 3.3.3 → 3.3.4

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:**
 

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.

package/skeleton/templates/AGENTS.md

@@ -134,7 +134,7 @@ Agents within a workspace communicate through `afx send`. Four addressing forms
 | `afx send architect:<name> "msg"` | Explicit per-architect addressing. **Architects (including `main`)**: open address grammar — any architect can address any other architect (sibling-architect messaging). **Builders**: allowed ONLY when `<name>` matches the builder's own spawning architect; mismatches are rejected by Tower's spoofing check. From a builder, this is an explicit form of the affinity routing, NOT an override. | Any sender (with the spoofing constraint above for builders). |
 | `afx send <workspace>:architect "msg"` | Cross-workspace addressing (e.g. `afx send marketmaker:architect "..."`). | Any sender. |
 
-**Send outcomes (delivered vs held)**: `afx send` reports the real first outcome. **delivered** means the message was written to the recipient's prompt after a clean render-gate pass; **held** means the prompt wasn't clear, so the message was persisted in Tower's durable mailbox and delivers automatically once the prompt is clean — with a why-held reason (`busy`, `no-profile`, or `no-live-pty`) and a mailbox id. A held message is never force-injected onto a busy line, so it can't corrupt a half-typed draft, and held rows survive a Tower restart. List held messages with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>`; `afx send --interrupt` is the explicit bypass.
+**Send outcomes (delivered vs held)**: `afx send` reports the real first outcome. **delivered** means the message was written to the recipient's prompt after a clean render-gate pass; **held** means the prompt wasn't clear, so the message was persisted in Tower's durable mailbox and delivers automatically once the prompt is clean — with a why-held reason (`busy`, `no-profile`, or `no-live-pty`) and a mailbox id. A held message is never force-injected onto a busy line, so it can't corrupt a draft the gate can see, and held rows survive a Tower restart. (The gate reads the composer off the rendered screen and counts input through `PtySession.write()`; `afx attach` writes the shellper socket directly, so a draft typed there is seen only once the app echoes it.) List held messages with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>`; `afx send --interrupt` is the explicit bypass.
 
 **Sibling-architect messaging**: when a workspace hosts more than one architect (added via `afx workspace add-architect --name <name>`), sibling architects message each other via the `architect:<name>` form. Example: `main` running `afx send architect:ob-refine "PR-iter-2 feedback ready"` lands on the `ob-refine` architect's terminal. This works because sender = architect bypasses the spoofing check.
 

package/skeleton/templates/CLAUDE.md

@@ -132,7 +132,7 @@ Agents within a workspace communicate through `afx send`. Four addressing forms
 | `afx send architect:<name> "msg"` | Explicit per-architect addressing. **Architects (including `main`)**: open address grammar — any architect can address any other architect (sibling-architect messaging). **Builders**: allowed ONLY when `<name>` matches the builder's own spawning architect; mismatches are rejected by Tower's spoofing check. From a builder, this is an explicit form of the affinity routing, NOT an override. | Any sender (with the spoofing constraint above for builders). |
 | `afx send <workspace>:architect "msg"` | Cross-workspace addressing (e.g. `afx send marketmaker:architect "..."`). | Any sender. |
 
-**Send outcomes (delivered vs held)**: `afx send` reports the real first outcome. **delivered** means the message was written to the recipient's prompt after a clean render-gate pass; **held** means the prompt wasn't clear, so the message was persisted in Tower's durable mailbox and delivers automatically once the prompt is clean — with a why-held reason (`busy`, `no-profile`, or `no-live-pty`) and a mailbox id. A held message is never force-injected onto a busy line, so it can't corrupt a half-typed draft, and held rows survive a Tower restart. List held messages with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>`; `afx send --interrupt` is the explicit bypass.
+**Send outcomes (delivered vs held)**: `afx send` reports the real first outcome. **delivered** means the message was written to the recipient's prompt after a clean render-gate pass; **held** means the prompt wasn't clear, so the message was persisted in Tower's durable mailbox and delivers automatically once the prompt is clean — with a why-held reason (`busy`, `no-profile`, or `no-live-pty`) and a mailbox id. A held message is never force-injected onto a busy line, so it can't corrupt a draft the gate can see, and held rows survive a Tower restart. (The gate reads the composer off the rendered screen and counts input through `PtySession.write()`; `afx attach` writes the shellper socket directly, so a draft typed there is seen only once the app echoes it.) List held messages with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>`; `afx send --interrupt` is the explicit bypass.
 
 **Sibling-architect messaging**: when a workspace hosts more than one architect (added via `afx workspace add-architect --name <name>`), sibling architects message each other via the `architect:<name>` form. Example: `main` running `afx send architect:ob-refine "PR-iter-2 feedback ready"` lands on the `ob-refine` architect's terminal. This works because sender = architect bypasses the spoofing check.