@svenroth-ai/shipwright 0.24.1-next.0

package/server/dist/core/session-watcher.js

@@ -0,0 +1,226 @@
+/*
+ * Session JSONL discovery + stateless byte-range reader.
+ *
+ * Variant-a narrow: NO chokidar, NO recursive watchers. Discovery is
+ * filename-first per PoC finding 1 — claude writes each session at
+ * `~/.claude/projects/<encoded-cwd>/<uuid>.jsonl`, and the filename is
+ * the authoritative primitive (first-line sessionId verification is a
+ * sanity check only; fork-session files begin with `file-history-snapshot`
+ * lines that carry no sessionId).
+ *
+ * The transcript endpoint reads byte-ranges stateless: the client supplies
+ * `fromByte` + `expectFingerprint`; the server returns the delta. No
+ * server-side offset cache → multi-tab works by construction.
+ *
+ * The disk primitives — the torn-read retry envelope (50 → 1600 ms × 6 over
+ * EBUSY / EPERM / EACCES / ENOENT, insurance against AV scanners / OneDrive /
+ * Defender), the POSITIONAL tail read (`readChunk` reads only `[fromByte, EOF)`,
+ * never the whole file) and the newline scan — live in `session-jsonl-io.ts`,
+ * which also carries the append/truncate concurrency contract they honour.
+ */
+import { readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { ENOENT_FATAL, lastIndexOfByte, readTailFromDisk, readWithRetry, } from "./session-jsonl-io.js";
+import { awaitingLaunchProbe } from "./session-watcher-debug.js";
+export const PROJECTS_DIR = path.join(homedir(), ".claude", "projects");
+const DEFAULT_DEPS = {
+    readdir: (p) => readdir(p),
+    stat: (p) => stat(p).then((s) => ({
+        mtimeMs: s.mtimeMs,
+        size: s.size,
+        isDirectory: () => s.isDirectory(),
+    })),
+    readTail: (p, fromByte) => readTailFromDisk(p, fromByte),
+    projectsDir: PROJECTS_DIR,
+};
+export class SessionWatcher {
+    deps;
+    constructor(deps = {}) {
+        this.deps = { ...DEFAULT_DEPS, ...deps };
+    }
+    /**
+     * Resolve the on-disk JSONL for a given pre-bound session UUID.
+     * Returns null if no file matches yet (common during
+     * `awaiting_external_start` before the user pastes). The env-gated
+     * awaiting-launch diagnostic lives in `session-watcher-debug.ts`.
+     */
+    async findByUuid(sessionUuid) {
+        const probe = awaitingLaunchProbe();
+        const wanted = `${sessionUuid.toLowerCase()}.jsonl`;
+        let subs;
+        try {
+            // D06/F24 — retry transient fs errors, fast-fail ENOENT (absent dir).
+            subs = await readWithRetry(() => this.deps.readdir(this.deps.projectsDir), ENOENT_FATAL);
+        }
+        catch {
+            probe?.readdirFailed(sessionUuid, this.deps.projectsDir);
+            return null;
+        }
+        for (const sub of subs) {
+            const subPath = path.join(this.deps.projectsDir, sub);
+            try {
+                const s = await readWithRetry(() => this.deps.stat(subPath), ENOENT_FATAL);
+                if (!s.isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            let files;
+            try {
+                files = await readWithRetry(() => this.deps.readdir(subPath), ENOENT_FATAL);
+            }
+            catch {
+                continue;
+            }
+            for (const f of files) {
+                if (f.toLowerCase() !== wanted)
+                    continue;
+                const fp = path.join(subPath, f);
+                try {
+                    // D06/F24 core fix — retry the matched file's stat (pre-fix a transient EBUSY here read as an authoritative "JSONL missing").
+                    const fs = await readWithRetry(() => this.deps.stat(fp), ENOENT_FATAL);
+                    probe?.hit(sessionUuid, sub, fs.size);
+                    return { path: fp, encodedCwd: sub, mtimeMs: fs.mtimeMs, sizeBytes: fs.size };
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+        probe?.miss(sessionUuid, subs);
+        return null;
+    }
+    /**
+     * Batch variant of {@link findByUuid} — resolves many session UUIDs in
+     * a SINGLE `~/.claude/projects` walk. `GET /api/external/tasks` uses
+     * this so the board delivers a LIVE JSONL mtime for every task in one
+     * scan (ADR-102 — the Resume-CTA gate must not be fed the stale
+     * persisted `lastJsonlSeenMtimeMs`, which only the transcript endpoint
+     * of the currently-open detail page refreshes).
+     *
+     * Returns a Map keyed by LOWERCASE uuid. UUIDs with no matching file
+     * on disk are simply absent from the result (same as `findByUuid`
+     * returning null). An empty input set short-circuits with no walk.
+     */
+    async findManyByUuid(uuids) {
+        const out = new Map();
+        // `<uuid>.jsonl` (lowercase) -> uuid (lowercase)
+        const wanted = new Map();
+        for (const u of uuids) {
+            const lc = u.toLowerCase();
+            wanted.set(`${lc}.jsonl`, lc);
+        }
+        if (wanted.size === 0)
+            return out;
+        let subs;
+        try {
+            subs = await this.deps.readdir(this.deps.projectsDir);
+        }
+        catch {
+            return out;
+        }
+        for (const sub of subs) {
+            if (out.size === wanted.size)
+                break; // all resolved — stop the walk early
+            const subPath = path.join(this.deps.projectsDir, sub);
+            try {
+                const s = await this.deps.stat(subPath);
+                if (!s.isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            let files;
+            try {
+                files = await this.deps.readdir(subPath);
+            }
+            catch {
+                continue;
+            }
+            for (const f of files) {
+                const uuid = wanted.get(f.toLowerCase());
+                if (!uuid || out.has(uuid))
+                    continue;
+                const fp = path.join(subPath, f);
+                try {
+                    const fst = await this.deps.stat(fp);
+                    out.set(uuid, {
+                        path: fp,
+                        encodedCwd: sub,
+                        mtimeMs: fst.mtimeMs,
+                        sizeBytes: fst.size,
+                    });
+                }
+                catch {
+                    /* unreadable — leave absent, mirrors findByUuid's null path */
+                }
+            }
+        }
+        return out;
+    }
+    /**
+     * Read a byte-range from the JSONL with torn-read retry + UTF-8 safe
+     * chunk trimming. Always returns content ending on `\n` so the client
+     * never sees a partial line (and `\n` is safe to split on even in the
+     * middle of a multi-byte UTF-8 sequence).
+     *
+     * Returns the `JsonlLocation` it read from on success, so a caller needing
+     * the file's mtime/size does not walk `~/.claude/projects` a second time for
+     * an answer this call already had (iterate-2026-07-22-…-single-walk).
+     */
+    async readChunk(args) {
+        const loc = args.location ?? (await this.findByUuid(args.sessionUuid));
+        if (!loc)
+            return { status: "missing" };
+        const fingerprint = computeFingerprint(loc);
+        if (args.expectFingerprint && args.expectFingerprint !== fingerprint) {
+            const [, prevSizeStr] = args.expectFingerprint.split(":");
+            const prevSize = Number.parseInt(prevSizeStr ?? "0", 10);
+            if (loc.sizeBytes < args.fromByte || loc.sizeBytes < prevSize) {
+                return { status: "rotated", currentFingerprint: fingerprint };
+            }
+        }
+        // Positional: only `[fromByte, EOF)` leaves the disk. `liveSize` is the end
+        // THAT read observed, so a file truncated between discovery and the read
+        // clamps `from` exactly as the old whole-file reader implicitly did.
+        // No `fatalCodes` here, deliberately: unlike discovery, a transient ENOENT
+        // on the read is an AV scanner / sync client yanking a file we just saw,
+        // and must be retried rather than reported as an authoritative miss.
+        // NOTE `chunk.toByte` may exceed `chunk.size`: `size` comes from the
+        // discovery stat while the read runs through the EOF its OWN handle saw.
+        // Pre-existing, and load-bearing since a client cursor arrived — a
+        // `fromByte` past `prevSize` is exactly what the rotation check's
+        // `sizeBytes < fromByte` disjunct absorbs (internal review, LOW-5).
+        const { bytes, size: liveSize } = await readWithRetry(() => this.deps.readTail(loc.path, args.fromByte));
+        const from = Math.min(Math.max(args.fromByte, 0), liveSize);
+        let slice = bytes;
+        let endExclusive = from + slice.length;
+        const lastNl = lastIndexOfByte(slice, 0x0a);
+        if (lastNl === -1) {
+            slice = Buffer.alloc(0);
+            endExclusive = from;
+        }
+        else {
+            slice = slice.subarray(0, lastNl + 1);
+            endExclusive = from + lastNl + 1;
+        }
+        return {
+            status: "ok",
+            location: loc,
+            chunk: {
+                fingerprint,
+                size: loc.sizeBytes,
+                fromByte: from,
+                toByte: endExclusive,
+                content: slice.toString("utf-8"),
+            },
+        };
+    }
+}
+export function computeFingerprint(loc) {
+    return `${Math.trunc(loc.mtimeMs)}:${loc.sizeBytes}`;
+}
+//# sourceMappingURL=session-watcher.js.map

package/server/dist/core/session-watcher.js.map

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

package/server/dist/core/shell-quote.d.ts

@@ -0,0 +1,5 @@
+export declare function qPs(v: string): string;
+export declare function qCmd(v: string): string;
+export declare function qPosix(v: string): string;
+export declare function toPosixPath(p: string): string;
+//# sourceMappingURL=shell-quote.d.ts.map

package/server/dist/core/shell-quote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-quote.d.ts","sourceRoot":"","sources":["../../src/core/shell-quote.ts"],"names":[],"mappings":"AAYA,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrC;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAwBtC;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxC;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C"}

package/server/dist/core/shell-quote.js

@@ -0,0 +1,49 @@
+// Shell-specific argument escaping for the three launch shells (PowerShell,
+// cmd.exe, POSIX).
+//
+// Extracted from launcher.ts (iterate-2026-06-27-codeql-hardening) to keep that
+// file under the 300-LOC limit and make the quoters independently testable.
+// `core/actions-substitute.ts` calls them per target shell before substituting
+// user-derived placeholders into command templates; the shell-escape discipline
+// is the security boundary for command-template substitution (plan.md § 2.2).
+// launcher.ts re-exports these, so existing `from "./launcher.js"` importers
+// keep working. Do not move this logic behind a different abstraction without
+// updating `actions-substitute.ts`.
+export function qPs(v) {
+    // PS single-quoted: embedded `'` → `''`.
+    return `'${v.replace(/'/g, "''")}'`;
+}
+export function qCmd(v) {
+    // cmd.exe double-quoted argument, escaped per CommandLineToArgvW (the prior
+    // `"${v.replace(/"/g,'\\"')}"` left backslashes unescaped — CodeQL
+    // js/incomplete-sanitization #4): N `\` before an embedded `"` → 2N+1 `\`+`"`;
+    // N `\` before the CLOSING quote → 2N `\` (a trailing `\` can't escape it);
+    // `\` not before a quote stays literal (`C:\foo` must not become `C:\\foo`).
+    // Argv layer only; cmd.exe metachar handling is out of scope on this
+    // loopback tool (inputs aren't cross-user-trust; `qPs` is the default shell).
+    let out = '"';
+    let pendingBackslashes = 0;
+    for (const ch of v) {
+        if (ch === "\\") {
+            pendingBackslashes += 1;
+            continue;
+        }
+        if (ch === '"') {
+            out += "\\".repeat(pendingBackslashes * 2 + 1) + '"';
+        }
+        else {
+            out += "\\".repeat(pendingBackslashes) + ch;
+        }
+        pendingBackslashes = 0;
+    }
+    out += "\\".repeat(pendingBackslashes * 2) + '"';
+    return out;
+}
+export function qPosix(v) {
+    // POSIX single-quoted: `'` → `'\''`.
+    return `'${v.replace(/'/g, "'\\''")}'`;
+}
+export function toPosixPath(p) {
+    return p.replace(/\\/g, "/");
+}
+//# sourceMappingURL=shell-quote.js.map

package/server/dist/core/shell-quote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-quote.js","sourceRoot":"","sources":["../../src/core/shell-quote.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,mBAAmB;AACnB,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,+EAA+E;AAC/E,gFAAgF;AAChF,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,oCAAoC;AAEpC,MAAM,UAAU,GAAG,CAAC,CAAS;IAC3B,yCAAyC;IACzC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,CAAS;IAC5B,4EAA4E;IAC5E,mEAAmE;IACnE,+EAA+E;IAC/E,4EAA4E;IAC5E,6EAA6E;IAC7E,qEAAqE;IACrE,8EAA8E;IAC9E,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,IAAI,kBAAkB,GAAG,CAAC,CAAC;IAC3B,KAAK,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;QACnB,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,kBAAkB,IAAI,CAAC,CAAC;YACxB,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;QACvD,CAAC;aAAM,CAAC;YACN,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE,CAAC;QAC9C,CAAC;QACD,kBAAkB,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;IACjD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,CAAS;IAC9B,qCAAqC;IACrC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC"}

package/server/dist/core/task-editability.d.ts

@@ -0,0 +1,22 @@
+import type { ExternalTask } from "./sdk-sessions-store.js";
+/**
+ * Fields frozen once a task has started. Keep this literal byte-identical
+ * to the client mirror — the parity test extracts and compares it.
+ */
+export declare const FROZEN_WHEN_STARTED: readonly ["description", "phase", "priority", "complexityHint", "autonomy"];
+export type FrozenField = (typeof FROZEN_WHEN_STARTED)[number];
+/**
+ * A task is "never started" while it sits in the Backlog and has never
+ * been launched. A `draft` task that ran and was moved back to the
+ * Backlog keeps its `launchedAt` (set by /launch) and its
+ * `firstJsonlObservedAt` — it counts as STARTED, so its launch-shaping
+ * fields stay frozen.
+ */
+export declare function isNeverStarted(task: Pick<ExternalTask, "state" | "launchedAt" | "firstJsonlObservedAt">): boolean;
+/**
+ * True when `field` may be edited given the task's lifecycle position.
+ * Never-started → everything editable. Started → only the non-frozen
+ * fields (title / projectId / domain / tags / blockedBy).
+ */
+export declare function isFieldEditable(field: string, task: Pick<ExternalTask, "state" | "launchedAt" | "firstJsonlObservedAt">): boolean;
+//# sourceMappingURL=task-editability.d.ts.map

package/server/dist/core/task-editability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-editability.d.ts","sourceRoot":"","sources":["../../src/core/task-editability.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,mBAAmB,6EAMtB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,YAAY,GAAG,sBAAsB,CAAC,GACxE,OAAO,CAMT;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,YAAY,GAAG,sBAAsB,CAAC,GACxE,OAAO,CAGT"}

package/server/dist/core/task-editability.js

@@ -0,0 +1,34 @@
+/**
+ * Fields frozen once a task has started. Keep this literal byte-identical
+ * to the client mirror — the parity test extracts and compares it.
+ */
+export const FROZEN_WHEN_STARTED = [
+    "description",
+    "phase",
+    "priority",
+    "complexityHint",
+    "autonomy",
+];
+/**
+ * A task is "never started" while it sits in the Backlog and has never
+ * been launched. A `draft` task that ran and was moved back to the
+ * Backlog keeps its `launchedAt` (set by /launch) and its
+ * `firstJsonlObservedAt` — it counts as STARTED, so its launch-shaping
+ * fields stay frozen.
+ */
+export function isNeverStarted(task) {
+    return (task.state === "draft" &&
+        !task.launchedAt &&
+        !task.firstJsonlObservedAt);
+}
+/**
+ * True when `field` may be edited given the task's lifecycle position.
+ * Never-started → everything editable. Started → only the non-frozen
+ * fields (title / projectId / domain / tags / blockedBy).
+ */
+export function isFieldEditable(field, task) {
+    if (isNeverStarted(task))
+        return true;
+    return !FROZEN_WHEN_STARTED.includes(field);
+}
+//# sourceMappingURL=task-editability.js.map

package/server/dist/core/task-editability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-editability.js","sourceRoot":"","sources":["../../src/core/task-editability.ts"],"names":[],"mappings":"AAwBA;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,aAAa;IACb,OAAO;IACP,UAAU;IACV,gBAAgB;IAChB,UAAU;CACF,CAAC;AAIX;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAyE;IAEzE,OAAO,CACL,IAAI,CAAC,KAAK,KAAK,OAAO;QACtB,CAAC,IAAI,CAAC,UAAU;QAChB,CAAC,IAAI,CAAC,oBAAoB,CAC3B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAa,EACb,IAAyE;IAEzE,IAAI,cAAc,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,CAAE,mBAAyC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC"}

package/server/dist/core/terminal-prompt-detect.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extract the waiting-picker block from decoded terminal viewport text.
+ * Returns the trimmed block (capped at `MAX_QUESTION_TEXT_LEN`) when a
+ * live `AskUserQuestion` picker is the bottom-most content, else `null`.
+ */
+export declare function extractTerminalPrompt(visibleText: string): string | null;
+//# sourceMappingURL=terminal-prompt-detect.d.ts.map

package/server/dist/core/terminal-prompt-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-prompt-detect.d.ts","sourceRoot":"","sources":["../../src/core/terminal-prompt-detect.ts"],"names":[],"mappings":"AA8DA;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA6DxE"}

package/server/dist/core/terminal-prompt-detect.js

@@ -0,0 +1,128 @@
+/*
+ * terminal-prompt-detect.ts — iterate-2026-05-18-inbox-terminal-prompts
+ *
+ * Pure detector for a *waiting* `AskUserQuestion` picker in the visible
+ * text of an embedded-terminal session.
+ *
+ * Why this exists: Claude Code journals a tool-call turn only after the
+ * tool returns. For `AskUserQuestion` "returns" = "the user answered", so
+ * the tool_use + tool_result land in the JSONL together, after the
+ * answer. A *waiting* picker is therefore never visible in the JSONL —
+ * neither `deriveInbox` (path A) nor `detectAwaitingUserQuestion` (path B)
+ * can see it. The only data source that reflects a live picker is the
+ * terminal output itself (the per-task `@xterm/headless` mirror).
+ *
+ * `extractTerminalPrompt` takes the decoded visible-viewport text (from
+ * `HeadlessMirror.getVisibleText()` via `PtyManager.peekTerminalText()`)
+ * and returns the picker block, or `null`.
+ *
+ * Hardening folded in from the iterate plan's external review:
+ *   - gemini-2 (zombie prompt): the footer MUST be the bottom-most
+ *     non-blank content. Once Claude exits and the shell prints a fresh
+ *     prompt below the (lingering) footer, the picker is stale → null.
+ *   - openai-10 (security): the captured block is bounded above by a
+ *     horizontal rule, a 2-blank-line gap, or a hard line cap, then
+ *     length-capped — so arbitrary scrollback above the picker cannot
+ *     leak into the inbox response.
+ *   - openai-5: footer matching is separator-agnostic + case-insensitive.
+ */
+import { MAX_QUESTION_TEXT_LEN } from "./inbox-derive.js";
+/** "Enter to select" cue — half of the strong footer signature. */
+const FOOTER_SELECT = /enter to select/i;
+/** "Esc to cancel" cue — the other half. Both required. */
+const FOOTER_CANCEL = /esc to cancel/i;
+/** Any footer-ish cue — used to recognise the (possibly wrapped) footer
+ *  line(s) at the bottom of the viewport. */
+const FOOTER_CUE = /tab\/arrow|to navigate|to cancel|to select/i;
+/** Hard cap on collected block lines — a real picker is well under this;
+ *  the cap bounds a pathological viewport. */
+const MAX_BLOCK_LINES = 24;
+/** Box-drawing (U+2500–U+257F) + ascii rule characters. */
+const RULE_CHAR = /[─-╿\-_=]/u;
+function isBlank(line) {
+    return line.trim().length === 0;
+}
+/** A horizontal-rule line — Claude Code renders one above the picker.
+ *  Used as the block's top boundary so preamble text never leaks in. */
+function isRuleLine(line) {
+    const t = line.trim();
+    if (t.length < 3)
+        return false;
+    let ruleCount = 0;
+    for (const ch of t) {
+        if (RULE_CHAR.test(ch))
+            ruleCount++;
+    }
+    return ruleCount / t.length >= 0.8;
+}
+/**
+ * Extract the waiting-picker block from decoded terminal viewport text.
+ * Returns the trimmed block (capped at `MAX_QUESTION_TEXT_LEN`) when a
+ * live `AskUserQuestion` picker is the bottom-most content, else `null`.
+ */
+export function extractTerminalPrompt(visibleText) {
+    if (!visibleText)
+        return null;
+    const lines = visibleText.split("\n");
+    // The footer MUST be the bottom-most non-blank line. A picker whose
+    // footer is no longer at the bottom (shell prompt printed below it,
+    // Claude exited) is stale — do not surface it (gemini-2).
+    let lastNonBlank = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (!isBlank(lines[i])) {
+            lastNonBlank = i;
+            break;
+        }
+    }
+    if (lastNonBlank === -1)
+        return null;
+    if (!FOOTER_CUE.test(lines[lastNonBlank]))
+        return null;
+    // Footer region = the contiguous footer-ish run ending at lastNonBlank
+    // (covers a footer wrapped across 2 lines on a narrow terminal). It
+    // must carry BOTH the "Enter to select" and "Esc to cancel" cues — a
+    // strong, separator-agnostic signature (openai-5).
+    let footerTop = lastNonBlank;
+    while (footerTop > 0 &&
+        !isBlank(lines[footerTop - 1]) &&
+        FOOTER_CUE.test(lines[footerTop - 1])) {
+        footerTop--;
+    }
+    const footerRegion = lines.slice(footerTop, lastNonBlank + 1).join(" ");
+    if (!FOOTER_SELECT.test(footerRegion) || !FOOTER_CANCEL.test(footerRegion)) {
+        return null;
+    }
+    // Collect the picker block upward from the footer. Bounded by a
+    // horizontal-rule line, a 2-blank-line gap, or the hard line cap so
+    // unrelated scrollback above the picker cannot leak in (openai-10).
+    const block = [];
+    let blankRun = 0;
+    for (let i = lastNonBlank; i >= 0 && block.length < MAX_BLOCK_LINES; i--) {
+        const line = lines[i];
+        if (isRuleLine(line))
+            break;
+        if (isBlank(line)) {
+            blankRun++;
+            if (blankRun >= 2)
+                break;
+        }
+        else {
+            blankRun = 0;
+        }
+        block.push(line);
+    }
+    block.reverse();
+    while (block.length > 0 && isBlank(block[0]))
+        block.shift();
+    while (block.length > 0 && isBlank(block[block.length - 1]))
+        block.pop();
+    if (block.length === 0)
+        return null;
+    const text = block.join("\n");
+    // Keep the head (question + options sit at the top of a picker block);
+    // a pathological over-long block loses only its trailing lines.
+    return text.length > MAX_QUESTION_TEXT_LEN
+        ? text.slice(0, MAX_QUESTION_TEXT_LEN)
+        : text;
+}
+//# sourceMappingURL=terminal-prompt-detect.js.map

package/server/dist/core/terminal-prompt-detect.js.map

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

package/server/dist/core/tests-gate.d.ts

@@ -0,0 +1,23 @@
+export interface TestsLike {
+    passed: number | null;
+    total: number | null;
+    skipped?: number | null;
+}
+export type GateState = "pass" | "fail" | "unknown";
+/**
+ * This run's landing instant — the second reversal. Mirrors D4's own
+ * `CONVENTION_EPOCH_MS` pattern exactly (compared as an instant via
+ * `Date.parse`, not lexically — this log carries a mix of `Z` and `+02:00`
+ * suffixes, which do not sort the same way as strings).
+ */
+export declare const REVERSAL_EPOCH_MS: number;
+/**
+ * `pass` / `fail` / `unknown` for one run's recorded tests. `unknown` when
+ * `total`/`passed` is absent, non-integer, negative, or `total <= 0` — the
+ * honest "nothing citable" signal, never a guess. A missing/unparseable/
+ * offset-less `ts` defaults to the OLD (pre-epoch) rule — the stricter,
+ * already-battle-tested one — so an ambiguous timestamp degrades toward
+ * caution, never a false `pass`.
+ */
+export declare function deriveTestsGate(tests: TestsLike | null, ts: string | null): GateState;
+//# sourceMappingURL=tests-gate.d.ts.map

package/server/dist/core/tests-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tests-gate.d.ts","sourceRoot":"","sources":["../../src/core/tests-gate.ts"],"names":[],"mappings":"AAqCA,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAqC,CAAC;AAqBpE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAqBrF"}

package/server/dist/core/tests-gate.js

@@ -0,0 +1,92 @@
+/*
+ * tests-gate.ts — the ONE place a `work_completed` run's recorded test counts
+ * turn into a pass/fail/unknown verdict (iterate-2026-08-08-tests-total-skip-contract).
+ *
+ * Two repos disagree about what `tests.total` means: this project's D4
+ * ratchet (`event-test-counts-executed.test.ts`) historically required
+ * `total` = tests that EXECUTED (passed + failed), `skipped` tracked apart;
+ * the monorepo that actually WRITES these events (`record_event.py` /
+ * `tests_block.py`, P2.05, already shipped) uses the opposite: `total` =
+ * tests COLLECTED (passed + failed + skipped). Decision: this project adopts
+ * the monorepo's convention going forward (see the iterate spec's
+ * `## Decision` section) — it is the sole writer for every Shipwright-managed
+ * project, not just this one.
+ *
+ * REVERSAL_EPOCH_MS is a SECOND cutover, layered on the ratchet's existing
+ * first one (`CONVENTION_EPOCH_MS`, 2026-07-21): events dated before it keep
+ * being read under the OLD rule (`passed === total`, `skipped` ignored for
+ * the verdict); events at/after it use the NEW rule (`passed + skipped ===
+ * total`). Both branches are PERMANENT — old events are immutable and must
+ * keep reading correctly forever, this is not a migration shim to delete
+ * later.
+ *
+ * WHY AN EPOCH, NOT A PERMANENT "EITHER CONVENTION" CHECK. A pure
+ * `passed === total || passed + skipped === total` cannot distinguish an
+ * OLD-convention run that has a genuine failure whose count happens to equal
+ * its `skipped` value (`passed:99, total:100, skipped:1` meant "1 real
+ * failure, 1 separately-tracked skip" under the old rule) from a NEW
+ * -convention genuinely green run with the identical numbers (100 collected,
+ * 0 failures). Caught by external plan review (openai, both the plan pass
+ * and the architecture pass) — verified: this project's own Iron Law means a
+ * real failure was never actually finalized under the old rule, so the
+ * collision has never occurred in this log, but the ratchet's job is to hold
+ * even for an event this project did not itself write, so the ambiguity is a
+ * real soundness gap, not a cosmetic one. The epoch removes it structurally:
+ * an event is judged by exactly ONE rule, never both.
+ */
+/**
+ * This run's landing instant — the second reversal. Mirrors D4's own
+ * `CONVENTION_EPOCH_MS` pattern exactly (compared as an instant via
+ * `Date.parse`, not lexically — this log carries a mix of `Z` and `+02:00`
+ * suffixes, which do not sort the same way as strings).
+ */
+export const REVERSAL_EPOCH_MS = Date.parse("2026-08-08T00:00:00Z");
+/** A non-negative integer, else `null` — rejects a negative/float/NaN value
+ *  rather than letting it participate in the arithmetic (a negative
+ *  `skipped` could otherwise forge a `pass` out of a real shortfall). */
+function normalizedCount(v) {
+    return Number.isInteger(v) && v >= 0 ? v : null;
+}
+/** An explicit UTC/offset suffix (`Z` or `±HH:MM`/`±HHMM`) — bare
+ *  `Date.parse` treats an offset-LESS date-time string as host-LOCAL time
+ *  (ECMA-262 Date Time String Format), which would make the epoch verdict
+ *  depend on the machine running the check rather than the event itself
+ *  (doubt review, LOW-MEDIUM: `"2026-08-08T01:00:00"` parses `pass` in UTC
+ *  and `fail` in Europe/Zurich for the same event). This log's real `ts`
+ *  values always carry one; an offset-less string is treated the same as an
+ *  unparseable one, below. */
+function hasExplicitOffset(ts) {
+    return /(?:[Zz]|[+-]\d{2}:?\d{2})$/.test(ts);
+}
+/**
+ * `pass` / `fail` / `unknown` for one run's recorded tests. `unknown` when
+ * `total`/`passed` is absent, non-integer, negative, or `total <= 0` — the
+ * honest "nothing citable" signal, never a guess. A missing/unparseable/
+ * offset-less `ts` defaults to the OLD (pre-epoch) rule — the stricter,
+ * already-battle-tested one — so an ambiguous timestamp degrades toward
+ * caution, never a false `pass`.
+ */
+export function deriveTestsGate(tests, ts) {
+    if (tests == null)
+        return "unknown";
+    const passed = normalizedCount(tests.passed);
+    const total = normalizedCount(tests.total);
+    if (passed == null || total == null || total <= 0)
+        return "unknown";
+    const tsMs = ts && hasExplicitOffset(ts) ? Date.parse(ts) : NaN;
+    const isPostReversal = Number.isFinite(tsMs) && tsMs >= REVERSAL_EPOCH_MS;
+    if (isPostReversal) {
+        const skip = normalizedCount(tests.skipped) ?? 0;
+        // `executed = total - skip`. A run where EVERY collected test was
+        // skipped (`executed <= 0`) satisfies `passed + skip === total`
+        // vacuously (0 + total === total) without a single test having run — the
+        // same "nothing citable" gap `total <= 0` above exists to catch, reopened
+        // one level down by the reversal (code review, MEDIUM: a false ALL CLEAR
+        // is the one thing this predicate must never produce).
+        if (total - skip <= 0)
+            return "unknown";
+        return passed + skip === total ? "pass" : "fail";
+    }
+    return passed === total ? "pass" : "fail";
+}
+//# sourceMappingURL=tests-gate.js.map

package/server/dist/core/tests-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tests-gate.js","sourceRoot":"","sources":["../../src/core/tests-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAUH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;AAEpE;;yEAEyE;AACzE,SAAS,eAAe,CAAC,CAAU;IACjC,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAK,CAAY,IAAI,CAAC,CAAC,CAAC,CAAE,CAAY,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1E,CAAC;AAED;;;;;;;8BAO8B;AAC9B,SAAS,iBAAiB,CAAC,EAAU;IACnC,OAAO,4BAA4B,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAuB,EAAE,EAAiB;IACxE,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IACpC,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,MAAM,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAEpE,MAAM,IAAI,GAAG,EAAE,IAAI,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAChE,MAAM,cAAc,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,iBAAiB,CAAC;IAE1E,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjD,kEAAkE;QAClE,gEAAgE;QAChE,yEAAyE;QACzE,0EAA0E;QAC1E,yEAAyE;QACzE,uDAAuD;QACvD,IAAI,KAAK,GAAG,IAAI,IAAI,CAAC;YAAE,OAAO,SAAS,CAAC;QACxC,OAAO,MAAM,GAAG,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IACnD,CAAC;IACD,OAAO,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AAC5C,CAAC"}