@quantiya/codevibe-core 2.0.1 → 2.0.2

package/dist/reviewer/providers/gemini.d.ts

@@ -1,6 +1,7 @@
-import { type ReviewerProvider, type ReviewerSpec } from '../provider.js';
+import { type ReviewerEvaluateOptions, type ReviewerProvider, type ReviewerSpec } from '../provider.js';
 import { type SubprocessOutcome } from '../subprocess.js';
 import type { ReviewerVerdict } from '../types.js';
+import { type VerdictClassifier } from '../verdict-classifier.js';
 import type { BuiltCommand } from './claude.js';
 /** Construction options. */
 export interface GeminiReviewerProviderOptions {
@@ -42,7 +43,7 @@ export interface GeminiModelStats {
 export declare class GeminiReviewerProvider implements ReviewerProvider {
     private readonly executable;
     constructor(opts?: GeminiReviewerProviderOptions);
-    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+    evaluate(spec: ReviewerSpec, gateId: string, opts?: ReviewerEvaluateOptions): Promise<ReviewerVerdict>;
 }
 /**
  * Construct the Gemini CLI invocation. Split out from `evaluate` so unit
@@ -71,13 +72,13 @@ export declare class GeminiReviewerProvider implements ReviewerProvider {
  * session INACTIVE (empirically observed 2026-04-21 during Phase 2c.2
  * local testing).
  */
-export declare function buildCommand(executable: string, spec: ReviewerSpec): BuiltCommand;
+export declare function buildCommand(executable: string, spec: ReviewerSpec, sandboxed?: boolean): BuiltCommand;
 /**
  * Map the raw subprocess outcome into a `ReviewerVerdict` or throw a
  * structured `ReviewerErrorClass`. See `claude.ts::buildVerdict` for the
  * shared safety rule (non-zero exit overrides any parseable stdout).
  */
-export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome): ReviewerVerdict;
+export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, classifyVerdict?: VerdictClassifier): Promise<ReviewerVerdict>;
 /**
  * Parse the FIRST complete JSON object in `stdout`, discarding any trailing
  * bytes. User-level hooks (e.g., CodeVibe's own Gemini plugin hooks

package/dist/reviewer/registry.d.ts

@@ -1,4 +1,4 @@
-import { type ReviewerProvider, type ReviewerSpec } from './provider.js';
+import { type ReviewerEvaluateOptions, type ReviewerProvider, type ReviewerSpec } from './provider.js';
 import type { AgentKind, ReviewerVerdict } from './types.js';
 /**
  * Per-agent reviewer dispatch.
@@ -62,12 +62,12 @@ export declare class ReviewerRegistry implements ReviewerProvider {
      * existing escalation path handles it. The `reason` field includes
      * the agent name so audit can identify the misconfiguration.
      */
-    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+    evaluate(spec: ReviewerSpec, gateId: string, opts?: ReviewerEvaluateOptions): Promise<ReviewerVerdict>;
 }
 /**
- * Production factory: build a registry pre-populated with all three
- * subprocess providers (Claude, Gemini, Codex) using the standard
- * binaries from PATH. Equivalent of Rust's
+ * Production factory: build a registry pre-populated with all four
+ * subprocess providers (Claude, Gemini, Codex, Antigravity) using the
+ * standard binaries from PATH. Equivalent of Rust's
  * `withSubprocessProviders()` napi factory.
  *
  * Plugins call this once at startup and hand the registry to the

package/dist/reviewer/subprocess.d.ts

@@ -1,3 +1,4 @@
+import type { SubstrateHandle } from '../substrate/types.js';
 /**
  * Successful subprocess run. Exit status may still be failure (non-zero
  * code); the caller decides whether to treat that as a reviewer spawn error
@@ -72,8 +73,44 @@ export interface RunReviewerOptions {
      * primary plugin session. Each provider is responsible for setting it;
      * this module does NOT inject it automatically because providers may
      * also need to forward `process.env` selectively.
+     *
+     * # CP-7 §8 (Stage-1-resolved) — IGNORED on the substrate path
+     *
+     * `env` applies ONLY to the LEGACY (no-`substrate`) path, where it is
+     * passed verbatim to `child_process.spawn`. When `substrate` is supplied
+     * the child is obtained via `SubstrateHandle.exec(argv, …)`, whose env is
+     * PRE-BAKED at `substrate.launch()` time (the I1 allow-list `sanitizedEnv`
+     * with the broker base-URL redirect, NO vendor key) — `exec()` takes no
+     * env parameter by contract (`substrate/types.ts:138`). So this field is
+     * deliberately UNUSED on the substrate path: that is the moat invariant —
+     * a sandboxed reviewer MUST NOT inherit ANY ambient credential, and the
+     * provider's `{...process.env}` spread (the historic moat hole) never
+     * reaches the child because we do not honor `env` here. See the per-agent
+     * providers' `buildCommand` which drops the `process.env` spread for the
+     * substrate path. The `QUORUM_REVIEWER_SUBPROCESS` marker is folded into
+     * the substrate's sanitizedEnv at launch (the same way the implementor's
+     * §3.6 markers are), not via this field.
      */
     env: NodeJS.ProcessEnv;
+    /**
+     * CP-7 §8 (Stage-1-resolved) — OPTIONAL substrate handle. When supplied,
+     * the reviewer runs INSIDE the CP-7 trusted-execution sandbox + broker
+     * (exactly like a substrate-confined implementor): the child is obtained
+     * via `substrate.exec(argv, { stdinTty: true, … })` instead of
+     * `child_process.spawn`, so it sees ONLY the pre-baked I1 allow-list env
+     * (broker base-URL + bootstrap config dir; NO ambient vendor creds), and
+     * its model API call routes through the loopback broker (which injects the
+     * vendor key host-side). ABSENT → the LEGACY path (`child_process.spawn`
+     * with `env`) runs byte-identical to pre-CP-7-reviewer-sandbox behavior.
+     *
+     * The §3.1 lifecycle (prompt-write-to-stdin, stdout/stderr capture, the
+     * timeout race, abort/signal handling, teardown/kill, the SubprocessOutcome
+     * shape) is PRESERVED EXACTLY on both paths — `SubstrateProc` exposes the
+     * same `stdin`/`stdout`/`stderr`/`kill`/`on('close'|'error')` surface, so
+     * the lifecycle code below is shared; only the child-acquisition step
+     * differs.
+     */
+    substrate?: SubstrateHandle;
     /** Working directory; falls back to `process.cwd()`. */
     cwd?: string;
     /**

package/dist/reviewer/token-usage.d.ts

@@ -0,0 +1,32 @@
+/**
+ * [P2-0] Clamp an UNTYPED token field (from agent CLI JSON) to a finite,
+ * non-negative INTEGER. Token fields come from untyped agent JSON — a string /
+ * object / `NaN` / negative / fractional value would poison the per-task
+ * accumulator (→ `NaN` render, or a reopened window showing a LOWER total),
+ * violating the "token count is a number" invariant. Every numeric ingress
+ * (`unwrapClaudeJson` usage reads, Codex `sumCodexTokens` per-event sum, the
+ * QuorumLoop `addTaskTokens`) gates on this, so a malformed field contributes 0,
+ * never corrupts the accumulator.
+ */
+export declare function finiteToken(n: unknown): number;
+/**
+ * [P2-6] Unwrap a Claude Code `--output-format json` NON-interactive envelope into
+ * `{ text, tokens }`. The ENTIRE body is `try/catch`-guarded — ANY throw (parse
+ * error, unexpected shape, field-access `TypeError`) degrades to the backward-compat
+ * raw-stdout fallback `{ text: stdout, tokens: undefined }`, so adding this unwrap
+ * can NEVER break a caller (it reduces to today's raw-stdout behavior).
+ *
+ *   • No `type:'result'` object located / non-JSON → raw fallback (byte-identical
+ *     to today — the downstream parser sees the raw stdout).
+ *   • `is_error === true` OR `result` not a non-empty string → `{ text:'', tokens:
+ *     undefined }`. The CALLER treats an empty/failed result as an agent FAILURE
+ *     (reviewer ESCALATE / resolver human-gate — same as today), NOT a silent pass.
+ *   • else → `{ text: result, tokens: (finiteToken(usage.input_tokens) +
+ *     finiteToken(usage.output_tokens)) || undefined }`. `finiteToken` clamps
+ *     absent/malformed usage to 0 (no `TypeError`, no `NaN`); cache tokens are
+ *     excluded in v1 (input+output only — see design "Known v1 limitation").
+ */
+export declare function unwrapClaudeJson(stdout: string): {
+    text: string;
+    tokens?: number;
+};

package/dist/reviewer/types.d.ts

@@ -1,13 +1,13 @@
 /**
- * Three agent kinds the reviewer subprocess layer can spawn.
+ * Agent kinds the reviewer subprocess layer can spawn.
  *
  * Lowercase wire format matches `codevibe_policy::AgentKind`'s
  * `#[serde(rename_all = "lowercase")]` attribute. **Append-only after launch**
- * — adding a fourth agent (e.g. a hypothetical fourth CLI) is fine; renaming
- * `claude` → `Claude` would break every audit chain entry that has serialised
- * it.
+ * — `antigravity` appended per AGY-2.0-SUPPORT-DESIGN.md (Phase A, 2026-07-03);
+ * renaming `claude` → `Claude` would break every audit chain entry that has
+ * serialised it.
  */
-export type AgentKind = 'claude' | 'gemini' | 'codex';
+export type AgentKind = 'claude' | 'gemini' | 'codex' | 'antigravity';
 /**
  * Review lens a reviewer seat evaluates through.
  *

package/dist/reviewer/verdict-classifier.d.ts

@@ -0,0 +1,62 @@
+import type { LocalGemmaPlannerRunner } from '../planner/local-gemma';
+import type { AgentKind, ReviewerRole, VerdictKind } from './types';
+/** Per-verdict context (seat/role/agent) — carried for observability; the Gemma
+ *  classification itself is context-free (deterministic on `rawText`). */
+export interface VerdictClassifierContext {
+    seatId: number;
+    role: ReviewerRole;
+    agent: AgentKind;
+}
+/**
+ * A classifier's resolved decision. `reason` is set ONLY on a fail-closed ESCALATE
+ * (a SAFE closed label — never raw model/reviewer text); a genuine reviewer verdict
+ * (incl. a genuine ESCALATE the reviewer actually chose) leaves `reason` undefined
+ * so the provider keeps the reviewer's own reasoning (D5/MED-C).
+ */
+export interface VerdictClassification {
+    verdict: VerdictKind;
+    reason?: string;
+}
+export type VerdictClassifier = (rawText: string, ctx: VerdictClassifierContext) => Promise<VerdictClassification>;
+/** SAFE closed labels for a fail-closed ESCALATE (D3/D5/MED-C). Never raw text. */
+export declare const VERDICT_CLASSIFIER_UNCERTAIN = "verdict_classifier_uncertain";
+export declare const VERDICT_CLASSIFIER_CONFLICT = "verdict_classifier_conflict";
+export declare const VERDICT_CLASSIFIER_UNAVAILABLE = "verdict_classifier_unavailable";
+/**
+ * Build a fail-closed Gemma verdict classifier. Order:
+ *   (1) empty `rawText.trim()===''` → ESCALATE (no `classify` call);
+ *   (2) [D2a] conflicting standalone verdicts → ESCALATE (before Gemma);
+ *   (3) classify (8s race) → validate JSON/enum/`confidence:'high'` per D3;
+ *   (4) REVISE → require `extractSuggestedChanges(postVerdictReasoning(rawText))`
+ *       yields ≥1 change (D5), else ESCALATE.
+ * Whole body try/catch-wrapped; any throw / timeout → ESCALATE (unavailable).
+ * A genuine non-ESCALATE verdict (and a genuine reviewer ESCALATE) returns NO
+ * `reason` so the provider keeps the reviewer's own reasoning.
+ */
+export declare function makeGemmaVerdictClassifier(runner: LocalGemmaPlannerRunner, opts?: {
+    timeoutMs?: number;
+}): VerdictClassifier;
+/**
+ * A trivial classifier that returns ESCALATE (with a closed `reason` label) for
+ * every input, with no runner. Installed by the wiring when flag=`gemma` but the
+ * Gemma runner is null at boot (Ollama unreachable) — so `gemma` mode NEVER
+ * silently degrades to the regex parser (agy-MED-1).
+ */
+export declare function alwaysEscalateClassifier(reason: string): VerdictClassifier;
+/**
+ * [D5] Resolve the `ReviewerVerdict`'s `reasoning` + `suggested_changes` from a
+ * classification, shared by all three providers' `buildVerdict` so the safety-
+ * critical mapping lives in ONE audited place:
+ *  - `reasoning`: a fail-closed ESCALATE (has a closed `reason` label) → that
+ *    label (never raw text, parity with the old `parse_failure`→template); every
+ *    other verdict (incl. a genuine reviewer ESCALATE, `reason` undefined) → the
+ *    reviewer's raw text verbatim.
+ *  - `suggested_changes`: REVISE → `extractSuggestedChanges(postVerdictReasoning(
+ *    rawText))` (non-empty by construction — the classifier already gated it);
+ *    every other verdict → `[]`.
+ */
+export declare function resolveClassifiedVerdictFields(classification: VerdictClassification, rawText: string): {
+    verdict: VerdictKind;
+    reasoning: string;
+    suggested_changes: string[];
+};

package/dist/session/__tests__/prepare-event-timestamp.test.d.ts

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

package/dist/session/index.d.ts

@@ -3,3 +3,4 @@ export type { ResumeOrCreateSessionInput, ResumeOrCreateSessionResult } from './
 export { rekeySessionForNewDevices } from './session-rekey';
 export { startDeviceKeyWatcher } from './device-key-watcher';
 export { registerDeviceEncryptionKey } from './register-device-key';
+export { prepareEventTimestamp, _resetPrepareEventTimestampForTesting, } from './prepare-event-timestamp';

package/dist/session/prepare-event-timestamp.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Returns an ISO-8601 timestamp with millisecond precision that is
+ * STRICTLY GREATER than any previous timestamp returned for the same
+ * `orderingKey` within this process.
+ *
+ * Formula: `Math.max(baseMs, lastMs + 1, floorMs)` where `floorMs` is
+ * `notBeforeMs + 1` when a finite `notBeforeMs` is supplied (else 0), and:
+ *   - baseMs = parsed agentClock if provided (and valid), else Date.now()
+ *   - lastMs = previously-emitted ms for this orderingKey (or 0 if first)
+ *
+ * `agentClock` ANCHORS the timestamp when provided. This is the load-bearing
+ * behavior for agy's transcript replay: agy emits events with their original
+ * `created_at` even during a backfill (so subscription clients see them in
+ * logical order, not in replay-arrival order). For hook-driven plugins
+ * (claude/codex/gemini), `agentClock` is left undefined and baseMs = wallMs.
+ *
+ * Memory: bounded LRU with cap=MAX_LRU_KEYS. Eviction order is least-
+ * recently-touched, so active orderingKeys are never evicted. Resets on
+ * process restart (correct: restart is a new lifecycle).
+ */
+export declare function prepareEventTimestamp(opts: {
+    orderingKey: string;
+    agentClock?: string;
+    notBeforeMs?: number;
+}): string;
+/**
+ * Test-only: clear the per-key map. Used by jest/vitest to reset state
+ * between tests. Not exported from the package root.
+ */
+export declare function _resetPrepareEventTimestampForTesting(): void;

package/dist/substrate/__tests__/docker.test.d.ts

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

package/dist/substrate/__tests__/forwarder.test.d.ts

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

package/dist/substrate/__tests__/git-proxy.test.d.ts

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

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

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

package/dist/substrate/__tests__/substrate-e2e.integration.test.d.ts

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

package/dist/substrate/command-runner.d.ts

@@ -0,0 +1,19 @@
+import type { CommandResult, CommandRunner, RunnerProc } from './types';
+/**
+ * The production `CommandRunner` — runs `docker` / `sandbox-exec` via
+ * `node:child_process`. No shell is used (argv is passed directly to
+ * `spawn`), so there is no shell-injection surface from the constructed
+ * arguments.
+ */
+export declare class ChildProcessCommandRunner implements CommandRunner {
+    run(argv: string[], opts?: {
+        timeoutMs?: number;
+        input?: string;
+    }): Promise<CommandResult>;
+    spawnLong(argv: string[], opts: {
+        stdinTty: boolean;
+        signal?: AbortSignal;
+        env?: Readonly<Record<string, string>>;
+        cwd?: string;
+    }): RunnerProc;
+}

package/dist/substrate/docker.d.ts

@@ -0,0 +1,134 @@
+import { type ForwarderFactory } from './forwarder';
+import type { CommandRunner, EgressObservationHook, Substrate, SubstrateHandle, SubstrateSpec } from './types';
+/** Where, inside the container, the worktree is mounted (the agent's cwd/home). */
+export declare const CONTAINER_WORKDIR = "/workspace";
+/** Injectable deps — default-wired to the real runtime; stubbed in unit tests. */
+export interface DockerSubstrateDeps {
+    /** Process layer (default: `node:child_process`). Stub in unit tests. */
+    runner?: CommandRunner;
+    /** Host-side UDS relay factory (default: real `node:net`). */
+    forwarderFactory?: ForwarderFactory;
+    /** §3.5 observation seam. **W3 wires the emit**; default no-op. */
+    onEgressDenied?: EgressObservationHook;
+    /** Override the container image (default {@link DEFAULT_IMAGE}). */
+    image?: string;
+    /**
+     * Override the host root for the per-session scratch dir (default:
+     * os.tmpdir()). The per-session dir holds ONLY the broker socket (in `uds/`),
+     * the relay script, and the scrubbed git-proxy (in `gitproxy/`) — no secrets.
+     * The git-proxy now lives UNDER this dir (MED fix), so the one
+     * teardown/rollback rm removes it.
+     */
+    sessionRoot?: string;
+}
+/** The deterministic per-session container name. */
+export declare function containerName(id: string): string;
+/**
+ * The shell-wrapped container entrypoint: start the in-container relay in the
+ * background, then hold the container alive for `docker exec`. We MUST wrap in
+ * `sh -c` because the relay has to run CONCURRENTLY with the hold (the relay is
+ * the broker channel; `exec sleep infinity` keeps the container up for exec).
+ * `exec` replaces the shell with sleep so signals (docker kill) propagate.
+ *
+ * MED fix (Stage-2): the whole `sh -c` runs under `env -i <sanitizedEnv>` so
+ * PID1 (and thus everything inheriting from it, including `docker exec`) has
+ * EXACTLY `sanitizedEnv` — the image's baked env is wiped. The relay needs
+ * Node on PATH; `sanitizedEnv` carries PATH (the allow-list includes it).
+ *
+ * Exposed for the conformance test (pins the `env -i … sh -c 'node relay.js
+ * <port> <sock> & exec sleep infinity'` shape).
+ */
+export declare function buildContainerEntrypoint(sanitizedEnv: Readonly<Record<string, string>>): string[];
+/**
+ * `docker run --network none -d` argv. Builds the FULL Option-A isolation
+ * surface the conformance test pins:
+ *   - `--network none`         → STRUCTURAL default-deny (only `lo`, no egress).
+ *   - `-v <workdir>:/workspace` → ONLY the worktree mounted (rw).
+ *   - `-v <gitProxy>:/workspace/.git:ro` → scrubbed `.git`, read-only (if any).
+ *   - `-v <relayScript>:/codevibe/relay.js:ro` → the in-container relay (ro).
+ *   - `-v <udsDir>:/codevibe/broker:rw`  → the bind-mounted broker UDS dir (rw,
+ *     so the container's `connect()` works; the dir holds only the socket).
+ *   - env via repeated `-e K=V` built EXACTLY from `spec.sanitizedEnv` (no host
+ *     env passthrough; `docker run` does NOT inherit the host env). MED fix:
+ *     the `-e` flags ADD to the image's baked env, so the AUTHORITATIVE wipe is
+ *     the `env -i <sanitizedEnv>` prefix on the entrypoint (PID1) + every exec.
+ *   - entrypoint: `env -i <sanitizedEnv> sh -c 'node relay.js <port> <sock> &
+ *     exec sleep infinity'` — PID1's env is EXACTLY sanitizedEnv (MED fix).
+ * NO `--add-host`, NO `--network <name>`, NO `--internal`, and NO `-v` for host
+ * keychain/home/dotfiles is ever added.
+ */
+export declare function buildRunArgv(args: {
+    id: string;
+    image: string;
+    workdir: string;
+    gitProxyPath: string | null;
+    relayScriptPath: string;
+    udsDir: string;
+    sanitizedEnv: Readonly<Record<string, string>>;
+    /** CP-7 PART D — apiKeyHelper bootstrap mount (`hostDir`→`sandboxDir:ro`). */
+    agentBootstrap?: {
+        hostDir: string;
+        sandboxDir: string;
+    };
+}): string[];
+/**
+ * `docker exec [-i] <name> env -i <sanitizedEnv> <argv...>` — run the agent
+ * inside the live sandbox. MED fix (Stage-2): the `env -i <sanitizedEnv>`
+ * prefix clears whatever env `docker exec` would inherit from PID1 / the image
+ * and sets EXACTLY `sanitizedEnv`, so the agent env is the SAME set as the A5
+ * path (no image `PATH`/baked-env leak). `--env-file`/`-e` on `docker exec`
+ * only ADD; `env -i` in the command position is the authoritative wipe.
+ */
+export declare function buildExecArgv(id: string, argv: string[], stdinTty: boolean, sanitizedEnv: Readonly<Record<string, string>>): string[];
+/** `docker kill <name>` — teardown step 1. */
+export declare function buildKillArgv(id: string): string[];
+/** `docker rm -f <name>` — teardown step 2 (idempotent via -f). */
+export declare function buildRmArgv(id: string): string[];
+/**
+ * A1 Docker substrate (`egressFidelity: 'strict'`, Option A). See file header
+ * for the full egress + fs + env contract.
+ */
+export declare class DockerSubstrate implements Substrate {
+    private readonly runner;
+    private readonly forwarderFactory;
+    private readonly onEgressDenied;
+    private readonly image;
+    private readonly sessionRoot;
+    constructor(deps?: DockerSubstrateDeps);
+    launch(spec: SubstrateSpec): Promise<SubstrateHandle>;
+    private rollback;
+    /**
+     * r5 HIGH-2 (Codex — NULL-vs-THROW gap). The proxy build produced no usable
+     * proxy (it returned `null` OR threw). Decide the safe outcome by whether the
+     * workdir actually HAS a `.git`:
+     *
+     *   - NO `<workdir>/.git`            → return `null` (a non-git workdir; the
+     *                                      `docker run` mounts only the worktree,
+     *                                      git reports "not a repository" — no
+     *                                      credential surface either way).
+     *   - `<workdir>/.git` EXISTS        → write an EMPTY SCRUBBED `.git` overlay
+     *                                      (a dir with ONLY a stripped synthetic
+     *                                      `config` — NO remotes/creds/hooks) and
+     *                                      return its path, so the `:ro` bind mount
+     *                                      SHADOWS the real `.git`. Degraded git
+     *                                      reads, but the credential surface is
+     *                                      fail-closed.
+     *   - overlay write ALSO fails       → roll back + throw (NEVER mount the
+     *                                      worktree with a live `.git`).
+     *
+     * Used for BOTH the null-return and the throw path so a workdir with a real
+     * but unresolvable `.git` can never reach the agent un-shadowed. `fsp.stat`
+     * (NOT `lstat`) follows a `.git` that is a symlink/dir/file alike — any of
+     * those "exists" cases must be shadowed.
+     */
+    private ensureGitOverlayOrFailClosed;
+    private assertDockerAvailable;
+}
+export declare const __testing: {
+    DEFAULT_IMAGE: string;
+    CONTAINER_WORKDIR: string;
+    CONTAINER_GIT: string;
+    CONTAINER_RELAY_PATH: string;
+    CONTAINER_BROKER_DIR: string;
+    RELAY_PORT: number;
+};

package/dist/substrate/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Thrown by {@link import('./docker').DockerSubstrate.launch} when the Docker
+ * CLI/daemon is absent or unusable, and by
+ * {@link import('./sandbox-exec').SandboxExecSubstrate.launch} when
+ * `sandbox-exec` is unavailable (non-macOS / missing binary).
+ *
+ * The LE catches this to drive the §6 Q2 fallback ladder. The carried
+ * `isolationTech` + `reason` let the LE log/branch precisely; the substrate
+ * itself NEVER falls back silently — refusing to run is the safe state.
+ */
+export declare class SubstrateUnavailableError extends Error {
+    /** Which backend was unavailable (`docker` / `sandbox_exec`). */
+    readonly isolationTech: string;
+    /** Human-readable cause (CLI missing, daemon down, non-macOS, …). */
+    readonly reason: string;
+    constructor(
+    /** Which backend was unavailable (`docker` / `sandbox_exec`). */
+    isolationTech: string, 
+    /** Human-readable cause (CLI missing, daemon down, non-macOS, …). */
+    reason: string, cause?: unknown);
+}
+/**
+ * Thrown when a substrate lifecycle step (network create, container run,
+ * `docker exec`, profile write) fails for a reason OTHER than the backend
+ * being absent — i.e. the backend is present but a command errored. Distinct
+ * from {@link SubstrateUnavailableError} so the LE does NOT mistake a transient
+ * command failure for "no runtime, fall back to A5."
+ */
+export declare class SubstrateLaunchError extends Error {
+    readonly isolationTech: string;
+    readonly reason: string;
+    constructor(isolationTech: string, reason: string, cause?: unknown);
+}

package/dist/substrate/forwarder.d.ts

@@ -0,0 +1,67 @@
+import type { EgressObservationHook } from './types';
+/**
+ * Construction spec for the host-side UDS relay. The substrate owns one per
+ * session.
+ */
+export interface ForwarderSpec {
+    /** Orchestration task_id — stamped on every `egress_denied` observation. */
+    taskId: string;
+    /**
+     * The FIXED upstream the relay ALWAYS dials (`spec.hostBrokerAddr`).
+     * Agent-supplied targets are ignored — this is the only destination.
+     */
+    hostBrokerAddr: string;
+    /**
+     * The host UDS path the relay LISTENS on (the container bind-mounts this rw
+     * and its in-relay dials it). Required for Option A — there is no TCP bind.
+     */
+    udsPath: string;
+    /** §3.5 observation seam. **W3 wires the emit**; default no-op. */
+    onEgressDenied?: EgressObservationHook;
+}
+/**
+ * The host-side UDS relay (§3.1, `strict` tier, Option A). Listens on a
+ * per-session host Unix-domain socket; every inbound connection is relayed to
+ * the single fixed `hostBrokerAddr`. It never reads an agent-supplied
+ * destination. A broker-upstream connect failure fires
+ * {@link EgressObservationHook} (W3 → `egress_denied`).
+ */
+export declare class HostEgressForwarder {
+    private readonly server;
+    private readonly upstream;
+    private readonly onEgressDenied;
+    private readonly taskId;
+    private readonly udsPath;
+    private listening;
+    constructor(spec: ForwarderSpec);
+    /**
+     * Start listening on the host UDS. Removes any stale socket file at the path
+     * first (a crashed prior run can leave one — listen() would EADDRINUSE).
+     * Resolves with the UDS path the container dials.
+     */
+    start(): Promise<{
+        udsPath: string;
+    }>;
+    /** The host UDS path the container dials (valid after {@link start}). */
+    boundAddr(): string;
+    /**
+     * Idempotent teardown — closes the listener (relayed sockets drop with it)
+     * and unlinks the host UDS file so the per-session dir can be removed.
+     */
+    stop(): Promise<void>;
+    private onConnection;
+    private observeDenial;
+    /**
+     * Directly record a blocked outbound attempt. Under Option A there is no
+     * network-observable denied attempt for A1 (the container has no NIC — see
+     * the docker.ts §3.5 footnote), so this is STRUCTURALLY UNFIRED for A1. It
+     * stays exposed so a future iptables/A5 tier that CAN observe a sandbox→
+     * non-broker attempt routes it through the same seam + id minting.
+     */
+    recordBlockedDestination(destination: string, denialReason: string): void;
+    private safeDestroy;
+}
+/** Factory the substrate uses (injectable so unit tests can stub the relay). */
+export type ForwarderFactory = (spec: ForwarderSpec) => HostEgressForwarder;
+/** Default factory — the real `node:net` UDS relay. */
+export declare const defaultForwarderFactory: ForwarderFactory;

package/dist/substrate/git-proxy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A minimal synthetic `config` written into the proxy. Repository-format
+ * version + bare=false ONLY — explicitly NO `[remote ...]`, NO `[credential]`,
+ * NO `core.hooksPath`, NO `[user]` (which could carry a signing key path). This
+ * is the credential-scrub: the real repo's config never enters the sandbox.
+ */
+export declare const SCRUBBED_CONFIG: string;
+/**
+ * Resolve the real parent `.git` directory for a worktree. In a worktree the
+ * `<workdir>/.git` is a FILE: `gitdir: /abs/path/to/parent/.git/worktrees/<n>`.
+ * The commit objects live in the parent repo's top-level `.git` (i.e. two
+ * levels up from `worktrees/<n>`). For a NON-worktree checkout `<workdir>/.git`
+ * is already the real dir. Returns the directory that holds `objects/` +
+ * `refs/`.
+ *
+ * @returns the resolved real git-common-dir, or `null` if `<workdir>/.git` is
+ *   absent/unreadable (the caller skips proxying — a non-git workdir is fine).
+ */
+export declare function resolveGitCommonDir(workdir: string): Promise<string | null>;
+/**
+ * Build a read-only, credential-scrubbed `.git` proxy at `destDir` from the
+ * resolved git-common-dir. **[W2-min]** — copies only {@link COPIED_GIT_ENTRIES}
+ * + a synthetic stripped {@link SCRUBBED_CONFIG}; NO remotes/creds/hooks/reflog.
+ *
+ * The substrate bind-mounts `destDir` READ-ONLY into the sandbox at
+ * `<workdir>/.git`. Returns the proxy path on success, or `null` if `workdir`
+ * is not a resolvable git checkout (the substrate then mounts only the worktree
+ * with no `.git`, and git read commands simply report "not a repository" — no
+ * ambient exposure either way).
+ */
+export declare function buildScrubbedGitProxy(workdir: string, destDir: string): Promise<string | null>;
+export declare const __testing: {
+    COPIED_GIT_ENTRIES: readonly ["HEAD", "refs", "packed-refs", "objects"];
+    SCRUBBED_CONFIG: string;
+};

package/dist/substrate/index.d.ts

@@ -0,0 +1,12 @@
+export type { IsolationTech, EgressFidelity, SubstrateSpec, SubstrateProc, SubstrateHandle, Substrate, EgressDenialDetail, EgressObservationHook, CommandResult, CommandRunner, RunnerProc, } from "./types";
+export { NOOP_EGRESS_HOOK } from "./types";
+export { DockerSubstrate } from "./docker";
+export type { DockerSubstrateDeps } from "./docker";
+export { SandboxExecSubstrate, buildSeatbeltProfile } from "./sandbox-exec";
+export type { SandboxExecDeps } from "./sandbox-exec";
+export { SubstrateUnavailableError, SubstrateLaunchError } from "./errors";
+export { ChildProcessCommandRunner } from "./command-runner";
+export { HostEgressForwarder, defaultForwarderFactory } from "./forwarder";
+export type { ForwarderSpec, ForwarderFactory } from "./forwarder";
+export { buildScrubbedGitProxy, resolveGitCommonDir } from "./git-proxy";
+export { IN_CONTAINER_RELAY_SOURCE, CONTAINER_RELAY_PATH, CONTAINER_BROKER_DIR, CONTAINER_BROKER_SOCK, BROKER_SOCK_NAME, RELAY_PORT, } from "./relay-script";

package/dist/substrate/relay-script.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The in-container relay source. argv: `node relay.js <port> <udsPath>`.
+ *   - `<port>`   : the loopback TCP port the agent dials (container namespace).
+ *   - `<udsPath>`: the bind-mounted host UDS the bytes are forwarded to.
+ *
+ * `net.createServer` on `127.0.0.1:<port>` → `net.connect(<udsPath>)` → pipe
+ * both ways. A per-connection UDS-connect failure drops only that connection
+ * (the agent retries); a listen failure exits non-zero so the wrapper's hold
+ * surfaces it. Bound to `127.0.0.1` explicitly so it never binds a routable
+ * interface (there is none under `--network none`, but this is belt-and-braces).
+ */
+export declare const IN_CONTAINER_RELAY_SOURCE = "'use strict';\n// CP-7 A1 in-container relay (loopback TCP -> bind-mounted host UDS).\nconst net = require('net');\nconst port = Number(process.argv[2]);\nconst udsPath = process.argv[3];\nif (!Number.isInteger(port) || port <= 0 || port > 65535 || !udsPath) {\n  console.error('relay: usage: node relay.js <port> <udsPath>');\n  process.exit(2);\n}\nconst server = net.createServer((client) => {\n  // Single hard-wired upstream: the bind-mounted host UDS. No agent-supplied\n  // destination is ever read \u2014 this relay forwards loopback bytes to the UDS only.\n  const up = net.connect(udsPath);\n  const drop = () => { try { client.destroy(); } catch (e) {} try { up.destroy(); } catch (e) {} };\n  up.on('connect', () => { client.pipe(up); up.pipe(client); });\n  up.on('error', drop);\n  client.on('error', drop);\n});\nserver.on('error', (err) => {\n  console.error('relay: listen failed: ' + (err && err.message));\n  process.exit(1);\n});\nserver.listen(port, '127.0.0.1', () => {\n  console.error('relay: listening on 127.0.0.1:' + port + ' -> ' + udsPath);\n});\n";
+/** The in-container path the relay script is bind-mounted (read-only) to. */
+export declare const CONTAINER_RELAY_PATH = "/codevibe/relay.js";
+/** The in-container directory the host UDS dir is bind-mounted (rw) to. */
+export declare const CONTAINER_BROKER_DIR = "/codevibe/broker";
+/** The UDS filename inside the broker dir (host + container agree on this). */
+export declare const BROKER_SOCK_NAME = "broker.sock";
+/** The in-container UDS path the relay forwards to. */
+export declare const CONTAINER_BROKER_SOCK = "/codevibe/broker/broker.sock";
+/**
+ * The FIXED loopback port the in-container relay listens on, and the port the
+ * agent dials via `sandboxBrokerUrl = http://127.0.0.1:<port>`. The container
+ * has its OWN net namespace under `--network none`, so a fixed port never
+ * collides with anything on the host. 8787 is arbitrary-but-stable.
+ */
+export declare const RELAY_PORT = 8787;