@svenroth-ai/shipwright 0.24.1-next.0

package/server/dist/terminal/headless-mirror.js

@@ -0,0 +1,389 @@
+/*
+ * headless-mirror.ts — Iterate A (ADR-088)
+ *
+ * Per-task @xterm/headless Terminal instance that mirrors a live pty's
+ * byte stream. Lives only while the pty is live. On dispose we snapshot
+ * the stable cell-state via the M2 double-serialize stabilization
+ * (`serializeStable()`) and the caller persists it to disk via
+ * snapshot-store.
+ *
+ * Architecture invariants (from .shipwright/planning/embedded-terminal-refactor-headless.md):
+ *
+ *   1. Headless mirrors only for LIVE ptys. Idle/completed tasks persist
+ *      only the serialized snapshot on disk, not a live Terminal instance.
+ *   2. @xterm/headless is CJS — wire via the default-import-destructure
+ *      shim from this file's ESM consumers.
+ *   3. `term.write(data, callback)` MUST be awaited before serialize. The
+ *      parser is async-ish; serializing immediately after a batch can
+ *      capture incomplete state. write() below wraps the callback in a
+ *      Promise.
+ *   4. Snapshot version is pinned by the caller (snapshot-store header);
+ *      no version logic lives here. The output of serializeStable() is
+ *      the verbatim payload that gets the header glued on.
+ *   5. Plan-D″ (ADR-034) unaffected — this mirror parses pty output;
+ *      never spawns Claude. The pty-manager spawn whitelist is unchanged.
+ *
+ * Why M2 (double-serialize)? Spike T2 in the planning doc proved that
+ * `serialize → write-back → serialize` is idempotent: round2 == round3.
+ * The first serialize ("raw") has a 1-character resize-drift artifact
+ * (column-0 dash on one line of an otherwise-blank dialog row in the
+ * production scenario). One extra parse + serialize cycle eliminates it.
+ * Cost: ~10 ms per attach. See planning doc § "Resize-drift mitigation".
+ */
+// CJS interop. @xterm/headless ships CommonJS; @xterm/addon-serialize
+// ships CommonJS. ESM consumers must default-import the package and
+// destructure the named export.
+import pkg from "@xterm/headless";
+import addonPkg from "@xterm/addon-serialize";
+const { Terminal } = pkg;
+const { SerializeAddon } = addonPkg;
+/**
+ * DECTCEM (cursor-visibility) restore sequences.
+ *
+ * `@xterm/addon-serialize`'s `_serializeModes()` serializes the public
+ * IModes set + the mouse-tracking selector, but NEVER DECTCEM (`?25`).
+ * `serializeStable()` re-appends exactly one of these so a reattach
+ * reproduces the producer's cursor-visibility state instead of xterm's
+ * always-visible default. Sibling workaround for the same addon-serialize
+ * mode-drop class: `replay-snapshot.ts` re-appends `?1006h`.
+ */
+const CURSOR_HIDE = "\x1b[?25l";
+const CURSOR_SHOW = "\x1b[?25h";
+/**
+ * Snapshot every line in the active buffer (scrollback + viewport) as
+ * strings — used by serializeStableWithCanonicalBuffer to capture the
+ * round2 reference. translateToString(false) preserves trailing spaces;
+ * the test compares character-for-character.
+ */
+function snapshotVisibleLines(term) {
+    const buffer = term.buffer.active;
+    const total = buffer.length;
+    const out = new Array(total);
+    for (let y = 0; y < total; y++) {
+        const line = buffer.getLine(y);
+        out[y] = line ? line.translateToString(false) : "";
+    }
+    return out;
+}
+/**
+ * Per-task headless terminal mirror. Disposable.
+ *
+ * Lifecycle:
+ *   - new HeadlessMirror({...})            — construct in pty-manager.spawn
+ *   - await mirror.write(buf)              — once per pty.onData chunk
+ *   - const snap = await mirror.serializeStable()  — on pty.kill / dispose
+ *   - mirror.dispose()                     — frees the Terminal instance
+ *
+ * Memory: a Terminal at 120×30 with 1 000-line scrollback uses ~1-2 MB
+ * RSS measured under the spike. Multiplied by the active-task-count cap
+ * in pty-manager, total live-mirror memory stays well under the spike's
+ * 80 MB ceiling across multiple in-scope terminals.
+ */
+/**
+ * Hard caps to defeat resize-DoS. xterm.js allocates per-cell state, so
+ * 100 000 × 100 000 = 10 000 000 000 cells would OOM the Node process.
+ * Real terminals top out around 500 × 200; we cap at 1000 × 500 (well
+ * above any real terminal) so a misbehaving client can't request a
+ * pathological resize. Clamping is silent because the pty itself uses
+ * the requested dims — the mirror just clamps for its own buffer
+ * allocation (round-tripped through resize() below).
+ */
+const MAX_COLS = 1000;
+const MAX_ROWS = 500;
+function clampCols(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return 1;
+    return Math.min(Math.floor(n), MAX_COLS);
+}
+function clampRows(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return 1;
+    return Math.min(Math.floor(n), MAX_ROWS);
+}
+export class HeadlessMirror {
+    taskId;
+    term;
+    cols;
+    rows;
+    scrollback;
+    disposed = false;
+    /**
+     * Tracks unresolved write() resolvers. serializeStable() awaits the
+     * corresponding promises before snapshotting so the parser cannot be
+     * mid-CSI / mid-OSC when the serialize callback runs (Gemini
+     * external-review #4 + architecture invariant #3 + external code
+     * review HIGH: tracking resolvers explicitly so `dispose()` can
+     * forcibly resolve them and never hang `flushPendingWrites`).
+     *
+     * Stored as a Map of Promise -> resolver so dispose() can drain the
+     * set without waiting for parser callbacks that may never fire on a
+     * disposed Terminal. The set is bounded by the in-flight write count.
+     */
+    pendingWrites = new Map();
+    constructor(opts) {
+        this.taskId = opts.taskId;
+        this.cols = clampCols(opts.cols);
+        this.rows = clampRows(opts.rows);
+        this.scrollback = opts.scrollback ?? 1000;
+        this.term = new Terminal({
+            cols: this.cols,
+            rows: this.rows,
+            scrollback: this.scrollback,
+            // allowProposedApi: serializeAddon uses proposed APIs on some
+            // versions; setting true is the documented requirement.
+            allowProposedApi: true,
+        });
+    }
+    /**
+     * Test-only handle on the underlying Terminal. Real callers go through
+     * write/serializeStable/dispose; the fixture test needs to feed bytes
+     * and snapshot visible lines directly.
+     */
+    get terminalForTesting() {
+        return this.term;
+    }
+    /**
+     * Feed raw bytes into the headless mirror. Awaits the parser callback
+     * before resolving — this is architecture invariant #3, required for
+     * mid-escape split correctness.
+     *
+     * Accepts Buffer | Uint8Array | string. node-pty emits strings by
+     * default; the snapshot pipeline can also feed Buffers.
+     */
+    write(data) {
+        if (this.disposed) {
+            // No-op on disposed mirror; never throw from the pty.onData hot path.
+            return Promise.resolve();
+        }
+        // Capture resolver in a closure so dispose() can drain pending
+        // writes without depending on the parser callback ever firing on a
+        // disposed Terminal (external code review HIGH: hang risk).
+        let storedResolve;
+        const p = new Promise((resolve) => {
+            storedResolve = resolve;
+            try {
+                // Cast: @xterm/headless typings accept string | Uint8Array.
+                // Buffer is a Uint8Array subclass so the cast is safe.
+                this.term.write(data, () => resolve());
+            }
+            catch (err) {
+                // Parser exceptions are silently swallowed — the broadcast loop
+                // must stay live (external review Gemini #3). The pending-writes
+                // tracking still resolves so serializeStable() doesn't block.
+                // eslint-disable-next-line no-console
+                console.warn(`[headless-mirror] term.write threw for ${this.taskId}: ${err.message}`);
+                resolve();
+            }
+        });
+        this.pendingWrites.set(p, storedResolve);
+        p.finally(() => {
+            this.pendingWrites.delete(p);
+        });
+        return p;
+    }
+    /**
+     * Await every in-flight write callback. Used internally by
+     * serializeStable so the parser is in a stable state when round1
+     * runs (architecture invariant #3 + external review Gemini #4).
+     */
+    async flushPendingWrites() {
+        // Snapshot the current set; new writes that arrive while we wait
+        // are not part of this flush. This is intentional: serializeStable
+        // captures the state at the moment cleanup decided to snapshot.
+        const inflight = [...this.pendingWrites.keys()];
+        if (inflight.length === 0)
+            return;
+        await Promise.all(inflight);
+    }
+    /**
+     * Adjust dimensions. Headless terminal preserves scrollback contents
+     * across resize; rewrap behavior follows xterm.js's reflow.
+     */
+    resize(cols, rows) {
+        if (this.disposed)
+            return;
+        // Clamp to defeat resize-DoS (external review Gemini #5). The pty
+        // itself is sized by the caller; we cap only the mirror.
+        this.cols = clampCols(cols);
+        this.rows = clampRows(rows);
+        this.term.resize(this.cols, this.rows);
+    }
+    /**
+     * M2 double-serialize. Per spike T2: `serialize → write-back → serialize`
+     * is idempotent at round2 == round3, so this produces the stable fixed
+     * point that the client's xterm.js will reproduce byte-for-byte.
+     *
+     * Procedure:
+     *   raw   = primary serialize (may contain 1-char drift artifacts)
+     *   warm  = transient Terminal, replay raw, serialize → stable (round2)
+     *   return stable, dispose warm
+     *
+     * Contract: when the returned `stable` string is later written into a
+     * fresh client-side xterm Terminal of the same cols/rows, that
+     * Terminal's visible buffer (round3 application) is line-for-line
+     * equal to the warm Terminal's visible buffer at the moment of round2
+     * serialization. The live mirror's own visible buffer is round1 — it
+     * may differ from round2 by one or two cells on resize boundaries.
+     * That is the documented one-shot artifact M2 trades for idempotence.
+     *
+     * The warm Terminal MUST use identical cols/rows + scrollback so the
+     * replay buffer is identical in shape.
+     */
+    async serializeStable() {
+        const { stable } = await this.serializeStableWithCanonicalBuffer();
+        return stable;
+    }
+    /**
+     * Same as serializeStable() but also returns the canonical (round2)
+     * visible-buffer snapshot. Test-only — production callers use
+     * serializeStable() which discards the buffer. The round2 buffer is
+     * the contract reference: a client replay of `stable` produces the
+     * same lines.
+     *
+     * `stable` additionally carries a trailing DECTCEM (`?25h` / `?25l`):
+     * addon-serialize never serializes cursor visibility, so it is restored
+     * explicitly here — see `readCursorHidden()`.
+     */
+    async serializeStableWithCanonicalBuffer() {
+        if (this.disposed) {
+            throw new Error("HeadlessMirror.serializeStable: mirror is disposed");
+        }
+        // External review Gemini #4 — drain in-flight writes so the live
+        // parser is at a stable state (NOT mid-CSI / mid-OSC) before
+        // round1 serializes. Without this, a fire-and-forget pty.onData
+        // mirror.write() that arrived just before kill could leave the
+        // serialize output missing the trailing payload bytes.
+        await this.flushPendingWrites();
+        // Capture DECTCEM from the LIVE mirror now — after the flush so a
+        // trailing ?25 toggle in the last pty chunk is already processed, and
+        // before round1/round2 (which read addon state, not this.term's
+        // cursor mode). addon-serialize drops ?25 entirely; readCursorHidden()
+        // + the append at the return is the restore.
+        const cursorHidden = this.readCursorHidden();
+        // Round 1 — serialize the live mirror.
+        const liveAddon = new SerializeAddon();
+        this.term.loadAddon(liveAddon);
+        let raw;
+        try {
+            raw = liveAddon.serialize();
+        }
+        finally {
+            liveAddon.dispose();
+        }
+        // Round 2 — replay into a warm Terminal of identical dimensions +
+        // scrollback. Serialize the warm one. Per T2, this output equals
+        // round 3 (the next replay would be idempotent).
+        const warm = new Terminal({
+            cols: this.cols,
+            rows: this.rows,
+            scrollback: this.scrollback,
+            allowProposedApi: true,
+        });
+        const warmAddon = new SerializeAddon();
+        warm.loadAddon(warmAddon);
+        try {
+            await new Promise((resolve) => {
+                warm.write(raw, () => resolve());
+            });
+            const stable = warmAddon.serialize();
+            const canonicalLines = snapshotVisibleLines(warm);
+            // DECTCEM restore — append the cursor-visibility mode addon-serialize
+            // never emits. Position-independent and idempotent (xterm no-ops a
+            // redundant mode set), so it does not perturb the M2 fixed point or
+            // the round2 visible buffer (`canonicalLines`) — cursor visibility is
+            // not cell content.
+            const stableWithCursor = stable + (cursorHidden ? CURSOR_HIDE : CURSOR_SHOW);
+            return { stable: stableWithCursor, canonicalLines };
+        }
+        finally {
+            warmAddon.dispose();
+            warm.dispose();
+        }
+    }
+    /**
+     * Live mirror's DECTCEM state — `true` when the cursor is hidden.
+     * addon-serialize never serializes `?25`, so `serializeStable()` restores
+     * it explicitly: else a reattach shows a ghost cursor that Claude Code
+     * (fullscreen under `CLAUDE_CODE_NO_FLICKER=1`, ADR-095/098) believes is
+     * hidden, jumping with every CUP redraw. The `_core.coreService` peek is
+     * an internal-surface read (xterm exact-pinned 6.0.0, CLAUDE.md rule 22),
+     * correct across `?25l` / `?25h` AND soft-reset. Unreadable internal →
+     * `false` (pre-fix behaviour) so a future xterm refactor degrades safely.
+     */
+    readCursorHidden() {
+        try {
+            const core = this.term._core;
+            return core?.coreService?.isCursorHidden === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Current dimensions. Used by snapshot-store to write the header. */
+    get dimensions() {
+        return { cols: this.cols, rows: this.rows };
+    }
+    /**
+     * Decoded text of the visible viewport (the bottom page) — scrollback
+     * excluded, ANSI already interpreted into cells. Reads rows
+     * `baseY … baseY + rows` so it always captures the bottom of the
+     * buffer regardless of scroll state. Trailing whitespace per line is
+     * trimmed.
+     *
+     * iterate-2026-05-18-inbox-terminal-prompts: consumed by
+     * `PtyManager.peekTerminalText()` so the inbox can detect a *waiting*
+     * `AskUserQuestion` picker — the picker is on-screen, never in the
+     * JSONL. Best-effort: returns "" on a disposed mirror or any
+     * buffer-read error (never throws — it sits behind an inbox poll).
+     */
+    getVisibleText() {
+        if (this.disposed)
+            return "";
+        try {
+            const buf = this.term.buffer.active;
+            const start = buf.baseY;
+            const rows = [];
+            for (let y = start; y < start + this.rows; y++) {
+                const line = buf.getLine(y);
+                rows.push(line ? line.translateToString(true) : "");
+            }
+            return rows.join("\n");
+        }
+        catch {
+            return "";
+        }
+    }
+    /**
+     * Idempotent. External code review HIGH: drain pending writes BEFORE
+     * disposing the Terminal so any `flushPendingWrites()` awaiters can
+     * resolve immediately rather than wait forever on parser callbacks
+     * that will never fire on a disposed Terminal.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Forcibly resolve any in-flight write promises. The associated
+        // `term.write` callback may never run on a disposed Terminal; this
+        // path guarantees flushPendingWrites() returns instead of hanging.
+        for (const resolve of this.pendingWrites.values()) {
+            try {
+                resolve();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.pendingWrites.clear();
+        try {
+            this.term.dispose();
+        }
+        catch {
+            // best-effort
+        }
+    }
+    get isDisposed() {
+        return this.disposed;
+    }
+}
+//# sourceMappingURL=headless-mirror.js.map

package/server/dist/terminal/headless-mirror.js.map

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

package/server/dist/terminal/headless-probe.d.ts

@@ -0,0 +1,26 @@
+export interface HeadlessProbeResult {
+    ok: boolean;
+    /** Resolved `@xterm/headless` version when ok; null otherwise. */
+    terminalVersion: string | null;
+    /** Reason the probe failed (free-form, log-friendly). null when ok. */
+    reason: string | null;
+}
+export type DynamicImportFn = (specifier: string) => Promise<unknown>;
+/**
+ * Probe both packages by dynamically importing them + reading the
+ * `version` field from `@xterm/headless`'s package.json. Two-step
+ * verification:
+ *
+ *   1. import `@xterm/headless` — verifies the package loads + exports
+ *      a usable `Terminal` constructor.
+ *   2. import `@xterm/addon-serialize` — verifies the addon package
+ *      loads + exports `SerializeAddon`.
+ *
+ * Each step in its own try/catch so the diagnostic is precise: "headless
+ * import failed" vs. "addon import failed".
+ *
+ * The default `importer` is the native `import(...)` expression. Tests
+ * inject a custom importer that returns/throws synthetic modules.
+ */
+export declare function probeHeadlessDeps(importer?: DynamicImportFn): Promise<HeadlessProbeResult>;
+//# sourceMappingURL=headless-probe.d.ts.map

package/server/dist/terminal/headless-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-probe.d.ts","sourceRoot":"","sources":["../../src/terminal/headless-probe.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,kEAAkE;IAClE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,uEAAuE;IACvE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,GAAE,eAAqD,GAC9D,OAAO,CAAC,mBAAmB,CAAC,CAkE9B"}

package/server/dist/terminal/headless-probe.js

@@ -0,0 +1,99 @@
+/*
+ * headless-probe.ts — Iterate C (ADR-087, MEDIUM-B2 fix).
+ *
+ * Boot-time pre-probe of `@xterm/headless` + `@xterm/addon-serialize`
+ * via dynamic import. Returns a structured result so the boot path can
+ * downgrade `headlessMirrorEnabled=false` on failure WITHOUT crashing.
+ *
+ * Background: Iterate B (ADR-089) wired both packages via static ESM
+ * imports in `server/src/index.ts` + `server/src/terminal/headless-mirror.ts`.
+ * If either package is missing/corrupt at runtime (broken `node_modules`,
+ * monorepo hoist mishap, partial `npm install`), the server crashed at
+ * boot — there was no graceful fallback to "no snapshot, still serve".
+ *
+ * Decision: pre-probe via dynamic import at boot. On failure log a
+ * structured warn, set `headlessMirrorEnabled=false`, continue server
+ * start. The legacy chunked path is now retired so a probe failure
+ * means "no replay at all" (per the plan's stated trade-off in ADR-087:
+ * "Failure mode (snapshot write fails): Client falls back to 'no replay'
+ * (blank terminal with live shell)").
+ */
+/**
+ * Probe both packages by dynamically importing them + reading the
+ * `version` field from `@xterm/headless`'s package.json. Two-step
+ * verification:
+ *
+ *   1. import `@xterm/headless` — verifies the package loads + exports
+ *      a usable `Terminal` constructor.
+ *   2. import `@xterm/addon-serialize` — verifies the addon package
+ *      loads + exports `SerializeAddon`.
+ *
+ * Each step in its own try/catch so the diagnostic is precise: "headless
+ * import failed" vs. "addon import failed".
+ *
+ * The default `importer` is the native `import(...)` expression. Tests
+ * inject a custom importer that returns/throws synthetic modules.
+ */
+export async function probeHeadlessDeps(importer = (s) => import(/* @vite-ignore */ s)) {
+    // Step 1 — @xterm/headless.
+    let headlessMod;
+    try {
+        headlessMod = await importer("@xterm/headless");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            terminalVersion: null,
+            reason: `@xterm/headless import failed: ${err.message}`,
+        };
+    }
+    // Headless ships CJS; ESM consumers get a wrapper with .default.
+    const headlessDefault = headlessMod?.default ?? headlessMod;
+    const TerminalCtor = headlessDefault?.Terminal;
+    if (typeof TerminalCtor !== "function") {
+        return {
+            ok: false,
+            terminalVersion: null,
+            reason: "@xterm/headless does not export a `Terminal` constructor (corrupt package?)",
+        };
+    }
+    // Step 2 — @xterm/addon-serialize.
+    let addonMod;
+    try {
+        addonMod = await importer("@xterm/addon-serialize");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            terminalVersion: null,
+            reason: `@xterm/addon-serialize import failed: ${err.message}`,
+        };
+    }
+    const addonDefault = addonMod?.default ?? addonMod;
+    const SerializeAddonCtor = addonDefault?.SerializeAddon;
+    if (typeof SerializeAddonCtor !== "function") {
+        return {
+            ok: false,
+            terminalVersion: null,
+            reason: "@xterm/addon-serialize does not export a `SerializeAddon` constructor",
+        };
+    }
+    // Step 3 — read terminalVersion from the package.json. Use the same
+    // dynamic-import path so a probe-induced failure mirrors the runtime.
+    // Best-effort: success without a version is still ok (the snapshot
+    // writer's own resolver does a separate fs read).
+    let terminalVersion = null;
+    try {
+        const pkgMod = await importer("@xterm/headless/package.json");
+        const pkg = pkgMod?.default ??
+            pkgMod;
+        if (pkg && typeof pkg.version === "string" && pkg.version.length > 0) {
+            terminalVersion = pkg.version;
+        }
+    }
+    catch {
+        /* non-fatal — fs fallback exists in snapshot-store */
+    }
+    return { ok: true, terminalVersion, reason: null };
+}
+//# sourceMappingURL=headless-probe.js.map

package/server/dist/terminal/headless-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-probe.js","sourceRoot":"","sources":["../../src/terminal/headless-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAYH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,WAA4B,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAE/D,4BAA4B;IAC5B,IAAI,WAAoB,CAAC;IACzB,IAAI,CAAC;QACH,WAAW,GAAG,MAAM,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,EAAE,EAAE,KAAK;YACT,eAAe,EAAE,IAAI;YACrB,MAAM,EAAE,kCAAmC,GAAa,CAAC,OAAO,EAAE;SACnE,CAAC;IACJ,CAAC;IACD,iEAAiE;IACjE,MAAM,eAAe,GAClB,WAAqC,EAAE,OAAO,IAAI,WAAW,CAAC;IACjE,MAAM,YAAY,GAAI,eAA0C,EAAE,QAAQ,CAAC;IAC3E,IAAI,OAAO,YAAY,KAAK,UAAU,EAAE,CAAC;QACvC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,eAAe,EAAE,IAAI;YACrB,MAAM,EACJ,6EAA6E;SAChF,CAAC;IACJ,CAAC;IAED,mCAAmC;IACnC,IAAI,QAAiB,CAAC;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,QAAQ,CAAC,wBAAwB,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,EAAE,EAAE,KAAK;YACT,eAAe,EAAE,IAAI;YACrB,MAAM,EAAE,yCAA0C,GAAa,CAAC,OAAO,EAAE;SAC1E,CAAC;IACJ,CAAC;IACD,MAAM,YAAY,GAAI,QAAkC,EAAE,OAAO,IAAI,QAAQ,CAAC;IAC9E,MAAM,kBAAkB,GACrB,YAA6C,EAAE,cAAc,CAAC;IACjE,IAAI,OAAO,kBAAkB,KAAK,UAAU,EAAE,CAAC;QAC7C,OAAO;YACL,EAAE,EAAE,KAAK;YACT,eAAe,EAAE,IAAI;YACrB,MAAM,EACJ,uEAAuE;SAC1E,CAAC;IACJ,CAAC;IAED,oEAAoE;IACpE,sEAAsE;IACtE,mEAAmE;IACnE,kDAAkD;IAClD,IAAI,eAAe,GAAkB,IAAI,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,8BAA8B,CAAC,CAAC;QAC9D,MAAM,GAAG,GACN,MAA6C,EAAE,OAAO;YACtD,MAA+B,CAAC;QACnC,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrE,eAAe,GAAG,GAAG,CAAC,OAAO,CAAC;QAChC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sDAAsD;IACxD,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACrD,CAAC"}

package/server/dist/terminal/idle-reaper.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Default detached-grace before an orphaned pty is reaped: 12 h.
+ *
+ * The 30-min default this replaces was too aggressive for remote/mobile
+ * use (leave a session waiting at a prompt, return after a commute → killed
+ * + work lost). For a single-user local tool the asymmetry favours a
+ * generous value: a lingering pty costs a few processes on your own PC; a
+ * premature reap costs lost work. Overridable via
+ * `SHIPWRIGHT_TERMINAL_IDLE_TIMEOUT_MS` (resolved in `config.ts`).
+ */
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 43200000;
+export interface IdleReaperOpts {
+    /** Grace, in ms, after the last client detaches before the pty is reaped. */
+    timeoutMs: number;
+    /** Invoked with the taskId when a task's grace elapses. */
+    onReap: (taskId: string) => void;
+    /** Scheduler seams for deterministic tests. Default to the globals. */
+    setTimeoutFn?: (handler: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimeoutFn?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+/**
+ * Per-task idle grace manager. `touch(taskId, attachCount)` is the single
+ * entry point: callers invoke it on every lifecycle event that bears on
+ * orphan status (attach, detach, pty output, pty input, spawn). The reaper
+ * decides arm-vs-disarm from `attachCount` alone, so the gating policy
+ * lives in exactly one place.
+ */
+export declare class IdleReaper {
+    private readonly timers;
+    private readonly timeoutMs;
+    private readonly onReap;
+    private readonly setT;
+    private readonly clearT;
+    constructor(opts: IdleReaperOpts);
+    /**
+     * Re-evaluate a task's idle grace.
+     *   - `attachCount > 0`  → a client is watching → disarm (never an orphan).
+     *   - `attachCount === 0` → arm (or re-arm) the grace; on expiry `onReap`
+     *     fires and the timer is forgotten.
+     */
+    touch(taskId: string, attachCount: number): void;
+    /** Disarm a task's grace (used on cleanup / explicit kill). Idempotent. */
+    cancel(taskId: string): void;
+    /** Whether a grace is currently armed for the task (tests / observability). */
+    isArmed(taskId: string): boolean;
+}
+//# sourceMappingURL=idle-reaper.d.ts.map

package/server/dist/terminal/idle-reaper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idle-reaper.d.ts","sourceRoot":"","sources":["../../src/terminal/idle-reaper.ts"],"names":[],"mappings":"AA+BA;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,WAAa,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,uEAAuE;IACvE,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IAClF,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,CAAC;CACjE;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoD;IAC3E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8C;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgD;gBAE3D,IAAI,EAAE,cAAc;IAOhC;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAehD,2EAA2E;IAC3E,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ5B,+EAA+E;IAC/E,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;CAGjC"}