@svenroth-ai/shipwright 0.24.1-next.0

package/server/dist/terminal/snapshot-store.js

@@ -0,0 +1,439 @@
+/*
+ * snapshot-store.ts — Iterate A (ADR-088)
+ *
+ * Disk persistence for headless-mirror cell-state snapshots. Per-task
+ * `<scrollbackDir>/<taskId>.snapshot` (same directory as scrollback-store,
+ * separate extension so existing `.log` / `.log.1` artifacts are
+ * undisturbed). Atomic write via temp file + rename.
+ *
+ * File format (UTF-8 plain text):
+ *
+ *     # shipwright-snapshot v2 xterm@<terminalVersion> <cols>x<rows>\n
+ *     <serializedPayload>
+ *
+ * Example header:
+ *
+ *     # shipwright-snapshot v2 xterm@6.0.0 120x30
+ *
+ * Header semantics (external review OpenAI #8 — disambiguation):
+ *   `<cols>x<rows>` is the FINAL terminal size at the moment the
+ *   snapshot was written (i.e. the pty's last-known dimensions before
+ *   pty.kill / pty.onExit). It is NOT initial size, and resize history
+ *   is NOT preserved. Iterate A is write-only; the consumer in Iterate
+ *   B uses these dims to construct a replay-time Terminal of matching
+ *   shape so the serialize→write idempotence (M2) holds.
+ *
+ * Version semantics:
+ *   - `v2` is the current envelope version. Bumped from `v1` in Iterate
+ *     I (ADR-097) when @xterm/headless was upgraded 5.5.0 → 6.0.0. The
+ *     loader rejects v1 with `unknown_version` — pre-upgrade tasks
+ *     surface as "no replay envelope, blank terminal with live shell"
+ *     (per ADR-087 trade-off). Bump on incompatible header changes
+ *     (e.g. adding a hash field, JSON envelope, or any future xterm
+ *     major where the addon-serialize byte-stream is not guaranteed
+ *     parser-compatible across versions).
+ *   - `xterm@<version>` is the @xterm/headless / @xterm/addon-serialize
+ *     PINNED version that produced the payload (architecture
+ *     invariant #4 in the plan-of-record, amended in ADR-097). On read,
+ *     the caller MAY reject snapshots whose terminalVersion does not
+ *     match the currently-pinned version — Iterate A only embeds it;
+ *     Iterate B wires the strict-match policy at the replay path.
+ *
+ * Path-safety: reuses the same UUID + realpath patterns as
+ * scrollback-store.ts. UUID format is validated on every public method;
+ * realpath is verified at op-time (defeats mid-runtime symlink swap).
+ * File mode 0o600 / dir mode 0o700 on POSIX (Windows ignores POSIX
+ * modes — same caveat as scrollback-store privacy disclosure).
+ *
+ * Read more: .shipwright/planning/embedded-terminal-refactor-headless.md
+ * § "Iterate A — Headless mirror behind feature flag".
+ */
+import * as fsAsync from "node:fs/promises";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+import PQueue from "p-queue";
+import { clearTaskSnapshotTmp } from "./snapshot-tmp-sweep.js";
+// Pinned terminal-emulator version that produced the snapshot payload.
+// Sourced from @xterm/headless's package.json at module load. We do NOT
+// hardcode because the plan invariant pins via npm dependency (exact
+// version, no caret) — so the package.json is the source of truth.
+//
+// Surfaced separately via getTerminalVersion() so the snapshot writer
+// always embeds the same string the runtime is using.
+let cachedTerminalVersion = null;
+async function readTerminalVersion() {
+    if (cachedTerminalVersion !== null)
+        return cachedTerminalVersion;
+    // Resolve via fileURLToPath so Windows paths come out as
+    // `C:\path\to\file` instead of `/C:/path/to/file` (which path.resolve
+    // mangles when joined with `..` segments).
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        // Dev/test layout — server/src/terminal/snapshot-store.ts
+        path.resolve(here, "../../node_modules/@xterm/headless/package.json"),
+        // Production build layout — server/dist/terminal/snapshot-store.js
+        path.resolve(here, "../node_modules/@xterm/headless/package.json"),
+        // Repo-root fallback (`server/` is a workspace child)
+        path.resolve(here, "../../../node_modules/@xterm/headless/package.json"),
+    ];
+    for (const cand of candidates) {
+        try {
+            const raw = await fsAsync.readFile(cand, "utf8");
+            const json = JSON.parse(raw);
+            if (typeof json.version === "string" && json.version.length > 0) {
+                cachedTerminalVersion = json.version;
+                return cachedTerminalVersion;
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    // Last-resort sentinel — should never fire in normal install.
+    cachedTerminalVersion = "unknown";
+    return cachedTerminalVersion;
+}
+/** Test-only: reset the version cache so tests can stub a fresh read. */
+export function _resetTerminalVersionCacheForTesting() {
+    cachedTerminalVersion = null;
+}
+const UUID_PATTERN = /^[0-9a-fA-F-]{36}$/;
+// ADR-097: bumped from v1 to v2 when @xterm/headless was upgraded
+// 5.5.0 → 6.0.0. Loader rejects v1 (and any other unknown version)
+// with `unknown_version`; the caller (replay-snapshot.ts) treats that
+// the same as ENOENT — no replay envelope is emitted, the client
+// gets a blank terminal with live shell. See ADR-097 § Snapshot
+// envelope bump rationale.
+const SUPPORTED_VERSIONS = new Set(["v2"]);
+export class SnapshotStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SnapshotStoreError";
+    }
+}
+/**
+ * Per-task snapshot persistence.
+ *
+ * Lifecycle:
+ *   - new SnapshotStore(dir)        — server bootstrap
+ *   - await store.init()            — ensure dir + cache realpath
+ *   - await store.write(taskId, …)  — pty.kill path
+ *   - await store.read(taskId)      — replay path (Iterate B)
+ *   - await store.has(taskId)       — diagnostic (Iterate A wires this)
+ *   - await store.clear(taskId)     — task delete cascade
+ */
+export class SnapshotStore {
+    dir;
+    fileMode;
+    dirMode;
+    renameMaxAttempts;
+    renameFn;
+    resolvedDir = null;
+    /**
+     * Iterate B (MEDIUM-1) — per-task PQueue (concurrency=1) serializes all
+     * WRITE operations for the same taskId. Two simultaneous `write()`s (fast
+     * kill→respawn cycles, test loops, restart races) would otherwise collide
+     * on the tmp path `<taskId>.snapshot.tmp-<pid>-<ms>-<rand>` — one writer's
+     * writeFile clobbering the other's tmp before its rename lands. Mirrors
+     * scrollback-store's per-task queue. Read/has stay unqueued (they touch
+     * only the FINAL `.snapshot`; rename is atomic vs concurrent readers).
+     * clear() drains this queue (onIdle) BEFORE unlinking the final AND before
+     * sweeping tmp strays (D19/F26), so no live rename can race the wipe. The
+     * crypto.randomBytes(4) tmp suffix is a belt-AND-braces second defense.
+     */
+    writeQueues = new Map();
+    constructor(dir, opts = {}) {
+        this.dir = dir;
+        this.fileMode = opts.fileMode ?? 0o600;
+        this.dirMode = opts.dirMode ?? 0o700;
+        this.renameMaxAttempts = opts.renameMaxAttempts ?? 3;
+        this.renameFn = opts.renameFn ?? ((from, to) => fsAsync.rename(from, to));
+    }
+    /** Idempotent — creates dir + caches resolved path. */
+    async init() {
+        await this.ensureDirResolved();
+    }
+    /**
+     * Write a snapshot atomically (temp file + fs.rename). Existing
+     * snapshot for the same task is overwritten. Caller MUST pass cols/rows
+     * matching the headless-mirror's current dimensions; we embed them in
+     * the header verbatim.
+     *
+     * Iterate B (close MEDIUM-1, MEDIUM-2 from A's code review):
+     *   - Per-task PQueue serializes concurrent writes for the same taskId.
+     *   - Tmp filename includes a 4-byte crypto random suffix so even if a
+     *     future iterate routes writes around the queue, same-millisecond
+     *     collisions remain impossible.
+     *   - fs.rename retries on EBUSY/EPERM (Windows AV scanner transients)
+     *     with 50→100→200 ms backoff. Matches scrollback-store.safeRename
+     *     budget so durability characteristics are identical at both
+     *     write surfaces.
+     */
+    async write(taskId, payload) {
+        this.validateTaskId(taskId);
+        const queue = this.getOrCreateWriteQueue(taskId);
+        await queue.add(() => this.writeLocked(taskId, payload));
+    }
+    async writeLocked(taskId, payload) {
+        const dir = await this.ensureDirResolved();
+        const final = await this.resolveTargetPath(taskId);
+        // crypto.randomBytes(4) yields 8 hex chars → 4 294 967 296 keyspace
+        // per pid+ms combination. Combined with pid + ms this is collision-
+        // free in practice.
+        const rand = randomBytes(4).toString("hex");
+        const tmp = path.join(dir, `${taskId}.snapshot.tmp-${process.pid}-${Date.now()}-${rand}`);
+        const terminalVersion = await readTerminalVersion();
+        const header = `# shipwright-snapshot v2 xterm@${terminalVersion} ${payload.cols}x${payload.rows}\n`;
+        const body = header + payload.data;
+        await fsAsync.writeFile(tmp, body, { encoding: "utf8", mode: this.fileMode });
+        try {
+            await this.safeRename(tmp, final);
+        }
+        catch (err) {
+            // Clean up the tmp file if rename failed terminally (e.g. EACCES
+            // — non-retryable, or EBUSY budget exhausted).
+            try {
+                await fsAsync.unlink(tmp);
+            }
+            catch {
+                /* best-effort */
+            }
+            throw err;
+        }
+    }
+    /**
+     * Retry-on-EBUSY wrapper for fs.rename. Mirrors scrollback-store's
+     * safeRename — Windows AV scanners + recent-write windows produce
+     * transient EBUSY/EPERM that resolve within ~100 ms. Three attempts
+     * with 50→100→200 ms backoff (no jitter; predictable for tests).
+     */
+    async safeRename(from, to) {
+        let lastErr = null;
+        for (let attempt = 0; attempt < this.renameMaxAttempts; attempt++) {
+            try {
+                await this.renameFn(from, to);
+                return;
+            }
+            catch (err) {
+                lastErr = err;
+                const code = lastErr.code;
+                if (code !== "EBUSY" && code !== "EPERM")
+                    throw err;
+                // Exponential-ish backoff: 50, 100, 200 ms. The last attempt
+                // does NOT wait — there is no further attempt after it.
+                if (attempt < this.renameMaxAttempts - 1) {
+                    const delay = 50 * Math.pow(2, attempt);
+                    await new Promise((r) => setTimeout(r, delay));
+                }
+            }
+        }
+        if (lastErr)
+            throw lastErr;
+    }
+    getOrCreateWriteQueue(taskId) {
+        let q = this.writeQueues.get(taskId);
+        if (!q) {
+            q = new PQueue({ concurrency: 1 });
+            this.writeQueues.set(taskId, q);
+        }
+        return q;
+    }
+    /**
+     * Read + parse the snapshot. Returns null if absent (ENOENT).
+     * Throws SnapshotStoreError on malformed header / unknown version.
+     */
+    async read(taskId) {
+        this.validateTaskId(taskId);
+        const target = await this.resolveTargetPath(taskId);
+        let raw;
+        try {
+            raw = await fsAsync.readFile(target, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        return parseSnapshotEnvelope(raw);
+    }
+    /** Existence probe — does not read or parse. */
+    async has(taskId) {
+        this.validateTaskId(taskId);
+        const target = await this.resolveTargetPath(taskId);
+        try {
+            await fsAsync.stat(target);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return false;
+            throw err;
+        }
+    }
+    /**
+     * Best-effort variant — used by task-delete cascade (Iterate C
+     * MEDIUM-B1 fix). Silently no-ops on malformed taskId; logs warn on
+     * any clear failure but does not throw. Mirrors scrollback-store's
+     * `clearBestEffort` contract.
+     */
+    async clearBestEffort(taskId) {
+        if (!UUID_PATTERN.test(taskId))
+            return;
+        try {
+            await this.clear(taskId);
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[snapshot] clearBestEffort failed for ${taskId}: ${err.message}`);
+        }
+    }
+    /**
+     * Delete the snapshot file + any orphaned `<taskId>.snapshot.tmp-*` strays.
+     * Idempotent. D01/F05 — fence the write queue (await onIdle) BEFORE unlink so
+     * a flush can't re-create it. D19/F26 — the tmp sweep runs AFTER the fence
+     * (no live rename can race it) and REGARDLESS of the final's presence (an
+     * interrupted write leaves a tmp with no `.snapshot`).
+     */
+    async clear(taskId) {
+        this.validateTaskId(taskId);
+        // Fence first: drain any queued/in-flight write, then drop the queue
+        // ref (bounds the Map). The unlinks below then wipe it for good.
+        const q = this.writeQueues.get(taskId);
+        if (q) {
+            try {
+                await q.onIdle();
+            }
+            catch {
+                /* best-effort */
+            }
+            this.writeQueues.delete(taskId);
+        }
+        const dir = await this.ensureDirResolved();
+        const target = await this.resolveTargetPath(taskId);
+        try {
+            await fsAsync.unlink(target);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        await clearTaskSnapshotTmp({ dir, taskId });
+    }
+    /**
+     * Iterate B — drop the per-task write queue when the caller is
+     * confident no further writes will arrive (typical: pty-manager.cleanup
+     * after the final finalizeMirrorSnapshot has resolved). Idempotent.
+     * The queue's onIdle() is awaited before deletion so any pending
+     * work completes; subsequent writes for the same task would create
+     * a fresh queue.
+     */
+    async releaseQueue(taskId) {
+        if (!UUID_PATTERN.test(taskId))
+            return;
+        const q = this.writeQueues.get(taskId);
+        if (!q)
+            return;
+        try {
+            await q.onIdle();
+        }
+        catch {
+            /* best-effort */
+        }
+        this.writeQueues.delete(taskId);
+    }
+    // --- internals ----------------------------------------------------------
+    validateTaskId(taskId) {
+        if (!UUID_PATTERN.test(taskId)) {
+            throw new SnapshotStoreError("invalid_task_id", `taskId does not match UUID pattern: ${taskId}`);
+        }
+    }
+    /**
+     * Realpath-at-op-time guard. Mirrors scrollback-store.resolveTaskFile.
+     * If the resolved target is outside the snapshot dir, throw.
+     * ENOENT is OK (target doesn't exist yet — write will create it).
+     */
+    async resolveTargetPath(taskId) {
+        const dir = await this.ensureDirResolved();
+        const candidate = path.join(dir, `${taskId}.snapshot`);
+        let real;
+        try {
+            real = await fsAsync.realpath(candidate);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return candidate;
+            throw err;
+        }
+        const rel = path.relative(dir, real);
+        if (rel.startsWith("..") || path.isAbsolute(rel)) {
+            throw new SnapshotStoreError("snapshot_path_outside_dir", `realpath escape for ${taskId}: ${real}`);
+        }
+        return real;
+    }
+    async ensureDirResolved() {
+        if (this.resolvedDir)
+            return this.resolvedDir;
+        await fsAsync.mkdir(this.dir, { recursive: true, mode: this.dirMode });
+        this.resolvedDir = await fsAsync.realpath(this.dir);
+        return this.resolvedDir;
+    }
+}
+/**
+ * Parse a snapshot envelope. Exported for unit tests.
+ *
+ * Accepts:
+ *   `# shipwright-snapshot <version> xterm@<terminalVersion> <cols>x<rows>\n<data>`
+ *
+ * Rejects unknown versions, missing fields, non-integer dims. Trailing
+ * data after the first `\n` is the payload (preserved verbatim including
+ * its own newlines).
+ */
+export function parseSnapshotEnvelope(raw) {
+    const newlineIdx = raw.indexOf("\n");
+    if (newlineIdx < 0) {
+        throw new SnapshotStoreError("malformed_header", "snapshot envelope has no newline after header");
+    }
+    // External review OpenAI #12 — bound header size. A real header is
+    // ~50 bytes; anything past 512 is malformed or hostile.
+    if (newlineIdx > 512) {
+        throw new SnapshotStoreError("malformed_header", `snapshot header exceeds 512 bytes (got ${newlineIdx})`);
+    }
+    const headerLine = raw.slice(0, newlineIdx);
+    const data = raw.slice(newlineIdx + 1);
+    // Header shape: `# shipwright-snapshot <version> xterm@<ver> <cols>x<rows>`
+    // Bounded sub-patterns (per ReDoS-resistance discipline from
+    // scrollback-store.ts):
+    //   - version: `v\d{1,3}` (v0..v999)
+    //   - terminalVersion: up to 64 non-whitespace chars
+    //   - dims: up to 5-digit cols + rows (caps match HeadlessMirror's
+    //     MAX_COLS=1000, MAX_ROWS=500, both 4-digit; 5 digits absorbs
+    //     future bumps).
+    const re = /^# shipwright-snapshot (v\d{1,3}) xterm@(\S{1,64}) (\d{1,5})x(\d{1,5})$/;
+    const m = re.exec(headerLine);
+    if (!m) {
+        throw new SnapshotStoreError("malformed_header", `snapshot header does not match expected shape: ${headerLine}`);
+    }
+    const version = m[1];
+    if (!SUPPORTED_VERSIONS.has(version)) {
+        throw new SnapshotStoreError("unknown_version", `Unknown snapshot version: ${version}`);
+    }
+    const cols = parseInt(m[3], 10);
+    const rows = parseInt(m[4], 10);
+    // External code review MEDIUM: reject 0x0 and out-of-band dims so
+    // downstream consumers (Iterate B replay path) can trust the values
+    // without re-validating. Caps match HeadlessMirror.MAX_COLS/MAX_ROWS.
+    if (cols <= 0 || rows <= 0 || cols > 1000 || rows > 500) {
+        throw new SnapshotStoreError("malformed_header", `snapshot dims out of range: ${cols}x${rows} (allowed 1..1000 cols, 1..500 rows)`);
+    }
+    return {
+        version: version,
+        terminalVersion: m[2],
+        cols,
+        rows,
+        data,
+    };
+}
+//# sourceMappingURL=snapshot-store.js.map

package/server/dist/terminal/snapshot-store.js.map

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

package/server/dist/terminal/snapshot-tmp-sweep.d.ts

@@ -0,0 +1,48 @@
+/** Default reclamation age for the periodic sweep (1h). */
+export declare const DEFAULT_TMP_MAX_AGE_MS: number;
+export interface SnapshotTmpSweepDeps {
+    readdir: (dir: string) => Promise<string[]>;
+    stat: (p: string) => Promise<{
+        mtimeMs: number;
+    }>;
+    unlink: (p: string) => Promise<void>;
+}
+export interface SnapshotTmpSweepOpts {
+    dir: string;
+    /** Reclaim tmp files whose mtime is older than this. Default 1h. */
+    maxAgeMs?: number;
+    deps?: Partial<SnapshotTmpSweepDeps>;
+    /** Injected for tests. Defaults to Date.now. */
+    now?: () => number;
+    logWarn?: (msg: string) => void;
+    logInfo?: (msg: string) => void;
+}
+export interface SnapshotTmpSweepResult {
+    /** tmp files unlinked. */
+    deleted: number;
+    /** stat/unlink failures (kept going). */
+    errors: number;
+    /** tmp files younger than the cutoff, left in place. */
+    preserved: number;
+}
+/**
+ * Age-gated sweep of orphaned `<taskId>.snapshot.tmp-*` staging files.
+ * Best-effort: dir-read failure and per-file failures are non-fatal (they
+ * log a warn and never throw). Wire into the boot + 24h periodic sweep in
+ * index.ts alongside the scrollback sweep.
+ */
+export declare function sweepOrphanSnapshotTmp(opts: SnapshotTmpSweepOpts): Promise<SnapshotTmpSweepResult>;
+/**
+ * Immediately unlink every `<taskId>.snapshot.tmp-*` staging stray for one
+ * task — NO age gate. Called from the DELETE cascade so a removed task
+ * leaves no snapshot artifacts behind (delete = privacy boundary; the tmp
+ * may hold secrets). Best-effort; per-file failures log a warn. Returns the
+ * count removed. Silently no-ops on a malformed taskId.
+ */
+export declare function clearTaskSnapshotTmp(opts: {
+    dir: string;
+    taskId: string;
+    deps?: Partial<Pick<SnapshotTmpSweepDeps, "readdir" | "unlink">>;
+    logWarn?: (msg: string) => void;
+}): Promise<number>;
+//# sourceMappingURL=snapshot-tmp-sweep.d.ts.map

package/server/dist/terminal/snapshot-tmp-sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-tmp-sweep.d.ts","sourceRoot":"","sources":["../../src/terminal/snapshot-tmp-sweep.ts"],"names":[],"mappings":"AAqCA,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,QAAiB,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACrC,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAQD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,sBAAsB,CAAC,CAwDjC;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC;IACjE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC,GAAG,OAAO,CAAC,MAAM,CAAC,CAiClB"}

package/server/dist/terminal/snapshot-tmp-sweep.js

@@ -0,0 +1,141 @@
+/*
+ * snapshot-tmp-sweep.ts — D19 (F26), 2026-07-10.
+ *
+ * Reclamation of orphaned `<taskId>.snapshot.tmp-*` staging files.
+ *
+ * SnapshotStore.write() (snapshot-store.ts) stages a snapshot to
+ * `<taskId>.snapshot.tmp-<pid>-<ms>-<rand>` then atomically renames it to
+ * `<taskId>.snapshot`. If the process exits between writeFile(tmp) and the
+ * rename — graceful shutdown fires a fire-and-forget finalize then
+ * process.exit WITHOUT awaiting snapshot writes (index.ts shutdown path),
+ * or the Windows EBUSY rename budget exhausts — the tmp staging file is
+ * stranded with FULL terminal cell-state (possibly secrets), and NO
+ * existing cleanup surface matches it:
+ *   - the DELETE cascade unlinks the exact `<taskId>.snapshot` path;
+ *   - scrollback-store.sweepExpired matches `<taskId>.log(.N)?`;
+ *   - the iterate-C boot wipe (boot-wipe.ts) matches `.log*`.
+ * So an orphaned tmp leaks to disk indefinitely. These two helpers close
+ * the gap and are wired into the boot + 24h periodic sweep in index.ts
+ * (sweepOrphanSnapshotTmp) and the task-delete cascade (clearTaskSnapshotTmp).
+ *
+ * Age-gating (default 1h) is the correctness guard for the periodic sweep:
+ * a live write renames its tmp within milliseconds, so any tmp older than
+ * the cutoff is provably orphaned — no active-task veto needed. Live
+ * `.snapshot` / `.log` files never match the tmp pattern and are always
+ * preserved.
+ *
+ * Both functions are pure over an injectable fs deps object (mirrors
+ * boot-wipe.ts) so unit tests can drive them without touching disk;
+ * production wires `node:fs/promises`.
+ */
+import * as fsAsync from "node:fs/promises";
+import * as path from "node:path";
+/** Matches `<uuid>.snapshot.tmp-...` staging files. Bounded — ReDoS-safe. */
+const SNAPSHOT_TMP_RE = /^[0-9a-fA-F-]{36}\.snapshot\.tmp-/;
+const UUID_RE = /^[0-9a-fA-F-]{36}$/;
+/** Default reclamation age for the periodic sweep (1h). */
+export const DEFAULT_TMP_MAX_AGE_MS = 60 * 60 * 1000;
+const defaultDeps = {
+    readdir: (dir) => fsAsync.readdir(dir),
+    stat: (p) => fsAsync.stat(p),
+    unlink: (p) => fsAsync.unlink(p),
+};
+/**
+ * Age-gated sweep of orphaned `<taskId>.snapshot.tmp-*` staging files.
+ * Best-effort: dir-read failure and per-file failures are non-fatal (they
+ * log a warn and never throw). Wire into the boot + 24h periodic sweep in
+ * index.ts alongside the scrollback sweep.
+ */
+export async function sweepOrphanSnapshotTmp(opts) {
+    const deps = { ...defaultDeps, ...opts.deps };
+    const now = opts.now ?? Date.now;
+    const logWarn = opts.logWarn ?? ((m) => console.warn(m));
+    const logInfo = opts.logInfo ?? ((m) => console.log(m));
+    const cutoff = now() - (opts.maxAgeMs ?? DEFAULT_TMP_MAX_AGE_MS);
+    const result = { deleted: 0, errors: 0, preserved: 0 };
+    let entries;
+    try {
+        entries = await deps.readdir(opts.dir);
+    }
+    catch (err) {
+        // ENOENT = dir not created yet (benign, pre-first-pty) → silent no-op.
+        // Any other error (EACCES/EPERM/EIO) is a REAL operational failure that
+        // leaves orphan tmp files (possibly secrets) on disk — surface it so the
+        // privacy-cleanup gap stays visible (the call-site `.catch` is only a
+        // last-resort guard; this function never throws).
+        if (err.code !== "ENOENT") {
+            logWarn(`[snapshot-tmp] sweep readdir failed (${err.message}); orphan tmp files may persist`);
+        }
+        return result;
+    }
+    for (const name of entries) {
+        if (!SNAPSHOT_TMP_RE.test(name))
+            continue;
+        const full = path.join(opts.dir, name);
+        let mtimeMs;
+        try {
+            mtimeMs = (await deps.stat(full)).mtimeMs;
+        }
+        catch {
+            result.errors++;
+            continue;
+        }
+        if (mtimeMs >= cutoff) {
+            result.preserved++;
+            continue;
+        }
+        try {
+            await deps.unlink(full);
+            result.deleted++;
+        }
+        catch (err) {
+            result.errors++;
+            logWarn(`[snapshot-tmp] unlink failed for ${name}: ${err.message}`);
+        }
+    }
+    if (result.deleted > 0 || result.errors > 0) {
+        logInfo(`[snapshot-tmp] orphan sweep: deleted=${result.deleted} errors=${result.errors} preserved=${result.preserved}`);
+    }
+    return result;
+}
+/**
+ * Immediately unlink every `<taskId>.snapshot.tmp-*` staging stray for one
+ * task — NO age gate. Called from the DELETE cascade so a removed task
+ * leaves no snapshot artifacts behind (delete = privacy boundary; the tmp
+ * may hold secrets). Best-effort; per-file failures log a warn. Returns the
+ * count removed. Silently no-ops on a malformed taskId.
+ */
+export async function clearTaskSnapshotTmp(opts) {
+    if (!UUID_RE.test(opts.taskId))
+        return 0;
+    const readdir = opts.deps?.readdir ?? ((d) => fsAsync.readdir(d));
+    const unlink = opts.deps?.unlink ?? ((p) => fsAsync.unlink(p));
+    const logWarn = opts.logWarn ?? ((m) => console.warn(m));
+    const prefix = `${opts.taskId}.snapshot.tmp-`;
+    let entries;
+    try {
+        entries = await readdir(opts.dir);
+    }
+    catch (err) {
+        // ENOENT (dir absent) is benign; any other error is a real failure that
+        // may leave this task's tmp strays behind — log it, stay best-effort.
+        if (err.code !== "ENOENT") {
+            logWarn(`[snapshot-tmp] clear readdir failed for ${opts.taskId} (${err.message})`);
+        }
+        return 0;
+    }
+    let deleted = 0;
+    for (const name of entries) {
+        if (!name.startsWith(prefix))
+            continue;
+        try {
+            await unlink(path.join(opts.dir, name));
+            deleted++;
+        }
+        catch (err) {
+            logWarn(`[snapshot-tmp] clear failed for ${name}: ${err.message}`);
+        }
+    }
+    return deleted;
+}
+//# sourceMappingURL=snapshot-tmp-sweep.js.map

package/server/dist/terminal/snapshot-tmp-sweep.js.map

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