@cluesmith/codev 3.2.3 → 3.3.0

package/dist/agent-farm/servers/render-gate.js

@@ -0,0 +1,251 @@
+/**
+ * Render-empty gate (Spec 1313, Phase 2) — the sole authority that answers
+ * "is this screen a clean, empty prompt?".
+ *
+ * A message body is only ever written to a prompt this gate proves empty, so
+ * corruption is eliminated by construction: a message can never fuse with a
+ * draft because it is never delivered while one exists. The classifier is a direct
+ * port of the G-lite classifier validated against the real claude/codex TUIs in
+ * spike 1265 (`codev/spikes/1265-poc/exp-g2-glite-prod-path.mjs`).
+ *
+ * WHAT it reads (Spec 1313 render-gate round 2 — capped-ring reconciliation): the gate
+ * classifies a rendered terminal SCREEN via the sync core {@link classifyBuffer}. In
+ * PRODUCTION that screen is the session's persistent bounded mirror (`SessionScreen`,
+ * terminal layer): one long-lived `@xterm/headless` Terminal fed the session's output
+ * incrementally — from birth on the live path — whose current viewport IS the live screen. The gate originally
+ * REBUILT the screen every check by replaying the whole output ring
+ * (`ringBuffer.getAll().join('\n')`) through a throwaway Terminal — but #1205 capped the ring's
+ * newline-free `partial` at 2 MiB (`trimPartial` halves to ~1 MiB), and a claude/codex
+ * alt-screen frame (`\x1b[?1049h`) is exactly one giant newline-free partial. So once a busy
+ * long-lived agent's frame crossed the cap, the gate was handed a TORN front — dropping the
+ * composer marker (→ false `no-composer-marker`) or the composer's lower rule (→ the region
+ * spills into status chrome → false `user-text`) — and held its mail PERMANENTLY. That is the
+ * over-ceiling delivery outage the whole-ring render was meant to eliminate, resurrected one
+ * layer down for exactly the busiest agents. A bounded terminal mirror needs only the live byte
+ * stream, not the whole ring, so the cap is irrelevant, the live-ring tear is gone, each classify is
+ * O(viewport) rather than O(ring size), and the whole-render era's unbounded-`partial` OOM risk
+ * (#1047: one classify allocating a multi-hundred-MB string) is closed. The whole-ring
+ * {@link classifyScreen} entry survives for the fixture suite and any transient one-shot
+ * classify; it shares the SAME classifier core, so the two paths can never diverge.
+ *
+ * Caveat — adopt/reconnect seed: after a Tower restart the mirror is seeded from a bounded replay
+ * tail (`capRingSeed`, 1 MiB), not the live-from-birth stream, so a long-lived alt-screen frame can
+ * be born torn on adopt. That classifies not-clean → the gate HOLDS (fail-safe, never a misdelivery)
+ * and self-heals on the next repaint/viewer nudge. Pre-existing (the pre-round-2 whole-ring gate saw
+ * the same capped seed), not a round-2 regression; tracked as #1361.
+ *
+ * Classifier (fail-toward-not-clean): CLEAN requires
+ *   (a) a recognized composer marker on the screen, AND
+ *   (b) a positively-bounded composer region (a rule/status line BELOW the
+ *       marker — never a scan to the screen bottom), AND
+ *   (c) zero normal-intensity (non-dim), non-whitespace, non-chrome cells in that
+ *       region — with one measured exemption: claude's suggested-command *ghost* cursor
+ *       cell (an inverse, non-dim char at the cursor followed by a non-empty dim run), which
+ *       is composer chrome, not typed text (see `isGhostCursorCell`).
+ * The placeholder-vs-user-text distinction is an SGR attribute — both TUIs
+ * render rotating placeholder/hint text DIM while typed text is normal-intensity
+ * (measured, spike g2) — so no placeholder allowlist is needed. Anything
+ * unrecognized (no marker, no region boundary, a menu, a picker, a draft, a
+ * wrapper/boot screen, or a mirror that has not yet repainted a coherent frame) → NOT clean →
+ * the message stays held. There is no force path.
+ *
+ * Cost (spike g2, @xterm/headless 6.0.0): classifying a rendered viewport is sub-millisecond
+ * (bounded rows × cols, independent of history); the mirror pays a normal terminal-emulator
+ * parse per output chunk — the cost any emulator pays for the byte stream — amortised across
+ * the session instead of spent in a per-check whole-history burst.
+ */
+// `@xterm/headless` resolves to its CommonJS entry (no `exports` map, no
+// `type: module`), and its named exports are not statically analyzable, so a
+// native-node ESM `import { Terminal }` throws "Named export 'Terminal' not
+// found" when the compiled dist runs under node (production; masked under vitest
+// by vite's CJS interop). Default-import the module object — the codebase's
+// convention for CJS deps (cf. `import Database from 'better-sqlite3'`).
+import xtermHeadless from '@xterm/headless';
+const { Terminal } = xtermHeadless;
+/**
+ * Box-drawing / prompt chrome that is never "user text". The composer marker
+ * glyphs (❯ ›) live here too; the marker cell is additionally skipped by
+ * position so a profile whose marker is not listed still never self-trips.
+ */
+const IGNORE_CHARS = new Set(['❯', '›', '│', '▌', '─', '━', '╌', '┄', '╭', '╰', '┌', '└', '']);
+/** All-whitespace (incl. NBSP and other Unicode spaces) → ignorable. */
+const WHITESPACE = /^\s+$/u;
+/** Rendered viewport lines, right-trimmed — the same extraction the spike asserts on. */
+function screenLines(term, rows) {
+    const buf = term.buffer.active;
+    const top = buf.viewportY;
+    const lines = [];
+    for (let i = 0; i < rows; i++) {
+        const line = buf.getLine(top + i);
+        lines.push(line ? line.translateToString(true).trimEnd() : '');
+    }
+    return lines;
+}
+/** Last row index whose text starts with the profile's composer marker, or -1. */
+function findMarkerRow(lines, markerPattern) {
+    let markerRow = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (markerPattern.test(lines[i]))
+            markerRow = i;
+    }
+    return markerRow;
+}
+/**
+ * First region-ending row after the marker (the rule/status line beneath the
+ * composer), or -1 when none is found. -1 means the composer has no proven lower
+ * bound (a partial/mid-repaint frame, or a torn replay) — the caller MUST hold, not
+ * scan to the screen bottom: scanning further counts status chrome below the
+ * composer as user text (the old bug) OR, if that chrome renders empty/dim, returns
+ * a false CLEAN. A missing boundary is indeterminate, and indeterminate is not-clean.
+ */
+function findRegionEnd(lines, markerRow, endPatterns) {
+    for (let i = markerRow + 1; i < lines.length; i++) {
+        if (endPatterns.some((p) => p.test(lines[i])))
+            return i;
+    }
+    return -1;
+}
+/**
+ * Ghost-suggestion cursor cell (Spec 1313 render-gate hardening — false-`busy` on an idle
+ * claude composer). When claude's own last reply mentioned a runnable command it paints
+ * that command into the otherwise-empty composer as a *suggested-command ghost*, and the
+ * ghost's first character doubles as the software block cursor: it is rendered SGR-7
+ * INVERSE at normal intensity while the rest of the ghost is SGR-2 dim
+ * (`❯ ␛[7m a ␛[27m␛[2mfx cleanup …␛[22m`, measured live — captured as
+ * `claude-ghost-suggestion-empty.replay.bin`). The universal dim rule already skips the
+ * ghost body, but the lone inverse cursor cell was counted as user text → the composer
+ * classified `user-text`/`busy` FOREVER while genuinely empty, so mail to an idle
+ * (unattended) agent was never delivered (fail-safe becomes fail-forever for an idle
+ * recipient — the exact agent `afx send` exists to wake).
+ *
+ * This exempts exactly that cell: the cell at the headless buffer's cursor position,
+ * rendered inverse at normal intensity, whose following run on the same row is dim or
+ * empty (the measured ghost tail). It is deliberately NARROW — NOT the blanket inverse
+ * skip the finding warns against — and does not false-clean a real draft:
+ *   - measured, claude renders the block cursor inverse only on the trailing WHITESPACE
+ *     past a real draft (already skipped as whitespace) and never inverse-renders typed
+ *     characters, so a real draft's typed cells are non-inverse and still counted;
+ *   - an inverse *selection* over real multi-char text fails the dim-tail test (its
+ *     following cells are non-dim) and, even if it passed, only this one cell is skipped
+ *     while every other selected cell keeps the verdict `busy`.
+ * A lone inverse cursor cell with NO dim tail (a 1-char draft with the cursor sitting on its
+ * only char, empty composer otherwise) is NOT exempted — it stays `busy` — because the
+ * exemption requires positive ghost evidence (≥1 dim suggestion-body cell). That closes the
+ * false-clean an empty-tail exemption would have opened, honoring the no-new-corruption-vector
+ * / fail-toward-hold invariant (Codex CMAP, 2026-08-06). Real ghosts always carry a multi-char
+ * dim command body (the captured fixture's tail is 23 dim cells), so nothing real is lost.
+ */
+function isGhostCursorCell(line, row, col, cols, cursorRow, cursorCol, cell, probe) {
+    if (row !== cursorRow || col !== cursorCol)
+        return false;
+    if (!cell.isInverse())
+        return false; // typed text is never inverse-rendered; only the software cursor is
+    // Require POSITIVE ghost evidence: at least one dim, non-whitespace, non-chrome cell must
+    // follow on this row (the SGR-2 suggestion body), and EVERY following such cell must be dim.
+    // An empty / whitespace-only tail is NOT a ghost — it is a 1-char draft with the cursor on
+    // its only char, which must stay `busy` (fail-toward-hold; a lone inverse cell is not proof
+    // of a ghost). Any non-dim text to the right ⇒ real content, also not a ghost.
+    let sawDimTail = false;
+    for (let c = col + 1; c < cols; c++) {
+        line.getCell(c, probe);
+        const ch = probe.getChars();
+        if (!ch || WHITESPACE.test(ch) || IGNORE_CHARS.has(ch))
+            continue;
+        if (!probe.isDim())
+            return false;
+        sawDimTail = true;
+    }
+    return sawDimTail;
+}
+/**
+ * The classifier CORE (Spec 1313 render-gate round 2): classify an already-rendered
+ * headless buffer against a profile. Synchronous — it only READS the live buffer, it never
+ * parses — so it is shared, unchanged, by BOTH gate paths: the production persistent-mirror
+ * gate (`SessionScreen.read()` → this) and the transient {@link classifyScreen} (write a
+ * replay into a throwaway term → this). One classifier core means the two paths can never
+ * disagree about what "empty" means.
+ *
+ * Precondition: the caller has already parsed all input into `term` (the mirror flushes in
+ * `read()`; `classifyScreen` awaits its `write`). Having no `await`, a single call is atomic
+ * against concurrent feeds — nothing can mutate the buffer mid-scan.
+ *
+ * Returns `{ clean: true, detail: 'empty' }` only when a composer marker is present and the
+ * composer region carries zero normal-intensity user cells; otherwise
+ * `{ clean: false, reason: 'busy', … }`.
+ */
+export function classifyBuffer(term, cols, rows, profile) {
+    const buf = term.buffer.active;
+    const lines = screenLines(term, rows);
+    const markerRow = findMarkerRow(lines, profile.markerPattern);
+    if (markerRow === -1) {
+        // No composer marker: a wrapper/boot screen, a full-screen picker with no marker, a
+        // mirror that has not yet repainted a coherent frame, or an unrenderable snapshot.
+        // Never clean — the safe direction.
+        return { clean: false, reason: 'busy', detail: 'no-composer-marker' };
+    }
+    const endRow = findRegionEnd(lines, markerRow, profile.regionEndPatterns);
+    if (endRow === -1) {
+        // A marker with no rule/status line beneath it: a partial/mid-repaint frame. The
+        // composer has no proven lower bound, so hold rather than scan into the status chrome
+        // below it (which would either miscount chrome as user text or, if it renders
+        // empty/dim, return a false CLEAN).
+        return { clean: false, reason: 'busy', detail: 'no-region-end' };
+    }
+    const top = buf.viewportY;
+    const cell = buf.getNullCell();
+    const probe = buf.getNullCell(); // scratch cell for the ghost-tail look-ahead (never clobbers `cell`)
+    // Cursor position is viewport-relative (matching `row`, which indexes from `viewportY`).
+    const cursorRow = buf.cursorY;
+    const cursorCol = buf.cursorX;
+    let userCells = 0;
+    for (let row = markerRow; row < endRow; row++) {
+        const line = buf.getLine(top + row);
+        if (!line)
+            continue;
+        for (let col = 0; col < cols; col++) {
+            line.getCell(col, cell);
+            const ch = cell.getChars();
+            if (!ch || WHITESPACE.test(ch) || IGNORE_CHARS.has(ch))
+                continue;
+            if (row === markerRow && col === 0)
+                continue; // the marker glyph itself
+            if (cell.isDim())
+                continue; // placeholder / hint chrome renders dim (claude/codex)
+            if (profile.placeholderFgPalette !== undefined &&
+                cell.isFgPalette() &&
+                cell.getFgColor() === profile.placeholderFgPalette) {
+                continue; // per-app placeholder color: agy renders its idle hint in palette-8 (gray)
+            }
+            if (isGhostCursorCell(line, row, col, cols, cursorRow, cursorCol, cell, probe)) {
+                continue; // claude's suggested-command ghost cursor cell (see isGhostCursorCell)
+            }
+            userCells++;
+        }
+    }
+    return userCells === 0
+        ? { clean: true, detail: 'empty' }
+        : { clean: false, reason: 'busy', detail: 'user-text' };
+}
+/**
+ * Classify a one-shot replay snapshot by rendering it into a THROWAWAY headless terminal
+ * (Spec 1313). The transient path — the fixture suite and any caller holding a replay string
+ * rather than a live mirror. Production instead classifies the session's persistent
+ * {@link SessionScreen} directly via {@link classifyBuffer} (see the module header). Async
+ * because the headless terminal parses its input on a write callback; the shared
+ * {@link classifyBuffer} then does the actual classification.
+ */
+export async function classifyScreen(snapshot, profile) {
+    const { cols, rows } = snapshot;
+    // A throwaway terminal for this single classify. scrollback 2000 is ample for a
+    // whole-replay render; the gate reads only the viewport, so the value never changes the
+    // verdict (the persistent mirror uses a much smaller one for the same reason).
+    const term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 2000 });
+    try {
+        await new Promise((resolve) => term.write(snapshot.replay, resolve));
+        return classifyBuffer(term, cols, rows, profile);
+    }
+    finally {
+        term.dispose();
+    }
+}
+//# sourceMappingURL=render-gate.js.map

package/dist/agent-farm/servers/render-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-gate.js","sourceRoot":"","sources":["../../../src/agent-farm/servers/render-gate.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/servers/session-log-sweep.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Issue #1238: retention for PTY session logs.
+ *
+ * `PtySession` already bounds a *single* session's log (50 MB, one `.1`
+ * rotation — see `../../terminal/pty-session.ts`), but nothing has ever
+ * deleted the log of a session that ended. Every terminal Tower has ever
+ * opened leaves a file behind forever: an audited machine reached 29,728 files
+ * / 19 GB in `~/.agent-farm/logs`, 97% of it untouched for over a month.
+ *
+ * This module adds the missing cross-file policy: a log is deleted once its
+ * last write is older than the retention window. mtime is the retention key
+ * because the last byte written to a session log is, in effect, the moment
+ * that session stopped producing output — the "session ended" signal, without
+ * needing to join against DB session state (which is itself pruned, so dead
+ * sessions leave no row to join against).
+ *
+ * Live sessions are excluded by id regardless of mtime. A session log's fd is
+ * held open for the session's whole life, so unlinking it under a live writer
+ * would silently redirect every subsequent write into an unlinked inode —
+ * losing the log of the one session someone might actually want to read. A
+ * 30-day-idle live session is vanishingly unlikely, but the guard is cheap.
+ *
+ * Wired in `./tower-server.ts` on two triggers (Tower startup, and a daily
+ * in-process timer), mirroring the husk sweep in `./shellper-husk-sweep.ts`.
+ */
+export declare const DEFAULT_LOG_RETENTION_DAYS = 30;
+export declare const DEFAULT_LOG_SWEEP_INTERVAL_MS: number;
+export declare const MS_PER_DAY: number;
+/**
+ * Retention window in days (env `AGENT_FARM_LOG_RETENTION_DAYS`, default 30).
+ * `0` disables the sweep entirely — an explicit "keep everything" opt-out for
+ * anyone who treats these logs as an audit trail.
+ *
+ * NaN-checked rather than `parsed || default` because `0` is a meaningful
+ * override and is falsy in JS (same reasoning as `resolveHuskGraceMs`).
+ */
+export declare function resolveLogRetentionDays(env?: NodeJS.ProcessEnv): number;
+/**
+ * Sweep cadence (env `AGENT_FARM_LOG_SWEEP_INTERVAL_MS`, default 24h). Floored
+ * at 1s so a bad value can't spin the event loop; tests shorten it deliberately.
+ */
+export declare function resolveLogSweepIntervalMs(env?: NodeJS.ProcessEnv): number;
+export interface SessionLogFootprint {
+    /** Number of session log files (including `.log.1` rotations). */
+    files: number;
+    /** Total bytes on disk. */
+    bytes: number;
+    /** mtime of the oldest log, or null when there are none. */
+    oldestMtimeMs: number | null;
+}
+/**
+ * Total footprint of the session log directory. Read-only — used by
+ * `codev doctor` to surface the number the issue was filed about, and by the
+ * sweep's own logging. A missing directory is a healthy zero, not an error.
+ */
+export declare function measureSessionLogs(logDir: string): SessionLogFootprint;
+export interface SweepSessionLogsOptions {
+    /** The session log directory, i.e. `~/.agent-farm/logs`. */
+    logDir: string;
+    /** Age at which a log becomes eligible for deletion. `0` disables the sweep. */
+    retentionMs: number;
+    /**
+     * Ids of sessions that are alive right now. Their logs are never deleted,
+     * however old the mtime looks, because their fd is still open.
+     */
+    activeSessionIds?: Iterable<string>;
+    /** Seam, defaults to `Date.now()`. */
+    now?: number;
+    log?: (msg: string) => void;
+}
+export interface SweepSessionLogsResult {
+    /** Session log files examined. */
+    scanned: number;
+    /** Files unlinked. */
+    deleted: number;
+    /** Bytes reclaimed (sum of the deleted files' sizes). */
+    bytesFreed: number;
+    /** Aged-out files kept because their session is still live. */
+    skippedActive: number;
+    /** Files that were eligible but could not be unlinked. */
+    failed: number;
+}
+/**
+ * Delete session logs whose last write is older than `retentionMs`.
+ *
+ * Never throws: a log directory that can't be read, or an individual file that
+ * can't be stat'd or unlinked, is counted and skipped. Log retention is
+ * janitorial — it must not be able to take Tower's startup path down with it.
+ */
+export declare function sweepSessionLogs(opts: SweepSessionLogsOptions): SweepSessionLogsResult;
+/** Human-readable byte count for log lines and `codev doctor` output. */
+export declare function formatBytes(bytes: number): string;
+//# sourceMappingURL=session-log-sweep.d.ts.map

package/dist/agent-farm/servers/session-log-sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-log-sweep.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/session-log-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,eAAO,MAAM,6BAA6B,QAAsB,CAAC;AAEjE,eAAO,MAAM,UAAU,QAAsB,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAGpF;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAGtF;AAED,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAyBtE;AAED,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpC,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,sBAAsB,CA2DtF;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD"}

package/dist/agent-farm/servers/session-log-sweep.js

@@ -0,0 +1,165 @@
+/**
+ * Issue #1238: retention for PTY session logs.
+ *
+ * `PtySession` already bounds a *single* session's log (50 MB, one `.1`
+ * rotation — see `../../terminal/pty-session.ts`), but nothing has ever
+ * deleted the log of a session that ended. Every terminal Tower has ever
+ * opened leaves a file behind forever: an audited machine reached 29,728 files
+ * / 19 GB in `~/.agent-farm/logs`, 97% of it untouched for over a month.
+ *
+ * This module adds the missing cross-file policy: a log is deleted once its
+ * last write is older than the retention window. mtime is the retention key
+ * because the last byte written to a session log is, in effect, the moment
+ * that session stopped producing output — the "session ended" signal, without
+ * needing to join against DB session state (which is itself pruned, so dead
+ * sessions leave no row to join against).
+ *
+ * Live sessions are excluded by id regardless of mtime. A session log's fd is
+ * held open for the session's whole life, so unlinking it under a live writer
+ * would silently redirect every subsequent write into an unlinked inode —
+ * losing the log of the one session someone might actually want to read. A
+ * 30-day-idle live session is vanishingly unlikely, but the guard is cheap.
+ *
+ * Wired in `./tower-server.ts` on two triggers (Tower startup, and a daily
+ * in-process timer), mirroring the husk sweep in `./shellper-husk-sweep.ts`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** `<session-uuid>.log` and its single rotation `<session-uuid>.log.1`. */
+const SESSION_LOG_RE = /^(.+)\.log(\.1)?$/;
+export const DEFAULT_LOG_RETENTION_DAYS = 30;
+export const DEFAULT_LOG_SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Retention window in days (env `AGENT_FARM_LOG_RETENTION_DAYS`, default 30).
+ * `0` disables the sweep entirely — an explicit "keep everything" opt-out for
+ * anyone who treats these logs as an audit trail.
+ *
+ * NaN-checked rather than `parsed || default` because `0` is a meaningful
+ * override and is falsy in JS (same reasoning as `resolveHuskGraceMs`).
+ */
+export function resolveLogRetentionDays(env = process.env) {
+    const parsed = parseInt(env.AGENT_FARM_LOG_RETENTION_DAYS ?? '', 10);
+    return Math.max(Number.isNaN(parsed) ? DEFAULT_LOG_RETENTION_DAYS : parsed, 0);
+}
+/**
+ * Sweep cadence (env `AGENT_FARM_LOG_SWEEP_INTERVAL_MS`, default 24h). Floored
+ * at 1s so a bad value can't spin the event loop; tests shorten it deliberately.
+ */
+export function resolveLogSweepIntervalMs(env = process.env) {
+    const parsed = parseInt(env.AGENT_FARM_LOG_SWEEP_INTERVAL_MS ?? '', 10);
+    return Math.max(Number.isNaN(parsed) ? DEFAULT_LOG_SWEEP_INTERVAL_MS : parsed, 1000);
+}
+/**
+ * Total footprint of the session log directory. Read-only — used by
+ * `codev doctor` to surface the number the issue was filed about, and by the
+ * sweep's own logging. A missing directory is a healthy zero, not an error.
+ */
+export function measureSessionLogs(logDir) {
+    const footprint = { files: 0, bytes: 0, oldestMtimeMs: null };
+    let entries;
+    try {
+        entries = fs.readdirSync(logDir);
+    }
+    catch {
+        return footprint;
+    }
+    for (const name of entries) {
+        if (!SESSION_LOG_RE.test(name))
+            continue;
+        let stat;
+        try {
+            stat = fs.statSync(path.join(logDir, name));
+        }
+        catch {
+            continue; // vanished mid-scan — nothing to account for
+        }
+        if (!stat.isFile())
+            continue;
+        footprint.files += 1;
+        footprint.bytes += stat.size;
+        if (footprint.oldestMtimeMs === null || stat.mtimeMs < footprint.oldestMtimeMs) {
+            footprint.oldestMtimeMs = stat.mtimeMs;
+        }
+    }
+    return footprint;
+}
+/**
+ * Delete session logs whose last write is older than `retentionMs`.
+ *
+ * Never throws: a log directory that can't be read, or an individual file that
+ * can't be stat'd or unlinked, is counted and skipped. Log retention is
+ * janitorial — it must not be able to take Tower's startup path down with it.
+ */
+export function sweepSessionLogs(opts) {
+    const result = {
+        scanned: 0,
+        deleted: 0,
+        bytesFreed: 0,
+        skippedActive: 0,
+        failed: 0,
+    };
+    if (opts.retentionMs <= 0)
+        return result;
+    const now = opts.now ?? Date.now();
+    const active = new Set(opts.activeSessionIds ?? []);
+    let entries;
+    try {
+        entries = fs.readdirSync(opts.logDir);
+    }
+    catch {
+        return result; // no log dir yet (fresh install) — nothing to sweep
+    }
+    for (const name of entries) {
+        const match = SESSION_LOG_RE.exec(name);
+        if (!match)
+            continue;
+        const fullPath = path.join(opts.logDir, name);
+        let stat;
+        try {
+            stat = fs.statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        result.scanned += 1;
+        if (now - stat.mtimeMs < opts.retentionMs)
+            continue;
+        if (active.has(match[1])) {
+            result.skippedActive += 1;
+            continue;
+        }
+        try {
+            fs.unlinkSync(fullPath);
+            result.deleted += 1;
+            result.bytesFreed += stat.size;
+        }
+        catch {
+            result.failed += 1;
+        }
+    }
+    if (result.deleted > 0 || result.failed > 0) {
+        opts.log?.(`Session log sweep: deleted ${result.deleted} log(s), freed ${formatBytes(result.bytesFreed)}` +
+            ` (${result.scanned} scanned` +
+            (result.skippedActive > 0 ? `, ${result.skippedActive} kept as live` : '') +
+            (result.failed > 0 ? `, ${result.failed} failed` : '') +
+            ')');
+    }
+    return result;
+}
+/** Human-readable byte count for log lines and `codev doctor` output. */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}
+//# sourceMappingURL=session-log-sweep.js.map

package/dist/agent-farm/servers/session-log-sweep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-log-sweep.js","sourceRoot":"","sources":["../../../src/agent-farm/servers/session-log-sweep.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/servers/session-submit.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Per-session submission lock (Spec 1273, verify phase).
+ *
+ * ## The bug this exists to make impossible
+ *
+ * `writeMessageToSession` writes text to the PTY and schedules the Enter that
+ * submits it **50–80ms later** (`message-write.ts`). The write functions return
+ * that completion offset but do not wait for it, and `/api/send` responded as
+ * soon as the write was *scheduled*. So an awaited send resolved before its own
+ * message had been submitted.
+ *
+ * In production (`afx reset`, 2026-07-31) that gap swallowed a `/clear`
+ * entirely. Reset awaited the raw write of `/clear`, then wrote the
+ * re-orientation — landing inside the 50ms window, into the same composer,
+ * ahead of the Enter. One Enter then submitted both as a single message
+ * beginning `/clear### [ARCHITECT INSTRUCTION...`. The slash command was never
+ * executed, the builder's context was never cleared, and every layer reported
+ * success.
+ *
+ * ## Ordering is not atomicity
+ *
+ * The paced writer already threads a delay offset between consecutive writes, and the
+ * mailbox delivery path serialises messages to one agent (`deliverAgentMailSerialized`
+ * chains each delivery on the prior one's paced completion). Both fix the *order* in
+ * which queued messages reach a session. Neither would have prevented this: the two
+ * writes were correctly ordered and still coalesced, because being second is not the
+ * same as being separate. What was missing is a guarantee that a submission completes —
+ * Enter included — before the next write to that session begins.
+ *
+ * ## What this provides
+ *
+ * A promise chain per session key. Each submission waits for the previous one to
+ * finish (including its Enter), so concurrent `/api/send` requests to the same
+ * terminal cannot interleave in the composer. `await submitToSession(...)` means
+ * *submitted*, not *scheduled* — which is what every caller already assumed it
+ * meant.
+ *
+ * Deliberately keyed by session id rather than holding a session object: Tower
+ * re-fetches sessions by id, and a lock that outlived its session would pin a
+ * dead reference.
+ *
+ * ## Exactly what it covers — this is NOT blanket per-session atomicity
+ *
+ * A lock only serialises writers that take it. Currently that is the `escape`
+ * and `interrupt` paths of `/api/send`. Every other PTY writer still writes
+ * directly, and it is worth being precise about why:
+ *
+ *   - The mailbox delivery path (`deliverAgentMailSerialized`, Spec 1313) — every
+ *     normal `/api/send` AND every cron notification (Phase 6 rerouted cron here; the
+ *     old blind `writeMessageToSession` is gone). NOT covered by this lock, and does not
+ *     need it: it runs its OWN per-agent write serializer that completion-chains each
+ *     delivery on the prior one's paced write (text + Enter), so two mailbox deliveries
+ *     to one agent cannot interleave. That is a disjoint lock from this per-session one,
+ *     so a mailbox delivery is not serialised against a concurrent `escape`/`interrupt`
+ *     here — but a normal mailbox delivery only ever writes onto a render-gate-verified
+ *     empty prompt, and `interrupt` is the explicit gate-bypassing human action (see
+ *     tower-routes.ts), so that residual cross-path race is an accepted, documented
+ *     boundary, not a regression this lock must close.
+ *   - `POST /api/terminals/:id/write` — NOT covered. It is a raw passthrough
+ *     with no Enter semantics of its own.
+ *   - `tower-websocket.ts` keystrokes and the shellper frame relay — DELIBERATELY
+ *     not covered. That is a human typing into their own terminal; serialising
+ *     it behind an agent's message would make the UI feel stuck, and the human
+ *     is the composer's owner.
+ *
+ * So the guarantee is: **two lock-taking `/api/send` submissions (escape/interrupt)
+ * to one session cannot interleave**, which is the failure that reached production.
+ * Anything stronger requires the remaining writers to take the lock too.
+ */
+/** Injectable for tests; real timers otherwise. */
+export interface SubmitClock {
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * Run a write against a session so that it completes before any other
+ * submission to the same session begins.
+ *
+ * @param sessionId  terminal/session id — the lock's granularity
+ * @param write      performs the write; returns ms from now until the final
+ *                   keystroke (the Enter) has been written. This is exactly what
+ *                   `writeMessageToSession` / `writeEscapeToSession` already
+ *                   return, so callers pass them through unchanged.
+ * @returns resolves once the submission is complete
+ */
+export declare function submitToSession(sessionId: string, write: () => number, clock?: SubmitClock): Promise<void>;
+/** Number of sessions with a submission in flight. Test/observability only. */
+export declare function pendingSubmissionSessions(): number;
+/** Drop all chains. Test-only; a live Tower should let them drain. */
+export declare function resetSubmissionChains(): void;
+//# sourceMappingURL=session-submit.d.ts.map

package/dist/agent-farm/servers/session-submit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-submit.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/session-submit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAUH,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,MAAM,EACnB,KAAK,GAAE,WAAuB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED,+EAA+E;AAC/E,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}