@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/substrate/sandbox-exec.d.ts

@@ -0,0 +1,116 @@
+import type { CommandRunner, Substrate, SubstrateHandle, SubstrateSpec } from './types';
+/** Injectable deps — default-wired to the real runtime; stubbed in unit tests. */
+export interface SandboxExecDeps {
+    /** Process layer (default: `node:child_process`). */
+    runner?: CommandRunner;
+    /** Override the temp dir for the generated profile (default: os.tmpdir()). */
+    profileRoot?: string;
+    /**
+     * Override the platform check (default: `process.platform`). A5 is macOS-only
+     * — a non-`darwin` platform yields {@link SubstrateUnavailableError}.
+     */
+    platform?: NodeJS.Platform;
+}
+/**
+ * Generate the Seatbelt profile string for a worktree (§3.1, `coarse` tier).
+ *
+ * Profile shape (the load-bearing tokens the conformance test pins):
+ *   `(version 1)` `(deny default)` — deny everything not explicitly allowed.
+ *   `(allow process-exec*)` / `(allow process-fork)` — let the agent process
+ *                                  bootstrap + spawn its own tooling.
+ *   `(allow mach-lookup)` + `(deny mach-lookup (global-name "com.apple.
+ *                                  SecurityServer"/"…securityd"/"…securityd.xpc"))`
+ *                                  — broad mach IPC to launch, but the Keychain
+ *                                  (securityd) services denied last as DEFENSE-IN-
+ *                                  DEPTH against a same-user agent reading the
+ *                                  vendor key via keytar's `SecKeychain*` mach
+ *                                  path. Empirically (see the deny block below),
+ *                                  keytar leaks the vendor key ONLY when BOTH the
+ *                                  securityd mach service AND the keychain DB
+ *                                  *file* are reachable; A5 never grants `$HOME`
+ *                                  (so the keychain file is already denied), and
+ *                                  this securityd deny is the second, independent
+ *                                  lock. Either lock alone blocks keytar — kept
+ *                                  belt-and-suspenders.
+ *   `(allow file-read* (literal "/"))` — read the ROOT dir itself. **Empirically
+ *                                  load-bearing:** without it the dyld bootstrap
+ *                                  cannot resolve absolute paths and the process
+ *                                  SIGABRTs (a `subpath "/usr"` rule does NOT
+ *                                  cover the `/` directory entry). This is the
+ *                                  fix for the Stage-1 HIGH-3 "profile cannot
+ *                                  launch a binary" finding.
+ *   `(allow file-read* (subpath ...))` — reads scoped to the system dirs a
+ *                                  process needs + the worktree. NOT a broad
+ *                                  read of `/` (host dotfiles/keychain stay
+ *                                  unreadable).
+ *   `(allow file-write* (subpath <wd>))` — writes scoped to the worktree ONLY.
+ *                                  NOTE: `<wd>` MUST be the CANONICAL (realpath)
+ *                                  path — on macOS `/tmp`→`/private/tmp`, and a
+ *                                  non-canonical write rule silently fails to
+ *                                  match. The caller canonicalizes before launch.
+ *   `(deny network*)`              — deny all network…
+ *   `(allow network-outbound (remote ip "localhost:*"))` — …except loopback.
+ *
+ * Loopback-only is the documented WEAK tier: it cannot pin the single broker
+ * port, so any other localhost listener stays reachable. The reduced-trust
+ * badge (`egressFidelity: 'coarse'`) signals this.
+ *
+ * @param workdir   the worktree path (SHOULD be canonical — see file header).
+ * @param execPath  the Node interpreter to grant read on (default
+ *                  `process.execPath`); injectable for deterministic tests.
+ */
+export declare function buildSeatbeltProfile(workdir: string, execPath?: string, 
+/**
+ * CP-7 PART D — extra READ-ONLY dirs to grant (the apiKeyHelper bootstrap dir
+ * holding the helper script + broker-token file + agent config). Read-only:
+ * the agent reads the current token; no write grant (the host owns rotation).
+ * These are explicit, scoped subpaths — NOT $HOME / /Users (the MED-fix
+ * invariant that host secrets stay unreadable still holds).
+ */
+extraReadDirs?: readonly string[], 
+/**
+ * Stage-2 HIGH (Codex — the `.git` credential leak). The host path of the
+ * SCRUBBED `.git` proxy (built by `git-proxy.ts`, same as A1's mount). When
+ * provided, the profile (a) GRANTS read on it (read-only — the agent runs
+ * `git` against it via `GIT_DIR`) and (b) DENIES read+write of the REAL
+ * `<workdir>/.git`, so the agent CANNOT read the host repo's credential
+ * helpers / tokenized remotes / hooks / reflogs directly. Without this the A5
+ * agent runs on the host fs and the `(allow file-read* (subpath "<wd>"))`
+ * grant would expose the real `.git`. Null/absent for a non-git workdir (the
+ * `.git` deny is still emitted — denying a non-existent path is harmless and
+ * keeps the profile shape uniform).
+ */
+gitProxyDir?: string | null, 
+/**
+ * r5 HIGH-1 (Codex) — the home dir to anchor the file-keychain (`~/.codevibe`)
+ * DENY at. Default `os.homedir()`; injectable for deterministic tests. The
+ * deny is the second, independent lock on the file-keychain dir (default-deny
+ * already blocks $HOME — see {@link FILE_KEYCHAIN_DIR_NAME}).
+ */
+homedir?: string, 
+/**
+ * CP-7 W3 — Stage-2 r1 HIGH (A5 "outside workdir → default-denied" is not
+ * universal). The RESOLVED per-task audit DIR (the sibling `.codevibe/audit/
+ * <group>/<track>/` tree). A5 grants broad READ subpaths for tooling (`/usr`,
+ * `/Library`, `/opt/homebrew`, `/usr/local`, `/opt/local`); if the repo/workdir
+ * (and therefore the sibling audit dir) lives UNDER one of those prefixes, the
+ * audit dir would be READABLE by the sandboxed agent even though it sits
+ * outside `workdir`. We emit an explicit TRAILING `(deny file-read* file-write*
+ * (subpath "<auditDir>"))` AFTER all the broad allows (Seatbelt last-match-
+ * wins, exactly like the `<wd>/.git` + `~/.codevibe` denies) so the agent can
+ * never read or tamper with the forensic record regardless of prefix overlap.
+ * Null/absent → no audit deny is emitted (e.g. a unit test without a real audit
+ * tree); production always threads the resolved audit dir.
+ */
+auditDir?: string | null): string;
+/**
+ * A5 macOS `sandbox-exec` substrate (`egressFidelity: 'coarse'`). See file
+ * header. NOT the default — the LE selects it as the macOS Docker-fallback.
+ */
+export declare class SandboxExecSubstrate implements Substrate {
+    private readonly runner;
+    private readonly profileRoot;
+    private readonly platform;
+    constructor(deps?: SandboxExecDeps);
+    launch(spec: SubstrateSpec): Promise<SubstrateHandle>;
+}

package/dist/substrate/types.d.ts

@@ -0,0 +1,218 @@
+import type { Readable, Writable } from "node:stream";
+/**
+ * Isolation backend for a substrate. `firecracker` is [DEF →
+ * A3-after-C2] — declared so the union admits the hosted runner without
+ * reopening the contract; not implemented in Rung 1.
+ */
+export type IsolationTech = "docker" | "sandbox_exec" | "firecracker";
+/**
+ * How tightly the substrate can pin egress to the single broker
+ * destination.
+ *
+ * - `strict`: single-destination allow-list (A1 netns / A3 VM net) —
+ *   all other egress is dropped at the substrate's egress proxy.
+ * - `coarse`: loopback-only; cannot pin the exact broker port (A5
+ *   Seatbelt) — the documented "weak for I3" tier. A `coarse` session
+ *   is surfaced via {@link SubstrateHandle.egressFidelity} so the LE
+ *   badges it reduced-trust.
+ */
+export type EgressFidelity = "strict" | "coarse";
+/**
+ * The full launch spec the LE passes to {@link Substrate.launch}.
+ * PHASE-CP-7-DESIGN §3.1.
+ */
+export interface SubstrateSpec {
+    isolationTech: IsolationTech;
+    /**
+     * Canonical host path of the session worktree — the ONLY filesystem
+     * mounted (§6 Q3 git-proxy).
+     */
+    workdir: string;
+    /**
+     * Where the broker actually listens on the HOST (e.g.
+     * `127.0.0.1:<ephemeral>`).
+     */
+    hostBrokerAddr: string;
+    /**
+     * What the agent points at FROM INSIDE the sandbox + the strict
+     * egress target. The container's `127.0.0.1` is NOT the host's, so the
+     * impl bridges sandbox→host. **A1 Option A (W2):** the agent dials a
+     * loopback `http://127.0.0.1:<port>` served by an in-container relay that
+     * forwards to a bind-mounted host UDS, which a host-side relay drains into
+     * the broker — under `--network none` the container has no host route, so a
+     * bind-mounted UDS is the only channel. (A5 uses host loopback directly.)
+     */
+    sandboxBrokerUrl: string;
+    /**
+     * Orchestration `task_id` = the audit scope (§3.5). The egress proxy
+     * keys `egress_denied` on it, so the SUBSTRATE needs it (not only the
+     * broker).
+     */
+    taskId: string;
+    /**
+     * The COMPLETE env the agent sees — built by the LE, wiped of every
+     * ambient cred (I1), WITH the §3.6 marker keys already folded in (the
+     * LE knows the implementor role at launch). `exec()` injects nothing
+     * further.
+     */
+    sanitizedEnv: Readonly<Record<string, string>>;
+    /**
+     * CP-7 PART D (§3.3 agy-R3 bootstrap) — OPTIONAL, additive. The host
+     * directory holding the agent's `apiKeyHelper` script + the broker-token
+     * file + the agent config (Claude `settings.json` / Codex `config.toml`),
+     * bind-mounted READ-ONLY into the sandbox at `sandboxDir` so the wiped,
+     * `--network none` agent can read the CURRENT broker token from a file
+     * WITHOUT a network/IPC fetch. The host LE REFRESHES the token file
+     * out-of-band on rotation; the read-only mount lets the host rewrite the
+     * underlying file while the agent can only READ it (it cannot forge/rotate
+     * a token). MUST live OUTSIDE the workdir mount so it never lands in the
+     * repo/diff. Absent → no bootstrap mount (e.g. a reviewer/probe, or a path
+     * that supplies the helper another way). A LOCAL-ONLY field — never on any
+     * wire; every existing `SubstrateSpec` construction still compiles.
+     */
+    agentBootstrap?: {
+        /** Host dir holding the helper script + token file + agent config (0700). */
+        hostDir: string;
+        /** Read-only mount point inside the sandbox (NOT under the workdir). */
+        sandboxDir: string;
+    };
+    /**
+     * CP-7 W3 — Stage-2 r1 HIGH (A5 audit-readability). OPTIONAL, additive. The
+     * RESOLVED per-task audit DIR (the sibling `.codevibe/audit/<group>/<track>/`
+     * tree the strict writer appends to). Threaded ONLY so the A5 Seatbelt profile
+     * can emit an explicit TRAILING `(deny file-read* file-write* (subpath
+     * "<auditDir>"))` — the agent must never read/forge the forensic record even if
+     * the repo/workdir lives under a broad-read tooling prefix (`/usr`, `/Library`,
+     * `/opt/homebrew`, …). A1 never mounts the audit tree, so it ignores this. A
+     * LOCAL-ONLY field — never on any wire; every existing `SubstrateSpec`
+     * construction still compiles (absent → no audit deny is emitted).
+     */
+    auditDir?: string;
+}
+/**
+ * A structural `ChildProcess` subset. The LE widens its internal child
+ * type to `ChildProcess | SubstrateProc` so `wireLifecycle`
+ * (spawn.ts:200-213, which calls `stream.destroy()/.destroyed` + kill +
+ * `on('close'|'error')`) consumes it unchanged.
+ *
+ * The `node:stream` `Writable`/`Readable` types are used (NOT
+ * `NodeJS.WritableStream`/`ReadableStream`) because the former expose
+ * `destroy()`/`destroyed`, which `wireLifecycle` depends on.
+ */
+export interface SubstrateProc {
+    readonly pid: number | undefined;
+    readonly stdin: Writable | null;
+    readonly stdout: Readable | null;
+    readonly stderr: Readable | null;
+    kill(signal?: NodeJS.Signals): boolean;
+    on(event: "close" | "error" | "exit", cb: (...a: unknown[]) => void): this;
+}
+/**
+ * A live substrate instance. PHASE-CP-7-DESIGN §3.1.
+ */
+export interface SubstrateHandle {
+    readonly id: string;
+    /**
+     * Surfaced so a `coarse` (A5) session carries a reduced-trust badge.
+     */
+    readonly egressFidelity: EgressFidelity;
+    exec(argv: string[], opts: {
+        stdinTty: boolean;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<SubstrateProc>;
+    /** Idempotent; MUST destroy the sandbox + its fs view. */
+    teardown(): Promise<void>;
+}
+/**
+ * The substrate factory the LE drives. A1/A5 implement this; A3 is a
+ * [DEF] later impl of the SAME interface.
+ */
+export interface Substrate {
+    launch(spec: SubstrateSpec): Promise<SubstrateHandle>;
+}
+/**
+ * One blocked-egress observation — the host-side forwarder (A1) or
+ * Seatbelt-violation observer (A5) invokes the {@link EgressObservationHook}
+ * with this on any connection/target it cannot honor. Fields mirror the
+ * §3.5 `egress_denied` payload so W3 forwards them directly.
+ */
+export interface EgressDenialDetail {
+    /** The non-broker destination the sandbox tried to reach. */
+    destination: string;
+    /** Transport protocol observed (e.g. `tcp`). */
+    protocol: string;
+    /** Why it was denied (e.g. `non-broker-destination`, `connect-failed`). */
+    denialReason: string;
+    /** Orchestration task_id — the §3.5 audit scope. */
+    taskId: string;
+    /**
+     * A proxy-assigned stable id per denial event (§3.5 dedup discriminator —
+     * the `ProgressEvent`/`ToolUse` model). The W2 forwarder mints it; W3 keys
+     * the `egress_denied` dedup on it.
+     */
+    callerEventId: string;
+}
+/**
+ * The W3-wired audit seam. The W2 substrate invokes this for each blocked
+ * outbound attempt. **W3 wires the emit** (`egress_denied` → the LE strict
+ * audit sink); the W2 default is {@link NOOP_EGRESS_HOOK}. Injected via the
+ * substrate constructor so the locked {@link SubstrateSpec}/{@link Substrate}
+ * interfaces stay unchanged (the hook is a dependency, not a wire field).
+ *
+ * Returns `void` (best-effort observation) — the §3.5 rationale: a kernel-
+ * dropped packet is already in the safe (denied) state, so the audit cannot
+ * gate the (already-blocked) effect. W3's emit is fire-and-forget here.
+ */
+export type EgressObservationHook = (detail: EgressDenialDetail) => void;
+/** The W2 default observation hook — a no-op. [W3 wires the emit] */
+export declare const NOOP_EGRESS_HOOK: EgressObservationHook;
+/** Result of a one-shot (await-to-completion) command run. */
+export interface CommandResult {
+    /** Exit code, or `null` if the process was signal-killed. */
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * A long-lived spawned process the runner hands back for `docker exec` /
+ * `sandbox-exec <argv>` — structurally a {@link SubstrateProc} (so the LE's
+ * `wireLifecycle` consumes it) plus nothing more.
+ */
+export type RunnerProc = SubstrateProc;
+/**
+ * The injected process layer for the A1/A5 impls (§3.1). `run` is the
+ * await-to-completion form (network create/rm, container run/kill — the impl
+ * inspects exit code/stderr); `spawnLong` is the streaming form for the agent
+ * process (`docker exec` / `sandbox-exec`) whose lifecycle the LE wires.
+ *
+ * **HIGH fix (Stage-2): `spawnLong` MUST accept an explicit `env`/`cwd`.** The
+ * A5 path spawns the agent via `spawnLong`; if it inherits `process.env`, every
+ * ambient credential (`ANTHROPIC_API_KEY`, …) leaks into the sandboxed agent —
+ * an I1 violation that defeats the whole moat. When `env` is supplied the
+ * spawned process sees EXACTLY that env (no `process.env` merge). When `env` is
+ * `undefined` the legacy inherit-`process.env` behavior is retained (used only
+ * for non-agent spawns that have no isolation requirement).
+ */
+export interface CommandRunner {
+    /** Run a command to completion, capturing stdout/stderr + exit code. */
+    run(argv: string[], opts?: {
+        timeoutMs?: number;
+        input?: string;
+    }): Promise<CommandResult>;
+    /**
+     * Spawn a streaming, long-lived process (the agent under the sandbox).
+     *
+     * `env`, when present, is the COMPLETE environment the child sees — there is
+     * NO `process.env` merge (I1: a host ambient credential MUST NOT reach the
+     * sandboxed agent). `cwd`, when present, sets the child's working directory.
+     */
+    spawnLong(argv: string[], opts: {
+        stdinTty: boolean;
+        signal?: AbortSignal;
+        /** EXACT child env (no `process.env` merge). Absent → inherit (legacy). */
+        env?: Readonly<Record<string, string>>;
+        /** Child working directory. Absent → inherit the parent's cwd. */
+        cwd?: string;
+    }): RunnerProc;
+}

package/dist/substrate-launch/__tests__/apikey-bootstrap.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/substrate-launch/__tests__/creditless-loop.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/substrate-launch/__tests__/engage-substrate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/substrate-launch/__tests__/fallback-ladder.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/substrate-launch/__tests__/le-env-scrub.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/substrate-launch/__tests__/sanitized-env.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/substrate-launch/apikey-bootstrap.d.ts

@@ -0,0 +1,84 @@
+import type { VendorProvider } from "../credential-broker/types";
+/** The fixed filenames inside the bootstrap dir (host + sandbox agree). */
+export declare const HELPER_SCRIPT_NAME = "broker-apikey-helper.sh";
+export declare const TOKEN_FILE_NAME = "broker-token";
+/** Claude reads `settings.json`'s `apiKeyHelper`; Codex reads `config.toml`. */
+export declare const CLAUDE_SETTINGS_NAME = "settings.json";
+export declare const CODEX_CONFIG_NAME = "config.toml";
+/** Where, inside the sandbox, the bootstrap dir is mounted (NOT the workdir). */
+export declare const SANDBOX_BOOTSTRAP_DIR = "/codevibe/agent";
+/** The Codex model-provider id the broker config registers. */
+export declare const CODEX_PROVIDER_ID = "codevibe_broker";
+/** Inputs for materializing the bootstrap. */
+export interface ApiKeyBootstrapInput {
+    provider: VendorProvider;
+    /** The URL the agent dials the broker at FROM INSIDE the sandbox. */
+    sandboxBrokerUrl: string;
+    /**
+     * The CURRENT broker token to seed the token file with (the broker minted it
+     * at start). Rotation later goes through {@link ApiKeyBootstrap.refresh}.
+     */
+    initialToken: string;
+    /**
+     * The mount point of the bootstrap dir INSIDE the sandbox. For A1 Docker this
+     * is the `:ro` mount (e.g. {@link SANDBOX_BOOTSTRAP_DIR}). For A5 the sandbox
+     * fs IS the host fs, so the in-sandbox path equals the (mkdtemp'd) host dir —
+     * pass `{ sandboxDirEqualsHostDir: true }` instead of a literal `sandboxDir`.
+     * Used to bake ABSOLUTE in-sandbox paths into the helper/config.
+     */
+    sandboxDir?: string;
+    /**
+     * A5 mode — the bootstrap is NOT mounted; the sandbox reads it directly from
+     * the host fs, so the in-sandbox path == the created host dir. When true,
+     * `sandboxDir` is ignored and the baked paths use the host dir.
+     */
+    sandboxDirEqualsHostDir?: boolean;
+    /** Override the host root for the bootstrap dir (default os.tmpdir()). */
+    hostRoot?: string;
+    /**
+     * The host path of the agent's rw WORKDIR mount (the worktree). The token
+     * file + helper MUST live OUTSIDE this dir — otherwise the broker token (and
+     * the helper) become visible/writable through the agent's workdir mount,
+     * defeating the read-only bootstrap mount (Stage-2 M-2). `create` `realpath`s
+     * BOTH the resolved bootstrap dir and this path and FAILS CLOSED if the
+     * bootstrap dir is inside or equal to the workdir. Required for the substrate
+     * path (the LE always knows the workdir); tests that don't pass it skip the
+     * check (no workdir to collide with).
+     */
+    workdir?: string;
+}
+/**
+ * A materialized apiKeyHelper bootstrap. Holds the host paths so the LE can
+ * REFRESH the token file on rotation and TEAR DOWN (remove) the dir at session
+ * end. The `spec` it exposes is exactly what {@link
+ * import('../substrate/types').SubstrateSpec.agentBootstrap} wants.
+ */
+export declare class ApiKeyBootstrap {
+    /** Host dir holding the helper + token file + agent config (0700). */
+    readonly hostDir: string;
+    /** In-sandbox mount point of {@link hostDir}. */
+    readonly sandboxDir: string;
+    /** Host path of the token file (the LE rewrites this on rotation). */
+    private readonly tokenFileHostPath;
+    private constructor();
+    /**
+     * Materialize the bootstrap: create the host dir (0700), write the token file
+     * (0600), the helper script (0700, executable), and the agent config. Returns
+     * the live {@link ApiKeyBootstrap}.
+     */
+    static create(input: ApiKeyBootstrapInput): Promise<ApiKeyBootstrap>;
+    /** The `SubstrateSpec.agentBootstrap` value for this bootstrap. */
+    get spec(): {
+        hostDir: string;
+        sandboxDir: string;
+    };
+    /**
+     * REFRESH the broker token (rotation / on a broker 401). Atomically rewrites
+     * the token file (write a temp + rename) so the agent never reads a partial
+     * token. The agent's helper re-runs on its next call / on a 401 and picks up
+     * the new value. The agent's mount is read-only, so ONLY the host can do this.
+     */
+    refresh(token: string): Promise<void>;
+    /** Remove the bootstrap dir (session teardown). Idempotent. */
+    destroy(): Promise<void>;
+}

package/dist/substrate-launch/engage-substrate.d.ts

@@ -0,0 +1,102 @@
+import { type RotationHandle } from "../credential-broker";
+import type { BrokerDeps } from "../credential-broker/broker";
+import type { ModelGatewayBroker, UpstreamClient, VendorProvider } from "../credential-broker/types";
+import type { ProcessRole } from "../local-executor/types";
+import type { SubstrateHandle } from "../substrate/types";
+import { type FallbackLadderDeps } from "./fallback-ladder";
+/** Map the implementor agent to the broker provider (Claude+Codex only, §6 Q4). */
+export declare function providerForAgent(agentKind: "CLAUDE" | "GEMINI" | "CODEX" | "ANTIGRAVITY"): VendorProvider | null;
+/** Inputs the LE passes to engage the moat for one implementor session. */
+export interface EngageSubstrateInput {
+    /** Orchestration task_id — the audit scope (§3.5). */
+    taskId: string;
+    /**
+     * The agent to engage for. CLAUDE/CODEX are Trusted (substrate + broker);
+     * GEMINI/ANTIGRAVITY are reduced-trust (§6 Q4) — for those,
+     * `engageSubstrate` RETURNS a `reduced_trust` EngageResult (AGY-2.0 D7)
+     * so raw-wired callers (`cli.ts` engagers → `engageSubstrateForSpawn` /
+     * `engageReviewerSubstrate`) route them onto the legacy+badge path instead
+     * of crashing the spawn loop.
+     */
+    agentKind: "CLAUDE" | "GEMINI" | "CODEX" | "ANTIGRAVITY";
+    /** Canonical host path of the session worktree (the only fs mounted). */
+    workdir: string;
+    /** The implementor role marker value (always 'implementor' here). */
+    role: ProcessRole;
+    /** Ladder deps (injectable for tests). */
+    ladderDeps?: FallbackLadderDeps;
+    /** Broker upstream client override (tests inject a stub; default real fetch). */
+    upstreamClient?: UpstreamClient;
+    /** Broker vendor-key store / audit sink overrides (forwarded to the broker). */
+    brokerDeps?: Pick<BrokerDeps, "vendorKeyStore" | "auditSink">;
+    /**
+     * CP-7 W3 — explicit per-task `audit.jsonl` path override (tests). Production
+     * leaves this unset: `engageSubstrate` DERIVES it from `workdir` (the
+     * stateDir) as the sibling `<repoRootCanonical>/.codevibe/audit/<group>/
+     * <track>/audit.jsonl` (§W3.2). Either way the fail-closed containment guard
+     * asserts the resolved path is OUTSIDE the workdir before launch.
+     */
+    auditPath?: string;
+    /** Broker factory override (tests inject a stub broker). */
+    makeBroker?: (deps: BrokerDeps) => ModelGatewayBroker & {
+        currentBrokerToken(): {
+            value: string;
+            expiresAtMs: number;
+        } | null;
+        rotateBrokerToken?(): RotationHandle | null;
+        /** M-3 — confirm the helper file holds the rotated token (drop grace). */
+        commitBrokerTokenRotation?(handle?: RotationHandle): void;
+        /** M-3 — file rewrite failed; restore the prior token (fail closed). */
+        rollbackBrokerTokenRotation?(handle?: RotationHandle): void;
+    };
+    /**
+     * Broker-token refresh interval (ms). The LE re-mints + rewrites the
+     * apiKeyHelper token file every interval (well within the 30-min TTL) so a
+     * long session never hits an expired-token 401 loop. Default 10 min; set
+     * `0` to disable the timer (tests). NEVER persisted/logged.
+     */
+    tokenRefreshIntervalMs?: number;
+    /** Bootstrap host-root override (tests). */
+    bootstrapHostRoot?: string;
+    /** Safe locale source for the sanitized env (default: none). */
+    localeSource?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * The substrate-engaged result: the spawn seam runs the agent via
+ * `substrateHandle`, with `finalEnv` already folded with the §3.6 markers (it
+ * is informational here — the handle already carries it as `sanitizedEnv`).
+ * `refreshBrokerToken` is wired to the bootstrap so the LE can rotate.
+ */
+export interface SubstrateEngaged {
+    mode: "substrate";
+    tier: "docker" | "sandbox_exec";
+    /** Reduced-trust badge for the A5 coarse tier (false for A1 strict). */
+    reducedTrust: boolean;
+    reducedTrustReason?: string;
+    substrateHandle: SubstrateHandle;
+    /** The complete env the agent runs under (markers folded) — for assertions. */
+    finalEnv: Readonly<Record<string, string>>;
+    /** Rotate the broker token in the bootstrap token file (on a broker 401). */
+    refreshBrokerToken(): Promise<void>;
+    /** Stop the broker (zeroize), destroy the bootstrap, tear down the substrate. */
+    teardown(): Promise<void>;
+}
+/** The reduced-trust (moat-OFF) result the LE surfaces with a prominent badge. */
+export interface ReducedTrustEngaged {
+    mode: "reduced_trust";
+    reducedTrust: true;
+    reducedTrustReason: string;
+    /** No broker, no substrate — the LE uses the legacy nodeSpawn path. */
+    teardown(): Promise<void>;
+}
+export type EngageResult = SubstrateEngaged | ReducedTrustEngaged;
+/**
+ * Engage the trusted-execution moat for one implementor session (PARTs B–F).
+ *
+ * Fail-closed contract: on the SUBSTRATE branch, if the broker can't start OR
+ * the bootstrap can't be written OR the substrate can't launch, we ROLL BACK
+ * (stop broker, destroy bootstrap) and THROW — we do NOT silently downgrade to
+ * an unsandboxed run. The ONLY non-substrate path is the ladder explicitly
+ * choosing reduced-trust (no runtime available), which returns the badge.
+ */
+export declare function engageSubstrate(input: EngageSubstrateInput): Promise<EngageResult>;

package/dist/substrate-launch/fallback-ladder.d.ts

@@ -0,0 +1,49 @@
+import type { DockerSubstrateDeps } from "../substrate/docker";
+import type { SandboxExecDeps } from "../substrate/sandbox-exec";
+import type { CommandRunner, Substrate } from "../substrate/types";
+/** Which rung of the §6 Q2 ladder was selected. */
+export type SubstrateTier = "docker" | "sandbox_exec" | "reduced_trust";
+/**
+ * The ladder's result. A `substrate` is present for the two real tiers; the
+ * `reduced_trust` tier has `substrate: null` (the LE takes the legacy path +
+ * the prominent badge).
+ */
+export type SubstrateSelection = {
+    tier: "docker";
+    substrate: Substrate;
+    /** Strict egress (single-destination allow-list) — full moat. */
+    reducedTrust: false;
+} | {
+    tier: "sandbox_exec";
+    substrate: Substrate;
+    /** Coarse egress (loopback-only) — reduced-trust BADGE per §3.1. */
+    reducedTrust: true;
+    reducedTrustReason: string;
+} | {
+    tier: "reduced_trust";
+    substrate: null;
+    /** No substrate — the moat is OFF this session (legacy path). */
+    reducedTrust: true;
+    reducedTrustReason: string;
+};
+/** Injectable deps for the ladder (so it is testable without a real daemon). */
+export interface FallbackLadderDeps {
+    /** Process layer for the `docker version` probe (default real). */
+    runner?: CommandRunner;
+    /** Platform override (default `process.platform`). */
+    platform?: NodeJS.Platform;
+    /** Deps forwarded to the chosen DockerSubstrate. */
+    dockerDeps?: DockerSubstrateDeps;
+    /** Deps forwarded to the chosen SandboxExecSubstrate. */
+    sandboxExecDeps?: SandboxExecDeps;
+    /** Substrate factory overrides (tests inject stubs). */
+    makeDocker?: (deps?: DockerSubstrateDeps) => Substrate;
+    makeSandboxExec?: (deps?: SandboxExecDeps) => Substrate;
+}
+/**
+ * Resolve the §6 Q2 ladder. Returns the chosen substrate + tier, or the
+ * reduced-trust sentinel. NEVER throws for "no substrate available" — that is a
+ * VALID (reduced-trust) outcome the LE surfaces with a badge; it throws only on
+ * a programming error.
+ */
+export declare function selectSubstrate(deps?: FallbackLadderDeps): Promise<SubstrateSelection>;

package/dist/substrate-launch/index.d.ts

@@ -0,0 +1,12 @@
+export { engageSubstrate, providerForAgent, } from "./engage-substrate";
+export type { EngageSubstrateInput, EngageResult, SubstrateEngaged, ReducedTrustEngaged, } from "./engage-substrate";
+export { selectSubstrate } from "./fallback-ladder";
+export type { SubstrateSelection, SubstrateTier, FallbackLadderDeps, } from "./fallback-ladder";
+export { buildSanitizedBaseEnv, assertNoAmbientCreds, SAFE_ENV_ALLOWLIST, SANDBOX_DEFAULT_PATH, } from "./sanitized-env";
+export type { SanitizedEnvInput } from "./sanitized-env";
+export { ApiKeyBootstrap, SANDBOX_BOOTSTRAP_DIR, HELPER_SCRIPT_NAME, TOKEN_FILE_NAME, CODEX_PROVIDER_ID, } from "./apikey-bootstrap";
+export type { ApiKeyBootstrapInput } from "./apikey-bootstrap";
+export { scrubLeEnvOrReexec, buildScrubbedLeEnv, findCredShapedKeys, isCredShapedEnvKey, LE_ENV_SCRUBBED_MARKER, } from "./le-env-scrub";
+export type { LeEnvScrubDeps } from "./le-env-scrub";
+export { Cp7AuditWriter, CP7_CANONICAL_FORM_VERSION, GENESIS_PREV_HASH, canonicalJson, canonicalEntryBytes, computeEntryHash, verifyChain, } from "../local-executor/cp7-audit-writer";
+export type { Cp7AuditEntry } from "../local-executor/cp7-audit-writer";