comisai 1.0.45 → 1.0.46

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/result-ref-store.d.ts

@@ -1,22 +1,22 @@
 /**
  * `result-ref-store` — the workspace-confined disk I/O + GC behind the minimal
- * `ResultRef` (REF-01/02/03). It materializes a high-volume tool return to
+ * `ResultRef`. It materializes a high-volume tool return to
  * `<workspace>/results/<id>.<kind>` and hands back a structured `ResultRef`; the
  * big payload stays on disk as DATA and is sliced in-jail (`jq`/`grep`/`read`)
- * the same turn, so only the tiny handle re-enters context (v8 §23.9
- * "materialize-then-extract", CaMeL §12.2 — an untrusted web/MCP payload never
+ * the same turn, so only the tiny handle re-enters context (the
+ * "materialize-then-extract" pattern — an untrusted web/MCP payload never
  * re-enters as control).
  *
- * This is the DISK half on top of Plan 01's PURE math (`@comis/core`
+ * This is the DISK half on top of the PURE math (`@comis/core`
  * `result-ref.ts`: `checkPerFileCap`/`selectEvictions`/`isExpired`/
  * `computeExpiresAt`) — the store does the fs, the core owns the GC arithmetic.
  *
- * It is NET-NEW and DISTINCT from `microcompaction-guard.ts` (the Gap-2 split —
- * do NOT conflate):
+ * It is NET-NEW and DISTINCT from `microcompaction-guard.ts` (do NOT
+ * conflate):
  *   - dir: `<workspace>/results/` (the jail's writable root), NOT
  *     `<sessionDir>/tool-results/`.
  *   - return: the structured `ResultRef` (`{ref,kind,bytes,...}`), NOT a string.
- *   - lifecycle: per-run, GC'd on orchestrate-run end (the Plan 04 runner calls
+ *   - lifecycle: per-run, GC'd on orchestrate-run end (the runner calls
  *     `gcRun`/`cleanupRun`), NOT session-lifetime.
  * It REUSES only the contained-write helpers (`ensureContainedDir`/
  * `writeRegularFile`, `@comis/observability` fs-safe.ts:408/582) — the same
@@ -32,6 +32,19 @@
  * @module
  */
 import { type ComisLogger, type ResultRef } from "@comis/core";
+/**
+ * The TTL for a durable CHECKPOINT ResultRef (RESUME-05) — deliberately far
+ * LONGER than {@link DEFAULT_TTL_MS} so a checkpoint outlives a full run PLUS a
+ * resume window: a run may last up to MAX_TIMEOUT_MS (~10 min) and then sit as a
+ * resumable durable row until an operator (or the boot sweep) resumes it, so the
+ * last checkpoint must survive well beyond the 30-min ordinary-result default.
+ * 24 h gives an overnight run that times out a full day to be resumed before the
+ * orphan sweep reclaims the (still capped) blob. The runner threads this via
+ * `MaterializeContext.ttlMs`; the per-file (8 MiB) + per-run aggregate caps are
+ * UNCHANGED — a checkpoint is capped exactly like any ResultRef (T-WS4-02), only
+ * its lifetime is longer.
+ */
+export declare const CHECKPOINT_TTL_MS: number;
 /** The materialized-content kinds (mirrors `ResultRef.kind`). */
 type ResultKind = ResultRef["kind"];
 /** Injected collaborators (AGENTS.md §2.4). */
@@ -64,6 +77,11 @@ export interface CleanupRunContext {
     readonly workspacePath: string;
     readonly runId: string;
 }
+/** Context for the per-run materialized-aggregate read (read-only enumeration). */
+export interface RunAggregateContext {
+    /** The jailed workspace path whose `results/` the aggregate enumerates. */
+    readonly workspacePath: string;
+}
 /** The content-free error a refuse/failed-write returns (never the payload). */
 export interface MaterializeError {
     /** A short, content-free reason (safe to surface to the agent/logs). */
@@ -82,6 +100,18 @@ export interface ResultRefStore {
     gcRun(ctx: GcRunContext): Promise<void>;
     /** Remove the run's `results/` entries on run end. */
     cleanupRun(ctx: CleanupRunContext): Promise<void>;
+    /**
+     * Read the run's materialized-result aggregate — the file count and total
+     * bytes currently under `<workspace>/results/`. READ-ONLY (it enumerates,
+     * never evicts), so the runner can capture it BEFORE {@link cleanupRun} wipes
+     * the dir. Content-free: counts + bytes only, never a path or content.
+     * Optional so a minimal stub store need not implement it; the concrete
+     * {@link createResultRefStore} always provides it.
+     */
+    runAggregate?(ctx: RunAggregateContext): {
+        count: number;
+        bytes: number;
+    };
 }
 /**
  * Infer the materialized {@link ResultKind} from the payload + the producing

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/result-ref-store.js

@@ -1,23 +1,23 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * `result-ref-store` — the workspace-confined disk I/O + GC behind the minimal
- * `ResultRef` (REF-01/02/03). It materializes a high-volume tool return to
+ * `ResultRef`. It materializes a high-volume tool return to
  * `<workspace>/results/<id>.<kind>` and hands back a structured `ResultRef`; the
  * big payload stays on disk as DATA and is sliced in-jail (`jq`/`grep`/`read`)
- * the same turn, so only the tiny handle re-enters context (v8 §23.9
- * "materialize-then-extract", CaMeL §12.2 — an untrusted web/MCP payload never
+ * the same turn, so only the tiny handle re-enters context (the
+ * "materialize-then-extract" pattern — an untrusted web/MCP payload never
  * re-enters as control).
  *
- * This is the DISK half on top of Plan 01's PURE math (`@comis/core`
+ * This is the DISK half on top of the PURE math (`@comis/core`
  * `result-ref.ts`: `checkPerFileCap`/`selectEvictions`/`isExpired`/
  * `computeExpiresAt`) — the store does the fs, the core owns the GC arithmetic.
  *
- * It is NET-NEW and DISTINCT from `microcompaction-guard.ts` (the Gap-2 split —
- * do NOT conflate):
+ * It is NET-NEW and DISTINCT from `microcompaction-guard.ts` (do NOT
+ * conflate):
  *   - dir: `<workspace>/results/` (the jail's writable root), NOT
  *     `<sessionDir>/tool-results/`.
  *   - return: the structured `ResultRef` (`{ref,kind,bytes,...}`), NOT a string.
- *   - lifecycle: per-run, GC'd on orchestrate-run end (the Plan 04 runner calls
+ *   - lifecycle: per-run, GC'd on orchestrate-run end (the runner calls
  *     `gcRun`/`cleanupRun`), NOT session-lifetime.
  * It REUSES only the contained-write helpers (`ensureContainedDir`/
  * `writeRegularFile`, `@comis/observability` fs-safe.ts:408/582) — the same
@@ -54,6 +54,19 @@ const PREVIEW_MAX_BYTES = 2048;
  * the runner may override via `ctx.ttlMs`.
  */
 const DEFAULT_TTL_MS = 30 * 60 * 1000;
+/**
+ * The TTL for a durable CHECKPOINT ResultRef (RESUME-05) — deliberately far
+ * LONGER than {@link DEFAULT_TTL_MS} so a checkpoint outlives a full run PLUS a
+ * resume window: a run may last up to MAX_TIMEOUT_MS (~10 min) and then sit as a
+ * resumable durable row until an operator (or the boot sweep) resumes it, so the
+ * last checkpoint must survive well beyond the 30-min ordinary-result default.
+ * 24 h gives an overnight run that times out a full day to be resumed before the
+ * orphan sweep reclaims the (still capped) blob. The runner threads this via
+ * `MaterializeContext.ttlMs`; the per-file (8 MiB) + per-run aggregate caps are
+ * UNCHANGED — a checkpoint is capped exactly like any ResultRef (T-WS4-02), only
+ * its lifetime is longer.
+ */
+export const CHECKPOINT_TTL_MS = 24 * 60 * 60 * 1000;
 // ---------------------------------------------------------------------------
 // Pure helpers (no fs, no clock) — kind inference, preview, id.
 // ---------------------------------------------------------------------------
@@ -166,7 +179,7 @@ export function createResultRefStore(deps) {
         const bytes = Buffer.isBuffer(payload)
             ? payload.byteLength
             : Buffer.byteLength(payload, "utf8");
-        // 1. Per-file cap (REF-03) — refuse (content-free) BEFORE any write.
+        // 1. Per-file cap — refuse (content-free) BEFORE any write.
         const capCheck = checkPerFileCap(bytes, PER_FILE_CAP_BYTES);
         if (!capCheck.ok) {
             log.warn({
@@ -355,5 +368,20 @@ export function createResultRefStore(deps) {
             log.debug({ err: e, hint: `best-effort unlink (${reason}) failed; will retry on next GC/cleanup` }, "Suppressed a results/ unlink failure");
         }
     }
-    return { materialize, gcRun, cleanupRun };
+    /**
+     * Fold the run's materialized results into a content-free `{count, bytes}`
+     * aggregate by re-using {@link listRunResults}. READ-ONLY — it enumerates and
+     * sums, never unlinks — so the runner may call it BEFORE gcRun/cleanupRun to
+     * learn what the run materialized. An absent/empty `results/` folds to
+     * `{count:0, bytes:0}` (listRunResults returns [] defensively — no error).
+     */
+    function runAggregate(ctx) {
+        const entries = listRunResults(ctx.workspacePath);
+        let bytes = 0;
+        for (const entry of entries) {
+            bytes += entry.bytes;
+        }
+        return { count: entries.length, bytes };
+    }
+    return { materialize, gcRun, cleanupRun, runAggregate };
 }

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

@@ -0,0 +1,43 @@
+/**
+ * `savings-estimate` — a pure, total estimator of the context tokens an
+ * orchestrate run saved by materializing large tool returns to disk (as a
+ * `ResultRef`) instead of re-entering them into the model context.
+ *
+ * It is a labeled ESTIMATE, not exact accounting — honesty over precision:
+ *   - the shipped ~4-bytes-per-token proxy ({@link BYTES_PER_TOKEN});
+ *   - MATERIALIZED-ONLY — it counts only the over-threshold returns that became
+ *     `ResultRef` files on disk; sub-threshold inline returns are excluded;
+ *   - POST-BOUNCE — the "actual" side is the bounded stdout that actually
+ *     re-entered context, not the raw pre-bounce size.
+ *
+ *   wouldBeTokens  ≈ materializedBytes / 4        (had each over-threshold
+ *                                                  return been its own
+ *                                                  tool-result turn)
+ *   actualTokens   ≈ stdoutCharsReentered / 4     (the bounded stdout re-entry)
+ *   estSavedTokens = max(0, wouldBeTokens − actualTokens)   (never negative)
+ *   savedRatio     = wouldBeTokens > 0 ? estSavedTokens / wouldBeTokens : 0
+ *
+ * Content-free: it takes and returns numbers only — never bytes-content, never a
+ * path. Pure arithmetic: no I/O, no globals, total over any finite non-negative
+ * input (a caller-facing boundary maps a run's measured bytes to these numbers).
+ *
+ * @module
+ */
+/** The estimate's shape: the counterfactual, the actual, the saved delta + ratio. */
+export interface SavingsEstimate {
+    /** Tokens the materialized returns WOULD have added had each re-entered context. */
+    readonly wouldBeTokens: number;
+    /** Tokens the bounded stdout actually re-entered context with. */
+    readonly actualTokens: number;
+    /** max(0, wouldBeTokens − actualTokens) — the saved delta, never negative. */
+    readonly estSavedTokens: number;
+    /** estSavedTokens / wouldBeTokens in [0, 1]; 0 when nothing was materialized. */
+    readonly savedRatio: number;
+}
+/**
+ * Estimate the context tokens a run saved by materializing large tool returns
+ * instead of re-entering them. Both inputs are byte/char counts the runner
+ * measures (the materialized `ResultRef` bytes; the post-bounce stdout chars);
+ * this helper is a pure function of the two.
+ */
+export declare function estimateSavings(materializedBytes: number, stdoutCharsReentered: number): SavingsEstimate;

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

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `savings-estimate` — a pure, total estimator of the context tokens an
+ * orchestrate run saved by materializing large tool returns to disk (as a
+ * `ResultRef`) instead of re-entering them into the model context.
+ *
+ * It is a labeled ESTIMATE, not exact accounting — honesty over precision:
+ *   - the shipped ~4-bytes-per-token proxy ({@link BYTES_PER_TOKEN});
+ *   - MATERIALIZED-ONLY — it counts only the over-threshold returns that became
+ *     `ResultRef` files on disk; sub-threshold inline returns are excluded;
+ *   - POST-BOUNCE — the "actual" side is the bounded stdout that actually
+ *     re-entered context, not the raw pre-bounce size.
+ *
+ *   wouldBeTokens  ≈ materializedBytes / 4        (had each over-threshold
+ *                                                  return been its own
+ *                                                  tool-result turn)
+ *   actualTokens   ≈ stdoutCharsReentered / 4     (the bounded stdout re-entry)
+ *   estSavedTokens = max(0, wouldBeTokens − actualTokens)   (never negative)
+ *   savedRatio     = wouldBeTokens > 0 ? estSavedTokens / wouldBeTokens : 0
+ *
+ * Content-free: it takes and returns numbers only — never bytes-content, never a
+ * path. Pure arithmetic: no I/O, no globals, total over any finite non-negative
+ * input (a caller-facing boundary maps a run's measured bytes to these numbers).
+ *
+ * @module
+ */
+/**
+ * The bytes→tokens proxy: roughly four bytes per token. A deliberate
+ * rule-of-thumb, not a tokenizer — the estimate is labeled as such.
+ */
+const BYTES_PER_TOKEN = 4;
+/**
+ * Estimate the context tokens a run saved by materializing large tool returns
+ * instead of re-entering them. Both inputs are byte/char counts the runner
+ * measures (the materialized `ResultRef` bytes; the post-bounce stdout chars);
+ * this helper is a pure function of the two.
+ */
+export function estimateSavings(materializedBytes, stdoutCharsReentered) {
+    const wouldBeTokens = Math.round(materializedBytes / BYTES_PER_TOKEN);
+    const actualTokens = Math.round(stdoutCharsReentered / BYTES_PER_TOKEN);
+    const estSavedTokens = Math.max(0, wouldBeTokens - actualTokens);
+    const savedRatio = wouldBeTokens > 0 ? estSavedTokens / wouldBeTokens : 0;
+    return { wouldBeTokens, actualTokens, estSavedTokens, savedRatio };
+}

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

@@ -1,7 +1,7 @@
 import type { ComisLogger } from "@comis/core";
 /**
  * The injected git-exec seam. Mirrors the daemon's `execGit` precedent
- * (`workspace-handlers.ts`) but in the plan's `{ stdout, exitCode }` shape so the
+ * (`workspace-handlers.ts`) but in a `{ stdout, exitCode }` shape so the
  * lifecycle never imports `child_process`. The daemon composition root binds a
  * real `execFile("git", args, { cwd })` wrapper; unit tests inject a fake that
  * returns scripted replies per `args`.

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

@@ -3,13 +3,13 @@
 // WorktreeGitError (carrying a closed-union `errorKind`) so a git failure / a
 // `git`-absent host fails LOUD — a worktree op MUST never silently become a
 // non-worktree spawn or silently treat a failed status-probe as "clean" (that
-// would risk deleting agent work, T-219-09). createWorktree's throw is caught at
+// would risk deleting agent work). createWorktree's throw is caught at
 // the runner/spawn boundary; sweepOrphans CATCHES the predicate's throw and
 // PRESERVES the entry (never aborts the whole sweep) so the conservative-sweep
 // invariant holds.
 /**
  * `worktree-lifecycle` — the net-new git-worktree lifecycle for
- * `comis-agent spawn --worktree` (WT-01/WT-02).
+ * `comis-agent spawn --worktree`.
  *
  * A spawned child can run in an ISOLATED git worktree (its own working tree on a
  * fresh branch) so parallel children never clobber each other's files. A worktree
@@ -23,7 +23,7 @@
  *   3. {@link cleanIfUnchanged}          — remove ONLY a pristine worktree (else preserve+report)
  *   4. {@link sweepOrphans}              — conservative orphan-sweep + `git worktree prune`
  *
- * ## The keystone: the clean-if-unchanged predicate is EXACT (T-219-09, Pitfall 5)
+ * ## The keystone: the clean-if-unchanged predicate is EXACT
  *
  * "Unchanged" means BOTH:
  *   - `git -C <dir> status --porcelain` produces ZERO lines — no staged, no
@@ -81,7 +81,7 @@ function classifyGitFailure(stdout) {
     return "internal";
 }
 // ---------------------------------------------------------------------------
-// createWorktree (WT-01)
+// createWorktree
 // ---------------------------------------------------------------------------
 /**
  * Create an isolated git worktree on a fresh branch:
@@ -111,7 +111,7 @@ export async function createWorktree(gitExec, opts) {
     return { dir, baseRef, branch, ...(runId !== undefined ? { runId } : {}) };
 }
 // ---------------------------------------------------------------------------
-// isWorktreeCleanIfUnchanged — THE PRECISE PREDICATE (T-219-09, Pitfall 5)
+// isWorktreeCleanIfUnchanged — THE PRECISE PREDICATE
 // ---------------------------------------------------------------------------
 /**
  * The EXACT clean-if-unchanged predicate. Returns `true` ONLY when:
@@ -211,7 +211,7 @@ function logPreserve(logger, entry, reason) {
     }, "worktree preserved — not clean-if-unchanged");
 }
 // ---------------------------------------------------------------------------
-// sweepOrphans — CONSERVATIVE orphan-sweep (WT-02, T-219-09/T-219-10)
+// sweepOrphans — CONSERVATIVE orphan-sweep
 // ---------------------------------------------------------------------------
 /**
  * Sweep a registry of worktree entries, reclaiming ONLY:

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

@@ -28,7 +28,7 @@ interface ToolLogger {
 }
 /**
  * Dependencies for the process tool factory. Backward compatibility is NOT
- * preserved (see CLAUDE.md user-memory `feedback_no_backward_compat`).
+ * preserved.
  *
  * `toolCapabilityPort` is REQUIRED — read inside the `case "status":` branch
  * to decide whether to augment the result envelope with the retroactive

package/node_modules/@comis/skills/dist/tools/builtin/sandbox/bwrap-provider.d.ts

@@ -6,9 +6,9 @@
  *
  * @module
  */
-import type { JailAgentCliResolution, JailNodeResolution, SandboxOptions, SandboxProvider } from "./types.js";
+import type { JailAgentCliResolution, JailNodeResolution, JailPythonResolution, SandboxOptions, SandboxProvider } from "./types.js";
 /**
- * JAIL-04 / v8 §4.6 — Node-runtime honesty. Surfaces 2/3 (orchestrate / CLI)
+ * Node-runtime honesty. Surfaces 2/3 (orchestrate / CLI)
  * need a `node` INSIDE the jail; there is NO bundled Node. Resolve, in order:
  *   1. PROBE — a `node` executable resolves under one of the bound RO `pathDirs`
  *      (the SYSTEM_RO_PATHS + ~/.nvm binds put one there on most hosts) → "path"
@@ -17,8 +17,8 @@ import type { JailAgentCliResolution, JailNodeResolution, SandboxOptions, Sandbo
  *      (precedent: the terminal-driver execPath binds) → "bind".
  *   3. UNAVAILABLE — else surfaces 2/3 cannot run jailed; the caller surfaces a
  *      loud doctor/boot signal. The hint NEVER claims a bundled Node and NEVER
- *      implies a silent unjailed fallback (T-211-21 spoofing). Surface 1
- *      (in-process typed tools) still works.
+ *      implies a silent unjailed fallback — either would spoof containment
+ *      that does not exist. Surface 1 (in-process typed tools) still works.
  *
  * PURE: the only I/O is the injected `exists` predicate (defaults to
  * `existsSync`), so the resolver is macOS-unit-testable with a fake PATH/execPath.
@@ -30,19 +30,52 @@ export declare function resolveJailNode(opts: {
     readonly exists?: (p: string) => boolean;
 }): JailNodeResolution;
 /**
- * CLI-05/06 — comis-agent CLI-binary honesty. The `comis-agent` CLI surface
+ * Python-runtime honesty. The orchestrate `"py"` surface needs a `python3`
+ * interpreter INSIDE the jail; the interpreter comes from the RO-bound host
+ * `/usr`/`/bin` (nothing installs Python). Resolve in two honest modes:
+ *   1. PATH — the FIRST absolute candidate in `interpreterPaths` that `exists`
+ *      → `{ mode: "path", pythonBin }`. The runner invokes that ABSOLUTE path
+ *      (a bare `python3` could resolve off the child PATH to an unintended
+ *      interpreter, or exit 127).
+ *   2. UNAVAILABLE — none exist → `{ mode: "unavailable", hint }`. There is NO
+ *      bind fallback (unlike resolveJailNode's `process.execPath` net — the
+ *      daemon is Node, there is no daemon-python to bind), so a missing
+ *      interpreter is ALWAYS a LOUD unavailable. The caller must fail CLOSED:
+ *      refuse the run, NEVER fall through to a silent unjailed execution. The
+ *      hint NEVER claims a bundled Python (that would spoof containment that
+ *      does not exist).
+ *
+ * CRITICAL: probe ABSOLUTE interpreter paths (e.g. `/usr/bin/python3`), NOT
+ * directory roots. resolveJailNode is called with the SYSTEM_RO_PATHS roots
+ * (`/usr`, `/bin`) and joins `dir + "/node"`; it survives the `/usr/node` miss
+ * only because BIND(execPath) is its safety net. Python has no such net, so
+ * probing roots would falsely report `unavailable` on a host that HAS
+ * `/usr/bin/python3`. Callers pass absolute candidate paths; this resolver does
+ * NO join over its inputs.
+ *
+ * PURE: the only I/O is the injected `exists` predicate (defaults to
+ * `existsSync`), so the resolver is macOS-unit-testable with a fake filesystem.
+ */
+export declare function resolveJailPython(opts: {
+    /** ABSOLUTE candidate interpreter paths (e.g. /usr/bin/python3), NOT roots. */
+    readonly interpreterPaths: readonly string[];
+    /** Existence predicate (defaults to fs.existsSync) — injected for unit tests. */
+    readonly exists?: (p: string) => boolean;
+}): JailPythonResolution;
+/**
+ * comis-agent CLI-binary honesty. The `comis-agent` CLI surface
  * needs its `#!/usr/bin/env node` entry (`comis-agent-entry.js`) bound into the
  * jail, sha256-PINNED against the committed build manifest so a swapped/modified
- * binary is never bound (T-219-22 tampering). Resolve in two honest modes:
+ * (tampered) binary is never bound. Resolve in two honest modes:
  *   1. BIND — the entry exists AND its sha256 matches `expectedSha` (the manifest
  *      pin) → RO-bind it (src==dest, so COMIS_AGENT_BIN/PATH resolves it in-jail).
  *   2. UNAVAILABLE — the entry is MISSING, or present but its bytes do NOT match
  *      the pin (tamper) → the CLI surface is UNAVAILABLE with a LOUD, content-free
- *      hint (CLI-06). The caller (orchestrate-tool) degrades ONLY the CLI surface
+ *      hint. The caller (orchestrate-tool) degrades ONLY the CLI surface
  *      — the orchestrate SCRIPT surface still runs (unlike resolveJailNode, an
  *      unavailable comis-agent binary does NOT refuse the whole jail).
  *
- * Content-free (§2.7): the hint names the CAUSE (missing | hash-mismatch) and the
+ * Content-free: the hint names the CAUSE (missing | hash-mismatch) and the
  * operator action — it NEVER echoes the expected hash or the binary bytes.
  *
  * PURE: the only I/O is the injected `exists` predicate (defaults to existsSync)

package/node_modules/@comis/skills/dist/tools/builtin/sandbox/bwrap-provider.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-// @allow-throw: (1) exhaustiveness guard on networkMode union; unreachable at runtime, caught by TypeScript; equivalent to assertNever(). (2) JAIL-03 screenBind() fails LOUD at jail construction on a denylisted bind — a misconfig must never be a silently-emitted hole.
+// @allow-throw: (1) exhaustiveness guard on networkMode union; unreachable at runtime, caught by TypeScript; equivalent to assertNever(). (2) screenBind() fails LOUD at jail construction on a denylisted bind — a misconfig must never be a silently-emitted hole.
 /**
  * BwrapProvider -- Linux sandbox provider using Bubblewrap (bwrap).
  *
@@ -15,7 +15,7 @@ import os from "node:os";
 import { join } from "node:path";
 import { safePath, validateBindMount } from "@comis/core";
 /**
- * JAIL-04 / v8 §4.6 — Node-runtime honesty. Surfaces 2/3 (orchestrate / CLI)
+ * Node-runtime honesty. Surfaces 2/3 (orchestrate / CLI)
  * need a `node` INSIDE the jail; there is NO bundled Node. Resolve, in order:
  *   1. PROBE — a `node` executable resolves under one of the bound RO `pathDirs`
  *      (the SYSTEM_RO_PATHS + ~/.nvm binds put one there on most hosts) → "path"
@@ -24,8 +24,8 @@ import { safePath, validateBindMount } from "@comis/core";
  *      (precedent: the terminal-driver execPath binds) → "bind".
  *   3. UNAVAILABLE — else surfaces 2/3 cannot run jailed; the caller surfaces a
  *      loud doctor/boot signal. The hint NEVER claims a bundled Node and NEVER
- *      implies a silent unjailed fallback (T-211-21 spoofing). Surface 1
- *      (in-process typed tools) still works.
+ *      implies a silent unjailed fallback — either would spoof containment
+ *      that does not exist. Surface 1 (in-process typed tools) still works.
  *
  * PURE: the only I/O is the injected `exists` predicate (defaults to
  * `existsSync`), so the resolver is macOS-unit-testable with a fake PATH/execPath.
@@ -53,19 +53,63 @@ export function resolveJailNode(opts) {
     };
 }
 /**
- * CLI-05/06 — comis-agent CLI-binary honesty. The `comis-agent` CLI surface
+ * Python-runtime honesty. The orchestrate `"py"` surface needs a `python3`
+ * interpreter INSIDE the jail; the interpreter comes from the RO-bound host
+ * `/usr`/`/bin` (nothing installs Python). Resolve in two honest modes:
+ *   1. PATH — the FIRST absolute candidate in `interpreterPaths` that `exists`
+ *      → `{ mode: "path", pythonBin }`. The runner invokes that ABSOLUTE path
+ *      (a bare `python3` could resolve off the child PATH to an unintended
+ *      interpreter, or exit 127).
+ *   2. UNAVAILABLE — none exist → `{ mode: "unavailable", hint }`. There is NO
+ *      bind fallback (unlike resolveJailNode's `process.execPath` net — the
+ *      daemon is Node, there is no daemon-python to bind), so a missing
+ *      interpreter is ALWAYS a LOUD unavailable. The caller must fail CLOSED:
+ *      refuse the run, NEVER fall through to a silent unjailed execution. The
+ *      hint NEVER claims a bundled Python (that would spoof containment that
+ *      does not exist).
+ *
+ * CRITICAL: probe ABSOLUTE interpreter paths (e.g. `/usr/bin/python3`), NOT
+ * directory roots. resolveJailNode is called with the SYSTEM_RO_PATHS roots
+ * (`/usr`, `/bin`) and joins `dir + "/node"`; it survives the `/usr/node` miss
+ * only because BIND(execPath) is its safety net. Python has no such net, so
+ * probing roots would falsely report `unavailable` on a host that HAS
+ * `/usr/bin/python3`. Callers pass absolute candidate paths; this resolver does
+ * NO join over its inputs.
+ *
+ * PURE: the only I/O is the injected `exists` predicate (defaults to
+ * `existsSync`), so the resolver is macOS-unit-testable with a fake filesystem.
+ */
+export function resolveJailPython(opts) {
+    const exists = opts.exists ?? existsSync;
+    // PROBE each absolute candidate path; the first that exists is the interpreter.
+    for (const p of opts.interpreterPaths) {
+        if (exists(p)) {
+            return { mode: "path", pythonBin: p };
+        }
+    }
+    // UNAVAILABLE — honest, fail-closed degrade. NEVER a bundled-Python claim.
+    return {
+        mode: "unavailable",
+        hint: "The orchestrate 'py' surface needs a python3 interpreter inside the jail; " +
+            "none found under /usr/bin, /bin, or /usr/local/bin (the RO-bound host " +
+            "paths). Install python3 on the host. There is NEVER a bundled Python and " +
+            "NEVER a silent unjailed run.",
+    };
+}
+/**
+ * comis-agent CLI-binary honesty. The `comis-agent` CLI surface
  * needs its `#!/usr/bin/env node` entry (`comis-agent-entry.js`) bound into the
  * jail, sha256-PINNED against the committed build manifest so a swapped/modified
- * binary is never bound (T-219-22 tampering). Resolve in two honest modes:
+ * (tampered) binary is never bound. Resolve in two honest modes:
  *   1. BIND — the entry exists AND its sha256 matches `expectedSha` (the manifest
  *      pin) → RO-bind it (src==dest, so COMIS_AGENT_BIN/PATH resolves it in-jail).
  *   2. UNAVAILABLE — the entry is MISSING, or present but its bytes do NOT match
  *      the pin (tamper) → the CLI surface is UNAVAILABLE with a LOUD, content-free
- *      hint (CLI-06). The caller (orchestrate-tool) degrades ONLY the CLI surface
+ *      hint. The caller (orchestrate-tool) degrades ONLY the CLI surface
  *      — the orchestrate SCRIPT surface still runs (unlike resolveJailNode, an
  *      unavailable comis-agent binary does NOT refuse the whole jail).
  *
- * Content-free (§2.7): the hint names the CAUSE (missing | hash-mismatch) and the
+ * Content-free: the hint names the CAUSE (missing | hash-mismatch) and the
  * operator action — it NEVER echoes the expected hash or the binary bytes.
  *
  * PURE: the only I/O is the injected `exists` predicate (defaults to existsSync)
@@ -87,7 +131,7 @@ export function resolveJailAgentCli(opts) {
         };
     }
     // 2. HASH MISMATCH (tamper) — present but its bytes diverge from the manifest
-    //    pin. REFUSE to bind a tampered binary (T-219-22); the CLI surface is
+    //    pin. REFUSE to bind a tampered binary; the CLI surface is
     //    unavailable. The hint NEVER echoes the hash or the bytes (content-free).
     const actualSha = createHash("sha256").update(readFile(opts.binPath)).digest("hex");
     if (actualSha !== opts.expectedSha) {
@@ -104,10 +148,10 @@ export function resolveJailAgentCli(opts) {
     return { mode: "bind", binPath: opts.binPath };
 }
 /**
- * Screen a caller-controlled host bind path through the JAIL-03 denylist
+ * Screen a caller-controlled host bind path through the credential-denylist
  * backstop (validateBindMount) before it is emitted as a `--bind`/`--ro-bind`.
  *
- * Scope (v8 invariant 10 — the validator is a DENYLIST BACKSTOP on the ALLOW-LIST
+ * Scope (the validator is a DENYLIST BACKSTOP on the ALLOW-LIST
  * binds, NOT the primary boundary): this screens the DYNAMIC, caller/agent-supplied
  * binds — the workspace, the temp dir, operator/graph shared paths, and skill
  * discovery read-only paths — which are the attack surface (an agent/operator
@@ -261,7 +305,7 @@ export class BwrapProvider {
             this.available();
         }
         const args = [this.bwrapPath];
-        // WR-05: the credential-denylist base (`validateBindMount(hostPath, home)`)
+        // The credential-denylist base (`validateBindMount(hostPath, home)`)
         // must be an EXPLICIT trusted value, not a hidden ambient read inside this
         // pure arg generator. Prefer the caller-supplied `opts.home` (resolved once
         // from trusted config); fall back to `os.homedir()` only when omitted, so
@@ -269,12 +313,12 @@ export class BwrapProvider {
         // default rather than an implicit coupling. With `opts.home` supplied the
         // generator is deterministic (the screen-vs-bind interaction is unit-testable
         // without mocking process env), matching the purity discipline the rest of
-        // the JAIL-03 surface (getUserRoPaths(home), validateBindMount(_, home))
+        // the bind-screening surface (getUserRoPaths(home), validateBindMount(_, home))
         // already follows.
         const home = opts.home ?? os.homedir();
         // -- System paths (read-only, cached at first call) --
         // CURATED allow-list — the vetted boundary itself; NOT screened by the
-        // JAIL-03 denylist backstop (it would false-positive on /etc/resolv.conf).
+        // credential-denylist backstop (it would false-positive on /etc/resolv.conf).
         for (const sysPath of this.getSystemPaths()) {
             args.push("--ro-bind", sysPath, sysPath);
         }
@@ -285,15 +329,15 @@ export class BwrapProvider {
         // -- Temp directory (read-write) --
         args.push("--tmpfs", "/tmp");
         if (opts.tempDir && opts.tempDir !== "/tmp") {
-            screenBind(opts.tempDir, home); // JAIL-03: caller-controlled → screened.
+            screenBind(opts.tempDir, home); // caller-controlled → screened.
             args.push("--bind", opts.tempDir, opts.tempDir);
         }
         // -- Workspace (read-write) --
-        screenBind(opts.workspacePath, home); // JAIL-03: caller-controlled → screened.
+        screenBind(opts.workspacePath, home); // caller-controlled → screened.
         args.push("--bind", opts.workspacePath, opts.workspacePath);
         // -- Shared paths (read-write) --
         for (const sp of opts.sharedPaths) {
-            screenBind(sp, home); // JAIL-03: operator/graph-supplied → screened.
+            screenBind(sp, home); // operator/graph-supplied → screened.
             args.push("--bind", sp, sp);
         }
         // -- User config paths (read-only) --
@@ -325,11 +369,11 @@ export class BwrapProvider {
         // -- Read-only paths (discovery paths, custom) --
         for (const ro of opts.readOnlyPaths) {
             if (existsSync(ro)) {
-                screenBind(ro, home); // JAIL-03: discovery/operator-supplied → screened.
+                screenBind(ro, home); // discovery/operator-supplied → screened.
                 args.push("--ro-bind", ro, ro);
             }
         }
-        // -- Node runtime (JAIL-04 / v8 §4.6) --
+        // -- Node runtime --
         // When the resolved Node mode is "bind", RO-bind the daemon's node binary so
         // surfaces 2/3 (orchestrate/CLI) have a node inside the jail. READ-ONLY only
         // — a writable interpreter binary is a host-RCE vector. "path" (node already
@@ -339,12 +383,12 @@ export class BwrapProvider {
         if (opts.jailNode?.mode === "bind") {
             args.push("--ro-bind", opts.jailNode.execPath, opts.jailNode.execPath);
         }
-        // -- comis-agent CLI binary (CLI-05) --
+        // -- comis-agent CLI binary --
         // When the resolved CLI mode is "bind", RO-bind the sha256-pinned comis-agent
         // entry so the in-jail `comis-agent` CLI resolves (the caller sets
         // COMIS_AGENT_BIN to this same path). READ-ONLY only — a writable binary is a
-        // host-RCE vector (the §4.7 .linux audit proves a write to it from the jail
-        // fails). src==dest so COMIS_AGENT_BIN/PATH resolves it in-jail. The mode is a
+        // host-RCE vector (the .linux hardening suite proves a write to it from the
+        // jail fails). src==dest so COMIS_AGENT_BIN/PATH resolves it in-jail. The mode is a
         // RESOLVED INPUT (resolveJailAgentCli — hash-verified), never a live fs probe.
         // "unavailable" (missing/tampered) emits NO bind — the caller degrades ONLY
         // the CLI surface (the script surface is unaffected).
@@ -372,11 +416,11 @@ export class BwrapProvider {
             // none: kernel-enforced deny-all egress — --unshare-all already dropped the
             // netns; we simply do NOT re-share it (no --share-net, no socket, no proxy).
             // The skill-validation jail uses this so a synthesized script cannot reach
-            // the network during dynamic validation (T-201-35).
+            // the network during dynamic validation.
             args.push("--unshare-net");
         }
         else if (networkMode === "cap-socket") {
-            // cap-socket (Phase 211, ENDPOINT-03): kernel-enforced network namespace;
+            // cap-socket: kernel-enforced network namespace;
             // the capability-lease loopback endpoint's 0600 unix socket is reachable
             // via bind-mount only. Mirrors broker-only arg-order EXACTLY — --unshare-net
             // FIRST, then the socket --bind — because a netns affects IP sockets only,
@@ -386,7 +430,7 @@ export class BwrapProvider {
             // NOT screened: like the broker socket, the cap socket is a DAEMON-MINTED
             // per-run path (conventionally /run/comis or the data dir) — part of the
             // trusted allow-list, not the agent-supplied attack surface the denylist
-            // backstop guards. The endpoint (211-06) chooses this path, not the agent.
+            // backstop guards. The endpoint chooses this path, not the agent.
             args.push("--bind", capSocketPath, capSocketPath);
         }
         else {
@@ -396,11 +440,11 @@ export class BwrapProvider {
             throw new Error(`Unhandled network mode: ${String(_exhaustive)}`);
         }
         args.push("--die-with-parent", "--new-session");
-        // -- Seccomp profile (JAIL-01) --
+        // -- Seccomp profile --
         // bwrap --seccomp takes an FD to raw BPF bytecode (resolved by the caller via
         // loadSeccompProfileFd(); buildArgs stays a pure arg generator). Emit ONLY
         // when an fd is provided — a null/absent blob degrades to NO --seccomp (the
-        // other §4.7 controls above still apply). The .linux.test.ts proves the blob
+        // other hardening controls above still apply). The .linux.test.ts proves the blob
         // actually blocks the dangerous syscalls on the VPS.
         if (typeof opts.seccompFd === "number") {
             args.push("--seccomp", String(opts.seccompFd));