@cluesmith/codev 3.3.3 → 3.3.5

package/dist/terminal/terminal-replies.js

@@ -0,0 +1,181 @@
+/**
+ * Terminal REPLY stripping for the delivery gate's input signal (Issue #1473).
+ *
+ * The render gate needs to know when a HUMAN has put something on a session's line, so a
+ * gated delivery never lands on a composer somebody has started typing into. The only
+ * server-side observation point is {@link PtySession.write}'s external branch — every live
+ * client (the web terminal, the VS Code webview, mobile, the raw
+ * `POST /api/terminals/:id/write` route) funnels through it.
+ *
+ * But that stream is not keystrokes. xterm forwards terminal REPLIES — DA, DSR, CPR,
+ * XTWINOPS, DECRPM, DECRQSS, OSC colour queries, focus reports — through the very same
+ * `onData` event as typed characters, because from the client's point of view they are all
+ * "bytes to send upstream". The web client strips a few of them, but ONLY while
+ * `rc.initialPhase` is true (`Terminal.tsx`) — for a session's entire steady-state life that
+ * filter is off, and the VS Code webview and mobile clients never had one at all. (`afx
+ * attach` is not in scope either way: it writes the shellper socket directly, so neither its
+ * keystrokes nor its replies ever pass through `PtySession.write()` — see arch.md §5.)
+ * Counting a reply as human input would produce a hold with nobody at the keyboard, and
+ * worse, a SELF-TRIP: our own delivery write repaints the TUI, the TUI queries geometry, the
+ * browser answers, and the answer reads as a keystroke that blocks the next delivery. So the
+ * filter is a precondition of the whole design, and it lives here — server-side, where every
+ * client is covered, rather than in one cooperative client.
+ *
+ * SIGNAL-ONLY. Nothing here changes what reaches the PTY: the caller still writes the full
+ * chunk verbatim, because the application ASKED for the reply and blocks waiting on it.
+ * Swallowing a DA reply would hang every attached terminal.
+ *
+ * ## Failure directions
+ *
+ * - **Over-strip** (a real keystroke eaten from the signal) → that keystroke goes uncounted,
+ *   which is exactly today's behaviour, so never a regression — but it silently re-opens the
+ *   race this issue exists to close, which is why the survival tests below are the strict half.
+ * - **Under-strip** (a reply counted as input) → a spurious `busy:recent-input` hold that
+ *   clears on the next settle. Fail-safe, and now visible rather than silent.
+ *
+ * The filter is **chunk-local**: it sees exactly the string one `write()` was handed, so a
+ * reply that arrives split across two calls (a short socket read, a coalescing client) matches
+ * no pattern in either half and is under-stripped. That is the fail-safe direction — a hold
+ * that clears itself a settle later — and it is why no pattern here is written to span calls:
+ * buffering across chunks to catch it would put a real keystroke's arrival at the mercy of the
+ * NEXT chunk, which is the over-strip direction, and that one is silent.
+ *
+ * ## The table is derived from a PINNED dependency
+ *
+ * Every pattern below was read out of `@xterm/xterm@{@link XTERM_REPLY_TABLE_VERSION}`'s
+ * bundle — each `triggerDataEvent` call site that emits a reply rather than a keystroke. A
+ * version bump is therefore a REVIEW TRIGGER for this file: a newly-answered query (kitty
+ * keyboard, XTVERSION) becomes an uncounted-reply hold until its shape is added here. Two
+ * patterns below are pre-emptive for that reason and match nothing stock xterm 5.5 emits.
+ *
+ * ## Case sensitivity is load-bearing
+ *
+ * `ESC[C` is Right-arrow and `ESC[1;5C` is Ctrl-Right. The CSI family pattern keys on a
+ * LOWERCASE final byte set (`c`/`n`/`t`/`y`); an `i` flag on it would strip every arrow key,
+ * Home/End and shift-Tab out of the signal. No pattern here carries `i`, and
+ * `terminal-replies.test.ts` pins the survival of those exact sequences.
+ */
+/**
+ * The `@xterm/xterm` version whose emission sites this table was enumerated from. Bumping the
+ * dependency past it means re-reading its `triggerDataEvent` call sites; a test asserts this
+ * constant against the installed package's version so the bump cannot pass silently.
+ */
+export const XTERM_REPLY_TABLE_VERSION = '5.5.0';
+/**
+ * Sequences a terminal emulator sends UPSTREAM in answer to the application, never as a
+ * human action. Anchored one shape at a time — never a blanket "starts with ESC[" — so a
+ * keystroke can only be eaten by a pattern that names its exact form.
+ *
+ * What each covers, in xterm 5.5.0's own emission order:
+ *
+ *   1. The CSI answer family, keyed on a lowercase final byte:
+ *      - DA1  `ESC[?1;2c`, `ESC[?6c`            (`sendDeviceAttributesPrimary`)
+ *      - DA2  `ESC[>0;276;0c`, `ESC[>85;95;0c`, `ESC[>83;40003;0c`
+ *      - DSR  `ESC[0n`                          (`deviceStatus`, param 5)
+ *      - XTWINOPS `ESC[4;h;wt`, `ESC[6;h;wt`, `ESC[8;rows;colst`
+ *      - DECRPM `ESC[?2004$y`, `ESC[1;2$y`      (`_reportMode`)
+ *      No key sequence xterm can produce ends in `c`, `n`, `t` or `y` — its key finals are
+ *      `~ A B C D F H I O Z R M m`, all outside this class.
+ *   2. CPR `ESC[12;40R` and DECXCPR `ESC[?12;40R` — TWO params, not three. (An earlier
+ *      three-param pattern would have missed both.)
+ *   3. The kitty-keyboard query answer, for a fork that grows one. Its literal `?` is what
+ *      keeps it off real kitty-ENCODED keystrokes, which carry no `?`.
+ *   4. Focus in/out `ESC[I` / `ESC[O`. Stripped deliberately: a focus report cannot change
+ *      composer CONTENT, whereas a click that could carries its own mouse report — which is
+ *      preserved (see below). So this costs no coverage and stops an alt-tab holding mail.
+ *   5. DECRQSS `ESC P 1 $ r … ESC \` (`requestStatusString`).
+ *   6. XTVERSION `ESC P > | … ESC \` — pre-emptive; stock 5.5.0 never answers it.
+ *   7. OSC colour reports `ESC ] 10;rgb:…` / `ESC ] 4;12;rgb:…`, terminated by ST or BEL.
+ *
+ * NOT stripped, on purpose:
+ *
+ *   - **Mouse reports** (`ESC[<0;10;5M`, `ESC[<0;10;5m`, and the X10 `ESC[M` + 3 bytes). These
+ *     are built from a DOM event by the mouse ENCODERS and pushed through the generic data
+ *     path — they are a human ACTION that can change the composer (a click moves the cursor,
+ *     a middle-click pastes, a drag selects), not a parser answer. Stripping them would
+ *     re-open the race for every mouse-driven TUI. Motion tracking can be chatty, but that
+ *     only holds delivery while the mouse is actually moving, and it clears one settle after
+ *     it stops — the fail-safe direction.
+ *   - **Bracketed paste markers** (`ESC[200~` / `ESC[201~`). A paste is human input.
+ *
+ * Content-blind by construction: a reply-SHAPED byte run inside a bracketed paste is stripped
+ * from the signal while the surrounding pasted text still counts. Intended (over-strip is the
+ * safe direction) and pinned by a test.
+ */
+const TERMINAL_REPLY_PATTERNS = [
+    /\x1b\[[?>=]?[0-9;]*\$?[cnty]/g,
+    /\x1b\[\??[0-9]+;[0-9]+R/g,
+    /\x1b\[\?[0-9;]*u/g,
+    /\x1b\[[IO]/g,
+    /\x1bP[0-9]\$r[^\x1b]*\x1b\\/g,
+    /\x1bP>\|[^\x1b]*\x1b\\/g,
+    /\x1b\][0-9;]+;rgb:[0-9a-fA-F/]+(?:\x07|\x1b\\)/g,
+];
+/**
+ * Every recognized terminal reply in `data`, in the order the patterns match them.
+ *
+ * Diagnostics only — {@link stripTerminalReplies} does the real work and never calls this. It
+ * backs the `AF_LOG_INPUT_SIGNAL` trace, whose whole purpose is to let a human SEE which bytes
+ * were treated as a reply and which survived as input, rather than infer it from a hold that
+ * did or did not happen.
+ */
+export function terminalReplyMatches(data) {
+    const found = [];
+    for (const pattern of TERMINAL_REPLY_PATTERNS) {
+        for (const m of data.matchAll(pattern))
+            found.push(m[0]);
+    }
+    return found;
+}
+/**
+ * Render a byte run so it can be read in a log line: ESC as `\e`, other C0 controls and DEL as
+ * `\xNN`, everything else literal.
+ *
+ * Printing raw ESC to a terminal log would make the log itself move the cursor and repaint —
+ * the diagnostic would corrupt the thing it is diagnosing, and the reply bytes under
+ * investigation would be the ones that vanished.
+ */
+export function escapeBytes(data) {
+    let out = '';
+    for (const ch of data) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (ch === '\x1b')
+            out += '\\e';
+        else if (code < 0x20 || code === 0x7f)
+            out += `\\x${code.toString(16).padStart(2, '0')}`;
+        else
+            out += ch;
+    }
+    return out;
+}
+/**
+ * The human-input residue of one upstream chunk: `data` with every recognized terminal reply
+ * removed. Returns `''` when the chunk was nothing but replies — the caller reads that as "no
+ * human input here" and leaves the gate's input signal untouched.
+ *
+ * Pure and allocation-cheap; called on every keystroke, so the common case (plain text with
+ * no ESC at all) short-circuits before touching a regex.
+ *
+ * The short-circuit does NOT cover a bracketed paste: `ESC[200~ … ESC[201~` always contains
+ * ESC, so a pasted body — up to the 1 MiB a `/write` request body may carry — runs every
+ * pattern's `replace` over its full length. This is an EXTERNAL paste only (a human pasting
+ * into the browser terminal, or a caller POSTing one to `/api/terminals/:id/write`); a mail
+ * delivery's own bracketed paste (Issue #1567) is written with origin `'delivery'` and never
+ * reaches this function at all, so no long send pays the scan. Left as is deliberately: an
+ * external paste is a rare, human-paced event next to the per-keystroke path this function is
+ * tuned for, and any length guard cheap enough to be worth adding would have to decide where a
+ * reply may legitimately sit inside the payload — which is the over-strip direction, the
+ * silent one.
+ */
+export function stripTerminalReplies(data) {
+    if (!data.includes('\x1b'))
+        return data;
+    let out = data;
+    for (const pattern of TERMINAL_REPLY_PATTERNS) {
+        out = out.replace(pattern, '');
+        if (out === '')
+            return '';
+    }
+    return out;
+}
+//# sourceMappingURL=terminal-replies.js.map

package/dist/terminal/terminal-replies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-replies.js","sourceRoot":"","sources":["../../src/terminal/terminal-replies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,OAAO,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,uBAAuB,GAAsB;IACjD,+BAA+B;IAC/B,0BAA0B;IAC1B,mBAAmB;IACnB,aAAa;IACb,8BAA8B;IAC9B,yBAAyB;IACzB,iDAAiD;CAClD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,uBAAuB,EAAE,CAAC;QAC9C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,EAAE,KAAK,MAAM;YAAE,GAAG,IAAI,KAAK,CAAC;aAC3B,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,GAAG,IAAI,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;;YACpF,GAAG,IAAI,EAAE,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,OAAO,IAAI,uBAAuB,EAAE,CAAC;QAC9C,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC/B,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cluesmith/codev",
-  "version": "3.3.3",
+  "version": "3.3.5",
   "description": "Codev CLI - AI-assisted software development framework",
   "type": "module",
   "bin": {
@@ -35,9 +35,9 @@
     "open": "^10.1.0",
     "tree-kill": "^1.2.2",
     "ws": "^8.18.0",
-    "@cluesmith/codev-core": "3.3.3",
-    "@cluesmith/codev-sdk": "3.3.3",
-    "@cluesmith/codev-types": "3.3.3"
+    "@cluesmith/codev-core": "3.3.5",
+    "@cluesmith/codev-sdk": "3.3.5",
+    "@cluesmith/codev-types": "3.3.5"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",

package/scripts/forge/github/pr-list.sh

@@ -7,5 +7,9 @@
 # as objects (users carry `login`; teams carry `slug`/`name` and no `login`), so
 # `.login // empty` keeps user reviewers and drops team reviewers — matching the
 # `reviewRequests: string[]` contract in PrListItem (forge-contracts.ts).
-exec gh pr list --json number,title,url,reviewDecision,body,createdAt,author,reviewRequests,isDraft \
-  | jq '[.[] | .reviewRequests = [.reviewRequests[].login // empty]]'
+#
+# Not `gh … | jq`: POSIX sh has no pipefail, so the caller would see jq's exit
+# status and a rate-limited gh would look like a successful empty list (#1645).
+# forge-executable: gh
+out="$(gh pr list --json number,title,url,reviewDecision,body,createdAt,author,reviewRequests,isDraft)" || exit 1
+printf '%s' "$out" | jq '[.[] | .reviewRequests = [.reviewRequests[].login // empty]]'

package/scripts/forge/github/pr-search.sh

@@ -1,7 +1,9 @@
 #!/bin/sh
 # Forge concept: pr-search (GitHub via gh CLI)
 # Input: CODEV_SEARCH_QUERY
-# Output: JSON [{number, headRefName, baseRefName}]
+# Output: JSON [{number, headRefName, baseRefName, state}]
 # --state all is required so the search includes merged/closed PRs; without it
 # `gh pr list` defaults to --state open and post-merge lookups return nothing (#759).
-exec gh pr list --state all --search "$CODEV_SEARCH_QUERY" --json number,headRefName,baseRefName
+# `state` (OPEN/MERGED/CLOSED) lets consumers that only want open PRs filter
+# client-side — the spawn collision guard must ignore merged/closed ones (#1637).
+exec gh pr list --state all --search "$CODEV_SEARCH_QUERY" --json number,headRefName,baseRefName,state

package/scripts/forge/gitlab/issue-search.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-search (GitLab via glab CLI)
+# forge-executable: glab
 #
 # ⚠️ UNVERIFIED — mirrors gitlab/issue-list.sh (raw `glab ... --output json`,
 #    no field normalization) plus a state flag and a `body` field surfaced from

package/scripts/forge/gitlab/pr-search.sh

@@ -1,5 +1,38 @@
 #!/bin/sh
-# Forge concept: pr-search (GitLab via glab CLI)
+# Forge concept: pr-search (GitLab via glab CLI — merge requests)
+# Output: JSON [{number, headRefName, baseRefName, state, ...glab fields}]
+#
+# ⚠️ UNVERIFIED — `glab` is not available in the authoring environment (#920);
+#    written against glab's documented `mr list --output json` shape (confirmed
+#    against the field mappings already documented in gitlab/pr-list.sh and
+#    gitlab/pr-exists.sh). Smoke-test before relying on it.
+#
 # --all is required so the search includes merged/closed MRs; without it
 # `glab mr list` defaults to opened only and post-merge lookups return nothing (#759).
-exec glab mr list --all --search "$CODEV_SEARCH_QUERY" --output json
+#
+# Maps glab's GitLab-shaped fields into the forge-neutral PrSearchItem contract
+# (forge-contracts.ts); `. + {…}` is non-destructive for keys we don't touch:
+#   iid           -> number        (the MR number glab mr view/merge expects)
+#   source_branch -> headRefName
+#   target_branch -> baseRefName
+# Without this the spawn guard's message reads `PR #undefined` and consult's
+# findPRForIssue can't resolve the MR's base branch on GitLab.
+#
+# glab reports state lowercase (opened/merged/closed/locked); normalize to the
+# GitHub convention (OPEN/MERGED/CLOSED) so consumers filter with one comparison.
+# The spawn collision guard keys off state === "OPEN" to ignore merged MRs (#1637).
+# `locked` (a transient merging state) maps to OPEN too: the guard should err
+# toward the recoverable --force prompt, never silently skip a live collision.
+#
+# Not `glab … | jq`: POSIX sh has no pipefail, so the caller would see jq's exit
+# status and a failed glab would look like a successful empty list (#1645).
+# The capture-then-pipe shape hides `glab` from extractExecutable's first-line
+# heuristic (it lands on the `printf` builtin), so declare the backend explicitly
+# — same as github/pr-list.sh (#1645).
+# forge-executable: glab
+out="$(glab mr list --all --search "$CODEV_SEARCH_QUERY" --output json)" || exit 1
+printf '%s' "$out" | jq 'map(.
+  + {number: .iid}
+  + {headRefName: .source_branch}
+  + {baseRefName: .target_branch}
+  + {state: ((.state // "") | ascii_downcase as $s | if $s == "opened" or $s == "locked" then "OPEN" else ($s | ascii_upcase) end)})'

package/scripts/forge/linear/auth-status.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: auth-status (Linear via GraphQL API)
+# forge-executable: curl
 # Output: exit code (0 = authenticated)
 set -e
 

package/scripts/forge/linear/issue-comment.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-comment (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_ISSUE_ID, CODEV_COMMENT_BODY
 # Output: exit code only
 set -e

package/scripts/forge/linear/issue-list.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-list (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_LINEAR_TEAM (team key, e.g. "ENG")
 # Output: JSON [{number, title, url, labels, createdAt, author, assignees}]
 set -e

package/scripts/forge/linear/issue-search.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-search (Linear via GraphQL API)
+# forge-executable: curl
 #
 # ⚠️ UNVERIFIED — mirrors linear/issue-list.sh with `description` added to the
 #    query (mapped to `body`) and the state filter parameterized. No Linear

package/scripts/forge/linear/issue-view.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-view (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_ISSUE_ID (e.g. "ENG-123")
 # Output: JSON {title, body, state, url, author, createdAt, assignees, labels, milestone, comments[]}
 #

package/scripts/forge/linear/recently-closed.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: recently-closed (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_LINEAR_TEAM, CODEV_SINCE_DATE (optional, ISO date)
 # Output: JSON [{number, title, url, labels, createdAt, closedAt}]
 set -e

package/scripts/forge/linear/user-identity.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: user-identity (Linear via GraphQL API)
+# forge-executable: curl
 # Output: plain text display name
 set -e
 

package/skeleton/.claude/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/.claude/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/.claude/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/.claude/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
 
 ```