hammoc 1.6.0 → 1.7.0

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

@@ -0,0 +1,278 @@
+/**
+ * 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';
+import { randomUUID } from 'crypto';
+import { execSync } from 'child_process';
+import os from 'os';
+import path from 'path';
+import { existsSync, statSync, accessSync, constants as fsConstants } from 'fs';
+import { createLogger } from '../utils/logger.js';
+import { resolveBundledBinaryPath } from '../utils/bundledBinaryModelSupport.js';
+const log = createLogger('cliSessionPool');
+/**
+ * "I am running inside claude" environment signals. Stripped before spawning a
+ * fresh interactive claude so it starts a clean session rather than trying to
+ * attach to the host Hammoc process (spike §2).
+ *
+ * CHILD_SESSION / SESSION_ID matter when Hammoc itself is launched FROM INSIDE a claude session:
+ * the spawned CLI claude would inherit "I am a child session" and then NOT write its own session
+ * JSONL transcript — which the engine drains for chat content, so every turn would look empty
+ * (verified 2026-06-15: a probe that spawned claude under these inherited vars produced no
+ * transcript until they were stripped). Production Hammoc is not nested so it never hits this, but
+ * stripping them is the correct defensive posture for in-session launches.
+ */
+const CLAUDE_ENV_SIGNALS = [
+    'CLAUDECODE',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_CODE_SSE_PORT',
+    'CLAUDE_CODE_CHILD_SESSION',
+    'CLAUDE_CODE_SESSION_ID',
+];
+class CliSessionPool {
+    sessions = new Map();
+    // On Windows the server may be started from bash/MINGW with an incomplete PATH.
+    // Read the real Windows system PATH once via PowerShell+registry so spawned
+    // claude sessions inherit a complete environment regardless of launch shell.
+    // (Pattern borrowed from ptyService — kept private here for isolation.)
+    windowsSystemPath = (() => {
+        if (process.platform !== 'win32')
+            return null;
+        try {
+            const sysRoot = process.env.SystemRoot || 'C:\\Windows';
+            const ps = `${sysRoot}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`;
+            const cmd = `[System.Environment]::GetEnvironmentVariable('Path','Machine')+';'+[System.Environment]::GetEnvironmentVariable('Path','User')`;
+            return execSync(`"${ps}" -NoProfile -Command "${cmd}"`, { encoding: 'utf8' }).trim();
+        }
+        catch {
+            return null;
+        }
+    })();
+    /**
+     * Convert MINGW64 Unix-style PATH entries to Windows format and merge in the
+     * real Windows system PATH. (Borrowed verbatim in spirit from ptyService.)
+     */
+    normalizePathForWindows(env) {
+        if (process.platform !== 'win32')
+            return env;
+        const pathKeys = Object.keys(env).filter((k) => k.toUpperCase() === 'PATH');
+        const parts = pathKeys.map((k) => env[k]).filter(Boolean);
+        if (this.windowsSystemPath)
+            parts.push(this.windowsSystemPath);
+        if (parts.length === 0)
+            return env;
+        const merged = parts.join(';');
+        if (!merged)
+            return env;
+        const normalized = { ...env };
+        for (const k of pathKeys) {
+            delete normalized[k];
+        }
+        const entries = [];
+        for (const rawSegment of merged.split(';')) {
+            const segment = rawSegment.trim().replace(/^"|"$/g, '');
+            if (!segment)
+                continue;
+            const segParts = segment.split(':');
+            let i = 0;
+            while (i < segParts.length) {
+                const part = segParts[i];
+                if (part.length === 1 && /^[a-zA-Z]$/.test(part) && i + 1 < segParts.length && /^[/\\]/.test(segParts[i + 1])) {
+                    entries.push(`${part}:${segParts[i + 1]}`);
+                    i += 2;
+                }
+                else if (part) {
+                    entries.push(part);
+                    i++;
+                }
+                else {
+                    i++;
+                }
+            }
+        }
+        const windowsEntries = entries.map((p) => {
+            const match = p.match(/^\/([a-zA-Z])\/(.*)/);
+            if (match) {
+                return `${match[1].toUpperCase()}:\\${match[2].replace(/\//g, '\\')}`;
+            }
+            return p;
+        });
+        normalized['Path'] = windowsEntries.join(';');
+        return normalized;
+    }
+    /**
+     * Build the spawn environment: process.env minus undefined values and minus
+     * the "inside claude" signal vars, with Windows PATH normalized.
+     */
+    buildEnv() {
+        const base = Object.fromEntries(Object.entries(process.env).filter((e) => e[1] != null));
+        for (const signal of CLAUDE_ENV_SIGNALS) {
+            delete base[signal];
+        }
+        return this.normalizePathForWindows(base);
+    }
+    /**
+     * 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).
+     */
+    isValidBinaryOverride(candidate) {
+        try {
+            if (!statSync(candidate).isFile())
+                return false;
+            if (process.platform !== 'win32') {
+                accessSync(candidate, fsConstants.X_OK);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 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.
+     */
+    resolveClaudeBinary(env, override) {
+        const trimmedOverride = override?.trim();
+        if (trimmedOverride) {
+            if (this.isValidBinaryOverride(trimmedOverride))
+                return trimmedOverride;
+            log.warn(`Configured claude binary path is invalid (missing / not a file / not executable): "${trimmedOverride}" — falling back to auto-detect.`);
+        }
+        // Prefer the bundled engine binary shipped inside @anthropic-ai/claude-agent-sdk: it is the
+        // SAME Claude Code CLI as a system install (interactive by default) but version-pinned by
+        // Hammoc's package.json, so CLI mode and SDK mode run the identical engine — both recognize
+        // newly-released models (e.g. Fable 5). Auth/session are unaffected: the spawn inherits the
+        // same env, hence the same ~/.claude. A valid user override above still takes precedence.
+        const bundled = resolveBundledBinaryPath();
+        if (bundled && existsSync(bundled))
+            return bundled;
+        const home = os.homedir();
+        const isWin = process.platform === 'win32';
+        const candidates = isWin
+            ? [path.join(home, '.local', 'bin', 'claude.exe'), path.join(home, '.local', 'bin', 'claude')]
+            : [path.join(home, '.local', 'bin', 'claude')];
+        for (const candidate of candidates) {
+            if (existsSync(candidate))
+                return candidate;
+        }
+        try {
+            const probe = isWin ? 'where claude' : 'command -v claude';
+            const resolved = execSync(probe, { env, encoding: 'utf8' })
+                .split(/\r?\n/)
+                .map((s) => s.trim())
+                .find((s) => s && existsSync(s));
+            if (resolved)
+                return resolved;
+        }
+        catch {
+            // Not resolvable via PATH — fall through to bare name.
+        }
+        return isWin ? 'claude.exe' : 'claude';
+    }
+    /**
+     * 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) {
+        const env = this.buildEnv();
+        const bin = this.resolveClaudeBinary(env, opts.binaryPathOverride);
+        const handle = randomUUID();
+        const ptyProcess = pty.spawn(bin, opts.args, {
+            name: 'xterm-256color',
+            cols: opts.cols ?? 120,
+            rows: opts.rows ?? 40,
+            cwd: opts.cwd,
+            env,
+        });
+        this.sessions.set(handle, { pty: ptyProcess, handle, createdAt: Date.now() });
+        log.info(`CLI PTY spawned: handle=${handle} bin=${bin} args=[${opts.args.join(' ')}] cwd=${opts.cwd ?? '(inherit)'}`);
+        return { handle, pty: ptyProcess };
+    }
+    /** Attach the watcher teardown so dispose() tears down PTY + watcher together. */
+    registerDisposer(handle, dispose) {
+        const entry = this.sessions.get(handle);
+        if (entry)
+            entry.dispose = dispose;
+    }
+    /** Send Ctrl+C (interrupt) to the PTY without killing it. */
+    interrupt(handle) {
+        const entry = this.sessions.get(handle);
+        if (!entry)
+            return;
+        try {
+            entry.pty.write('\x03');
+        }
+        catch {
+            // PTY may already be gone.
+        }
+    }
+    /**
+     * 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) {
+        const entry = this.sessions.get(handle);
+        if (!entry)
+            return;
+        this.sessions.delete(handle);
+        try {
+            entry.dispose?.();
+        }
+        catch {
+            // Watcher teardown best-effort.
+        }
+        try {
+            entry.pty.kill();
+        }
+        catch {
+            // PTY may already be dead / ConPTY shutdown noise — ignore.
+        }
+        log.debug(`CLI PTY disposed: handle=${handle}`);
+    }
+    /** Destroy every CLI PTY (server shutdown). Symmetric with ptyService.destroyAll. */
+    destroyAll() {
+        if (this.sessions.size > 0) {
+            log.info(`Destroying all CLI PTYs (${this.sessions.size} active)`);
+        }
+        for (const handle of [...this.sessions.keys()]) {
+            this.dispose(handle);
+        }
+    }
+    /** Number of live CLI PTYs (for tests / introspection). */
+    get size() {
+        return this.sessions.size;
+    }
+    /** Whether a handle is still live in the pool. */
+    has(handle) {
+        return this.sessions.has(handle);
+    }
+}
+/** Module singleton — isolated from the web terminal pool (`ptyService`). */
+export const cliSessionPool = new CliSessionPool();
+//# sourceMappingURL=cliSessionPool.js.map

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * CLI spinner-progress grid reader (Epic 37 — Story 37.2)
+ *
+ * Reads the generation "↓ N tokens" counter (and the optional leading "(Ns ·" elapsed
+ * clock) from a *settled screen grid* produced by the headless screen model (Story
+ * 37.1). This is the token data source that replaces the linear ANSI-stripped buffer
+ * scan: claude overwrites the spinner counter **in place** (the same screen cell), so a
+ * settled grid carries one final value per row — the "365" + "366" → "365366" fusion
+ * the linear path suffered is **structurally impossible**, and the old fusion-defense
+ * guards (digit cap, malformed-grouping, implausible-jump) are no longer needed.
+ *
+ * Pure — input is the grid rows, output is the parsed progress or null. The CLI engine
+ * schedules a `flush()` and then calls this on the settled grid; the callback contract
+ * (`{ tokens, elapsedSeconds }`, emit-on-change) is unchanged.
+ *
+ * @see docs/stories/37.2.story.md
+ * [Source: docs/prd/epic-37-cli-terminal-emulation.md#story-372]
+ */
+export interface SpinnerProgress {
+    tokens: number;
+    elapsedSeconds: number;
+    /**
+     * True only when this spinner frame is in the THINKING phase (status segment reads
+     * "… · [still ]thinking …" after the token counter). Additive/optional — ABSENT means
+     * "not a recognized thinking phase" (generic generation), so existing callers/tests that
+     * read just `{ tokens, elapsedSeconds }` are unaffected. The client uses it to label the
+     * live progress indicator "Thinking…" (Story 37.11 AC1, achievable tier). See THINKING_PHASE_RE.
+     */
+    thinking?: boolean;
+}
+/**
+ * Read the freshest spinner counter from a settled screen grid. Returns null when no
+ * counter row is present (e.g. a thinking-phase spinner with no "↓ N tokens") — the
+ * caller treats null as "no emit", preserving the false-0 guard.
+ *
+ * Since claude overwrites the same cell, a settled grid has at most one counter row; if
+ * more than one matches, the BOTTOM-most (freshest rendered) row wins. Rows are never
+ * merged or concatenated — a single row already holds the whole current value.
+ */
+export declare function readSpinnerProgress(grid: string[]): SpinnerProgress | null;
+//# sourceMappingURL=cliSpinnerProgress.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cliSpinnerProgress.d.ts","sourceRoot":"","sources":["../../src/services/cliSpinnerProgress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAqEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,GAAG,IAAI,CAoC1E"}

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

@@ -0,0 +1,131 @@
+/**
+ * CLI spinner-progress grid reader (Epic 37 — Story 37.2)
+ *
+ * Reads the generation "↓ N tokens" counter (and the optional leading "(Ns ·" elapsed
+ * clock) from a *settled screen grid* produced by the headless screen model (Story
+ * 37.1). This is the token data source that replaces the linear ANSI-stripped buffer
+ * scan: claude overwrites the spinner counter **in place** (the same screen cell), so a
+ * settled grid carries one final value per row — the "365" + "366" → "365366" fusion
+ * the linear path suffered is **structurally impossible**, and the old fusion-defense
+ * guards (digit cap, malformed-grouping, implausible-jump) are no longer needed.
+ *
+ * Pure — input is the grid rows, output is the parsed progress or null. The CLI engine
+ * schedules a `flush()` and then calls this on the settled grid; the callback contract
+ * (`{ tokens, elapsedSeconds }`, emit-on-change) is unchanged.
+ *
+ * @see docs/stories/37.2.story.md
+ * [Source: docs/prd/epic-37-cli-terminal-emulation.md#story-372]
+ */
+import { liveFooterRows } from './cliGridRegion.js';
+/**
+ * The spinner counter as RENDERED in the grid. Captures both the raw ("↓ 108 tokens")
+ * and abbreviated ("↓ 1.4k tokens") shapes claude paints — matching the Story 37.1
+ * realframes counter regex `↓ ?[\d.,]+k? tokens`. The old linear CLI_PROGRESS_RE used
+ * `[\d,]+`, which breaks at `.`/`k` and so MISSED the abbreviated form entirely; reading
+ * the grid lets us capture it. The rotating glyph word (Flowing…/Crunched/Brewed/
+ * Moseying…) is deliberately NOT part of the match — it is version-fragile, so the row
+ * is identified by the counter alone.
+ *
+ * Both arrow directions are accepted (`[↑↓]`): claude renders the counter as "↓ N tokens"
+ * for some phases and "↑ N tokens" for others (실측 2026-06-14 — a long step showed
+ * "↑ 95.6k tokens"). The ↓-only regex MISSED the ↑ form, so a long ↑-phase emitted no
+ * progress at all and the UI looked frozen ("멈춤 vs 느림" 구분 불가). The arrow is required
+ * (not optional) so a bare "N tokens" in prose can't flash a phantom counter.
+ */
+const GRID_COUNTER_RE = /[↑↓]\s*([\d.,]+k?)\s*tokens/i;
+/**
+ * The leading elapsed clock, paren-anchored (Story 37.3 — "Xm Ys" summation). claude
+ * renders the clock as the FIRST thing after the spinner's "(" — either bare seconds
+ * "(9s ·" or a minute form "(1m 36s ·". Both the minute and second segments are optional
+ * and captured separately; an absent segment counts as 0, so bare seconds preserve their
+ * old value ("9s" → 9) and a missing clock yields 0. The "(" anchor is load-bearing: the
+ * time is always rendered right after the opening paren, so anchoring keeps a counter or
+ * prose number ("↓ 365 tokens", "thinking") from being mistaken for the clock.
+ */
+const GRID_ELAPSED_RE = /\((?:(\d+)m\s*)?(?:(\d+)s\b)?/;
+/**
+ * The THINKING-phase status segment claude renders INSIDE the spinner's paren group, AFTER the
+ * token counter: "↓ 143 tokens · thinking with high effort)" / "· still thinking with high effort)"
+ * (실측 2026-06-16, verbose:on AND verbose:off real PTY — `cli-verbose-on/off-long-thinking` fixtures).
+ *
+ * Why a *phase* flag and not a body thinking card: in verbose:true mode (Hammoc's spawn) claude paints
+ * NO live thinking *content* into the screen body — only this bottom spinner advances (elapsed clock +
+ * token counter + this phrase); the reasoning block lands WHOLE at completion. So the only live
+ * "Claude is thinking" signal is this spinner segment. Surfacing it lets the client LABEL the
+ * already-live generation-progress indicator as "Thinking…" (vs generic generation) WITHOUT inventing
+ * a card from the version-fragile, region-EXCLUDED footer spinner (which `scrollbackBodyRows` drops to
+ * avoid resume-repaint poisoning).
+ *
+ * Anchored `tokens … thinking` WITHIN the paren (`[^)]*`, no `)` crossing) so a rotating gerund word
+ * BEFORE the counter (a hypothetical "Thinking…" spinner glyph) can't false-positive — only the
+ * post-counter phase label counts. Effort-suffix agnostic ("with high effort" optional). A
+ * response-phase row ("↓ 1.3k tokens)") carries no such segment → not thinking.
+ */
+const THINKING_PHASE_RE = /\btokens\b[^)]*\bthinking\b/i;
+/**
+ * Sum the paren-anchored elapsed clock on a spinner row to integer seconds. Pure — input
+ * is the rendered row, output is `minutes * 60 + seconds`. A minute form "(1m 36s ·" → 96,
+ * bare seconds "(9s ·" → 9 (minutes default to 0), and a row with no clock segment → 0
+ * (Story 37.3 AC3). Hour ("Xh") forms are unobserved and out of scope; if claude ever
+ * renders them, the same anchored-sum pattern extends. The grid overwrites the spinner
+ * cell in place, so an in-place "(1m 36s" → "(1m 37s" redraw reads as the latest value
+ * (97), never a fused "136137" — fusion is structurally impossible here too.
+ */
+function sumElapsedSeconds(row) {
+    const m = GRID_ELAPSED_RE.exec(row);
+    if (!m)
+        return 0;
+    const minutes = m[1] ? parseInt(m[1], 10) : 0;
+    const seconds = m[2] ? parseInt(m[2], 10) : 0;
+    return minutes * 60 + seconds;
+}
+/**
+ * Read the freshest spinner counter from a settled screen grid. Returns null when no
+ * counter row is present (e.g. a thinking-phase spinner with no "↓ N tokens") — the
+ * caller treats null as "no emit", preserving the false-0 guard.
+ *
+ * Since claude overwrites the same cell, a settled grid has at most one counter row; if
+ * more than one matches, the BOTTOM-most (freshest rendered) row wins. Rows are never
+ * merged or concatenated — a single row already holds the whole current value.
+ */
+export function readSpinnerProgress(grid) {
+    // Live region only: the spinner counter renders at the bottom of the screen, so a "↓ N tokens"
+    // value QUOTED in resume-repaint scrollback can't flash a phantom counter during the pre-generation
+    // thinking phase (no live counter row yet). Bottom-most (freshest) within the region wins.
+    const region = liveFooterRows(grid);
+    for (let y = region.length - 1; y >= 0; y--) {
+        const counter = GRID_COUNTER_RE.exec(region[y]);
+        if (!counter)
+            continue;
+        const raw = counter[1];
+        // Normalize to an integer token count: strip thousands separators, then expand a
+        // "k" suffix ("1.4k" → 1400). The grid never fuses values, so this is plain parsing.
+        const tokens = /k$/i.test(raw)
+            ? Math.round(parseFloat(raw.slice(0, -1).replace(/,/g, '')) * 1000)
+            : parseInt(raw.replace(/,/g, ''), 10);
+        if (!Number.isFinite(tokens))
+            return null;
+        // Phase label rides the SAME counter row we already matched (no extra scan, same region —
+        // so no new resume-poisoning surface). Set only when true to keep the shape additive.
+        const thinking = THINKING_PHASE_RE.test(region[y]);
+        return { tokens, elapsedSeconds: sumElapsedSeconds(region[y]), ...(thinking ? { thinking: true } : {}) };
+    }
+    // Fallback: no token counter yet, but an elapsed clock is on screen → emit time-only (tokens 0). claude
+    // paints "(Ns ·" the moment generation starts, BEFORE the first "↓ N tokens" counter appears — without
+    // this the live timer stays frozen until tokens show up (the token-less "(12s" the user saw not parsed).
+    // Require a real minute/second digit (GRID_ELAPSED_RE leaves both groups undefined for a bare "("), so a
+    // stray paren in prose can't flash a phantom. Bottom-most (freshest) within the live region wins.
+    for (let y = region.length - 1; y >= 0; y--) {
+        // A counter ARROW on the row means a counter is mid-write ("↓ 36" before "tokens" settles, split across
+        // PTY chunks) — wait for it to settle rather than flashing a time-only reading. Fall back ONLY when the
+        // row carries no counter glyph at all (the genuine pre-counter "(12s" before any counter appears).
+        if (/[↑↓]/.test(region[y]))
+            continue;
+        const m = GRID_ELAPSED_RE.exec(region[y]);
+        if (m && (m[1] !== undefined || m[2] !== undefined)) {
+            return { tokens: 0, elapsedSeconds: sumElapsedSeconds(region[y]) };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=cliSpinnerProgress.js.map

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

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

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

@@ -0,0 +1,46 @@
+/**
+ * Shared standalone file-rewind mechanism (Epic 32 — Story 32.5).
+ *
+ * `rewindSessionFiles` is the SINGLE billing-neutral rewind primitive that BOTH
+ * conversation engines delegate to — `ChatService` (SDK mode) and `CliChatEngine`
+ * (CLI / subscription-pool mode). It was extracted verbatim from the mechanism
+ * Story 32.3 placed in `ChatService.rewindFiles` so the `--session-id`+`--resume`
+ * footgun guard lives in exactly one place (no comment drift, no chance a later
+ * edit re-adds `sessionId` to one engine but not the other).
+ *
+ * Why CLI mode may reuse an SDK `query()` here even though Epic 32 exists to keep
+ * conversation streaming OFF the SDK billing path: **rewind is a file-checkpoint
+ * operation with no model call — 0 tokens.** A throwaway `query({ prompt: '' })`
+ * is resumed only to drive its file-rewind control request; its async iterator is
+ * never consumed, so no turn is ever sent to the model. Verified against real
+ * claude (Story 32.5 AC4): rewinding a CLI-created session moved session/weekly
+ * utilization by 0 and returned in ~2s (file op, not a model round-trip). Billing
+ * is by *token usage*, so a 0-token rewind is neutral regardless of engine.
+ *
+ * This is therefore the documented exception to the 32.4 rule "the CLI engine does
+ * not spawn the SDK directly": it is allowed precisely because it costs nothing.
+ * It is also the ONLY programmatic rewind path — interactive claude exposes no
+ * non-interactive rewind flag (`claude --help`: only `--resume`/`--continue`/
+ * `--fork-session`/`--session-id`), its `/rewind` command is a full-screen ANSI
+ * picker, and the SDK control-protocol rewind is headless-stream-json only.
+ *
+ * [Source: packages/server/src/services/chatService.ts (32.3 mechanism);
+ *  docs/stories/32.5.story.md#AC1-AC3; node_modules/@anthropic-ai/claude-agent-sdk/sdk.d.ts:2290-2300]
+ */
+import { type RewindFilesResult } from '@anthropic-ai/claude-agent-sdk';
+/**
+ * Rewind tracked files for `sessionId` to their state at `messageUuid`. `dryRun`
+ * previews the change (returns file stats) without writing. Returns the SDK's
+ * `RewindFilesResult` verbatim (`canRewind` + optional `error`/file stats) so the
+ * `session:rewind-files` handler maps it to the wire identically for either engine.
+ *
+ * @param cwd Project working directory — locates the session JSONL + tracked files.
+ *            Pass `undefined` only when unknown; the dirty-marker side effect is then
+ *            skipped (the SDK still resolves a cwd, but cannot be flagged for cleanup).
+ */
+export declare function rewindSessionFiles(params: {
+    sessionId: string;
+    messageUuid: string;
+    dryRun?: boolean;
+}, cwd: string | undefined): Promise<RewindFilesResult>;
+//# sourceMappingURL=fileRewind.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fileRewind.d.ts","sourceRoot":"","sources":["../../src/services/fileRewind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAS,KAAK,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAM/E;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EACpE,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,OAAO,CAAC,iBAAiB,CAAC,CA4B5B"}

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

@@ -0,0 +1,77 @@
+/**
+ * Shared standalone file-rewind mechanism (Epic 32 — Story 32.5).
+ *
+ * `rewindSessionFiles` is the SINGLE billing-neutral rewind primitive that BOTH
+ * conversation engines delegate to — `ChatService` (SDK mode) and `CliChatEngine`
+ * (CLI / subscription-pool mode). It was extracted verbatim from the mechanism
+ * Story 32.3 placed in `ChatService.rewindFiles` so the `--session-id`+`--resume`
+ * footgun guard lives in exactly one place (no comment drift, no chance a later
+ * edit re-adds `sessionId` to one engine but not the other).
+ *
+ * Why CLI mode may reuse an SDK `query()` here even though Epic 32 exists to keep
+ * conversation streaming OFF the SDK billing path: **rewind is a file-checkpoint
+ * operation with no model call — 0 tokens.** A throwaway `query({ prompt: '' })`
+ * is resumed only to drive its file-rewind control request; its async iterator is
+ * never consumed, so no turn is ever sent to the model. Verified against real
+ * claude (Story 32.5 AC4): rewinding a CLI-created session moved session/weekly
+ * utilization by 0 and returned in ~2s (file op, not a model round-trip). Billing
+ * is by *token usage*, so a 0-token rewind is neutral regardless of engine.
+ *
+ * This is therefore the documented exception to the 32.4 rule "the CLI engine does
+ * not spawn the SDK directly": it is allowed precisely because it costs nothing.
+ * It is also the ONLY programmatic rewind path — interactive claude exposes no
+ * non-interactive rewind flag (`claude --help`: only `--resume`/`--continue`/
+ * `--fork-session`/`--session-id`), its `/rewind` command is a full-screen ANSI
+ * picker, and the SDK control-protocol rewind is headless-stream-json only.
+ *
+ * [Source: packages/server/src/services/chatService.ts (32.3 mechanism);
+ *  docs/stories/32.5.story.md#AC1-AC3; node_modules/@anthropic-ai/claude-agent-sdk/sdk.d.ts:2290-2300]
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { SessionService } from './sessionService.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('fileRewind');
+/**
+ * Rewind tracked files for `sessionId` to their state at `messageUuid`. `dryRun`
+ * previews the change (returns file stats) without writing. Returns the SDK's
+ * `RewindFilesResult` verbatim (`canRewind` + optional `error`/file stats) so the
+ * `session:rewind-files` handler maps it to the wire identically for either engine.
+ *
+ * @param cwd Project working directory — locates the session JSONL + tracked files.
+ *            Pass `undefined` only when unknown; the dirty-marker side effect is then
+ *            skipped (the SDK still resolves a cwd, but cannot be flagged for cleanup).
+ */
+export async function rewindSessionFiles(params, cwd) {
+    const { sessionId, messageUuid, dryRun } = params;
+    const rewindQuery = query({
+        prompt: '',
+        options: {
+            resume: sessionId,
+            cwd,
+            enableFileCheckpointing: true,
+            // Do NOT pass sessionId here — CLI rejects --session-id combined with
+            // --resume unless --fork-session is also set. resume: sessionId already
+            // identifies the session.
+        },
+    });
+    try {
+        const result = await rewindQuery.rewindFiles(messageUuid, { dryRun: !!dryRun });
+        log.info(`rewindFiles result: canRewind=${result.canRewind}, filesChanged=${result.filesChanged?.length ?? 0}, insertions=${result.insertions ?? 0}, deletions=${result.deletions ?? 0}`);
+        return result;
+    }
+    finally {
+        // Mark session as dirty BEFORE close — the throwaway query({ prompt: '' })
+        // leaves an empty user message in the JSONL. On the SDK send path that empty
+        // message triggers cache_control 400, so cleanRewindDirty strips it before the
+        // next SDK resume. (Interactive claude --resume tolerates it — verified Story
+        // 32.5 AC4 — so the CLI engine does not clean; any later SDK resume self-heals.)
+        if (cwd)
+            new SessionService().markRewindDirty(cwd, sessionId);
+        // Clean up the throwaway query object.
+        try {
+            rewindQuery.close();
+        }
+        catch { /* best-effort */ }
+    }
+}
+//# sourceMappingURL=fileRewind.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fileRewind.js","sourceRoot":"","sources":["../../src/services/fileRewind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,KAAK,EAA0B,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,GAAG,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;AAEvC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAoE,EACpE,GAAuB;IAEvB,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAClD,MAAM,WAAW,GAAG,KAAK,CAAC;QACxB,MAAM,EAAE,EAAE;QACV,OAAO,EAAE;YACP,MAAM,EAAE,SAAS;YACjB,GAAG;YACH,uBAAuB,EAAE,IAAI;YAC7B,sEAAsE;YACtE,wEAAwE;YACxE,0BAA0B;SAC3B;KACF,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAChF,GAAG,CAAC,IAAI,CAAC,iCAAiC,MAAM,CAAC,SAAS,kBAAkB,MAAM,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,gBAAgB,MAAM,CAAC,UAAU,IAAI,CAAC,eAAe,MAAM,CAAC,SAAS,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1L,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,2EAA2E;QAC3E,6EAA6E;QAC7E,+EAA+E;QAC/E,8EAA8E;QAC9E,iFAAiF;QACjF,IAAI,GAAG;YAAE,IAAI,cAAc,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC9D,uCAAuC;QACvC,IAAI,CAAC;YAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC"}

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

@@ -37,6 +37,17 @@ export declare function parseJSONLSessionMeta(filePath: string): Promise<{
  * @returns Sorted array of messages in conversation order
  */
 export declare function sortMessagesByParentUuid(messages: RawJSONLMessage[]): RawJSONLMessage[];
+/**
+ * Check if content is a task-notification message inserted by the SDK
+ * @param content The raw message content
+ * @returns Parsed task notification data, or null if not a task notification
+ */
+export declare function parseTaskNotification(content: string): {
+    taskId: string;
+    status: 'completed' | 'failed' | 'stopped';
+    summary: string;
+    toolUseId?: string;
+} | null;
 /**
  * Clean up command tags from user messages.
  * Converts "<command-message>X</command-message>\n<command-name>/Y</command-name>\n<command-args>Z</command-args>"

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

@@ -1 +1 @@
-{"version":3,"file":"historyParser.d.ts","sourceRoot":"","sources":["../../src/services/historyParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAQf,MAAM,gBAAgB,CAAC;AASxB;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAwBjF;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAuE7E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAqCvF;AA+HD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAuBxD;AAkDD,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,eAAe,EAAE,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CA2T7H"}
+{"version":3,"file":"historyParser.d.ts","sourceRoot":"","sources":["../../src/services/historyParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAQf,MAAM,gBAAgB,CAAC;AAUxB;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAwBjF;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAuE7E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAqCvF;AAqGD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAqBjK;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAuBxD;AAkDD,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,eAAe,EAAE,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CA0T7H"}