@svenroth-ai/shipwright 0.24.1-next.0

package/server/dist/terminal/pty-manager.js

@@ -0,0 +1,1014 @@
+/*
+ * pty-manager.ts — embedded-terminal pty lifecycle (iterate-2026-05-03).
+ *
+ * Plan-D'' compliance: webui hosts a NEUTRAL shell (pwsh / cmd / bash / …)
+ * — never `claude` directly. Whitelist enforced by basename normalisation
+ * so absolute paths like `/usr/local/bin/claude` cannot slip through.
+ *
+ * External-review (2026-05-03) drove these contracts:
+ *   - WS upgrade is the authoritative ensure-or-create entrypoint;
+ *     spawn() is idempotent for the same taskId (no dual-creation race).
+ *   - Writer ownership is bound to the live WS connection identity;
+ *     detach clears the writer slot synchronously.
+ *   - Last-connection-close keeps the pty alive (ADR-068-A1 Replay-on-
+ *     Attach contract). Navigation away from TaskDetail must NOT kill
+ *     a running claude session; the user re-attaches by navigating back.
+ *   - 30-min idle ceiling forces kill (the orphan GC mechanism). Plus
+ *     explicit user "Stop terminal session" + DELETE task cascade.
+ *   - Per-conn outbound buffer cap with drop-oldest backpressure.
+ *   - Shell-aware path quoting via quotePathForShell() — used by the
+ *     image-paste flow so cwd-with-spaces does not break the prompt.
+ *
+ * The actual node-pty backend is injected via PtySpawnFn so unit tests
+ * can stay native-binary-free.
+ */
+import { HeadlessMirror } from "./headless-mirror.js";
+import { IdleReaper, DEFAULT_IDLE_TIMEOUT_MS } from "./idle-reaper.js";
+import { writeSnapshotPreservingLarger } from "./snapshot-preserve.js";
+import { BackpressureTelemetry } from "./backpressure-telemetry.js";
+export class PtySpawnRejectedError extends Error {
+    constructor(target) {
+        super(`pty-manager: refusing to spawn '${target}' — only whitelisted shells are allowed (Plan-D''/ADR-067)`);
+        this.name = "PtySpawnRejectedError";
+    }
+}
+/**
+ * iterate-2026-07-15-e2e-pty-spawn-cwd-267 — the injected `spawnFn`
+ * (node-pty's `CreateProcess`) threw. Dominant cause on Windows: a spawn
+ * `cwd` that was removed / is delete-pending → `error code: 267`
+ * (ERROR_DIRECTORY). Distinct from `PtySpawnRejectedError` (whitelist);
+ * callers convert it to a clean rejection, not an uncaught throw. Full
+ * root-cause (267 ≠ resource exhaustion) is in the run's decision drop.
+ */
+export class PtySpawnFailedError extends Error {
+    /** Parsed native code when present (267 = ERROR_DIRECTORY on win32), else null. */
+    code;
+    constructor(cwd, cause) {
+        const causeMsg = cause instanceof Error ? cause.message : String(cause);
+        super(`pty-manager: failed to spawn a shell in cwd '${cwd}': ${causeMsg}`);
+        this.name = "PtySpawnFailedError";
+        const m = /error code:\s*(\d+)/i.exec(causeMsg);
+        this.code = m ? Number(m[1]) : null;
+        this.cause = cause;
+    }
+    /** True when the failure is an unusable cwd (win32 267 / POSIX ENOENT /
+     *  ENOTDIR) — the user-actionable case; other failures (EMFILE/EPERM) are
+     *  NOT labelled as a cwd problem, so callers stay accurate (code-review N1). */
+    get isLikelyCwdError() {
+        return this.code === 267 || /\b(ENOENT|ENOTDIR)\b/.test(this.message);
+    }
+}
+// ---------------------------------------------------------------------------
+// Whitelist + shell-kind inference
+// ---------------------------------------------------------------------------
+const WHITELIST = new Set([
+    "pwsh",
+    "pwsh.exe",
+    "powershell",
+    "powershell.exe",
+    "cmd",
+    "cmd.exe",
+    "bash",
+    "bash.exe",
+    "zsh",
+    "sh",
+    "fish",
+]);
+function basenameLower(target) {
+    // Handle both "/" and "\\" so a Windows path passed on a POSIX host
+    // still normalizes correctly during tests.
+    const lastSlash = Math.max(target.lastIndexOf("/"), target.lastIndexOf("\\"));
+    const base = lastSlash === -1 ? target : target.slice(lastSlash + 1);
+    return base.toLowerCase();
+}
+function inferShellKind(target) {
+    const b = basenameLower(target);
+    if (b === "pwsh" || b === "pwsh.exe" || b === "powershell" || b === "powershell.exe") {
+        return "pwsh";
+    }
+    if (b === "cmd" || b === "cmd.exe") {
+        return "cmd";
+    }
+    return "posix";
+}
+function isWhitelistedShell(target) {
+    return WHITELIST.has(basenameLower(target));
+}
+// ---------------------------------------------------------------------------
+// quotePathForShell — used by image-paste route so paths with spaces work.
+// ---------------------------------------------------------------------------
+export function quotePathForShell(absPath, kind) {
+    if (kind === "pwsh") {
+        // PowerShell single-quoted strings: only ' itself needs escaping (doubled).
+        return "'" + absPath.replace(/'/g, "''") + "'";
+    }
+    if (kind === "cmd") {
+        // cmd.exe: double-quoted, " escaped as "" (de-facto rule for argv parsing).
+        return '"' + absPath.replace(/"/g, '""') + '"';
+    }
+    // POSIX: single-quoted; close-quote, escaped quote, re-open-quote.
+    return "'" + absPath.replace(/'/g, "'\\''") + "'";
+}
+/** Sentinel for the legacy token-less pause()/resume() API. */
+const ANON_PAUSE_TOKEN = Symbol("pty-manager.anonymous-pause");
+export class PtyManager {
+    entries = new Map();
+    spawnFn;
+    wsBufferBytes;
+    idleTimeoutMs;
+    idleReaper;
+    scrollbackStore;
+    snapshotStore;
+    headlessMirrorEnabled;
+    expectedTerminalVersion;
+    watchdogStuckThresholdBytes;
+    watchdogStuckDurationMs;
+    watchdogIntervalMs;
+    watchdogEnabledOpt;
+    nowFn;
+    watchdogTimer = null;
+    /**
+     * Per-conn capability tracking (per external review code-pass —
+     * openai-5). `Map<conn, "ok" | "missing">`: "ok" = bufferedAmount
+     * returned a number; "missing" = bufferedAmount was undefined →
+     * skip THAT conn's eviction without disabling the watchdog globally.
+     * Conns absent from the map haven't been probed yet — first
+     * deliverWithBackpressure / watchdogTick that sees them stamps
+     * the result. Earlier global-disable design was rejected because
+     * a single legacy adapter would have permanently disabled stuck-
+     * writer eviction for healthy conns sharing the same PtyManager.
+     */
+    connCapability = new Map();
+    /** Whether the capability-missing warning has already been logged (rate-limit). */
+    capabilityWarnLogged = false;
+    /** Owns the saturation-episode state formerly `PtyEntry.backpressureRaised`. */
+    backpressure = new BackpressureTelemetry();
+    constructor(opts) {
+        this.spawnFn = opts.spawn;
+        this.wsBufferBytes = opts.wsBufferBytes ?? 1_048_576;
+        this.idleTimeoutMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+        // Orphan-GC (attachment-gated, iterate-2026-06-02): the idle ceiling
+        // fires ONLY when no client is attached; reap = the existing kill() path
+        // (flags the intentional close → v0.8.7 marker). Policy in idle-reaper.ts.
+        this.idleReaper = new IdleReaper({
+            timeoutMs: this.idleTimeoutMs,
+            onReap: (taskId) => this.kill(taskId),
+        });
+        this.scrollbackStore = opts.scrollbackStore;
+        this.snapshotStore = opts.snapshotStore;
+        // Mirror requires BOTH flag-on AND a configured store. Either alone
+        // is a no-op so misconfiguration cannot leak in-memory Terminals
+        // without a persistence path.
+        this.headlessMirrorEnabled =
+            (opts.headlessMirrorEnabled ?? false) && !!opts.snapshotStore;
+        this.expectedTerminalVersion = opts.expectedTerminalVersion ?? "unknown";
+        this.watchdogStuckThresholdBytes =
+            opts.watchdogStuckThresholdBytes ?? 524_288; // 512 KiB
+        this.watchdogStuckDurationMs = opts.watchdogStuckDurationMs ?? 2_000;
+        this.watchdogIntervalMs = opts.watchdogIntervalMs ?? 2_000;
+        this.watchdogEnabledOpt = opts.watchdogEnabled ?? false;
+        this.nowFn = opts.now ?? Date.now;
+        if (this.watchdogEnabledOpt) {
+            this.watchdogTimer = setInterval(() => this.watchdogTick(), this.watchdogIntervalMs);
+            // Avoid keeping a Node event loop alive solely for the watchdog.
+            const t = this.watchdogTimer;
+            if (typeof t.unref === "function")
+                t.unref();
+        }
+    }
+    /** Look up a handle by taskId. Returns undefined if not yet spawned. */
+    get(taskId) {
+        return this.entries.get(taskId)?.meta;
+    }
+    /**
+     * Return the set of taskIds with a live pty entry. Used by the daily
+     * scrollback sweep (ADR-068-A1, AC-11) to skip clearing files for
+     * tasks whose pty is still running but whose `sdk-sessions.json` state
+     * has drifted (e.g. session ended mid-run).
+     */
+    getLiveTaskIds() {
+        return new Set(this.entries.keys());
+    }
+    /** Idempotent ensure-or-create. */
+    spawn(taskId, opts) {
+        const existing = this.entries.get(taskId);
+        if (existing)
+            return existing.meta;
+        if (!isWhitelistedShell(opts.shell)) {
+            throw new PtySpawnRejectedError(opts.shell);
+        }
+        const meta = {
+            taskId,
+            cwd: opts.cwd,
+            shell: opts.shell,
+            shellKind: inferShellKind(opts.shell),
+        };
+        // iterate-2026-07-15 — node-pty's CreateProcess throws synchronously on an
+        // unusable cwd (267). Type it so WS-upgrade + prewarm callers degrade
+        // cleanly; no entry is registered yet, so a failed spawn leaks nothing.
+        let pty;
+        try {
+            pty = this.spawnFn(opts.shell, [], {
+                cwd: opts.cwd,
+                cols: opts.cols ?? 120,
+                rows: opts.rows ?? 30,
+            });
+        }
+        catch (err) {
+            throw new PtySpawnFailedError(opts.cwd, err);
+        }
+        // ADR-088: optional headless mirror — lifetime co-extensive with the
+        // entry (disposed in cleanup()); dims match the pty-spawn defaults.
+        const mirror = this.headlessMirrorEnabled
+            ? new HeadlessMirror({
+                taskId,
+                cols: opts.cols ?? 120,
+                rows: opts.rows ?? 30,
+            })
+            : null;
+        const entry = {
+            meta,
+            pty,
+            mirror,
+            dataSubs: new Set(),
+            connSubs: new Map(),
+            writer: null,
+            hadDataWritten: false,
+            lastResizeCols: null,
+            lastResizeRows: null,
+            pendingByConn: new Map(),
+            pauseRefCount: 0,
+            pausedConns: new Set(),
+            bufferedExceededSince: new Map(),
+            closing: false,
+        };
+        this.entries.set(taskId, entry);
+        // Forward pty output to all subscribers + reset idle timer.
+        pty.onData((data) => {
+            this.touchIdle(entry);
+            // ADR-068-A1: persist to disk before broadcast (fs.appendFileSync;
+            // try/catch so a disk error never breaks the broadcaster). D01 #2 —
+            // skip once torn down so a stuck shell can't re-create <taskId>.log.
+            if (this.scrollbackStore && !entry.tornDown) {
+                try {
+                    this.scrollbackStore.append(taskId, Buffer.from(data, "utf8"));
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[pty-manager] scrollback append failed for ${taskId}: ${err.message}`);
+                }
+            }
+            // ADR-088: shadow-write to the headless mirror. The mirror's
+            // write() returns a Promise that resolves after the parser
+            // callback fires; we kick it off but DO NOT await — the
+            // broadcast must stay synchronous so the WS write loop is not
+            // serialized behind xterm.js's parser. The promise resolves on
+            // the next microtask and any throw is swallowed by `.catch`.
+            // Architecture invariant #3 (await before serialize) is held by
+            // serializeStable() at snapshot time — not by every chunk write.
+            if (entry.mirror) {
+                entry.mirror.write(data).catch((err) => {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[pty-manager] headless mirror write failed for ${taskId}: ${err.message}`);
+                });
+            }
+            for (const cb of entry.dataSubs) {
+                try {
+                    cb(data);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            for (const [conn, sub] of entry.connSubs) {
+                this.deliverWithBackpressure(entry, conn, sub, data);
+            }
+        });
+        pty.onExit(() => {
+            // AC-2 — intentional kill (closing=true) appends a dim-grey
+            // "shell stopped" marker AFTER the dying-process flush drains
+            // (onExit fires once stdio handles closed). Natural exit → none.
+            if (entry.closing && this.scrollbackStore) {
+                this.appendShellStoppedMarker(taskId);
+            }
+            this.cleanup(taskId);
+            // D01/F01 — release a delete-cascade kill() awaiting full teardown.
+            entry.onExitDone?.();
+        });
+        this.touchIdle(entry);
+        return meta;
+    }
+    /**
+     * iterate-2026-05-08 v0.8.7 AC-2 — append a single dim-grey ANSI marker
+     * frame to disk-scrollback on intentional kill. Best-effort; never throws
+     * (onExit cleanup must stay infallible). Format:
+     *
+     *     \r\n\x1b[2m──── shell stopped at HH:MM:SS ────\x1b[m\r\n
+     *
+     * Timing safety (openai 2026-05-08 high; D01 #5): ScrollbackStore.append()
+     * is fs.appendFileSync — one open(O_APPEND)→write→close per call, no
+     * per-task WriteStream. closeStream() only resets the size cache, so the
+     * marker append in onExit CANNOT land on a closed handle even though kill()
+     * fires closeStream before awaiting onExit; a deleted entry doesn't affect
+     * append correctness (lookup by taskId + reopen each call).
+     */
+    appendShellStoppedMarker(taskId) {
+        if (!this.scrollbackStore)
+            return;
+        try {
+            const ts = new Date().toISOString().slice(11, 19);
+            const marker = `\r\n\x1b[2m──── shell stopped at ${ts} ────\x1b[m\r\n`;
+            this.scrollbackStore.append(taskId, Buffer.from(marker, "utf8"));
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[pty-manager] shell-stopped marker append failed for ${taskId}: ${err.message}`);
+        }
+    }
+    write(taskId, data) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return;
+        this.touchIdle(entry);
+        // The one signal for "no longer virgin" — set on real input, never
+        // at attach-time (iterate-2026-08-16-task-lifecycle-ux-fixes).
+        entry.hadDataWritten = true;
+        entry.pty.write(data);
+    }
+    resize(taskId, cols, rows) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return;
+        // Iterate v0.8.6 AC-2 — dedupe no-op resizes. ConPTY (and node-pty)
+        // emit a SIGWINCH-driven redraw on EVERY pty.resize call, even when
+        // (cols, rows) match the current state. PowerShell's READLINE
+        // responds to that by repainting "version banner + prompt + typed
+        // line" — ~1 KiB per redraw. With multiple WS attaches per visit
+        // (StrictMode double-mount) and multiple visits per session, this
+        // accumulates as the "100 Claude banner" symptom in xterm. Skip
+        // the call when nothing changed; the pty already has the right
+        // dimensions.
+        if (entry.lastResizeCols === cols && entry.lastResizeRows === rows) {
+            return;
+        }
+        entry.lastResizeCols = cols;
+        entry.lastResizeRows = rows;
+        entry.pty.resize(cols, rows);
+        // ADR-088: keep the headless mirror's dimensions in lockstep so the
+        // M2 stabilization at snapshot time uses the right cols/rows.
+        if (entry.mirror) {
+            try {
+                entry.mirror.resize(cols, rows);
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn(`[pty-manager] mirror resize failed for ${taskId}: ${err.message}`);
+            }
+        }
+    }
+    /**
+     * Post-replay redraw nudge (iterate-2026-07-27, FR-01.28) — re-apply the pty's
+     * CURRENT dimensions, deliberately bypassing `resize()`'s no-op dedupe.
+     *
+     * node-pty raises a SIGWINCH-driven redraw on EVERY `pty.resize` call, changed
+     * or not. `resize()` dedupes that (v0.8.6 AC-2, PowerShell banner spam) and
+     * MUST keep doing so — but the dedupe also swallows the one signal a fullscreen
+     * TUI needs after we restore a cell-state snapshot it never drew (ADR-087):
+     * Claude Code then repaints differentially with CUF cell-skips, which do not
+     * erase, so every skipped cell keeps a stale character. Rationale + the
+     * deterministic reproduction: `cuf-stale-cell-repro.test.ts`.
+     *
+     * Dimension-LESS by design (a caller cannot reflow the grid it is repairing)
+     * and at-most-once per attach (the dedupe is bypassed here — a loop re-creates
+     * the v0.8.6 spam). No-op for an unknown / torn-down / never-sized pty.
+     */
+    forceRedraw(taskId) {
+        const entry = this.entries.get(taskId);
+        if (!entry || entry.tornDown)
+            return;
+        const cols = entry.lastResizeCols;
+        const rows = entry.lastResizeRows;
+        if (typeof cols !== "number" || typeof rows !== "number")
+            return;
+        try {
+            entry.pty.resize(cols, rows);
+        }
+        catch (err) {
+            // `(err as Error).message` is NOT safe here: JS permits `throw null`, in
+            // which case the property read throws again and escapes this catch — out
+            // through the WS message handler. AC-3 promises swallowing, so format
+            // defensively (external code review MEDIUM).
+            const message = err instanceof Error ? err.message : String(err);
+            // eslint-disable-next-line no-console
+            console.warn(`[pty-manager] forceRedraw failed for ${taskId}: ${message}`);
+        }
+        // Mirror dims are unchanged, so it is deliberately NOT resized (ADR-088).
+    }
+    async kill(taskId) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return;
+        // AC-2 — flag intentional kill so onExit appends the marker; a duplicate
+        // kill() is a no-op (entry already gone). D01 #2 — tombstone the entry first
+        // so a parked flush / stuck-shell onData can't resurrect the wiped side-files.
+        entry.closing = true;
+        entry.tornDown = true;
+        // D01/F01 — a live entry guarantees onExit fires; `exited` = the marker append.
+        const exited = new Promise((r) => { entry.onExitDone = r; });
+        try {
+            entry.pty.kill();
+        }
+        catch {
+            // best-effort
+        }
+        // D01 #3 — cleanup stores the SINGLE finalize on the entry; read it here so
+        // a synchronous onExit (which ran cleanup already) is still awaited.
+        this.cleanup(taskId);
+        const finalize = entry.finalizePromise ?? Promise.resolve();
+        if (this.scrollbackStore) {
+            void this.scrollbackStore
+                .closeStream(taskId)
+                .catch((err) => {
+                // eslint-disable-next-line no-console
+                console.warn(`[pty-manager] scrollback closeStream failed for ${taskId}: ${err.message}`);
+            });
+        }
+        // D01 #1 — never hang the DELETE: finalize (privacy) is fully awaited; the
+        // proof-of-death `exited` degrades to a bounded 3 s ceiling (onExit is
+        // reliable for a live entry, but pty.kill() could throw / child could wedge).
+        await Promise.allSettled([
+            Promise.race([exited, new Promise((r) => { setTimeout(r, 3000).unref?.(); })]),
+            finalize,
+        ]);
+    }
+    killAll() {
+        // D01 #4 — kill() is async now, but shutdown must not block on per-pty
+        // teardown; finalize writes are best-effort on process death (pre-existing
+        // F26, orphaned tmps swept by snapshot-tmp-sweep). Fire-and-forget.
+        const taskIds = [...this.entries.keys()];
+        for (const id of taskIds)
+            void this.kill(id);
+        if (this.watchdogTimer !== null) {
+            clearInterval(this.watchdogTimer);
+            this.watchdogTimer = null;
+        }
+    }
+    /**
+     * Pause the live pty (ADR-068-A1) — anonymous-token API kept for
+     * backwards compat. Per-conn pause ownership is preferred via
+     * `pauseForConn(taskId, connToken)` so the watchdog's force-evict
+     * path can clean up specific stakes (per Gemini #3 + OpenAI #12).
+     */
+    pause(taskId) {
+        this.pauseForConn(taskId, ANON_PAUSE_TOKEN);
+    }
+    /** Counterpart to pause(). Idempotent — calling on a non-paused pty is a no-op. */
+    resume(taskId) {
+        this.resumeForConn(taskId, ANON_PAUSE_TOKEN);
+    }
+    /**
+     * AC-3a (iterate-2026-05-05). Pause the live pty under per-conn refcount
+     * ownership. Multiple conns can each hold their own pause stake;
+     * `pty.pause()` fires only on the 0→1 transition, `pty.resume()` only
+     * on the 1→0 transition. Idempotent for the same conn.
+     */
+    pauseForConn(taskId, connToken) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return;
+        if (entry.pausedConns.has(connToken))
+            return;
+        entry.pausedConns.add(connToken);
+        entry.pauseRefCount++;
+        if (entry.pauseRefCount === 1 && entry.pty.pause) {
+            try {
+                entry.pty.pause();
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn(`[pty-manager] pause failed for ${taskId}: ${err.message}`);
+            }
+        }
+    }
+    /**
+     * Counterpart to pauseForConn. Idempotent — silent no-op when the
+     * conn was not pausing (e.g. force-evicted twice, or never paused).
+     */
+    resumeForConn(taskId, connToken) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return;
+        if (!entry.pausedConns.has(connToken))
+            return;
+        entry.pausedConns.delete(connToken);
+        entry.pauseRefCount = Math.max(0, entry.pauseRefCount - 1);
+        if (entry.pauseRefCount === 0 && entry.pty.resume) {
+            try {
+                entry.pty.resume();
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn(`[pty-manager] resume failed for ${taskId}: ${err.message}`);
+            }
+        }
+    }
+    /**
+     * Generic data subscription used by tests + non-WS observers. Do NOT use
+     * for WS connections — those go through subscribeForConnection so the
+     * backpressure machinery sees them.
+     */
+    subscribe(taskId, cb) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return () => undefined;
+        entry.dataSubs.add(cb);
+        return () => {
+            entry.dataSubs.delete(cb);
+        };
+    }
+    /**
+     * Bind a WS connection. First attach is writer, the rest are readers.
+     * Idempotent: re-attaching the same `conn` returns its existing role
+     * (so onMessage can re-call attach to look up role without flipping
+     * the writer-slot — closes external code-review F6).
+     */
+    attach(taskId, conn) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            throw new Error(`pty-manager: attach to unknown task ${taskId}`);
+        // Atomic snapshot BEFORE mutation — closes the race a separate
+        // public read would expose against concurrent attach() calls
+        // (external review HIGH, iterate-2026-05-27-fix-pty-reused-prewarm-race).
+        // Sourced from hadDataWritten — see AttachResult.hadPriorWriter's doc comment.
+        const hadPriorWriter = entry.hadDataWritten;
+        let role;
+        if (entry.writer === null) {
+            entry.writer = conn;
+            role = "writer";
+        }
+        else if (entry.writer === conn) {
+            // Re-attach by the same conn — keep its writer role (idempotent).
+            role = "writer";
+        }
+        else {
+            role = "reader";
+        }
+        if (!entry.connSubs.has(conn)) {
+            // Placeholder — the routes layer calls subscribeForConnection right after.
+            entry.connSubs.set(conn, { onData: () => undefined });
+        }
+        // Attachment-gating (2026-06-02): a watching client disarms the grace.
+        this.touchIdle(entry);
+        return { role, hadPriorWriter };
+    }
+    /**
+     * Non-mutating role lookup. Use this in hot paths (e.g. onMessage)
+     * where calling `attach` would re-run the writer-slot decision logic.
+     * Returns `null` for unknown task or unbound connection.
+     */
+    getRole(taskId, conn) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return null;
+        if (!entry.connSubs.has(conn))
+            return null;
+        return entry.writer === conn ? "writer" : "reader";
+    }
+    /**
+     * Whether the entry currently has any writer bound. Used by
+     * /paste-image to refuse pty-injection when no live writer exists
+     * (external code-review F3 — writer-ownership tightening).
+     */
+    hasActiveWriter(taskId) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return false;
+        return entry.writer !== null;
+    }
+    /**
+     * Iterate E (ADR-092) — number of currently-attached WS connections
+     * for the task. Includes writer + every reader. The routes WS-close
+     * handler uses this to decide whether to trigger
+     * `flushMirrorSnapshot` (only when the count drops to 0).
+     *
+     * Returns 0 for unknown tasks (no entry).
+     */
+    attachCount(taskId) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return 0;
+        return entry.connSubs.size;
+    }
+    /**
+     * Iterate E (ADR-092) — serialize the live headless mirror on demand
+     * and return a SnapshotRecord (NOT written to disk). Used by the WS
+     * attach replay flow as a fallback when `tryReadSnapshot` returns
+     * null for a LIVE pty: without this path, re-attach to a live pty
+     * yields a blank terminal (the original ADR-091 bug).
+     *
+     * Returns null when:
+     *   - no entry for `taskId`,
+     *   - entry exists but `mirror === null` (flag-disabled OR
+     *     initialization refused),
+     *   - `mirror.serializeStable()` throws (e.g. mirror in cleanup).
+     *
+     * The returned record's `terminalVersion` is the value passed via
+     * `PtyManagerOpts.expectedTerminalVersion` at construction time —
+     * keeping it coupled to the same pinned `@xterm/headless` version
+     * the WS replay path's version-gate expects. When unset, defaults
+     * to `"unknown"` matching SnapshotStore's last-resort sentinel.
+     *
+     * Best-effort: never throws; logs warn on serialize failure.
+     */
+    async serializeMirrorIfLive(taskId) {
+        const entry = this.entries.get(taskId);
+        if (!entry || !entry.mirror)
+            return null;
+        try {
+            const stable = await entry.mirror.serializeStable();
+            const { cols, rows } = entry.mirror.dimensions;
+            return {
+                version: "v2",
+                terminalVersion: this.expectedTerminalVersion,
+                cols,
+                rows,
+                data: stable,
+            };
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[pty-manager] live-mirror serialize failed for ${taskId}: ${err.message}`);
+            return null;
+        }
+    }
+    /**
+     * iterate-2026-05-18-inbox-terminal-prompts — decoded visible-viewport
+     * text of the live headless mirror, or `null` when there is no live
+     * mirror for `taskId` (no entry, or `mirror === null` — flag off /
+     * pty exited / external-terminal launch).
+     *
+     * Consumed by the `/api/external/inbox` route to detect a waiting
+     * `AskUserQuestion` picker — the picker is on-screen, never journaled
+     * to the JSONL. Synchronous + best-effort: never throws (it sits
+     * behind a 3 s inbox poll).
+     */
+    peekTerminalText(taskId) {
+        const entry = this.entries.get(taskId);
+        if (!entry || !entry.mirror)
+            return null;
+        try {
+            return entry.mirror.getVisibleText();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Iterate E (ADR-092) — persist the live headless mirror to disk via
+     * `SnapshotStore.write()`, but do NOT dispose the mirror. The pty
+     * stays alive so subsequent `pty.onData` chunks keep mirroring and
+     * subsequent `serializeMirrorIfLive()` calls still return fresh
+     * state.
+     *
+     * This is the "snapshot-on-detach" half of the ADR-092 fix: when the
+     * last WS subscriber detaches, the routes layer fires this so the
+     * next attach (potentially after server restart) finds an on-disk
+     * snapshot at `tryReadSnapshot`. Without it, a Hono restart loses
+     * every live-pty's state since the last `pty.kill`.
+     *
+     * The write goes through the shared ADR-096 preservation gate
+     * (`writeSnapshotPreservingLarger`, snapshot-preserve.ts) — SAME gate
+     * finalizeMirrorSnapshot uses. Before this was shared, flush wrote
+     * unconditionally and could clobber a richer on-disk snapshot with a
+     * thin mirror (Claude TUI alt-screen exit) on the 2nd detach→reopen
+     * cycle, blanking the scrollback. The gate skips the write when the
+     * new payload is substantially smaller than the existing one.
+     *
+     * CLAUDE.md rule 21 / ADR-092: flush is a KEEP-ALIVE path — it MUST
+     * NOT dispose the mirror (the pty stays alive so subsequent onData
+     * keeps mirroring). Only finalizeMirrorSnapshot disposes.
+     *
+     * No-op when:
+     *   - no entry for `taskId`,
+     *   - entry has no mirror (flag off),
+     *   - no `snapshotStore` wired.
+     *
+     * Best-effort: never throws. Caller can fire-and-forget.
+     */
+    async flushMirrorSnapshot(taskId) {
+        const entry = this.entries.get(taskId);
+        if (!entry || !entry.mirror || !this.snapshotStore)
+            return;
+        try {
+            const stable = await entry.mirror.serializeStable();
+            // D01 #2 — re-check the captured entry on THIS tick: a flush that parked
+            // at serializeStable across a delete's kill+clear must NOT re-land the file.
+            if (entry.tornDown)
+                return;
+            const { cols, rows } = entry.mirror.dimensions;
+            // ADR-096 shared preservation gate — do NOT clobber a richer on-disk
+            // snapshot with a thinner mirror (see snapshot-preserve.ts). Same gate
+            // as finalizeMirrorSnapshot. Mirror is NOT disposed here (rule 21).
+            //
+            // shouldProceed re-checks entry.tornDown SYNCHRONOUSLY immediately
+            // before the write enqueue — the helper's unqueued `await store.read`
+            // yields the loop after the guard above, so a delete cascade that lands
+            // in that gap (kill sets tornDown + clear() unlinks the snapshot) MUST
+            // abort this write, or it would resurrect the just-wiped secret-bearing
+            // snapshot (doubt-review HIGH, iterate-2026-07-12). finalize OMITS this
+            // predicate — its kill-path write is authoritative and must land.
+            await writeSnapshotPreservingLarger(this.snapshotStore, taskId, { cols, rows, data: stable }, { caller: "flushMirrorSnapshot", shouldProceed: () => !entry.tornDown });
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[pty-manager] flushMirrorSnapshot failed for ${taskId}: ${err.message}`);
+        }
+    }
+    /** Replace the placeholder subscription with the routes' real callbacks. */
+    subscribeForConnection(taskId, conn, sub) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return;
+        entry.connSubs.set(conn, sub);
+        if (!entry.pendingByConn.has(conn)) {
+            entry.pendingByConn.set(conn, { bytes: 0, queue: [] });
+        }
+    }
+    /**
+     * Iterate E (ADR-092) — detach + count-after.
+     *
+     * Returns `{ remainingAttachCount }` so routes layer can decide on the
+     * snapshot-on-last-detach trigger atomically with the detach itself —
+     * closes the race the external code review (OpenAI HIGH #1) flagged
+     * in the original split-step design (check count → detach → check
+     * count again was vulnerable to concurrent attach landing in
+     * between).
+     *
+     * Detaches AND returns the post-detach count in one observation; the
+     * caller's "becameZero" branch is `remainingAttachCount === 0`. The
+     * underlying `connSubs.delete` is synchronous, so no inter-step
+     * window remains.
+     */
+    detachAndCount(taskId, conn) {
+        this.detach(taskId, conn);
+        return { remainingAttachCount: this.attachCount(taskId) };
+    }
+    /**
+     * Detach a WS conn. If conn was writer, the slot is freed and any
+     * remaining reader connection is promoted to writer (with onPromoteToWriter
+     * fired so the routes layer can notify that client).
+     *
+     * 2026-05-05 — last-detach NO LONGER kills the pty. The previous
+     * "no orphan tab leak" policy collided fundamentally with ADR-068-A1
+     * (Iterate 5) Replay-on-Attach: any TaskBoard ↔ TaskDetail navigation
+     * closes the WS, the server killed the pty, and re-attaching produced
+     * a brand-new shell with no claude session — the symptom users report
+     * as "Session bleibt nicht aktiv". Orphan management now relies on:
+     *   - 30-min idle ceiling (touchIdle on every pty.onData)
+     *   - explicit user "Stop terminal session" menu action
+     *   - DELETE task cascade (Phase 4 Close-task-kills-pty)
+     *   - server shutdown
+     * The pty's process tree is bounded, the scrollback file is bounded
+     * (1 MiB rotated), and the daily sweep TTL also catches abandoned
+     * scrollback for tasks whose pty has long since exited.
+     */
+    detach(taskId, conn) {
+        // BEFORE the entry guard: accounts hang off the manager, not the entry, so a
+        // detach after the entry is gone (reaper / stop / delete) would leak one.
+        this.backpressure.release(conn);
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return;
+        // AC-3 cleanup (per Gemini #3 + OpenAI #12): if the detached conn
+        // held a pause stake (e.g. mid-replay watchdog eviction), release
+        // it so pty.resume fires and the refcount doesn't leak.
+        if (entry.pausedConns.has(conn)) {
+            this.resumeForConn(taskId, conn);
+        }
+        entry.connSubs.delete(conn);
+        entry.pendingByConn.delete(conn);
+        entry.bufferedExceededSince.delete(conn);
+        this.connCapability.delete(conn);
+        const wasWriter = entry.writer === conn;
+        if (wasWriter)
+            entry.writer = null;
+        if (wasWriter) {
+            // Promote the oldest remaining connection to writer (Map iteration
+            // order is insertion order). Closes the StrictMode double-mount race
+            // where the second WS opens BEFORE the first close arrives, takes
+            // reader role, and only learns about the freed writer slot via
+            // this promotion hook.
+            const next = entry.connSubs.keys().next();
+            if (!next.done) {
+                const promoted = next.value;
+                entry.writer = promoted;
+                const sub = entry.connSubs.get(promoted);
+                if (sub?.onPromoteToWriter) {
+                    try {
+                        sub.onPromoteToWriter();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+        }
+        // Attachment-gating (2026-06-02): arm the grace iff that was the last client.
+        this.touchIdle(entry);
+    }
+    // --- internals -----------------------------------------------------------
+    cleanup(taskId) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return;
+        this.idleReaper.cancel(taskId);
+        this.entries.delete(taskId);
+        // ADR-088: finalize the headless mirror snapshot, then dispose. D01 #3 —
+        // store the promise on the entry so BOTH onExit and kill() await the SAME
+        // finalize (a synchronous onExit no longer drops kill()'s await). Failures
+        // never propagate — finalizeMirrorSnapshot is best-effort/infallible.
+        if (entry.mirror && this.snapshotStore) {
+            entry.finalizePromise = this.finalizeMirrorSnapshot(taskId, entry.mirror);
+        }
+        else {
+            if (entry.mirror) {
+                try {
+                    entry.mirror.dispose();
+                }
+                catch { /* ignore */ }
+            }
+            entry.finalizePromise = Promise.resolve();
+        }
+    }
+    /**
+     * ADR-088 — produce the M2 stable snapshot and persist it. Best-effort:
+     * a disk failure here MUST NOT crash kill / onExit. Logs a structured
+     * warn on failure so observability picks it up.
+     *
+     * Why this is detached + async: kill() / onExit are synchronous
+     * lifecycle hooks. The double-serialize cycle costs ~10 ms per the
+     * spike — small but non-zero. Detaching keeps the close path
+     * responsive and avoids back-pressuring the broadcaster.
+     *
+     * Iterate H (ADR-096) — the write goes through the shared preservation
+     * gate `writeSnapshotPreservingLarger` (snapshot-preserve.ts): if an
+     * existing on-disk snapshot is substantially larger than the about-to-
+     * write one (a Claude TUI alt-screen-exit clear yields a near-empty
+     * cell-state), the write is SKIPPED so the richer replay artifact
+     * survives. Same gate flushMirrorSnapshot now uses (iterate-2026-07-12
+     * de-dup). mirror.dispose() + releaseQueue still run in `finally` on
+     * every branch (skip or write).
+     */
+    async finalizeMirrorSnapshot(taskId, mirror) {
+        try {
+            const stable = await mirror.serializeStable();
+            const { cols, rows } = mirror.dimensions;
+            if (this.snapshotStore) {
+                await writeSnapshotPreservingLarger(this.snapshotStore, taskId, { cols, rows, data: stable }, { caller: "finalizeMirrorSnapshot" });
+            }
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[pty-manager] snapshot finalize failed for ${taskId}: ${err.message}`);
+        }
+        finally {
+            try {
+                mirror.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+            // ADR-089 (external review gemini): release the snapshot-store's
+            // per-task write queue so the Map cannot grow unboundedly for
+            // long-lived processes that churn through many tasks. The
+            // queue's onIdle() is awaited internally so any concurrent
+            // write (rare — finalize is the only write surface) completes
+            // before the entry is dropped.
+            if (this.snapshotStore) {
+                try {
+                    await this.snapshotStore.releaseQueue(taskId);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        }
+    }
+    // Orphan grace is attachment-gated (idle-reaper.ts): armed only when no client is attached.
+    touchIdle(entry) {
+        this.idleReaper.touch(entry.meta.taskId, entry.connSubs.size);
+    }
+    /**
+     * Deliver outgoing pty data to a single WS connection subscriber,
+     * applying drop-while-saturated backpressure: if the WS already has
+     * more than `wsBufferBytes` queued on the wire, drop the new chunk
+     * and fire `onBackpressure` TWICE per saturation episode — once when it
+     * opens and once when delivery resumes, the latter carrying the accurate
+     * episode total (policy: backpressure-telemetry.ts, iterate-2026-07-30).
+     *
+     * Note (vs external code-review F7): the spec said "drop-oldest", which
+     * needs a server-side drain hook (@hono/node-ws exposes none) plus a
+     * bufferedAmount-poll loop. Drop-while-saturated is simpler and cannot
+     * grow the server buffer unboundedly if drains stall. What that note
+     * called an acceptable loss window is no longer merely accepted: the
+     * client answers with a `resync` and the bytes come back as a full grid
+     * (ws-upgrade-handler.ts performResync).
+     */
+    deliverWithBackpressure(entry, conn, sub, data) {
+        const live = conn.bufferedAmount;
+        const incoming = Buffer.byteLength(data, "utf8");
+        // AC-3b — per-conn capability stamp (post-code-review v3, openai-5).
+        if (!this.connCapability.has(conn)) {
+            this.connCapability.set(conn, typeof live === "number" ? "ok" : "missing");
+        }
+        // AC-3b — track when this conn's buffered backlog first exceeded
+        // the stuck threshold. The watchdog evicts based on this timestamp,
+        // NOT on pty.onData freshness (per external review v2 — gemini-2 +
+        // openai-9: a runaway pty would otherwise keep the writer pinned
+        // forever).
+        if (typeof live === "number") {
+            const exceeded = live > this.watchdogStuckThresholdBytes;
+            const prev = entry.bufferedExceededSince.get(conn);
+            if (exceeded && (prev === undefined || prev === null)) {
+                entry.bufferedExceededSince.set(conn, this.nowFn());
+            }
+            else if (!exceeded && prev !== null && prev !== undefined) {
+                entry.bufferedExceededSince.set(conn, null);
+            }
+        }
+        // Saturated: chunk discarded, NEVER resent — client answers with `resync`.
+        // Drained: closes the episode with the accurate total. See backpressure-telemetry.ts.
+        const saturated = typeof live === "number" && live + incoming > this.wsBufferBytes;
+        const notice = saturated
+            ? this.backpressure.onDrop(entry.meta.taskId, conn, incoming)
+            : this.backpressure.onDelivered(entry.meta.taskId, conn);
+        if (notice && sub.onBackpressure) {
+            try {
+                sub.onBackpressure(notice);
+            }
+            catch { /* ignore */ }
+        }
+        if (saturated)
+            return;
+        try {
+            sub.onData(data);
+        }
+        catch { /* ignore */ }
+    }
+    /**
+     * AC-3b watchdog tick. Walks every entry; for each one with a writer,
+     * checks how long the writer's WS bufferedAmount has been above the
+     * stuck threshold. Beyond `watchdogStuckDurationMs`, evict via
+     * `detach()` so the cleanup chain (pause refcount release + reader
+     * promotion + onPromoteToWriter) runs.
+     *
+     * Capability is tracked PER-CONN (post-code-review openai-5). A
+     * single legacy WS adapter without bufferedAmount no longer disables
+     * eviction for healthy conns sharing the same manager.
+     */
+    watchdogTick() {
+        for (const [taskId, entry] of this.entries) {
+            const writer = entry.writer;
+            if (writer === null)
+                continue;
+            // Per-conn capability check.
+            if (this.connCapability.get(writer) === "missing")
+                continue;
+            const live = writer.bufferedAmount;
+            if (typeof live !== "number") {
+                // Stamp this writer as missing-capability + warn once globally.
+                this.connCapability.set(writer, "missing");
+                if (!this.capabilityWarnLogged) {
+                    this.capabilityWarnLogged = true;
+                    // eslint-disable-next-line no-console
+                    console.warn("[pty-manager] watchdog disabled for one or more writers — WSContext does not expose bufferedAmount; falling back to ws.close-driven release for affected conns");
+                }
+                continue;
+            }
+            this.connCapability.set(writer, "ok");
+            // If the writer's backlog crossed threshold mid-tick (no prior
+            // delivery to record it via deliverWithBackpressure), record now.
+            const prev = entry.bufferedExceededSince.get(writer);
+            const exceeded = live > this.watchdogStuckThresholdBytes;
+            if (exceeded && (prev === undefined || prev === null)) {
+                entry.bufferedExceededSince.set(writer, this.nowFn());
+                continue;
+            }
+            if (!exceeded) {
+                if (prev !== null && prev !== undefined) {
+                    entry.bufferedExceededSince.set(writer, null);
+                }
+                continue;
+            }
+            // exceeded === true && prev !== null/undefined — check stuck duration.
+            if (typeof prev === "number" && this.nowFn() - prev >= this.watchdogStuckDurationMs) {
+                // Stuck — evict. detach() runs the pause-refcount cleanup +
+                // promotes the next reader. Log so UAT can correlate.
+                // eslint-disable-next-line no-console
+                console.warn(`[pty-manager] watchdog evicting stuck writer for task ${taskId} (bufferedAmount=${live}B for ${this.nowFn() - prev}ms)`);
+                this.detach(taskId, writer);
+            }
+        }
+    }
+}
+//# sourceMappingURL=pty-manager.js.map