@svenroth-ai/shipwright 0.24.1-next.0

package/server/dist/terminal/backpressure-telemetry.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Payload of the `{type:"backpressure"}` WS envelope. `droppedBytes` keeps its
+ * original name and stays wire-compatible: at episode-open it is still the first
+ * dropped chunk's size. Its MEANING is now "bytes lost in this episode so far",
+ * which is what makes the loss countable (the old value could not be summed).
+ *
+ * Mirrored client-side in `client/src/hooks/useTerminalSocket.ts`. Additive only —
+ * an older client reading just `droppedBytes` keeps working.
+ */
+export interface BackpressureNotice {
+    /** Bytes lost in the CURRENT saturation episode, cumulative. */
+    droppedBytes: number;
+    /** Chunks lost in the current episode. */
+    droppedChunks: number;
+    /** Bytes lost across this connection's whole lifetime. */
+    totalDroppedBytes: number;
+    /** 1-based index of this saturation episode on this connection. */
+    episode: number;
+    /** True when delivery has resumed — this notice closes the episode. */
+    episodeEnded: boolean;
+}
+interface ConnAccount {
+    taskId: string;
+    /** Non-null while a saturation episode is open. */
+    episodeBytes: number | null;
+    episodeChunks: number;
+    totalDroppedBytes: number;
+    totalDroppedChunks: number;
+    episodes: number;
+    /** Timestamp of the last emitted log line, for throttling. */
+    lastLogAt: number;
+    /** Whether this connection has ever emitted a line (the first always emits). */
+    everLogged: boolean;
+    /** Lines withheld by the throttle since the last emitted one. */
+    suppressed: number;
+}
+export interface BackpressureTelemetryOpts {
+    now?: () => number;
+    log?: (msg: string) => void;
+    /** Minimum gap between mid-episode log lines, per connection. */
+    logIntervalMs?: number;
+}
+/** Default throttle for mid-episode lines. Open/close always log. */
+export declare const DEFAULT_LOG_INTERVAL_MS = 5000;
+export declare class BackpressureTelemetry {
+    private readonly accounts;
+    private readonly now;
+    private readonly log;
+    private readonly logIntervalMs;
+    constructor(opts?: BackpressureTelemetryOpts);
+    private account;
+    /**
+     * Emit `body` unless the throttle withholds it. The first line for a connection
+     * always emits; afterwards at most one line per `logIntervalMs`, whatever its
+     * kind. A withheld line is counted so the next emitted one can disclose it —
+     * suppression must cost timing detail, never the volume of the loss.
+     */
+    private throttledLog;
+    /**
+     * Record one discarded chunk.
+     *
+     * @returns the notice to forward to the client when this drop OPENS an
+     *   episode, or `null` while an episode is already open (the client has been
+     *   told; every further chunk is still counted).
+     */
+    onDrop(taskId: string, conn: unknown, bytes: number): BackpressureNotice | null;
+    /**
+     * Record a successful delivery. Closes an open episode.
+     *
+     * @returns the closing notice (carrying the accurate episode total) when an
+     *   episode was open, else `null`. Called on every delivery, so the no-episode
+     *   path is a single WeakMap lookup.
+     */
+    onDelivered(taskId: string, conn: unknown): BackpressureNotice | null;
+    /** Lifetime counters for a connection — diagnostics and tests. */
+    stats(conn: unknown): Readonly<ConnAccount> | undefined;
+    /**
+     * Explicit cleanup on detach — called from the same connection-teardown site that
+     * used to delete the old per-entry `backpressureRaised` flag, so accounts do not
+     * outlive their connection.
+     */
+    release(conn: unknown): void;
+    private notice;
+}
+export {};
+//# sourceMappingURL=backpressure-telemetry.d.ts.map

package/server/dist/terminal/backpressure-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backpressure-telemetry.d.ts","sourceRoot":"","sources":["../../src/terminal/backpressure-telemetry.ts"],"names":[],"mappings":"AAyCA;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,WAAW;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,UAAU,EAAE,OAAO,CAAC;IACpB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAE7C,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,IAAI,GAAE,yBAA8B;IAOhD,OAAO,CAAC,OAAO;IAmBf;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAgBpB;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IA0B/E;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI;IAcrE,kEAAkE;IAClE,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,SAAS;IAIvD;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAI5B,OAAO,CAAC,MAAM;CASf"}

package/server/dist/terminal/backpressure-telemetry.js

@@ -0,0 +1,158 @@
+/*
+ * backpressure-telemetry.ts — accounting + notification policy for the WS
+ * drop-while-saturated path (iterate-2026-07-30-terminal-ws-drop-resync, FR-01.28).
+ *
+ * WHY THIS MODULE EXISTS. `PtyManager.deliverWithBackpressure` discards a pty
+ * chunk when the WS already has more than `wsBufferBytes` queued, and never
+ * resends it. That path shipped with ADR-067 and logged **nothing at all**, so
+ * after nine fixes in the terminal-smear class it was still UNPROVEN whether it
+ * fires in real sessions — the first thing this iterate had to establish. It also
+ * notified the client only ONCE per saturation episode, reporting the size of the
+ * FIRST dropped chunk only, which made the losses uncountable even in principle.
+ *
+ * This module owns three things that belong together and were previously either
+ * absent or smeared across the pty lifecycle owner:
+ *
+ *   1. ACCOUNTING — per connection: bytes and chunks lost in the current
+ *      saturation episode, plus lifetime totals and an episode counter.
+ *   2. NOTIFICATION POLICY — one notice when an episode opens (so the client can
+ *      react promptly) and one when it closes (carrying the accurate episode
+ *      total). Deliberately NOT one per dropped chunk: pushing more frames into
+ *      an already-saturated socket is exactly the wrong move.
+ *   3. RATE-LIMITED LOGGING — the FIRST line for a connection always emits (a real
+ *      event must never be invisible); everything after it is throttled, INCLUDING
+ *      episode open/close transitions. Throttling only the mid-episode lines was
+ *      not enough: a connection whose `bufferedAmount` flaps across the threshold
+ *      opens and closes episodes repeatedly and would emit two lines per flap
+ *      forever, which is exactly the log flood AC-1 forbids (external review).
+ *      Every emitted line carries the cumulative counters plus the number of
+ *      suppressed lines, so throttling loses evidence of TIMING, never of VOLUME.
+ *
+ * The per-connection episode flag lives here rather than on `PtyEntry` (where it
+ * was `backpressureRaised`): the flag exists only to serve the notification policy,
+ * so it belongs with the policy.
+ *
+ * Keyed by a plain `Map` over `unknown`, deliberately NOT a `WeakMap`: `PtyManager`
+ * types a connection as `unknown` and its public API accepts a primitive, which a
+ * `WeakMap` key would reject with a runtime `TypeError` on the hot delivery path
+ * (external review). `release()` is called from the same connection-teardown site
+ * that used to delete the old per-entry flag, so the lifecycle is unchanged.
+ */
+/** Default throttle for mid-episode lines. Open/close always log. */
+export const DEFAULT_LOG_INTERVAL_MS = 5_000;
+export class BackpressureTelemetry {
+    accounts = new Map();
+    now;
+    log;
+    logIntervalMs;
+    constructor(opts = {}) {
+        this.now = opts.now ?? (() => Date.now());
+        // eslint-disable-next-line no-console
+        this.log = opts.log ?? ((m) => console.warn(m));
+        this.logIntervalMs = opts.logIntervalMs ?? DEFAULT_LOG_INTERVAL_MS;
+    }
+    account(taskId, conn) {
+        let a = this.accounts.get(conn);
+        if (!a) {
+            a = {
+                taskId,
+                episodeBytes: null,
+                episodeChunks: 0,
+                totalDroppedBytes: 0,
+                totalDroppedChunks: 0,
+                episodes: 0,
+                lastLogAt: 0,
+                everLogged: false,
+                suppressed: 0,
+            };
+            this.accounts.set(conn, a);
+        }
+        return a;
+    }
+    /**
+     * Emit `body` unless the throttle withholds it. The first line for a connection
+     * always emits; afterwards at most one line per `logIntervalMs`, whatever its
+     * kind. A withheld line is counted so the next emitted one can disclose it —
+     * suppression must cost timing detail, never the volume of the loss.
+     */
+    throttledLog(a, body) {
+        const now = this.now();
+        if (a.everLogged && now - a.lastLogAt < this.logIntervalMs) {
+            a.suppressed += 1;
+            return;
+        }
+        const withheld = a.suppressed > 0 ? ` (+${a.suppressed} similar suppressed)` : "";
+        a.suppressed = 0;
+        a.everLogged = true;
+        a.lastLogAt = now;
+        this.log(`${body} sessionDropped=${a.totalDroppedBytes}B/${a.totalDroppedChunks} chunks` +
+            ` episodes=${a.episodes}${withheld}`);
+    }
+    /**
+     * Record one discarded chunk.
+     *
+     * @returns the notice to forward to the client when this drop OPENS an
+     *   episode, or `null` while an episode is already open (the client has been
+     *   told; every further chunk is still counted).
+     */
+    onDrop(taskId, conn, bytes) {
+        const a = this.account(taskId, conn);
+        const opening = a.episodeBytes === null;
+        if (opening) {
+            a.episodeBytes = 0;
+            a.episodeChunks = 0;
+            a.episodes += 1;
+        }
+        a.episodeBytes = (a.episodeBytes ?? 0) + bytes;
+        a.episodeChunks += 1;
+        a.totalDroppedBytes += bytes;
+        a.totalDroppedChunks += 1;
+        this.throttledLog(a, opening
+            ? `[pty-manager] WS saturated — DISCARDING pty output for task=${a.taskId} ` +
+                `episode=${a.episodes} firstChunk=${bytes}B ` +
+                `(dropped and never resent; client will be asked to resync)`
+            : `[pty-manager] WS still saturated — task=${a.taskId} episode=${a.episodes} ` +
+                `episodeDropped=${a.episodeBytes}B/${a.episodeChunks} chunks`);
+        return opening ? this.notice(a, false) : null;
+    }
+    /**
+     * Record a successful delivery. Closes an open episode.
+     *
+     * @returns the closing notice (carrying the accurate episode total) when an
+     *   episode was open, else `null`. Called on every delivery, so the no-episode
+     *   path is a single WeakMap lookup.
+     */
+    onDelivered(taskId, conn) {
+        const a = this.accounts.get(conn);
+        if (!a || a.episodeBytes === null)
+            return null;
+        const notice = this.notice(a, true);
+        this.throttledLog(a, `[pty-manager] WS drained — task=${a.taskId} episode=${a.episodes} ` +
+            `episodeDropped=${a.episodeBytes}B/${a.episodeChunks} chunks`);
+        a.episodeBytes = null;
+        a.episodeChunks = 0;
+        return notice;
+    }
+    /** Lifetime counters for a connection — diagnostics and tests. */
+    stats(conn) {
+        return this.accounts.get(conn);
+    }
+    /**
+     * Explicit cleanup on detach — called from the same connection-teardown site that
+     * used to delete the old per-entry `backpressureRaised` flag, so accounts do not
+     * outlive their connection.
+     */
+    release(conn) {
+        this.accounts.delete(conn);
+    }
+    notice(a, episodeEnded) {
+        return {
+            droppedBytes: a.episodeBytes ?? 0,
+            droppedChunks: a.episodeChunks,
+            totalDroppedBytes: a.totalDroppedBytes,
+            episode: a.episodes,
+            episodeEnded,
+        };
+    }
+}
+//# sourceMappingURL=backpressure-telemetry.js.map

package/server/dist/terminal/backpressure-telemetry.js.map

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

package/server/dist/terminal/boot-wipe.d.ts

@@ -0,0 +1,47 @@
+export declare const ITERATE_C_WIPE_MARKER = ".iterate-c-wiped.marker";
+export interface BootWipeDeps {
+    readdir: (dir: string) => Promise<string[]>;
+    unlink: (p: string) => Promise<void>;
+    writeFile: (p: string, data: string) => Promise<void>;
+    stat: (p: string) => Promise<{
+        isFile(): boolean;
+    } | null>;
+}
+export interface BootWipeOpts {
+    /** Absolute path to the scrollback directory (e.g. <home>/.shipwright-webui/terminal-scrollback). */
+    dir: string;
+    /** Injected for tests; defaults to node:fs/promises. */
+    deps?: Partial<BootWipeDeps>;
+    /** Injected for tests; defaults to console.warn. */
+    logWarn?: (msg: string) => void;
+    /** Injected for tests; defaults to console.log. */
+    logInfo?: (msg: string) => void;
+}
+export interface BootWipeResult {
+    /** True if the marker existed before this run (i.e. wipe was skipped). */
+    skipped: boolean;
+    /** Number of `.log*` files unlinked successfully. */
+    deleted: number;
+    /** Number of per-file errors (kept going). */
+    errors: number;
+    /** Whether the marker was written this run. */
+    markerWritten: boolean;
+}
+/**
+ * Idempotent one-shot wipe of legacy byte-stream scrollback files.
+ *
+ * Behavior:
+ *   - If the marker exists → return `{skipped: true}` immediately.
+ *   - Else: list dir, unlink every entry matching `*.log` / `*.log.\d+`,
+ *     count successes + failures, then write the marker.
+ *   - Wipe failure of an individual file is non-fatal; we still write
+ *     the marker so subsequent boots don't retry the whole sweep.
+ *   - Marker-write failure: log warn but treat as success (the wipe
+ *     itself succeeded; missing marker is a recovery edge case that
+ *     the operator can re-trigger by deleting `.shipwright-webui/`).
+ *
+ * Returns a structured result so callers (boot path) can log a single
+ * summary line.
+ */
+export declare function runBootWipe(opts: BootWipeOpts): Promise<BootWipeResult>;
+//# sourceMappingURL=boot-wipe.d.ts.map

package/server/dist/terminal/boot-wipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-wipe.d.ts","sourceRoot":"","sources":["../../src/terminal/boot-wipe.ts"],"names":[],"mappings":"AAqCA,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,MAAM,IAAI,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,YAAY;IAC3B,qGAAqG;IACrG,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7B,oDAAoD;IACpD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,mDAAmD;IACnD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,aAAa,EAAE,OAAO,CAAC;CACxB;AAkBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAkE7E"}

package/server/dist/terminal/boot-wipe.js

@@ -0,0 +1,122 @@
+/*
+ * boot-wipe.ts — Iterate C (ADR-087).
+ *
+ * One-shot wipe of legacy `<scrollbackDir>/*.log*` files at first boot
+ * after Iterate C deploys. Replaces the 24-h TTL natural-decay strategy
+ * with a cleaner cut: the chunked-replay path is gone, so byte-stream
+ * scrollback files have no remaining consumer and accumulate as pure
+ * disk waste. We wipe once, mark the directory, and never wipe again.
+ *
+ * Architecture invariants:
+ *   1. Idempotent — a marker file `.iterate-c-wiped.marker` records that
+ *      the wipe ran. Subsequent boots short-circuit when the marker
+ *      exists. Loss of the marker after a successful wipe MUST NOT
+ *      cause re-wipe of new scrollback that may have accumulated post-
+ *      Iterate-C (we treat that as a stable post-conditioned state).
+ *   2. Marker is written AFTER unlinks complete (NEVER before — a crash
+ *      between marker-write and unlink would leave files orphaned with
+ *      no future wipe path).
+ *   3. Per-file failure is non-fatal — log a warn, continue with the
+ *      next file. The marker is still written if ANY file was removed
+ *      (partial wipe is a stable post-condition; the operator can
+ *      manually clean stragglers via the OS file manager).
+ *   4. Snapshot files (`.snapshot`) are PRESERVED — those are the
+ *      Iterate-B replay artifacts we explicitly want to keep.
+ *   5. Best-effort overall: dir-read failure logs a warn and returns
+ *      without writing the marker (so the wipe re-attempts on next
+ *      boot). Boot path MUST NOT crash on wipe failure.
+ *
+ * Testability:
+ *   - `runBootWipe(opts)` is a pure function over a deps object (fs +
+ *     dir) so unit tests can stub fs without touching disk. Production
+ *     wires `node:fs/promises` directly.
+ */
+import * as fsAsync from "node:fs/promises";
+import * as path from "node:path";
+export const ITERATE_C_WIPE_MARKER = ".iterate-c-wiped.marker";
+const LOG_FILE_RE = /\.log(?:\.\d+)?$/;
+const defaultDeps = {
+    readdir: (dir) => fsAsync.readdir(dir),
+    unlink: (p) => fsAsync.unlink(p),
+    writeFile: (p, data) => fsAsync.writeFile(p, data, { encoding: "utf8" }),
+    stat: async (p) => {
+        try {
+            const s = await fsAsync.stat(p);
+            return { isFile: () => s.isFile() };
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * Idempotent one-shot wipe of legacy byte-stream scrollback files.
+ *
+ * Behavior:
+ *   - If the marker exists → return `{skipped: true}` immediately.
+ *   - Else: list dir, unlink every entry matching `*.log` / `*.log.\d+`,
+ *     count successes + failures, then write the marker.
+ *   - Wipe failure of an individual file is non-fatal; we still write
+ *     the marker so subsequent boots don't retry the whole sweep.
+ *   - Marker-write failure: log warn but treat as success (the wipe
+ *     itself succeeded; missing marker is a recovery edge case that
+ *     the operator can re-trigger by deleting `.shipwright-webui/`).
+ *
+ * Returns a structured result so callers (boot path) can log a single
+ * summary line.
+ */
+export async function runBootWipe(opts) {
+    const deps = {
+        ...defaultDeps,
+        ...(opts.deps ?? {}),
+    };
+    const logWarn = opts.logWarn ?? ((m) => console.warn(m));
+    const logInfo = opts.logInfo ?? ((m) => console.log(m));
+    const markerPath = path.join(opts.dir, ITERATE_C_WIPE_MARKER);
+    const existing = await deps.stat(markerPath);
+    if (existing && existing.isFile()) {
+        return { skipped: true, deleted: 0, errors: 0, markerWritten: false };
+    }
+    let entries;
+    try {
+        entries = await deps.readdir(opts.dir);
+    }
+    catch (err) {
+        // Dir doesn't exist OR not readable — non-fatal; nothing to wipe.
+        // Don't write the marker either; on next boot the dir may exist and
+        // we'll retry the sweep cleanly.
+        logWarn(`[boot-wipe] scrollback dir not readable; skipping wipe (${err.message})`);
+        return { skipped: false, deleted: 0, errors: 0, markerWritten: false };
+    }
+    let deleted = 0;
+    let errors = 0;
+    for (const name of entries) {
+        if (!LOG_FILE_RE.test(name))
+            continue;
+        const fullPath = path.join(opts.dir, name);
+        try {
+            await deps.unlink(fullPath);
+            deleted++;
+        }
+        catch (err) {
+            errors++;
+            logWarn(`[boot-wipe] unlink failed for ${name}: ${err.message}`);
+        }
+    }
+    // Write the marker AFTER unlinks complete. Per the hard rule in the
+    // iterate spec: marker write failure must NOT trigger re-wipe — log
+    // warn but treat as wiped if any files were removed.
+    let markerWritten = false;
+    try {
+        await deps.writeFile(markerPath, `# iterate-c boot wipe marker\n# wiped=${deleted} errors=${errors} ts=${new Date().toISOString()}\n`);
+        markerWritten = true;
+    }
+    catch (err) {
+        logWarn(`[boot-wipe] marker write failed: ${err.message} — wipe stays effective; manual marker creation may be needed to suppress next-boot retry`);
+    }
+    if (deleted > 0 || errors > 0) {
+        logInfo(`[boot-wipe] iterate-C scrollback wipe complete: deleted=${deleted} errors=${errors} markerWritten=${markerWritten}`);
+    }
+    return { skipped: false, deleted, errors, markerWritten };
+}
+//# sourceMappingURL=boot-wipe.js.map

package/server/dist/terminal/boot-wipe.js.map

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

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

@@ -0,0 +1,139 @@
+import pkg from "@xterm/headless";
+declare const Terminal: typeof pkg.Terminal;
+type XtermTerminal = InstanceType<typeof Terminal>;
+export interface HeadlessMirrorOpts {
+    taskId: string;
+    cols: number;
+    rows: number;
+    /**
+     * Scrollback depth for the live mirror. xterm.js default is 1000.
+     * Matches `EmbeddedTerminal.tsx` client-side scrollback so visible
+     * regions line up.
+     */
+    scrollback?: number;
+}
+export declare class HeadlessMirror {
+    readonly taskId: string;
+    private term;
+    private cols;
+    private rows;
+    private readonly scrollback;
+    private disposed;
+    /**
+     * Tracks unresolved write() resolvers. serializeStable() awaits the
+     * corresponding promises before snapshotting so the parser cannot be
+     * mid-CSI / mid-OSC when the serialize callback runs (Gemini
+     * external-review #4 + architecture invariant #3 + external code
+     * review HIGH: tracking resolvers explicitly so `dispose()` can
+     * forcibly resolve them and never hang `flushPendingWrites`).
+     *
+     * Stored as a Map of Promise -> resolver so dispose() can drain the
+     * set without waiting for parser callbacks that may never fire on a
+     * disposed Terminal. The set is bounded by the in-flight write count.
+     */
+    private pendingWrites;
+    constructor(opts: HeadlessMirrorOpts);
+    /**
+     * Test-only handle on the underlying Terminal. Real callers go through
+     * write/serializeStable/dispose; the fixture test needs to feed bytes
+     * and snapshot visible lines directly.
+     */
+    get terminalForTesting(): XtermTerminal;
+    /**
+     * Feed raw bytes into the headless mirror. Awaits the parser callback
+     * before resolving — this is architecture invariant #3, required for
+     * mid-escape split correctness.
+     *
+     * Accepts Buffer | Uint8Array | string. node-pty emits strings by
+     * default; the snapshot pipeline can also feed Buffers.
+     */
+    write(data: Buffer | Uint8Array | string): Promise<void>;
+    /**
+     * Await every in-flight write callback. Used internally by
+     * serializeStable so the parser is in a stable state when round1
+     * runs (architecture invariant #3 + external review Gemini #4).
+     */
+    private flushPendingWrites;
+    /**
+     * Adjust dimensions. Headless terminal preserves scrollback contents
+     * across resize; rewrap behavior follows xterm.js's reflow.
+     */
+    resize(cols: number, rows: number): void;
+    /**
+     * M2 double-serialize. Per spike T2: `serialize → write-back → serialize`
+     * is idempotent at round2 == round3, so this produces the stable fixed
+     * point that the client's xterm.js will reproduce byte-for-byte.
+     *
+     * Procedure:
+     *   raw   = primary serialize (may contain 1-char drift artifacts)
+     *   warm  = transient Terminal, replay raw, serialize → stable (round2)
+     *   return stable, dispose warm
+     *
+     * Contract: when the returned `stable` string is later written into a
+     * fresh client-side xterm Terminal of the same cols/rows, that
+     * Terminal's visible buffer (round3 application) is line-for-line
+     * equal to the warm Terminal's visible buffer at the moment of round2
+     * serialization. The live mirror's own visible buffer is round1 — it
+     * may differ from round2 by one or two cells on resize boundaries.
+     * That is the documented one-shot artifact M2 trades for idempotence.
+     *
+     * The warm Terminal MUST use identical cols/rows + scrollback so the
+     * replay buffer is identical in shape.
+     */
+    serializeStable(): Promise<string>;
+    /**
+     * Same as serializeStable() but also returns the canonical (round2)
+     * visible-buffer snapshot. Test-only — production callers use
+     * serializeStable() which discards the buffer. The round2 buffer is
+     * the contract reference: a client replay of `stable` produces the
+     * same lines.
+     *
+     * `stable` additionally carries a trailing DECTCEM (`?25h` / `?25l`):
+     * addon-serialize never serializes cursor visibility, so it is restored
+     * explicitly here — see `readCursorHidden()`.
+     */
+    serializeStableWithCanonicalBuffer(): Promise<{
+        stable: string;
+        canonicalLines: string[];
+    }>;
+    /**
+     * Live mirror's DECTCEM state — `true` when the cursor is hidden.
+     * addon-serialize never serializes `?25`, so `serializeStable()` restores
+     * it explicitly: else a reattach shows a ghost cursor that Claude Code
+     * (fullscreen under `CLAUDE_CODE_NO_FLICKER=1`, ADR-095/098) believes is
+     * hidden, jumping with every CUP redraw. The `_core.coreService` peek is
+     * an internal-surface read (xterm exact-pinned 6.0.0, CLAUDE.md rule 22),
+     * correct across `?25l` / `?25h` AND soft-reset. Unreadable internal →
+     * `false` (pre-fix behaviour) so a future xterm refactor degrades safely.
+     */
+    private readCursorHidden;
+    /** Current dimensions. Used by snapshot-store to write the header. */
+    get dimensions(): {
+        cols: number;
+        rows: number;
+    };
+    /**
+     * Decoded text of the visible viewport (the bottom page) — scrollback
+     * excluded, ANSI already interpreted into cells. Reads rows
+     * `baseY … baseY + rows` so it always captures the bottom of the
+     * buffer regardless of scroll state. Trailing whitespace per line is
+     * trimmed.
+     *
+     * iterate-2026-05-18-inbox-terminal-prompts: consumed by
+     * `PtyManager.peekTerminalText()` so the inbox can detect a *waiting*
+     * `AskUserQuestion` picker — the picker is on-screen, never in the
+     * JSONL. Best-effort: returns "" on a disposed mirror or any
+     * buffer-read error (never throws — it sits behind an inbox poll).
+     */
+    getVisibleText(): string;
+    /**
+     * Idempotent. External code review HIGH: drain pending writes BEFORE
+     * disposing the Terminal so any `flushPendingWrites()` awaiters can
+     * resolve immediately rather than wait forever on parser callbacks
+     * that will never fire on a disposed Terminal.
+     */
+    dispose(): void;
+    get isDisposed(): boolean;
+}
+export {};
+//# sourceMappingURL=headless-mirror.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"headless-mirror.d.ts","sourceRoot":"","sources":["../../src/terminal/headless-mirror.ts"],"names":[],"mappings":"AAoCA,OAAO,GAAG,MAAM,iBAAiB,CAAC;AAElC,QAAA,MAAQ,QAAQ,qBAAQ,CAAC;AAKzB,KAAK,aAAa,GAAG,YAAY,CAAC,OAAO,QAAQ,CAAC,CAAC;AAgCnD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAoCD,qBAAa,cAAc;IACzB,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAS;IACzB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa,CAAwC;gBAEjD,IAAI,EAAE,kBAAkB;IAepC;;;;OAIG;IACH,IAAI,kBAAkB,IAAI,aAAa,CAEtC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCxD;;;;OAIG;YACW,kBAAkB;IAShC;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IASxC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAKxC;;;;;;;;;;OAUG;IACG,kCAAkC,IAAI,OAAO,CAAC;QAClD,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;IAyDF;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;IAWxB,sEAAsE;IACtE,IAAI,UAAU,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAE/C;IAED;;;;;;;;;;;;OAYG;IACH,cAAc,IAAI,MAAM;IAgBxB;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAqBf,IAAI,UAAU,IAAI,OAAO,CAExB;CACF"}