comisai 1.0.45 → 1.0.46

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-preflight.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `orchestrate-preflight` — three pure, total static-analysis helpers for the
+ * orchestrate PTC runner. No eval, no fs, no net: a TS-tolerant token scan over
+ * the model-authored script (read as INERT TEXT — it is neither run nor an
+ * injection sink) plus two total string projections.
+ *
+ *   - {@link extractCapabilityFootprint} — scans `comis_tools.<method>(` call
+ *     sites and maps each method to its {@link AgentCapability} via
+ *     `TOOL_CAPABILITY_MAP` (the single source of truth). Whitespace/newline
+ *     tolerant across the `comis_tools . method` boundary; the ts/js floor is
+ *     the `comis_tools.<m>(` form (a python `from comis_tools import x` bare
+ *     call is out of the floor and falls through to the endpoint). Methods not
+ *     in the cap-map are REPORTED as data (`unknownMethods`), never thrown.
+ *   - {@link classifyRecoverableStderr} — projects a bounded, already-scrubbed
+ *     stderr tail onto a CLOSED recoverable class (or `undefined`); it never
+ *     executes or reflects the tail.
+ *   - {@link buildDescribeDigest} — a deterministic name+capability projection
+ *     of `TOOL_CAPABILITY_MAP` for the repair prompt (no clock/random).
+ *
+ * ADVISORY ONLY: this module REPORTS a footprint + a class — it grants nothing.
+ * The authoritative deny stays at the jail cap-socket endpoint (default-deny by
+ * absence); a script that obfuscates or dodges the scan is still denied there.
+ * Pure: no I/O, no globals, no ambient state; total over any finite input.
+ *
+ * @module
+ */
+import { type AgentCapability } from "@comis/core";
+/** The declared capability footprint of a script: the caps, the known methods, the ordered call-site sequence, the unknowns. */
+export interface CapabilityFootprint {
+    /** The distinct {@link AgentCapability} values the script's call sites require. */
+    readonly caps: ReadonlySet<AgentCapability>;
+    /** The sorted, deduped cap-mapped method names the script calls. */
+    readonly methods: readonly string[];
+    /**
+     * The source-ordered call-site sequence of cap-mapped methods — repeats
+     * PRESERVED (= per-method call counts), bounded by {@link SEQUENCE_CAP}.
+     * Content-free: method NAMES only (never args/values/bodies).
+     */
+    readonly sequence: readonly string[];
+    /** The sorted, deduped `comis_tools.<x>(` methods NOT in the cap-map (advisory). */
+    readonly unknownMethods: readonly string[];
+}
+/**
+ * Statically extract the capability footprint of a model-authored script by
+ * scanning its `comis_tools.<method>(` call sites and mapping each method to its
+ * required capability via `TOOL_CAPABILITY_MAP`. Reads the script as inert text
+ * (no eval/fs/net). Total: an unknown method is DATA in `unknownMethods`, never
+ * an error; a script with no call sites yields empty results. Also yields the
+ * source-ordered `sequence` (cap-mapped call sites, repeats preserved = per-method
+ * counts, capped at {@link SEQUENCE_CAP}) beside the sorted/deduped `methods` SET.
+ */
+export declare function extractCapabilityFootprint(script: string): CapabilityFootprint;
+/**
+ * Classify a bounded stderr tail into a known-recoverable failure class, or
+ * `undefined` for anything else. Ordered first-match: `bad_import` (a missing
+ * module/package/import), then `comis_tools_misuse` (a `comis_tools` reference
+ * paired with a Type/Attribute error shape), then `syntax_error` (a malformed
+ * script body — the most frequent weak-model authoring failure; Node and Python
+ * both emit the exact token `SyntaxError`), then the generic `type_error`. The
+ * misuse class is tested BEFORE `syntax_error`/`type_error` so a `comis_tools`
+ * TypeError classifies as misuse; `syntax_error` is kept a DISTINCT class (not
+ * folded into a generic bucket) so its one-shot-repair success rate stays
+ * separately observable. The classes are disjoint in practice (a SyntaxError tail
+ * carries no Import/Type/Attribute token), so a `comis_tools` SyntaxError still
+ * classifies as `syntax_error`, not misuse. Case-sensitive: the token names are
+ * engine-emitted. Pure: a bounded regex projection — it never executes or reflects
+ * the tail. A repaired script re-runs in the SAME jail, so a bad regeneration
+ * still fails closed at the cap-socket endpoint.
+ */
+export declare function classifyRecoverableStderr(tail: string): "bad_import" | "comis_tools_misuse" | "syntax_error" | "type_error" | undefined;
+/**
+ * Build a deterministic, bounded digest of the available `comis_tools` methods
+ * grouped by the capability each requires — a pure projection of
+ * `TOOL_CAPABILITY_MAP` the repair prompt hands the utility model. Caps and the
+ * methods within each are sorted, so two calls are byte-identical (no
+ * clock/random). The `orch:*` cap identifiers and method names are real code
+ * identifiers (kept verbatim).
+ */
+export declare function buildDescribeDigest(): string;

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-preflight.js

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `orchestrate-preflight` — three pure, total static-analysis helpers for the
+ * orchestrate PTC runner. No eval, no fs, no net: a TS-tolerant token scan over
+ * the model-authored script (read as INERT TEXT — it is neither run nor an
+ * injection sink) plus two total string projections.
+ *
+ *   - {@link extractCapabilityFootprint} — scans `comis_tools.<method>(` call
+ *     sites and maps each method to its {@link AgentCapability} via
+ *     `TOOL_CAPABILITY_MAP` (the single source of truth). Whitespace/newline
+ *     tolerant across the `comis_tools . method` boundary; the ts/js floor is
+ *     the `comis_tools.<m>(` form (a python `from comis_tools import x` bare
+ *     call is out of the floor and falls through to the endpoint). Methods not
+ *     in the cap-map are REPORTED as data (`unknownMethods`), never thrown.
+ *   - {@link classifyRecoverableStderr} — projects a bounded, already-scrubbed
+ *     stderr tail onto a CLOSED recoverable class (or `undefined`); it never
+ *     executes or reflects the tail.
+ *   - {@link buildDescribeDigest} — a deterministic name+capability projection
+ *     of `TOOL_CAPABILITY_MAP` for the repair prompt (no clock/random).
+ *
+ * ADVISORY ONLY: this module REPORTS a footprint + a class — it grants nothing.
+ * The authoritative deny stays at the jail cap-socket endpoint (default-deny by
+ * absence); a script that obfuscates or dodges the scan is still denied there.
+ * Pure: no I/O, no globals, no ambient state; total over any finite input.
+ *
+ * @module
+ */
+import { TOOL_CAPABILITY_MAP } from "@comis/core";
+/**
+ * Match a `comis_tools.<ident>(` call site — the ts/js floor. `\s*` around the
+ * dot makes it tolerant of newlines/indentation between `comis_tools`, `.`, and
+ * the method; the capture group is the method identifier.
+ */
+const CALL_SITE_RE = /\bcomis_tools\s*\.\s*([A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
+/**
+ * Match an MCP proxy call site `comis_tools.mcp.<server>.<tool>(` — the SDK's sole
+ * path to a connected MCP tool. The flat {@link CALL_SITE_RE} misses it: the ident
+ * after `comis_tools` is "mcp", followed by "." (the server), not "(". This site
+ * maps to the fixed method name "mcp" (→ `orch:mcp`), identical to a direct
+ * `comis_tools.mcp(` call. The bracket form (`comis_tools.mcp["s"]["t"]()`) is a
+ * dynamic call the static scan intentionally leaves to the endpoint gate (fail-safe).
+ */
+const MCP_PROXY_RE = /\bcomis_tools\s*\.\s*mcp\s*\.\s*[A-Za-z_][A-Za-z0-9_]*\s*\.\s*[A-Za-z_][A-Za-z0-9_]*\s*\(/g;
+/**
+ * Upper bound on {@link CapabilityFootprint.sequence} — it keeps the first N
+ * cap-mapped call sites in source order. Bounds the content-free descriptor so a
+ * pathological script cannot bloat it (a security bound, not a correctness one).
+ */
+const SEQUENCE_CAP = 64;
+/**
+ * Statically extract the capability footprint of a model-authored script by
+ * scanning its `comis_tools.<method>(` call sites and mapping each method to its
+ * required capability via `TOOL_CAPABILITY_MAP`. Reads the script as inert text
+ * (no eval/fs/net). Total: an unknown method is DATA in `unknownMethods`, never
+ * an error; a script with no call sites yields empty results. Also yields the
+ * source-ordered `sequence` (cap-mapped call sites, repeats preserved = per-method
+ * counts, capped at {@link SEQUENCE_CAP}) beside the sorted/deduped `methods` SET.
+ */
+export function extractCapabilityFootprint(script) {
+    const caps = new Set();
+    const methods = new Set();
+    const sequence = [];
+    const unknownMethods = new Set();
+    // Collect both call-site shapes — the flat `comis_tools.<method>(` floor and the
+    // MCP proxy `comis_tools.mcp.<server>.<tool>(` — in a SINGLE source-ordered pass,
+    // so the descriptor `sequence` stays faithful when a script interleaves them. The
+    // proxy site records the fixed method name "mcp" (→ orch:mcp). A proxy site never
+    // also matches CALL_SITE_RE (the "mcp" ident is followed by ".", not "("), so no
+    // site is double-counted.
+    const hits = [];
+    for (const m of script.matchAll(CALL_SITE_RE))
+        hits.push({ index: m.index ?? 0, method: m[1] });
+    for (const m of script.matchAll(MCP_PROXY_RE))
+        hits.push({ index: m.index ?? 0, method: "mcp" });
+    hits.sort((a, b) => a.index - b.index);
+    for (const { method } of hits) {
+        const cap = TOOL_CAPABILITY_MAP[method];
+        if (cap) {
+            caps.add(cap);
+            methods.add(method);
+            // Ordered call-site sequence — repeats preserved (= per-method counts),
+            // bounded so a pathological script cannot bloat the descriptor.
+            if (sequence.length < SEQUENCE_CAP)
+                sequence.push(method);
+        }
+        else {
+            unknownMethods.add(method);
+        }
+    }
+    return {
+        caps,
+        methods: [...methods].sort(),
+        sequence,
+        unknownMethods: [...unknownMethods].sort(),
+    };
+}
+/**
+ * Classify a bounded stderr tail into a known-recoverable failure class, or
+ * `undefined` for anything else. Ordered first-match: `bad_import` (a missing
+ * module/package/import), then `comis_tools_misuse` (a `comis_tools` reference
+ * paired with a Type/Attribute error shape), then `syntax_error` (a malformed
+ * script body — the most frequent weak-model authoring failure; Node and Python
+ * both emit the exact token `SyntaxError`), then the generic `type_error`. The
+ * misuse class is tested BEFORE `syntax_error`/`type_error` so a `comis_tools`
+ * TypeError classifies as misuse; `syntax_error` is kept a DISTINCT class (not
+ * folded into a generic bucket) so its one-shot-repair success rate stays
+ * separately observable. The classes are disjoint in practice (a SyntaxError tail
+ * carries no Import/Type/Attribute token), so a `comis_tools` SyntaxError still
+ * classifies as `syntax_error`, not misuse. Case-sensitive: the token names are
+ * engine-emitted. Pure: a bounded regex projection — it never executes or reflects
+ * the tail. A repaired script re-runs in the SAME jail, so a bad regeneration
+ * still fails closed at the cap-socket endpoint.
+ */
+export function classifyRecoverableStderr(tail) {
+    if (/ImportError|ModuleNotFoundError|ERR_MODULE_NOT_FOUND|Cannot find (?:module|package)/.test(tail)) {
+        return "bad_import";
+    }
+    if (/comis_tools/.test(tail) &&
+        /TypeError|AttributeError|is not a function|has no attribute/.test(tail)) {
+        return "comis_tools_misuse";
+    }
+    if (/SyntaxError/.test(tail)) {
+        return "syntax_error";
+    }
+    if (/TypeError|AttributeError/.test(tail)) {
+        return "type_error";
+    }
+    return undefined;
+}
+/**
+ * Build a deterministic, bounded digest of the available `comis_tools` methods
+ * grouped by the capability each requires — a pure projection of
+ * `TOOL_CAPABILITY_MAP` the repair prompt hands the utility model. Caps and the
+ * methods within each are sorted, so two calls are byte-identical (no
+ * clock/random). The `orch:*` cap identifiers and method names are real code
+ * identifiers (kept verbatim).
+ */
+export function buildDescribeDigest() {
+    const byCap = new Map();
+    for (const [method, cap] of Object.entries(TOOL_CAPABILITY_MAP)) {
+        const bucket = byCap.get(cap);
+        if (bucket) {
+            bucket.push(method);
+        }
+        else {
+            byCap.set(cap, [method]);
+        }
+    }
+    const lines = ["comis_tools methods and the capability each requires:"];
+    for (const [cap, capMethods] of [...byCap.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        lines.push("", `${cap}:`);
+        for (const method of [...capMethods].sort()) {
+            lines.push(`  ${method} (${cap})`);
+        }
+    }
+    return lines.join("\n");
+}

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-repair.d.ts

@@ -0,0 +1,110 @@
+import { type ComisLogger, type EventMap } from "@comis/core";
+import type { CapabilityClass } from "@comis/agent";
+/** The bits of a spawned child the runner consumes (a `child_process` subset). */
+export interface OrchestrateSpawnedChild {
+    readonly stdout: {
+        on(event: "data", cb: (chunk: Buffer) => void): void;
+    } | null;
+    readonly stderr: {
+        on(event: "data", cb: (chunk: Buffer) => void): void;
+    } | null;
+    on(event: "close", cb: (code: number | null) => void): void;
+    on(event: "error", cb: (err: Error) => void): void;
+    kill(signal?: NodeJS.Signals): void;
+}
+/** The spawn seam — injected so the macOS unit suite runs WITHOUT a real spawn. */
+export type OrchestrateSpawnFn = (bin: string, args: string[], opts: {
+    env: Record<string, string | undefined>;
+    cwd?: string;
+}) => OrchestrateSpawnedChild;
+/**
+ * The daemon-minted one-shot repair completion closure: given the failed script +
+ * its bounded stderr tail + a describe digest, it does ONE utility-model re-prompt
+ * and returns the regenerated script (or `undefined` on give-up).
+ */
+export type OrchestrateRepairSeam = (input: {
+    script: string;
+    language: "ts" | "js" | "py";
+    stderrTail: string;
+    describeDigest: string;
+}) => Promise<string | undefined>;
+/**
+ * The hard in-stream ceiling on the daemon-side stdout collector. The post-exit
+ * stdout size-bounce only runs AFTER the child exits, so without this an
+ * unbounded jailed `console.log` flood would grow the daemon heap for the whole
+ * run. 4 MiB leaves ample headroom for a legitimate large result while bounding
+ * memory; past it the runner SIGKILLs the child and fails closed. Exported so the
+ * bound is unit-testable.
+ */
+export declare const STDOUT_HARD_CAP_BYTES: number;
+/**
+ * The wall-clock budget (ms) the runner ADDS to a per-run child lease's TTL when
+ * one-shot auto-repair is enabled for the run, so the single lease minted before
+ * the initial run stays valid through the repair-completion await and into the
+ * repaired re-run's in-jail cap calls. Sized to the repair seam's own hard
+ * completion ceiling (the utility-model abort timeout in `orchestrate-repair-seam.ts`,
+ * 120s): the seam blocks for at most that long between the two runs, so a lease
+ * short by less than this can expire mid-repair and deny the repaired run's cap
+ * calls (fails closed, but the repair silently no-ops for exactly the slow/local
+ * small models it targets). MUST stay >= that seam ceiling — raising the seam
+ * timeout above this reopens the gap. A larger-than-run child lease is harmless:
+ * it is still the short-lived, audience-bound, attenuateCaps-bounded per-run child,
+ * just sized to the real run+repair window rather than the run alone.
+ */
+export declare const REPAIR_LEASE_BUDGET_MS = 120000;
+/**
+ * Whether one-shot auto-repair is enabled for a run's capability class — the pure
+ * class-gate with the runner's fail-safe default applied (an absent class → the
+ * repair-eligible `small`, matching the platform's fail-closed direction). The
+ * SINGLE source of the class-gate: the runner consults it to size the child-lease
+ * TTL for the repair window (when a seam is also wired), and
+ * {@link runScriptWithOneShotRepair} consults it as part of its larger gate (which
+ * additionally requires a wired seam AND a recoverable failure) — so the lease
+ * sizing and the actual repair decision can never disagree on eligibility.
+ */
+export declare function repairEnabledForClass(capabilityClass: CapabilityClass | undefined): boolean;
+/** The closed run-degradation classes on `orchestrate:run_summary.failureClass`. */
+export type OrchestrateFailureClass = NonNullable<EventMap["orchestrate:run_summary"]["failureClass"]>;
+/**
+ * Map a thrown run error to its closed failure class + exit code. A carried
+ * {@link OrchestrateRunFailure} forwards its own class; any UNCLASSIFIED throw (a
+ * synchronous spawn throw, a child `error` event, a jail-unavailable refusal) is
+ * a spawn-class failure — the jail could not run.
+ */
+export declare function classifyRunError(err: unknown): {
+    failureClass: OrchestrateFailureClass;
+    exitCode: number;
+};
+/**
+ * Run the model's script in the jailed child, with a bounded one-shot auto-repair.
+ *
+ * Writes the script into the jail workspace then drives the jailed child to
+ * completion — stdout ONLY re-enters context; stderr and intermediate output
+ * never do. On a non-zero exit whose bounded stderr tail matches a known-
+ * recoverable class, it does ONE utility-model re-prompt (the injected
+ * {@link OrchestrateRepairSeam}) and re-runs the regenerated script EXACTLY once.
+ *
+ * Class-gated: repair is ON for weaker models, OFF for stronger; an absent class
+ * defaults to the repair-eligible class (fail-safe ON for an unknown small-target
+ * deployment). Bounded to a single attempt — a repaired-then-failed run surfaces
+ * the ORIGINAL bounded error, never a loop. Both the initial run and the single
+ * repaired re-run share the identical jail/cap/lease envelope the caller built
+ * (bin / spawnArgs / childEnv / scriptPath), so the regenerated script has the
+ * SAME blast radius as the original (no cap widening); the cap-socket endpoint
+ * stays the sole authoritative boundary. Returns the FINAL run's raw stdout, or
+ * throws the failure the caller maps + emits.
+ */
+export declare function runScriptWithOneShotRepair(input: {
+    readonly spawnFn: OrchestrateSpawnFn;
+    readonly bin: string;
+    readonly spawnArgs: string[];
+    readonly childEnv: Record<string, string | undefined>;
+    readonly scriptPath: string;
+    readonly timeoutMs: number;
+    readonly script: string;
+    readonly language: "ts" | "js" | "py";
+    readonly capabilityClass: CapabilityClass | undefined;
+    readonly repairSeam: OrchestrateRepairSeam | undefined;
+    readonly log: ComisLogger;
+    readonly runId: string;
+}): Promise<string>;

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-repair.js

@@ -0,0 +1,295 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: runScriptWithOneShotRepair re-throws the ORIGINAL bounded run
+// error when a repaired re-run still fails or the repair seam gives up — an
+// honest-degrade back to the orchestrate runner, whose AgentTool execution
+// boundary (agent-loop) catches it and surfaces it as a tool error.
+/**
+ * `orchestrate-repair` — the jailed-script execution engine for the `orchestrate`
+ * runner: drive one jailed child to completion, classify its failure onto a
+ * closed enum, and wrap the run in a bounded one-shot auto-repair.
+ *
+ *   - {@link runJailedChild} — spawn + drive one jailed child: collect a
+ *     byte-capped stdout, keep only a bounded stderr TAIL (surfaced ONLY on a
+ *     non-zero exit — the success path is stdout-only), kill on timeout or on a
+ *     stdout flood, and resolve the raw stdout or reject a classified
+ *     {@link OrchestrateRunFailure}. stderr and intermediate output never
+ *     re-enter context.
+ *   - {@link runScriptWithOneShotRepair} — write the script into the jail then
+ *     run it; on a non-zero exit whose bounded stderr tail matches a known-
+ *     recoverable class, do ONE utility-model re-prompt (the injected
+ *     {@link OrchestrateRepairSeam}) and re-run the regenerated script EXACTLY
+ *     once, in the identical jail/cap/lease envelope the caller built. Class-
+ *     gated (ON for weaker models, OFF for stronger); bounded to a single
+ *     attempt — a repaired-then-failed run surfaces the ORIGINAL bounded error,
+ *     never a loop.
+ *   - {@link classifyRunError} — map a thrown run error to its closed
+ *     {@link OrchestrateFailureClass} + exit code for the run_summary emit.
+ *
+ * The runner (orchestrate-tool) builds the jail/cap/lease envelope (args +
+ * secret-scrubbed env + per-run lease) and delegates execution here; the
+ * cap-socket endpoint stays the sole authoritative capability boundary.
+ *
+ * @module
+ */
+import { writeFileSync } from "node:fs";
+import { systemClearTimeout, systemSetTimeout, } from "@comis/core";
+import { autoRepairForClass } from "@comis/agent";
+import { buildDescribeDigest, classifyRecoverableStderr } from "./orchestrate-preflight.js";
+// ---------------------------------------------------------------------------
+// Constants + the failure model.
+// ---------------------------------------------------------------------------
+/**
+ * The hard in-stream ceiling on the daemon-side stdout collector. The post-exit
+ * stdout size-bounce only runs AFTER the child exits, so without this an
+ * unbounded jailed `console.log` flood would grow the daemon heap for the whole
+ * run. 4 MiB leaves ample headroom for a legitimate large result while bounding
+ * memory; past it the runner SIGKILLs the child and fails closed. Exported so the
+ * bound is unit-testable.
+ */
+export const STDOUT_HARD_CAP_BYTES = 4 * 1024 * 1024;
+/**
+ * The wall-clock budget (ms) the runner ADDS to a per-run child lease's TTL when
+ * one-shot auto-repair is enabled for the run, so the single lease minted before
+ * the initial run stays valid through the repair-completion await and into the
+ * repaired re-run's in-jail cap calls. Sized to the repair seam's own hard
+ * completion ceiling (the utility-model abort timeout in `orchestrate-repair-seam.ts`,
+ * 120s): the seam blocks for at most that long between the two runs, so a lease
+ * short by less than this can expire mid-repair and deny the repaired run's cap
+ * calls (fails closed, but the repair silently no-ops for exactly the slow/local
+ * small models it targets). MUST stay >= that seam ceiling — raising the seam
+ * timeout above this reopens the gap. A larger-than-run child lease is harmless:
+ * it is still the short-lived, audience-bound, attenuateCaps-bounded per-run child,
+ * just sized to the real run+repair window rather than the run alone.
+ */
+export const REPAIR_LEASE_BUDGET_MS = 120_000;
+/**
+ * Whether one-shot auto-repair is enabled for a run's capability class — the pure
+ * class-gate with the runner's fail-safe default applied (an absent class → the
+ * repair-eligible `small`, matching the platform's fail-closed direction). The
+ * SINGLE source of the class-gate: the runner consults it to size the child-lease
+ * TTL for the repair window (when a seam is also wired), and
+ * {@link runScriptWithOneShotRepair} consults it as part of its larger gate (which
+ * additionally requires a wired seam AND a recoverable failure) — so the lease
+ * sizing and the actual repair decision can never disagree on eligibility.
+ */
+export function repairEnabledForClass(capabilityClass) {
+    return autoRepairForClass(capabilityClass ?? "small");
+}
+/**
+ * Max chars of the jailed child's stderr retained as a diagnostic TAIL. On the
+ * success path stderr is dropped (stdout-only — diagnostic noise stays out of
+ * context); on a NON-ZERO exit this bounded tail is the only signal of WHY the
+ * child died (a thrown `TypeError`, a bad import, a comis_tools misuse) and is
+ * surfaced in the rejection so the failure is diagnosable without a re-run.
+ * Bounded so a stderr flood can neither
+ * grow the daemon heap nor swamp the error/context. The surfaced tail still
+ * passes the daemon OutputGuard on egress, and the jail env is secret-scrubbed.
+ */
+const STDERR_TAIL_MAX_CHARS = 2_000;
+/** Exit-code sentinels for the kill / spawn-fail paths where the child returns none. */
+const EXIT_CODE_TIMEOUT = 124; // GNU `timeout` convention.
+const EXIT_CODE_SIGKILL = 137; // 128 + SIGKILL(9) — the stdout hard-cap kill.
+const EXIT_CODE_SPAWN_FAIL = 127; // exec/spawn failure convention.
+/**
+ * A classified orchestrate-run failure: the closed {@link OrchestrateFailureClass}
+ * + the process exit code (a sentinel where the child produced none). Each throw
+ * site maps to a member BEFORE the run_summary emit, keeping the bus payload on a
+ * closed enum; the free-text message stays on the bounded tool-error surface,
+ * NEVER on the bus.
+ */
+class OrchestrateRunFailure extends Error {
+    failureClass;
+    exitCode;
+    /**
+     * The bounded, already-scrubbed stderr tail captured at the non-zero exit (empty
+     * on the timeout / stdout-cap / spawn-throw paths, which carry no child stderr).
+     * A STRUCTURED field so the one-shot repair path can classify + feed it directly,
+     * never by re-parsing {@link Error.message}.
+     */
+    stderrTail;
+    constructor(message, failureClass, exitCode, stderrTail = "") {
+        super(message);
+        this.name = "OrchestrateRunFailure";
+        this.failureClass = failureClass;
+        this.exitCode = exitCode;
+        this.stderrTail = stderrTail;
+    }
+}
+/**
+ * Map a thrown run error to its closed failure class + exit code. A carried
+ * {@link OrchestrateRunFailure} forwards its own class; any UNCLASSIFIED throw (a
+ * synchronous spawn throw, a child `error` event, a jail-unavailable refusal) is
+ * a spawn-class failure — the jail could not run.
+ */
+export function classifyRunError(err) {
+    if (err instanceof OrchestrateRunFailure) {
+        return { failureClass: err.failureClass, exitCode: err.exitCode };
+    }
+    return { failureClass: "spawn_fail", exitCode: EXIT_CODE_SPAWN_FAIL };
+}
+// ---------------------------------------------------------------------------
+// The single-attempt jailed-child driver.
+// ---------------------------------------------------------------------------
+/**
+ * Drive the jailed child to completion: collect stdout, surface a non-zero exit
+ * or a spawn error as a tool error (NEVER a silent success), kill on timeout.
+ * stderr is read+discarded (it never re-enters context — stdout-only).
+ */
+function runJailedChild(spawnFn, bin, args, opts, timeoutMs, ctx) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawnFn(bin, args, opts);
+        }
+        catch (err) {
+            reject(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        let stdout = "";
+        let stdoutBytes = 0;
+        let stderrTail = "";
+        let settled = false;
+        const timer = systemSetTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* already gone */
+            }
+            reject(new OrchestrateRunFailure(`orchestrate run exceeded its ${timeoutMs}ms timeout`, "timeout", EXIT_CODE_TIMEOUT));
+        }, timeoutMs);
+        timer.unref?.();
+        child.stdout?.on("data", (chunk) => {
+            if (settled)
+                return;
+            // Bound the in-stream accumulation. The post-exit stdout size-bounce
+            // does not protect the daemon heap DURING the run, so a jailed
+            // `while(true) console.log(...)` flood must be stopped here — fail closed:
+            // stop appending, SIGKILL the runaway child, and reject.
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > STDOUT_HARD_CAP_BYTES) {
+                settled = true;
+                systemClearTimeout(timer);
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* already gone */
+                }
+                ctx.log.warn({ runId: ctx.runId, errorKind: "resource", stdoutBytes, hint: `Jailed stdout exceeded the ${STDOUT_HARD_CAP_BYTES}B hard cap — the script was killed. Have it write high-volume output to a ResultRef (materialize) and slice it in-jail instead of console.log-ing it.` }, "orchestrate jailed child exceeded the stdout hard cap — killed");
+                reject(new OrchestrateRunFailure(`orchestrate stdout exceeded the ${STDOUT_HARD_CAP_BYTES}B hard cap`, "stdout_cap", EXIT_CODE_SIGKILL));
+                return;
+            }
+            stdout += chunk.toString("utf8");
+        });
+        // Read stderr but keep only a BOUNDED TAIL — it cannot back-pressure the child
+        // and never re-enters context on the SUCCESS path (stdout-only). But on a
+        // NON-ZERO exit the tail is the only signal of WHY the child died, so the close
+        // handler surfaces it in the rejection (otherwise the failure is just
+        // "exited with code N" and undiagnosable without a re-run).
+        child.stderr?.on("data", (chunk) => {
+            if (settled)
+                return;
+            stderrTail = (stderrTail + chunk.toString("utf8")).slice(-STDERR_TAIL_MAX_CHARS);
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            systemClearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            systemClearTimeout(timer);
+            if (code !== 0 && code !== null) {
+                const tail = stderrTail.trim();
+                ctx.log.warn({
+                    runId: ctx.runId,
+                    errorKind: "internal",
+                    exitCode: code,
+                    stderrTail: tail ? tail.slice(-512) : undefined,
+                }, "orchestrate jailed child exited non-zero");
+                reject(new OrchestrateRunFailure(`orchestrate jailed child exited with code ${code}${tail ? `:\n${tail}` : ""}`, "nonzero_exit", code, tail));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// The bounded one-shot repair orchestration.
+// ---------------------------------------------------------------------------
+/**
+ * Run the model's script in the jailed child, with a bounded one-shot auto-repair.
+ *
+ * Writes the script into the jail workspace then drives the jailed child to
+ * completion — stdout ONLY re-enters context; stderr and intermediate output
+ * never do. On a non-zero exit whose bounded stderr tail matches a known-
+ * recoverable class, it does ONE utility-model re-prompt (the injected
+ * {@link OrchestrateRepairSeam}) and re-runs the regenerated script EXACTLY once.
+ *
+ * Class-gated: repair is ON for weaker models, OFF for stronger; an absent class
+ * defaults to the repair-eligible class (fail-safe ON for an unknown small-target
+ * deployment). Bounded to a single attempt — a repaired-then-failed run surfaces
+ * the ORIGINAL bounded error, never a loop. Both the initial run and the single
+ * repaired re-run share the identical jail/cap/lease envelope the caller built
+ * (bin / spawnArgs / childEnv / scriptPath), so the regenerated script has the
+ * SAME blast radius as the original (no cap widening); the cap-socket endpoint
+ * stays the sole authoritative boundary. Returns the FINAL run's raw stdout, or
+ * throws the failure the caller maps + emits.
+ */
+export async function runScriptWithOneShotRepair(input) {
+    const { spawnFn, bin, spawnArgs, childEnv, scriptPath, timeoutMs, script, language, capabilityClass, repairSeam, log, runId, } = input;
+    // attemptRun writes the script into the workspace then drives the jailed child
+    // to completion. BOTH the initial run and the single repaired re-run go through
+    // it, sharing the identical jail/cap/lease envelope built by the caller.
+    const attemptRun = async (scriptText) => {
+        writeFileSync(scriptPath, scriptText);
+        return runJailedChild(spawnFn, bin, spawnArgs, { env: childEnv, cwd: undefined }, timeoutMs, { runId, log });
+    };
+    try {
+        return await attemptRun(script);
+    }
+    catch (runErr) {
+        const { failureClass } = classifyRunError(runErr);
+        const recoverable = runErr instanceof OrchestrateRunFailure
+            ? classifyRecoverableStderr(runErr.stderrTail)
+            : undefined;
+        if (failureClass === "nonzero_exit" &&
+            repairEnabledForClass(capabilityClass) &&
+            repairSeam !== undefined &&
+            recoverable !== undefined) {
+            log.debug({ runId, step: "repair", recoverable }, "orchestrate one-shot repair attempt");
+            const regenerated = await repairSeam({
+                script,
+                language,
+                // Sound: recoverable !== undefined implies runErr is an
+                // OrchestrateRunFailure (the ternary above only classifies that case).
+                stderrTail: runErr.stderrTail,
+                describeDigest: buildDescribeDigest(),
+            });
+            if (regenerated !== undefined && regenerated.trim() !== "") {
+                // The ONE re-run — no loop. A repaired-then-failed run re-throws the
+                // ORIGINAL bounded error (the seam's output did not fix the script).
+                try {
+                    return await attemptRun(regenerated);
+                }
+                catch {
+                    throw runErr;
+                }
+            }
+            // The seam gave up (no regenerated script) — honest-degrade to the
+            // original bounded error.
+            throw runErr;
+        }
+        // Not a recoverable class, class-gated off, or no repair seam wired —
+        // surface the original bounded error unchanged.
+        throw runErr;
+    }
+}