@with-logic/elwood 0.2.1 → 0.2.2

package/dist/runtime/probe/private-directory.js

@@ -0,0 +1,50 @@
+/**
+ * A directory made for one probe's output, mode 0700 under the system temp directory, and its
+ * removal however the probe ends (PRD §9.2, C-PERF-05).
+ */
+import { mkdtempSync, rmdirSync, rmSync } from "node:fs";
+import { chmod, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Makes a probe's private directory; `mkdtemp` makes it mode 0700. */
+export function makePrivateDirectory() {
+    return mkdtempSync(join(tmpdir(), "elwood-probe-"));
+}
+/**
+ * Removes a probe's private directory, which holds at most `entries`, as the probe settles: an
+ * unlink each and an `rmdir`, done at once. A directory the command changed, by what it made, locked,
+ * or removed there, is removed off the event loop instead, however large a tree it left. Never
+ * throws.
+ */
+export function removePrivateDirectory(dir, entries) {
+    try {
+        // `force`: setup that failed may not have made them.
+        for (const entry of entries)
+            rmSync(join(dir, entry), { force: true });
+        rmdirSync(dir);
+    }
+    catch {
+        void removeTree(dir);
+    }
+}
+async function removeTree(dir) {
+    try {
+        // The command may have made the directory, or one it made inside it, unreadable. Elwood
+        // owns them, so it can open them again.
+        await unlock(dir);
+        await rm(dir, { recursive: true, force: true });
+    }
+    catch {
+        // Mostly, the command removed the directory itself. Any other failure leaves it behind,
+        // unreported: the probe has settled, and nothing reads a removal's outcome yet.
+    }
+}
+/** Gives `dir` and every directory under it back their owner's access. */
+async function unlock(dir) {
+    await chmod(dir, 0o700);
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (entry.isDirectory())
+            await unlock(join(dir, entry.name));
+    }
+}
+//# sourceMappingURL=private-directory.js.map

package/dist/runtime/probe/private-directory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-directory.js","sourceRoot":"","sources":["../../../src/runtime/probe/private-directory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,uEAAuE;AACvE,MAAM,UAAU,oBAAoB;IAClC,OAAO,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,OAA0B;IAC5E,IAAI,CAAC;QACH,qDAAqD;QACrD,KAAK,MAAM,KAAK,IAAI,OAAO;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvE,SAAS,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,UAAU,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,GAAW;IACnC,IAAI,CAAC;QACH,wFAAwF;QACxF,wCAAwC;QACxC,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;QAClB,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,wFAAwF;QACxF,gFAAgF;IAClF,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,KAAK,UAAU,MAAM,CAAC,GAAW;IAC/B,MAAM,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACxB,KAAK,MAAM,KAAK,IAAI,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAChE,IAAI,KAAK,CAAC,WAAW,EAAE;YAAE,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC"}

package/dist/runtime/probe/results.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The results a probe settles with when its command did not simply exit: a spawn error, a
+ * bound, an overflow, a login shell that never started the command, or the e2e home guard
+ * (PRD §9.2, C-PERF-03, C-PERF-05, C-E2E-24; native spawn diagnostics, C-ERR-08).
+ */
+import type { CommandResult } from "../seams.ts";
+export declare function mapError(error: NodeJS.ErrnoException): NonNullable<CommandResult["error"]>;
+export declare function commandTimedOut(ms: number, stdout: string, stderr: string): CommandResult;
+export declare function launchTimedOut(ms: number, stdout: string, stderr: string): CommandResult;
+export declare function shellExited(status: number | null, stdout: string, stderr: string): CommandResult;
+/** A probe the e2e home guard stopped: the login shell's failure, with only the fixed reason. */
+export declare function guardStopped(stdout: string, stderr: string): CommandResult;
+export declare function overflow(stdout: string, stderr: string): CommandResult;
+//# sourceMappingURL=results.d.ts.map

package/dist/runtime/probe/results.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/runtime/probe/results.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,GAAG,WAAW,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAE1F;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAGzF;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAIxF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAIhG;AAED,iGAAiG;AACjG,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAO1E;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAGtE"}

package/dist/runtime/probe/results.js

@@ -0,0 +1,38 @@
+/**
+ * The results a probe settles with when its command did not simply exit: a spawn error, a
+ * bound, an overflow, a login shell that never started the command, or the e2e home guard
+ * (PRD §9.2, C-PERF-03, C-PERF-05, C-E2E-24; native spawn diagnostics, C-ERR-08).
+ */
+import { homeGuardExitCode, homeGuardStoppedReason } from "../home-guard/index.js";
+import { maxProbeStreamOutputBytes } from "./capped-buffer.js";
+export function mapError(error) {
+    return { code: error.code, syscall: error.syscall, path: error.path, message: error.message };
+}
+export function commandTimedOut(ms, stdout, stderr) {
+    const message = `probe timed out after ${ms} ms`;
+    return { status: null, stdout, stderr, error: { code: "ETIMEDOUT", message } };
+}
+export function launchTimedOut(ms, stdout, stderr) {
+    const message = `login shell did not start the probe command within ${ms} ms`;
+    const error = { code: "ETIMEDOUT", message, phase: "login_shell" };
+    return { status: null, stdout, stderr, error };
+}
+export function shellExited(status, stdout, stderr) {
+    const message = `login shell exited with status ${status} before starting the probe command`;
+    const error = { message, phase: "login_shell", shellStatus: status };
+    return { status: null, stdout, stderr, error };
+}
+/** A probe the e2e home guard stopped: the login shell's failure, with only the fixed reason. */
+export function guardStopped(stdout, stderr) {
+    const error = {
+        message: homeGuardStoppedReason,
+        phase: "login_shell",
+        shellStatus: homeGuardExitCode,
+    };
+    return { status: null, stdout, stderr, error };
+}
+export function overflow(stdout, stderr) {
+    const message = `a probe output stream exceeded ${maxProbeStreamOutputBytes} bytes`;
+    return { status: null, stdout, stderr, error: { code: "E2BIG", message } };
+}
+//# sourceMappingURL=results.js.map

package/dist/runtime/probe/results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.js","sourceRoot":"","sources":["../../../src/runtime/probe/results.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEnF,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,UAAU,QAAQ,CAAC,KAA4B;IACnD,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;AAChG,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,EAAU,EAAE,MAAc,EAAE,MAAc;IACxE,MAAM,OAAO,GAAG,yBAAyB,EAAE,KAAK,CAAC;IACjD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,EAAU,EAAE,MAAc,EAAE,MAAc;IACvE,MAAM,OAAO,GAAG,sDAAsD,EAAE,KAAK,CAAC;IAC9E,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAW,CAAC;IAC5E,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAqB,EAAE,MAAc,EAAE,MAAc;IAC/E,MAAM,OAAO,GAAG,kCAAkC,MAAM,oCAAoC,CAAC;IAC7F,MAAM,KAAK,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAW,CAAC;IAC9E,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACjD,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,MAAc;IACzD,MAAM,KAAK,GAAG;QACZ,OAAO,EAAE,sBAAsB;QAC/B,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE,iBAAiB;KACtB,CAAC;IACX,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,MAAc;IACrD,MAAM,OAAO,GAAG,kCAAkC,yBAAyB,QAAQ,CAAC;IACpF,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;AAC7E,CAAC"}

package/dist/runtime/probe/slots.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Caps how many probe shells run at once in this process. Each probe starts an interactive
+ * login shell, and a heavy profile is CPU-bound: one took about 2 s at 4 concurrent shells and
+ * 7-19 s at 16 on a loaded host. Without a cap, a fleet starting in many directories would start
+ * a shell for every probe at once and slow all of them. Implements PRD §9.2 and C-PERF-07.
+ */
+/**
+ * At most this many probes run at once; the rest wait their turn in arrival order. Eight keeps a
+ * heavy profile near 5 s per probe on a loaded 16-CPU host, against about 2 s at four and 7-19 s
+ * at sixteen, so a cold fleet still starts eight sessions at a time while each stays well inside
+ * its 60 s launch bound (C-PERF-05). The measurements are in docs/cli-behavior.md, "Probe shell
+ * startup under concurrency".
+ */
+export declare const maxConcurrentProbes = 8;
+/** Runs `probe` once a slot is free, and frees the slot when it settles either way. */
+export declare function withProbeSlot<T>(probe: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=slots.d.ts.map

package/dist/runtime/probe/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../../src/runtime/probe/slots.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAKrC,uFAAuF;AACvF,wBAAsB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAW1E"}

package/dist/runtime/probe/slots.js

@@ -0,0 +1,35 @@
+/**
+ * Caps how many probe shells run at once in this process. Each probe starts an interactive
+ * login shell, and a heavy profile is CPU-bound: one took about 2 s at 4 concurrent shells and
+ * 7-19 s at 16 on a loaded host. Without a cap, a fleet starting in many directories would start
+ * a shell for every probe at once and slow all of them. Implements PRD §9.2 and C-PERF-07.
+ */
+/**
+ * At most this many probes run at once; the rest wait their turn in arrival order. Eight keeps a
+ * heavy profile near 5 s per probe on a loaded 16-CPU host, against about 2 s at four and 7-19 s
+ * at sixteen, so a cold fleet still starts eight sessions at a time while each stays well inside
+ * its 60 s launch bound (C-PERF-05). The measurements are in docs/cli-behavior.md, "Probe shell
+ * startup under concurrency".
+ */
+export const maxConcurrentProbes = 8;
+let running = 0;
+const waiting = [];
+/** Runs `probe` once a slot is free, and frees the slot when it settles either way. */
+export async function withProbeSlot(probe) {
+    if (running < maxConcurrentProbes)
+        running += 1;
+    else
+        await new Promise((resolve) => waiting.push(resolve));
+    try {
+        return await probe();
+    }
+    finally {
+        // Hand the slot straight to the longest waiter, so a newcomer cannot take it first.
+        const next = waiting.shift();
+        if (next)
+            next();
+        else
+            running -= 1;
+    }
+}
+//# sourceMappingURL=slots.js.map

package/dist/runtime/probe/slots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.js","sourceRoot":"","sources":["../../../src/runtime/probe/slots.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAErC,IAAI,OAAO,GAAG,CAAC,CAAC;AAChB,MAAM,OAAO,GAAmB,EAAE,CAAC;AAEnC,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAI,KAAuB;IAC5D,IAAI,OAAO,GAAG,mBAAmB;QAAE,OAAO,IAAI,CAAC,CAAC;;QAC3C,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IACjE,IAAI,CAAC;QACH,OAAO,MAAM,KAAK,EAAE,CAAC;IACvB,CAAC;YAAS,CAAC;QACT,oFAAoF;QACpF,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,IAAI;YAAE,IAAI,EAAE,CAAC;;YACZ,OAAO,IAAI,CAAC,CAAC;IACpB,CAAC;AACH,CAAC"}

package/dist/runtime/probe/start.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Recognizes the probe shell's start line, which ends the login shell's launch phase and starts
+ * the probe command's own bound: on the runner's private control descriptor, or on stdout from a
+ * shell that closed that descriptor at startup. Implements PRD §9.2 and C-PERF-05.
+ */
+/**
+ * The line a probe shell writes once the user's startup files have loaded, before the probe
+ * command runs. It separates the profile's launch time from the command's own bound, which
+ * covers everything after the line: the not-found handlers' removal, then the command
+ * (PRD §9.2, C-PERF-05). Owned here, by the reader, so the runner never loads the shell
+ * helpers that the writer, `probeShellCommand`, lives in. It ends in a token drawn once per
+ * parent process: stdout, which the runner also watches, carries the profile's own output,
+ * and no profile can print a line it cannot predict.
+ */
+export declare const probeCommandStartLine: string;
+/**
+ * The start line's primary channel: a fourth pipe the runner opens for every probe. Not stdout
+ * or stderr, so a profile that redirects those (`exec 2>&1`, `exec 2>/dev/null`) cannot hide
+ * the line, and captured output stays exactly the profile's and the command's. A shell that
+ * closed it at startup writes the line on stdout instead (`probeStartScript`).
+ */
+export declare const probeControlFd = 3;
+/**
+ * The probe shell's script prefix: it writes the start line on the control descriptor. macOS's
+ * bash 3.2 started with both `-l` and `-i` closes every inherited descriptor above stderr before
+ * running the script, so there the write fails, silently, and the line goes to stdout. Not
+ * stderr: a profile may send that to `/dev/null` or into stdout, while a profile that hid stdout
+ * would hide the line, and so fail the probe as the login shell's. The runner removes the line
+ * from captured stdout. The descriptor stays open for the e2e home guard, which writes its stop
+ * line where the start line went (PRD §12), until `probeControlClose`.
+ */
+export declare const probeStartScript: string;
+/** Closes the control descriptor before the probe command, so the command does not inherit it. */
+export declare const probeControlClose = "exec 3>&-; ";
+/**
+ * The redirection a probe script gives the command it `exec`s: a placeholder that a named-pipe
+ * capture replaces with its two pipes' quoted paths once it has made them (`named-pipes.ts`).
+ * The paths are never in the login shell's environment, so nothing its startup files run is
+ * told where the probe's output goes.
+ */
+export declare const probeOutputRedirect = ">%elwood-probe-stdout% 2>%elwood-probe-stderr%";
+/**
+ * Removes the user's not-found handlers before the probe command runs: zsh's
+ * `command_not_found_handler` and bash's `command_not_found_handle`. A shell that finds no
+ * command runs its handler, so its output would be captured as the command's, and the status
+ * the handler returns would replace the 127 that tells preflight the CLI is missing. Each
+ * shell ignores the other's name, and a failed `unset` cannot end the shell under `errexit`.
+ */
+export declare const probeNotFoundHandlerReset = "unset -f command_not_found_handler command_not_found_handle 2>/dev/null || :; ";
+/** Whether a probe runs a script that announces its command with the start line. */
+export declare function announcesStart(args: readonly string[]): boolean;
+/** The two streams a probe's start line can arrive on. */
+export type ProbeStartChannel = "control" | "stdout";
+/** Watches both channels; the first to carry the start line starts the command. */
+export declare class ProbeStart {
+    private readonly watchers;
+    /** Whether any channel has carried the start line. */
+    get started(): boolean;
+    /** True exactly once across both channels: for the chunk that completes the start line. */
+    feed(channel: ProbeStartChannel, chunk: Buffer): boolean;
+    /** Removes the start line from captured stdout if the shell wrote it there (C-PERF-05). */
+    stripFromStdout(captured: string): string;
+}
+//# sourceMappingURL=start.d.ts.map

package/dist/runtime/probe/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../../src/runtime/probe/start.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,QAAiE,CAAC;AAEpG;;;;;GAKG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,QAA0G,CAAC;AAExI,kGAAkG;AAClG,eAAO,MAAM,iBAAiB,gBAAgC,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,mDAAmD,CAAC;AAEpF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,mFAC4C,CAAC;AAEnF,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE/D;AAKD,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErD,mFAAmF;AACnF,qBAAa,UAAU;IAErB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAGvB;IAEF,sDAAsD;IACtD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,2FAA2F;IAC3F,IAAI,CAAC,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAKxD,2FAA2F;IAC3F,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAG1C"}

package/dist/runtime/probe/start.js

@@ -0,0 +1,80 @@
+/**
+ * Recognizes the probe shell's start line, which ends the login shell's launch phase and starts
+ * the probe command's own bound: on the runner's private control descriptor, or on stdout from a
+ * shell that closed that descriptor at startup. Implements PRD §9.2 and C-PERF-05.
+ */
+import { randomBytes } from "node:crypto";
+import { StreamMarkerWatcher } from "../stream-marker.js";
+/**
+ * The line a probe shell writes once the user's startup files have loaded, before the probe
+ * command runs. It separates the profile's launch time from the command's own bound, which
+ * covers everything after the line: the not-found handlers' removal, then the command
+ * (PRD §9.2, C-PERF-05). Owned here, by the reader, so the runner never loads the shell
+ * helpers that the writer, `probeShellCommand`, lives in. It ends in a token drawn once per
+ * parent process: stdout, which the runner also watches, carries the profile's own output,
+ * and no profile can print a line it cannot predict.
+ */
+export const probeCommandStartLine = `elwood-probe-command-start-${randomBytes(8).toString("hex")}`;
+/**
+ * The start line's primary channel: a fourth pipe the runner opens for every probe. Not stdout
+ * or stderr, so a profile that redirects those (`exec 2>&1`, `exec 2>/dev/null`) cannot hide
+ * the line, and captured output stays exactly the profile's and the command's. A shell that
+ * closed it at startup writes the line on stdout instead (`probeStartScript`).
+ */
+export const probeControlFd = 3;
+/**
+ * The probe shell's script prefix: it writes the start line on the control descriptor. macOS's
+ * bash 3.2 started with both `-l` and `-i` closes every inherited descriptor above stderr before
+ * running the script, so there the write fails, silently, and the line goes to stdout. Not
+ * stderr: a profile may send that to `/dev/null` or into stdout, while a profile that hid stdout
+ * would hide the line, and so fail the probe as the login shell's. The runner removes the line
+ * from captured stdout. The descriptor stays open for the e2e home guard, which writes its stop
+ * line where the start line went (PRD §12), until `probeControlClose`.
+ */
+export const probeStartScript = `{ echo ${probeCommandStartLine} >&${probeControlFd}; } 2>/dev/null || echo ${probeCommandStartLine}; `;
+/** Closes the control descriptor before the probe command, so the command does not inherit it. */
+export const probeControlClose = `exec ${probeControlFd}>&-; `;
+/**
+ * The redirection a probe script gives the command it `exec`s: a placeholder that a named-pipe
+ * capture replaces with its two pipes' quoted paths once it has made them (`named-pipes.ts`).
+ * The paths are never in the login shell's environment, so nothing its startup files run is
+ * told where the probe's output goes.
+ */
+export const probeOutputRedirect = ">%elwood-probe-stdout% 2>%elwood-probe-stderr%";
+/**
+ * Removes the user's not-found handlers before the probe command runs: zsh's
+ * `command_not_found_handler` and bash's `command_not_found_handle`. A shell that finds no
+ * command runs its handler, so its output would be captured as the command's, and the status
+ * the handler returns would replace the 127 that tells preflight the CLI is missing. Each
+ * shell ignores the other's name, and a failed `unset` cannot end the shell under `errexit`.
+ */
+export const probeNotFoundHandlerReset = "unset -f command_not_found_handler command_not_found_handle 2>/dev/null || :; ";
+/** Whether a probe runs a script that announces its command with the start line. */
+export function announcesStart(args) {
+    return args.at(-1)?.startsWith(probeStartScript) ?? false;
+}
+const startText = `${probeCommandStartLine}\n`;
+const startBytes = Buffer.from(startText);
+/** Watches both channels; the first to carry the start line starts the command. */
+export class ProbeStart {
+    // One watcher per channel: a channel added to `ProbeStartChannel` must be given its own.
+    watchers = {
+        control: new StreamMarkerWatcher(startBytes),
+        stdout: new StreamMarkerWatcher(startBytes),
+    };
+    /** Whether any channel has carried the start line. */
+    get started() {
+        return Object.values(this.watchers).some((watcher) => watcher.seen);
+    }
+    /** True exactly once across both channels: for the chunk that completes the start line. */
+    feed(channel, chunk) {
+        if (this.started)
+            return false; // later copies are the command's own output
+        return this.watchers[channel].feed(chunk);
+    }
+    /** Removes the start line from captured stdout if the shell wrote it there (C-PERF-05). */
+    stripFromStdout(captured) {
+        return this.watchers.stdout.seen ? captured.replace(startText, "") : captured;
+    }
+}
+//# sourceMappingURL=start.js.map

package/dist/runtime/probe/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../../../src/runtime/probe/start.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,8BAA8B,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AAEpG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,qBAAqB,MAAM,cAAc,2BAA2B,qBAAqB,IAAI,CAAC;AAExI,kGAAkG;AAClG,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,cAAc,OAAO,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,gDAAgD,CAAC;AAEpF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GACpC,gFAAgF,CAAC;AAEnF,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,IAAuB;IACpD,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,gBAAgB,CAAC,IAAI,KAAK,CAAC;AAC5D,CAAC;AAED,MAAM,SAAS,GAAG,GAAG,qBAAqB,IAAI,CAAC;AAC/C,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAK1C,mFAAmF;AACnF,MAAM,OAAO,UAAU;IACrB,yFAAyF;IACxE,QAAQ,GAA6D;QACpF,OAAO,EAAE,IAAI,mBAAmB,CAAC,UAAU,CAAC;QAC5C,MAAM,EAAE,IAAI,mBAAmB,CAAC,UAAU,CAAC;KAC5C,CAAC;IAEF,sDAAsD;IACtD,IAAI,OAAO;QACT,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC;IAED,2FAA2F;IAC3F,IAAI,CAAC,OAA0B,EAAE,KAAa;QAC5C,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC,CAAC,4CAA4C;QAC5E,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED,2FAA2F;IAC3F,eAAe,CAAC,QAAgB;QAC9B,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAChF,CAAC;CACF"}

package/dist/runtime/probe-cache.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A keyed cache for probe results that stays bounded for a long-lived host. Implements the
+ * per-process version and capability caches of PRD §9.2 (C-PERF-02) and the
+ * never-cache-a-rejection rule of C-LIFE-11.
+ */
+export type ProbeCache<T> = {
+    /** The cached or in-flight result for `key`, else the result of a new `run()`. */
+    readonly get: (key: string, run: () => Promise<T>) => Promise<T>;
+    readonly clear: () => void;
+};
+/**
+ * Concurrent callers for one key share its single in-flight run, which is never evicted. Only
+ * the `maxSettledSuccesses` most recently used SUCCESSES are kept once settled; the least
+ * recently used goes first. In-flight runs do not count toward that bound. A rejection, or a value `succeeded` refuses (a probe that resolves with its failure),
+ * is never kept, so a failure cannot poison later callers. A run that settles after `clear()`
+ * is dropped rather than cached.
+ */
+export declare function createProbeCache<T>(maxSettledSuccesses: number, succeeded?: (value: T) => boolean): ProbeCache<T>;
+//# sourceMappingURL=probe-cache.d.ts.map

package/dist/runtime/probe-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-cache.d.ts","sourceRoot":"","sources":["../../src/runtime/probe-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,mBAAmB,EAAE,MAAM,EAC3B,SAAS,GAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAoB,GAC5C,UAAU,CAAC,CAAC,CAAC,CAwCf"}

package/dist/runtime/probe-cache.js

@@ -0,0 +1,56 @@
+/**
+ * A keyed cache for probe results that stays bounded for a long-lived host. Implements the
+ * per-process version and capability caches of PRD §9.2 (C-PERF-02) and the
+ * never-cache-a-rejection rule of C-LIFE-11.
+ */
+/**
+ * Concurrent callers for one key share its single in-flight run, which is never evicted. Only
+ * the `maxSettledSuccesses` most recently used SUCCESSES are kept once settled; the least
+ * recently used goes first. In-flight runs do not count toward that bound. A rejection, or a value `succeeded` refuses (a probe that resolves with its failure),
+ * is never kept, so a failure cannot poison later callers. A run that settles after `clear()`
+ * is dropped rather than cached.
+ */
+export function createProbeCache(maxSettledSuccesses, succeeded = () => true) {
+    const running = new Map();
+    // Map order is recency order: a hit is re-inserted at the end, eviction takes the front.
+    const settled = new Map();
+    const get = (key, run) => {
+        const hit = settled.get(key);
+        if (hit) {
+            settled.delete(key);
+            settled.set(key, hit);
+            return Promise.resolve(hit.value);
+        }
+        const existing = running.get(key);
+        if (existing)
+            return existing;
+        const pending = run();
+        running.set(key, pending);
+        const current = () => running.get(key) === pending;
+        pending.then((value) => {
+            if (!current())
+                return;
+            running.delete(key);
+            if (!succeeded(value))
+                return;
+            settled.set(key, { value });
+            for (const oldest of settled.keys()) {
+                if (settled.size <= maxSettledSuccesses)
+                    break;
+                settled.delete(oldest);
+            }
+        }, () => {
+            if (current())
+                running.delete(key);
+        });
+        return pending;
+    };
+    return {
+        get,
+        clear: () => {
+            running.clear();
+            settled.clear();
+        },
+    };
+}
+//# sourceMappingURL=probe-cache.js.map

package/dist/runtime/probe-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-cache.js","sourceRoot":"","sources":["../../src/runtime/probe-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,mBAA2B,EAC3B,YAAmC,GAAG,EAAE,CAAC,IAAI;IAE7C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC9C,yFAAyF;IACzF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAiC,CAAC;IACzD,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,GAAqB,EAAc,EAAE;QAC7D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,GAAG,EAAE,CAAC;YACR,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACtB,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC1B,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC;QACnD,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE;YACR,IAAI,CAAC,OAAO,EAAE;gBAAE,OAAO;YACvB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;gBAAE,OAAO;YAC9B,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAC5B,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;gBACpC,IAAI,OAAO,CAAC,IAAI,IAAI,mBAAmB;oBAAE,MAAM;gBAC/C,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;QACH,CAAC,EACD,GAAG,EAAE;YACH,IAAI,OAAO,EAAE;gBAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACrC,CAAC,CACF,CAAC;QACF,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IACF,OAAO;QACL,GAAG;QACH,KAAK,EAAE,GAAG,EAAE;YACV,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/runtime/readiness/initial-ready.d.ts

@@ -1,5 +1,5 @@
 /**
- * Shared hook-backed initial-readiness marker with a starvation deadline.
+ * Shared hook-backed initial-readiness marker with a two-stage starvation deadline.
  * Implements PRD §5.3/§9.4, C-API-19, and C-API-28.
  *
  * On a COLD start both adapters gate the first queued message on a pre-input
@@ -15,7 +15,8 @@
  * Claude's `InstructionsLoaded` DOES re-fire — so a resumed Claude is a hook/composer
  * race, whichever arrives first (readiness is idempotent). `armDeadline` is the ultimate
  * fallback for both start and resume so a missing readiness signal never starves the
- * queue forever.
+ * queue forever: its deadline marks onto a configured composer, and its backstop marks
+ * regardless.
  */
 export type InitialReady = {
     /** Permanently cancel readiness, including frames drained after process exit. */
@@ -25,8 +26,9 @@ export type InitialReady = {
     /** Fire readiness now (one-shot) — the pre-input readiness hook path. */
     readonly mark: () => void;
     /**
-     * Re-attempt a deferred hook/deadline mark once the composite readiness hold
-     * releases: a dialog must clear to a nonblocking idle composer (C-API-28).
+     * Per rendered frame: re-attempt a hook/deadline mark the composite readiness hold
+     * deferred, once it releases (a dialog must clear to a nonblocking idle composer), or
+     * a deadline mark still waiting for a configured composer (C-API-28).
      */
     readonly retryWhenReleased: (readinessHeld: boolean) => void;
 };
@@ -47,5 +49,29 @@ export type ComposerReadyFacts = {
  * composer stays an unsafe signal there (C-API-28).
  */
 export declare function markReadyOnResumeComposer(ready: Pick<InitialReady, "mark">, resumed: boolean, facts: ComposerReadyFacts, readinessHeld?: boolean): void;
-export declare function initialReady(callback: () => void, maxWaitMs?: number, isReadinessHeld?: () => boolean): InitialReady;
+/**
+ * Twice the longest measured Codex 0.164 trust-gate delay (30.6 s after first output,
+ * docs/cli-behavior.md): readiness without a configured composer this long after the
+ * first frame is no longer racing a late gate (C-API-28).
+ */
+export declare const initialBackstopMs = 60000;
+/** An adapter's evidence that a rendered composer belongs to a configured session. */
+export type ConfiguredComposerEvidence = {
+    /** The latest frame shows a configured session's composer outside any blocking dialog. */
+    readonly shown: () => boolean;
+    /** Readiness was released after the backstop without that composer on screen. */
+    readonly onBackstopRelease: () => void;
+    readonly backstopMs?: number;
+};
+/**
+ * With `composer` evidence, the initial deadline marks only onto a frame showing a
+ * configured session's composer: a CLI that has not configured its session is still
+ * booting, and under load can paint a trust gate after the deadline, so an earlier mark
+ * would drain the queue into the boot screen or that gate. A deadline that expires first
+ * waits for that frame, and the backstop after the first frame marks anyway, so an
+ * unrecognized composer delays readiness but never starves it. A release after the
+ * backstop without that composer is reported once through `onBackstopRelease`, so a host
+ * can tell it from ordinary readiness (C-API-28).
+ */
+export declare function initialReady(callback: () => void, initialDeadlineMs?: number, isReadinessHeld?: () => boolean, composer?: ConfiguredComposerEvidence): InitialReady;
 //# sourceMappingURL=initial-ready.d.ts.map

package/dist/runtime/readiness/initial-ready.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initial-ready.d.ts","sourceRoot":"","sources":["../../../src/runtime/readiness/initial-ready.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,YAAY,GAAG;IACzB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;IACjC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAAC,aAAa,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9D,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,sFAAsF;IACtF,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;CAC3C,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,EACjC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,kBAAkB,EACzB,aAAa,UAAQ,GACpB,IAAI,CAGN;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,IAAI,EACpB,SAAS,SAAS,EAClB,eAAe,GAAE,MAAM,OAAqB,GAC3C,YAAY,CA+Cd"}
+{"version":3,"file":"initial-ready.d.ts","sourceRoot":"","sources":["../../../src/runtime/readiness/initial-ready.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,YAAY,GAAG;IACzB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;IACjC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAAC,aAAa,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9D,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,sFAAsF;IACtF,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;CAC3C,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,EACjC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,kBAAkB,EACzB,aAAa,UAAQ,GACpB,IAAI,CAGN;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC,sFAAsF;AACtF,MAAM,MAAM,0BAA0B,GAAG;IACvC,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,IAAI,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,IAAI,EACpB,iBAAiB,SAAS,EAC1B,eAAe,GAAE,MAAM,OAAqB,EAC5C,QAAQ,CAAC,EAAE,0BAA0B,GACpC,YAAY,CAyEd"}

package/dist/runtime/readiness/initial-ready.js

@@ -1,5 +1,5 @@
 /**
- * Shared hook-backed initial-readiness marker with a starvation deadline.
+ * Shared hook-backed initial-readiness marker with a two-stage starvation deadline.
  * Implements PRD §5.3/§9.4, C-API-19, and C-API-28.
  *
  * On a COLD start both adapters gate the first queued message on a pre-input
@@ -15,7 +15,8 @@
  * Claude's `InstructionsLoaded` DOES re-fire — so a resumed Claude is a hook/composer
  * race, whichever arrives first (readiness is idempotent). `armDeadline` is the ultimate
  * fallback for both start and resume so a missing readiness signal never starves the
- * queue forever.
+ * queue forever: its deadline marks onto a configured composer, and its backstop marks
+ * regardless.
  */
 /**
  * On RESUME, mark readiness on the first genuine composer frame: the composer is
@@ -30,11 +31,45 @@ export function markReadyOnResumeComposer(ready, resumed, facts, readinessHeld =
     if (resumed && facts.composer_visible && !facts.blocking_prompt_visible && !readinessHeld)
         ready.mark();
 }
-export function initialReady(callback, maxWaitMs = 10_000, isReadinessHeld = () => false) {
+/**
+ * Twice the longest measured Codex 0.164 trust-gate delay (30.6 s after first output,
+ * docs/cli-behavior.md): readiness without a configured composer this long after the
+ * first frame is no longer racing a late gate (C-API-28).
+ */
+export const initialBackstopMs = 60_000;
+/**
+ * With `composer` evidence, the initial deadline marks only onto a frame showing a
+ * configured session's composer: a CLI that has not configured its session is still
+ * booting, and under load can paint a trust gate after the deadline, so an earlier mark
+ * would drain the queue into the boot screen or that gate. A deadline that expires first
+ * waits for that frame, and the backstop after the first frame marks anyway, so an
+ * unrecognized composer delays readiness but never starves it. A release after the
+ * backstop without that composer is reported once through `onBackstopRelease`, so a host
+ * can tell it from ordinary readiness (C-API-28).
+ */
+export function initialReady(callback, initialDeadlineMs = 10_000, isReadinessHeld = () => false, composer) {
+    const isComposerConfigured = () => composer === undefined || composer.shown();
     let ready = false;
     let cancelled = false;
     let deferredByHold = false;
+    let awaitingComposer = false;
+    let backstopFired = false;
     let deadline;
+    let backstop;
+    /**
+     * Timer marks are contained. A mark whose callback throws leaves `ready` false; a later
+     * readiness hook, or for the deadline the backstop, retries it.
+     */
+    const markFromTimer = (composerRequired) => {
+        try {
+            awaitingComposer = composerRequired && !isComposerConfigured();
+            if (!awaitingComposer)
+                mark();
+        }
+        catch {
+            // Retried by a later readiness hook or timer, as above.
+        }
+    };
     const mark = () => {
         if (ready || cancelled)
             return;
@@ -47,39 +82,50 @@ export function initialReady(callback, maxWaitMs = 10_000, isReadinessHeld = ()
             return;
         }
         deferredByHold = false;
+        const withoutComposer = composer !== undefined && backstopFired && !composer.shown();
         // Latch AFTER the callback returns, so if it throws (a throwing status/activity
         // listener) readiness is NOT consumed and a later hook/deadline/frame retries —
         // a failed transition must never permanently starve the queue (C-API-28).
         callback();
         ready = true;
+        clearTimeout(deadline);
+        clearTimeout(backstop);
+        try {
+            if (withoutComposer)
+                composer.onBackstopRelease();
+        }
+        catch {
+            // A failing warning sink must not undo or block the readiness just released.
+        }
     };
     return {
         cancel: () => {
             cancelled = true;
-            if (deadline)
-                clearTimeout(deadline);
+            clearTimeout(deadline);
+            clearTimeout(backstop);
         },
         mark,
         retryWhenReleased: (readinessHeld) => {
-            if (!ready && deferredByHold && !readinessHeld)
+            if (ready || readinessHeld)
+                return;
+            // A hold-deferred mark retries once the hold releases; a deadline that expired
+            // before the configured composer retries on the first frame showing it, even
+            // while work is on screen.
+            if (deferredByHold || (awaitingComposer && isComposerConfigured()))
                 mark();
         },
         replay: () => void (!cancelled && ready && callback()),
         // Arms on the first frame regardless of hook arrival, so a missing or failed
-        // readiness hook cannot starve readiness forever. The deadline's mark is contained
-        // (a throwing callback on a timer would otherwise be an uncaught exception); if it
-        // fails, `ready` stays false so a later hook or composer frame still retries.
+        // readiness hook cannot starve readiness forever. Timer marks are contained (a
+        // throwing callback on a timer would otherwise be an uncaught exception).
         armDeadline: () => {
-            if (cancelled)
+            if (cancelled || ready)
                 return;
-            deadline ??= setTimeout(() => {
-                try {
-                    mark();
-                }
-                catch {
-                    // Retried by a subsequent readiness hook or rendered composer frame.
-                }
-            }, maxWaitMs);
+            deadline ??= setTimeout(() => markFromTimer(true), initialDeadlineMs);
+            backstop ??= setTimeout(() => {
+                backstopFired = true;
+                markFromTimer(false);
+            }, composer?.backstopMs ?? initialBackstopMs);
         },
     };
 }