@specific.dev/spectest 0.127.0 → 0.129.0

package/dist/index.js

@@ -41,7 +41,7 @@ export { McpHttpError, McpRpcError, McpAuthDeniedError, } from "./mcp.js";
 import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, } from "./locator.js";
 import { escapeInvisible, textDifferenceNote, } from "./text-match.js";
 import { describeUrlPattern } from "./url-match.js";
-import { applyCoverageAdapters, validateCoverage } from "./coverage.js";
+import { applyCoverageAdapters, coverageAdapters, validateCoverage } from "./coverage.js";
 import { resolveExistingProjectPath } from "./project-files.js";
 export { ca } from "./environment-ca.js";
 // Low-level ingress primitives + the framework lowering that the friendly
@@ -185,6 +185,15 @@ function expandServiceGroups(input) {
             // Rewrite relative dependsOn to final keys; a spread keeps function
             // fields (helpers/setup) and the enumerable-symbol ingress decls.
             const final = { ...svc, ...(part === entry.primary ? primaryOverrides : {}) };
+            // Component-owned nested containers keep their collection when callers
+            // add ordinary service coverage (for example browser coverage on k3s).
+            const collectors = coverageAdapters(svc.coverage).filter(adapter => adapter.collect);
+            if (part === entry.primary && collectors.length && primaryOverrides.coverage !== undefined) {
+                const extra = primaryOverrides.coverage;
+                final.coverage = { ...(typeof extra === "object" ? extra : {}), adapters: [
+                        ...collectors, ...coverageAdapters(extra).filter(adapter => !collectors.includes(adapter)),
+                    ] };
+            }
             if (final.dependsOn?.length) {
                 final.dependsOn = final.dependsOn.map((d) => partKeys.has(d) ? naming.key(d) : d);
             }

package/dist/recorder.d.ts

@@ -407,6 +407,9 @@ export interface RecordedBrowserLocatorPart {
 }
 export interface BrowserEvent extends BaseEvent {
     kind: "browser";
+    /** Explicit navigation options, when supplied by the test. */
+    timeout?: number;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
     action: BrowserAction;
     target?: RecordedBrowserLocatorPart[];
     destinationTarget?: RecordedBrowserLocatorPart[];
@@ -534,6 +537,18 @@ export interface TerminalEvent extends BaseEvent {
 }
 /** Action taken on an open interactive terminal session. */
 export type TerminalStepAction = "send" | "sendLine" | "press" | "waitFor" | "exit" | "close";
+export type TerminalWaitMatcher = {
+    kind: "text";
+    value: string;
+} | {
+    kind: "regex";
+    value: string;
+    flags: string;
+} | {
+    kind: "custom";
+    description?: string;
+};
+export type TerminalWaitOutcome = "matched" | "timed_out" | "failure_matched" | "predicate_error" | "process_exited" | "cancelled";
 /**
  * One operation on an open interactive terminal — analogous to
  * `BrowserEvent`. The session's heavy asciicast frames live on the
@@ -557,9 +572,21 @@ export interface TerminalStepEvent extends BaseEvent {
     description?: string;
     /** How many polls `waitFor` made. */
     attempts?: number;
-    /** Whether `waitFor` matched (false means it timed out). */
+    /** Whether `waitFor` matched; see outcome for failure reasons. */
     matched?: boolean;
-    /** Exit code observed on `close`. */
+    /** The condition being observed, including an optional custom-predicate description. */
+    matcher?: TerminalWaitMatcher;
+    outcome?: TerminalWaitOutcome;
+    failureMatchers?: {
+        description: string;
+        matcher: TerminalWaitMatcher;
+    }[];
+    intervalMs?: number;
+    timeoutMs?: number;
+    /** Wait boundaries on the session clock, including time with no output. */
+    castStartTimeSec?: number;
+    castEndTimeSec?: number;
+    /** Exit code observed on exit, close, or a failed wait. */
     exitCode?: number;
     /** Rendered screen at the moment of the op (post-action), truncated. */
     screenPreview: string;

package/dist/terminal.d.ts

@@ -25,6 +25,25 @@ export interface TerminalOpts {
      */
     timeoutMs?: number;
 }
+/** A visible terminal failure that should stop a wait immediately. */
+export interface TerminalFailureCondition {
+    description: string;
+    matcher: string | RegExp;
+}
+export interface TerminalWaitOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    /** Cancel this observation without closing the terminal. */
+    signal?: AbortSignal;
+    /** Describe a custom predicate's condition separately from the step title. */
+    condition?: string;
+    /** Checked against the rendered screen before the success matcher. */
+    failOn?: readonly TerminalFailureCondition[];
+}
+export interface TerminalCloseOptions {
+    /** Total deadline including graceful exit, kill and pipe drain. Default 10 s. */
+    timeoutMs?: number;
+}
 /** Result of the one-shot `ctx.terminal(...)` convenience. */
 export interface TerminalResult {
     /** Full decoded PTY output (raw bytes, ANSI escapes included). Capped. */
@@ -50,7 +69,8 @@ export interface Terminal {
     /**
      * Resolves when the underlying process ends — by `close()`, by the
      * inner command exiting, or by timeout — to a `TerminalResult` with
-     * the full captured `output` and `exitCode`. Never rejects.
+     * the full captured `output` and `exitCode`. Rejects if output cannot
+     * be drained after exit.
      *
      * The result is provenance-tagged against the `exit` step, so an
      * `expect((await term.exited).output).toContain(...)` /
@@ -91,29 +111,23 @@ export interface Terminal {
      * `description` is a short human label that shows up in the event
      * log so timelines don't fill with anonymous waits.
      *
-     * Defaults: 5 s total timeout, 100 ms between polls. Throws on
-     * timeout.
+     * Defaults: 10 s total timeout, 100 ms between polls. Throws on timeout,
+     * a failure condition, predicate error, cancellation, or process exit before
+     * a match. On exit the final drained screen is checked first. Async custom
+     * predicates are supported; cancellation stops polling but cannot forcibly
+     * cancel work started by the predicate itself.
      */
-    waitFor(description: string, matcher: string, opts?: {
-        timeoutMs?: number;
-        intervalMs?: number;
-    }): Promise<Wrapped<string>>;
-    waitFor(description: string, matcher: RegExp, opts?: {
-        timeoutMs?: number;
-        intervalMs?: number;
-    }): Promise<Wrapped<RegExpMatchArray>>;
-    waitFor<T = unknown>(description: string, matcher: (screen: string, output: string) => T, opts?: {
-        timeoutMs?: number;
-        intervalMs?: number;
-    }): Promise<Wrapped<NonNullable<Awaited<T>>>>;
+    waitFor(description: string, matcher: string, opts?: TerminalWaitOptions): Promise<Wrapped<string>>;
+    waitFor(description: string, matcher: RegExp, opts?: TerminalWaitOptions): Promise<Wrapped<RegExpMatchArray>>;
+    waitFor<T = unknown>(description: string, matcher: (screen: string, output: string) => T, opts?: TerminalWaitOptions): Promise<Wrapped<NonNullable<Awaited<T>>>>;
     /**
      * Tear down. Writes Ctrl-D to stdin to nudge the shell out, then
      * SIGKILLs after a grace period. Idempotent. Resolves to a
      * `TerminalResult` (tagged against the `close` step) so you can assert
      * on the transcript of a session that doesn't self-terminate. Optional
-     * — terminals are not auto-closed when a test ends.
+     * — terminals are not auto-closed when a test ends. Rejects on cleanup timeout.
      */
-    close(): Promise<Wrapped<TerminalResult>>;
+    close(opts?: TerminalCloseOptions): Promise<Wrapped<TerminalResult>>;
 }
 /**
  * The concrete handle `openTerminal` returns. Extends the public

package/dist/terminal.js

@@ -20,7 +20,7 @@
 //
 // PTY-on-the-host trick: the daemon runs under systemd with no controlling
 // TTY, so `docker exec -it` (the docker CLI rejects -it when its own stdin
-// isn't a TTY) needs a PTY wrapper. `script -qfc 'CMD' /dev/null` allocates
+// isn't a TTY) needs a PTY wrapper. `script -qfec 'CMD' /dev/null` allocates
 // a PTY for CMD; we set the slave's size with `stty rows R cols C` inside
 // the wrapped command so the container app sees the cols/rows the caller
 // asked for. `script(1)` ships in util-linux which is essential on Debian,
@@ -97,9 +97,10 @@ export async function openTerminal(args) {
     // 80x24, but the daemon has none, so it's whatever util-linux picks
     // as the fallback).
     const inner = `stty rows ${rows} cols ${cols} 2>/dev/null; exec ${shellQuote(["docker", ...dockerArgs])}`;
-    // `script -q -f -c CMD /dev/null` runs CMD in a PTY (no preamble, flushed
+    // `script -q -f -e -c CMD /dev/null` runs CMD in a PTY (no preamble, flushed
     // after each write, output discarded — we capture via stdout pipe).
-    const spawnArgs = ["script", "-qfc", inner, "/dev/null"];
+    // -e preserves the child command status; without it script reports 0 on failure.
+    const spawnArgs = ["script", "-qfec", inner, "/dev/null"];
     const start = Date.now();
     const proc = Bun.spawn(spawnArgs, {
         stdin: "pipe",
@@ -119,14 +120,22 @@ export async function openTerminal(args) {
     let exitCode;
     let closed = false;
     let resolveExit;
-    const rawExited = new Promise((res) => {
+    let rejectExit;
+    let exitSettled = false;
+    const exitWaiters = new Set();
+    const cancelWaits = new Set();
+    const rawExited = new Promise((res, reject) => {
         resolveExit = res;
+        rejectExit = reject;
     });
+    // Lifecycle errors are observed by waitFor/exited/close, possibly much later.
+    void rawExited.catch(() => { });
     // Cast time at the moment the process actually exited. Captured by
     // the IIFE below so the `exit` step we record points the player at
     // the very end of the visible session.
     let exitCastTimeSec;
-    const decoder = new TextDecoder("utf-8", { fatal: false });
+    let outputEnded = false;
+    const readers = new Set();
     // Subscribers waiting for the next frame to arrive. Used by send /
     // sendLine / press so the recorded `castTimeSec` lands on the echo's
     // frame instead of microseconds before it.
@@ -143,13 +152,16 @@ export async function openTerminal(args) {
     // millisecond as the following `sendLine`'s echo showed that echo
     // — the replay ran one step ahead of the step list.
     let lastFrameT = 0;
+    let lastRenderedFrameT = 0;
     const ingest = (chunk) => {
+        if (outputEnded)
+            return;
         let t = (Date.now() - start) / 1000;
         if (t <= lastFrameT)
             t = lastFrameT + 0.001;
         lastFrameT = t;
         sink.pushFrame(t, chunk);
-        emu.write(chunk);
+        emu.write(chunk, () => { lastRenderedFrameT = t; });
         if (output.length < OUTPUT_CAP_BYTES) {
             const room = OUTPUT_CAP_BYTES - output.length;
             output += chunk.length > room ? chunk.slice(0, room) : chunk;
@@ -173,21 +185,31 @@ export async function openTerminal(args) {
                 if (done)
                     return;
                 done = true;
+                clearTimeout(timeout);
+                const index = frameWaiters.indexOf(finish);
+                if (index >= 0)
+                    frameWaiters.splice(index, 1);
                 resolve();
             };
+            const timeout = setTimeout(finish, timeoutMs);
             frameWaiters.push(finish);
-            setTimeout(finish, timeoutMs);
         });
     };
     const drainStream = async (stream) => {
         if (!stream)
             return;
         const reader = stream.getReader();
+        const decoder = new TextDecoder("utf-8", { fatal: false });
+        readers.add(reader);
         try {
             while (true) {
                 const { done, value } = await reader.read();
-                if (done)
+                if (done) {
+                    const tail = decoder.decode();
+                    if (tail)
+                        ingest(tail);
                     return;
+                }
                 if (!value || value.byteLength === 0)
                     continue;
                 const chunk = decoder.decode(value, { stream: true });
@@ -197,15 +219,23 @@ export async function openTerminal(args) {
             }
         }
         finally {
+            readers.delete(reader);
             reader.releaseLock();
         }
     };
+    const stopOutput = () => {
+        outputEnded = true;
+        for (const reader of readers)
+            void reader.cancel().catch(() => { });
+    };
+    const flushScreen = () => new Promise((resolve) => emu.write("", resolve));
     // Drain stdout + stderr concurrently. `script` writes everything to
     // stdout under `-t`, but we drain stderr anyway in case script(1)
     // itself emits diagnostics there.
     const stdout = proc.stdout;
     const stderr = proc.stderr;
     const drained = Promise.all([drainStream(stdout), drainStream(stderr)]);
+    void drained.catch(() => { });
     // Race the optional session-level timeout. For interactive terminals
     // we usually have no timeout; the wrapper for one-shot supplies one.
     let timer;
@@ -221,39 +251,42 @@ export async function openTerminal(args) {
             }
         }, opts.timeoutMs);
     }
-    // When the process exits, drain whatever's left and resolve `exited`.
-    // We don't await `drained` here — it's already running and will
-    // settle on its own; the explicit `await drained` happens in close().
-    (async () => {
-        const code = await proc.exited;
-        exited = true;
-        exitCode = code;
-        if (timer)
-            clearTimeout(timer);
-        // Let `drained` finish so the final asciicast frames land before we
-        // mark the sink closed. drainStream is bounded by the OS pipe being
-        // closed when proc exits, so this won't hang.
+    // A child may inherit a pipe after the PTY wrapper exits. Bound the drain,
+    // and flush xterm's asynchronous writes before exposing the final screen.
+    void (async () => {
         try {
-            await drained;
+            const code = await proc.exited;
+            exited = true;
+            exitCode = code;
+            if (timer)
+                clearTimeout(timer);
+            await within(drained.then(flushScreen), 5_000, "Terminal output did not finish draining within 5000ms");
+            exitCastTimeSec = lastRenderedFrameT + 0.0005;
+            sink.markClosed();
+            resolveExit(code);
         }
-        catch {
-            /* ignore */
+        catch (error) {
+            stopOutput();
+            sink.markClosed();
+            rejectExit(error);
+        }
+        finally {
+            exitSettled = true;
+            if (timer)
+                clearTimeout(timer);
+            for (const wake of exitWaiters)
+                wake();
+            exitWaiters.clear();
         }
-        // Record cast time AFTER drain, so the `exit` step we record below
-        // points the player at the very last frame (the program's final
-        // output before EOF). Same between-frames stamp as `recordOpEvent`.
-        exitCastTimeSec = lastFrameT + 0.0005;
-        sink.markClosed();
-        resolveExit(code);
     })();
     // Helper to write raw bytes to the PTY. We treat stdin as binary
     // pipes (Bun's `proc.stdin` is a Web `WritableStream<Uint8Array>` or
     // a FileSink-like depending on the version — use the FileSink-style
     // `write(string)` which both shapes accept).
     const stdinWriter = proc.stdin;
-    const writeStdin = async (data) => {
-        if (exited || closed || !stdinWriter)
-            return;
+    const writeStdin = async (data, closing = false) => {
+        if (exited || (closed && !closing) || !stdinWriter)
+            throw new Error(`Terminal ${JSON.stringify(service)} is ${exited ? "exited" : "closed"}`);
         stdinWriter.write(data);
         try {
             const r = stdinWriter.flush?.();
@@ -326,9 +359,17 @@ export async function openTerminal(args) {
     const getExited = () => {
         if (exitedAccessor)
             return exitedAccessor;
-        const resv = reserveEvent();
         exitedAccessor = (async () => {
-            const code = await rawExited;
+            let code;
+            try {
+                code = await rawExited;
+            }
+            catch (error) {
+                recordOpEvent("exit", { exitCode }, Date.now(), errorMessage(error));
+                throw error;
+            }
+            // Reserve on actual completion, not when .exited is read for a race.
+            const resv = reserveEvent();
             const result = buildResult(code);
             // No recorder (eval/setup): there's no event to nest under, but we
             // still wrap (with an undefined seq) so the accessor's wrapped type is
@@ -353,6 +394,7 @@ export async function openTerminal(args) {
         })();
         return exitedAccessor;
     };
+    let closePromise;
     const handle = {
         cols,
         rows,
@@ -424,93 +466,207 @@ export async function openTerminal(args) {
             return renderScreen();
         },
         async waitFor(description, matcher, waitOpts) {
-            const timeoutMs = waitOpts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS;
-            const intervalMs = waitOpts?.intervalMs ?? 100;
+            const timeoutMs = durationOption(waitOpts?.timeoutMs, DEFAULT_ACTION_TIMEOUT_MS, "timeoutMs");
+            const intervalMs = durationOption(waitOpts?.intervalMs, 100, "intervalMs");
             const t = Date.now();
             const resv = reserveEvent();
-            const deadline = t + timeoutMs;
+            const castStartTimeSec = Math.max((t - start) / 1000, lastFrameT + 0.0005);
+            const condition = typeof matcher === "function"
+                ? { kind: "custom", ...(waitOpts?.condition ? { description: waitOpts.condition } : {}) }
+                : describeMatcher(matcher);
+            const failureMatchers = waitOpts?.failOn?.map(({ description, matcher }) => ({
+                description, matcher: describeMatcher(matcher),
+            }));
             let attempts = 0;
-            const check = () => {
-                attempts++;
-                const scr = renderScreen();
-                if (typeof matcher === "string") {
-                    return scr.includes(matcher) ? matcher : null;
-                }
-                if (matcher instanceof RegExp) {
-                    const m = scr.match(matcher);
-                    return m ?? null;
-                }
-                return matcher(scr, output);
+            let observed;
+            let outcome = "predicate_error";
+            const control = new AbortController();
+            const cancel = () => {
+                outcome = "cancelled";
+                control.abort(waitOpts?.signal?.reason ?? new Error(`waitFor ${JSON.stringify(description)} cancelled: terminal closed`));
             };
-            while (true) {
-                const v = check();
-                if (v) {
-                    const seq = recordOpEvent("waitFor", { description, attempts, matched: true }, t, undefined, resv);
-                    // Tag the matched value so an `expect(...)` on it links its
-                    // assertion back to this waitFor step (sourceSeq) instead of
-                    // rendering as an orphan sidebar row. Mirrors how http/db/exec
-                    // results carry their op's seq. `as never` lets this single
-                    // body satisfy the three overload return types.
-                    return wrap(v, seq);
-                }
-                if (Date.now() >= deadline) {
-                    const err = `waitFor ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`;
-                    recordOpEvent("waitFor", { description, attempts, matched: false }, t, err, resv);
-                    throw new Error(err);
+            const timeout = setTimeout(() => {
+                outcome = "timed_out";
+                control.abort(new Error(`waitFor ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`));
+            }, timeoutMs);
+            cancelWaits.add(cancel);
+            waitOpts?.signal?.addEventListener("abort", cancel, { once: true });
+            if (waitOpts?.signal?.aborted || closed)
+                cancel();
+            const waitFields = () => ({
+                description, attempts, matched: outcome === "matched", outcome,
+                matcher: condition, failureMatchers, timeoutMs, intervalMs,
+                ...(outcome === "process_exited" ? { exitCode } : {}),
+                castStartTimeSec,
+                castEndTimeSec: castStartTimeSec + (Date.now() - t) / 1000,
+            });
+            const pause = () => new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    clearTimeout(poll);
+                    exitWaiters.delete(wake);
+                    control.signal.removeEventListener("abort", abort);
+                };
+                const wake = () => { cleanup(); resolve(); };
+                const abort = () => { cleanup(); reject(control.signal.reason); };
+                const poll = setTimeout(wake, intervalMs);
+                exitWaiters.add(wake);
+                control.signal.addEventListener("abort", abort, { once: true });
+                if (control.signal.aborted)
+                    abort();
+                else if (exitSettled)
+                    wake();
+            });
+            try {
+                while (true) {
+                    control.signal.throwIfAborted();
+                    if (exited || exitSettled) {
+                        try {
+                            await withSignal(rawExited, control.signal);
+                        }
+                        catch (error) {
+                            if (!control.signal.aborted)
+                                outcome = "process_exited";
+                            throw error;
+                        }
+                    }
+                    control.signal.throwIfAborted();
+                    const checkedFinalScreen = exitSettled;
+                    const screen = renderScreen();
+                    const preview = truncateUtf8(screen);
+                    observed = { castTimeSec: lastRenderedFrameT + 0.0005,
+                        screenPreview: preview.value, screenTruncated: preview.truncated };
+                    attempts++;
+                    for (const failure of waitOpts?.failOn ?? []) {
+                        if (matchScreen(screen, failure.matcher)) {
+                            outcome = "failure_matched";
+                            throw new Error(`waitFor ${JSON.stringify(description)} failed: ${failure.description}`);
+                        }
+                    }
+                    const observedOutput = output;
+                    const value = typeof matcher === "function"
+                        ? await withSignal(Promise.resolve().then(() => {
+                            control.signal.throwIfAborted();
+                            return matcher(screen, observedOutput);
+                        }), control.signal)
+                        : matchScreen(screen, matcher);
+                    control.signal.throwIfAborted();
+                    if (value) {
+                        outcome = "matched";
+                        const seq = recordOpEvent("waitFor", { ...waitFields(), ...observed }, t, undefined, resv);
+                        return wrap(value, seq);
+                    }
+                    if (exitSettled && !checkedFinalScreen)
+                        continue;
+                    if (exitSettled) {
+                        outcome = "process_exited";
+                        throw new Error(`waitFor ${JSON.stringify(description)} failed: terminal exited with code ${exitCode} before the condition matched`);
+                    }
+                    await pause();
                 }
-                await new Promise((r) => setTimeout(r, intervalMs));
+            }
+            catch (error) {
+                recordOpEvent("waitFor", { ...waitFields(),
+                    ...((outcome === "predicate_error" || outcome === "failure_matched") ? observed : {}),
+                }, t, errorMessage(error), resv);
+                throw error;
+            }
+            finally {
+                clearTimeout(timeout);
+                cancelWaits.delete(cancel);
+                waitOpts?.signal?.removeEventListener("abort", cancel);
             }
         },
-        async close() {
-            // Use `rawExited` rather than `term.exited` everywhere we need a
-            // raw number internally — the public getter resolves to a wrapped
-            // result (and records an `exit` step on first read) which we don't
-            // want as a side-effect of internal teardown logic.
-            if (closed)
-                return buildResult(exitCode ?? (await rawExited));
-            closed = true;
+        close(closeOpts) {
+            if (closePromise)
+                return closePromise;
+            const timeoutMs = durationOption(closeOpts?.timeoutMs, 10_000, "timeoutMs");
             const t = Date.now();
             const resv = reserveEvent();
-            // Polite first: send EOF (Ctrl-D). For a login shell this exits
-            // cleanly. For a long-running command it's a no-op and we fall
-            // through to SIGKILL.
-            try {
-                await writeStdin("\x04");
-            }
-            catch {
-                /* ignore */
-            }
-            // Closing stdin signals EOF to the script wrapper too.
-            try {
-                proc.stdin?.end?.();
-            }
-            catch {
-                /* ignore */
-            }
-            // Grace period before forcibly killing.
-            const grace = 1_500;
-            const raced = await Promise.race([
-                rawExited,
-                new Promise((r) => setTimeout(() => r("timeout"), grace)),
-            ]);
-            if (raced === "timeout") {
+            closed = true;
+            for (const cancel of cancelWaits)
+                cancel();
+            closePromise = (async () => {
                 try {
-                    proc.kill();
+                    if (!exited) {
+                        // Send EOF even though new user operations are now closed.
+                        try {
+                            await writeStdin("\x04", true);
+                        }
+                        catch { /* already exited */ }
+                        try {
+                            proc.stdin?.end?.();
+                        }
+                        catch { /* already closed */ }
+                    }
+                    const grace = Math.min(1_500, timeoutMs / 2);
+                    let graceTimer;
+                    const finished = await Promise.race([
+                        rawExited.then(() => true),
+                        new Promise((resolve) => { graceTimer = setTimeout(() => resolve(false), grace); }),
+                    ]).finally(() => clearTimeout(graceTimer));
+                    if (!finished && !exited) {
+                        try {
+                            proc.kill("SIGKILL");
+                        }
+                        catch { /* process already gone */ }
+                    }
+                    const code = await within(rawExited, Math.max(0, timeoutMs - (Date.now() - t)), `Terminal close timed out after ${timeoutMs}ms`);
+                    const result = buildResult(code);
+                    const seq = recordOpEvent("close", { exitCode: code }, t, undefined, resv);
+                    return wrap(result, seq);
                 }
-                catch {
-                    /* ignore */
+                catch (error) {
+                    if (!exited) {
+                        try {
+                            proc.kill("SIGKILL");
+                        }
+                        catch { /* best effort */ }
+                    }
+                    stopOutput();
+                    if (timer)
+                        clearTimeout(timer);
+                    recordOpEvent("close", { exitCode }, t, errorMessage(error), resv);
+                    throw error;
                 }
-            }
-            const code = await rawExited;
-            const result = buildResult(code);
-            const seq = recordOpEvent("close", { exitCode: code }, t, undefined, resv);
-            // Tag the result against the close step so assertions on the
-            // transcript of a non-self-terminating session nest under it.
-            return wrap(result, seq);
+            })();
+            return closePromise;
         },
     };
     return handle;
 }
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function durationOption(value, fallback, name) {
+    const duration = value ?? fallback;
+    if (!Number.isFinite(duration) || duration < 0)
+        throw new Error(`${name} must be a finite non-negative number`);
+    return duration;
+}
+function describeMatcher(matcher) {
+    return typeof matcher === "string" ? { kind: "text", value: matcher }
+        : { kind: "regex", value: matcher.source, flags: matcher.flags };
+}
+function matchScreen(screen, matcher) {
+    return typeof matcher === "string" ? (screen.includes(matcher) ? matcher : null)
+        : screen.match(new RegExp(matcher.source, matcher.flags));
+}
+function withSignal(work, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+        if (signal.aborted) {
+            signal.removeEventListener("abort", abort);
+            abort();
+        }
+    });
+}
+function within(work, ms, message) {
+    const control = new AbortController();
+    const timer = setTimeout(() => control.abort(new Error(message)), ms);
+    return withSignal(work, control.signal).finally(() => clearTimeout(timer));
+}
 // ────────────────────────────────────────────────────────────────────────
 // Key name → byte sequence
 // ────────────────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.127.0",
+  "version": "0.129.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",