comisai 1.0.45 → 1.0.46

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

@@ -0,0 +1,54 @@
+import { type ComisLogger } from "@comis/core";
+import { type OrchestrateDurableRuns } from "./orchestrate-durable.js";
+import { type OrchestrateSpawnFn } from "./orchestrate-repair.js";
+import type { JailAgentCliResolution, JailNodeResolution, JailPythonResolution, SandboxProvider } from "../sandbox/types.js";
+/**
+ * The input one deterministic replay hands the re-spawn — the validated root run
+ * id, the run's jailed workspace, the bound SEPARATE replay socket path, the
+ * ephemeral bearer, and the child env with `COMIS_ORCH_SOCKET`/`COMIS_CAP_LEASE`
+ * already pointed at the replay socket + bearer (built by the daemon caller).
+ * Structurally matches the daemon's `OrchestrateReplayRespawnInput`.
+ */
+export interface OrchestrateReplayRespawnInput {
+    readonly rootRunId: string;
+    readonly workspacePath: string;
+    readonly socketPath: string;
+    readonly bearer: string;
+    readonly childEnv: Record<string, string | undefined>;
+}
+/** The re-spawn closure: re-run the pinned bytes against the replay socket → stdout. */
+export type OrchestrateReplayRespawnFn = (input: OrchestrateReplayRespawnInput) => Promise<{
+    stdout: string;
+    diverged?: boolean;
+}>;
+/** Deps for {@link createOrchestrateReplayRespawn} (the composition root assembles it). */
+export interface OrchestrateReplayRespawnDeps {
+    /** The OS sandbox provider — the SAME one the orchestrate runner jails with. */
+    readonly sandbox: SandboxProvider;
+    /** The durable-run store — `getByRootRun` resolves the run's pinned scriptRef. */
+    readonly durableRuns: OrchestrateDurableRuns;
+    /** Structured logger. */
+    readonly logger: ComisLogger;
+    /** The inherited base env the child scrubs (the lease/socket ride the caller's childEnv). */
+    readonly baseEnv?: Record<string, string | undefined>;
+    /** The built module dir holding the SDK assets (defaults to this module's dir). */
+    readonly sdkAssetsDir?: string;
+    /** Replay wall-clock timeout (ms). */
+    readonly replayTimeoutMs?: number;
+    /** Test seam: the child spawn (defaults to the real production spawn). */
+    readonly spawnFn?: OrchestrateSpawnFn;
+    /** Test seam: the jail-node resolver (defaults to the runner's real resolver). */
+    readonly resolveJailNodeFn?: () => JailNodeResolution;
+    /** Test seam: the jail-python resolver (defaults to the runner's real resolver). */
+    readonly resolveJailPythonFn?: () => JailPythonResolution;
+    /** Test seam: the comis-agent CLI resolver (defaults to the runner's real resolver). */
+    readonly resolveJailAgentCliFn?: () => JailAgentCliResolution;
+    /** Test seam: the seccomp-fd loader (defaults to the real loader; null on macOS). */
+    readonly loadSeccompFdFn?: () => number | null;
+}
+/**
+ * Build the deterministic-replay re-spawn closure. Assembled once at the daemon
+ * composition root (it needs the sandbox provider) and threaded into the
+ * `orchestrate.replay` RPC's `OrchestrateReplayWiring.respawn`.
+ */
+export declare function createOrchestrateReplayRespawn(deps: OrchestrateReplayRespawnDeps): OrchestrateReplayRespawnFn;

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

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: the deterministic-replay re-spawn seam. It THROWS a content-free
+// error on a validation/jail-unavailable failure and lets runScriptWithOneShotRepair's
+// bounded run error propagate — the daemon's runOrchestrateReplaySession wraps this
+// in a try/finally (socket teardown) and rpc-dispatch converts the throw to a
+// JSON-RPC error (mirrors the orchestrate runner's throwToolError boundary).
+/**
+ * `createOrchestrateReplayRespawn` — the sandbox-backed pinned-byte re-spawn that
+ * `comis orchestrate replay <runId>` drives. It re-runs a durable orchestrate
+ * run's PINNED script bytes in the SAME jail envelope a live run uses, but with
+ * `COMIS_ORCH_SOCKET` pointed at the SEPARATE operator replay socket (INV-1) so
+ * the recorded results are served back deterministically — never the production
+ * capability endpoint.
+ *
+ * It composes the SHIPPED primitives verbatim (never a fork of the jail logic):
+ *   - {@link loadResumeSpec} — resolve the PINNED bytes (the sole source; the
+ *     operator supplies no script — T-WS4-03);
+ *   - the SAME `defaultResolveJailNode`/`defaultResolveJailPython`/
+ *     `defaultResolveJailAgentCli` resolvers + `SDK_ASSETS` copy + `scrubSecretEnv`
+ *     + `sandbox.buildArgs` the runner uses (so the replay jail is byte-identical);
+ *   - {@link runScriptWithOneShotRepair} with NO repair seam — a deterministic
+ *     replay must re-run the EXACT pinned bytes (a regenerated script would break
+ *     byte-identity).
+ *
+ * The real bwrap byte-identical round-trip is the `.linux`/VPS tier; this seam's
+ * LOGIC (pinned-byte load, INV-1 socket target, honest-degrade) is macOS-unit-
+ * testable with an injected spawn.
+ *
+ * @module
+ */
+import { copyFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { safePath } from "@comis/core";
+import { SDK_ASSETS, defaultResolveJailAgentCli, defaultResolveJailNode, defaultResolveJailPython, defaultSpawn, scrubSecretEnv, } from "./orchestrate-tool.js";
+import { defaultOrchestrateDurableFs, loadResumeSpec, } from "./orchestrate-durable.js";
+import { runScriptWithOneShotRepair } from "./orchestrate-repair.js";
+import { closeSeccompProfileFd, loadSeccompProfileFd } from "../sandbox/seccomp-profile.js";
+/** Default hard wall-clock timeout (ms) for a replay re-spawn. */
+const DEFAULT_REPLAY_TIMEOUT_MS = 60_000;
+/**
+ * Build the deterministic-replay re-spawn closure. Assembled once at the daemon
+ * composition root (it needs the sandbox provider) and threaded into the
+ * `orchestrate.replay` RPC's `OrchestrateReplayWiring.respawn`.
+ */
+export function createOrchestrateReplayRespawn(deps) {
+    const log = deps.logger.child({ submodule: "orchestrate-replay-respawn" });
+    const spawnFn = deps.spawnFn ?? defaultSpawn;
+    const resolveNode = deps.resolveJailNodeFn ?? defaultResolveJailNode;
+    const resolvePython = deps.resolveJailPythonFn ?? defaultResolveJailPython;
+    const loadSeccompFd = deps.loadSeccompFdFn ?? loadSeccompProfileFd;
+    const sdkAssetsDir = deps.sdkAssetsDir ?? dirname(fileURLToPath(import.meta.url));
+    const resolveAgentCli = deps.resolveJailAgentCliFn ?? (() => defaultResolveJailAgentCli(sdkAssetsDir));
+    const replayTimeoutMs = deps.replayTimeoutMs ?? DEFAULT_REPLAY_TIMEOUT_MS;
+    return async ({ rootRunId, workspacePath, socketPath, childEnv }) => {
+        // 1. Load the PINNED bytes (the sole source — the operator supplies no script).
+        const loaded = await loadResumeSpec(deps.durableRuns, defaultOrchestrateDurableFs, {
+            resumeRunId: rootRunId,
+            workspacePath,
+        });
+        if (!loaded.ok) {
+            throw new Error(`orchestrate replay: ${loaded.error}`);
+        }
+        const { scriptRef, scriptBytes, language } = loaded.value;
+        // 2. Copy the committed SDK + runtime shim so the pinned script's imports resolve
+        //    (the IDENTICAL asset set a live run gets; both paths safePath-confined).
+        for (const asset of SDK_ASSETS) {
+            copyFileSync(safePath(sdkAssetsDir, asset), safePath(workspacePath, asset));
+        }
+        // 3. Resolve the jail node / interpreter / CLI — honest-degrade (throw) on an
+        //    unavailable jail; NEVER a quiet host-side run outside the jail (INV-1 fail-closed).
+        const seccompFd = loadSeccompFd();
+        try {
+            const jailNode = resolveNode();
+            if (jailNode.mode === "unavailable") {
+                throw new Error(`orchestrate replay jail unavailable: ${jailNode.hint}`);
+            }
+            let interp;
+            if (language === "py") {
+                const jailPython = resolvePython();
+                if (jailPython.mode === "unavailable") {
+                    throw new Error(`orchestrate replay 'py' surface unavailable: ${jailPython.hint}`);
+                }
+                interp = jailPython.pythonBin;
+            }
+            else {
+                interp = jailNode.mode === "bind" ? jailNode.execPath : "node";
+            }
+            const jailAgentCli = resolveAgentCli();
+            // 4. Build the cap-socket jail args pointed at the SEPARATE replay socket
+            //    (INV-1) — never the production capability endpoint.
+            const tempDir = safePath(workspacePath, ".tmp");
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- safePath-confined to the run workspace (mirrors orchestrate-tool.ts).
+            mkdirSync(tempDir, { recursive: true });
+            const args = deps.sandbox.buildArgs({
+                workspacePath,
+                sharedPaths: [],
+                readOnlyPaths: [],
+                cwd: workspacePath,
+                tempDir,
+                network: { mode: "cap-socket", capSocketPath: socketPath },
+                seccompFd,
+                jailNode,
+                jailAgentCli,
+            });
+            const bin = args[0];
+            const spawnArgs = [...args.slice(1), "/bin/bash", "-c", `${interp} ${scriptRef}`];
+            // 5. Env: scrub the base, set COMIS_AGENT_BIN when the CLI is bound, THEN merge
+            //    the caller's childEnv LAST so COMIS_ORCH_SOCKET (→ the replay socket) +
+            //    COMIS_CAP_LEASE (→ the ephemeral bearer) ALWAYS win (INV-1 by construction).
+            const env = scrubSecretEnv(deps.baseEnv ?? {});
+            if (jailAgentCli.mode === "bind") {
+                env.COMIS_AGENT_BIN = jailAgentCli.binPath;
+            }
+            Object.assign(env, childEnv);
+            // 6. Re-spawn the PINNED bytes. Deterministic replay ⇒ NO auto-repair
+            //    (repairSeam/capabilityClass undefined) — a regenerated script would break
+            //    byte-identity. runScriptWithOneShotRepair writes the pinned bytes to the
+            //    scriptPath and drives the jailed child to completion.
+            const scriptPath = safePath(workspacePath, scriptRef);
+            const stdout = await runScriptWithOneShotRepair({
+                spawnFn,
+                bin,
+                spawnArgs,
+                childEnv: env,
+                scriptPath,
+                timeoutMs: replayTimeoutMs,
+                script: scriptBytes,
+                language,
+                capabilityClass: undefined,
+                repairSeam: undefined,
+                log,
+                runId: rootRunId,
+            });
+            log.info({ rootRunId, step: "replay-respawn-complete", stdoutBytes: stdout.length }, "orchestrate replay re-spawn complete");
+            return { stdout };
+        }
+        finally {
+            // Always close the inherited seccomp fd (null-safe + double-close-safe) — the
+            // parent keeps its own copy after fork; a leak exhausts the daemon fd table.
+            closeSeccompProfileFd(seccompFd);
+        }
+    };
+}

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

@@ -1,6 +1,6 @@
 import type { ResultRef } from "@comis/core";
 /**
- * A ResultRef decorated with the §23.9 in-jail extraction helpers (REF-02). The
+ * A ResultRef decorated with the in-jail extraction helpers. The
  * big (untrusted) payload stays materialized on the jailed workspace as DATA;
  * these helpers slice it IN-JAIL via the `orch:read`-gated read/grep/jq/sql/
  * jsonpath tools so only the relevant rows/lines re-enter context — the full
@@ -25,9 +25,9 @@ export interface WrappedResultRef extends ResultRef {
  * framing exactly. The `method` and `params` are passed THROUGH verbatim — the
  * caller decides whether it is a `tool.invoke` (see {@link invoke}) or a direct
  * orchestration method (`session.spawn`, `graph.execute`, `cron.add`, …, the
- * `comis-agent` CLI-04 subcommands). The lease (`COMIS_CAP_LEASE`) authenticates
+ * `comis-agent` subcommands). The lease (`COMIS_CAP_LEASE`) authenticates
  * every call; the unix cap socket (`COMIS_ORCH_SOCKET`) is the only egress — this
- * is deliberately NOT the loopback gateway WebSocket (the wire CLI-04 forbids).
+ * is deliberately NOT the loopback gateway WebSocket (the wire this design forbids).
  *
  * @param method - The wire method (e.g. `"tool.invoke"`, `"session.spawn"`).
  * @param params - The method params, forwarded verbatim (no envelope wrapping).
@@ -51,7 +51,7 @@ export declare function callCapSocket(method: string, params: Record<string, unk
  */
 export declare function invoke(tool: string, args?: Record<string, unknown>): Promise<unknown>;
 /**
- * Decorate a {@link ResultRef} with the in-jail extraction helpers (REF-02). The
+ * Decorate a {@link ResultRef} with the in-jail extraction helpers. The
  * generated SDK calls this for the high-volume tool returns; the helpers route
  * through {@link invoke} to the `orch:read`-gated read/grep/jq tools over the
  * materialized `results/` file, so only the requested slice re-enters context.

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

@@ -8,9 +8,9 @@
  * — the stable `./orchestrate-sdk-runtime.js` contract the generated
  * `comis_tools.js` imports (`invoke` + `wrapResultRef`), where each typed SDK
  * method delegates to {@link invoke}. `comis-agent`'s direct-method subcommands
- * (CLI-04) ride {@link callCapSocket} directly so they can dispatch a non-tool
+ * ride {@link callCapSocket} directly so they can dispatch a non-tool
  * method (`session.spawn`, `graph.execute`, …) without the `tool.invoke`
- * envelope. Both speak the exact wire the Phase-211 capability endpoint serves
+ * envelope. Both speak the exact wire the capability endpoint serves
  * (`setup-capability-endpoint.ts` — one `{ bearer, method, params }` line per
  * connection → one `{ result }` / `{ error }` line back).
  *
@@ -20,14 +20,14 @@
  * (`COMIS_CAP_LEASE`) authenticates every call, audience-bound at the endpoint.
  * So the runtime needs nothing but `node:net` + JSON — there is deliberately NO
  * WebSocket / gateway client: that loopback gateway transport is unreachable
- * from the `--unshare-net` jail and is the very wire CLI-04 forbids.
+ * from the `--unshare-net` jail and is the wire this containment design forbids.
  *
  * Globals rule (AGENTS.md §2.2): this runtime executes INSIDE the jail, which has
  * NO `node_modules` — so it MUST be self-contained (node built-ins only). It
  * therefore reads the two lease env vars via a local `process.env` accessor rather
  * than importing `@comis/core`'s `systemGetEnv` seam: that import is unreachable
  * from the jail and would make EVERY `comis_tools` import fail `ERR_MODULE_NOT_FOUND`
- * (live VPS finding 2026-06-23 — guarded by `orchestrate-sdk-self-contained.test.ts`).
+ * (guarded by `orchestrate-sdk-self-contained.test.ts`).
  *
  * @module
  */
@@ -39,7 +39,7 @@ import * as net from "node:net";
  */
 // eslint-disable-next-line no-restricted-syntax -- jailed runtime: process.env is the sole env source (no @comis/core seam reachable in the jail)
 const systemGetEnv = (name) => process.env[name];
-/** The method the runtime always sends — the one-route dispatch (v8 §6.2). */
+/** The method the runtime always sends — the one-route dispatch. */
 const TOOL_INVOKE_METHOD = "tool.invoke";
 /** The lease env var the cap socket authenticates each call with. */
 const ENV_CAP_LEASE = "COMIS_CAP_LEASE";
@@ -52,9 +52,9 @@ const ENV_ORCH_SOCKET = "COMIS_ORCH_SOCKET";
  * framing exactly. The `method` and `params` are passed THROUGH verbatim — the
  * caller decides whether it is a `tool.invoke` (see {@link invoke}) or a direct
  * orchestration method (`session.spawn`, `graph.execute`, `cron.add`, …, the
- * `comis-agent` CLI-04 subcommands). The lease (`COMIS_CAP_LEASE`) authenticates
+ * `comis-agent` subcommands). The lease (`COMIS_CAP_LEASE`) authenticates
  * every call; the unix cap socket (`COMIS_ORCH_SOCKET`) is the only egress — this
- * is deliberately NOT the loopback gateway WebSocket (the wire CLI-04 forbids).
+ * is deliberately NOT the loopback gateway WebSocket (the wire this design forbids).
  *
  * @param method - The wire method (e.g. `"tool.invoke"`, `"session.spawn"`).
  * @param params - The method params, forwarded verbatim (no envelope wrapping).
@@ -134,7 +134,7 @@ export function invoke(tool, args) {
     return callCapSocket(TOOL_INVOKE_METHOD, { tool, args: args ?? {} });
 }
 /**
- * Decorate a {@link ResultRef} with the in-jail extraction helpers (REF-02). The
+ * Decorate a {@link ResultRef} with the in-jail extraction helpers. The
  * generated SDK calls this for the high-volume tool returns; the helpers route
  * through {@link invoke} to the `orch:read`-gated read/grep/jq tools over the
  * materialized `results/` file, so only the requested slice re-enters context.

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

@@ -1,5 +1,5 @@
 /**
- * `orchestrate-tool` — the Surface-2 `orchestrate` runner (ORCH-01/02). The
+ * `orchestrate-tool` — the `orchestrate` runner. The
  * headline autonomy primitive: the model writes ONE script that chains
  * capability-scoped typed tools (the committed `comis_tools` SDK) in a jailed
  * child, and only size-bounded stdout re-enters context — a search→fetch→
@@ -7,25 +7,25 @@
  * ResultRefs (queried in-jail) rather than the transcript.
  *
  * It composes the SHIPPED substrate, adding NO new sandbox primitive:
- *   - the Phase-211 bwrap cap-socket jail (`BwrapProvider.buildArgs` with
+ *   - the bwrap cap-socket jail (`BwrapProvider.buildArgs` with
  *     `network:{mode:"cap-socket"}` → `--unshare-net` + the cap socket `--bind`;
  *     `~/.comis` is masked by construction — the jail binds only the workspace +
  *     `SYSTEM_RO_PATHS`, never the data dir).
- *   - `resolveJailNode` (JAIL-04) for the honest-degrade: no `node`/`bwrap`
+ *   - `resolveJailNode` for the honest-degrade: no `node`/`bwrap`
  *     inside the jail → a loud precondition error, NEVER a quiet host-side run
  *     outside the jail.
- *   - the committed `comis_tools.{d.ts,js}` SDK (Plan 03) + the
- *     `orchestrate-sdk-runtime.js` shim (Task 1), copied into the workspace so
+ *   - the committed `comis_tools.{d.ts,js}` SDK + the
+ *     `orchestrate-sdk-runtime.js` shim, copied into the workspace so
  *     the script can `import "./comis_tools.js"`.
- *   - the `result-ref-store` run lifecycle (Plan 03) — the runner owns
- *     `cleanupRun` (REF-03) in a `finally`.
+ *   - the `result-ref-store` run lifecycle — the runner owns
+ *     `cleanupRun` in a `finally`.
  *   - `createToolResultSizeGuard` (@comis/agent) for the stdout size-bounce.
  *
- * ORCH-02 (env-scrub): the inherited/base env is filtered through
+ * Env-scrub: the inherited/base env is filtered through
  * {@link scrubSecretEnv} (drop any `*KEY* / *TOKEN* / *SECRET*` key) BEFORE the
  * daemon-injected lease vars (`COMIS_CAP_LEASE`/`COMIS_ORCH_SOCKET`) are merged —
  * the lease vars ride `brokerSpawnEnv.placeholders`, merged LAST, so they survive
- * the scrub by construction (Pitfall 4). A host secret can never leak into the
+ * the scrub by construction. A host secret can never leak into the
  * jailed (attacker-controlled) child; the lease the SDK authenticates with always
  * does.
  *
@@ -38,40 +38,41 @@
  */
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
-import { type ComisLogger } from "@comis/core";
-import type { JailAgentCliResolution, JailNodeResolution, SandboxProvider } from "../sandbox/types.js";
-import type { CleanupRunContext, GcRunContext, MaterializeContext } from "./result-ref-store.js";
+import { type AgentCapability, type ComisLogger, type EventMap } from "@comis/core";
+import type { CapabilityClass } from "@comis/agent";
+import type { JailAgentCliResolution, JailNodeResolution, JailPythonResolution, SandboxProvider } from "../sandbox/types.js";
+import type { CleanupRunContext, GcRunContext, MaterializeContext, RunAggregateContext } from "./result-ref-store.js";
+import type { OrchestrateSpawnFn } from "./orchestrate-repair.js";
+import type { OrchestrateDurableRuns } from "./orchestrate-durable.js";
 import type { ResultRef } from "@comis/core";
+export { STDOUT_HARD_CAP_BYTES } from "./orchestrate-repair.js";
+export type { OrchestrateSpawnFn, OrchestrateSpawnedChild } from "./orchestrate-repair.js";
 declare const OrchestrateParams: Type.TObject<{
     script: Type.TString;
-    language: Type.TUnion<[Type.TLiteral<"ts">, Type.TLiteral<"js">]>;
+    language: Type.TUnion<[Type.TLiteral<"ts">, Type.TLiteral<"js">, Type.TLiteral<"py">]>;
     timeoutMs: Type.TOptional<Type.TInteger>;
     captureStdout: Type.TOptional<Type.TBoolean>;
+    resumeRunId: Type.TOptional<Type.TString>;
 }>;
-/** 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;
-/** Minimal store surface the runner needs (the run-lifecycle owner — REF-03). */
+/** Minimal store surface the runner needs (the runner owns the run lifecycle). */
 export interface OrchestrateResultStore {
     materialize(payload: string | Buffer, toolName: string, ctx: MaterializeContext): Promise<ResultRef | {
         error: string;
     } | undefined>;
     gcRun(ctx: GcRunContext): Promise<void>;
     cleanupRun(ctx: CleanupRunContext): Promise<void>;
+    /**
+     * Read the run's materialized `{count,bytes}` aggregate — a READ-ONLY
+     * enumeration of `results/`. The runner captures it BEFORE the `finally`
+     * `cleanupRun` wipes the dir (the run_summary savings input). Optional so a
+     * minimal stub store compiles; the concrete `createResultRefStore` always
+     * provides it. Absent ⇒ the runner treats the run as having materialized
+     * nothing (`{count:0,bytes:0}`).
+     */
+    runAggregate?(ctx: RunAggregateContext): {
+        count: number;
+        bytes: number;
+    };
 }
 /** Dependencies for the orchestrate runner (AGENTS.md §2.4 — injected). */
 export interface OrchestrateToolDeps {
@@ -82,21 +83,21 @@ export interface OrchestrateToolDeps {
     /**
      * The cap socket bound into the jail (`network:{mode:"cap-socket", capSocketPath}`).
      * Daemon-minted per-run path (conventionally `/run/comis` or the data dir) —
-     * Plan 05 threads it from the kept endpoint handle.
+     * the daemon wiring threads it from the kept endpoint handle.
      */
     readonly capSocketPath: string;
     /** The platform sandbox provider (BwrapProvider on Linux) — the arg generator. */
     readonly sandbox: SandboxProvider;
     /**
      * The daemon-injected lease-env carrier. `placeholders` (COMIS_CAP_LEASE /
-     * COMIS_ORCH_SOCKET) are merged AFTER the secret-scrub so they survive it
-     * (Pitfall 4). Optional: when absent the child gets no lease (the SDK calls
+     * COMIS_ORCH_SOCKET) are merged AFTER the secret-scrub so they survive it.
+     * Optional: when absent the child gets no lease (the SDK calls
      * would then fail their precondition — never a silent unauthenticated run).
      */
     readonly brokerSpawnEnv?: {
         readonly placeholders: Record<string, string>;
     };
-    /** The ResultRef store — the runner owns `cleanupRun` on run end (REF-03). */
+    /** The ResultRef store — the runner owns `cleanupRun` on run end. */
     readonly store: OrchestrateResultStore;
     /** The directory holding the committed SDK assets to copy into the jail. */
     readonly sdkAssetsDir?: string;
@@ -104,10 +105,17 @@ export interface OrchestrateToolDeps {
     readonly spawnFn?: OrchestrateSpawnFn;
     /** The jail-node resolver (default the real `resolveJailNode`). */
     readonly resolveJailNodeFn?: () => JailNodeResolution;
+    /**
+     * The jail-python resolver (default `defaultResolveJailPython`, which probes
+     * the ABSOLUTE host interpreter bin paths). Consumed ONLY on a `language:"py"`
+     * run: an `unavailable` verdict REFUSES the run (fail-closed, never a silent
+     * unjailed run); a `path` verdict supplies the absolute `pythonBin` to invoke.
+     */
+    readonly resolveJailPythonFn?: () => JailPythonResolution;
     /**
      * The comis-agent CLI-binary resolver (default `defaultResolveJailAgentCli`,
      * which resolves the dist entry + reads the committed manifest sha via
-     * `import.meta.url` and calls `resolveJailAgentCli`). CLI-05/06: a missing or
+     * `import.meta.url` and calls `resolveJailAgentCli`). A missing or
      * tampered binary makes ONLY the CLI surface unavailable (a loud WARN, no bind,
      * no COMIS_AGENT_BIN) — the orchestrate SCRIPT surface still runs.
      */
@@ -117,26 +125,119 @@ export interface OrchestrateToolDeps {
     /** Injected wall clock (default `systemNowMs`). */
     readonly now?: () => number;
     /**
-     * The base/inherited env to scrub (ORCH-02). REQUIRED — the daemon wiring
-     * (Plan 05) supplies the inherited env explicitly, so the runner never reads
+     * The base/inherited env to scrub. REQUIRED — the daemon wiring
+     * supplies the inherited env explicitly, so the runner never reads
      * an ambient global (AGENTS.md §2.2). The lease vars are added separately via
      * {@link brokerSpawnEnv}, merged AFTER the scrub.
      */
     readonly baseEnv: Record<string, string | undefined>;
+    /**
+     * The per-run child-lease mint seam (D5, EXPLAIN-01). When present, the
+     * runner mints a short-TTL CHILD lease per run and injects the returned
+     * `bearer` as `COMIS_CAP_LEASE` — OVERRIDING the assembly bearer that rides
+     * {@link brokerSpawnEnv}. The child lease shares the assembly's `rootRunId`
+     * (tree accounting untouched) with `parentLeaseId` = the assembly lease, so
+     * every in-jail cap call for the run audits under this run's `leaseId` (the
+     * INV-1 per-run correlator). The runner SIZES the `ttlMs` it passes: the run
+     * timeout, or the run timeout + the one-shot-repair budget when auto-repair is
+     * enabled (so the single lease outlives the repair-completion await into the
+     * repaired re-run). Minted daemon-side and threaded as a plain closure —
+     * the runner never imports the LeaseManager. Absent (older wiring) → the assembly
+     * bearer authenticates (no per-run mint; never an unauthenticated run).
+     */
+    readonly mintRunLease?: (runId: string, ttlMs: number) => {
+        leaseId: string;
+        bearer: string;
+    };
+    /**
+     * The agent-side event bus, structurally typed to the ONE channel this runner
+     * emits (the emit-capability-audit.ts EmitCapabilityAuditDeps precedent). When
+     * present, every run — success AND each failure class — emits a content-free
+     * `orchestrate:run_summary` at completion (the `comis explain` / `comis fleet`
+     * signal). Emit from the TOOL (not a daemon graph handler) because this
+     * threaded bus reaches the live per-session trajectory bridge; the bridge
+     * attaches at execute() START, so the completion-time emit always lands.
+     * Absent (older wiring) ⇒ no emit (never an error — the run is unaffected).
+     */
+    readonly eventBus?: {
+        emit: (event: "orchestrate:run_summary", payload: EventMap["orchestrate:run_summary"]) => unknown;
+    };
+    /**
+     * The tree-stable root the run's lease inherits — an attribution key on the
+     * run_summary event (the daemon-shared bus fans out to every session bridge, so
+     * the payload self-attributes, never inferred from ambient state). Threaded
+     * from `buildAutonomyToolWiring`. Absent ⇒ the emit falls back to the run's own
+     * `runId` (never undefined on the wire).
+     */
+    readonly rootRunId?: string;
+    /** The owning session — the other run_summary attribution key. Threaded from the wiring; absent for a heartbeat/cron run. */
+    readonly sessionKey?: string;
+    /**
+     * The agent's HELD capability set (fed from the resolved autonomy profile's
+     * `resolved.capabilities` daemon-side). When present, the pre-flight statically
+     * scans the model's script for its capability footprint and FAILS FAST pre-spawn
+     * with a cap-named error if the footprint needs a cap the agent lacks.
+     * This is ADVISORY UX only — it grants nothing; the bwrap cap-socket endpoint's
+     * default-deny-by-absence stays the sole authoritative boundary. Absent
+     * (older wiring) ⇒ the cap fail-fast is skipped (the endpoint still gates).
+     */
+    readonly allowedCaps?: readonly AgentCapability[];
+    /**
+     * The approval gate, structurally typed to the ONE method used (the eventBus-dep
+     * precedent). When present, the pre-flight fires ONE approval on the script's whole
+     * capability footprint (the exact sorted cap set) BEFORE spawn; a `!approved`
+     * resolution refuses the run. The daemon threads this seam ONLY when
+     * `config.approvals.enabled`, so seam-presence IS "approvals configured" — there is
+     * no rule engine (the reused gate is the whole mechanism). Absent ⇒ no approval fire.
+     */
+    readonly approvalGate?: {
+        requestApproval(req: {
+            toolName: string;
+            action: string;
+            params: Record<string, unknown>;
+            agentId: string;
+            sessionKey: string;
+            trustLevel: "admin" | "user" | "guest";
+            channelType?: string;
+        }): Promise<{
+            approved: boolean;
+            reason?: string;
+        }>;
+    };
+    /**
+     * The resolved capability class (operator override ?? provider-family), threaded
+     * daemon-side. The one-shot auto-repair is class-gated (ON for weaker models, OFF
+     * for stronger). Declared here as the contract the one-shot repair path consumes;
+     * UNUSED by the pre-flight gate. Absent ⇒ treat as the fail-safe class
+     * (repair-eligible) where consumed.
+     */
+    readonly capabilityClass?: CapabilityClass;
+    /**
+     * The daemon-minted one-shot repair completion closure (like {@link mintRunLease}):
+     * 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). Declared here as the contract the one-shot repair path consumes; UNUSED
+     * by the pre-flight gate. Absent ⇒ no repair.
+     */
+    readonly repairSeam?: (input: {
+        script: string;
+        language: "ts" | "js" | "py";
+        stderrTail: string;
+        describeDigest: string;
+    }) => Promise<string | undefined>;
+    /**
+     * The durable-run store port, threaded ONLY when the resume surface is on: the
+     * run registers a resumable row at start (scriptRef), a TIMEOUT re-affirms it +
+     * SKIPS cleanupRun, `resumeRunId` loads the pinned bytes. Absent ⇒ default-off.
+     */
+    readonly durableRuns?: OrchestrateDurableRuns;
 }
-/**
- * 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 declare const STDOUT_HARD_CAP_BYTES: number;
+/** The SDK asset filenames copied into the jail workspace (exported: the replay re-spawn reuses them). */
+export declare const SDK_ASSETS: readonly ["comis_tools.d.ts", "comis_tools.js", "comis_tools.py", "orchestrate-sdk-runtime.js"];
 /** Default hard timeout for a jailed run (ms). Exported for the clamp tests. */
 export declare const DEFAULT_TIMEOUT_MS = 60000;
 /**
- * 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
@@ -144,13 +245,13 @@ export declare const DEFAULT_TIMEOUT_MS = 60000;
  */
 export declare const MAX_TIMEOUT_MS: number;
 /**
- * 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.
  *
@@ -160,7 +261,7 @@ export declare const MAX_TIMEOUT_MS: number;
 export declare function scrubSecretEnv(base: Record<string, string | undefined>): Record<string, string>;
 /**
  * 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.
  *
@@ -169,7 +270,7 @@ export declare function scrubSecretEnv(base: Record<string, string | undefined>)
  */
 export declare function clampTimeoutMs(requested: number | undefined): number;
 /**
- * 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,
@@ -177,4 +278,26 @@ export declare function clampTimeoutMs(requested: number | undefined): number;
  * @returns The `orchestrate` AgentTool.
  */
 export declare function createOrchestrateTool(deps: OrchestrateToolDeps): AgentTool<typeof OrchestrateParams>;
-export {};
+/** The default real spawn (the unit suite injects `spawnFn`; exported: the replay re-spawn drives it too). */
+export declare const defaultSpawn: OrchestrateSpawnFn;
+/** The default jail-node resolver — probe the jail PATH / bind the daemon node (exported: the replay re-spawn resolves identically). */
+export declare function defaultResolveJailNode(): JailNodeResolution;
+/**
+ * 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 declare function defaultResolveJailPython(): JailPythonResolution;
+/**
+ * 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
+ * itself is absent (e.g. an old/partial build), honest-degrade to "unavailable"
+ * — the CLI surface is off, the orchestrate SCRIPT surface still runs, NEVER an
+ * unverified bind.
+ */
+export declare function defaultResolveJailAgentCli(assetDir: string): JailAgentCliResolution;