@svenroth-ai/shipwright 0.24.1-next.0

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

@@ -0,0 +1,116 @@
+/*
+ * snapshot-preserve.ts — ADR-096 preservation gate, extracted 2026-07-12
+ * (iterate-2026-07-12-mirror-flush-preserve-gate).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The headless-mirror cell-state is persisted from TWO surfaces in
+ * pty-manager.ts:
+ *   - finalizeMirrorSnapshot  (kill / pty.onExit path)
+ *   - flushMirrorSnapshot     (last-WS-detach keep-alive path, ADR-092)
+ *
+ * Before this module, ONLY finalize carried the ADR-096 preservation
+ * heuristic; flush wrote UNCONDITIONALLY. That asymmetry lost terminal
+ * history on the 2nd detach→reopen cycle: a live pty whose Claude TUI had
+ * left the alt-screen (DECRST 1049 → near-empty main buffer) serialised to
+ * a thin mirror, and the last-detach flush clobbered the richer disk
+ * snapshot that a prior detach (or finalize) had written. Next reopen →
+ * blank scrollback.
+ *
+ * The fix lifts the gate into this shared helper so BOTH write surfaces
+ * apply it identically.
+ *
+ * THE HEURISTIC (unchanged from finalize's original inline gate)
+ * --------------------------------------------------------------
+ * Before writing, compare the about-to-write payload's byte length against
+ * any existing on-disk snapshot. If the new one is substantially smaller
+ * (< SNAPSHOT_PRESERVE_THRESHOLD of existing), preserve the existing
+ * snapshot and skip the write. Rationale: a Claude TUI shutdown / alt-screen
+ * exit yields an almost-empty cell-state; the previously-persisted richer
+ * state is the correct replay artifact.
+ *
+ * Edge cases (identical to the original finalize gate):
+ *   - No existing snapshot (`read` returns null) → write the new one
+ *     (first writer wins; the comparison never fires because existingLen=0).
+ *   - `read` throws (malformed header, IO error) → log + write the new one
+ *     (best-effort fallback; do not lose data on a stat/parse error).
+ *   - New payload empty + existing has content → preserve existing
+ *     (subsumed by the threshold rule; 0 < existing * threshold).
+ *
+ * KNOWN, ACCEPTED LIMITATION (pre-existing, shared with the old finalize
+ * gate): read-then-write is NOT atomic. A concurrent writer between the
+ * read and the write could interleave. This is the SAME non-atomicity the
+ * inline finalize gate already had; per-task write serialisation lives one
+ * layer down in SnapshotStore's PQueue. Adding cross-read+write locking is
+ * explicitly OUT of scope for the extraction (see ADR).
+ *
+ * RESURRECTION GUARD (iterate-2026-07-12, doubt-review HIGH): the
+ * `await store.read` below YIELDS the event loop. SnapshotStore.write()
+ * enqueues SYNCHRONOUSLY (validateTaskId -> getOrCreateWriteQueue ->
+ * queue.add all run before its first await), so pre-extraction the caller's
+ * `if (entry.tornDown) return;` guard sat DIRECTLY before the synchronous
+ * write with no yield between them — a concurrent delete cascade's clear()
+ * fence always serialised AFTER the write. Introducing the unqueued
+ * `store.read` reopened that gap: a delete (kill sets tornDown + releaseQueue,
+ * then clear() unlinks the `.snapshot`) can land while we park at read, and
+ * the post-read write would RE-CREATE the just-wiped, secret-bearing file
+ * (privacy resurrection). The optional `shouldProceed` predicate restores the
+ * pre-extraction guarantee: it is re-checked SYNCHRONOUSLY immediately before
+ * the write enqueue (no await between), so a caller passing
+ * `() => !entry.tornDown` aborts the write exactly when the old guard would
+ * have. The kill/finalize path OMITS the predicate (its write MUST land — it
+ * is the authoritative exit snapshot, fenced by kill-awaits-finalize-before-
+ * clear).
+ */
+/** ADR-096 threshold. A new payload below this fraction of an existing
+ *  on-disk payload is treated as a TUI alt-screen-exit clear and the write
+ *  is skipped to preserve the richer snapshot. Heuristic — do NOT tune
+ *  without re-verifying the DECRST-1049 scenario. */
+export const SNAPSHOT_PRESERVE_THRESHOLD = 0.6;
+/**
+ * Write `payload` for `taskId` via `store`, UNLESS an existing on-disk
+ * snapshot is substantially larger — in which case preserve the existing
+ * one and skip the write (ADR-096).
+ *
+ * Best-effort on read: a read failure logs and falls through to write, so a
+ * malformed/unreadable existing snapshot never blocks persistence.
+ *
+ * Never throws for the gate logic itself; a `write` rejection propagates to
+ * the caller (both call sites already wrap this in try/catch).
+ */
+export async function writeSnapshotPreservingLarger(store, taskId, payload, opts = {}) {
+    const warn = opts.log ??
+        ((msg) => {
+            // eslint-disable-next-line no-console
+            console.warn(msg);
+        });
+    const caller = opts.caller ?? "writeSnapshotPreservingLarger";
+    let existingDataLen = 0;
+    try {
+        const existing = await store.read(taskId);
+        if (existing)
+            existingDataLen = existing.data.length;
+    }
+    catch (readErr) {
+        warn(`[snapshot-preserve] ${caller}: existing snapshot read failed for ${taskId} (${readErr.message}) — proceeding with write`);
+        // existingDataLen stays 0 → the comparison below cannot fire, the new
+        // snapshot is written (best-effort: never lose data on a read error).
+    }
+    const newDataLen = payload.data.length;
+    if (existingDataLen > 0 && newDataLen < existingDataLen * SNAPSHOT_PRESERVE_THRESHOLD) {
+        warn(`[snapshot-preserve] ${caller}: preserving richer on-disk snapshot for ${taskId} (new=${newDataLen}B, existing=${existingDataLen}B — likely Claude TUI exit clear, ADR-096)`);
+        return { skipped: true };
+    }
+    // Resurrection guard — re-check liveness SYNCHRONOUSLY here, immediately
+    // before the write enqueue. `store.write` enqueues synchronously, so there
+    // is NO await between this check and the enqueue: a delete cascade that
+    // completed while we parked at `store.read` above cannot be re-raced by
+    // this write. Abort rather than re-create a just-wiped snapshot.
+    if (opts.shouldProceed && !opts.shouldProceed()) {
+        warn(`[snapshot-preserve] ${caller}: aborting write for ${taskId} — liveness lost after read (concurrent delete/teardown); not resurrecting the snapshot`);
+        return { skipped: true, aborted: true };
+    }
+    await store.write(taskId, payload);
+    return { skipped: false };
+}
+//# sourceMappingURL=snapshot-preserve.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-preserve.js","sourceRoot":"","sources":["../../src/terminal/snapshot-preserve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH;;;qDAGqD;AACrD,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AA2C/C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,KAAwB,EACxB,MAAc,EACd,OAAqD,EACrD,OAA0C,EAAE;IAE5C,MAAM,IAAI,GACR,IAAI,CAAC,GAAG;QACR,CAAC,CAAC,GAAW,EAAE,EAAE;YACf,sCAAsC;YACtC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;IACL,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,+BAA+B,CAAC;IAE9D,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,QAAQ;YAAE,eAAe,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;IACvD,CAAC;IAAC,OAAO,OAAO,EAAE,CAAC;QACjB,IAAI,CACF,uBAAuB,MAAM,uCAAuC,MAAM,KAAM,OAAiB,CAAC,OAAO,2BAA2B,CACrI,CAAC;QACF,sEAAsE;QACtE,sEAAsE;IACxE,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;IACvC,IAAI,eAAe,GAAG,CAAC,IAAI,UAAU,GAAG,eAAe,GAAG,2BAA2B,EAAE,CAAC;QACtF,IAAI,CACF,uBAAuB,MAAM,4CAA4C,MAAM,SAAS,UAAU,eAAe,eAAe,4CAA4C,CAC7K,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,yEAAyE;IACzE,2EAA2E;IAC3E,wEAAwE;IACxE,wEAAwE;IACxE,iEAAiE;IACjE,IAAI,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;QAChD,IAAI,CACF,uBAAuB,MAAM,wBAAwB,MAAM,yFAAyF,CACrJ,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC"}

package/server/dist/terminal/snapshot-store.d.ts

@@ -0,0 +1,147 @@
+/** Test-only: reset the version cache so tests can stub a fresh read. */
+export declare function _resetTerminalVersionCacheForTesting(): void;
+export declare class SnapshotStoreError extends Error {
+    readonly code: "invalid_task_id" | "snapshot_path_outside_dir" | "unknown_version" | "malformed_header";
+    constructor(code: "invalid_task_id" | "snapshot_path_outside_dir" | "unknown_version" | "malformed_header", message: string);
+}
+export interface SnapshotHeader {
+    version: "v2";
+    terminalVersion: string;
+    cols: number;
+    rows: number;
+}
+export interface SnapshotRecord extends SnapshotHeader {
+    data: string;
+}
+export type SnapshotRenameFn = (from: string, to: string) => Promise<void>;
+export interface SnapshotStoreOpts {
+    /** POSIX file mode for `<taskId>.snapshot`. Ignored on Windows. */
+    fileMode?: number;
+    /** POSIX dir mode for the snapshot directory. Ignored on Windows. */
+    dirMode?: number;
+    /**
+     * Iterate B — Windows EBUSY/EPERM retry budget on fs.rename. Mirrors
+     * scrollback-store's `renameMaxAttempts` (default 3). Windows AV
+     * scanners + recent-write windows produce transient EBUSY; without
+     * retry every transient EBUSY = lost snapshot.
+     */
+    renameMaxAttempts?: number;
+    /** Custom rename function for tests (simulate Windows EBUSY). */
+    renameFn?: SnapshotRenameFn;
+}
+/**
+ * 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 declare class SnapshotStore {
+    readonly dir: string;
+    private readonly fileMode;
+    private readonly dirMode;
+    private readonly renameMaxAttempts;
+    private readonly renameFn;
+    private resolvedDir;
+    /**
+     * 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.
+     */
+    private readonly writeQueues;
+    constructor(dir: string, opts?: SnapshotStoreOpts);
+    /** Idempotent — creates dir + caches resolved path. */
+    init(): Promise<void>;
+    /**
+     * 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.
+     */
+    write(taskId: string, payload: {
+        cols: number;
+        rows: number;
+        data: string;
+    }): Promise<void>;
+    private writeLocked;
+    /**
+     * 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).
+     */
+    private safeRename;
+    private getOrCreateWriteQueue;
+    /**
+     * Read + parse the snapshot. Returns null if absent (ENOENT).
+     * Throws SnapshotStoreError on malformed header / unknown version.
+     */
+    read(taskId: string): Promise<SnapshotRecord | null>;
+    /** Existence probe — does not read or parse. */
+    has(taskId: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    clearBestEffort(taskId: string): Promise<void>;
+    /**
+     * 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`).
+     */
+    clear(taskId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    releaseQueue(taskId: string): Promise<void>;
+    private validateTaskId;
+    /**
+     * 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).
+     */
+    private resolveTargetPath;
+    private ensureDirResolved;
+}
+/**
+ * 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 declare function parseSnapshotEnvelope(raw: string): SnapshotRecord;
+//# sourceMappingURL=snapshot-store.d.ts.map

package/server/dist/terminal/snapshot-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-store.d.ts","sourceRoot":"","sources":["../../src/terminal/snapshot-store.ts"],"names":[],"mappings":"AAkGA,yEAAyE;AACzE,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D;AAWD,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,IAAI,EAChB,iBAAiB,GACjB,2BAA2B,GAC3B,iBAAiB,GACjB,kBAAkB;gBAJN,IAAI,EAChB,iBAAiB,GACjB,2BAA2B,GAC3B,iBAAiB,GACjB,kBAAkB,EACtB,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAe,SAAQ,cAAc;IACpD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3E,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAa;aAqBN,GAAG,EAAE,MAAM;IApB7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,WAAW,CAAuB;IAC1C;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;gBAGvC,GAAG,EAAE,MAAM,EAC3B,IAAI,GAAE,iBAAsB;IAQ9B,uDAAuD;IACjD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;;;;;;;;;;;;OAeG;IACG,KAAK,CACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GACpD,OAAO,CAAC,IAAI,CAAC;YAMF,WAAW;IAmCzB;;;;;OAKG;YACW,UAAU;IAqBxB,OAAO,CAAC,qBAAqB;IAS7B;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAa1D,gDAAgD;IAC1C,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAY3C;;;;;OAKG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpD;;;;;;OAMG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB1C;;;;;;;OAOG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjD,OAAO,CAAC,cAAc;IAStB;;;;OAIG;YACW,iBAAiB;YAoBjB,iBAAiB;CAMhC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CA6DjE"}