@lucascouts/claude-agent-tui 0.1.0

package/dist/end-of-turn.js

@@ -0,0 +1,415 @@
+// === Story 024 — End-of-turn detector (E3 augmented predicate + Δt quiescence + turn watchdog) ===
+//
+// The forked engine drives the real `claude` TUI in a PTY and reads turns from the JSONL transcript
+// (story 023). The pure TUI never emits `session_state_changed:state='idle'`, so there is NO native
+// end-of-turn signal. This module implements the E3-derived heuristic that tells the rewritten
+// `prompt()` loop when a turn ends, so it can resolve the ACP `PromptResponse{stopReason}` exactly
+// once per turn (§5 BLOCKER, R2). Δt, the predicate, and the turn watchdog are consumed VERBATIM
+// from the Degrau-0 E3 binding decision (experiments/DEGRAU0-RESULTS.md, Binding decision 2) — this
+// module IMPLEMENTS them, it does NOT re-derive them.
+//
+// Task 1.1 — the terminal-stop predicate: the pure core that identifies the single terminal-stop
+// `assistant` boundary candidate per turn.
+import { TURN_WATCHDOG_MS } from "./linearize.js";
+import { FILE_DISCOVERY_WATCHDOG_MS } from "./jsonl.js";
+import { mapStopReason } from "./stop-reason-map.js";
+// Re-export the two watchdog windows from their OWNING modules so the detector exposes a single
+// source of truth: the turn watchdog (5583 ms) lives in linearize.ts (story 017), the file-discovery
+// watchdog (2000 ms) in jsonl.ts. Re-exporting — never re-declaring — guarantees the two windows can
+// neither drift apart nor be conflated (the §13 R2-vs-R3 Constraint the story forbids breaking).
+export { TURN_WATCHDOG_MS, FILE_DISCOVERY_WATCHDOG_MS };
+// === Story 034 (live-acceptance fix) — STALL semantics ============================================
+//
+// The G1 live acceptance (2026-06-11, session 9cedb4c2) faulted a REAL first turn at 5583 ms: E3
+// calibrated that window on trivial Degrau-0 turns as a TOTAL-turn cap, but live turns legitimately
+// exceed it (cold start, thinking, long tools) and the JSONL writes whole blocks, so long silent
+// gaps are normal mid-turn. Corrected semantics: the watchdog re-arms on every observed event
+// (activity = liveness) and trips only after `watchdogMs` of total SILENCE. TURN_WATCHDOG_MS stays
+// exported as the E3 constant (story 017 cadence + explicit option), but is no longer the default.
+/**
+ * Default STALL window (ms): the watchdog trips only after this much transcript silence while a
+ * turn is in flight. Generous on purpose — a long text block or tool run writes nothing for tens of
+ * seconds; the watchdog exists to fail a DEAD turn loudly (R5.2), not to cap a slow one.
+ */
+export const TURN_STALL_WATCHDOG_MS = 120_000;
+/** Env var overriding the default stall window per process (positive integer ms). */
+export const TURN_WATCHDOG_ENV = "FORK_TURN_WATCHDOG_MS";
+/** The default stall window: the {@link TURN_WATCHDOG_ENV} override when valid, else the constant. */
+function resolveDefaultWatchdogMs() {
+    const raw = process.env[TURN_WATCHDOG_ENV];
+    if (raw !== undefined && raw !== "") {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return TURN_STALL_WATCHDOG_MS;
+}
+/**
+ * The TERMINAL `message.stop_reason` values (E3 augmented predicate, Binding decision 2). An
+ * `assistant` event whose stop_reason is one of these is an end-of-turn boundary CANDIDATE; a
+ * `tool_use` pause (or `null`) is mid-turn and NOT a boundary. Typed `ReadonlySet` so the set
+ * cannot drift at a call site.
+ */
+export const TERMINAL_STOP_REASONS = new Set([
+    "end_turn",
+    "stop_sequence",
+    "max_tokens",
+]);
+/** True iff `value` is a non-null, non-array object — the guard before any property read. */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether `event` is a sidechain (subagent) row (story 041, R4.1). A subagent's transcript rows
+ * carry a non-null `parent_tool_use_id` (SDK snake_case) / `parentToolUseId` (story-015 typed name)
+ * pointing up to the spawning Task `tool_use` — the SAME canonical signal `linearize.ts`
+ * (`isSidechainMsg`) uses. A sidechain assistant row's OWN `stop_reason:'end_turn'` is the
+ * SUBAGENT's turn ending, NOT the parent's, so it must be excluded from terminal candidacy: it can
+ * never resolve the parent turn even if it reaches the detector.
+ */
+function isSidechain(event) {
+    if (!isObject(event))
+        return false;
+    const pid = event.parent_tool_use_id ?? event.parentToolUseId;
+    return pid !== null && pid !== undefined;
+}
+// === Story 041 / Task 4.2 — an in-flight Task/Agent tool_use holds the turn OPEN (R4.2) ===========
+//
+// A main-chain `Task`/`Agent` `tool_use` spawns a sub-agent whose work can run silently for a long
+// time (cold start, long tools, deep nesting). While that `tool_use` has NO matching `tool_result`
+// yet, the turn is IN-FLIGHT: the silence watchdog must NOT trip and no end-of-turn may resolve,
+// however long the sub-agent runs. The detector feed is main-chain-only (the pump never advances the
+// detector cursor for sidechain rows — R4.1 structural), so this open-Task scan runs over main-chain
+// rows: it reads `tool_use` blocks named `Task`/`Agent` off assistant rows and the `tool_result`
+// blocks (`tool_use_id`) that close them off user rows.
+/** The sub-agent-spawning tool names whose open `tool_use` holds the parent turn open (R4.2). */
+const SUBAGENT_TOOL_NAMES = new Set(["Task", "Agent"]);
+/** The `message.content[]` array of an event when present, else `[]` — read defensively (§6). */
+function contentBlocksOf(event) {
+    const message = event.message;
+    if (!isObject(message))
+        return [];
+    const content = message.content;
+    return Array.isArray(content) ? content : [];
+}
+/**
+ * The ids of sub-agent-spawning (`Task`/`Agent`) `tool_use` blocks in `event` (R4.2). A non-assistant
+ * row, a string/missing `content`, or any non-`Task`/`Agent` `tool_use` (e.g. `Bash`) yields none —
+ * so an ordinary tool call never holds the turn. Pure; never throws.
+ */
+function subagentToolUseIds(event) {
+    if (!isObject(event) || event.type !== "assistant")
+        return [];
+    const ids = [];
+    for (const block of contentBlocksOf(event)) {
+        if (isObject(block) &&
+            block.type === "tool_use" &&
+            typeof block.id === "string" &&
+            typeof block.name === "string" &&
+            SUBAGENT_TOOL_NAMES.has(block.name)) {
+            ids.push(block.id);
+        }
+    }
+    return ids;
+}
+/**
+ * The `tool_use_id`s closed by `tool_result` blocks in `event` (R4.2) — the back-reference the SDK
+ * writes on the user row that carries a sub-agent's result (`tool_result.tool_use_id === id`, the
+ * same field `event-switch.ts` models). A non-object/string `content` yields none. Pure; never throws.
+ */
+function closedToolUseIds(event) {
+    const ids = [];
+    for (const block of contentBlocksOf(event)) {
+        if (isObject(block) && block.type === "tool_result" && typeof block.tool_use_id === "string") {
+            ids.push(block.tool_use_id);
+        }
+    }
+    return ids;
+}
+/**
+ * The E3 augmented predicate (Binding decision 2): is `event` an `assistant` event whose
+ * `message.stop_reason` is a TERMINAL value? Reads everything defensively — a non-`assistant`
+ * `.type`, a missing/string `message`, or a `null`/`undefined`/`tool_use` stop_reason all yield
+ * `false`. Pure and total: never throws.
+ *
+ * Story 041 (R4.1): a SIDECHAIN row (non-null `parent_tool_use_id`) is EXCLUDED — its terminal stop
+ * is the subagent's own turn ending and must never end the parent turn.
+ */
+export function isTerminalStop(event) {
+    if (!isObject(event))
+        return false;
+    if (event.type !== "assistant")
+        return false;
+    if (isSidechain(event))
+        return false; // R4.1: a sidechain terminal stop never ends the parent turn
+    const message = event.message;
+    if (!isObject(message))
+        return false;
+    const stopReason = message.stop_reason;
+    return typeof stopReason === "string" && TERMINAL_STOP_REASONS.has(stopReason);
+}
+/**
+ * The LAST event in `events` satisfying {@link isTerminalStop} — the single per-turn boundary
+ * candidate (E3 picks the LAST terminal `assistant`, so a turn that streamed several assistant
+ * blocks collapses to one boundary). Returns `undefined` when no event is terminal (e.g. a
+ * `tool_use`-only turn still in flight). Pure; never throws on an unknown `.type` or string content.
+ */
+export function findTerminalCandidate(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        if (isTerminalStop(events[i]))
+            return events[i];
+    }
+    return undefined;
+}
+// === Task 2 — Δt quiescence window + queued-prompt confirmation ===================================
+/**
+ * The Δt quiescence window (ms) — E3 binding decision 2: the SMALLEST zero-false-positive window
+ * (Δt sweep, experiments/DECISION.md). A terminal candidate is confirmed only after Δt of silence
+ * with no further user/assistant write. Consumed VERBATIM from E3 — NOT re-derived here.
+ */
+export const DELTA_T_MS = 200;
+const defaultSchedule = (fn, ms) => {
+    const handle = setTimeout(fn, ms);
+    // Don't let an armed turn timer keep the process alive on its own.
+    handle.unref?.();
+    return () => clearTimeout(handle);
+};
+/**
+ * Typed error surfaced when no end-of-turn is detected within the 5583 ms turn watchdog (R5.2). It
+ * carries the elapsed window plus last-seen-event diagnostics so the §5 stall is observable for R2
+ * runtime telemetry instead of hanging the ACP protocol silently.
+ */
+export class TurnTimeoutError extends Error {
+    constructor(diag) {
+        super(`end-of-turn not detected within ${diag.elapsedMs}ms turn watchdog` +
+            (diag.sessionId ? ` (session ${diag.sessionId})` : "") +
+            (diag.lastEventType
+                ? `; last event type=${diag.lastEventType} stop_reason=${diag.lastStopReason ?? "null"}`
+                : ""));
+        this.name = "TurnTimeoutError";
+        this.elapsedMs = diag.elapsedMs;
+        this.lastEventType = diag.lastEventType;
+        this.lastStopReason = diag.lastStopReason;
+        this.sessionId = diag.sessionId;
+    }
+}
+/** The `uuid` of an event when it is a non-empty string — the per-turn `fired` latch key. */
+function eventUuid(event) {
+    const uuid = event.uuid;
+    return typeof uuid === "string" && uuid.length > 0 ? uuid : undefined;
+}
+/** True for a `user` or `assistant` write — the only events that confirm a queued boundary (R4). */
+function isUserOrAssistantWrite(event) {
+    return isObject(event) && (event.type === "user" || event.type === "assistant");
+}
+/** Last-seen-event diagnostics for a {@link TurnTimeoutError} (`.type` + `message.stop_reason`). */
+function eventDiag(event) {
+    if (!isObject(event))
+        return {};
+    const lastEventType = typeof event.type === "string" ? event.type : undefined;
+    const message = event.message;
+    const lastStopReason = isObject(message) && typeof message.stop_reason === "string" ? message.stop_reason : undefined;
+    return { lastEventType, lastStopReason };
+}
+/**
+ * The end-of-turn detector: feed it the linearized turn events via {@link EndOfTurnDetector.observe}
+ * and it emits exactly one end-of-turn per turn. A terminal candidate (Task 1) arms a Δt timer; the
+ * boundary is confirmed on Δt quiescence (here) or immediately on a queued follow-up write (Task 2.2).
+ * A `fired` latch keyed on the boundary uuid prevents the same terminal event from firing twice.
+ */
+export function createEndOfTurnDetector(opts) {
+    const schedule = opts.schedule ?? defaultSchedule;
+    const deltaTMs = opts.deltaTMs ?? DELTA_T_MS;
+    const watchdogMs = opts.watchdogMs ?? resolveDefaultWatchdogMs();
+    let pendingCandidate;
+    let cancelDelta;
+    let cancelWatchdog;
+    let lastEvent; // last event seen — diagnostics for a watchdog timeout
+    const firedUuids = new Set();
+    // Story 041 (R4.2): main-chain `Task`/`Agent` `tool_use` ids with no matching `tool_result` yet.
+    // While this set is non-empty a sub-agent is in flight, so the silence watchdog HOLDS (re-arms)
+    // instead of tripping — a long, silent sub-agent run must not cause a false end-of-turn.
+    const openTaskIds = new Set();
+    let stopped = false;
+    let cancelled = false; // single-resolution cancel latch (markCancelled — story 030 seam)
+    function clearDelta() {
+        cancelDelta?.();
+        cancelDelta = undefined;
+    }
+    /** Clear the armed turn watchdog so it cannot fire for a turn that already resolved (R5.3). */
+    function clearWatchdog() {
+        cancelWatchdog?.();
+        cancelWatchdog = undefined;
+    }
+    function confirmBoundary() {
+        if (cancelled)
+            return; // cancel latch (R3.4): never emit an end-of-turn for a cancelled turn
+        const boundary = pendingCandidate;
+        if (!boundary)
+            return;
+        // Latch BEFORE emit: clear the pending candidate so a re-entrant observe() inside the
+        // onEndOfTurn callback cannot double-confirm the same turn.
+        pendingCandidate = undefined;
+        clearDelta();
+        clearWatchdog(); // end-of-turn resolved → the watchdog must not fire for this turn (R5.3)
+        openTaskIds.clear(); // R4.2: a resolved turn starts the next one with no stale open Task
+        const uuid = eventUuid(boundary);
+        if (uuid)
+            firedUuids.add(uuid);
+        opts.onEndOfTurn(boundary);
+    }
+    function armDelta() {
+        clearDelta();
+        cancelDelta = schedule(() => {
+            cancelDelta = undefined;
+            confirmBoundary();
+        }, deltaTMs);
+    }
+    /**
+     * (Re)arm the stall watchdog: if no end-of-turn confirms within `watchdogMs` of SILENCE, the turn
+     * is failed loudly (Task 3.2 / story-034 stall semantics) instead of hanging the ACP protocol
+     * (§5 BLOCKER, R5.2). Called at turn start and again on every observed event (activity = liveness).
+     */
+    function armWatchdog() {
+        clearWatchdog();
+        cancelWatchdog = schedule(() => {
+            cancelWatchdog = undefined;
+            // Story 041 (R4.2): a main-chain `Task`/`Agent` `tool_use` is still open (no `tool_result`),
+            // so a sub-agent is in flight. The silence is EXPECTED — HOLD the turn by re-arming the
+            // watchdog instead of failing it. Without this, a long, silent sub-agent run would falsely
+            // trip the stall watchdog and resolve the turn early. The hold is bounded by the eventual
+            // `tool_result` (which empties `openTaskIds`) or a real main-chain terminal stop.
+            if (openTaskIds.size > 0) {
+                armWatchdog();
+                return;
+            }
+            const error = new TurnTimeoutError({
+                elapsedMs: watchdogMs,
+                sessionId: opts.sessionId,
+                ...eventDiag(lastEvent),
+            });
+            // R2 runtime telemetry — surface loudly via both channels; never swallow the stall.
+            opts.logger?.error("[end-of-turn] turn watchdog tripped:", error.message);
+            opts.onTurnTimeout?.(error);
+        }, watchdogMs);
+    }
+    return {
+        beginTurn() {
+            if (stopped || cancelled)
+                return;
+            armWatchdog();
+        },
+        observe(event) {
+            if (stopped || cancelled)
+                return;
+            lastEvent = event; // track for watchdog-timeout diagnostics (Task 3.2)
+            // Story 041 (R4.2): track open main-chain `Task`/`Agent` `tool_use`s. A sub-agent-spawning
+            // `tool_use` ADDS its id (the turn is now in flight on a sub-agent); a `tool_result` REMOVES
+            // every id it closes (`tool_use_id`). While `openTaskIds` is non-empty the watchdog HOLDS
+            // rather than trips (see armWatchdog). Order matters only across events, not within one row, so
+            // closing first then opening is fine: a row is never both the open and its own close.
+            for (const id of closedToolUseIds(event))
+                openTaskIds.delete(id);
+            for (const id of subagentToolUseIds(event))
+                openTaskIds.add(id);
+            // Story-034 stall semantics: a watched event is transcript ACTIVITY — the turn is alive, so
+            // push the silence deadline out. Only while in flight (armed): replay/load observes with no
+            // beginTurn and must never start a stall clock, and a cleared watchdog must stay cleared.
+            if (cancelWatchdog !== undefined)
+                armWatchdog();
+            // Queued-prompt / back-to-back (R4): a NEW user/assistant write arriving while a candidate is
+            // still pending (before Δt) confirms the PRIOR boundary immediately — cancelling the Δt timer —
+            // then a fresh detection cycle begins for `event` below. This is what keeps two back-to-back
+            // turns from merging into a single boundary.
+            if (pendingCandidate && event !== pendingCandidate && isUserOrAssistantWrite(event)) {
+                confirmBoundary();
+            }
+            if (isTerminalStop(event)) {
+                const uuid = eventUuid(event);
+                if (uuid && firedUuids.has(uuid))
+                    return; // duplicate of an already-fired turn → idempotent
+                pendingCandidate = event;
+                armDelta(); // (re)arm the Δt quiescence timer
+            }
+        },
+        noteActivity() {
+            // Story 044 (R1.2, Option B): liveness-only kick from the sub-agent watcher. Mirrors the
+            // activity re-arm inside observe() but registers NO event — no lastEvent, no openTaskIds
+            // mutation, no pendingCandidate/Δt bookkeeping. Re-arms only while in flight (armed): a
+            // replay/load kick never starts a stall clock, and a stopped/cancelled detector stays silent.
+            if (stopped || cancelled)
+                return;
+            if (cancelWatchdog !== undefined)
+                armWatchdog();
+        },
+        markCancelled() {
+            // Single-resolution cancel seam (R3.4): set the latch and clear both timers so the detector
+            // cannot also fire an end-of-turn for this turn. Read-only — the ACP session/cancel →
+            // PromptResponse{stopReason:'cancelled'} resolution and its §8 wiring are story 030, which
+            // calls this seam (latch here, resolution there — the two halves stay traceable).
+            cancelled = true;
+            clearDelta();
+            clearWatchdog();
+            pendingCandidate = undefined;
+            openTaskIds.clear(); // R4.2: a cancelled turn drops any in-flight Task hold
+        },
+        stop() {
+            stopped = true;
+            clearDelta();
+            clearWatchdog();
+            pendingCandidate = undefined;
+            openTaskIds.clear(); // R4.2: teardown drops any in-flight Task hold
+        },
+    };
+}
+// === Task 4.2 — resolve the pending session/prompt once per boundary =============================
+/** Read `event.message.stop_reason` defensively — the raw value {@link mapStopReason} consumes. */
+function readStopReason(event) {
+    const message = event.message;
+    return isObject(message) ? message.stop_reason : undefined;
+}
+/**
+ * Wrap the end-of-turn detector in the awaitable the rewritten `prompt()` loop (story 023) returns
+ * (R2). The promise stays pending across every mid-turn event and settles EXACTLY ONCE — resolving
+ * with `{ stopReason: mapStopReason(boundary.message.stop_reason) }` on the confirmed boundary, or
+ * rejecting with the surfaced {@link TurnTimeoutError} on a watchdog trip. A single-resolution latch
+ * makes a detector/watchdog/cancel race settle the prompt exactly once (and stops the detector so a
+ * late boundary cannot produce a second settlement).
+ */
+export function createTurnResolver(opts = {}) {
+    let settled = false;
+    let resolveFn;
+    let rejectFn;
+    const promise = new Promise((res, rej) => {
+        resolveFn = res;
+        rejectFn = rej;
+    });
+    // Single-resolution latch: a detector/watchdog/cancel race settles the prompt EXACTLY ONCE. The
+    // detector's own latches already clear its timers on confirm/timeout, so any late callback that
+    // still reaches `settle` is a harmless no-op.
+    function settle(action) {
+        if (settled)
+            return;
+        settled = true;
+        action();
+    }
+    const detector = createEndOfTurnDetector({
+        onEndOfTurn: (boundary) => settle(() => resolveFn({ stopReason: mapStopReason(readStopReason(boundary), opts.logger) })),
+        onTurnTimeout: (error) => settle(() => rejectFn(error)),
+        schedule: opts.schedule,
+        sessionId: opts.sessionId,
+        logger: opts.logger,
+        deltaTMs: opts.deltaTMs,
+        watchdogMs: opts.watchdogMs,
+    });
+    return {
+        detector,
+        promise,
+        cancel() {
+            // Claim the single-resolution latch FIRST (R2.2) so a racing detector boundary cannot also
+            // resolve, then mark the detector cancelled (story-024 seam, R3.1) to clear its Δt + watchdog.
+            settle(() => resolveFn({ stopReason: "cancelled" }));
+            detector.markCancelled();
+        },
+    };
+}

package/dist/engine-lifecycle.d.ts

@@ -0,0 +1,222 @@
+import pty from "node-pty";
+import type { PtyEngineHandle } from "./engine-pty.js";
+import type { AnsiMirrorOptions } from "./ansi-mirror.js";
+/**
+ * Minimal contract the lifecycle layer depends on from the JSONL tail watcher (story 015,
+ * downstream). Lifecycle only needs to STOP it on cleanup — it never reads from it. Defined
+ * here as the interface seam so 014 can tear the watcher down before 015 ships the concrete
+ * `fs.watch`/tail implementation.
+ */
+export interface SessionWatcher {
+    /** Tear down the watcher: stop the fs.watch/tail, flush buffers, drop listeners. */
+    stop(): void;
+}
+/** Diagnostics passed to the {@link SessionEngineOptions.onCleanup} hook. */
+export interface CleanupInfo {
+    sessionId: string;
+    /** PTY exit code, when cleanup was triggered by `onExit`. */
+    exitCode?: number;
+    /** PTY terminating signal, when cleanup was triggered by `onExit`. */
+    signal?: number;
+}
+/**
+ * Default PTY geometry applied when Zed supplies no terminal size (§5 Spawn defaults). Mirrors
+ * the story 013 spawn dimensions so a no-size resize matches a freshly-spawned PTY.
+ */
+export declare const DEFAULT_COLS = 120;
+export declare const DEFAULT_ROWS = 40;
+/**
+ * Resize debounce window (ms). Rapid resize requests (e.g. a window drag) are coalesced and
+ * only the last size is applied after this window elapses, so the TUI is not thrashed (§5).
+ */
+export declare const RESIZE_DEBOUNCE_MS = 100;
+/** Construction options for a {@link SessionEngine}. */
+export interface SessionEngineOptions {
+    /** The spawned PTY handle from story 013's `spawnClaudePty` (or the story 014 resume spawn). */
+    handle: PtyEngineHandle;
+    /** The per-session JSONL tail watcher (story 015). Optional until 015 lands. */
+    watcher?: SessionWatcher;
+    /**
+     * The live session registry. The engine registers itself on construction and deletes its
+     * entry on cleanup. Injectable so tests can observe the map churn directly.
+     */
+    sessions?: Map<string, SessionEngine>;
+    /** Optional diagnostics hook invoked exactly once, when cleanup runs. */
+    onCleanup?: (info: CleanupInfo) => void;
+    /** Resize debounce window in ms; defaults to {@link RESIZE_DEBOUNCE_MS}. */
+    resizeDebounceMs?: number;
+    /** Injectable timer fns (default global setTimeout/clearTimeout); fake-timer tests override. */
+    setTimeoutFn?: typeof setTimeout;
+    clearTimeoutFn?: typeof clearTimeout;
+    /**
+     * Story 035 — OPTIONAL cosmetic live ANSI mirror (§5). OFF by default: when absent/disabled the
+     * `p.onData` tap is NEVER attached and the engine path is byte-for-byte the read-only Degrau-1
+     * behaviour. When enabled (flag on + sink), the engine subscribes a stateless one-way mirror that
+     * forwards raw TUI bytes to the sink for §9 gating visibility, and detaches it on {@link cleanup}.
+     * The mirror is strictly subordinate to the JSONL tail: no state, no `SessionUpdate` (§2).
+     */
+    ansiMirror?: AnsiMirrorOptions;
+}
+/**
+ * Per-session managed engine: ONE Node process owns the PTY (§2). Task 1 wires the PTY's
+ * `onExit` to a single, idempotent `cleanup` that tears down the watcher and releases the
+ * per-session connection state exactly once (R1.1–R1.3).
+ *
+ * `onExit` is only ONE of the possible teardown triggers — an explicit kill (Task 3) routes
+ * through the same `cleanup`, so the per-session `disposed` guard makes the second trigger a
+ * no-op rather than double-freeing the watcher/session-map handles.
+ */
+export declare class SessionEngine {
+    /** The pre-generated v4 session id, == the JSONL transcript basename (story 013). */
+    readonly sessionId: string;
+    /** The live PTY handle whose lifecycle this engine owns. */
+    readonly pty: PtyEngineHandle["pty"];
+    /** The JSONL tail watcher (story 015); cleared on cleanup. */
+    watcher?: SessionWatcher;
+    private readonly sessions?;
+    private readonly onCleanup?;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private readonly debounceMs;
+    private resizeTimer?;
+    private pendingSize?;
+    private disposed;
+    /**
+     * Story 028: the AbortController for the BACKGROUND fresh-path transcript discovery poll (the
+     * unbounded `watchdogMs: Infinity` glob loop that arms the watcher once the transcript appears).
+     * Stored here (sub-task 2.1) so the lifecycle owns the handle; `cleanup()` aborts it (sub-task 3.1)
+     * so tearing a never-interacted session down cancels the dangling poll instead of leaking it.
+     */
+    private pendingDiscovery?;
+    /**
+     * Story 035: the `IDisposable` for the OPTIONAL cosmetic live ANSI mirror's `p.onData` tap.
+     * Present ONLY when the mirror flag was enabled; `undefined` on the default OFF path (where no
+     * `onData` listener was ever attached). `cleanup()` detaches it so the cosmetic tap does not
+     * outlive the session.
+     */
+    private ansiMirror?;
+    constructor(opts: SessionEngineOptions);
+    /**
+     * Debounced terminal resize (R2.1–R2.3). Stores the latest (cols, rows) and (re)arms a short
+     * debounce timer; when it fires, applies ONLY the last size via `p.resize`. Falls back to the
+     * 120×40 default when no size is supplied. A resize requested after the PTY has exited is
+     * dropped without throwing (the `disposed` guard) rather than writing to a dead handle.
+     */
+    requestResize(cols?: number, rows?: number): void;
+    /**
+     * Ctrl+C — write the interrupt byte `\x03` to the PTY to cancel the current turn (R3.1).
+     * No-op after the PTY has exited (R3.4) rather than writing to a dead handle.
+     *
+     * EXPOSED but deliberately NOT wired to any ACP `session/cancel` handler here — the Degrau-1
+     * path is read-only; the `session/cancel`→Ctrl+C wiring is story 030.
+     */
+    interrupt(): void;
+    /** Esc — write the escape byte `\x1b` to the PTY (R3.2). No-op after exit (R3.4). */
+    escape(): void;
+    /**
+     * Kill the PTY process (R3.3). No-op after exit (R3.4). In production the subsequent `onExit`
+     * routes through the idempotent {@link cleanup}, so no explicit teardown call is needed here.
+     */
+    kill(): void;
+    /**
+     * Idempotent teardown (R1.1–R1.3): runs the body exactly once per session. Clears any armed
+     * resize timer, stops the watcher, releases the session-map entry, and fires the diagnostics
+     * hook. A second call (e.g. explicit kill followed by `onExit`) is a no-op — it leaves no
+     * residual timer, watcher subscription, or session-map entry to free again.
+     */
+    cleanup(info?: {
+        exitCode?: number;
+        signal?: number;
+    }): void;
+    /**
+     * Store the AbortController for the background fresh-path discovery poll (story 028, sub-task 2.1).
+     * `cleanup()` aborts it (sub-task 3.1) so a session torn down before its first interaction cancels
+     * the dangling `watchdogMs: Infinity` poll instead of leaking it. The engine owns the handle.
+     */
+    setPendingDiscovery(ac: AbortController): void;
+    /** Whether {@link cleanup} has already run for this session. */
+    get isDisposed(): boolean;
+}
+/**
+ * Build the robust resume argv (§5, R4.1): `bash -c 'claude --resume "<id>" || claude'`. The
+ * `|| claude` makes a FAILED `--resume` fall back to a fresh interactive session rather than
+ * hanging. The id is double-quoted so it survives shell word-splitting. There is deliberately
+ * NO `-p`/`--print`/`stream-json` — those select the SDK/credit non-interactive path.
+ */
+export declare function buildResumeArgv(sessionId: string): [string, string];
+/** Options for {@link spawnResumePty}. */
+export interface SpawnResumeOptions {
+    /** The prior session id to reattach to (== the JSONL transcript basename). */
+    sessionId: string;
+    /** Host working directory the resumed TUI runs in. */
+    cwd: string;
+    /** Base environment to sanitize; defaults to the parent process env. */
+    baseEnv?: Record<string, string | undefined>;
+    /** Injectable spawn function (defaults to node-pty's `spawn`); tests pass a fake. */
+    spawn?: typeof pty.spawn;
+}
+/**
+ * Spawn the resume PTY, reusing story 013's sanitized env (R4.2) so the resumed turn keeps the
+ * `entrypoint='cli'` subscription posture. Same env-sanitize ({@link buildSanitizedEnv}),
+ * refuse-to-spawn taint guard ({@link assertSpawnEnvUntainted}), shell resolution
+ * ({@link resolveShell}), and §5 PTY geometry as the story 013 spawn path — ONLY the argv
+ * differs (robust resume vs the fresh `--session-id` launch). Returns the same
+ * {@link PtyEngineHandle} shape so a {@link SessionEngine} manages a resumed PTY identically.
+ */
+export declare function spawnResumePty(opts: SpawnResumeOptions): PtyEngineHandle;
+/** Options for {@link createSessionEngine}. */
+export interface CreateSessionEngineOptions {
+    /** Host working directory the spawned TUI runs in (story 013 spawn). */
+    cwd: string;
+    /** Base environment to sanitize; defaults to the parent process env. */
+    baseEnv?: Record<string, string | undefined>;
+    /** Injectable spawn function (defaults to node-pty's `spawn`); tests pass a fake. */
+    spawn?: typeof pty.spawn;
+    /**
+     * Story 034 (§9 hybrid gate): per-session SCRATCH settings file carrying the fork's
+     * `PreToolUse` hook, forwarded to {@link spawnClaudePty} as `--settings "<file>"`. The
+     * caller MUST have written it (story 032 `injectHook`) BEFORE calling — claude reads
+     * settings only at startup (GATE_FINDINGS blocker c). Absent → ungated spawn (pre-034).
+     */
+    settingsFile?: string;
+    /**
+     * Factory that starts the per-session JSONL tail watcher (story 015) for the freshly spawned
+     * PTY. Invoked exactly once with the spawned session id and PTY. Returns the watcher handle the
+     * engine tears down on cleanup. The watcher's JSONL tail — NOT `p.onData` — is the single
+     * source of truth for session state (§2). Optional until story 015 lands.
+     */
+    startWatcher?: (sessionId: string, p: PtyEngineHandle["pty"]) => SessionWatcher;
+    /** The live session registry the engine registers into and deletes from on cleanup. */
+    sessions?: Map<string, SessionEngine>;
+    /** Resize debounce window in ms; defaults to {@link RESIZE_DEBOUNCE_MS}. */
+    resizeDebounceMs?: number;
+    /** Optional diagnostics hook invoked exactly once, when cleanup runs. */
+    onCleanup?: (info: CleanupInfo) => void;
+    /** Injectable timer fns (default global setTimeout/clearTimeout); fake-timer tests override. */
+    setTimeoutFn?: typeof setTimeout;
+    clearTimeoutFn?: typeof clearTimeout;
+    /**
+     * Story 035 — OPTIONAL cosmetic live ANSI mirror (§5). OFF by default. Forwarded to the
+     * {@link SessionEngine}; when absent/disabled NO `p.onData` tap is attached and the binding is
+     * byte-for-byte the read-only Degrau-1 path. The mirror is cosmetic only — it produces no
+     * `SessionUpdate` and never feeds the structural path (§2: state comes only from the JSONL tail).
+     */
+    ansiMirror?: AnsiMirrorOptions;
+}
+/**
+ * Bind ONE PTY and ONE JSONL watcher into a single per-session {@link SessionEngine}, hosted by
+ * THIS one Node process (§2 — no out-of-process supervisor, no `child_process.fork`). The PTY is
+ * spawned via story 013's sanitized path; the watcher is started by the injected story-015
+ * factory; the returned engine record owns both (PTY handle + watcher handle + resize timer +
+ * disposed flag).
+ *
+ * ── tail-as-source-of-truth fence (§2 ordering) ───────────────────────────────────────────────
+ * Session state derives SOLELY from the watcher's JSONL tail. The live ANSI mirror (story 035) is
+ * cosmetic and OFF by default: with no `ansiMirror` option, `p.onData` is NEVER subscribed and this
+ * binding is byte-for-byte the read-only Degrau-1 path. Even when enabled, the mirror is one-way
+ * (bytes → live-view sink) and MUST NOT mutate session state or drive turn transitions. Do not add
+ * an `onData`→state path in this binding: structure comes only from the JSONL tail.
+ * ──────────────────────────────────────────────────────────────────────────────────────────────
+ */
+export declare function createSessionEngine(opts: CreateSessionEngineOptions): SessionEngine;
+//# sourceMappingURL=engine-lifecycle.d.ts.map

package/dist/engine-lifecycle.d.ts.map

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