@cluesmith/codev 3.2.3 → 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.3",
+  "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.3"
+    "@cluesmith/codev-core": "3.3.0",
+    "@cluesmith/codev-sdk": "3.3.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",
@@ -46,10 +48,10 @@
     "jsdom": "^28.1.0",
     "playwright": "^1.58.0",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2",
+    "typescript": "^6.0.3",
     "vitest": "^4.0.15",
-    "@cluesmith/codev-types": "3.2.3",
-    "@cluesmith/codev-dashboard": "0.0.0"
+    "@cluesmith/codev-web": "0.0.0",
+    "@cluesmith/codev-types": "3.3.0"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -71,9 +73,9 @@
   },
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "pnpm clean && tsc && pnpm build:dashboard && pnpm copy-skeleton",
-    "build:dashboard": "cd ../dashboard && pnpm build && rm -rf ../../packages/codev/dashboard-dist && cp -r dist ../../packages/codev/dashboard-dist",
-    "dev:dashboard": "cd ../dashboard && pnpm dev",
+    "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",
     "start": "node dist/cli.js",

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

@@ -99,6 +99,19 @@ afx status                      # Show all builders and workspace status
 
 No flags needed. Shows Tower status, workspace, and all active builders.
 
+## afx whoami
+
+```bash
+afx whoami                      # Report this terminal's identity (workspace, type, name)
+afx whoami --json               # Same, as a single JSON object
+```
+
+Resolves identity from Tower/global.db's perspective: builder-worktree cwd
+match first, then the Tower-injected `CODEV_ARCHITECT_NAME` env var. Exits 1
+with an explanation when identity cannot be determined — it never guesses and
+never defaults to `main` (issue #1094). Builders also get an `architect:`
+field naming their spawning architect when recorded. Works without Tower.
+
 ## afx tower
 
 ```bash
@@ -131,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

@@ -0,0 +1,135 @@
+---
+name: arch-init
+description: Adopt an architect identity and recover its state from codev/state/<name>.md. Use when an architect terminal needs to (re)establish which architect it is — after a restart, context loss, or session handoff — or when the user says "/arch-init", "you are the X architect", or "recover your architect state". Identity resolves via `afx whoami` (an explicit name argument overrides); if neither resolves, ask the human — never guess.
+argument-hint: "[name]   (e.g. main; omit to auto-detect via afx whoami)"
+---
+
+# /arch-init — become architect `<name>` and recover state
+
+You are an **architect agent** in a codev workspace. This command tells you
+which architect you are and where your durable state lives, so you can resume
+mid-stream.
+
+`$ARGUMENTS` is the architect name (e.g. `main`, or a sibling architect's
+name in a multi-architect workspace).
+
+## What to do
+
+1. **Resolve your name.**
+   - If `$ARGUMENTS` is non-empty, that is your name — the human named you
+     explicitly, which removes all identity-resolution risk. **Validate it
+     first**: an architect name must match `[a-z][a-z0-9-]*` and be at most
+     64 characters (lowercase letters, digits, hyphens; starts with a
+     letter). Reject anything else — slashes, `..`, uppercase, spaces — and
+     tell the human the rule. Never build a file path from an unvalidated
+     name (path-traversal guard).
+   - If `$ARGUMENTS` is empty, run `afx whoami` and read its output:
+     - `type: architect` → adopt the reported `name`.
+     - `type: builder` → STOP. This terminal is a builder, not an architect;
+       report the mismatch to the human and do not adopt an architect
+       identity.
+     - Non-zero exit (identity unknown) → STOP and ask the human which
+       architect you are. Do NOT guess, and do NOT default to `main` —
+       adopting the wrong identity and writing to another architect's state
+       file is the exact failure this command exists to prevent.
+
+2. **Read your state file: `codev/state/<name>.md`** (relative to the
+   workspace root).
+   - If it does not exist: list the architect state files in `codev/state/`
+     — **excluding `*_thread.md` files**, which are builder thread logs that
+     share the directory — tell the human the file is missing, and ask
+     whether to start a fresh state file for `<name>`. Do not fabricate
+     state.
+   - The state file is authoritative free text. It typically opens with a
+     role banner and may carry resume instructions; follow whatever it says.
+   - Architect state files are per-person and gitignored
+     (`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
+   describes.
+
+## Saving your state (and knowing when to `/clear`)
+
+Recovery is only half the loop. `/arch-init` reads state; **you** write it. The
+state file is not crash insurance — it is your deliberate memory-management
+mechanism. Auto-compaction happens at an arbitrary moment with content you did
+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 → 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
+could pick up cleanly from. Good moments, judged by you: a gate approval, a PR
+merge, a completed investigation, the end of a long tool-heavy stretch.
+**Never save mid-task.** The state file must describe a point you can resume
+*from*, not a half-finished action; a mid-task snapshot resumes into confusion.
+
+**How to save (write format = read format).** Recovery reads *the role banner
+plus the most recent dated section*, so a save must leave exactly that behind:
+
+1. **Rewrite the current-state / open-loops section in place** — overwrite it
+   with where things actually stand now (current focus + open loops + how to
+   resume). Do not accumulate stale "current state" blocks, and never leave two
+   sections with the same heading (a duplicated "How to resume" or "Open loops"
+   means you appended where you should have overwritten). **Delete resolved
+   loops entirely** — a closed item's record is the log entry, not a lingering
+   line in current state.
+2. **Append one short dated log entry** capturing what changed this stretch.
+3. **Compact — this is part of the save, not optional polish.** Every save
+   both adds AND removes: after writing, keep the recent dated log entries in
+   full and collapse older ones into a single one-line summary that names
+   where the detail lives (the closed PRs, issues, and reviews it covered).
+   Remember these state files are gitignored — there is no git history to
+   fall back on, so pruned prose is gone for good. Prune by replacing detail
+   with pointers to durable artifacts, never by deleting the only record of
+   something. The file is a summary a fresh session reads at a glance —
+   one screen is the right order of magnitude, judged by you. If a save has
+   grown it past easy readability, prune as part of that save rather than
+   leaving it for next time.
+
+**Content guardrails.** No secrets (tokens, keys, credentials). No transcript
+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 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 refresh if this
+> session is feeling heavy.
+
+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)
+
+- **Never auto-approve porch gates.** A gate notification is for the human,
+  not you.
+- **Touch only your own builders / spawns / filings.** Sibling architects own
+  theirs.
+- **Never `cd` into a builder worktree**; use `git -C` + absolute paths.
+- **Stay on the default branch at the workspace root**; verify with
+  `git branch` if unsure.