wotann 0.5.0

package/dist/utils/marker-polling.d.ts

@@ -0,0 +1,216 @@
+/**
+ * marker-polling — Terminus-KIRA-style unique-marker command wrapping +
+ * double-confirmation polling for streaming shell output.
+ *
+ * The "fabricated success" problem on long-running agents:
+ *
+ *   1. Agent invokes `./run-tests.sh` which prints "running..." then takes 30s.
+ *   2. Harness reads the first chunk ("running..."), sees non-empty output,
+ *      returns it to the agent as "the command completed".
+ *   3. Agent claims the task is done — before the tests actually finished.
+ *
+ * Terminus-KIRA's fix: append a unique sentinel echo after the command and
+ * poll the output stream until the sentinel appears. Only then is the command
+ * actually finished from the harness's perspective. A "double-confirm" window
+ * of ~100 ms after the marker catches any trailing bytes that the OS might
+ * flush slightly after the sentinel print.
+ *
+ * This module is a pure utility:
+ *   - {@link markerWrap} returns `{ cmdWithMarker, marker }`
+ *   - {@link stripMarker} removes the marker line(s) from output
+ *   - {@link findMarker} locates the marker boundary in a buffer
+ *   - {@link pollForMarker} reads chunks from an `AsyncIterable<string>` until
+ *      the marker is seen or a timeout fires, then does a short double-confirm
+ *      read to collect trailing bytes
+ *
+ * Integration sites (callers that stream stdout) wrap the user-supplied
+ * command with {@link markerWrap}, feed the stream through
+ * {@link pollForMarker}, and surface the polled result. The module is backend-
+ * agnostic so it works for local spawn(), docker exec, SSH pipelines, PTY
+ * attaches — any source that yields text chunks.
+ *
+ * Honest-failure posture: if the timeout fires before the marker is seen, the
+ * result carries `done: false, timedOut: true`. Callers MUST NOT treat
+ * `timedOut: true` as success — bar #14 of the WOTANN quality bars applies
+ * (commit messages/claims need runtime evidence, not optimistic shortcuts).
+ *
+ * Phase-2 port, MASTER_PLAN_V8 §5 P1-B3. Expected TerminalBench 2.0 delta:
+ * +2–3 pp on tasks where premature stream-read was the failure mode.
+ */
+/**
+ * Options for {@link markerWrap}. `uuid` lets callers inject a deterministic
+ * identifier (tests, same-session multiple-run scenarios). When omitted a
+ * fresh UUIDv4 is generated per call so two parallel commands never share a
+ * marker.
+ */
+export interface MarkerWrapOptions {
+    /** Optional pre-built unique id. When omitted, a UUIDv4 is generated. */
+    readonly uuid?: string;
+    /** Optional session-scoped salt folded into the marker for cross-session
+     *  disambiguation. Not a security boundary — defensive only. */
+    readonly sessionId?: string;
+}
+export interface MarkerWrapResult {
+    /** The original command plus the trailing marker echo. */
+    readonly cmdWithMarker: string;
+    /** The exact marker string that will appear on stdout once the wrapped
+     *  command completes. Callers poll the stream for this. */
+    readonly marker: string;
+    /** Regex-safe form for callers that want to match with boundaries. */
+    readonly markerRegex: RegExp;
+}
+/**
+ * Options for {@link pollForMarker}. Keeping both poll-interval and timeout
+ * honest: timeouts must fire and must be reported as {@link PollResult.timedOut}
+ * = true — never silently coerced into success.
+ */
+export interface PollOptions {
+    /** Total wall-clock budget before giving up. Default 30 s. */
+    readonly timeoutMs?: number;
+    /** Sleep between reads when the source has no pending data.
+     *  Smaller = more CPU, larger = more tail latency. Default 25 ms. */
+    readonly pollIntervalMs?: number;
+    /** How long to keep draining after the marker is first seen so trailing
+     *  bytes are captured. Default 100 ms (Terminus-KIRA value). */
+    readonly doubleConfirmMs?: number;
+    /** Optional AbortSignal for external cancellation. */
+    readonly signal?: AbortSignal;
+}
+export interface PollResult {
+    /** Everything the stream emitted before the marker, verbatim — stripped of
+     *  the marker itself and any trailing bytes collected during the double-
+     *  confirm window. Callers see exactly what the command produced. */
+    readonly output: string;
+    /** True when the marker was observed AND the double-confirm window drained.
+     *  False when the timeout fired first — caller must treat the result as
+     *  incomplete and MUST NOT claim success. */
+    readonly done: boolean;
+    /** True if the timeout fired before the marker was seen. Mutually exclusive
+     *  with done=true. */
+    readonly timedOut: boolean;
+    /** Bytes collected during the post-marker double-confirm window. Separate
+     *  from output so observability callers can tell how much the marker slid.
+     *  Zero-length when no trailing bytes arrived — still populated for
+     *  consistent shape. */
+    readonly trailing: string;
+}
+/**
+ * Error thrown (at the caller's option) when a poll completes without seeing
+ * the marker. Most callers should prefer the result-object form (PollResult)
+ * and branch on `timedOut`, but some code paths want a throwable for error
+ * propagation.
+ */
+export declare class TimedOutWithoutMarker extends Error {
+    readonly marker: string;
+    readonly partialOutput: string;
+    readonly timeoutMs: number;
+    readonly timedOutWithoutMarker: true;
+    constructor(marker: string, partialOutput: string, timeoutMs: number);
+}
+/**
+ * Wraps a shell command with a trailing marker echo so callers can detect
+ * true completion from a streaming output. The marker is printed on its own
+ * line via `printf` with a leading newline (`\n__CMD_DONE_<uuid>__\n`) so
+ * partial mid-line output from the wrapped command never gets concatenated
+ * with the marker string.
+ *
+ * Important safety notes:
+ *   - We use `; printf '\\n%s\\n' '<marker>'` (NOT `&&`) so the marker is
+ *     emitted regardless of the wrapped command's exit status. Otherwise a
+ *     failing command's "completion" would never be detected and we'd time
+ *     out with partial output — defeating the whole point.
+ *   - The marker is single-quoted so shell metacharacters in the UUID (none
+ *     in practice, but the sessionId salt is caller-supplied) can't escape.
+ *   - Even though `printf` is a POSIX shell built-in, we prefer it over
+ *     `echo` because `echo`'s handling of backslashes and `-n` is portable-
+ *     ly inconsistent across `sh` implementations. `printf '\\n%s\\n'`
+ *     prints exactly one newline before and one after the marker.
+ *
+ * @param command  User-supplied shell command (may contain any pipes/redirs).
+ * @param options  Optional marker customization.
+ * @returns `{ cmdWithMarker, marker, markerRegex }`.
+ */
+export declare function markerWrap(command: string, options?: MarkerWrapOptions): MarkerWrapResult;
+export interface FindMarkerResult {
+    readonly index: number;
+    readonly endIndex: number;
+    readonly found: boolean;
+}
+/**
+ * Locate the marker within a buffer. Returns the index of the first byte of
+ * the marker and the exclusive end (first byte AFTER the marker).
+ *
+ * Callers use the pair to split `before = buf.slice(0, index)` and
+ * `trailing = buf.slice(endIndex)` without rebuilding.
+ */
+export declare function findMarker(buffer: string, marker: string): FindMarkerResult;
+/**
+ * Strip the marker line from `buffer` and return the output the command
+ * actually emitted. Also strips the single newline we inserted right before
+ * the marker so the output looks exactly like it would without marker-wrap.
+ *
+ * If the marker is not present, returns the buffer unchanged.
+ */
+export declare function stripMarker(buffer: string, marker: string): string;
+/**
+ * A minimal async chunk source. Any shape matching this can be polled.
+ * Implementations yield string chunks; empty string signals "no data yet,
+ * caller should wait before asking again".
+ */
+export interface ChunkSource {
+    /**
+     * Read whatever is currently buffered. Must return synchronously (sync
+     * sources are expected to buffer between calls and drain on read). Async
+     * sources should resolve immediately with whatever has arrived — the poll
+     * loop handles waiting.
+     */
+    read(): Promise<string> | string;
+    /** Called once when polling gives up (timeout or marker seen).
+     *  Use to clean up subscriptions, timers, file handles. */
+    close?(): Promise<void> | void;
+}
+/**
+ * Poll the source until the marker appears, then run a double-confirm window
+ * collecting trailing bytes. Returns {@link PollResult} — honest timeout is
+ * reported as `{ done: false, timedOut: true }`, never silently as success.
+ *
+ * Implementation notes:
+ *   - We use setTimeout-based sleeps rather than a fixed-interval loop so
+ *     cancellation via `signal` is immediate.
+ *   - We never mutate the input source state; buffering happens in `acc`.
+ *   - The double-confirm phase uses the same pollInterval as the main phase
+ *     for consistency.
+ */
+export declare function pollForMarker(source: ChunkSource, marker: string, options?: PollOptions): Promise<PollResult>;
+/**
+ * Convenience helper: run a command via {@link markerWrap} + spawn() and poll
+ * the stdout stream until the marker is seen. Returns `{ output, stderr,
+ * exitCode, timedOut }`.
+ *
+ * This is the integration point for backends that want drop-in marker-backed
+ * exec. Existing exec paths (e.g. `terminal-backends.LocalBackend.execute`)
+ * can opt in by calling this when the caller passes `{ useMarker: true }`.
+ *
+ * Kept separate from the existing `LocalBackend.execute` to preserve its
+ * public API. Callers choose marker mode explicitly.
+ */
+export interface SpawnWithMarkerOptions {
+    readonly cwd?: string;
+    readonly env?: Record<string, string>;
+    readonly timeoutMs?: number;
+    readonly doubleConfirmMs?: number;
+    readonly pollIntervalMs?: number;
+    readonly shell?: string;
+    readonly sessionId?: string;
+}
+export interface SpawnWithMarkerResult {
+    readonly output: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+    readonly timedOut: boolean;
+    readonly done: boolean;
+    readonly trailing: string;
+    readonly marker: string;
+}
+export declare function spawnWithMarker(command: string, options?: SpawnWithMarkerOptions): Promise<SpawnWithMarkerResult>;
+//# sourceMappingURL=marker-polling.d.ts.map

package/dist/utils/marker-polling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker-polling.d.ts","sourceRoot":"","sources":["../../src/utils/marker-polling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAMH;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;oEACgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;+DAC2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;yEACqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;oEACgE;IAChE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB;;yEAEqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;iDAE6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB;0BACsB;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;4BAGwB;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAG5B,MAAM,EAAE,MAAM;aACd,aAAa,EAAE,MAAM;aACrB,SAAS,EAAE,MAAM;IAJnC,QAAQ,CAAC,qBAAqB,EAAG,IAAI,CAAU;gBAE7B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM;CAOpC;AAID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAY7F;AAoBD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAI3E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAWlE;AAID;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACjC;+DAC2D;IAC3D,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CAyErB;AA8BD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC,CAuEhC"}

package/dist/utils/marker-polling.js

@@ -0,0 +1,324 @@
+/**
+ * marker-polling — Terminus-KIRA-style unique-marker command wrapping +
+ * double-confirmation polling for streaming shell output.
+ *
+ * The "fabricated success" problem on long-running agents:
+ *
+ *   1. Agent invokes `./run-tests.sh` which prints "running..." then takes 30s.
+ *   2. Harness reads the first chunk ("running..."), sees non-empty output,
+ *      returns it to the agent as "the command completed".
+ *   3. Agent claims the task is done — before the tests actually finished.
+ *
+ * Terminus-KIRA's fix: append a unique sentinel echo after the command and
+ * poll the output stream until the sentinel appears. Only then is the command
+ * actually finished from the harness's perspective. A "double-confirm" window
+ * of ~100 ms after the marker catches any trailing bytes that the OS might
+ * flush slightly after the sentinel print.
+ *
+ * This module is a pure utility:
+ *   - {@link markerWrap} returns `{ cmdWithMarker, marker }`
+ *   - {@link stripMarker} removes the marker line(s) from output
+ *   - {@link findMarker} locates the marker boundary in a buffer
+ *   - {@link pollForMarker} reads chunks from an `AsyncIterable<string>` until
+ *      the marker is seen or a timeout fires, then does a short double-confirm
+ *      read to collect trailing bytes
+ *
+ * Integration sites (callers that stream stdout) wrap the user-supplied
+ * command with {@link markerWrap}, feed the stream through
+ * {@link pollForMarker}, and surface the polled result. The module is backend-
+ * agnostic so it works for local spawn(), docker exec, SSH pipelines, PTY
+ * attaches — any source that yields text chunks.
+ *
+ * Honest-failure posture: if the timeout fires before the marker is seen, the
+ * result carries `done: false, timedOut: true`. Callers MUST NOT treat
+ * `timedOut: true` as success — bar #14 of the WOTANN quality bars applies
+ * (commit messages/claims need runtime evidence, not optimistic shortcuts).
+ *
+ * Phase-2 port, MASTER_PLAN_V8 §5 P1-B3. Expected TerminalBench 2.0 delta:
+ * +2–3 pp on tasks where premature stream-read was the failure mode.
+ */
+import { randomUUID } from "node:crypto";
+/**
+ * Error thrown (at the caller's option) when a poll completes without seeing
+ * the marker. Most callers should prefer the result-object form (PollResult)
+ * and branch on `timedOut`, but some code paths want a throwable for error
+ * propagation.
+ */
+export class TimedOutWithoutMarker extends Error {
+    marker;
+    partialOutput;
+    timeoutMs;
+    timedOutWithoutMarker = true;
+    constructor(marker, partialOutput, timeoutMs) {
+        super(`marker-polling timed out after ${String(timeoutMs)}ms without seeing marker "${marker}" (got ${String(partialOutput.length)} bytes)`);
+        this.marker = marker;
+        this.partialOutput = partialOutput;
+        this.timeoutMs = timeoutMs;
+        this.name = "TimedOutWithoutMarker";
+    }
+}
+// ── markerWrap ────────────────────────────────────────
+/**
+ * Wraps a shell command with a trailing marker echo so callers can detect
+ * true completion from a streaming output. The marker is printed on its own
+ * line via `printf` with a leading newline (`\n__CMD_DONE_<uuid>__\n`) so
+ * partial mid-line output from the wrapped command never gets concatenated
+ * with the marker string.
+ *
+ * Important safety notes:
+ *   - We use `; printf '\\n%s\\n' '<marker>'` (NOT `&&`) so the marker is
+ *     emitted regardless of the wrapped command's exit status. Otherwise a
+ *     failing command's "completion" would never be detected and we'd time
+ *     out with partial output — defeating the whole point.
+ *   - The marker is single-quoted so shell metacharacters in the UUID (none
+ *     in practice, but the sessionId salt is caller-supplied) can't escape.
+ *   - Even though `printf` is a POSIX shell built-in, we prefer it over
+ *     `echo` because `echo`'s handling of backslashes and `-n` is portable-
+ *     ly inconsistent across `sh` implementations. `printf '\\n%s\\n'`
+ *     prints exactly one newline before and one after the marker.
+ *
+ * @param command  User-supplied shell command (may contain any pipes/redirs).
+ * @param options  Optional marker customization.
+ * @returns `{ cmdWithMarker, marker, markerRegex }`.
+ */
+export function markerWrap(command, options = {}) {
+    const uuid = options.uuid ?? randomUUID();
+    const salt = options.sessionId ? `_${sanitizeSalt(options.sessionId)}` : "";
+    const marker = `__CMD_DONE_${uuid}${salt}__`;
+    // Refuse to proceed if someone passes a pathological `uuid` that would
+    // break the single-quoted printf. We only accept hex/dash/underscore.
+    if (!/^[A-Za-z0-9_-]+$/.test(marker)) {
+        throw new Error(`marker-polling: marker "${marker}" contains disallowed chars`);
+    }
+    const cmdWithMarker = `${command}; printf '\\n%s\\n' '${marker}'`;
+    const markerRegex = new RegExp(escapeRegex(marker));
+    return { cmdWithMarker, marker, markerRegex };
+}
+/**
+ * Restrict session-id salt characters so that even an adversarial sessionId
+ * can't escape the single-quoted marker or introduce shell metacharacters.
+ * Non-matching chars are dropped (not escaped) because the salt is purely
+ * advisory disambiguation — losing a few chars doesn't change correctness.
+ */
+function sanitizeSalt(input) {
+    return input.replace(/[^A-Za-z0-9]/g, "").slice(0, 32);
+}
+function escapeRegex(input) {
+    // UUIDs and our marker format never include special regex chars, but
+    // callers may pass sessionId derivatives — be defensive.
+    return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Locate the marker within a buffer. Returns the index of the first byte of
+ * the marker and the exclusive end (first byte AFTER the marker).
+ *
+ * Callers use the pair to split `before = buf.slice(0, index)` and
+ * `trailing = buf.slice(endIndex)` without rebuilding.
+ */
+export function findMarker(buffer, marker) {
+    const idx = buffer.indexOf(marker);
+    if (idx < 0)
+        return { index: -1, endIndex: -1, found: false };
+    return { index: idx, endIndex: idx + marker.length, found: true };
+}
+/**
+ * Strip the marker line from `buffer` and return the output the command
+ * actually emitted. Also strips the single newline we inserted right before
+ * the marker so the output looks exactly like it would without marker-wrap.
+ *
+ * If the marker is not present, returns the buffer unchanged.
+ */
+export function stripMarker(buffer, marker) {
+    const loc = findMarker(buffer, marker);
+    if (!loc.found)
+        return buffer;
+    // The prefix convention from markerWrap() is `\n<marker>\n`. Trim the
+    // newline(s) immediately bordering the marker, but only if present — we
+    // never over-trim user content.
+    let startCut = loc.index;
+    if (startCut > 0 && buffer.charAt(startCut - 1) === "\n")
+        startCut -= 1;
+    const before = buffer.slice(0, startCut);
+    const after = loc.endIndex < buffer.length ? buffer.slice(loc.endIndex).replace(/^\n/, "") : "";
+    return before + after;
+}
+/**
+ * Poll the source until the marker appears, then run a double-confirm window
+ * collecting trailing bytes. Returns {@link PollResult} — honest timeout is
+ * reported as `{ done: false, timedOut: true }`, never silently as success.
+ *
+ * Implementation notes:
+ *   - We use setTimeout-based sleeps rather than a fixed-interval loop so
+ *     cancellation via `signal` is immediate.
+ *   - We never mutate the input source state; buffering happens in `acc`.
+ *   - The double-confirm phase uses the same pollInterval as the main phase
+ *     for consistency.
+ */
+export async function pollForMarker(source, marker, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const pollIntervalMs = options.pollIntervalMs ?? 25;
+    const doubleConfirmMs = options.doubleConfirmMs ?? 100;
+    const signal = options.signal;
+    const start = Date.now();
+    let acc = "";
+    let markerSeen = false;
+    let markerIndex = -1;
+    try {
+        // Phase 1: read until marker or timeout
+        while (!markerSeen) {
+            if (signal?.aborted) {
+                return buildTimedOut(acc, marker, "aborted");
+            }
+            const elapsed = Date.now() - start;
+            if (elapsed >= timeoutMs) {
+                return buildTimedOut(acc, marker, "timeout");
+            }
+            const chunk = await source.read();
+            if (chunk) {
+                acc += chunk;
+                const loc = findMarker(acc, marker);
+                if (loc.found) {
+                    markerSeen = true;
+                    markerIndex = loc.index;
+                    break;
+                }
+            }
+            if (!markerSeen) {
+                await sleep(pollIntervalMs, signal);
+            }
+        }
+        // Phase 2: double-confirm — keep draining for doubleConfirmMs to catch
+        // trailing bytes. We still respect the outer timeout.
+        const dcStart = Date.now();
+        while (Date.now() - dcStart < doubleConfirmMs) {
+            if (signal?.aborted)
+                break;
+            const elapsed = Date.now() - start;
+            if (elapsed >= timeoutMs)
+                break;
+            const chunk = await source.read();
+            if (chunk)
+                acc += chunk;
+            await sleep(pollIntervalMs, signal);
+        }
+        const loc = findMarker(acc, marker);
+        const effectiveIndex = loc.found ? loc.index : markerIndex;
+        const effectiveEnd = loc.found ? loc.endIndex : markerIndex + marker.length;
+        // Trim the newline we inserted immediately before the marker, if any.
+        let beforeCut = effectiveIndex;
+        if (beforeCut > 0 && acc.charAt(beforeCut - 1) === "\n")
+            beforeCut -= 1;
+        const before = acc.slice(0, beforeCut);
+        const trailing = effectiveEnd < acc.length ? acc.slice(effectiveEnd).replace(/^\n/, "") : "";
+        return {
+            output: before,
+            done: true,
+            timedOut: false,
+            trailing,
+        };
+    }
+    finally {
+        if (source.close) {
+            try {
+                await source.close();
+            }
+            catch {
+                // Cleanup errors are non-fatal for poll callers — we've already
+                // captured whatever they need. Surfacing would mask the real
+                // poll result.
+            }
+        }
+    }
+}
+function buildTimedOut(acc, _marker, _reason) {
+    return {
+        output: acc,
+        done: false,
+        timedOut: true,
+        trailing: "",
+    };
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const t = setTimeout(() => {
+            if (signal && abortListener)
+                signal.removeEventListener("abort", abortListener);
+            resolve();
+        }, ms);
+        let abortListener;
+        if (signal) {
+            abortListener = () => {
+                clearTimeout(t);
+                resolve();
+            };
+            signal.addEventListener("abort", abortListener, { once: true });
+        }
+    });
+}
+export async function spawnWithMarker(command, options = {}) {
+    // Late import to keep the pure-utility layer above free of node:spawn so
+    // it can be tree-shaken for environments that don't need the integration.
+    const { spawn } = await import("node:child_process");
+    const { cmdWithMarker, marker } = markerWrap(command, {
+        sessionId: options.sessionId,
+    });
+    const shell = options.shell ?? "/bin/sh";
+    const child = spawn(shell, ["-c", cmdWithMarker], {
+        cwd: options.cwd,
+        env: options.env ? { ...process.env, ...options.env } : undefined,
+    });
+    let stderrBuf = "";
+    let stdoutBuf = "";
+    let exitCode = 0;
+    let exited = false;
+    child.stdout.on("data", (chunk) => {
+        stdoutBuf += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+        stderrBuf += chunk.toString();
+    });
+    child.on("close", (code) => {
+        exited = true;
+        exitCode = typeof code === "number" ? code : exitCode;
+    });
+    child.on("error", () => {
+        exited = true;
+        exitCode = exitCode || 1;
+    });
+    const source = {
+        read() {
+            // Snapshot current buffer and consume it — next read returns only
+            // bytes that arrived since the last read. This gives pollForMarker
+            // a clean incremental view without duplicate bytes in `acc`.
+            const out = stdoutBuf;
+            stdoutBuf = "";
+            return out;
+        },
+        async close() {
+            if (!exited) {
+                child.kill("SIGTERM");
+            }
+        },
+    };
+    const polled = await pollForMarker(source, marker, {
+        timeoutMs: options.timeoutMs,
+        pollIntervalMs: options.pollIntervalMs,
+        doubleConfirmMs: options.doubleConfirmMs,
+    });
+    // Wait briefly for the child to reap (exit code is advisory once the
+    // marker was seen — by design marker echo runs after the user command
+    // regardless of exit status).
+    if (!exited) {
+        await Promise.race([new Promise((res) => child.once("close", () => res())), sleep(50)]);
+    }
+    return {
+        output: polled.output,
+        stderr: stderrBuf,
+        exitCode,
+        timedOut: polled.timedOut,
+        done: polled.done,
+        trailing: polled.trailing,
+        marker,
+    };
+}
+//# sourceMappingURL=marker-polling.js.map

package/dist/utils/marker-polling.js.map

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

package/dist/utils/path-realpath.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Path realpath/symlink defence helpers — Wave 3-S.
+ *
+ * Closes inherited Claude Code CVE classes:
+ *   - CVE-2026-25724: deny-list bypass via symlink. Pure path.resolve is
+ *     lexical only; `safe.txt` symlinked to `../../../package.json` evades
+ *     any matcher that checks the raw user-supplied path. The fix is to
+ *     resolve through realpath BEFORE matching, so the canonical target is
+ *     what the matcher sees.
+ *   - CVE-2026-39861: symlink sandbox-escape on write. `writeFileSync`
+ *     follows existing symlinks at the leaf, so an attacker who
+ *     pre-creates `harmless.txt` as a symlink to `~/.ssh/authorized_keys`
+ *     gets us to write through to the target. Wrap writes with O_NOFOLLOW
+ *     (POSIX) or an explicit lstat precheck (cross-platform fallback).
+ *
+ * This module is stateless. Every helper is pure: input -> output, no
+ * shared globals, no caches. Designed for defence-in-depth — the caller
+ * keeps its existing matcher AND consults this helper, so a bug in either
+ * layer alone does not open the gate.
+ */
+import { type WriteFileOptions } from "node:fs";
+/**
+ * Resolve `p` through every symlink in its prefix and return the canonical
+ * absolute path. ENOENT-safe: when the leaf does not exist, walk up the
+ * parent chain until we hit a real ancestor, realpath() that ancestor,
+ * then re-append the unresolved tail. This mirrors the
+ * `canonicalizeExistingPrefix` pattern already used in
+ * src/tools/hashline-edits.ts so the two callers cannot disagree about
+ * what "canonical" means.
+ *
+ * Used by deny-list matchers (file-freeze, secret-scanner, sensitive
+ * file regex, command sanitizer) to ensure they evaluate the REAL
+ * target, not the lexically-resolved input.
+ *
+ * Defensive: on any unexpected failure we return the lexically-resolved
+ * path. Callers should treat a "differs from raw" canonical as a strong
+ * signal — when in doubt, BLOCK (QB#6 honest fallback: better to refuse
+ * a legit write than approve a malicious one).
+ */
+export declare function canonicalizePathForCheck(p: string): string;
+/**
+ * Throw if `path` exists AND is a symlink. Used as defence-in-depth
+ * alongside `canonicalizePathForCheck` and `safeWriteFile` — even if
+ * one layer mis-resolves, this layer refuses to operate on a symlink
+ * leaf.
+ *
+ * NON-existing paths pass silently. The caller is presumed to be about
+ * to create a fresh file; the write itself is what `safeWriteFile`
+ * guards.
+ */
+export declare function assertNotSymlink(path: string): void;
+export interface SafeWriteOptions {
+    /** File mode for newly-created files. Default: 0o644. */
+    readonly mode?: number;
+}
+/**
+ * Write `content` to `path` with symlink-following defence. On POSIX the
+ * underlying open() is called with O_WRONLY | O_CREAT | O_TRUNC |
+ * O_NOFOLLOW so a pre-existing symlink at the leaf causes the syscall to
+ * fail with ELOOP rather than silently overwrite the symlink target. On
+ * platforms without O_NOFOLLOW (Windows) we fall back to an lstat
+ * precheck — race-prone but better than nothing.
+ *
+ * Parent directories must already exist; this helper does NOT mkdir.
+ * Callers that need recursive directory creation should call mkdirSync
+ * explicitly first (and then this helper).
+ *
+ * Behaviour matches `writeFileSync(path, content)` for happy-path:
+ * truncate-or-create, write all of content, close. On failure throws
+ * the underlying syscall error.
+ */
+export declare function safeWriteFile(path: string, content: string | Buffer, options?: SafeWriteOptions): void;
+/**
+ * Convenience: writeFileSync-shaped wrapper that accepts the same
+ * `WriteFileOptions` shape (encoding/mode/flag) some legacy call sites
+ * pass. Encoding is honoured for string inputs; mode is honoured for
+ * new file creation; the `flag` field is IGNORED — symlink refusal is
+ * non-negotiable in this helper.
+ */
+export declare function safeWriteFileCompat(path: string, content: string | Buffer, options?: WriteFileOptions): void;
+//# sourceMappingURL=path-realpath.d.ts.map

package/dist/utils/path-realpath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-realpath.d.ts","sourceRoot":"","sources":["../../src/utils/path-realpath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAQL,KAAK,gBAAgB,EACtB,MAAM,SAAS,CAAC;AAKjB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAO1D;AAoCD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAiBnD;AAwBD,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,gBAAqB,GAC7B,IAAI,CA2CN;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAON"}