@roamcode.ai/server 1.0.0

package/dist/terminal-manager.js

@@ -0,0 +1,917 @@
+// packages/server/src/terminal-manager.ts
+import { unlinkSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { TerminalProcess, tmuxSessionName, TMUX_SOCKET } from "./terminal-process.js";
+import { capturePane } from "./pane-status.js";
+import { CODEX_MCP_TOKEN_PREFIX } from "./config.js";
+import { parseLegacyClaudeArgs } from "./providers/options.js";
+import { ProviderRegistry } from "./providers/registry.js";
+import { ProviderError, } from "./providers/types.js";
+import { createCodexThreadPersistence } from "./providers/codex-thread-persistence.js";
+import { codexThreadResolutionCoordinator } from "./providers/codex-thread-coordinator.js";
+/** Cap the per-session replay buffer of attachment frames so a long-lived session can't grow unbounded. */
+const MAX_ATTACHMENT_BUFFER = 50;
+const clampDim = (n, fallback) => Math.max(1, Math.trunc(n ?? fallback) || fallback);
+function claudeArgsOf(options) {
+    const args = [];
+    if (options.model)
+        args.push("--model", options.model);
+    if (options.effort)
+        args.push("--effort", options.effort);
+    if (options.permissionMode)
+        args.push("--permission-mode", options.permissionMode);
+    if (options.dangerouslySkip)
+        args.push("--dangerously-skip-permissions");
+    for (const dir of options.addDirs ?? [])
+        args.push("--add-dir", dir);
+    args.push(...(options.legacyArgs ?? []));
+    return args;
+}
+export class TerminalManager {
+    deps;
+    records = new Map();
+    providers;
+    attachConfig;
+    constructor(deps) {
+        this.deps = deps;
+        this.providers = deps.providers;
+    }
+    /** Late-bound (after listen(), which resolves the loopback port) — same config the chat SessionManager
+     *  gets. When set, each terminal's claude is spawned with `--mcp-config` so send_image/send_file work. */
+    setAttachConfig(attach) {
+        this.attachConfig = attach;
+    }
+    create(explicit) {
+        if (explicit.options.provider !== explicit.provider) {
+            throw new ProviderError("INVALID_PROVIDER_OPTIONS", "provider and options provider must match");
+        }
+        this.providers.get(explicit.provider);
+        if (this.records.has(explicit.id)) {
+            throw new Error(`Session id ${explicit.id} already exists`);
+        }
+        const now = this.deps.now();
+        const options = explicit.options;
+        const dangerouslySkip = options.provider === "claude"
+            ? options.dangerouslySkip === true
+            : options.dangerouslyBypassApprovalsAndSandbox === true;
+        const meta = {
+            id: explicit.id,
+            provider: explicit.provider,
+            cwd: explicit.cwd,
+            mode: "terminal",
+            status: "running",
+            createdAt: now,
+            lastActivityAt: now,
+            activity: "idle", // the ~2.5s monitor flips it to "working" as soon as claude starts generating
+            awaiting: false,
+            dangerouslySkip,
+            model: options.model,
+            effort: options.provider === "claude" ? options.effort : options.reasoningEffort,
+            ...(options.provider === "claude"
+                ? { permissionMode: options.permissionMode }
+                : { sandbox: options.sandbox, approvalPolicy: options.approvalPolicy }),
+            ...(options.provider === "codex" ? { identityState: "pending" } : {}),
+        };
+        const common = {
+            meta,
+            cols: clampDim(explicit.cols, 80),
+            rows: clampDim(explicit.rows, 24),
+            subs: new Set(),
+            cleanupPaths: new Set(),
+            attachments: [],
+            adoptedLive: false,
+        };
+        if (options.provider === "claude") {
+            const spawnArgs = claudeArgsOf(options);
+            this.deps.store.claimNew({
+                provider: "claude",
+                id: explicit.id,
+                cwd: explicit.cwd,
+                mode: "terminal",
+                dangerouslySkip,
+                status: "running",
+                createdAt: now,
+                lastActivityAt: now,
+                ...(spawnArgs.length > 0 ? { spawnArgs } : {}),
+            });
+            const record = { ...common, provider: "claude", options };
+            this.records.set(explicit.id, record);
+        }
+        else {
+            this.deps.store.claimNew({
+                provider: "codex",
+                id: explicit.id,
+                cwd: explicit.cwd,
+                mode: "terminal",
+                launchOptions: options,
+                status: "running",
+                createdAt: now,
+                lastActivityAt: now,
+            });
+            const record = { ...common, provider: "codex", options, identityAmbiguous: false };
+            this.records.set(explicit.id, record);
+        }
+        return meta;
+    }
+    /** Temporary explicit-Claude seam for the pre-provider transport. */
+    createLegacyClaude(opts) {
+        return this.create({
+            id: opts.id,
+            cwd: opts.cwd,
+            provider: "claude",
+            options: parseLegacyClaudeArgs(opts.claudeArgs ?? []),
+            ...(opts.cols === undefined ? {} : { cols: opts.cols }),
+            ...(opts.rows === undefined ? {} : { rows: opts.rows }),
+        });
+    }
+    /**
+     * Delete stale per-session 0600 files that hold the access token — `mcp-config-<id>.json`, `hooks-<id>.json`,
+     * `hook-auth-<id>`, and `codex-mcp-token-<id>`. A file is stale when no live session owns its id: leaked by a
+     * crash, an orphan-reap, a rehydrated record (which carries no such paths, so stop() never unlinks its files),
+     * or a token rotation. Call at boot AFTER rehydrate + setAttachConfig so `records` reflects the surviving
+     * sessions. No-op without an attach config.
+     */
+    sweepStaleMcpConfigs() {
+        if (!this.attachConfig)
+            return 0;
+        const dir = this.attachConfig.dataDir;
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return 0;
+        }
+        const liveIds = new Set(this.records.keys());
+        let removed = 0;
+        for (const name of names) {
+            const m = /^(?:mcp-config-|hooks-)(.+)\.json$/.exec(name) ?? /^(?:hook-auth-)(.+)$/.exec(name);
+            const sessionId = m?.[1] ?? (name.startsWith(CODEX_MCP_TOKEN_PREFIX) ? name.slice(CODEX_MCP_TOKEN_PREFIX.length) : undefined);
+            if (!sessionId || liveIds.has(sessionId))
+                continue;
+            try {
+                unlinkSync(join(dir, name));
+                removed += 1;
+            }
+            catch {
+                /* already gone / race — ignore */
+            }
+        }
+        return removed;
+    }
+    /**
+     * Kill running terminal sessions with NO attached client that have been idle longer than `ttlMs`. OFF by
+     * default (ttlMs <= 0) and opt-in via env (SESSION_IDLE_TTL_MS): sessions intentionally survive a
+     * disconnect for later reattach, so reaping them must never be the default — it's only for hosts that
+     * choose to bound the accumulation of detached claude+tmux processes. Returns the number reaped.
+     */
+    reapIdle(ttlMs) {
+        if (!(ttlMs > 0))
+            return 0;
+        const cutoff = this.deps.now() - ttlMs;
+        const stale = [];
+        for (const [id, rec] of this.records) {
+            if (rec.subs.size > 0 || rec.meta.status !== "running")
+                continue; // attached or already ended → keep
+            if (rec.meta.lastActivityAt <= cutoff)
+                stale.push(id);
+        }
+        for (const id of stale)
+            this.stop(id); // stop() kills tmux+claude, unlinks the mcp config, prunes the row
+        return stale.length;
+    }
+    /**
+     * Push a JSON control message to every attached client of a terminal session. An `attach` (file/image)
+     * frame is ALSO buffered (bounded, oldest-dropped) so a client that (re)connects later still sees files
+     * that arrived while it was away — see {@link attach}'s replay. Other control frames (e.g. `ask`, which
+     * has its own answer/replay flow in the transport) are delivered live only.
+     */
+    pushControl(id, msg) {
+        const rec = this.records.get(id);
+        if (!rec)
+            return false;
+        if (msg.t === "attach") {
+            rec.attachments.push(msg);
+            if (rec.attachments.length > MAX_ATTACHMENT_BUFFER)
+                rec.attachments.shift();
+        }
+        const json = JSON.stringify(msg);
+        for (const s of [...rec.subs]) {
+            try {
+                s.onControl?.(json);
+            }
+            catch {
+                /* ignore a bad sink */
+            }
+        }
+        return true;
+    }
+    /**
+     * Set a session's `awaiting` flag ("claude is blocked on YOU"). The capture-pane monitor
+     * ({@link refreshActivity}) is the authority for this flag in production; this explicit setter exists for
+     * direct overrides and is exercised by the manager's tests. Deterministic — no timers, no terminal scraping.
+     * A missing session is a no-op. Does NOT fire the away-from-desk push — the monitor owns that so it can gate
+     * on {@link isAttached}.
+     */
+    setAwaiting(id, value) {
+        const rec = this.records.get(id);
+        if (!rec)
+            return;
+        rec.meta.awaiting = value;
+        // Keep `activity` consistent for the instant case (the ask flow calls this the moment claude blocks on a
+        // question, before the monitor's next sweep): true → "blocked" so the rail shows "needs you" immediately.
+        // On false we don't know the real state, so leave `activity` for the monitor to re-derive from the pane.
+        if (value)
+            rec.meta.activity = "blocked";
+    }
+    /** Clear the awaiting flag (user is active / session ended). */
+    clearAwaiting(rec) {
+        rec.meta.awaiting = false;
+    }
+    /** Whether a session currently has ≥1 attached client (a live browser WS). The hook route uses this so the
+     *  away-from-desk push fires ONLY when nobody is watching. */
+    isAttached(id) {
+        return (this.records.get(id)?.subs.size ?? 0) > 0;
+    }
+    /** How many sessions are currently `awaiting` you. Threaded into each away-from-desk push as `badgeCount`
+     *  so the home-screen app badge tracks "how many sessions need you" (Android/desktop badge; iOS can't). */
+    awaitingCount() {
+        let n = 0;
+        for (const rec of this.records.values())
+            if (rec.meta.awaiting)
+                n += 1;
+        return n;
+    }
+    /**
+     * Set/clear a session's display name (PATCH /sessions/:id). `undefined` clears back to unnamed. Written
+     * through to the store so the name survives restarts + rehydrate. Returns false for an unknown id so the
+     * route can 404 without a separate lookup.
+     */
+    setName(id, name) {
+        const rec = this.records.get(id);
+        if (!rec)
+            return false;
+        rec.meta.name = name;
+        this.deps.store.setName(id, name);
+        return true;
+    }
+    /**
+     * Re-derive every RUNNING session's `awaiting` flag from its LIVE rendered tmux pane (`capture-pane`) — the
+     * single, UNIVERSAL source of truth for working / blocked / idle. Works for EVERY session (no per-session
+     * hooks needed → correct for sessions created before hooks existed) and works while the browser is DETACHED
+     * (it reads tmux directly). Called on a ~2.5s timer from start.ts. Read-only: it can never disturb a live
+     * session.
+     *
+     * {@link classifyPaneStatus} decides. A capture that returns "" (tmux hiccup) leaves the last value
+     * untouched so the status never flaps on a transient miss.
+     *
+     * `awaiting` (the loud "needs you" flag) tracks activity==="blocked" ONLY — a finished-but-idle session, or
+     * one whose background agents are still developing, is NOT "needs you". Fires
+     * {@link TerminalManagerDeps.onAwaiting} (the away push) on a not-blocked→blocked transition when no client is
+     * attached, so the nudge is universal + fires only for a genuine block.
+     */
+    async refreshActivity() {
+        const capture = this.deps.capturePane ??
+            ((name) => capturePane({ socket: this.deps.tmuxSocket ?? TMUX_SOCKET, sessionName: name }));
+        await Promise.all([...this.records.entries()].map(async ([id, rec]) => {
+            if (rec.meta.status !== "running")
+                return;
+            const pane = await capture(tmuxSessionName(id));
+            if (!pane)
+                return; // capture failed/empty → keep the last known value (don't flap on a transient miss)
+            const provider = this.providers.get(rec.provider);
+            const activity = provider.classifyPane(pane);
+            const runtimeMetadata = provider.runtimeMetadata?.(pane);
+            if (runtimeMetadata?.model)
+                rec.meta.model = runtimeMetadata.model;
+            if (runtimeMetadata?.effort)
+                rec.meta.effort = runtimeMetadata.effort;
+            const nowBlocked = activity === "blocked";
+            const wasBlocked = rec.meta.awaiting;
+            rec.meta.activity = activity;
+            rec.meta.awaiting = nowBlocked;
+            if (nowBlocked && !wasBlocked && rec.subs.size === 0) {
+                try {
+                    this.deps.onAwaiting?.(id);
+                }
+                catch {
+                    /* a push failure must never break the monitor */
+                }
+            }
+        }));
+    }
+    /**
+     * Nudge tmux to repaint the WHOLE screen for a session whose pty is already running — used when a client
+     * REATTACHES (a fresh xterm) to a still-live tmux client that drew its screen earlier and won't redraw on
+     * its own, so the new client would otherwise show only a blinking cursor until something changes. A brief
+     * pty size wiggle (+1 row, then back) sends SIGWINCH, which makes tmux redraw — exactly what the manual
+     * window-resize the user found does, minus the manual part. Deferred so the new client's own initial resize
+     * lands first (rec.cols/rec.rows are then the final size we wiggle around). Best-effort + unref'd timers.
+     */
+    forceRedraw(rec) {
+        const proc = rec.proc;
+        if (!proc)
+            return;
+        const t = setTimeout(() => {
+            if (rec.proc !== proc)
+                return; // detached / respawned in the meantime
+            proc.resize(rec.cols, Math.max(1, rec.rows + 1)); // wiggle up → SIGWINCH → tmux redraws
+            const back = setTimeout(() => {
+                if (rec.proc === proc)
+                    proc.resize(rec.cols, rec.rows); // ...then restore the real viewport size
+            }, 60);
+            if (typeof back.unref === "function")
+                back.unref();
+        }, 180);
+        if (typeof t.unref === "function")
+            t.unref();
+    }
+    /** Subscribe to provider output, spawning lazily through the owning provider on the first attach. */
+    async attach(id, handlers, size, opts) {
+        const rec = this.records.get(id);
+        if (!rec || opts?.signal?.aborted)
+            return undefined;
+        const resumeConversation = opts?.respawn === "continue" && rec.meta.status === "ended" && !rec.proc;
+        const provider = this.providers.get(rec.provider);
+        if (resumeConversation &&
+            provider.resumeIdentity === "required" &&
+            (rec.provider !== "codex" || rec.identityAmbiguous || !rec.providerSessionId)) {
+            throw new ProviderError("RESUME_IDENTITY_UNAVAILABLE", `exact resume identity unavailable for ${rec.provider} session ${id}`);
+        }
+        if (size && !rec.proc) {
+            rec.cols = clampDim(size.cols, rec.cols);
+            rec.rows = clampDim(size.rows, rec.rows);
+        }
+        let abortListenerAttached = false;
+        let detached = false;
+        const releaseAbortListener = () => {
+            if (!abortListenerAttached)
+                return;
+            abortListenerAttached = false;
+            opts?.signal?.removeEventListener("abort", abortPendingAttach);
+        };
+        const sub = {
+            onData: handlers.onData,
+            onExit: handlers.onExit,
+            onControl: handlers.onControl,
+            releaseAbortListener,
+        };
+        const detach = () => {
+            if (detached)
+                return;
+            detached = true;
+            releaseAbortListener();
+            rec.subs.delete(sub);
+            // Keep the owning PTY client while detached: its runtime/exit listeners are the lifecycle monitor for
+            // the provider and tmux session. Data fanout is already a no-op with no subscribers, and a later attach
+            // reuses this process instead of double-spawning or losing provider cleanup ownership.
+            if (rec.subs.size === 0 && rec.meta.awaiting && rec.meta.status === "running") {
+                try {
+                    this.deps.onAwaiting?.(id);
+                }
+                catch {
+                    /* a push must NEVER break the terminal */
+                }
+            }
+        };
+        const abortPendingAttach = () => detach();
+        opts?.signal?.addEventListener("abort", abortPendingAttach, { once: true });
+        abortListenerAttached = opts?.signal !== undefined;
+        rec.subs.add(sub);
+        // Replay any file/image attachments that arrived while this client was away, so the Files panel is
+        // correct on (re)connect. Only to the newly-attached sub. Each attach frame carries a unique `id`, so
+        // the web can dedupe a replayed frame it already rendered. Wrapped so a bad sink can't break attach.
+        if (sub.onControl && rec.attachments.length > 0) {
+            for (const msg of rec.attachments) {
+                try {
+                    sub.onControl(JSON.stringify(msg));
+                }
+                catch {
+                    /* ignore a bad sink */
+                }
+            }
+        }
+        const joinedLiveProcess = rec.proc !== undefined;
+        if (!rec.proc) {
+            try {
+                const intent = resumeConversation ? "resume" : "fresh";
+                if (rec.spawnPromise && rec.spawnIntent !== intent) {
+                    throw new ProviderError("RESUME_IDENTITY_UNAVAILABLE", `conflicting concurrent attach intent for ${rec.provider} session ${id}`);
+                }
+                if (!rec.spawnPromise) {
+                    const promise = this.spawnForRecord(id, rec, intent);
+                    rec.spawnPromise = promise;
+                    rec.spawnIntent = intent;
+                    void promise.then(() => {
+                        if (rec.spawnPromise === promise) {
+                            rec.spawnPromise = undefined;
+                            rec.spawnIntent = undefined;
+                        }
+                    }, () => {
+                        if (rec.spawnPromise === promise) {
+                            rec.spawnPromise = undefined;
+                            rec.spawnIntent = undefined;
+                        }
+                    });
+                }
+                await rec.spawnPromise;
+            }
+            catch (error) {
+                detach();
+                throw error;
+            }
+            if (!rec.proc) {
+                detach();
+                return undefined;
+            }
+        }
+        if (joinedLiveProcess) {
+            // Reattaching to a STILL-RUNNING session: its pty/tmux client is alive from an earlier connection whose
+            // WS never cleanly closed (e.g. the app was backgrounded a long time, so the old sub lingered and the pty
+            // wasn't torn down + respawned). tmux drew its screen to that pty long ago, so THIS fresh xterm receives
+            // no redraw and shows only a blinking cursor until something changes — the reported "open an old chat →
+            // blank until I resize the window" bug. Nudge tmux to repaint the whole screen. See forceRedraw.
+            //
+            // ALT-SCREEN HANDOFF: a tmux client sits on the ALTERNATE screen for its whole attached life, but it
+            // sent that enter sequence (`smcup`, \x1b[?1049h) only ONCE — down the pty when it first attached, to a
+            // subscriber that's long gone. A fresh xterm joining this LIVE pty therefore renders the coming redraw
+            // into its NORMAL buffer: every repaint stacks into local scrollback (a phantom right-hand scrollbar),
+            // and the web client's two-finger gesture — which picks claude's pager vs local scrollback by the
+            // active buffer type — silently degrades to scrolling that junk buffer (user report: "sağda scrollbar
+            // çıkıyor, arkaya çok az kaydırabiliyorum"). Flip the newcomer onto the alt screen BEFORE the redraw.
+            try {
+                sub.onData("\x1b[?1049h");
+            }
+            catch {
+                /* ignore a bad sink */
+            }
+            this.forceRedraw(rec);
+        }
+        return {
+            unsubscribe: () => {
+                detach();
+            },
+        };
+    }
+    async spawnForRecord(id, rec, intent) {
+        const provider = this.providers.get(rec.provider);
+        const buildingCleanupPaths = new Set();
+        try {
+            const adoptingLive = rec.adoptedLive && intent === "fresh";
+            const spec = adoptingLive
+                ? { executable: "/usr/bin/true", args: [], env: process.env, cleanupPaths: [] }
+                : await provider.buildProcess({
+                    roamSessionId: id,
+                    cwd: rec.meta.cwd,
+                    intent,
+                    options: rec.options,
+                    ...(this.attachConfig ? { attach: this.attachConfig } : {}),
+                    ...(intent === "resume" && rec.provider === "codex" && rec.providerSessionId
+                        ? { providerSessionId: rec.providerSessionId }
+                        : {}),
+                    registerCleanupPaths: (paths) => {
+                        for (const path of paths)
+                            buildingCleanupPaths.add(path);
+                    },
+                });
+            for (const path of spec.cleanupPaths)
+                buildingCleanupPaths.add(path);
+            if (this.records.get(id) !== rec || rec.subs.size === 0) {
+                this.cleanupProviderPaths(provider, [...buildingCleanupPaths]);
+                buildingCleanupPaths.clear();
+                return undefined;
+            }
+            for (const path of buildingCleanupPaths)
+                rec.cleanupPaths.add(path);
+            buildingCleanupPaths.clear();
+            const startProcess = () => {
+                const candidate = new TerminalProcess({
+                    sessionId: id,
+                    cwd: rec.meta.cwd,
+                    executable: spec.executable,
+                    args: spec.args,
+                    env: spec.env,
+                    cols: rec.cols,
+                    rows: rec.rows,
+                    enableMouseHistory: rec.provider === "codex",
+                    ...(this.deps.ptySpawn ? { ptySpawn: this.deps.ptySpawn } : {}),
+                    ...(this.deps.runTmux ? { runTmux: this.deps.runTmux } : {}),
+                    ...(this.deps.tmuxSocket ? { tmuxSocket: this.deps.tmuxSocket } : {}),
+                    ...(adoptingLive ? { attachOnly: true } : {}),
+                });
+                const runtimeSignalParser = provider.createRuntimeSignalParser?.();
+                candidate.on("data", (chunk) => {
+                    try {
+                        const signals = runtimeSignalParser ? runtimeSignalParser.push(chunk) : provider.runtimeSignals(chunk);
+                        for (const signal of signals)
+                            this.applyRuntimeSignal(id, rec, signal);
+                    }
+                    catch {
+                        /* malformed provider output must not interrupt PTY fanout */
+                    }
+                    for (const sink of [...rec.subs]) {
+                        try {
+                            sink.onData(chunk);
+                        }
+                        catch {
+                            /* ignore a bad sink */
+                        }
+                    }
+                });
+                candidate.on("exit", () => {
+                    if (rec.proc !== candidate)
+                        return;
+                    rec.meta.status = "ended";
+                    rec.meta.activity = "idle";
+                    this.clearAwaiting(rec);
+                    rec.proc = undefined;
+                    this.cleanupRecordPaths(rec, provider);
+                    const dying = [...rec.subs];
+                    const wasAttached = dying.length > 0;
+                    for (const sink of dying)
+                        sink.releaseAbortListener();
+                    rec.subs.clear();
+                    for (const sink of dying) {
+                        try {
+                            sink.onExit?.();
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                    }
+                    try {
+                        this.deps.onFinished?.(id, wasAttached);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                });
+                try {
+                    candidate.start();
+                }
+                catch (error) {
+                    candidate.removeAllListeners();
+                    try {
+                        candidate.stop({ kill: true });
+                    }
+                    catch {
+                        /* a partially-started terminal is already fail-closed */
+                    }
+                    throw error;
+                }
+                // Publish only after the actual PTY/tmux client started successfully. A failed start must never leave
+                // a broken object that makes attach believe a terminal exists.
+                rec.meta.status = "running";
+                rec.proc = candidate;
+                rec.adoptedLive = false;
+                return candidate;
+            };
+            if (adoptingLive)
+                return startProcess();
+            if (rec.provider === "codex" && intent === "fresh") {
+                const storedIdentity = this.deps.store.get(id)?.providerSessionId;
+                if (rec.providerSessionId !== undefined || storedIdentity !== undefined) {
+                    // A deliberate fresh restart creates a new conversation. Retire the old authoritative id before
+                    // the resolver snapshot/spawn so provisional ownership can never collide with, resume, or expose
+                    // the previous thread. Persist first: a crash after this point remains fail-closed on reopen.
+                    this.deps.store.setProviderSessionId(id, undefined);
+                    rec.providerSessionId = undefined;
+                    rec.meta.providerSessionId = undefined;
+                }
+                rec.identityAmbiguous = false;
+                rec.meta.identityState = "pending";
+            }
+            if (rec.provider === "codex" && intent === "fresh" && this.deps.codexThreadResolver) {
+                let proc;
+                let terminalSpawnAttempted = false;
+                let terminalSpawnError;
+                let preSpawnError;
+                try {
+                    const exactId = await this.deps.codexThreadResolver(rec.meta.cwd).resolveAfterSpawn({
+                        cwd: rec.meta.cwd,
+                        persistence: createCodexThreadPersistence(this.deps.store, id),
+                        spawn: (signal) => {
+                            const started = (async () => {
+                                try {
+                                    await spec.preSpawnCheck?.();
+                                }
+                                catch (error) {
+                                    preSpawnError = error;
+                                    throw error;
+                                }
+                                if (signal.aborted || this.records.get(id) !== rec || rec.subs.size === 0) {
+                                    throw new ProviderError("RESUME_IDENTITY_UNAVAILABLE", "Codex launch was canceled");
+                                }
+                                terminalSpawnAttempted = true;
+                                try {
+                                    proc = startProcess();
+                                }
+                                catch (error) {
+                                    terminalSpawnError = error;
+                                    throw error;
+                                }
+                            })();
+                            return {
+                                started,
+                                cancel: async () => {
+                                    try {
+                                        await started;
+                                    }
+                                    catch {
+                                        return; // no process exists, so cancellation is fully acknowledged
+                                    }
+                                    // A live terminal is deliberately not killed for auxiliary identity failure. An unresolved
+                                    // acknowledgement makes the Task 7 coordinator poison later discovery before releasing.
+                                    await new Promise(() => { });
+                                },
+                            };
+                        },
+                    });
+                    rec.providerSessionId = exactId;
+                    rec.identityAmbiguous = false;
+                    rec.meta.providerSessionId = exactId;
+                    rec.meta.identityState = "exact";
+                    return proc;
+                }
+                catch {
+                    if (terminalSpawnError !== undefined)
+                        throw terminalSpawnError;
+                    if (preSpawnError !== undefined)
+                        throw preSpawnError;
+                    rec.providerSessionId = undefined;
+                    rec.identityAmbiguous = true;
+                    rec.meta.providerSessionId = undefined;
+                    rec.meta.identityState = "ambiguous";
+                    try {
+                        this.deps.store.setProviderSessionId(id, undefined);
+                    }
+                    catch {
+                        /* identity remains fail-closed in memory */
+                    }
+                    if (!proc && !terminalSpawnAttempted && this.records.get(id) === rec && rec.subs.size > 0) {
+                        // Discovery failed before a terminal was actually attempted (including a resolver-owned deadline
+                        // between proof and spawn). Starting now is intentionally untracked, so poison process-wide
+                        // discovery, recheck any selected-profile proof immediately before the fallback process
+                        // construction, then allow this degraded-but-usable terminal to continue.
+                        codexThreadResolutionCoordinator.poisonUnknownSpawnOutcome();
+                        await spec.preSpawnCheck?.();
+                        if (this.records.get(id) !== rec)
+                            return undefined;
+                        if (rec.subs.size > 0) {
+                            terminalSpawnAttempted = true;
+                            proc = startProcess();
+                        }
+                    }
+                    if (!proc) {
+                        rec.meta.status = "ended";
+                        rec.meta.activity = "idle";
+                        this.clearAwaiting(rec);
+                        try {
+                            this.deps.store.setStatus(id, "dormant");
+                        }
+                        catch {
+                            /* in-memory state is still truthfully ended */
+                        }
+                        this.cleanupRecordPaths(rec, provider);
+                    }
+                    return proc;
+                }
+            }
+            await spec.preSpawnCheck?.();
+            if (this.records.get(id) !== rec || rec.subs.size === 0) {
+                this.cleanupRecordPaths(rec, provider);
+                return undefined;
+            }
+            return startProcess();
+        }
+        catch (error) {
+            rec.proc = undefined;
+            rec.meta.status = "ended";
+            rec.meta.activity = "idle";
+            this.clearAwaiting(rec);
+            try {
+                this.deps.store.setStatus(id, "errored");
+            }
+            catch {
+                /* preserve the original provider/terminal error */
+            }
+            this.cleanupProviderPaths(provider, [...buildingCleanupPaths]);
+            buildingCleanupPaths.clear();
+            this.cleanupRecordPaths(rec, provider);
+            throw error;
+        }
+    }
+    cleanupProviderPaths(provider, paths) {
+        if (paths.length === 0)
+            return;
+        try {
+            provider.cleanup(paths);
+        }
+        catch {
+            /* provider cleanup is best-effort and must not break teardown */
+        }
+    }
+    cleanupRecordPaths(rec, provider) {
+        if (rec.cleanupPaths.size === 0)
+            return;
+        const paths = [...rec.cleanupPaths];
+        rec.cleanupPaths.clear();
+        this.cleanupProviderPaths(provider, paths);
+    }
+    applyRuntimeSignal(id, rec, signal) {
+        if (signal.type === "provider-session-id") {
+            if (rec.provider !== "codex")
+                return;
+            // Production exact identity is resolver-owned. OSC ids remain a compatibility signal only when no
+            // resolver was configured (principally isolated adapter/manager tests).
+            if (this.deps.codexThreadResolver)
+                return;
+            if (rec.identityAmbiguous || (rec.providerSessionId && rec.providerSessionId !== signal.id)) {
+                rec.identityAmbiguous = true;
+                rec.providerSessionId = undefined;
+                rec.meta.identityState = "ambiguous";
+                rec.meta.providerSessionId = undefined;
+                this.deps.store.setProviderSessionId(id, undefined);
+                return;
+            }
+            try {
+                this.deps.store.setProviderSessionId(id, signal.id);
+                rec.providerSessionId = signal.id;
+                rec.meta.identityState = "exact";
+                rec.meta.providerSessionId = signal.id;
+            }
+            catch {
+                rec.identityAmbiguous = true;
+                rec.providerSessionId = undefined;
+                rec.meta.identityState = "ambiguous";
+                rec.meta.providerSessionId = undefined;
+                try {
+                    this.deps.store.setProviderSessionId(id, undefined);
+                }
+                catch {
+                    /* already fail-closed in memory */
+                }
+            }
+            return;
+        }
+        const wasBlocked = rec.meta.awaiting;
+        rec.meta.activity = signal.type;
+        rec.meta.awaiting = signal.type === "blocked";
+        if (rec.meta.awaiting && !wasBlocked && rec.subs.size === 0) {
+            try {
+                this.deps.onAwaiting?.(id);
+            }
+            catch {
+                /* a push failure must not break terminal output */
+            }
+        }
+    }
+    write(id, data) {
+        const rec = this.records.get(id);
+        rec?.proc?.write(data);
+        if (rec) {
+            rec.meta.activity = "working";
+            this.clearAwaiting(rec);
+            rec.meta.lastActivityAt = this.deps.now();
+            this.deps.store.touch(id, rec.meta.lastActivityAt);
+        }
+    }
+    resize(id, cols, rows) {
+        const rec = this.records.get(id);
+        if (!rec)
+            return;
+        rec.cols = clampDim(cols, rec.cols);
+        rec.rows = clampDim(rows, rec.rows);
+        rec.proc?.resize(rec.cols, rec.rows);
+    }
+    stop(id) {
+        const rec = this.records.get(id);
+        this.records.delete(id);
+        if (rec?.proc) {
+            const proc = rec.proc;
+            rec.proc = undefined;
+            proc.removeAllListeners();
+            proc.stop({ kill: true });
+        }
+        else
+            this.killTmux(id);
+        if (rec) {
+            this.cleanupRecordPaths(rec, this.providers.get(rec.provider));
+        }
+        this.deps.store.delete(id);
+    }
+    get(id) {
+        return this.records.get(id)?.meta;
+    }
+    list() {
+        return [...this.records.values()].map((r) => r.meta);
+    }
+    /**
+     * After a server/OTA restart: adopt stored terminal sessions whose tmux session is still alive (so they
+     * reappear, resumable), prune store rows whose tmux session is gone, AND kill ORPHAN tmux sessions — live
+     * `rc-*` sessions with no store row (leaked by a crash or an interrupted cleanup) — so they don't pile up.
+     */
+    rehydrate(opts) {
+        const live = new Set(opts.liveTmuxNames);
+        const storedTerminalIds = new Set(this.deps.store
+            .list()
+            .filter((s) => s.mode === "terminal")
+            .map((s) => s.id));
+        for (const s of this.deps.store.list()) {
+            if (s.mode !== "terminal")
+                continue;
+            if (!live.has(tmuxSessionName(s.id))) {
+                this.deps.store.delete(s.id); // tmux session gone → prune the stale row
+                continue;
+            }
+            if (this.records.has(s.id))
+                continue;
+            try {
+                this.providers.get(s.provider);
+            }
+            catch {
+                continue; // retain the durable row and live tmux session; never launch under another provider
+            }
+            let parsedOptions;
+            try {
+                parsedOptions = s.provider === "claude" ? parseLegacyClaudeArgs(s.spawnArgs ?? []) : s.launchOptions;
+            }
+            catch {
+                continue; // isolate malformed historical options to this row; retain it for diagnostics
+            }
+            const options = s.provider === "claude" && parsedOptions.provider === "claude" && s.dangerouslySkip
+                ? { ...parsedOptions, dangerouslySkip: true }
+                : parsedOptions;
+            const common = {
+                meta: {
+                    id: s.id,
+                    provider: s.provider,
+                    cwd: s.cwd,
+                    mode: "terminal",
+                    status: "running",
+                    createdAt: s.createdAt,
+                    lastActivityAt: s.lastActivityAt,
+                    activity: "idle", // the monitor re-derives real activity from the pane on its next ~2.5s sweep
+                    awaiting: false,
+                    // Preserve the persisted RCE-skip flag so a rehydrated session is still badged correctly.
+                    dangerouslySkip: options.provider === "claude"
+                        ? options.dangerouslySkip === true
+                        : options.dangerouslyBypassApprovalsAndSandbox === true,
+                    model: options.model,
+                    effort: options.provider === "claude" ? options.effort : options.reasoningEffort,
+                    ...(options.provider === "claude"
+                        ? { permissionMode: options.permissionMode }
+                        : { sandbox: options.sandbox, approvalPolicy: options.approvalPolicy }),
+                    // The user's rename survives a server restart the same way.
+                    name: s.name,
+                    ...(s.provider === "codex"
+                        ? s.providerSessionId
+                            ? { identityState: "exact", providerSessionId: s.providerSessionId }
+                            : { identityState: "ambiguous" }
+                        : {}),
+                },
+                cols: 80,
+                rows: 24,
+                subs: new Set(),
+                cleanupPaths: new Set(),
+                attachments: [],
+                adoptedLive: true,
+            };
+            if (s.provider === "claude" && options.provider === "claude") {
+                this.records.set(s.id, { ...common, provider: "claude", options });
+            }
+            else if (s.provider === "codex" && options.provider === "codex") {
+                this.records.set(s.id, {
+                    ...common,
+                    provider: "codex",
+                    options,
+                    ...(s.providerSessionId ? { providerSessionId: s.providerSessionId } : {}),
+                    identityAmbiguous: false,
+                });
+            }
+        }
+        // Orphan-reap ONLY with a durable store. In "memory-fallback" (better-sqlite3 didn't load) the store is
+        // EMPTY after a restart, so EVERY live rc-* session looks like an orphan — reaping would then destroy
+        // ALL running terminals on any restart (incl. OTA), e.g. after a native-module ABI break. Leaking a
+        // genuinely-orphaned tmux session is far better than killing every live one, so skip reaping here.
+        if (this.deps.store.mode !== "memory-fallback") {
+            for (const name of opts.liveTmuxNames) {
+                if (!name.startsWith("rc-"))
+                    continue;
+                const id = name.slice(3);
+                if (!storedTerminalIds.has(id))
+                    this.killTmux(id); // orphan → reap
+            }
+        }
+    }
+    /** Kill a tmux session for an id without needing a live proc (reuses TerminalProcess's socketed kill). */
+    killTmux(id) {
+        new TerminalProcess({
+            sessionId: id,
+            cwd: "/",
+            executable: "/usr/bin/true",
+            ...(this.deps.runTmux ? { runTmux: this.deps.runTmux } : {}),
+            ...(this.deps.tmuxSocket ? { tmuxSocket: this.deps.tmuxSocket } : {}),
+        }).stop({ kill: true });
+    }
+}