comisai 1.0.44 → 1.0.46

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

@@ -1,13 +1,21 @@
 import { Type } from "typebox";
 import { spawn } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname } from "node:path";
-import { registerActivityLabelSpec, safePath, systemClearTimeout, systemNowMs, systemSetTimeout, } from "@comis/core";
+import { registerActivityLabelSpec, safePath, systemNowMs, tryGetContext, } from "@comis/core";
 import { createToolResultSizeGuard } from "@comis/agent";
-import { resolveJailAgentCli, resolveJailNode, SYSTEM_RO_PATHS } from "../sandbox/bwrap-provider.js";
+import { resolveJailAgentCli, resolveJailNode, resolveJailPython, SYSTEM_RO_PATHS, } from "../sandbox/bwrap-provider.js";
 import { loadSeccompProfileFd, closeSeccompProfileFd } from "../sandbox/seccomp-profile.js";
 import { throwToolError } from "../../../platform-tools/tool-helpers.js";
+import { estimateSavings } from "./savings-estimate.js";
+import { extractCapabilityFootprint } from "./orchestrate-preflight.js";
+import { classifyRunError, repairEnabledForClass, runScriptWithOneShotRepair, REPAIR_LEASE_BUDGET_MS, } from "./orchestrate-repair.js";
+import { finalizeCompletedRun, markResumable, registerDurableRun, resolveScriptSource, defaultOrchestrateDurableFs, } from "./orchestrate-durable.js";
+// The jailed-child execution engine + its seam types live in orchestrate-repair;
+// re-export the public surface the runner has always exposed here (the barrel +
+// the unit suite import these names from this module).
+export { STDOUT_HARD_CAP_BYTES } from "./orchestrate-repair.js";
 // Activity label (channel render): the descriptor name equals the emitted tool
 // name (`"orchestrate"`). A static fallback so the render is not the bare
 // humanized form while the script runs.
@@ -16,53 +24,41 @@ registerActivityLabelSpec("orchestrate", {
     label: "running an orchestrate script",
 });
 // ---------------------------------------------------------------------------
-// Parameter schema (ORCH-01).
+// Parameter schema.
 // ---------------------------------------------------------------------------
 const OrchestrateParams = Type.Object({
     script: Type.String({
         description: "The script body to run in the jailed child. It may `import { comis_tools } from \"./comis_tools.js\"` and chain the capability-scoped tools; only what it console.logs (stdout) re-enters context.",
     }),
-    language: Type.Union([Type.Literal("ts"), Type.Literal("js")], {
-        description: 'The script language: "ts" or "js".',
+    language: Type.Union([Type.Literal("ts"), Type.Literal("js"), Type.Literal("py")], {
+        description: 'The script language: "ts", "js", or "py".',
     }),
     timeoutMs: Type.Optional(Type.Integer({ description: "Hard wall-clock timeout for the jailed run (ms). Default 60000." })),
     captureStdout: Type.Optional(Type.Boolean({ description: "Reserved — stdout is always the (only) captured channel." })),
+    resumeRunId: Type.Optional(Type.String({
+        description: "Resume a timed-out durable run by its id: re-spawns the PINNED stored script. The `script` param is IGNORED on resume — no new bytes are accepted. Requires the durable-resume surface.",
+    })),
 });
 // ---------------------------------------------------------------------------
 // Constants.
 // ---------------------------------------------------------------------------
-/** The SDK asset filenames copied into the jail workspace (Plan 03 + Task 1). */
-const SDK_ASSETS = ["comis_tools.d.ts", "comis_tools.js", "orchestrate-sdk-runtime.js"];
-/** The comis-built comis-agent entry that is sha256-pinned + RO-bound (CLI-05). */
+/** The SDK asset filenames copied into the jail workspace (exported: the replay re-spawn reuses them). */
+export const SDK_ASSETS = [
+    "comis_tools.d.ts",
+    "comis_tools.js",
+    "comis_tools.py",
+    "orchestrate-sdk-runtime.js",
+];
+/** The comis-built comis-agent entry that is sha256-pinned + RO-bound. */
 const COMIS_AGENT_ENTRY_FILENAME = "comis-agent-entry.js";
 /** The committed manifest (rides into dist via the asset-copy) holding the pin. */
 const COMIS_AGENT_MANIFEST_FILENAME = "comis-agent-manifest.json";
 /** Max stdout characters that re-enter context — the rest is size-bounced. */
 const STDOUT_MAX_CHARS = 30_000;
-/**
- * The hard in-stream ceiling on the daemon-side stdout collector (WR-01). The
- * `STDOUT_MAX_CHARS` bounce only runs AFTER the child exits, so without this an
- * unbounded jailed `console.log` flood grows the daemon heap for the whole run.
- * A few × `STDOUT_MAX_CHARS` (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;
-/**
- * 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
- * (hermes-usecases live-test 2026-06-25). 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;
 /** Default hard timeout for a jailed run (ms). Exported for the clamp tests. */
 export const DEFAULT_TIMEOUT_MS = 60_000;
 /**
- * The hard ceiling on a model-supplied `timeoutMs` (WR-02). The schema accepts
+ * The hard ceiling on a model-supplied `timeoutMs`. The schema accepts
  * any positive integer, so without this a jailed (attacker-controlled) script
  * could request `timeoutMs: 999_999_999` (~11.5 days) and pin a child for an
  * arbitrarily long window. 10 minutes is far longer than any legitimate
@@ -72,10 +68,10 @@ export const MAX_TIMEOUT_MS = 10 * 60_000;
 /** The per-run aggregate `results/` budget passed to the store's GC. */
 const PER_RUN_AGGREGATE_CAP_BYTES = 64 * 1024 * 1024;
 // ---------------------------------------------------------------------------
-// Pure exported helper — the ORCH-02 env-scrub (macOS-unit-testable).
+// Pure exported helper — the env-scrub (macOS-unit-testable).
 // ---------------------------------------------------------------------------
 /**
- * Matches any env key that could carry a credential (ORCH-02 + IN-01). Covers
+ * Matches any env key that could carry a credential. Covers
  * the obvious `KEY/TOKEN/SECRET` names PLUS common credential names that contain
  * none of those substrings (`PASSWORD`, `PASSPHRASE`, `CREDENTIAL(S)`,
  * `PRIVATE`, `BEARER`, `AUTH`, a `_PAT` suffix, `DSN`). `_PAT\b` is anchored so
@@ -86,13 +82,13 @@ const PER_RUN_AGGREGATE_CAP_BYTES = 64 * 1024 * 1024;
  */
 const SECRET_KEY_PATTERN = /KEY|TOKEN|SECRET|PASSWORD|PASSPHRASE|CREDENTIAL|PRIVATE|BEARER|AUTH|_PAT\b|DSN/i;
 /**
- * Filter a base/inherited env map for the jailed child (ORCH-02): drop every key
+ * Filter a base/inherited env map for the jailed child: drop every key
  * matching `*KEY* / *TOKEN* / *SECRET*` (case-insensitive) and every undefined
  * value, returning a clean `Record<string,string>`.
  *
  * This runs over the BASE env ONLY — the daemon-injected lease vars
  * (`COMIS_CAP_LEASE`/`COMIS_ORCH_SOCKET`) are merged AFTER this scrub (they ride
- * `brokerSpawnEnv.placeholders`), so they survive by construction (Pitfall 4).
+ * `brokerSpawnEnv.placeholders`), so they survive by construction.
  * Keeping the scrub a pure function over the base map makes the survival property
  * unit-testable on macOS with no real spawn.
  *
@@ -112,7 +108,7 @@ export function scrubSecretEnv(base) {
 }
 /**
  * Resolve the effective jailed-run wall-clock timeout from a model-supplied
- * value (WR-02): a non-positive / non-numeric request falls back to
+ * value: a non-positive / non-numeric request falls back to
  * {@link DEFAULT_TIMEOUT_MS}; any larger request is clamped down to
  * {@link MAX_TIMEOUT_MS}. Pure so the bound is unit-testable with no spawn.
  *
@@ -127,7 +123,7 @@ export function clampTimeoutMs(requested) {
 // Factory.
 // ---------------------------------------------------------------------------
 /**
- * Create the `orchestrate` AgentTool (ORCH-01/02). See the module doc for the
+ * Create the `orchestrate` AgentTool. See the module doc for the
  * composition + the containment guarantees.
  *
  * @param deps - The injected collaborators (workspace, cap socket, sandbox,
@@ -138,6 +134,7 @@ export function createOrchestrateTool(deps) {
     const log = deps.logger.child({ submodule: "orchestrate-tool" });
     const spawnFn = deps.spawnFn ?? defaultSpawn;
     const resolveNode = deps.resolveJailNodeFn ?? defaultResolveJailNode;
+    const resolvePython = deps.resolveJailPythonFn ?? defaultResolveJailPython;
     const loadSeccompFd = deps.loadSeccompFdFn ?? loadSeccompProfileFd;
     const now = deps.now ?? systemNowMs;
     const sdkAssetsDir = deps.sdkAssetsDir ?? dirname(fileURLToPath(import.meta.url));
@@ -151,45 +148,191 @@ export function createOrchestrateTool(deps) {
             const startedMs = now();
             const runId = `orch-${startedMs.toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
             const workspacePath = deps.workspaceResolver();
-            // WR-02: bound the model-supplied timeout (fallback default, clamp ceiling)
+            // Bound the model-supplied timeout (fallback default, clamp ceiling)
             // so a jailed script cannot pin a child for an arbitrarily long window.
             const timeoutMs = clampTimeoutMs(params.timeoutMs);
-            log.debug({ runId, step: "start", language: params.language }, "orchestrate run starting");
-            // Resolve the seccomp fd ONCE, BEFORE the try (CR-01 + seccomp-profile.ts
-            // §21-43). The fd is opened WITHOUT O_CLOEXEC so the bwrap child inherits
+            // Durable row key = the tree rootRunId (also the checkpoint core's key);
+            // `skipCleanup` gates the finally on a resumable timeout.
+            const durableKey = deps.rootRunId ?? runId;
+            let skipCleanup = false;
+            // Resolve the script source (fresh params, or PINNED bytes on a resume).
+            // Fail-CLOSED: a resumeRunId with the surface off is REFUSED, not run as `script`.
+            const resolved = await resolveScriptSource(params, deps.durableRuns, defaultOrchestrateDurableFs, {
+                workspacePath,
+                runId,
+            });
+            if (!resolved.ok) {
+                throwToolError(resolved.error.code, resolved.error.message, { hint: resolved.error.hint });
+            }
+            const { script, language, scriptName } = resolved.value;
+            // Static pre-flight, run BEFORE any resource is acquired — no seccomp fd
+            // opened, no run_summary emitted, no child spawned on a rejection (it precedes
+            // the try/finally and the loadSeccompFd below). Scan the model's script for its
+            // capability footprint (pure text analysis — no eval/fs/net) and:
+            //   (a) FAIL FAST with a cap-named error if the footprint needs a cap the agent
+            //       lacks, so a small model gets a precise pre-spawn error instead of a
+            //       mid-run failure after a jail is burned; and
+            //   (b) fire ONE approval on the whole footprint (the exact sorted cap set) when
+            //       an approval gate is wired — a `!approved` resolution refuses the run.
+            //       Seam-presence IS "approvals configured" (the daemon threads the gate only
+            //       when config.approvals.enabled); there is no rule engine — the reused gate
+            //       is the whole mechanism.
+            // ADVISORY ONLY: the footprint grants nothing. A script that dodges the static
+            // scan (a dynamic/computed call → empty footprint) proceeds past here and is
+            // still denied at the cap-socket endpoint by default-deny-by-absence, the sole
+            // authoritative boundary.
+            const footprint = extractCapabilityFootprint(script);
+            if (deps.allowedCaps) {
+                const held = new Set(deps.allowedCaps);
+                const missing = [...footprint.caps].filter((cap) => !held.has(cap)).sort();
+                if (missing.length > 0) {
+                    throwToolError("permission_denied", `This script calls tools requiring capabilities the agent lacks: ${missing.join(", ")}.`, {
+                        hint: `Remove those calls or grant ${missing.join("/")} in the agent's autonomy profile. The jail endpoint denies them regardless — this is a pre-spawn fail-fast.`,
+                    });
+                }
+            }
+            if (deps.approvalGate && footprint.caps.size > 0) {
+                const sortedCaps = [...footprint.caps].sort();
+                // The trust level / agent id / session come from the framework-injected
+                // request context (tryGetContext), never from the model's params — the tool
+                // cannot self-supply them. Undefined outside a request scope (heartbeat/cron).
+                const ctx = tryGetContext();
+                const resolution = await deps.approvalGate.requestApproval({
+                    toolName: "orchestrate",
+                    action: `orchestrate:${sortedCaps.join("+")}`,
+                    params: { caps: sortedCaps },
+                    agentId: ctx?.userId ?? "unknown",
+                    sessionKey: ctx?.sessionKey ?? "",
+                    trustLevel: (ctx?.trustLevel ?? "admin"),
+                    ...(ctx?.channelType ? { channelType: ctx.channelType } : {}),
+                });
+                if (!resolution.approved) {
+                    throwToolError("permission_denied", "Orchestrate run denied by the approval workflow.", {
+                        hint: resolution.reason ?? "no reason given",
+                    });
+                }
+            }
+            // The per-run child leaseId (D5) — the per-run correlator carried on the
+            // run_summary emit. Undefined when no mintRunLease seam is wired (the
+            // assembly bearer authenticates instead).
+            let childLeaseId;
+            // The owning TURN's trace correlator — snapshotted ONCE from the framework
+            // request context (distinct from runId/rootRunId, the orchestrate-run ids).
+            // Carried on run_summary so the learning ledger keys the descriptor row on
+            // the turn trajectory. Undefined outside a request scope (heartbeat/cron).
+            const turnTraceId = tryGetContext()?.traceId;
+            // Emit the content-free run_summary (EXPLAIN-02) — success AND every failure
+            // class route through here. Captures the run's materialized {count,bytes}
+            // BEFORE the finally's cleanup wipes results/ (Pitfall 3), computes the
+            // SAVE-01 estimate, and self-attributes via rootRunId + sessionKey (the
+            // daemon-shared bus fans out to every session bridge). A no-op when no
+            // eventBus is wired — never the stderr tail / script body / params (INV-5).
+            const emitRunSummary = (outcome) => {
+                if (deps.eventBus === undefined)
+                    return;
+                // The emit MUST NEVER throw into the run flow. TypedEventBus.emit delegates
+                // to EventEmitter.emit, which invokes subscribers synchronously and
+                // PROPAGATES a throwing one — so a throwing subscriber (a future plugin hook
+                // or a new bridge branch) would otherwise be caught by the run's catch,
+                // re-classified as spawn_fail, re-emitted (double record), and flip a
+                // SUCCESSFUL run into a failed tool call. Swallow + log so a bad subscriber
+                // can never perturb the run outcome (the run already rode its own
+                // return/throw); the store aggregate read is inside the guard too.
+                try {
+                    const agg = deps.store.runAggregate?.({ workspacePath }) ?? { count: 0, bytes: 0 };
+                    const savings = estimateSavings(agg.bytes, outcome.stdoutCharsReentered);
+                    deps.eventBus.emit("orchestrate:run_summary", {
+                        runId,
+                        ...(childLeaseId !== undefined ? { leaseId: childLeaseId } : {}),
+                        rootRunId: deps.rootRunId ?? runId,
+                        ...(deps.sessionKey !== undefined ? { sessionKey: deps.sessionKey } : {}),
+                        ...(turnTraceId !== undefined ? { traceId: turnTraceId } : {}),
+                        language,
+                        durationMs: now() - startedMs,
+                        exitCode: outcome.exitCode,
+                        ...(outcome.failureClass !== undefined ? { failureClass: outcome.failureClass } : {}),
+                        stdoutBytesRaw: outcome.stdoutBytesRaw,
+                        stdoutCharsReentered: outcome.stdoutCharsReentered,
+                        resultRefCount: agg.count,
+                        resultRefBytes: agg.bytes,
+                        // Savings is carried ONLY when the run materialized ResultRefs — the
+                        // documented contract (orchestrate.mdx / json-rpc.mdx), the fold's
+                        // omit-branch, and the schema test. A run that materialized nothing
+                        // OMITS both keys rather than carrying a phantom 0, mirroring the sibling
+                        // optional leaseId / sessionKey / failureClass conditional spreads.
+                        ...(agg.count > 0
+                            ? { estSavedTokens: savings.estSavedTokens, savedRatio: savings.savedRatio }
+                            : {}),
+                        // The content-free ordered call-site sequence + counts from the pre-flight
+                        // footprint (already computed above) — names only, never args/bodies.
+                        // Omitted (like the sibling optional spreads) when no cap-mapped call site.
+                        ...(footprint.sequence.length > 0 ? { toolSequence: footprint.sequence } : {}),
+                        timestamp: now(),
+                    });
+                }
+                catch (emitErr) {
+                    log.debug({ runId, err: emitErr instanceof Error ? emitErr : undefined }, "orchestrate run_summary emit failed (non-fatal)");
+                }
+            };
+            log.debug({ runId, step: "start", language }, "orchestrate run starting");
+            // Resolve the seccomp fd ONCE, BEFORE the try (see the fd-lifecycle
+            // contract in seccomp-profile.ts). The fd is opened WITHOUT O_CLOEXEC so the bwrap child inherits
             // it — the parent (daemon) keeps its OWN copy after fork and MUST close it
             // in the finally below, or every jailed run leaks one descriptor and a
             // long-running daemon exhausts its fd table. Opening it here (not inside
-            // the try) means the finally always closes it even when writeFileSync /
-            // copyFileSync / resolveNode throws (those run after this point today, so
+            // the try) means the finally always closes it even when copyFileSync /
+            // resolveNode / the jailed run throws (those run after this point today, so
             // a throw there would otherwise leak the fd). Null on macOS (blob absent →
             // no --seccomp); closeSeccompProfileFd is null-safe + double-close-safe.
             const seccompFd = loadSeccompFd();
             try {
-                // 1. Write the model's script verbatim into the jailed workspace.
-                const scriptName = `${runId}.${params.language}`;
+                // 1. Resolve the script path (scriptName resolved above — the run's
+                //    `<runId>.<language>`, or the pinned scriptRef on a resume). The write
+                //    is deferred to the run engine (step 6) so the one-shot repair can
+                //    re-write the SAME path and re-run in the identical envelope.
                 const scriptPath = safePath(workspacePath, scriptName);
-                writeFileSync(scriptPath, params.script);
                 // 2. Copy the committed SDK + the runtime shim so the script can
                 //    `import "./comis_tools.js"` (which imports ./orchestrate-sdk-runtime.js).
                 for (const asset of SDK_ASSETS) {
                     copyFileSync(safePath(sdkAssetsDir, asset), safePath(workspacePath, asset));
                 }
                 log.debug({ runId, step: "sdk-written" }, "script + SDK written to workspace");
-                // 3. Honest-degrade (S4): resolve the jail node; refuse on unavailable —
-                //    NEVER a quiet host-side run outside the jail (T-212-18).
+                // 3. Honest-degrade: resolve the jail node; refuse on unavailable —
+                //    NEVER a quiet host-side run outside the jail.
                 const jailNode = resolveNode();
                 if (jailNode.mode === "unavailable") {
                     log.warn({ runId, errorKind: "precondition", hint: jailNode.hint }, "orchestrate jail unavailable — refusing to run");
                     throwToolError("not_implemented", "The orchestrate jail is unavailable on this host (no node/bwrap inside the jail).", { hint: jailNode.hint });
                 }
-                // 3b. CLI-05/06 honest-degrade: resolve the sha256-pinned comis-agent
-                //     binary. UNLIKE the node resolve, an unavailable (missing/tampered)
-                //     binary does NOT refuse the whole jail — it degrades ONLY the
-                //     comis-agent CLI surface (the orchestrate SCRIPT surface is
-                //     independent and still runs). A LOUD content-free WARN names the
-                //     cause; we then omit the bind + COMIS_AGENT_BIN (never a silent bind
-                //     of a missing/tampered binary — T-219-22 / T-219-24).
+                // 3a. Select the SCRIPT interpreter, honest-degrading the "py" surface.
+                //     ts/js run under the daemon node; "py" runs under the RO-bound host
+                //     python3 resolved by `resolvePython`. Resolve + refuse-on-unavailable
+                //     HERE — before buildArgs and the per-run lease mint — mirroring the
+                //     node refuse above: an absent interpreter NEVER falls through to a
+                //     silent unjailed run (INV-1 fail-closed). The interpreter is invoked
+                //     by its ABSOLUTE path (bind-mode node's execPath, or the resolved
+                //     pythonBin): a bare `node`/`python3` is not on the jail's scrubbed
+                //     PATH and would exit 127 (the #236 lesson). Python has no BIND net, so
+                //     `resolveJailPython` returns the absolute pythonBin directly.
+                let interp;
+                if (language === "py") {
+                    const jailPython = resolvePython();
+                    if (jailPython.mode === "unavailable") {
+                        log.warn({ runId, errorKind: "precondition", hint: jailPython.hint }, "orchestrate 'py' surface unavailable — refusing to run");
+                        throwToolError("not_implemented", "The orchestrate 'py' surface is unavailable on this host (no python3 inside the jail).", { hint: jailPython.hint });
+                    }
+                    interp = jailPython.pythonBin;
+                }
+                else {
+                    interp = jailNode.mode === "bind" ? jailNode.execPath : "node";
+                }
+                // 3b. Honest-degrade for the CLI surface: resolve the sha256-pinned
+                //     comis-agent binary. UNLIKE the node resolve, an unavailable
+                //     (missing/tampered) binary does NOT refuse the whole jail — it
+                //     degrades ONLY the comis-agent CLI surface (the orchestrate SCRIPT
+                //     surface is independent and still runs). A LOUD content-free WARN
+                //     names the cause; we then omit the bind + COMIS_AGENT_BIN (never a
+                //     silent bind of a missing/tampered binary).
                 const jailAgentCli = resolveAgentCli();
                 if (jailAgentCli.mode === "unavailable") {
                     log.warn({ runId, errorKind: "precondition", hint: jailAgentCli.hint }, "comis-agent CLI surface unavailable inside the jail (the orchestrate script surface still works)");
@@ -199,15 +342,15 @@ export function createOrchestrateTool(deps) {
                 //    The provider binds the curated SYSTEM_RO_PATHS itself (so jq + node
                 //    resolve); we pass NO extra readOnlyPaths (mirrors the cap-socket
                 //    .linux.test) — re-listing them here would route the curated
-                //    allow-list through the JAIL-03 discovery screen (a false-positive on
-                //    /etc/* paths that resolve into a blocked dir on some hosts).
-                //    `jailAgentCli` is passed verbatim — buildArgs RO-binds the binary
-                //    ONLY on mode "bind", omits it otherwise (CLI-05).
+                //    allow-list through the provider's read-only-path discovery screen
+                //    (a false-positive on /etc/* paths that resolve into a blocked dir
+                //    on some hosts). `jailAgentCli` is passed verbatim — buildArgs
+                //    RO-binds the binary ONLY on mode "bind", omits it otherwise.
                 // The jail `--bind`s `<workspace>/.tmp` as its writable temp; bwrap requires
                 // the bind SOURCE to exist, so create it BEFORE building the args. A missing
                 // `.tmp` makes bwrap fail at construction with "Can't find source path
-                // …/.tmp" → exit 1 on EVERY real jailed run (live VPS finding 2026-06-23;
-                // invisible to the macOS unit suite, which injects a fake spawn). Guarded by
+                // …/.tmp" → exit 1 on EVERY real jailed run (invisible to the macOS unit
+                // suite, which injects a fake spawn). Guarded by
                 // orchestrate-tool.test.ts.
                 const tempDir = safePath(workspacePath, ".tmp");
                 mkdirSync(tempDir, { recursive: true });
@@ -222,46 +365,135 @@ export function createOrchestrateTool(deps) {
                     jailNode,
                     jailAgentCli,
                 });
-                // The jailed command runs the script with node, from the workspace cwd.
-                // In BIND mode the daemon's node is --ro-bind'd at its absolute execPath
-                // but is NOT on the jail's scrubbed PATH (e.g. /usr/bin:/bin), so a bare
-                // `node` exits 127 (command not found). Invoke it by the resolved absolute
-                // path; in PATH mode the bare name resolves off a bound PATH dir. Latent
-                // since #236 — surfaced by the CI runner's hostedtoolcache node, which sits
-                // outside SYSTEM_RO_PATHS → BIND. Guarded by orchestrate-tool.test.ts.
-                const nodeBin = jailNode.mode === "bind" ? jailNode.execPath : "node";
-                const command = `${nodeBin} ${scriptName}`;
+                // Run the script with the interpreter resolved at step 3a (node for ts/js,
+                // python3 for py), invoked by its ABSOLUTE path from the workspace cwd — a
+                // bare `node`/`python3` is not on the jail's scrubbed PATH and exits 127.
+                const command = `${interp} ${scriptName}`;
                 const bin = args[0];
                 const spawnArgs = [...args.slice(1), "/bin/bash", "-c", command];
-                // 5. Env: the ORCH-02 scrub over the BASE env, THEN the lease placeholders
-                //    merged LAST (Pitfall 4 — they survive the scrub by construction).
+                // 5. Env: the secret scrub over the BASE env, THEN the lease placeholders
+                //    merged LAST (so they survive the scrub by construction).
                 const childEnv = scrubSecretEnv(deps.baseEnv);
                 if (deps.brokerSpawnEnv) {
                     Object.assign(childEnv, deps.brokerSpawnEnv.placeholders);
                 }
-                // 5b. CLI-05: expose COMIS_AGENT_BIN (the in-jail comis-agent path) ONLY
+                // 5a. Per-run child lease (D5): when the daemon threads the mint seam,
+                //     mint a short-TTL CHILD bearer for THIS run and inject it as
+                //     COMIS_CAP_LEASE — OVERRIDING the assembly bearer merged just above.
+                //     Every in-jail cap call then audits under this run's leaseId (the
+                //     INV-1 per-run correlator). Minted here (step 5), AFTER the
+                //     honest-degrade refusals (steps 3/3b), so a refused run wastes no
+                //     lease. Absent seam → the assembly bearer authenticates (never an
+                //     unauthenticated run). The child bearer is registered in OutputGuard
+                //     at mint (daemon side), so logging its leaseId (not the bearer) is safe.
+                if (deps.mintRunLease) {
+                    // Size the child-lease TTL to the run's ACTUAL lifetime. When one-shot
+                    // auto-repair is enabled for this run (a repair-eligible class AND a
+                    // wired repair seam), the run engine awaits one utility-model completion
+                    // — bounded by the seam's abort ceiling — BETWEEN the initial run and the
+                    // repaired re-run, all under THIS single lease. A lease sized to the tight
+                    // `timeoutMs` would expire during that repair await, so the repaired
+                    // re-run's in-jail cap calls would authenticate with a dead lease and be
+                    // denied (fails closed, but the repair silently no-ops for exactly the
+                    // slow/local small models it targets). Extend the TTL by the repair budget
+                    // so the ONE minted lease covers the run+repair window; when repair is off,
+                    // keep the tight `timeoutMs`. The lease is only SIZED here, never re-minted
+                    // — one leaseId per run (the INV-1 attribution the run_summary keys on) and
+                    // the same audience-bound child (INV-7) are both preserved.
+                    const repairEnabled = deps.repairSeam !== undefined && repairEnabledForClass(deps.capabilityClass);
+                    const leaseTtlMs = repairEnabled ? timeoutMs + REPAIR_LEASE_BUDGET_MS : timeoutMs;
+                    const child = deps.mintRunLease(runId, leaseTtlMs);
+                    childLeaseId = child.leaseId;
+                    childEnv.COMIS_CAP_LEASE = child.bearer;
+                    log.debug({ runId, leaseId: childLeaseId, step: "child-lease", leaseTtlMs, repairEnabled }, "per-run child lease minted (overrides the assembly bearer)");
+                }
+                // 5b. Expose COMIS_AGENT_BIN (the in-jail comis-agent path) ONLY
                 //     when the binary is bound. It is NOT a secret, so it is set AFTER the
                 //     scrub (like the lease vars). On "unavailable" it is intentionally
                 //     unset — the in-jail `comis-agent` then has no binary to resolve, the
-                //     loud WARN above already announced the scoped degrade (CLI-06).
+                //     loud WARN above already announced the scoped degrade.
                 if (jailAgentCli.mode === "bind") {
                     childEnv.COMIS_AGENT_BIN = jailAgentCli.binPath;
                 }
-                // 6. Spawn the jailed child; capture stdout ONLY (stderr/intermediate
-                //    never re-enter); size-bounce the stdout.
-                const stdout = await runJailedChild(spawnFn, bin, spawnArgs, { env: childEnv, cwd: undefined }, timeoutMs, { runId, log });
+                // A run reaches the jail WITH a lease iff COMIS_CAP_LEASE was set (the
+                // assembly bearer via brokerSpawnEnv, or the per-run child bearer via
+                // mintRunLease). A run with none is degraded — flagged lease_absent below.
+                const leasePresent = childEnv.COMIS_CAP_LEASE !== undefined;
+                // 5c. Register a resumable durable row (scriptRef set) BEFORE the run so a
+                //     mid-pipeline restart's boot sweep finds it (after the honest-degrade
+                //     refusals so a refused run writes no row). Best-effort; COALESCE-safe.
+                if (deps.durableRuns !== undefined) {
+                    await registerDurableRun(deps.durableRuns, {
+                        rootRunId: durableKey,
+                        scriptRef: scriptName,
+                        nowMs: now(),
+                    });
+                }
+                // 6. Run the jailed child, with a bounded one-shot auto-repair. Writes the
+                //    script into the workspace then drives the jailed child to completion
+                //    (stdout ONLY re-enters; stderr/intermediate never do). The initial run
+                //    and the single repaired re-run share the identical jail/cap/lease
+                //    envelope built above (bin / spawnArgs / childEnv / scriptPath). The
+                //    repair resolves the FINAL outcome HERE, before the terminal run_summary
+                //    emit below, so a repaired-then-succeeded run emits exactly one (success)
+                //    summary and an escaping error emits once in the outer catch.
+                const stdout = await runScriptWithOneShotRepair({
+                    spawnFn,
+                    bin,
+                    spawnArgs,
+                    childEnv,
+                    scriptPath,
+                    timeoutMs,
+                    script,
+                    language,
+                    capabilityClass: deps.capabilityClass,
+                    repairSeam: deps.repairSeam,
+                    log,
+                    runId,
+                });
                 const bounced = sizeBounceStdout(stdout);
+                // The POST-bounce char count — the tokens that actually re-entered
+                // context (the SAVE-01 "actual"; raw stdout.length would overstate).
+                const stdoutCharsReentered = bounced.reduce((sum, b) => sum + b.text.length, 0);
+                // A clean exit with NO lease is still a degraded run — name it
+                // lease_absent so `comis explain` can attribute the missing lease.
+                emitRunSummary({
+                    exitCode: 0,
+                    failureClass: leasePresent ? undefined : "lease_absent",
+                    stdoutBytesRaw: stdout.length,
+                    stdoutCharsReentered,
+                });
                 log.info({ runId, step: "complete", durationMs: now() - startedMs, stdoutBytes: stdout.length }, "orchestrate run complete");
                 return { content: bounced, details: { runId, stdoutBytes: stdout.length } };
             }
+            catch (err) {
+                // Every failure class emits a run_summary too — mapped to the closed
+                // enum, BEFORE the finally's cleanup wipes results/ — then re-throws so
+                // the AgentTool boundary still surfaces the original (bounded) tool error
+                // (the stderr tail stays on THAT surface, never on the bus).
+                const { failureClass, exitCode } = classifyRunError(err);
+                emitRunSummary({ exitCode, failureClass, stdoutBytesRaw: 0, stdoutCharsReentered: 0 });
+                // A durable-registered run that TIMED OUT becomes resumable: re-affirm the
+                // row + SKIP the finally cleanupRun so the pinned script + last checkpoint
+                // survive (the orphan sweep reclaims a truly-dead run). Others clean normally.
+                if (failureClass === "timeout" && deps.durableRuns !== undefined) {
+                    const decision = await markResumable(deps.durableRuns, {
+                        rootRunId: durableKey,
+                        scriptRef: scriptName,
+                        nowMs: now(),
+                    });
+                    skipCleanup = decision.skipCleanup;
+                }
+                throw err;
+            }
             finally {
-                // 7. CR-01: close the PARENT's copy of the seccomp fd. By the time the
+                // 7. Close the PARENT's copy of the seccomp fd. By the time the
                 //    finally runs the child has already inherited it (spawn returned, or
                 //    threw — either way the parent's copy is open and must be released).
                 //    null-safe + double-close-safe, so this is unconditional. Closing
                 //    BEFORE gcRun/cleanupRun guarantees a throwing GC cannot skip it.
                 closeSeccompProfileFd(seccompFd);
-                // 8. REF-03: the runner owns the run lifecycle — GC then drop the run's
+                // 8. The runner owns the run lifecycle — GC then drop the run's
                 //    results/ entries, on success AND on failure.
                 try {
                     await deps.store.gcRun({
@@ -274,129 +506,54 @@ export function createOrchestrateTool(deps) {
                 catch (gcErr) {
                     log.warn({ runId, errorKind: "resource", err: gcErr instanceof Error ? gcErr : undefined }, "orchestrate gcRun failed (non-fatal)");
                 }
-                await deps.store.cleanupRun({ workspacePath, runId });
+                // A resumable timeout SKIPS cleanupRun (which wipes ALL of results/, where
+                // the checkpoint lives). gcRun stays — the checkpoint's longer TTL spares it.
+                if (!skipCleanup) {
+                    await deps.store.cleanupRun({ workspacePath, runId });
+                    // A NON-resumable terminal run must not leak its durable row/pinned script
+                    // (only a resumable timeout keeps them; a no-op when the surface is off).
+                    await finalizeCompletedRun(deps.durableRuns, { rootRunId: durableKey, scriptRef: scriptName, workspacePath, runId }, log);
+                }
             }
         },
     };
 }
-// ---------------------------------------------------------------------------
-// Internals.
-// ---------------------------------------------------------------------------
-/**
- * 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 Error(`orchestrate run exceeded its ${timeoutMs}ms timeout`));
-        }, timeoutMs);
-        timer.unref?.();
-        child.stdout?.on("data", (chunk) => {
-            if (settled)
-                return;
-            // WR-01: bound the in-stream accumulation. The post-exit STDOUT_MAX_CHARS
-            // 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 Error(`orchestrate stdout exceeded the ${STDOUT_HARD_CAP_BYTES}B hard cap`));
-                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 Error(`orchestrate jailed child exited with code ${code}${tail ? `:\n${tail}` : ""}`));
-                return;
-            }
-            resolve(stdout);
-        });
-    });
-}
-/** Size-bounce the raw stdout into bounded text content (ORCH-01 / T-212-21). */
+/** Size-bounce the raw stdout into bounded text content. */
 function sizeBounceStdout(stdout) {
     const guard = createToolResultSizeGuard();
     const result = guard.truncateIfNeeded([{ type: "text", text: stdout }], STDOUT_MAX_CHARS, "orchestrate stdout");
     // The guard preserves the {type:"text", text} shape; map to the narrow block.
     return result.content.map((b) => ({ type: "text", text: b.text ?? "" }));
 }
-/** The default real spawn (the unit suite injects `spawnFn`; this is production). */
-const defaultSpawn = (bin, args, opts) => spawn(bin, args, {
+/** The default real spawn (the unit suite injects `spawnFn`; exported: the replay re-spawn drives it too). */
+export const defaultSpawn = (bin, args, opts) => spawn(bin, args, {
     env: opts.env,
     cwd: opts.cwd,
     stdio: ["ignore", "pipe", "pipe"],
 });
-/** The default jail-node resolver — probe the jail PATH / bind the daemon node. */
-function defaultResolveJailNode() {
+/** The default jail-node resolver — probe the jail PATH / bind the daemon node (exported: the replay re-spawn resolves identically). */
+export function defaultResolveJailNode() {
     return resolveJailNode({ pathDirs: SYSTEM_RO_PATHS, execPath: readExecPath() });
 }
+/**
+ * The default jail-python resolver — probe the ABSOLUTE host interpreter bin
+ * paths (NOT the SYSTEM_RO_PATHS directory roots `defaultResolveJailNode` uses).
+ * Python has no BIND fallback the way node does (there is no daemon-python to
+ * ro-bind), so probing roots (`/usr`,`/bin`) would falsely report `unavailable`
+ * on a host that has `/usr/bin/python3`. All three candidates live under the
+ * RO-bound `/usr`/`/bin`, so a hit is reachable in-jail at the same absolute path.
+ */
+export function defaultResolveJailPython() {
+    return resolveJailPython({
+        interpreterPaths: ["/usr/bin/python3", "/bin/python3", "/usr/local/bin/python3"],
+    });
+}
 /** Read `process.execPath` through a narrow boundary (the daemon's own node). */
 function readExecPath() {
     return process.execPath;
 }
 /**
- * The default comis-agent CLI resolver (CLI-05/06). Resolve the built entry +
+ * The default comis-agent CLI resolver. Resolve the built entry +
  * the committed manifest from `assetDir` (the built module dir, which carries
  * both via the copy-sandbox-assets step), read the pinned sha, and delegate to
  * `resolveJailAgentCli` (which hash-verifies the bound bytes). When the manifest
@@ -404,7 +561,7 @@ function readExecPath() {
  * — the CLI surface is off, the orchestrate SCRIPT surface still runs, NEVER an
  * unverified bind.
  */
-function defaultResolveJailAgentCli(assetDir) {
+export function defaultResolveJailAgentCli(assetDir) {
     const manifestPath = safePath(assetDir, COMIS_AGENT_MANIFEST_FILENAME);
     if (!existsSync(manifestPath)) {
         return {