hammoc 1.5.0 → 1.7.0

package/packages/server/dist/services/cliScreenCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliScreenCache.d.ts","sourceRoot":"","sources":["../../src/services/cliScreenCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgBH;kGACkG;AAClG,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAGnE;AAED,6FAA6F;AAC7F,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAElE;AAED;wGACwG;AACxG,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAI3E;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEvD"}

package/packages/server/dist/services/cliScreenCache.js

@@ -0,0 +1,48 @@
+/**
+ * CLI screen cache (Story 37.7, reworked in 37.8) — a session-lifetime snapshot of the
+ * current claude TUI screen, used to restore late-joining / refreshed / collapse-expanded
+ * browsers in CLI mode.
+ *
+ * The Story 37.1 headless emulator is per-TURN (spawned with the PTY, disposed at teardown).
+ * But the CLI engine is turn-per-process, so between turns there is no emulator and no live
+ * PTY. This cache lives at the SESSION scope: while a turn streams, the engine refreshes it
+ * with the CURRENT serialized screen on the same ~100ms throttle as the live `cli:screen-frame`
+ * (so a late-join mid-turn restores the live screen, not a stale one), and hands off the FINAL
+ * serialized screen at teardown. A `session:join` or `cli:request-screen-frame` arriving
+ * between turns then has a "current screen" to send.
+ *
+ * Story 37.8: the entry is now a single SERIALIZED frame string (ANSI/color intact, produced
+ * by the screen model's serialize addon), not a plain-text grid — the client restores it via
+ * reset()+write(frame), identical to a live frame, so restore and live share one render path.
+ *
+ * Pure module-level Map. CLI-only; SDK mode never writes it (no PTY / screen model), so `get`
+ * returns undefined for SDK sessions and the frame push is naturally a no-op.
+ */
+const cache = new Map();
+/** Store (or replace) the current serialized screen frame for a session. `ts` records recency.
+ *  Preserves the existing `stalled` flag — only the watchdog (setCliScreenStall) mutates that. */
+export function setCliScreen(sessionId, frame) {
+    const prev = cache.get(sessionId);
+    cache.set(sessionId, { frame, stalled: prev?.stalled ?? false, ts: Date.now() });
+}
+/** Return the cached serialized screen frame for a session, or undefined on a cache miss. */
+export function getCliScreen(sessionId) {
+    return cache.get(sessionId)?.frame;
+}
+/** Update the soft screen-stall flag on an EXISTING screen entry. No-op on a cache miss, so a
+ *  frame-less (leak-prone) entry is never created — a cached screen frame is what defines a session. */
+export function setCliScreenStall(sessionId, stalled) {
+    const prev = cache.get(sessionId);
+    if (!prev)
+        return;
+    cache.set(sessionId, { ...prev, stalled });
+}
+/** Current cached stall flag for a session (false on a miss). Used to resync late joiners. */
+export function getCliScreenStall(sessionId) {
+    return cache.get(sessionId)?.stalled ?? false;
+}
+/** Drop a session's cached screen (called when its socket room empties — leak guard). */
+export function deleteCliScreen(sessionId) {
+    cache.delete(sessionId);
+}
+//# sourceMappingURL=cliScreenCache.js.map

package/packages/server/dist/services/cliScreenCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliScreenCache.js","sourceRoot":"","sources":["../../src/services/cliScreenCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAcH,MAAM,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEhD;kGACkG;AAClG,MAAM,UAAU,YAAY,CAAC,SAAiB,EAAE,KAAa;IAC3D,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACnF,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC;AACrC,CAAC;AAED;wGACwG;AACxG,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,OAAgB;IACnE,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,OAAO,IAAI,KAAK,CAAC;AAChD,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAC1B,CAAC"}

package/packages/server/dist/services/cliScreenModel.d.ts

@@ -0,0 +1,141 @@
+/**
+ * CLI Screen Model (Epic 37 — Story 37.1)
+ *
+ * A thin server-side **headless terminal** that reconstructs the *final screen grid*
+ * the interactive `claude` TUI paints into its PTY. The CLI engine's existing
+ * extraction (Story 32.7 spinner / 32.6 permission / 32.8 question / usage-limit)
+ * runs regex over a **linear** ANSI-stripped buffer (`stripAnsiForDetect` →
+ * `progressBuffer` etc.). A linear buffer has no cursor-movement information, so a
+ * counter that claude *overwrites in place* (the spinner's "365" → "366" on the same
+ * column) gets **concatenated** ("365" + "366" → "365366" fusion). The accumulated
+ * workarounds (digit caps, implausible-jump guards) only paper over that.
+ *
+ * This model feeds the raw PTY frames (ANSI intact) into a real `@xterm/headless`
+ * `Terminal` — the **same terminal core** (`@xterm/xterm` 5.5.x) the client mirror
+ * (`CliPtyMirror.tsx`) also renders into, now via the serialized `cli:screen-frame`. The
+ * emulator *applies* the cursor moves claude intended, leaving only the final grid,
+ * where same-cell updates are overwrites — so fusion is **structurally impossible**.
+ *
+ * Story 37.1 is a *spike-bearing gate*: it adds this grid model as a **pure
+ * foundation** (no production consumer is moved here yet — that is 37.2~37.4) and
+ * proves real-claude frames reconstruct faithfully (GO/NO-GO). The screen model is
+ * fed *unconditionally* on every turn ("reconstruct always / display-only toggle",
+ * AC3) — unlike the mirror passthrough which is gated by the `cliPtyMirror` pref.
+ *
+ * Geometry is **120×80** — the engine passes `cols`/`rows` to `cliSessionPool.spawnClaude`
+ * explicitly, matching this model and `CliPtyMirror` (COLS=120 / ROWS=80) — so the
+ * coordinates claude addresses line up with what we read. (Story 37.8 raised rows 40→80 so
+ * the mirror shows more of claude's screen at once.)
+ *
+ * API surface (intentionally thin):
+ *   createCliScreenModel(cols=120, rows=40) → { write, flush, readGrid, readScreenText, serialize, dispose }
+ *
+ * @see docs/stories/37.1.story.md
+ * [Source: docs/prd/epic-37-cli-terminal-emulation.md#story-371]
+ */
+/**
+ * Default CLI terminal geometry — MUST match `cliSessionPool.spawnClaude` (the engine passes
+ * these explicitly) and `CliPtyMirror` (COLS=120 / ROWS=80). claude draws its in-place redraws
+ * at *these* coordinates; a mismatch desyncs the grid. (Story 37.8 raised ROWS 40→80 so the
+ * mirror shows more of claude's screen at once.)
+ */
+export declare const CLI_SCREEN_COLS = 120;
+export declare const CLI_SCREEN_ROWS = 80;
+/**
+ * Scrollback retention (lines kept ABOVE the viewport). Story 37.11 AC5: a single block (a long tool
+ * diff / reasoning) taller than the viewport scrolls its HEAD — the opening glyph the card parser keys
+ * on — off the top. With `scrollback:0` that head was discarded, so the parser saw only the glyph-less
+ * TAIL and could not classify the block; it fell back to the late JSONL (a screen↔file timing race).
+ * Retaining scrollback lets `readGrid(scrollbackRows)` recover the head so the SCREEN stays the single
+ * primary card source. The mirror is kept viewport-only via `serialize({scrollback:0})` so this
+ * retention never bloats the `cli:screen-frame` payload.
+ */
+export declare const CLI_SCREEN_SCROLLBACK = 5000;
+/**
+ * The foreground color CLASS of a leading `●` card bullet (Story 37.10 — tool running/done).
+ * The interactive claude TUI paints the card bullet in a TRUECOLOR that encodes tool status,
+ * which the plain-text `readGrid()` (translateToString) discards. Verified against real frames
+ * (cli-real-pty-dump): a COMPLETED tool's bullet is green (78,186,101), an IN-PROGRESS tool's
+ * bullet is gray (153,153,153), and an assistant TEXT body bullet is white (255,255,255). The
+ * class — not the exact RGB — is the stable signal (claude may retune the shade), so we bucket:
+ *   - 'green' : tool COMPLETE  (g clearly dominates r & b)
+ *   - 'white' : assistant text body bullet (all channels high ≥200)
+ *   - 'gray'  : tool RUNNING / dim (the remaining low-saturation case)
+ *   - 'other' : a non-RGB / palette / default fg (older TUI or unexpected) — treated as not-green
+ *   - null    : the row has no leading `●` glyph
+ */
+export type CliBulletColor = 'green' | 'white' | 'gray' | 'other' | null;
+/** The screen model's read/write surface consumed by later stories (37.2~37.4). */
+export interface CliScreenModel {
+    /**
+     * Feed a raw PTY frame (ANSI intact) straight into the emulator. **No linear
+     * strip** — the whole point is that the emulator *interprets* the ANSI. Cheap and
+     * fire-and-forget: xterm buffers the write and parses it asynchronously, so the
+     * grid is not guaranteed settled until `flush()` resolves.
+     */
+    write(data: string): void;
+    /**
+     * Resolve once every preceding `write` has been parsed into the buffer. xterm's
+     * write pipeline is asynchronous/buffered (verified — an immediate read after
+     * `write` returns the pre-write grid), so a reader that needs a *settled* grid
+     * must `await flush()` first. Implemented via xterm's own write callback (writes
+     * are FIFO, so an empty write's callback fires after all prior writes are parsed).
+     */
+    flush(): Promise<void>;
+    /**
+     * The active screen (viewport) as one trimmed string per row — exactly `rows`
+     * entries, blank rows included as ''. Later detectors (37.2~37.4) scan these rows
+     * for the spinner line / modal box / permission-mode status row.
+     *
+     * `scrollbackRows` (Story 37.11 AC5, default 0 = viewport-only / unchanged): when > 0, PREPEND up
+     * to that many scrolled-off rows ABOVE the viewport so the card parser can read a block whose head
+     * scrolled off the top. Footer detectors pass 0 (they want only the live bottom region); only the
+     * card scraper passes a window.
+     */
+    readGrid(scrollbackRows?: number): string[];
+    /** `readGrid().join('\n')` — convenience surface for line-spanning detectors. */
+    readScreenText(): string;
+    /**
+     * Per-row foreground-color CLASS of each row's leading `●` card bullet (Story 37.10).
+     * One entry per row, index-aligned with `readGrid(scrollbackRows)` for the SAME `scrollbackRows`
+     * (so a caller can slice both identically). `null` where a row has no leading `●`. This is the COLOR
+     * channel `readGrid()` throws away — used to read tool running(gray)/done(green) status off the
+     * bullet, far more robust than the `⎿ Waiting…`/`⎿ Running…` placeholder TEXT (misread as results).
+     */
+    readBulletColors(scrollbackRows?: number): CliBulletColor[];
+    /**
+     * Serialize the CURRENT screen to a string WITH ANSI/color escapes (via the serialize
+     * addon) — suitable for the client mirror to `reset()` + `write()` into an identical
+     * screen. Call AFTER `flush()` so the serialized state is settled. Covers normal +
+     * alternate buffers (claude TUI is a full-screen / alt-buffer app); an alt screen is
+     * prefixed with the alt-buffer-enter + cursor-home sequence, which the client absorbs
+     * via `reset()` before each write. Unlike `readGrid` (plain text for detectors), this
+     * preserves color — it is the mirror's content source, not a detection source. VIEWPORT-ONLY
+     * (`serialize({scrollback:0})`): the card parser's scrollback retention (Story 37.11 AC5) must NOT
+     * bloat the mirror frame, so only the active screen is serialized (its pre-37.11 scope).
+     */
+    serialize(): string;
+    /**
+     * Story 37.11 AC3: mark the CURRENT TURN's start at the live cursor (call once, at generation
+     * start). Floors `readGrid(scrollbackRows>0)`/`readBulletColors(scrollbackRows>0)` so a resume
+     * boot-repaint of the prior conversation (ABOVE this mark) is excluded from the card scrape.
+     * 실측 2026-06-16: registered at generation-start ⇒ ZERO prior-turn leak across FIT and overflow
+     * frames (a 130-line turn-2 that scrolled the prior repaint into scrollback leaked it 0 times).
+     */
+    markTurnStart(): void;
+    /** Dispose the underlying emulator. Idempotent-safe at the call sites (single teardown path). */
+    dispose(): void;
+}
+/**
+ * Create a headless screen model owning one `@xterm/headless` Terminal.
+ *
+ * `disableStdin: true` (we never type into this emulator — it is read-only), `scrollback:
+ * CLI_SCREEN_SCROLLBACK` (Story 37.11 AC5 — retain scrolled-off lines so `readGrid(scrollbackRows)`
+ * can recover the HEAD of a block taller than the viewport; was 0, which discarded the head and
+ * forced the card parser to fall back to the late JSONL), and `allowProposedApi: true` (the `buffer`
+ * namespace used to read the grid is proposed API in 5.x — verified to throw otherwise).
+ * `Terminal.open()` is **never** called: headless has no DOM/renderer; we read the buffer model
+ * directly. The mirror's `serialize()` is scoped to the viewport so this retention never bloats it.
+ */
+export declare function createCliScreenModel(cols?: number, rows?: number): CliScreenModel;
+//# sourceMappingURL=cliScreenModel.d.ts.map

package/packages/server/dist/services/cliScreenModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliScreenModel.d.ts","sourceRoot":"","sources":["../../src/services/cliScreenModel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAiBH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAEzE,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5C,iFAAiF;IACjF,cAAc,IAAI,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,gBAAgB,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;IAC5D;;;;;;;;;;OAUG;IACH,SAAS,IAAI,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,aAAa,IAAI,IAAI,CAAC;IACtB,iGAAiG;IACjG,OAAO,IAAI,IAAI,CAAC;CACjB;AAwBD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,GAAE,MAAwB,EAC9B,IAAI,GAAE,MAAwB,GAC7B,cAAc,CA8FhB"}

package/packages/server/dist/services/cliScreenModel.js

@@ -0,0 +1,196 @@
+/**
+ * CLI Screen Model (Epic 37 — Story 37.1)
+ *
+ * A thin server-side **headless terminal** that reconstructs the *final screen grid*
+ * the interactive `claude` TUI paints into its PTY. The CLI engine's existing
+ * extraction (Story 32.7 spinner / 32.6 permission / 32.8 question / usage-limit)
+ * runs regex over a **linear** ANSI-stripped buffer (`stripAnsiForDetect` →
+ * `progressBuffer` etc.). A linear buffer has no cursor-movement information, so a
+ * counter that claude *overwrites in place* (the spinner's "365" → "366" on the same
+ * column) gets **concatenated** ("365" + "366" → "365366" fusion). The accumulated
+ * workarounds (digit caps, implausible-jump guards) only paper over that.
+ *
+ * This model feeds the raw PTY frames (ANSI intact) into a real `@xterm/headless`
+ * `Terminal` — the **same terminal core** (`@xterm/xterm` 5.5.x) the client mirror
+ * (`CliPtyMirror.tsx`) also renders into, now via the serialized `cli:screen-frame`. The
+ * emulator *applies* the cursor moves claude intended, leaving only the final grid,
+ * where same-cell updates are overwrites — so fusion is **structurally impossible**.
+ *
+ * Story 37.1 is a *spike-bearing gate*: it adds this grid model as a **pure
+ * foundation** (no production consumer is moved here yet — that is 37.2~37.4) and
+ * proves real-claude frames reconstruct faithfully (GO/NO-GO). The screen model is
+ * fed *unconditionally* on every turn ("reconstruct always / display-only toggle",
+ * AC3) — unlike the mirror passthrough which is gated by the `cliPtyMirror` pref.
+ *
+ * Geometry is **120×80** — the engine passes `cols`/`rows` to `cliSessionPool.spawnClaude`
+ * explicitly, matching this model and `CliPtyMirror` (COLS=120 / ROWS=80) — so the
+ * coordinates claude addresses line up with what we read. (Story 37.8 raised rows 40→80 so
+ * the mirror shows more of claude's screen at once.)
+ *
+ * API surface (intentionally thin):
+ *   createCliScreenModel(cols=120, rows=40) → { write, flush, readGrid, readScreenText, serialize, dispose }
+ *
+ * @see docs/stories/37.1.story.md
+ * [Source: docs/prd/epic-37-cli-terminal-emulation.md#story-371]
+ */
+// `@xterm/headless` ships CommonJS; under Node ESM the named export `Terminal`
+// is not detected by the cjs-module-lexer, so a named import
+// (`import { Terminal } from ...`) fails at runtime. The default import resolves
+// to the module's `module.exports`, off which `Terminal` is destructured.
+// (Verified empirically — not assumed; see Story 37.1 Task 1.)
+import headless from '@xterm/headless';
+const { Terminal } = headless;
+// @xterm/addon-serialize ships CJS as well, so it hits the same named-import caveat as
+// headless above — default-import and destructure. SerializeAddon reads the buffer model
+// directly (no DOM/renderer), which is exactly the `@xterm/headless` + serialize-addon
+// combo xterm.js documents for server-side state capture and reconnection restore.
+import serializeMod from '@xterm/addon-serialize';
+const { SerializeAddon } = serializeMod;
+/**
+ * Default CLI terminal geometry — MUST match `cliSessionPool.spawnClaude` (the engine passes
+ * these explicitly) and `CliPtyMirror` (COLS=120 / ROWS=80). claude draws its in-place redraws
+ * at *these* coordinates; a mismatch desyncs the grid. (Story 37.8 raised ROWS 40→80 so the
+ * mirror shows more of claude's screen at once.)
+ */
+export const CLI_SCREEN_COLS = 120;
+export const CLI_SCREEN_ROWS = 80;
+/**
+ * Scrollback retention (lines kept ABOVE the viewport). Story 37.11 AC5: a single block (a long tool
+ * diff / reasoning) taller than the viewport scrolls its HEAD — the opening glyph the card parser keys
+ * on — off the top. With `scrollback:0` that head was discarded, so the parser saw only the glyph-less
+ * TAIL and could not classify the block; it fell back to the late JSONL (a screen↔file timing race).
+ * Retaining scrollback lets `readGrid(scrollbackRows)` recover the head so the SCREEN stays the single
+ * primary card source. The mirror is kept viewport-only via `serialize({scrollback:0})` so this
+ * retention never bloats the `cli:screen-frame` payload.
+ */
+export const CLI_SCREEN_SCROLLBACK = 5000;
+/** The assistant card bullet glyph (U+25CF) — its fg color encodes tool status (Story 37.10). */
+const CARD_BULLET = '●';
+/**
+ * Classify a `●` cell's foreground color into a {@link CliBulletColor} bucket. Only TRUECOLOR
+ * (claude paints the bullet via `\x1b[38;2;r;g;bm`) carries the status signal; a non-RGB fg is
+ * 'other' (not-green → treated as running, the safe default). Thresholds bucket by hue/brightness,
+ * not exact RGB, so a TUI shade retune still classifies (green: g clearly dominates; white: all
+ * channels bright; gray: the remaining low-saturation case). Verified RGBs: green 78,186,101 /
+ * gray 153,153,153 / white 255,255,255 (cli-real-pty-dump).
+ */
+function classifyBulletFg(cell) {
+    if (!cell.isFgRGB())
+        return 'other';
+    const c = cell.getFgColor();
+    const r = (c >> 16) & 0xff;
+    const g = (c >> 8) & 0xff;
+    const b = c & 0xff;
+    if (g - r >= 30 && g - b >= 30)
+        return 'green'; // done — green dominates (78,186,101)
+    if (r >= 200 && g >= 200 && b >= 200)
+        return 'white'; // assistant text body (255,255,255)
+    return 'gray'; // running / dim (153,153,153) and any other low-saturation fg
+}
+/**
+ * Create a headless screen model owning one `@xterm/headless` Terminal.
+ *
+ * `disableStdin: true` (we never type into this emulator — it is read-only), `scrollback:
+ * CLI_SCREEN_SCROLLBACK` (Story 37.11 AC5 — retain scrolled-off lines so `readGrid(scrollbackRows)`
+ * can recover the HEAD of a block taller than the viewport; was 0, which discarded the head and
+ * forced the card parser to fall back to the late JSONL), and `allowProposedApi: true` (the `buffer`
+ * namespace used to read the grid is proposed API in 5.x — verified to throw otherwise).
+ * `Terminal.open()` is **never** called: headless has no DOM/renderer; we read the buffer model
+ * directly. The mirror's `serialize()` is scoped to the viewport so this retention never bloats it.
+ */
+export function createCliScreenModel(cols = CLI_SCREEN_COLS, rows = CLI_SCREEN_ROWS) {
+    const terminal = new Terminal({
+        cols,
+        rows,
+        disableStdin: true,
+        scrollback: CLI_SCREEN_SCROLLBACK,
+        allowProposedApi: true,
+    });
+    // Load the serialize addon onto the headless terminal. headless has no renderer, but
+    // serialize only reads the buffer model, so `open()` is unnecessary (same as readGrid).
+    // headless and addon-serialize ship separate (structurally identical) ITerminalAddon
+    // types, so the load is cast through `unknown` to bridge the two module declarations.
+    const serializeAddon = new SerializeAddon();
+    terminal.loadAddon(serializeAddon);
+    // Story 37.11 AC3: marks the current turn's start (set via markTurnStart at generation start). The
+    // card scraper's scrollback read is FLOORED here so a resume boot-repaint of the PRIOR conversation
+    // (painted into THIS turn's buffer ABOVE the mark) is never read as a live card. The marker rides
+    // scroll/eviction (xterm IMarker — probe-verified). null/absent ⇒ floor 0 (read full window).
+    let turnMarker;
+    const turnFloor = () => (turnMarker && !turnMarker.isDisposed ? turnMarker.line : 0);
+    return {
+        write(data) {
+            terminal.write(data);
+        },
+        flush() {
+            return new Promise((resolve) => {
+                terminal.write('', resolve);
+            });
+        },
+        readGrid(scrollbackRows = 0) {
+            const buffer = terminal.buffer.active;
+            const grid = [];
+            // The active viewport is the absolute range [baseY, baseY + rows). Story 37.11 AC5: when a
+            // caller asks for scrollback, START up to `scrollbackRows` lines higher so the scrolled-off HEAD
+            // of an over-tall block is included; 0 = viewport-only (unchanged). The start is clamped two ways:
+            // `max(turnFloor(), …)` keeps the read AT/below the current-turn mark (AC3 — a resume repaint that
+            // scrolled into scrollback ABOVE the mark is excluded), and `min(baseY, …)` keeps it AT/above baseY
+            // so the VIEWPORT is ALWAYS fully read (a mark inside the viewport never hides a live card — only
+            // the scrollback portion is floored). `translateToString(true)` trims trailing whitespace.
+            const startY = scrollbackRows > 0 ? Math.min(buffer.baseY, Math.max(turnFloor(), buffer.baseY - scrollbackRows)) : buffer.baseY;
+            for (let absY = startY; absY < buffer.baseY + rows; absY++) {
+                const line = buffer.getLine(absY);
+                grid.push(line ? line.translateToString(true) : '');
+            }
+            return grid;
+        },
+        readScreenText() {
+            return this.readGrid().join('\n');
+        },
+        readBulletColors(scrollbackRows = 0) {
+            const buffer = terminal.buffer.active;
+            const out = [];
+            // Same window as readGrid(scrollbackRows) so the two stay index-aligned (Story 37.11 AC5).
+            const startY = scrollbackRows > 0 ? Math.min(buffer.baseY, Math.max(turnFloor(), buffer.baseY - scrollbackRows)) : buffer.baseY;
+            for (let absY = startY; absY < buffer.baseY + rows; absY++) {
+                const line = buffer.getLine(absY);
+                let cls = null;
+                if (line) {
+                    for (let x = 0; x < cols; x++) {
+                        const cell = line.getCell(x);
+                        if (!cell)
+                            continue;
+                        const ch = cell.getChars();
+                        if (ch === CARD_BULLET) {
+                            cls = classifyBulletFg(cell);
+                            break;
+                        }
+                        // The bullet must be the LEADING glyph of the row (after indent spaces); a non-blank
+                        // non-bullet first glyph (e.g. `⎿`, box-drawing, prose) means this row has no card bullet.
+                        if (ch && ch.trim().length > 0)
+                            break;
+                    }
+                }
+                out.push(cls);
+            }
+            return out;
+        },
+        serialize() {
+            // VIEWPORT-ONLY (Story 37.11 AC5): the card parser's scrollback retention must not bloat the
+            // mirror frame, so serialize just the active screen (its pre-37.11 scope). Probe-verified: the
+            // addon honors `{scrollback:0}` (default incl-scrollback payload was ~2x the viewport-only one).
+            return serializeAddon.serialize({ scrollback: 0 });
+        },
+        markTurnStart() {
+            // Drop a marker at the live cursor = the current turn's start. Replaces any prior mark so a
+            // re-entrant call can't drift the floor downward (it must stay at the FIRST generation frame).
+            turnMarker?.dispose();
+            turnMarker = terminal.registerMarker(0);
+        },
+        dispose() {
+            turnMarker?.dispose();
+            terminal.dispose();
+        },
+    };
+}
+//# sourceMappingURL=cliScreenModel.js.map

package/packages/server/dist/services/cliScreenModel.js.map

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

package/packages/server/dist/services/cliScreenStallWatchdog.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Soft CLI screen-stall watchdog.
+ *
+ * The reconstructed claude screen changes ~1×/second while a turn is healthy (the spinner glyph
+ * rotates and the elapsed clock ticks), so a long flat-line of NO content change is a reliable
+ * "claude froze" signal — far more reliable than the removed inactivity timeout, which watched JSONL
+ * activity that legitimately pauses during deep thinking. This pure helper turns a stream of screen
+ * frames into a single stalled↔live state:
+ *
+ *   - a CHANGED frame proves liveness → clears any active stall and (re)arms the timer;
+ *   - an identical repaint is ignored (no real change);
+ *   - after `stallMs` with no change the timer fires `onStallChange(true)` — but ONLY if `isActive()`
+ *     still holds (a running, non-modal turn), so a finished turn or a pending permission/question
+ *     modal can never false-trigger;
+ *   - `dispose()` (turn end) clears the timer so a stale fire can't leak into the next turn, and
+ *     drops any active stall.
+ *
+ * Advisory ONLY: the caller decides what to do with the signal — Hammoc surfaces a "looks stuck —
+ * Stop?" affordance and never auto-aborts. The scheduler is injectable so the timing is unit-testable
+ * without real timers.
+ */
+export interface ScreenStallWatchdog {
+    /** Feed a screen frame. A changed frame clears the stall and re-arms; an identical one is ignored. */
+    noteFrame(frame: string): void;
+    /** Tear down at turn end: clear the timer and drop any active stall. */
+    dispose(): void;
+}
+export interface ScreenStallWatchdogOptions {
+    /** No-change window in ms. `<= 0` disables the watchdog entirely (noteFrame/dispose become no-ops). */
+    stallMs: number;
+    /** Fire-guard, re-checked when the timer elapses: is this still a running, non-modal turn? */
+    isActive: () => boolean;
+    /** Called only on a stalled↔live transition (never repeated for the same state). */
+    onStallChange: (stalled: boolean) => void;
+    /** Injectable scheduler (tests). Default setTimeout. */
+    schedule?: (cb: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    /** Injectable canceller (tests). Default clearTimeout. */
+    cancel?: (id: ReturnType<typeof setTimeout>) => void;
+}
+export declare function createScreenStallWatchdog(opts: ScreenStallWatchdogOptions): ScreenStallWatchdog;
+//# sourceMappingURL=cliScreenStallWatchdog.d.ts.map

package/packages/server/dist/services/cliScreenStallWatchdog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliScreenStallWatchdog.d.ts","sourceRoot":"","sources":["../../src/services/cliScreenStallWatchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,mBAAmB;IAClC,sGAAsG;IACtG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,wEAAwE;IACxE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IACzC,uGAAuG;IACvG,OAAO,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,oFAAoF;IACpF,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C,wDAAwD;IACxD,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IACzE,0DAA0D;IAC1D,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,CAAC;CACtD;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,0BAA0B,GAAG,mBAAmB,CA2C/F"}

package/packages/server/dist/services/cliScreenStallWatchdog.js

@@ -0,0 +1,45 @@
+export function createScreenStallWatchdog(opts) {
+    const schedule = opts.schedule ?? ((cb, ms) => setTimeout(cb, ms));
+    const cancel = opts.cancel ?? ((id) => clearTimeout(id));
+    let timer = null;
+    let lastFrame = null;
+    let stalled = false;
+    const setStalled = (next) => {
+        if (stalled === next)
+            return;
+        stalled = next;
+        opts.onStallChange(next);
+    };
+    const clearTimer = () => {
+        if (timer !== null) {
+            cancel(timer);
+            timer = null;
+        }
+    };
+    const arm = () => {
+        clearTimer();
+        if (opts.stallMs <= 0)
+            return;
+        timer = schedule(() => {
+            timer = null;
+            if (opts.isActive())
+                setStalled(true);
+        }, opts.stallMs);
+    };
+    return {
+        noteFrame(frame) {
+            if (opts.stallMs <= 0)
+                return;
+            if (frame === lastFrame)
+                return; // identical repaint — not a real change
+            lastFrame = frame;
+            setStalled(false); // content moved → live (clears any active stall)
+            arm();
+        },
+        dispose() {
+            clearTimer();
+            setStalled(false);
+        },
+    };
+}
+//# sourceMappingURL=cliScreenStallWatchdog.js.map

package/packages/server/dist/services/cliScreenStallWatchdog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliScreenStallWatchdog.js","sourceRoot":"","sources":["../../src/services/cliScreenStallWatchdog.ts"],"names":[],"mappings":"AAyCA,MAAM,UAAU,yBAAyB,CAAC,IAAgC;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC;IAEzD,IAAI,KAAK,GAAyC,IAAI,CAAC;IACvD,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,UAAU,GAAG,CAAC,IAAa,EAAE,EAAE;QACnC,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO;QAC7B,OAAO,GAAG,IAAI,CAAC;QACf,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,GAAG,EAAE;QACtB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,MAAM,CAAC,KAAK,CAAC,CAAC;YACd,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,GAAG,GAAG,GAAG,EAAE;QACf,UAAU,EAAE,CAAC;QACb,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC;YAAE,OAAO;QAC9B,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE;YACpB,KAAK,GAAG,IAAI,CAAC;YACb,IAAI,IAAI,CAAC,QAAQ,EAAE;gBAAE,UAAU,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACnB,CAAC,CAAC;IAEF,OAAO;QACL,SAAS,CAAC,KAAa;YACrB,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC;gBAAE,OAAO;YAC9B,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,CAAC,wCAAwC;YACzE,SAAS,GAAG,KAAK,CAAC;YAClB,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,iDAAiD;YACpE,GAAG,EAAE,CAAC;QACR,CAAC;QACD,OAAO;YACL,UAAU,EAAE,CAAC;YACb,UAAU,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/packages/server/dist/services/cliSessionPool.d.ts

@@ -0,0 +1,97 @@
+/**
+ * CLI Session Pool (Epic 32 — Story 32.4)
+ *
+ * Owns the PTY processes for the CLI conversation engine (`CliChatEngine`), one
+ * per in-flight turn. This pool is **deliberately a separate module singleton
+ * from `ptyService`** (the web terminal pool): the dashboard's "active terminals"
+ * count is derived from `ptyService`'s session map, so routing CLI-engine PTYs
+ * through `ptyService` would pollute that count (Sprint Change Proposal §9.2 #3,
+ * spike §9-3). Keeping a distinct instance guarantees the CLI engine's PTYs never
+ * leak into the terminal count — isolation by construction.
+ *
+ * The Windows PATH normalization and binary-discovery patterns are *borrowed*
+ * from `ptyService` (which stays unmodified). They are duplicated here on purpose
+ * for file independence and isolation — the same convention `chatService.ts` and
+ * `streamHandler.ts` already use for `extractContextWindow`.
+ */
+import * as pty from 'node-pty';
+/** Handle returned to the engine for a spawned CLI PTY. */
+export interface CliPtyHandle {
+    /** Opaque key used to address this PTY in the pool (not the claude session id). */
+    handle: string;
+    pty: pty.IPty;
+}
+interface SpawnClaudeOptions {
+    /** Working directory for the claude session (the project root). */
+    cwd?: string;
+    /** Arguments passed to claude (interactive — no `--print`/`--output-format`). */
+    args: string[];
+    cols?: number;
+    rows?: number;
+    /**
+     * Epic 33 (Story 33.3): user-configured `claude` binary path. When set and valid it
+     * takes precedence over auto-detection; an invalid value falls back gracefully (see
+     * `resolveClaudeBinary`). Empty / undefined = auto-detect.
+     */
+    binaryPathOverride?: string;
+}
+declare class CliSessionPool {
+    private sessions;
+    private readonly windowsSystemPath;
+    /**
+     * Convert MINGW64 Unix-style PATH entries to Windows format and merge in the
+     * real Windows system PATH. (Borrowed verbatim in spirit from ptyService.)
+     */
+    private normalizePathForWindows;
+    /**
+     * Build the spawn environment: process.env minus undefined values and minus
+     * the "inside claude" signal vars, with Windows PATH normalized.
+     */
+    private buildEnv;
+    /**
+     * Best-effort sanity check for a user-supplied binary override (Story 33.3): exists,
+     * is a regular file, and (POSIX only) is executable by this process. Windows has no
+     * comparable execute bit, so `.exe`/file existence is sufficient there. Intentionally
+     * shallow — no signature / "is this really claude" inspection (out of scope).
+     */
+    private isValidBinaryOverride;
+    /**
+     * Resolve an executable path for `claude`. PATH lookup can fail in the server's
+     * child process (spike §9-5: `where claude` failed; the fallback resolved it),
+     * so known install locations are tried first, then a PATH probe with the
+     * corrected env, then a bare name as a last resort (pty resolves via env PATH).
+     *
+     * Story 33.3: when a non-empty `override` is supplied it is checked first and used
+     * if valid. An *invalid* override never hard-fails the turn — it logs a warning and
+     * falls through to the normal chain (auto-detect is the better UX than blocking CLI
+     * mode over a bad path). Empty / undefined skips the override entirely.
+     */
+    private resolveClaudeBinary;
+    /**
+     * Spawn an interactive claude TUI in a PTY and register it in the pool.
+     * The caller drives stdin (prompt injection), wires `pty.onData`, and attaches
+     * a watcher disposer via `registerDisposer`.
+     */
+    spawnClaude(opts: SpawnClaudeOptions): CliPtyHandle;
+    /** Attach the watcher teardown so dispose() tears down PTY + watcher together. */
+    registerDisposer(handle: string, dispose: () => void): void;
+    /** Send Ctrl+C (interrupt) to the PTY without killing it. */
+    interrupt(handle: string): void;
+    /**
+     * Tear down a CLI PTY: run the watcher disposer, kill the process, remove from
+     * the pool. Removal happens first so any onExit listener's dispose is a no-op.
+     * The kill is wrapped in try/catch to absorb Windows ConPTY shutdown noise
+     * (`AttachConsole failed`, spike §9-6 — `ptyService.killSession` pattern).
+     */
+    dispose(handle: string): void;
+    /** Destroy every CLI PTY (server shutdown). Symmetric with ptyService.destroyAll. */
+    destroyAll(): void;
+    /** Number of live CLI PTYs (for tests / introspection). */
+    get size(): number;
+    /** Whether a handle is still live in the pool. */
+    has(handle: string): boolean;
+}
+/** Module singleton — isolated from the web terminal pool (`ptyService`). */
+export declare const cliSessionPool: CliSessionPool;
+export {};
+//# sourceMappingURL=cliSessionPool.d.ts.map

package/packages/server/dist/services/cliSessionPool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliSessionPool.d.ts","sourceRoot":"","sources":["../../src/services/cliSessionPool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AA+BhC,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC;CACf;AAUD,UAAU,kBAAkB;IAC1B,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,cAAM,cAAc;IAClB,OAAO,CAAC,QAAQ,CAAkC;IAMlD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAU7B;IAEL;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAgD/B;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAUhB;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAY7B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IAkC3B;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,YAAY;IAkBnD,kFAAkF;IAClF,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAK3D,6DAA6D;IAC7D,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAU/B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAiB7B,qFAAqF;IACrF,UAAU,IAAI,IAAI;IASlB,2DAA2D;IAC3D,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,kDAAkD;IAClD,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;CAG7B;AAED,6EAA6E;AAC7E,eAAO,MAAM,cAAc,gBAAuB,CAAC"}