@cluesmith/codev 3.2.4 → 3.3.0

package/dist/terminal/shellper-replay-buffer.js

@@ -2,56 +2,126 @@
  * Standalone replay buffer for the shellper process.
  *
  * Unlike RingBuffer (which stores lines), this stores raw byte chunks
- * to preserve exact terminal output including escape sequences. It tracks
- * the total bytes stored and evicts oldest chunks when the limit is exceeded.
+ * to preserve exact terminal output including escape sequences. It evicts
+ * the oldest chunks when either the line or the byte ceiling is exceeded;
+ * both ceilings are needed, because a full-screen TUI emits almost no
+ * newlines and so is bounded only by the byte one (#1205).
  *
  * This module has NO dependencies beyond Node.js built-ins so the shellper
  * process doesn't need to pull in the full package dependency tree.
+ * (shellper-protocol.ts is a sibling module under the same constraint.)
  */
+import { REPLAY_PAYLOAD_MAX } from './shellper-protocol.js';
+/**
+ * Byte ceiling on what this buffer retains (#1205). Until it existed the buffer
+ * was bounded only by line count, and a full-screen TUI (which redraws in place
+ * and emits almost no newlines) grew it without limit for the life of the
+ * session — multi-GB in the field.
+ *
+ * Derived from REPLAY_PAYLOAD_MAX rather than written as its own literal, and
+ * that derivation is the point: every send is capped at REPLAY_PAYLOAD_MAX and
+ * ShellperProcess.getReplayData() has no production callers, so it is provably
+ * the most that can ever leave the process. Bytes retained above it are
+ * unreadable by any consumer and are pure resident cost. Tying the two together
+ * keeps that true if the send cap ever moves — retaining more than can be sent
+ * would be waste, retaining less would make the send cap unreachable.
+ *
+ * This is a retention policy, not a wire constraint, which is why it lives here
+ * next to the buffer rather than in shellper-protocol.ts.
+ */
+export const REPLAY_BUFFER_MAX_BYTES = REPLAY_PAYLOAD_MAX;
+const ESC = 0x1b;
+/**
+ * How far past a byte-driven trim point we scan looking for an ESC to align to.
+ * Bounded so alignment can never turn into a long scan over ESC-free data.
+ */
+const ESC_ALIGN_SCAN_LIMIT = 4096;
+/**
+ * Nudge a trim offset forward to the next ESC byte, so a cut doesn't land in
+ * the middle of an escape sequence and leave the client rendering its tail as
+ * literal garbage. Returns `offset` unchanged when no ESC is within the scan
+ * window, which is the correct fallback: a raw cut is what we'd have done
+ * anyway, and the post-connect repaint nudge covers the rest.
+ *
+ * Only byte-driven cuts need this. A newline-driven cut lands just past a
+ * `\n`, which can never appear inside an escape sequence, so it is already
+ * safe and aligning it would discard content for nothing.
+ */
+function alignToEscape(buf, offset) {
+    const limit = Math.min(buf.length, offset + ESC_ALIGN_SCAN_LIMIT);
+    for (let i = offset; i < limit; i++) {
+        if (buf[i] === ESC)
+            return i;
+    }
+    return offset;
+}
+function countNewlines(buf) {
+    let count = 0;
+    for (let i = 0; i < buf.length; i++) {
+        if (buf[i] === 0x0a)
+            count++;
+    }
+    return count;
+}
 export class ShellperReplayBuffer {
     chunks = [];
     totalBytes = 0;
     maxLines;
+    maxBytes;
     lineCount = 0;
     /**
      * @param maxLines Maximum number of lines to retain. Lines are delimited
      *   by newline characters in the raw data stream.
+     * @param maxBytes Maximum bytes to retain. Required because `maxLines` alone
+     *   does not bound anything for a full-screen TUI: such an app redraws in
+     *   place via cursor addressing and emits almost no newlines, so the line
+     *   ceiling never fires and the buffer grows for the life of the session
+     *   (#1205). Defaults to REPLAY_BUFFER_MAX_BYTES.
      */
-    constructor(maxLines = 10_000) {
+    constructor(maxLines = 10_000, maxBytes = REPLAY_BUFFER_MAX_BYTES) {
         this.maxLines = maxLines;
+        this.maxBytes = maxBytes;
     }
     /**
      * Append raw PTY output data to the buffer.
-     * Evicts oldest chunks if the line count exceeds maxLines.
+     * Evicts oldest chunks if either the line or the byte ceiling is exceeded.
      */
     append(data) {
         const buf = typeof data === 'string' ? Buffer.from(data, 'utf-8') : data;
         if (buf.length === 0)
             return;
-        // Count newlines in this chunk
-        let newLines = 0;
-        for (let i = 0; i < buf.length; i++) {
-            if (buf[i] === 0x0a)
-                newLines++;
-        }
         this.chunks.push(buf);
         this.totalBytes += buf.length;
-        this.lineCount += newLines;
-        // Evict oldest chunks if we've exceeded the line limit
-        while (this.lineCount > this.maxLines && this.chunks.length > 1) {
+        this.lineCount += countNewlines(buf);
+        this.evict();
+    }
+    /**
+     * Drop the oldest data until both ceilings are satisfied.
+     *
+     * Trimming from the front can cut mid-escape-sequence or discard an
+     * alt-screen-enter, which is why it was rejected in #1047. It is accepted
+     * here because every layer above already does exactly this (the send cap,
+     * the ring seed, the frame-skip path) and relies on the client's
+     * post-connect repaint nudge; an unbounded buffer, by contrast, killed
+     * sessions. Byte-driven cuts are ESC-aligned to narrow the window in which
+     * a client renders a truncated sequence as literal text.
+     */
+    evict() {
+        while ((this.lineCount > this.maxLines || this.totalBytes > this.maxBytes) &&
+            this.chunks.length > 1) {
             const oldest = this.chunks[0];
-            let removedLines = 0;
-            for (let i = 0; i < oldest.length; i++) {
-                if (oldest[i] === 0x0a)
-                    removedLines++;
-            }
             this.chunks.shift();
             this.totalBytes -= oldest.length;
-            this.lineCount -= removedLines;
+            this.lineCount -= countNewlines(oldest);
         }
-        // Handle edge case: single chunk exceeds line limit.
-        // Trim from the front to keep only the last maxLines lines.
-        if (this.lineCount > this.maxLines && this.chunks.length === 1) {
+        // A single remaining chunk can still exceed either ceiling on its own.
+        if (this.chunks.length !== 1)
+            return;
+        // Line ceiling: cut just past the newline that leaves maxLines behind.
+        // A newline never appears inside an escape sequence, so this cut is
+        // inherently safe and must not be ESC-aligned (that would discard content
+        // for no benefit).
+        if (this.lineCount > this.maxLines) {
             const chunk = this.chunks[0];
             let linesToSkip = this.lineCount - this.maxLines;
             let offset = 0;
@@ -60,21 +130,87 @@ export class ShellperReplayBuffer {
                     linesToSkip--;
                 offset++;
             }
-            this.chunks[0] = chunk.subarray(offset);
-            this.totalBytes = this.chunks[0].length;
-            this.lineCount = this.maxLines;
+            this.replaceSoleChunk(chunk.subarray(offset));
+        }
+        // Byte ceiling: keep the tail. This cut can land anywhere, so align it.
+        const chunk = this.chunks[0];
+        if (chunk.length > this.maxBytes) {
+            this.replaceSoleChunk(chunk.subarray(alignToEscape(chunk, chunk.length - this.maxBytes)));
         }
     }
     /**
-     * Get all buffered data as a single concatenated Buffer.
-     * Used for the REPLAY frame on reconnection.
+     * Replace the only chunk with a trimmed version of itself.
+     *
+     * Copies rather than retaining the `subarray` view: a view keeps the entire
+     * original allocation alive, so trimming an oversized chunk down to the
+     * ceiling would free none of the memory this class exists to bound. The copy
+     * is at most `maxBytes` and only happens on the rare path where a single
+     * append exceeded a ceiling by itself.
      */
-    getReplayData() {
+    replaceSoleChunk(next) {
+        const owned = Buffer.from(next);
+        this.chunks[0] = owned;
+        this.totalBytes = owned.length;
+        this.lineCount = countNewlines(owned);
+    }
+    /**
+     * Get buffered data as a single Buffer, for the REPLAY frame on reconnection.
+     *
+     * @param maxBytes When given, return at most this many bytes (the most recent
+     *   ones). The tail is collected by walking `chunks` backwards and slicing
+     *   only the boundary chunk, so the allocation is O(maxBytes) rather than
+     *   O(history).
+     *
+     * That distinction is the whole point (#1205). This runs on *every* client
+     * connect, and the caller's cap used to be applied to the result — meaning a
+     * multi-GB buffer allocated a multi-GB copy on top of itself at exactly the
+     * moment a user opened the terminal, then threw almost all of it away. Peak
+     * footprint doubled, and sessions were killed for it. Capping here bounds the
+     * spike regardless of how large the buffer has already grown, which also
+     * makes this correct for a buffer that accumulated before any byte ceiling
+     * existed.
+     */
+    getReplayData(maxBytes) {
         if (this.chunks.length === 0)
             return Buffer.alloc(0);
-        if (this.chunks.length === 1)
-            return this.chunks[0];
-        return Buffer.concat(this.chunks);
+        if (maxBytes === undefined || this.totalBytes <= maxBytes) {
+            // Single-chunk fast path returns the internal Buffer *by reference*
+            // rather than copying. Safe because nothing mutates chunks in place and
+            // callers only read, but it is an aliasing property the old
+            // always-concat version did not have: a caller that mutated the result
+            // would corrupt the buffer. Copy here if that ever stops being true.
+            if (this.chunks.length === 1)
+                return this.chunks[0];
+            return Buffer.concat(this.chunks, this.totalBytes);
+        }
+        if (maxBytes <= 0)
+            return Buffer.alloc(0);
+        const tail = [];
+        let collected = 0;
+        for (let i = this.chunks.length - 1; i >= 0 && collected < maxBytes; i--) {
+            const chunk = this.chunks[i];
+            const remaining = maxBytes - collected;
+            if (chunk.length <= remaining) {
+                tail.push(chunk);
+                collected += chunk.length;
+                continue;
+            }
+            // Boundary chunk: take only its tail, aligned off a mid-sequence cut.
+            //
+            // `break` is load-bearing. ESC alignment moves the cut *forward*, so the
+            // piece is usually shorter than `remaining` — without breaking, the loop
+            // would see spare capacity and keep taking bytes from still-older chunks,
+            // stitching fragments across a gap into what must be one contiguous
+            // suffix. That also re-admits the unaligned mid-sequence prefix this
+            // alignment exists to prevent. Returning fewer than `maxBytes` is the
+            // accepted contract; returning a spliced stream is not.
+            const piece = chunk.subarray(alignToEscape(chunk, chunk.length - remaining));
+            tail.push(piece);
+            collected += piece.length;
+            break;
+        }
+        tail.reverse();
+        return Buffer.concat(tail, collected);
     }
     /** Current number of bytes stored. */
     get size() {

package/dist/terminal/shellper-replay-buffer.js.map

@@ -1 +1 @@
-{"version":3,"file":"shellper-replay-buffer.js","sourceRoot":"","sources":["../../src/terminal/shellper-replay-buffer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"shellper-replay-buffer.js","sourceRoot":"","sources":["../../src/terminal/shellper-replay-buffer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cluesmith/codev",
-  "version": "3.2.4",
+  "version": "3.3.0",
   "description": "Codev CLI - AI-assisted software development framework",
   "type": "module",
   "bin": {
@@ -23,7 +23,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.41",
     "@google/genai": "^1.0.0",
-    "@openai/codex-sdk": "^0.142.5",
+    "@openai/codex-sdk": "^0.146.0",
+    "@xterm/headless": "^6.0.0",
     "better-sqlite3": "^12.10.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
@@ -33,7 +34,8 @@
     "open": "^10.1.0",
     "tree-kill": "^1.2.2",
     "ws": "^8.18.0",
-    "@cluesmith/codev-core": "3.2.4"
+    "@cluesmith/codev-core": "3.3.0",
+    "@cluesmith/codev-sdk": "3.3.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",
@@ -49,7 +51,7 @@
     "typescript": "^6.0.3",
     "vitest": "^4.0.15",
     "@cluesmith/codev-web": "0.0.0",
-    "@cluesmith/codev-types": "3.2.4"
+    "@cluesmith/codev-types": "3.3.0"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -71,8 +73,8 @@
   },
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "pnpm clean && tsc && pnpm build:dashboard && pnpm copy-skeleton",
-    "build:dashboard": "cd ../../apps/web && pnpm build && rm -rf ../../packages/codev/dashboard-dist && cp -r dist ../../packages/codev/dashboard-dist",
+    "build": "pnpm --filter \"@cluesmith/codev^...\" build && pnpm clean && tsc && pnpm copy-dashboard && pnpm copy-skeleton",
+    "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",
     "dev": "tsx src/cli.ts",

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

@@ -144,7 +144,20 @@ afx cron enable <name>          # Enable
 afx cron disable <name>         # Disable
 ```
 
-There is NO `afx cron add` — create YAML files in `.af-cron/` directly.
+There is NO `afx cron add` — create YAML files in `.af-cron/` directly:
+
+```yaml
+name: Service Health Check      # required, unique per workspace
+schedule: "*/15 * * * *"        # required, cron expression (or @hourly/@daily/@startup)
+command: ./health-check.sh      # required, run via shell
+message: "Health alert: ${output}"  # required, ${output} = trimmed command output
+condition: "exitCode != 0"      # optional JS expression, see below
+target: architect               # optional, default architect
+timeout: 30                     # optional, seconds, default 30
+enabled: true                   # optional, default true
+```
+
+`condition` is a JavaScript expression with two variables in scope: `output` (string — the command's trimmed output) and `exitCode` (number — 0 on success, the command's exit code on non-zero exit, 124 on timeout, -1 on spawn failure). With a `condition`, the message is delivered exactly when it evaluates truthy — including on failed runs (e.g. `exitCode != 0` alerts when the command fails). Without a `condition`, the message is delivered only when the command exits 0.
 
 ## Other commands
 

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

@@ -63,7 +63,11 @@ not choose; a state save happens at a boundary **you** pick, with a summary
 **you** curate. That is strictly better, so use it:
 
 ```
-/arch-init (recover) → work → save at a checkpoint → suggest /clear → human /clears → /arch-init → …
+/arch-init (recover) → work → save at a checkpoint → refresh → /arch-init (recover) → …
+                                                       │
+              packaged:  /arch-save  ─────────────────┤  stops monitors, saves, clears,
+                                                       │  schedules /arch-init
+              manual:    suggest /clear → human clears ┘  then human runs /arch-init
 ```
 
 **When to save.** Save at a *resumable boundary* — a point a fresh session
@@ -99,17 +103,26 @@ plus the most recent dated section*, so a save must leave exactly that behind:
 dumps or raw tool output. Include only: current focus, open loops, and the
 instructions a fresh session needs to resume.
 
-**Then — and only then — suggest `/clear`.** Save first, *then* tell the human
-it is a good time to clear. You cannot clear your own context and must never
-decide unilaterally to lose it; keeping the irreversible step behind a human
-keystroke means accepting the suggestion can never lose anything, because the
-save already happened. Make the suggestion **advisory, never nagging**, and
-only right after a save — e.g.:
+**Then — and only then — suggest the refresh.** Save first, *then* tell the
+human it is a good time to clear. You must never decide unilaterally to lose
+your context; keeping the irreversible step behind a human decision means
+accepting the suggestion can never lose anything, because the save already
+happened. Make the suggestion **advisory, never nagging**, and only right
+after a save — e.g.:
 
-> State saved to `codev/state/<name>.md` — good time to `/clear` if this
+> State saved to `codev/state/<name>.md` — good time to refresh if this
 > session is feeling heavy.
 
-Do not repeat it, and do not prompt to `/clear` at any other time.
+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
+(save → human clears → `/arch-init`) stays valid and is the fallback when
+Tower is unavailable.
 
 ## Guardrails (architect-wide; the state file may add more)
 

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

@@ -0,0 +1,183 @@
+---
+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)"
+---
+
+# /arch-save — save state, clear, and come back as yourself
+
+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.
+
+## When NOT to run this
+
+**On the owner's direction, or when the owner runs it themselves.** Do not invoke this
+autonomously mid-task on your own judgement — the irreversible step is a human decision,
+relocated from "press `/clear`" to "invoke `/arch-save`", not removed. If the owner tells
+you to run it, run it; if you think it is time, *suggest* it and wait.
+
+**Only at a resumable boundary** — a gate approval, a PR merge, a completed investigation,
+the end of a long tool-heavy stretch. **Never mid-task.** Nothing here can check that; the
+state file must describe a point a fresh session can resume *from*, not a half-finished
+action. A mid-task snapshot resumes into confusion.
+
+## The procedure
+
+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
+
+If `$ARGUMENTS` is non-empty, that is your name. Otherwise run `afx whoami` and use the
+reported `name` when `type: architect`.
+
+- `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).
+
+**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`.
+
+### 2. Stop your own monitors
+
+Enumerate every monitor, watcher or background task you armed, and stop it.
+
+This is the half that only *you* can do. Monitors are **session-bound, not
+context-bound**: they survive `/clear` and keep firing into a context that cannot evaluate
+their alerts. `pgrep` cannot see them — they are harness background tasks, not shell
+processes — so the instance after the clear has no handle on them. You do. Use it.
+
+### 3. Write the pruned state file
+
+Rewrite `codev/state/<name>.md`. **Pruning is part of the save, not polish afterwards — a
+save that only appends has not done its job.**
+
+- **Rewrite the current-state / open-loops section in place.** Do not accumulate stale
+  "current state" blocks. Never leave two sections with the same heading — a duplicated
+  "How to resume" means you appended where you should have overwritten.
+- **Delete resolved loops outright.** A closed item's record is the log entry, not a
+  lingering line in current state.
+- **Append one short dated entry** for what changed this stretch.
+- **Collapse older entries into one-line summaries that point at durable artifacts** — the
+  merged PRs, closed issues and reviews where the detail actually lives.
+- **Aim for one screen.** If the file has grown past easy reading, prune as part of *this*
+  save rather than leaving it for next time.
+
+**Prune by pointer, never by deletion.** These files are gitignored (`.gitignore:15`), so
+there is no history to recover from — pruned prose is gone for good. Replace detail with a
+pointer to something durable; never delete the only record of something. Copying the file
+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.
+
+Use the template at the end of this document.
+
+### 4. Clear
+
+```bash
+afx send architect:<name> --raw '/clear'
+```
+
+**`architect:<name>`, never bare `architect`.** For a non-builder sender the bare form
+resolves to `main`, or to the first registered architect — so a *sibling* architect
+running this would clear **main's** terminal instead of its own. That destroys the context
+of someone who never asked for anything, and it is one word away from correct.
+
+**`--raw`, never the escape channel.** The escape route writes a bare ESC and discards the
+message body, so `/clear` sent that way delivers an interrupt: the command appears to
+succeed and nothing is cleared.
+
+### 5. Schedule the re-init
+
+```bash
+afx send architect:<name> --delay 15 --raw '/arch-init <name>'
+```
+
+Tower holds this for 15 seconds and then delivers it. It has to come from outside the
+session, because the clear destroys the context that would otherwise send it.
+
+**Tower does not know whether the clear landed** — it waits out a delay, it does not
+observe the result. 15 seconds is a value chosen because it works in practice, not a
+guarantee about the clear's completion. If the timing is wrong the re-init arrives at the
+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.
+
+**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
+the failure is recoverable. Retry the send; if it keeps failing (Tower down, for example),
+tell the owner that the clear is queued with no re-init scheduled, and give them the
+command to send by hand once Tower is back. Ending the turn here is the one way to turn a
+recoverable failure into a cleared session nobody is coming back for.
+
+### 6. Stop
+
+Do not start new work. End your turn so the clear can take effect.
+
+## After the clear
+
+`/arch-init` will read your state file and resume. Two things it should do first, in this
+order:
+
+1. **Reconcile monitors.** You stopped yours in step 2, but treat any alert you cannot
+   account for from the state block's monitor list as **stale** — disregard it, and stop
+   it if you can. An alert from a decommissioned target is indistinguishable from a live
+   one.
+2. **Then re-arm** the monitors the block lists, and let each one **self-test once** before
+   trusting its alerts. A freshly-armed monitor's first alert has been a false positive in
+   practice.
+
+## If `/arch-init` never arrives
+
+Nothing is lost. The state file is on disk, the terminal is alive. Send it by hand:
+
+```bash
+afx send architect:<name> --raw '/arch-init <name>'
+```
+
+This is the recovery the whole design leans on, which is why the cycle can accept imprecise
+timing rather than needing machinery to guarantee it.
+
+**If the clear did not take effect** — you still have your full context and a stray
+`/arch-init` arrived — nothing was destroyed. Check whether `/clear` was submitted as its
+own message rather than merged into another one, and report it; a `/clear` that arrives as
+literal text on the front of the next message never executes.
+
+## State block template
+
+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.
+
+```
+# <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:
+# 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.)
+# 2. DONE pre-clear, with receipts: <PR> MERGED (<sha>, verified on origin/<branch>);
+#    <branch> PUSH-VERIFIED (<sha> local==origin). Distinguish "written" from "verified" —
+#    a cold reader cannot tell.
+# 3. ACTIVE LANES: <builder-id> = <workstream> (<brief file on disk>; <standing rule>).
+#    Name the file, so no instruction lives only in the context being destroyed.
+# 4. LATEST RESULTS: <the decision-relevant numbers>, so the first post-resume decision
+#    needs no archaeology.
+# 5. QUEUED, with ordering: <item> — WAITS for <verdict>; <item> — <when>.
+# 6. ENVELOPE: <standing authorization that survives>; <what expired with the completed
+#    work>.
+```
+
+## Guardrails (architect-wide)
+
+- **Never auto-approve porch gates.** A gate notification is for the human, not you.
+- **Touch only your own builders / spawns / filings.**
+- **Never `cd` into a builder worktree**; use `git -C` and absolute paths.
+- **Stay on the default branch at the workspace root.**

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

@@ -57,3 +57,34 @@ codev doctor
 - `codev init` creates a new directory — use `codev adopt` for existing projects
 - Always run `codev adopt` and `codev update` from the project root
 - `codev update` only updates framework files — it never touches specs/plans/reviews
+
+## Local build and install (this repository)
+
+Test changes locally before publishing. Run from the repository root:
+
+```bash
+pnpm build                  # builds core first, then codev (including dashboard)
+pnpm -w run local-install   # packs both packages, installs globally, restarts Tower
+```
+
+`local-install` (`scripts/local-install.sh`) packs `@cluesmith/codev-core` and
+`@cluesmith/codev`, installs both in a single `npm install -g` (separate installs fail —
+`codev-core` is not on the public registry), restores the executable bit on
+`scripts/forge/**/*.sh` that `pnpm pack` strips, and restarts Tower last. Install runs while
+Tower is up; only the final restart causes downtime. **Do not stop Tower first**, and do not use
+`npm link` / `pnpm link` — it breaks global installs.
+
+`pnpm build` also runs `copy-skeleton`, which copies `codev-skeleton/` into
+`packages/codev/skeleton`. **Tests read that copy**, so after editing anything under
+`codev-skeleton/` you must rebuild before the suite reflects your change.
+
+### Where to run things
+
+- `pnpm install` — repository root (installs all workspace packages)
+- `pnpm build` / `pnpm test` — `packages/codev/`, or `pnpm --filter @cluesmith/codev build`
+- Unit tests `packages/codev/tests/unit/` · E2E `packages/codev/tests/e2e/`
+- Never run npm commands from the repository root unless told to
+
+### Measuring code size
+
+`tokei -e "tests/lib" -e "node_modules" -e ".git" -e ".builders" -e "dist" .`