@cluesmith/codev 3.3.0 → 3.3.2

package/dist/terminal/session-screen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-screen.d.ts","sourceRoot":"","sources":["../../src/terminal/session-screen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAOH,OAAO,KAAK,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAcpE,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAS;IAItB,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAMtC;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAOxC;;;;;;;;;;;;;;;;OAgBG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAMjC,0DAA0D;IAC1D,IAAI,IAAI,IAAI,MAAM,CAEjB;IACD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,0FAA0F;IAC1F,OAAO,IAAI,IAAI;CAUhB"}
+{"version":3,"file":"session-screen.d.ts","sourceRoot":"","sources":["../../src/terminal/session-screen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAQH,OAAO,KAAK,EAAE,QAAQ,IAAI,gBAAgB,EAAkB,MAAM,iBAAiB,CAAC;AAsBpF,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAS;IAItB,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAWtC;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAOxC;;;;;;;;;;;;;;;;OAgBG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAMjC;;;;;;;;;;;;;OAaG;IACH,SAAS,IAAI,MAAM;IAKnB;;;;;;;OAOG;IACH,IAAI,UAAU,IAAI,QAAQ,GAAG,WAAW,CAEvC;IAED,0DAA0D;IAC1D,IAAI,IAAI,IAAI,MAAM,CAEjB;IACD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,0FAA0F;IAC1F,OAAO,IAAI,IAAI;CAUhB"}

package/dist/terminal/session-screen.js

@@ -40,19 +40,29 @@
 // and its named exports are not statically analyzable, so a native-node ESM
 // `import { Terminal }` throws "Named export 'Terminal' not found" under the compiled
 // dist (see the identical note in render-gate.ts). Default-import the module object.
+// `@xterm/addon-serialize` ships the same way (same repo and release train).
 import xtermHeadless from '@xterm/headless';
+import xtermSerialize from '@xterm/addon-serialize';
 const { Terminal } = xtermHeadless;
+const { SerializeAddon } = xtermSerialize;
 /**
- * Scrollback retained by the mirror. The gate reads ONLY the current viewport
- * (`viewportY … viewportY + rows`), never scrollback, so this can be modest — it exists
- * only so a transient scroll doesn't momentarily drop viewport lines during reflow. Kept
- * small to bound per-session memory (one Terminal per live session): at ~200 lines it is a
- * few hundred KB even at a wide geometry. The viewport a classify sees is identical for any
- * scrollback ≥ rows, so this never changes a verdict (asserted by the production-path tests).
+ * Scrollback retained by the mirror, now serving two consumers (PIR #1354):
+ *
+ * - The render gate reads ONLY the current viewport (`viewportY … viewportY + rows`),
+ *   never scrollback, and its verdict is identical for any scrollback ≥ rows (asserted
+ *   by the production-path tests) — so for the gate this value is a free variable.
+ * - {@link SessionScreen.serialize} is the viewer-attach replay payload, and its
+ *   scrollback IS the history a reconnecting viewer gets back. 1000 matches the ring
+ *   buffer's default line capacity (`ringBufferLines`), so snapshot replay does not
+ *   regress history depth versus the raw-ring replay it replaces.
+ *
+ * Memory: measured ~509 KB per fully-scrolled 200x50 terminal at 1000 lines (~215 KB
+ * at the previous 200) — the bounded per-session budget the plan commits to.
  */
-const GATE_SCROLLBACK = 200;
+const SCREEN_SCROLLBACK = 1000;
 export class SessionScreen {
     term;
+    serializer;
     _cols;
     _rows;
     // Promise of the most recently issued write's parse completion. `@xterm/headless`
@@ -63,7 +73,12 @@ export class SessionScreen {
     constructor(cols, rows) {
         this._cols = cols;
         this._rows = rows;
-        this.term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: GATE_SCROLLBACK });
+        this.term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: SCREEN_SCROLLBACK });
+        this.serializer = new SerializeAddon();
+        // The addon's typings bind to the full `@xterm/xterm` Terminal; its runtime touches
+        // only the buffer/parser surface the headless build shares (proven by the round-trip
+        // suite), so the declared-type gap is bridged explicitly here.
+        this.term.loadAddon(this.serializer);
     }
     /**
      * Fold one chunk of PTY output into the screen. Called at the session's single output
@@ -112,6 +127,36 @@ export class SessionScreen {
         await this.pending;
         return { term: this.term, cols: this._cols, rows: this._rows };
     }
+    /**
+     * Serialize the current screen state (both buffers, colors/attrs, cursor, alt-screen
+     * mode, plus up to {@link SCREEN_SCROLLBACK} lines of history) back into a terminal
+     * byte stream a client can replay — the O(screen) viewer-attach payload (PIR #1354).
+     *
+     * SYNCHRONOUS by design: it reads whatever is parsed into the grid right now.
+     * Callers wanting a coherent frame must flush first ({@link read}) and must call this
+     * with no intervening `await` afterward — the same no-interleave discipline the render
+     * gate's classifier relies on. `PtySession.replaySnapshot` owns that protocol.
+     *
+     * Throws whatever the addon throws; the caller maps failures to the raw-replay
+     * fallback. After {@link dispose} the term is freed — return '' rather than touching it
+     * (callers treat an empty snapshot for a non-empty session as a fallback signal).
+     */
+    serialize() {
+        if (this.disposed)
+            return '';
+        return this.serializer.serialize({ scrollback: SCREEN_SCROLLBACK });
+    }
+    /**
+     * Which buffer the emulated app is currently in. 'alternate' identifies the
+     * full-screen-TUI case whose delta resume is unservable from the line-based ring
+     * (`RingBuffer.getSince` returns [] for a caught-up client), so the attach path
+     * routes it to {@link serialize} instead. Read without flushing: worst case the
+     * routing decision lags the last few unparsed bytes, and both routes remain correct
+     * (the raw path keeps its client-nudge recovery).
+     */
+    get bufferType() {
+        return this.term.buffer.active.type;
+    }
     /** Current mirror geometry (matches the live session). */
     get cols() {
         return this._cols;

package/dist/terminal/session-screen.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-screen.js","sourceRoot":"","sources":["../../src/terminal/session-screen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,wFAAwF;AACxF,4EAA4E;AAC5E,sFAAsF;AACtF,qFAAqF;AACrF,OAAO,aAAa,MAAM,iBAAiB,CAAC;AAG5C,MAAM,EAAE,QAAQ,EAAE,GAAG,aAAa,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,eAAe,GAAG,GAAG,CAAC;AAS5B,MAAM,OAAO,aAAa;IACP,IAAI,CAAmB;IAChC,KAAK,CAAS;IACd,KAAK,CAAS;IACtB,kFAAkF;IAClF,kFAAkF;IAClF,wFAAwF;IAChF,OAAO,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3C,QAAQ,GAAG,KAAK,CAAC;IAEzB,YAAY,IAAY,EAAE,IAAY;QACpC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,IAAI,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC,CAAC;IAChG,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,IAAY;QACf,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACxF,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,IAAY,EAAE,IAAY;QAC/B,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QAClF,MAAM,IAAI,CAAC,OAAO,CAAC;QACnB,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IACjE,CAAC;IAED,0DAA0D;IAC1D,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IACD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,0FAA0F;IAC1F,OAAO;QACL,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACpB,8FAA8F;QAC9F,kGAAkG;QAClG,+FAA+F;QAC/F,+FAA+F;QAC/F,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IACnC,CAAC;CACF"}
+{"version":3,"file":"session-screen.js","sourceRoot":"","sources":["../../src/terminal/session-screen.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cluesmith/codev",
-  "version": "3.3.0",
+  "version": "3.3.2",
   "description": "Codev CLI - AI-assisted software development framework",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.2.41",
     "@google/genai": "^1.0.0",
     "@openai/codex-sdk": "^0.146.0",
+    "@xterm/addon-serialize": "^0.14.0",
     "@xterm/headless": "^6.0.0",
     "better-sqlite3": "^12.10.0",
     "chalk": "^5.3.0",
@@ -34,24 +35,25 @@
     "open": "^10.1.0",
     "tree-kill": "^1.2.2",
     "ws": "^8.18.0",
-    "@cluesmith/codev-core": "3.3.0",
-    "@cluesmith/codev-sdk": "3.3.0"
+    "@cluesmith/codev-core": "3.3.2",
+    "@cluesmith/codev-sdk": "3.3.2",
+    "@cluesmith/codev-types": "3.3.2"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",
-    "@xterm/xterm": "^5.5.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.1",
     "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.0.18",
+    "@xterm/xterm": "^5.5.0",
     "jsdom": "^28.1.0",
     "playwright": "^1.58.0",
+    "three": "0.160.0",
     "tsx": "^4.19.2",
     "typescript": "^6.0.3",
     "vitest": "^4.0.15",
-    "@cluesmith/codev-web": "0.0.0",
-    "@cluesmith/codev-types": "3.3.0"
+    "@cluesmith/codev-web": "0.0.0"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -73,7 +75,8 @@
   },
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "pnpm --filter \"@cluesmith/codev^...\" build && pnpm clean && tsc && pnpm copy-dashboard && pnpm copy-skeleton",
+    "build": "pnpm --filter \"@cluesmith/codev^...\" build && pnpm clean && tsc && pnpm bundle-assets",
+    "bundle-assets": "pnpm copy-dashboard && pnpm copy-skeleton && node ./scripts/copy-three.mjs",
     "copy-dashboard": "rm -rf dashboard-dist && cp -r ../../apps/web/dist dashboard-dist",
     "dev:dashboard": "cd ../../apps/web && pnpm dev",
     "copy-skeleton": "rm -rf skeleton && cp -r ../../codev-skeleton skeleton",

package/scripts/forge/gitea/pr-view.sh

@@ -1,3 +1,6 @@
 #!/bin/sh
 # Forge concept: pr-view (Gitea via tea CLI)
-exec tea pulls view "$CODEV_PR_NUMBER" --output json
+# Sets `url` to the PR's browser page (`html_url`). Gitea's own `url` field is
+# the API endpoint (would render raw JSON in a browser), so we prefer `html_url`
+# and fall back to the existing `url` only if `html_url` is absent.
+tea pulls view "$CODEV_PR_NUMBER" --output json | jq '.url = (.html_url // .url)'

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

@@ -7,5 +7,5 @@ if [ "$CODEV_INCLUDE_COMMENTS" = "1" ]; then
   exec gh pr view "$CODEV_PR_NUMBER" --comments
 else
   exec gh pr view "$CODEV_PR_NUMBER" \
-    --json title,body,state,author,baseRefName,headRefName,additions,deletions
+    --json title,body,state,url,author,baseRefName,headRefName,additions,deletions
 fi

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

@@ -1,3 +1,6 @@
 #!/bin/sh
 # Forge concept: pr-view (GitLab via glab CLI)
-exec glab mr view "$CODEV_PR_NUMBER" --output json
+# Adds a `url` field mapped from GitLab's `web_url` (the MR's browser page);
+# all other fields glab emits are passed through unchanged. `. + {url: …}` is
+# non-destructive — if `web_url` is absent, `url` is null (optional by contract).
+glab mr view "$CODEV_PR_NUMBER" --output json | jq '. + {url: .web_url}'

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

@@ -69,6 +69,60 @@ afx send 0042 "PR approved, please merge"
 afx send 0585 "check the test output" --file /tmp/test-results.txt
 ```
 
+## afx interrupt
+
+Sends an ESC keystroke to a builder's PTY — the only thing that reaches it **mid-turn**.
+
+```
+afx interrupt <builder>
+```
+
+| Flag | Description |
+|------|-------------|
+| `--no-enter` | Send ESC alone, without the trailing Enter |
+
+A builder chaining foreground waits inside one turn queues every `afx send` unread — including your order
+to stop. ESC ends the turn so the queue processes. Distinct from `afx send --interrupt` (Ctrl+C).
+
+```bash
+afx interrupt 0042
+afx send 0042 "That producer died — stop waiting and report."
+```
+
+## afx refresh
+
+Refreshes a builder's context: save working state → `/clear` → re-orient. Use when a builder's context window
+is exhausted; `afx spawn --resume` reattaches the *same* conversation and does **not** give it a fresh one.
+
+```
+afx refresh <builder>
+```
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Print what would be sent; write nothing to the builder |
+| `--note <text>` | Extra context appended to the re-orientation |
+| `--file <path>` | Append file content (48KB max, read from *your* filesystem) |
+| `--interrupt-first` | ESC before the save request, for a builder already wedged |
+| `--mode <strict\|soft>` | Override mode if it cannot be detected |
+| `--timeout <seconds>` | Wait for the save-state receipt (default 300) |
+| `--min-bytes <n>` | Minimum state-file size to accept (default 1000) |
+| `--quiet-window <ms>` | Terminal silence counting as turn-ended (default 1500) |
+
+Every gate fails safe: if the state file never arrives, carries a stale nonce, is a stub, is still being
+written, or the builder will not go quiet, the command **aborts without clearing** and exits non-zero,
+naming the gate. Requires a harness with in-session context clearing (Claude Code); others abort loudly.
+
+`afx reset` is a deprecated alias: it still works, prints a one-line notice to stderr, and will be removed
+in a future release.
+
+```bash
+afx refresh 0042 --dry-run                # inspect first — touches nothing
+afx refresh 0042
+afx refresh 0042 --note "PR #90 merged while you were mid-phase. Rebase first."
+afx refresh 0042 --interrupt-first        # builder is wedged mid-turn
+```
+
 ## afx cleanup
 
 Removes a builder's worktree and branch after work is done.

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

@@ -107,8 +107,14 @@ guarantee about the clear's completion. If the timing is wrong the re-init arriv
 wrong moment, which costs one manual message (see below) and nothing else. That is the
 whole reason this cycle can be built on a delay rather than on machinery.
 
-Delayed sends are **not persisted** — if Tower restarts inside the window, the message is
-dropped. That is recoverable; see below.
+Delayed sends **are persisted**. The body is written to the durable mailbox at request time
+with a `not_before` timestamp, so Tower keeps no timer for it and a restart inside the window
+does not lose it — the re-init is delivered once the delay passes. The one thing a restart does
+drop is the Ctrl+C nudge of a delayed `--interrupt`, which this cycle does not use.
+
+That removes a failure mode this section used to warn about, but not the need for the recovery
+path below: delivery still waits on an empty prompt, so a re-init can arrive late rather than
+never.
 
 **If this send fails, do not end your turn.** Step 4 queued the `/clear`, but it does not
 take effect until your turn ends — so at this moment you still have your full context and

package/skeleton/.claude/skills/builder-refresh/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: builder-refresh
+description: Refresh a builder's own context at a protocol boundary — save working state, verify it, clear, and re-orient. Use when porch emits a context-refresh task, or the builder is told to "refresh your context" / "run a self-refresh". A builder does not invoke this autonomously mid-task; porch chooses the moment. Counterpart to the architect's /arch-save.
+argument-hint: "(none — porch's refresh task supplies the commands)"
+---
+
+# /builder-refresh — save, clear, and come back knowing where you are
+
+You are a builder that has reached a protocol boundary. Your context can be discarded
+here safely, because everything that matters is already on disk: the spec, the plan,
+`status.yaml`, your thread narrative, and git history. A fresh context re-orients from
+those artifacts rather than from memory.
+
+**The enforcement is in the command, not in this document.** `afx self-refresh` refuses to
+clear on an unverified save, refuses when the re-entry cannot be scheduled, and refuses
+when your worktree has uncommitted tracked changes. This skill sequences the steps and
+explains the judgement calls; it cannot and does not decide whether the clear is safe.
+
+## When NOT to run this
+
+**Porch chooses the moment. You do not.** Run this when porch's refresh task tells you to,
+or when the architect directs it. Do not invoke it mid-task on your own judgement — a
+boundary is a point a fresh context can resume *from*, and a mid-task snapshot resumes into
+confusion.
+
+If you are not at a boundary and think you need a refresh anyway, say so to the architect
+rather than doing it: `afx send architect "..."`.
+
+## The procedure
+
+### 1. Use the commands porch gave you
+
+Porch's refresh task contains the exact two commands for this boundary, including the
+`--boundary` flag. **Run those, verbatim.**
+
+Do not retype them from memory and do not omit the flag. `--boundary` binds the challenge
+to the boundary it was issued at, so a challenge left behind by an aborted refresh cannot
+be used to clear you at a *later* boundary, against a save describing work that has since
+moved on. That guard has been silently disabled twice by an instruction that dropped the
+flag, which is why this document deliberately does not restate the commands.
+
+If you arrived here without a porch task — an architect-directed refresh, say — there is no
+boundary to bind, and the flagless form is correct. Run `afx self-refresh --help` for the
+exact spelling rather than guessing it.
+
+### 2. Write your working state
+
+The first command prints a save request naming a file and a marker line. Write that file.
+
+**The marker must be the FIRST LINE**, reproduced exactly. A save whose nonce appears
+further down is refused — that check exists because echoing the request back into the file
+otherwise passed every gate, and echoing instructions is something agents do by accident.
+
+**Write for a cold reader** — a competent agent that wakes up with your worktree, your
+branch, and no memory of this conversation. Most of your state is already on disk, so do
+not restate the spec or the plan. Carry only what the artifacts do not contain:
+
+- **receipts** — what is done and *verified*, with paths and commit hashes, distinguishing
+  "written" from "verified";
+- **deviations** from the plan, and why;
+- **flaky or skipped tests**, and what you did about them;
+- **deferred work**, and the reason;
+- **standing orders** from the architect you are still bound by, including anything you
+  were told NOT to do;
+- **the next concrete action**.
+
+Pointers, not prose. The save has a minimum size, and it is not a word count to pad — a
+file below it is indistinguishable from a stub. If you genuinely have less than that to
+say, you are probably omitting receipts or standing orders.
+
+### 3. Run the execute command, then stop
+
+The second command verifies your save, writes a re-orientation to disk, schedules your
+re-entry, and clears you — in that order, and only if every step succeeds.
+
+**Then end your turn.** Do not start new work. The clear takes effect when the turn ends.
+
+## If it refuses
+
+Most refusals happen **before** anything destructive, and those leave your context
+untouched. One does not. Read which you got.
+
+### Pre-clear refusals — your context is intact
+
+| Refusal | What it means |
+|---|---|
+| state file missing / too small / wrong nonce | Your save did not satisfy the gate — check the marker is on line 1 |
+| worktree has uncommitted tracked changes | Commit first; a refreshed context re-orients from git, so uncommitted work is invisible to it |
+| Tower is not running, or did not schedule the re-entry | Clearing would strand you, so it refused |
+| challenge missing / already consumed / for a different boundary | Run the begin step again |
+| invalid parameters | A flag is out of range — nothing was read or written |
+| challenge could not be marked consumed | Nothing was cleared, but a re-entry **is** already queued and will arrive; ignore it. Retrying queues a second one |
+
+For any of these: **report it and carry on.**
+
+```bash
+afx send architect "Context refresh refused at <boundary>: <the reason it printed>"
+```
+
+Then run `porch next` for your normal tasks. **The refresh never blocks your work** — the
+boundary is recorded as consumed either way, so a failed refresh costs you some context and
+nothing else.
+
+### `clear-failed` — you cannot assume anything
+
+If the command reports that the clear was attempted but **may still have landed**, do not
+treat that as a pre-clear refusal. Sending `/clear` can succeed on the wire and still report
+an error, so from inside this turn it is genuinely unknown whether your context survives.
+
+- A re-entry message **is** already queued and will arrive shortly. If your context was
+  cleared, that message is your re-orientation. If it was not, the message is harmless and
+  can be ignored.
+- Do not start new work in this state.
+- Tell the architect explicitly that the outcome is ambiguous:
+
+```bash
+afx send architect "Self-refresh clear-failed at <boundary> — clear may or may not have landed; re-entry is queued"
+```
+
+## After the clear
+
+A re-entry message arrives shortly, identifying itself as an automatic context refresh. It
+carries your identity, protocol, project, worktree and branch, and points at
+`.builder-reorient.md` — the full spawn-quality frame, on disk.
+
+It will tell you to run `porch next`. Do that; porch's state is untouched by the clear and
+its next task emission *is* your re-orientation.
+
+**If the re-entry never arrives**, nothing is lost. `.builder-reorient.md` is on disk and
+the architect can send you back with one message. Say so if you notice.
+
+## What this does not do
+
+- It does not write `status.yaml`. Only porch does, and the boundary is already recorded
+  there before you are asked to refresh.
+- It does not decide *whether* to refresh. Porch decided that.
+- It does not retry. A boundary is refreshed at most once, so a refusal means this boundary
+  simply does not get a refresh.

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

@@ -69,6 +69,60 @@ afx send 0042 "PR approved, please merge"
 afx send 0585 "check the test output" --file /tmp/test-results.txt
 ```
 
+## afx interrupt
+
+Sends an ESC keystroke to a builder's PTY — the only thing that reaches it **mid-turn**.
+
+```
+afx interrupt <builder>
+```
+
+| Flag | Description |
+|------|-------------|
+| `--no-enter` | Send ESC alone, without the trailing Enter |
+
+A builder chaining foreground waits inside one turn queues every `afx send` unread — including your order
+to stop. ESC ends the turn so the queue processes. Distinct from `afx send --interrupt` (Ctrl+C).
+
+```bash
+afx interrupt 0042
+afx send 0042 "That producer died — stop waiting and report."
+```
+
+## afx refresh
+
+Refreshes a builder's context: save working state → `/clear` → re-orient. Use when a builder's context window
+is exhausted; `afx spawn --resume` reattaches the *same* conversation and does **not** give it a fresh one.
+
+```
+afx refresh <builder>
+```
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Print what would be sent; write nothing to the builder |
+| `--note <text>` | Extra context appended to the re-orientation |
+| `--file <path>` | Append file content (48KB max, read from *your* filesystem) |
+| `--interrupt-first` | ESC before the save request, for a builder already wedged |
+| `--mode <strict\|soft>` | Override mode if it cannot be detected |
+| `--timeout <seconds>` | Wait for the save-state receipt (default 300) |
+| `--min-bytes <n>` | Minimum state-file size to accept (default 1000) |
+| `--quiet-window <ms>` | Terminal silence counting as turn-ended (default 1500) |
+
+Every gate fails safe: if the state file never arrives, carries a stale nonce, is a stub, is still being
+written, or the builder will not go quiet, the command **aborts without clearing** and exits non-zero,
+naming the gate. Requires a harness with in-session context clearing (Claude Code); others abort loudly.
+
+`afx reset` is a deprecated alias: it still works, prints a one-line notice to stderr, and will be removed
+in a future release.
+
+```bash
+afx refresh 0042 --dry-run                # inspect first — touches nothing
+afx refresh 0042
+afx refresh 0042 --note "PR #90 merged while you were mid-phase. Rebase first."
+afx refresh 0042 --interrupt-first        # builder is wedged mid-turn
+```
+
 ## afx cleanup
 
 Removes a builder's worktree and branch after work is done.

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

@@ -107,8 +107,14 @@ guarantee about the clear's completion. If the timing is wrong the re-init arriv
 wrong moment, which costs one manual message (see below) and nothing else. That is the
 whole reason this cycle can be built on a delay rather than on machinery.
 
-Delayed sends are **not persisted** — if Tower restarts inside the window, the message is
-dropped. That is recoverable; see below.
+Delayed sends **are persisted**. The body is written to the durable mailbox at request time
+with a `not_before` timestamp, so Tower keeps no timer for it and a restart inside the window
+does not lose it — the re-init is delivered once the delay passes. The one thing a restart does
+drop is the Ctrl+C nudge of a delayed `--interrupt`, which this cycle does not use.
+
+That removes a failure mode this section used to warn about, but not the need for the recovery
+path below: delivery still waits on an empty prompt, so a re-init can arrive late rather than
+never.
 
 **If this send fails, do not end your turn.** Step 4 queued the `/clear`, but it does not
 take effect until your turn ends — so at this moment you still have your full context and

package/skeleton/.codex/skills/builder-refresh/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: builder-refresh
+description: Refresh a builder's own context at a protocol boundary — save working state, verify it, clear, and re-orient. Use when porch emits a context-refresh task, or the builder is told to "refresh your context" / "run a self-refresh". A builder does not invoke this autonomously mid-task; porch chooses the moment. Counterpart to the architect's /arch-save.
+argument-hint: "(none — porch's refresh task supplies the commands)"
+---
+
+# /builder-refresh — save, clear, and come back knowing where you are
+
+You are a builder that has reached a protocol boundary. Your context can be discarded
+here safely, because everything that matters is already on disk: the spec, the plan,
+`status.yaml`, your thread narrative, and git history. A fresh context re-orients from
+those artifacts rather than from memory.
+
+**The enforcement is in the command, not in this document.** `afx self-refresh` refuses to
+clear on an unverified save, refuses when the re-entry cannot be scheduled, and refuses
+when your worktree has uncommitted tracked changes. This skill sequences the steps and
+explains the judgement calls; it cannot and does not decide whether the clear is safe.
+
+## When NOT to run this
+
+**Porch chooses the moment. You do not.** Run this when porch's refresh task tells you to,
+or when the architect directs it. Do not invoke it mid-task on your own judgement — a
+boundary is a point a fresh context can resume *from*, and a mid-task snapshot resumes into
+confusion.
+
+If you are not at a boundary and think you need a refresh anyway, say so to the architect
+rather than doing it: `afx send architect "..."`.
+
+## The procedure
+
+### 1. Use the commands porch gave you
+
+Porch's refresh task contains the exact two commands for this boundary, including the
+`--boundary` flag. **Run those, verbatim.**
+
+Do not retype them from memory and do not omit the flag. `--boundary` binds the challenge
+to the boundary it was issued at, so a challenge left behind by an aborted refresh cannot
+be used to clear you at a *later* boundary, against a save describing work that has since
+moved on. That guard has been silently disabled twice by an instruction that dropped the
+flag, which is why this document deliberately does not restate the commands.
+
+If you arrived here without a porch task — an architect-directed refresh, say — there is no
+boundary to bind, and the flagless form is correct. Run `afx self-refresh --help` for the
+exact spelling rather than guessing it.
+
+### 2. Write your working state
+
+The first command prints a save request naming a file and a marker line. Write that file.
+
+**The marker must be the FIRST LINE**, reproduced exactly. A save whose nonce appears
+further down is refused — that check exists because echoing the request back into the file
+otherwise passed every gate, and echoing instructions is something agents do by accident.
+
+**Write for a cold reader** — a competent agent that wakes up with your worktree, your
+branch, and no memory of this conversation. Most of your state is already on disk, so do
+not restate the spec or the plan. Carry only what the artifacts do not contain:
+
+- **receipts** — what is done and *verified*, with paths and commit hashes, distinguishing
+  "written" from "verified";
+- **deviations** from the plan, and why;
+- **flaky or skipped tests**, and what you did about them;
+- **deferred work**, and the reason;
+- **standing orders** from the architect you are still bound by, including anything you
+  were told NOT to do;
+- **the next concrete action**.
+
+Pointers, not prose. The save has a minimum size, and it is not a word count to pad — a
+file below it is indistinguishable from a stub. If you genuinely have less than that to
+say, you are probably omitting receipts or standing orders.
+
+### 3. Run the execute command, then stop
+
+The second command verifies your save, writes a re-orientation to disk, schedules your
+re-entry, and clears you — in that order, and only if every step succeeds.
+
+**Then end your turn.** Do not start new work. The clear takes effect when the turn ends.
+
+## If it refuses
+
+Most refusals happen **before** anything destructive, and those leave your context
+untouched. One does not. Read which you got.
+
+### Pre-clear refusals — your context is intact
+
+| Refusal | What it means |
+|---|---|
+| state file missing / too small / wrong nonce | Your save did not satisfy the gate — check the marker is on line 1 |
+| worktree has uncommitted tracked changes | Commit first; a refreshed context re-orients from git, so uncommitted work is invisible to it |
+| Tower is not running, or did not schedule the re-entry | Clearing would strand you, so it refused |
+| challenge missing / already consumed / for a different boundary | Run the begin step again |
+| invalid parameters | A flag is out of range — nothing was read or written |
+| challenge could not be marked consumed | Nothing was cleared, but a re-entry **is** already queued and will arrive; ignore it. Retrying queues a second one |
+
+For any of these: **report it and carry on.**
+
+```bash
+afx send architect "Context refresh refused at <boundary>: <the reason it printed>"
+```
+
+Then run `porch next` for your normal tasks. **The refresh never blocks your work** — the
+boundary is recorded as consumed either way, so a failed refresh costs you some context and
+nothing else.
+
+### `clear-failed` — you cannot assume anything
+
+If the command reports that the clear was attempted but **may still have landed**, do not
+treat that as a pre-clear refusal. Sending `/clear` can succeed on the wire and still report
+an error, so from inside this turn it is genuinely unknown whether your context survives.
+
+- A re-entry message **is** already queued and will arrive shortly. If your context was
+  cleared, that message is your re-orientation. If it was not, the message is harmless and
+  can be ignored.
+- Do not start new work in this state.
+- Tell the architect explicitly that the outcome is ambiguous:
+
+```bash
+afx send architect "Self-refresh clear-failed at <boundary> — clear may or may not have landed; re-entry is queued"
+```
+
+## After the clear
+
+A re-entry message arrives shortly, identifying itself as an automatic context refresh. It
+carries your identity, protocol, project, worktree and branch, and points at
+`.builder-reorient.md` — the full spawn-quality frame, on disk.
+
+It will tell you to run `porch next`. Do that; porch's state is untouched by the clear and
+its next task emission *is* your re-orientation.
+
+**If the re-entry never arrives**, nothing is lost. `.builder-reorient.md` is on disk and
+the architect can send you back with one message. Say so if you notice.
+
+## What this does not do
+
+- It does not write `status.yaml`. Only porch does, and the boundary is already recorded
+  there before you are asked to refresh.
+- It does not decide *whether* to refresh. Porch decided that.
+- It does not retry. A boundary is refreshed at most once, so a refusal means this boundary
+  simply does not get a refresh.

package/skeleton/protocol-schema.json

@@ -39,6 +39,23 @@
       "description": "Signals that can be emitted during protocol execution",
       "additionalProperties": { "$ref": "#/$defs/signal" }
     },
+    "context_refresh": {
+      "type": "object",
+      "description": "Boundaries at which builders automatically refresh their context (Spec 1470). Absent means no refreshes.",
+      "additionalProperties": false,
+      "properties": {
+        "on_enter": {
+          "type": "array",
+          "description": "Protocol phase ids to refresh on entry to. Each must name a phase this protocol declares.",
+          "uniqueItems": true,
+          "items": { "type": "string" }
+        },
+        "on_plan_phase_advance": {
+          "type": "boolean",
+          "description": "Refresh when advancing from one plan phase to the next. Requires a 'per_plan_phase' phase. Excludes the first plan phase, which coincides with entering the phase itself."
+        }
+      }
+    },
     "phase_completion": {
       "type": "object",
       "description": "Checks run when a plan phase completes",