@cluesmith/codev 3.2.4 → 3.3.1

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.1",
   "description": "Codev CLI - AI-assisted software development framework",
   "type": "module",
   "bin": {
@@ -23,7 +23,9 @@
   "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/addon-serialize": "^0.14.0",
+    "@xterm/headless": "^6.0.0",
     "better-sqlite3": "^12.10.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
@@ -33,23 +35,25 @@
     "open": "^10.1.0",
     "tree-kill": "^1.2.2",
     "ws": "^8.18.0",
-    "@cluesmith/codev-core": "3.2.4"
+    "@cluesmith/codev-core": "3.3.1",
+    "@cluesmith/codev-sdk": "3.3.1",
+    "@cluesmith/codev-types": "3.3.1"
   },
   "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.2.4"
+    "@cluesmith/codev-web": "0.0.0"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -71,8 +75,9 @@
   },
   "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 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",
     "dev": "tsx src/cli.ts",

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.
@@ -144,7 +198,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)