toolroll 0.9.52 → 0.9.53

package/dist/exec.js

@@ -9,8 +9,7 @@
 import { linuxFenceAvailable, linuxFenced, macosFenceAvailable, macosFenced } from "./agent-fence.js";
 import { execFile, spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { observeProcessTree, stopProcessTree, readProcessObservationFailure } from "./process-tree.js";
+import { observeProcessTree, stopProcessTree } from "./process-tree.js";
 import { jsonlDiscriminants } from "./jsonl-discriminants.js";
 import { createContainer, currentContainment } from "./containment.js";
 import { claudeLimitsOf, noteLimits } from "./provider-limits.js";
@@ -63,8 +62,8 @@ function rejectedChild(error, child) {
     return error instanceof SpawnCustodyFailure ? error.child : child;
 }
 /**
- * The ONE spawn road for containable children (buffered, streaming and
- * held transports): consult the pinned policy, make this spawn's OS
+ * The ONE spawn road for containable children (buffered and streaming
+ * transports): consult the pinned policy, make this spawn's OS
  * object, spawn the target INSIDE it, and register the object beside the
  * handle. Under observed containment this is exactly the old spawn. A
  * required policy that cannot be met throws ContainmentRefusal here —
@@ -274,15 +273,6 @@ export function terminateOwnedProcesses(owner) {
     }
     return terminated;
 }
-/**
- * Live held-session SUPERVISORS (v6 W7). Not in liveProviders: SIGKILLing a
- * supervisor's group would orphan the agent living in its own fresh group.
- * The sweep's contract here is SIGTERM first — the supervisor's handler
- * fences its child (EOF → grace → group SIGKILL) — and SIGKILL only on a
- * repeat sweep, which is the one road that can orphan an agent and is why
- * it is the escalation, never the opener.
- */
-const heldSupervisors = new Map();
 /** SIGKILL the child's whole process group; fall back to the child alone. */
 function killGroup(child) {
     const container = containers.get(child);
@@ -346,28 +336,6 @@ export function terminateLiveProviders() {
         killGroup(child);
         terminated += 1;
     }
-    // Held supervisors take the graceful road first (v6 W7): SIGTERM makes
-    // the supervisor fence its own agent race-free through the handle only
-    // it holds. A second sweep escalates to SIGKILL — the documented
-    // residual hole, reachable only by double-escalation, with the startup
-    // orphan fence paging for anything that lingers.
-    for (const [supervisor, stage] of heldSupervisors) {
-        try {
-            if (stage === "fresh") {
-                supervisor.kill("SIGTERM");
-                heldSupervisors.set(supervisor, "termed");
-            }
-            else {
-                // With a native OS object the escalation reaches the agent too:
-                // the object's kill is the one road that cannot orphan it.
-                killGroup(supervisor);
-            }
-        }
-        catch {
-            // Already gone.
-        }
-        terminated += 1;
-    }
     return terminated;
 }
 /** The one place a child's environment is decided (audit IV-5). */
@@ -1555,324 +1523,3 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
         child.on("close", code => finish(code));
     });
 }
-// ---- the held session transport (Parity II Phase 2, spec v2 S0a + v6 W9) ----
-/**
- * Where the supervisor script lives: a plain-.mjs sibling of this module in
- * BOTH layouts (src/ under tsx, dist/ after build — postbuild copies it).
- */
-export function supervisorPath() {
-    return fileURLToPath(new URL("./supervisor.mjs", import.meta.url));
-}
-/**
- * Darwin's sun_path is 104 bytes including the terminator; Linux allows a
- * hair more. Refusing at spawn beats failing inside bind() with a raw
- * ENAMETOOLONG after custody was already recorded.
- */
-export const HELD_SOCKET_PATH_LIMIT = 103;
-export function heldSocketPathProblem(path) {
-    const bytes = Buffer.byteLength(path, "utf8");
-    if (bytes > HELD_SOCKET_PATH_LIMIT) {
-        return `the control socket path is ${bytes} bytes — the platform limit is ${HELD_SOCKET_PATH_LIMIT}: ${path}`;
-    }
-    return null;
-}
-/**
- * Hold one claude process open across stream-json turns, under a
- * supervisor whose parenthood makes the eventual kill provable. Returns
- * once the supervisor's control frame settles the spawn either way.
- *
- * No timers live here: the per-turn wall deadline, liveness lapse, and
- * absolute expiry are the coordinator's exact timers (v2 S1d) — this
- * transport only moves bytes and counts the protocol's own marks.
- */
-export function startClaudeHeldSession(file, args, options) {
-    const pathProblem = heldSocketPathProblem(options.socketPath);
-    if (pathProblem !== null) {
-        return Promise.resolve({ ok: false, reason: "socket-path", message: pathProblem });
-    }
-    const childEnv = resolveChildEnv(options) ?? { ...process.env };
-    const events = options.events ?? {};
-    return new Promise(resolveStart => {
-        let supervisor;
-        let container = null;
-        let attachFailure = null;
-        try {
-            // The supervisor spawns INSIDE the OS object, so the agent it holds
-            // and every tool the agent launches are members too: one kill reaches
-            // the whole hold, and the object's empty state proves the hold over.
-            const spawned = spawnContained(process.execPath, [supervisorPath(), file, ...args], {
-                cwd: options.cwd,
-                env: {
-                    ...childEnv,
-                    SO_HELD_SOCKET: options.socketPath,
-                    SO_HELD_COOKIE: options.cookie,
-                    SO_HELD_GRACE_MS: String(options.graceMs ?? 10_000),
-                    SO_HELD_DIAGNOSTIC_FD: currentContainment().mode === "observed" ? "3" : "",
-                },
-                stdio: currentContainment().mode === "observed" ? ["pipe", "pipe", "pipe", "pipe"] : ["pipe", "pipe", "pipe"],
-                detached: false,
-            }, options.owner ?? "held", {
-                beforeSpawn: options.beforeSpawn,
-                onSpawn: options.onSpawn,
-                onSpawnFailed: options.onSpawnFailed,
-                onContainer: options.onContainer,
-                onContainerEmpty: options.onContainerEmpty,
-                onUnknown: options.onUnknown,
-                fence: options.fence,
-            });
-            supervisor = spawned.child;
-            container = spawned.container;
-            void spawned.attached.then(outcome => { if (!outcome.ok)
-                attachFailure = outcome.detail; });
-            if (container === null)
-                observeProcessTree(supervisor, options);
-        }
-        catch (error) {
-            const left = rejectedChild(error, supervisor);
-            const refused = () => resolveStart({ ok: false, reason: "spawn-failed", message: String(error instanceof SpawnCustodyFailure ? error.reason : error) });
-            if (left === undefined)
-                refused();
-            else {
-                left.once("close", refused);
-                left.on("error", () => { });
-                killGroup(left);
-            }
-            return;
-        }
-        // This pipe belongs to the supervisor, not the agent's relayed stream.
-        // Native containment uses its existing attachment descriptors instead.
-        if (container === null) {
-            const diagnostics = supervisor.stdio[3];
-            let buffer = "", reportedFault = false;
-            const diagnosticFault = () => {
-                if (reportedFault)
-                    return;
-                reportedFault = true;
-                // This channel carries diagnostics only. Its failure cannot invent
-                // lost child identity; genuine supervisor uncertainty still exits126.
-                try {
-                    options.onObservationFailure?.({ phase: "supervisor", operation: "diagnostic-read", code: "SUPERVISOR_DIAGNOSTIC", rootPid: supervisor.pid ?? null, at: new Date().toISOString(), identityUnknown: false });
-                }
-                catch { }
-            };
-            if (diagnostics !== null && diagnostics !== undefined && "on" in diagnostics) {
-                diagnostics.on("data", (chunk) => {
-                    buffer += chunk.toString("utf8");
-                    if (buffer.length > 16_384) {
-                        buffer = "";
-                        diagnosticFault();
-                        return;
-                    }
-                    let cut;
-                    while ((cut = buffer.indexOf("\n")) !== -1) {
-                        const line = buffer.slice(0, cut);
-                        buffer = buffer.slice(cut + 1);
-                        let failure = null;
-                        try {
-                            failure = readProcessObservationFailure(JSON.parse(line));
-                        }
-                        catch { }
-                        if (failure === null) {
-                            diagnosticFault();
-                            continue;
-                        }
-                        try {
-                            options.onObservationFailure?.(failure);
-                        }
-                        catch { /* No diagnostic can certify exit or clear an existing witness. */ }
-                    }
-                });
-                diagnostics.on("error", diagnosticFault);
-                diagnostics.on("end", () => { if (buffer !== "")
-                    diagnosticFault(); });
-            }
-        }
-        heldSupervisors.set(supervisor, "fresh");
-        let settledStart = false;
-        let agentPgid = null;
-        let initSeq = 0;
-        let resultSeq = 0;
-        let sessionSeen = false;
-        let partial = "";
-        let exitResolve = () => { };
-        const exited = new Promise(pass => {
-            exitResolve = pass;
-        });
-        const readyTimer = setTimeout(() => {
-            if (settledStart)
-                return;
-            settledStart = true;
-            try {
-                killGroup(supervisor);
-            }
-            catch {
-                // Already gone.
-            }
-            resolveStart({ ok: false, reason: "ready-timeout", message: "the supervisor never sent its control frame" });
-        }, options.readyTimeoutMs ?? 10_000);
-        const handle = {
-            supervisorPid: null,
-            agentPgid: null,
-            writeTurn(json) {
-                const stdin = supervisor.stdin;
-                if (stdin === null || stdin.destroyed || !stdin.writable)
-                    return false;
-                try {
-                    stdin.write(json.endsWith("\n") ? json : `${json}\n`);
-                    return true;
-                }
-                catch {
-                    return false;
-                }
-            },
-            endInput() {
-                try {
-                    supervisor.stdin?.end();
-                }
-                catch {
-                    // Already closed.
-                }
-            },
-            terminate() {
-                try {
-                    supervisor.kill("SIGTERM");
-                    heldSupervisors.set(supervisor, "termed");
-                }
-                catch {
-                    // Already gone.
-                }
-            },
-            killHard() {
-                try {
-                    killGroup(supervisor);
-                }
-                catch {
-                    // Already gone.
-                }
-            },
-            exited,
-        };
-        const keep = (line) => {
-            if (line.length > JSONL_LINE_CAP)
-                return;
-            let event;
-            try {
-                event = JSON.parse(line);
-            }
-            catch {
-                return;
-            }
-            if (event === null || typeof event !== "object")
-                return;
-            // The control frame settles the start, exactly once, before any
-            // agent byte — the two-hop handshake (v6 W9).
-            if (!settledStart && typeof event["so_supervisor"] === "string") {
-                settledStart = true;
-                clearTimeout(readyTimer);
-                if (event["so_supervisor"] === "ready") {
-                    agentPgid = typeof event["agentPgid"] === "number" ? event["agentPgid"] : null;
-                    handle.agentPgid = agentPgid;
-                    handle.supervisorPid =
-                        typeof event["supervisorPid"] === "number" ? event["supervisorPid"] : (supervisor.pid ?? null);
-                    resolveStart({ ok: true, handle });
-                }
-                else {
-                    const message = typeof event["message"] === "string" ? event["message"] : "spawn failed";
-                    resolveStart({ ok: false, reason: "spawn-failed", message });
-                }
-                return;
-            }
-            if (typeof event["so_supervisor"] === "string")
-                return; // never two frames; drop strays
-            const type = String(event["type"] ?? "");
-            if (type === "system" && String(event["subtype"] ?? "") === "init") {
-                initSeq += 1;
-                if (!sessionSeen && events.onSessionId !== undefined) {
-                    const id = transportSessionId(event["session_id"]);
-                    if (id !== null) {
-                        sessionSeen = true;
-                        try {
-                            events.onSessionId(id);
-                        }
-                        catch {
-                            // A registry that cannot be written must not kill the turn.
-                        }
-                    }
-                }
-                try {
-                    events.onTurnInit?.(initSeq);
-                }
-                catch {
-                    // Observational.
-                }
-            }
-            else if (type === "rate_limit_event") {
-                noteLimits(claudeLimitsOf(event));
-            }
-            else if (type === "result" && primaryResultOrigin(event)) {
-                resultSeq += 1;
-                try {
-                    events.onTurnResult?.(resultSeq, event);
-                }
-                catch {
-                    // Observational.
-                }
-            }
-            try {
-                events.onStreamEvent?.(event);
-            }
-            catch {
-                // Observational only, arc-1 rule unchanged.
-            }
-        };
-        supervisor.stdout?.setEncoding("utf8");
-        supervisor.stdout?.on("data", (chunk) => {
-            partial += chunk;
-            let cut = partial.indexOf("\n");
-            while (cut !== -1) {
-                keep(partial.slice(0, cut));
-                partial = partial.slice(cut + 1);
-                cut = partial.indexOf("\n");
-            }
-            if (partial.length > JSONL_LINE_CAP * 2)
-                partial = partial.slice(-JSONL_LINE_CAP);
-        });
-        supervisor.on("error", error => {
-            heldSupervisors.delete(supervisor);
-            if (!settledStart) {
-                settledStart = true;
-                clearTimeout(readyTimer);
-                resolveStart({ ok: false, reason: "spawn-failed", message: String(error) });
-            }
-            exitResolve({ code: null });
-        });
-        supervisor.on("close", code => {
-            heldSupervisors.delete(supervisor);
-            if (partial.trim() !== "")
-                keep(partial);
-            // The POSIX supervisor could not prove its observed tree drained.
-            // Persist uncertainty before any onExit handler can release custody.
-            if (container === null && code === CONTAINMENT_REFUSED_CODE) {
-                try {
-                    options.onUnknown?.();
-                }
-                catch { /* the observer must not prevent settlement */ }
-            }
-            const settlement = container === null ? Promise.resolve(true) : settleContainer(container, options);
-            void settlement.then(empty => {
-                if (!settledStart) {
-                    settledStart = true;
-                    clearTimeout(readyTimer);
-                    resolveStart({ ok: false, reason: "spawn-failed", message: attachFailure ?? "the supervisor exited before its control frame" });
-                }
-                try {
-                    events.onExit?.({ code: empty ? code : CONTAINMENT_REFUSED_CODE });
-                }
-                catch {
-                    // Observational.
-                }
-                exitResolve({ code: empty ? code : CONTAINMENT_REFUSED_CODE });
-            });
-        });
-    });
-}

package/dist/exhaustion.d.ts

@@ -1,93 +1,39 @@
 /**
- * The terminal exhaustion taxonomy (fallback chains, R1/C5/C8 of the
- * approved design). A finished attempt is classified into ONE of these,
- * where the evidence still exists — the provider adapter's structural
- * record plus the gateway's authoritative CLI version and auth mode —
- * NEVER in disposal, by which time the structural signal is gone.
+ * How a finished attempt ended, classified where the evidence still exists
+ * (the provider adapter's structural terminal record), never in disposal.
+ * The one class that changes what happens next is `auth-expired`: a sign-in
+ * or API key that no longer works pauses dispatch for that provider until
+ * someone signs in, instead of burning attempts. Everything else is the
+ * ordinary failure road.
  *
- * The whole feature is FAIL CLOSED by construction: a recognizer's
- * eligible-signal set is EMPTY until a versioned fixture, captured from a
- * GENUINELY EXHAUSTED subscription, proves the exact bytes. A build with
- * no fixture for a (provider, version) can therefore NEVER return an
- * eligible class — so it can never authorize a paid fallback. A
- * successful run cannot establish the exhausted shape; only real
- * exhaustion can, and the plane cannot manufacture it.
- *
- * Precedence (C5), applied by the classifier:
- * - A present STRUCTURAL FAILURE terminal blocks success ingestion even
- *   on exit 0 (that is the parser's job; this module reads the record).
- * - Only an ALLOWLISTED, version+auth-specific pattern yields an ELIGIBLE
- *   class. Exit code, bare rate-limit prose, timeout, notFound, stderr,
- *   and zero tokens NEVER independently establish exhaustion.
- * - Everything unmatched is `unknown` — the ordinary failure road.
- * - A sign-in that no longer works (`auth-expired`) is recognized FIRST,
- *   for every provider and version: an expired or revoked login is not a
- *   property of a CLI version, and retrying it only burns attempts. It is
- *   never fallback-eligible — a lapsed login must not reach a paid key.
+ * `usage-exhausted`, `credits-depleted` and `transient-throttle` are only
+ * ever read from older runs' records (they were stamped by a removed
+ * feature); this build never produces them.
  */
-import type { ProviderId } from "./provider.js";
-export type TerminalClass = 
-/** The subscription/plan usage cap is spent — FALLBACK-ELIGIBLE. */
-"usage-exhausted"
-/** An API-key account's paid credits/quota are gone — FALLBACK-ELIGIBLE. */
- | "credits-depleted"
-/** Temporary throttling NOT tied to the usage cap — backoff, NEVER paid fallback. */
- | "transient-throttle"
-/** The provider's sign-in or API key no longer works — NO retry, NO
- * fallback: dispatch for that provider pauses until someone signs in. */
+export type TerminalClass = "usage-exhausted" | "credits-depleted" | "transient-throttle"
+/** The provider's sign-in or API key no longer works — no retry:
+ * dispatch for that provider pauses until someone signs in. */
  | "auth-expired"
-/** A definite non-exhaustion terminal (ordinary failure). */
+/** A definite structural failure terminal (ordinary failure). */
  | "not-exhausted"
-/** No structural signal matched — the ordinary failure/strike road. */
+/** No structural signal — the ordinary failure/strike road. */
  | "unknown";
-/** The two classes that may authorize a fallback advance. */
-export declare const FALLBACK_ELIGIBLE: ReadonlySet<TerminalClass>;
-export declare function isFallbackEligible(cls: TerminalClass): boolean;
 /**
- * The structural terminal a provider's parser retained — the honest input
- * to classification. `failed` marks a structural FAILURE terminal (codex
- * turn.failed, a gemini error terminal): its presence blocks success
- * ingestion regardless of exit code. `text` is the bounded terminal
- * message; `code` its machine code if the harness typed one.
+ * The structural terminal a provider's parser retained. `failed` marks a
+ * structural FAILURE terminal (codex turn.failed, a gemini error terminal):
+ * its presence blocks success ingestion regardless of exit code. `text` is
+ * the bounded terminal message; `code` its machine code if the harness
+ * typed one.
  */
 export type StructuralTerminal = {
     failed: boolean;
     text: string | null;
     code: string | null;
 };
-/** Whether THIS build carries a fixture-backed recognizer for a
- * (provider, version). The C8 gate consults this at every authority
- * point — not only at classification — so a downgrade to an unfixtured
- * build severs any in-flight fallback authority. */
-export declare function hasRecognizer(provider: ProviderId, version: string | null): boolean;
-/**
- * The EXACT C8 capability check (Codex E2/E3 review, finding 8): whether
- * this build can recognize the specific eligible class an AUTH MODE would
- * produce — a subscription's `usage-exhausted` needs a nonempty
- * eligibleUsage set; an api-key account's `credits-depleted` needs a
- * nonempty eligibleCredits set. `hasRecognizer` (any-eligible) is too coarse
- * at the authority point: a version fixtured for usage only must NOT
- * authorize a credits-depleted advance.
- */
-export declare function recognizesEligible(provider: ProviderId, version: string | null, authMode: "subscription" | "api-key"): boolean;
-/** The eligible class an auth mode can legitimately carry — the C8
- * consistency invariant: `usage-exhausted` iff subscription,
- * `credits-depleted` iff api-key. A stamp that violates this pairing is a
- * bad/overwritten record and must never advance. */
-export declare function classMatchesAuthMode(cls: TerminalClass, authMode: "subscription" | "api-key"): boolean;
-/**
- * Classify a finished attempt. Fail closed: no recognizer for this exact
- * (provider, version) => never an eligible class. `authMode` decides which
- * eligible class a match yields — a subscription that hits its cap is
- * `usage-exhausted`; an api-key account out of credits is
- * `credits-depleted`. A structural failure with no eligible/transient
- * match is `not-exhausted`; no structural failure and no match is
- * `unknown`.
- */
+/** Classify a finished attempt: a sign-in that no longer works first, for
+ * any provider or version; then a structural failure terminal is
+ * `not-exhausted`, and anything else `unknown`. */
 export declare function classifyTerminal(args: {
-    provider: ProviderId;
-    version: string | null;
-    authMode: "subscription" | "api-key";
     terminal: StructuralTerminal | null;
     /** What a run that failed within seconds, having produced nothing, said
      * on its way out (stderr and unstructured stdout) — read ONLY for the