@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/reviewer/output-parser.d.ts

@@ -33,14 +33,14 @@ export type VerdictParseError = {
     kind: 'empty_output';
 } | {
     /**
-     * The first non-blank line did not start with one of the four
-     * verdict keywords (case-insensitive). Includes any leading markdown
-     * formatting, quotation, or `VERDICT:` prefix that makes the line
-     * diverge from the locked contract.
+     * The first non-blank line could not be reduced to one of the four
+     * verdict keywords (case-insensitive). Harmless wrappers/labels such as
+     * `**APPROVE**` and `VERDICT: APPROVE` are accepted; prose prefaces are
+     * still rejected.
      *
-     * Also fired when a non-blank, non-indented line of prose appears
-     * after the bullet section starts (the format reserves post-bullet
-     * lines for blank lines or indented continuations only).
+     * Under the relaxed contract this fires ONLY on the FIRST non-blank
+     * line — trailing/interleaved prose AFTER a bulleted list no longer
+     * errors (it is folded into `reasoning`; see the module header).
      */
     kind: 'invalid_verdict';
     /** The offending line, trimmed but otherwise verbatim. */
@@ -52,8 +52,11 @@ export type VerdictParseError = {
      *  line is a parse failure. */
     kind: 'reasoning_missing';
 } | {
-    /** Verdict was REVISE but no bulleted suggested-changes list followed.
-     *  Design-locked: REVISE requires at least one concrete change. */
+    /** Verdict was REVISE but no concrete change could be found — neither a
+     *  bulleted suggested-changes list NOR fallback prose (#581). REVISE
+     *  requires at least one concrete change; in practice this is
+     *  unreachable because `reasoning_missing` already rejects a REVISE with
+     *  no prose, but the variant is kept as a fail-closed guard. */
     kind: 'revise_missing_changes';
 } | {
     /** A non-REVISE verdict was followed by a bulleted list, which the
@@ -87,9 +90,42 @@ export type ParseResult = {
 /**
  * Parse a reviewer reply. Strict: any deviation from the locked format
  * returns `{ ok: false, error: ... }` which the subprocess layer routes to
- * a parse-failure `ReviewerError`.
+ * a parse-failure `ReviewerError`. The ONE deliberate relaxation is the #581
+ * REVISE-prose leniency documented in the module header.
  *
- * Mirrors Rust's `parse_verdict_output` byte-for-byte. Test coverage
- * matches the Rust unit-test set verbatim.
+ * Was a byte-for-byte port of Rust's `parse_verdict_output`; the #581
+ * leniency is a TS-only divergence (this is the live path — the Rust parser
+ * is legacy/off-path). The shared-with-Rust test set is preserved verbatim;
+ * the #581 leniency tests are TS-additive.
  */
 export declare function parseVerdictOutput(raw: string): ParseResult;
+/**
+ * [Gemma classifier · D5] Extract `suggested_changes` from a REVISE reviewer's
+ * (verdict-STRIPPED) reasoning, mirroring `parseVerdictOutput`'s BULLETS-FIRST-
+ * ELSE-PROSE behavior (a bare `deriveChangesFromProse` would fold `- `/`* `
+ * bullet lists into one paragraph, LOSING structure). Collect `- `/`* ` bullets
+ * (dropping empties, folding indented continuations, treating trailing non-indented
+ * prose as commentary NOT a change); if any bullet was found, return them; else
+ * fall back to `deriveChangesFromProse` (numbered-list / paragraph derivation).
+ * Empty result ⇒ the caller downgrades REVISE → ESCALATE (fail-closed).
+ */
+export declare function extractSuggestedChanges(reasoning: string): string[];
+/**
+ * [Gemma classifier · D2a] The verdict KIND of a line iff it is a STANDALONE
+ * verdict line — `parseVerdictToken` (which strips the `VERDICT:`/`DECISION:`
+ * label, markdown wrappers, and trailing punctuation) parses it AND it carries NO
+ * inline reasoning. So `APPROVE`, `**APPROVE**`, `VERDICT: APPROVE`, `APPROVE.`
+ * → their kind; `APPROVE because the tests pass` → `null` (inline reasoning). Used
+ * by the classifier's deterministic conflicting-verdict guard + `postVerdictReasoning`.
+ */
+export declare function standaloneVerdictKind(line: string): VerdictKind | null;
+/**
+ * [Gemma classifier · D5/HIGH-A] The reviewer's post-verdict reasoning for change
+ * derivation: the text AFTER the FIRST standalone verdict line (dropping the
+ * pre-verdict preamble + the verdict line), with any REMAINING standalone verdict
+ * lines removed; if there is NO standalone verdict line (Gemma inferred the verdict
+ * from non-standalone text), the whole `rawText`. Mirrors the shipped parser, which
+ * only ever sees verdict-stripped `reasoning` — feeding raw text to change
+ * derivation would promote the preamble + the verdict token to bogus changes.
+ */
+export declare function postVerdictReasoning(rawText: string): string;

package/dist/reviewer/provider.d.ts

@@ -1,4 +1,68 @@
+import type { SubstrateHandle } from '../substrate/types.js';
+import type { VerdictClassifier } from './verdict-classifier.js';
 import type { AgentKind, ReviewerRole, ReviewerVerdict } from './types.js';
+/**
+ * CP-7 §8 (Stage-1-resolved) — per-evaluate options threaded from the live
+ * caller (`QuorumLoop.spawnOneSeat`) down through the registry into the
+ * provider. Today it carries ONLY the optional CP-7 substrate handle; it is an
+ * options object (not a positional arg) so future per-evaluate knobs do not
+ * churn every provider signature.
+ *
+ * # Why this is NOT on `ReviewerSpec`
+ *
+ * `ReviewerSpec` is a wire-format DATA struct (snake_case, echoed into the
+ * audit log + FFI). A live `SubstrateHandle` is a runtime resource (broker +
+ * sandbox lifecycle) that must NEVER be serialized — keeping it on a separate
+ * non-wire options object preserves the spec's data-only contract.
+ */
+export interface ReviewerEvaluateOptions {
+    /**
+     * CP-7 §8 — when present, the reviewer runs INSIDE the CP-7 trusted-execution
+     * sandbox + broker (no ambient vendor creds; model call via the loopback
+     * broker), exactly like a substrate-confined implementor. The provider
+     * forwards it to `runReviewer({ …, substrate })` AND drops the
+     * `{...process.env}` env spread in its `buildCommand` (the env is pre-baked
+     * sanitized at `substrate.launch()`). ABSENT → the legacy unsandboxed path
+     * (byte-identical to pre-CP-7-reviewer-sandbox behavior).
+     */
+    substrate?: SubstrateHandle;
+    /**
+     * CP-7 reviewer-sandbox fix — the HOST path of the substrate workdir (the
+     * sandboxed child's cwd). REQUIRED in practice whenever {@link substrate} is
+     * present for the Codex provider, which writes its verdict via `codex exec
+     * --output-last-message <path>`: on the sandbox path that file MUST live in
+     * the sandbox-writable + host-readable workdir, NOT `os.tmpdir()` (which the
+     * A1 container does not mount and the A5 Seatbelt profile does not grant for
+     * writes). The provider passes a RELATIVE filename to codex (codex's cwd ==
+     * the workdir on BOTH backends — A5 `cwd: workdir`; Docker `docker exec -w
+     * /workspace`) and reads it back from `<workdir>/<name>` on the host (the same
+     * inode, even when A5 canonicalizes the workdir — the host read follows the
+     * symlink). The Claude / Gemini providers do not use a file output, so they
+     * ignore this field. ABSENT (legacy path / non-substrate) → the provider uses
+     * its byte-identical legacy `os.tmpdir()` location.
+     *
+     * # Why this is NOT derivable from `substrate`
+     *
+     * `SubstrateHandle` (a runtime resource) deliberately does NOT expose the
+     * workdir — it is a launch-time input the caller already holds. Threading the
+     * host workdir here (the loop's `workingDir`, the very value it engages the
+     * substrate with) keeps the handle's surface minimal.
+     */
+    workdir?: string;
+    /**
+     * REVIEWER-VERDICT-GEMMA-CLASSIFIER-DESIGN.md (D1) — when present, the provider's
+     * `buildVerdict` calls `await classifyVerdict(rawText, ctx)` (local-Gemma verdict
+     * classification, fail-closed) INSTEAD of the regex `parseVerdictOutput`. Under
+     * the default `gemma` mode this is ALWAYS present (the real Gemma classifier, or
+     * a dummy always-ESCALATE classifier when the runner is null at boot) — so a
+     * silent regex fallback is impossible. ABSENT ⇒ the provider uses the regex
+     * `parseVerdictOutput`, reachable ONLY via `CODEVIBE_REVIEWER_VERDICT_CLASSIFIER=regex`
+     * (a deliberate `undefined`, never an accidental missing-classifier fallback).
+     * The non-zero-exit → `spawn_failed` guard still runs FIRST (a crashed reviewer
+     * is a spawn failure, never sent to the classifier).
+     */
+    classifyVerdict?: VerdictClassifier;
+}
 /**
  * Spec for spawning one reviewer at one gate. Constructed by the engine
  * from `ReviewerAgentSpec` (from `PolicySnapshot`) + the context bundle for
@@ -67,6 +131,28 @@ export interface ReviewerSpec {
      */
     model_hint: string | null;
 }
+/**
+ * CP-1.f escalation per-seat surfacing — SAFE, CLOSED failure-classification
+ * label. The cross-repo contract (`/tmp/cp1f-escalation-impl-contract.md` §1)
+ * pins this taxonomy byte-for-byte with the Rust side
+ * (`reason_code: Option<ReviewerFailureReason>` on `ReviewerError::SpawnFailed`,
+ * `#[serde(rename_all = "snake_case")]`).
+ *
+ * # Safety invariant (LOAD-BEARING)
+ *
+ * This is a LABEL ONLY. It MUST NEVER carry raw stderr / stdout / paths /
+ * credentials. It is **distinct from and never derived into** the raw
+ * `spawn_failed.reason` (which DOES carry stderr). `QuorumLoop.synthesizeEscalate`
+ * reads ONLY this label and maps it through a fixed `label → human template`
+ * table — the raw `.reason` never reaches the wire `reasoning`.
+ *
+ * - `usage_limit`   — provider hit a usage / capacity / rate limit.
+ * - `auth_failed`   — provider could not authenticate (401 / not-logged-in).
+ * - `timeout`       — the wrapper's own wall-clock timeout fired.
+ * - `parse_failure` — the stream parsed but yielded no usable final reply.
+ * - `spawn_failed`  — generic fallback (non-zero exit, no structured error).
+ */
+export type ReviewerFailureReason = 'usage_limit' | 'auth_failed' | 'timeout' | 'parse_failure' | 'spawn_failed';
 /**
  * Typed error thrown by `ReviewerProvider.evaluate`. Discriminated union
  * matching Rust's `#[serde(tag = "kind", rename_all = "snake_case")]` enum.
@@ -86,11 +172,26 @@ export type ReviewerError = {
     elapsed_ms: number;
 } | {
     /** Reviewer process could not be launched (CLI missing, spawn syscall
-     *  failed, etc.). */
+     *  failed, etc.) OR exited non-zero. */
     kind: 'spawn_failed';
     agent: AgentKind;
-    /** Human-readable cause. */
+    /**
+     * Human-readable cause. **MAY carry raw stderr** — must stay in logs /
+     * audit only. NEVER promote this into the synthesized verdict wire
+     * `reasoning` (CP-1.f sanitization invariant). Use `failureReason` for
+     * the user-facing one-liner instead.
+     */
     reason: string;
+    /**
+     * CP-1.f — SAFE, CLOSED classification of WHY the reviewer could not
+     * complete, derived from the provider's `--json` STDOUT error stream
+     * (NOT from `reason`/stderr). `QuorumLoop.synthesizeEscalate` reads this
+     * — never `reason` — and maps it through a fixed human template.
+     * Optional: absent on the legacy path (older serialized errors) →
+     * `synthesizeEscalate` falls back to the clean `spawn_failed` template,
+     * never raw output.
+     */
+    failureReason?: ReviewerFailureReason;
 } | {
     /** Reviewer returned but its output couldn't be parsed into a valid
      *  verdict. Raw output is preserved for the audit log. */
@@ -144,10 +245,13 @@ export interface ReviewerProvider {
      * @param spec - the reviewer to spawn (seat_id + role + agent + prompt + timeout)
      * @param gateId - the `ReviewGate` UUID this verdict attaches to. Stored
      *                 on the returned `ReviewerVerdict.gate_id`.
+     * @param opts - CP-7 §8 (Stage-1-resolved) OPTIONAL per-evaluate options;
+     *               carries the substrate handle when the reviewer is sandboxed.
+     *               ABSENT/`{}` → the legacy unsandboxed path (byte-identical).
      * @returns the parsed `ReviewerVerdict` on success.
      * @throws `ReviewerErrorClass` on timeout, spawn failure, parse failure,
      *         cancellation, or internal join failure. Use `e.detail.kind` to
      *         narrow.
      */
-    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+    evaluate(spec: ReviewerSpec, gateId: string, opts?: ReviewerEvaluateOptions): Promise<ReviewerVerdict>;
 }

package/dist/reviewer/providers/__tests__/failure-classifier.test.d.ts

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

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

@@ -0,0 +1,49 @@
+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';
+/** Built command shape — split out so tests can inspect args/env without spawning. */
+export interface BuiltCommand {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+}
+/** Construction options. */
+export interface AntigravityReviewerProviderOptions {
+    /** Override the `agy` executable path (tests point at a fixture CLI). */
+    executable?: string;
+}
+/**
+ * Real Antigravity reviewer provider. Wraps the `agy` CLI (the bare
+ * Google-distributed binary — NOT the `codevibe-agy` 1.x wrapper).
+ */
+export declare class AntigravityReviewerProvider implements ReviewerProvider {
+    private readonly executable;
+    constructor(opts?: AntigravityReviewerProviderOptions);
+    evaluate(spec: ReviewerSpec, gateId: string, opts?: ReviewerEvaluateOptions): Promise<ReviewerVerdict>;
+}
+/**
+ * Construct the agy CLI invocation (design D4):
+ *
+ * - `--print ''` — non-interactive one-shot; the EMPTY value selects the
+ *   STDIN prompt (fed by `runReviewer`), keeping multi-line markdown out of
+ *   argv (same posture as gemini's `-p ''`).
+ * - `--model <hint>` — optional; omitted when `spec.model_hint` is `null`
+ *   (agy default model).
+ * - `--print-timeout <s>s` — agy's INTERNAL print-mode poll ceiling, derived
+ *   from the spec timeout so agy gives up (with its own clean teardown)
+ *   BEFORE `runReviewer`'s external `timeout_ms` kill fires.
+ * - `--add-dir <workdir>` — grants agy's tools the repo (workspace-centric).
+ *
+ * No `--output-format json` exists in agy print mode — stdout is the raw
+ * reply text and there is no usage/token envelope (D10: tokens_used null).
+ */
+export declare function buildCommand(executable: string, spec: ReviewerSpec, workdir: string): BuiltCommand;
+/**
+ * Map the raw subprocess outcome into a `ReviewerVerdict` or throw a
+ * structured `ReviewerErrorClass`. Exit code first (a crashed CLI's stdout is
+ * unreliable); then the verdict text is `outcome.stdout` VERBATIM (no json
+ * unwrap — agy print mode is plain text) fed to the injected classifier
+ * (default) or the legacy regex parser (`CODEVIBE_REVIEWER_VERDICT_CLASSIFIER=regex`).
+ */
+export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, classifyVerdict?: VerdictClassifier): Promise<ReviewerVerdict>;

package/dist/reviewer/providers/claude.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';
 /**
  * Built command shape — split out so tests can inspect args / env without
  * spawning a process. `runReviewer` consumes this shape directly.
@@ -27,7 +28,7 @@ export interface ClaudeReviewerProviderOptions {
 export declare class ClaudeReviewerProvider implements ReviewerProvider {
     private readonly executable;
     constructor(opts?: ClaudeReviewerProviderOptions);
-    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+    evaluate(spec: ReviewerSpec, gateId: string, opts?: ReviewerEvaluateOptions): Promise<ReviewerVerdict>;
 }
 /**
  * Construct the Claude CLI invocation. Split out from `evaluate` so unit
@@ -48,12 +49,26 @@ export declare class ClaudeReviewerProvider implements ReviewerProvider {
  *
  * Set unconditionally to `'1'` in the child's environment. See module docs
  * for the rationale and why `--bare` was rejected as the primary defense.
+ *
+ * # CP-7 §8 (Stage-1-resolved) — `sandboxed` drops the `process.env` spread
+ *
+ * On the SUBSTRATE path (`sandboxed === true`) the returned `env` is EMPTY:
+ * the reviewer's real env is pre-baked at `substrate.launch()` (the I1
+ * allow-list `sanitizedEnv` — broker base-URL + config dir, NO vendor key),
+ * and `runReviewer` ignores `BuiltCommand.env` when a substrate handle is
+ * present. We deliberately do NOT spread `{...process.env}` here in that
+ * case: the spread re-introduces `ANTHROPIC_API_KEY` / OAuth env + the host
+ * `ANTHROPIC_BASE_URL` / `CLAUDE_CONFIG_DIR` that would DEFEAT the broker
+ * redirect (THE moat hole). The `QUORUM_REVIEWER_SUBPROCESS` marker is folded
+ * into the substrate's sanitizedEnv at launch (the engager's marker step),
+ * not via this field. On the LEGACY path (`sandboxed === false`, the default)
+ * the env is built exactly as before — byte-identical non-regression.
  */
-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`. Exit code is checked first — a crashed
  * CLI that happened to print something valid on stdout should still be
  * treated as a spawn failure, not a silently-accepted verdict.
  */
-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>;

package/dist/reviewer/providers/codex.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 CodexReviewerProviderOptions {
@@ -15,7 +16,7 @@ export interface CodexReviewerProviderOptions {
 export declare class CodexReviewerProvider implements ReviewerProvider {
     private readonly executable;
     constructor(opts?: CodexReviewerProviderOptions);
-    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+    evaluate(spec: ReviewerSpec, gateId: string, opts?: ReviewerEvaluateOptions): Promise<ReviewerVerdict>;
 }
 /**
  * Construct the Codex CLI invocation. Split out from `evaluate` so unit
@@ -35,18 +36,26 @@ export declare class CodexReviewerProvider implements ReviewerProvider {
  * - `--ephemeral` — do NOT write a session JSONL under
  *   `~/.codex/sessions/`.
  * - `--output-last-message <path>` — write the model's final agent
- *   message verbatim to `path`.
+ *   message verbatim to `path`. On the LEGACY path `path` is an ABSOLUTE
+ *   `os.tmpdir()` file; on the SUBSTRATE path it is a RELATIVE filename so
+ *   codex writes it into its cwd (the workdir) — the only sandbox-writable +
+ *   host-readable location (see `evaluate` / `resolveLastMessagePaths`).
  * - `--model <hint>` — optional; omitted when `spec.model_hint` is `null`.
  * - `-` (final arg) — read prompt from stdin.
+ *
+ * `lastMessagePath` is the value passed to `--output-last-message` AS CODEX
+ * SEES IT (the in-sandbox arg): an absolute tmp path on the legacy path, a
+ * relative-to-cwd filename on the substrate path. The CALLER (`evaluate`) owns
+ * the corresponding HOST read/unlink path.
  */
-export declare function buildCommand(executable: string, spec: ReviewerSpec, lastMessagePath: string): BuiltCommand;
+export declare function buildCommand(executable: string, spec: ReviewerSpec, lastMessagePath: string, sandboxed?: boolean): BuiltCommand;
 /**
  * Map the raw subprocess outcome + the file Codex wrote into a
  * `ReviewerVerdict` or throw a structured `ReviewerErrorClass`. See
  * `claude.ts::buildVerdict` for the shared safety rule (non-zero exit
  * overrides any parseable stdout / file).
  */
-export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, lastMessage: string): ReviewerVerdict;
+export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, lastMessage: string, classifyVerdict?: VerdictClassifier): Promise<ReviewerVerdict>;
 /**
  * Sum `usage.input_tokens + usage.output_tokens` across every
  * `turn.completed` JSONL event in `stdout`. Returns `null` when no
@@ -63,5 +72,38 @@ export declare function sumCodexTokens(stdout: string): number | null;
  * the OS temp dir; we own its lifecycle (create on codex's side, read +
  * delete on ours). Per-process pid + UUID is enough — no race risk across
  * concurrent reviewers in the same engine run.
+ *
+ * Used for the LEGACY (unsandboxed) path; the sandbox path routes the file
+ * THROUGH the workdir instead — see {@link resolveLastMessagePaths}.
  */
 export declare function makeLastMessagePath(): string;
+/**
+ * CP-7 reviewer-sandbox fix — resolve the TWO paths for the codex
+ * `--output-last-message` file:
+ *  - `argPath`  — what codex SEES (the value passed to the CLI flag).
+ *  - `hostPath` — what the HOST reads/unlinks the file at.
+ *
+ * LEGACY (`sandboxed === false`): both are the SAME absolute `os.tmpdir()`
+ * path (byte-identical to pre-CP-7-reviewer-sandbox behavior). codex writes
+ * the host tmp file directly.
+ *
+ * SUBSTRATE (`sandboxed === true`): codex cannot write the host `os.tmpdir()`
+ * (A1 never mounts host `/tmp`; A5's Seatbelt profile grants writes to the
+ * WORKDIR only). So `argPath` is a RELATIVE filename: codex's cwd IS the
+ * workdir on both backends (A5 spawns `cwd: workdir`; Docker `docker exec -w
+ * /workspace`), so codex writes `<sandboxCwd>/<name>`. The host reads it at
+ * `hostPath = <workdir>/<name>` — the SAME inode (A5 shares the host fs even
+ * after the substrate canonicalizes the workdir, because the host read follows
+ * the symlink; A1 bind-mounts the workdir, so `<workdir>` on the host IS
+ * `/workspace` in the container). A relative `argPath` is deliberately
+ * cwd-agnostic, so it is correct for BOTH backends without per-backend mapping.
+ *
+ * FAIL-CLOSED: the substrate path REQUIRES the host `workdir`. Without it we
+ * cannot read codex's verdict back, so we THROW (the caller turns a provider
+ * throw into a clean synthesized ESCALATE) rather than silently writing to a
+ * relative file the host cannot locate.
+ */
+export declare function resolveLastMessagePaths(sandboxed: boolean, workdir: string | undefined): {
+    argPath: string;
+    hostPath: string;
+};

package/dist/reviewer/providers/failure-classifier.d.ts

@@ -0,0 +1,26 @@
+import type { ReviewerFailureReason } from '../provider.js';
+/**
+ * Classify a single provider error MESSAGE into a `ReviewerFailureReason`, or
+ * `null` if it matches no known structured-failure signal.
+ *
+ * SAFE: returns only the closed label — never the message. Pure string match;
+ * no I/O, never throws.
+ */
+export declare function classifyFailureMessage(message: string): ReviewerFailureReason | null;
+/**
+ * Scan a provider's `--json` STDOUT event stream for a structured failure
+ * event (`{"type":"error"}` / `{"type":"turn.failed"}`) and classify the FIRST
+ * one found into a `ReviewerFailureReason`. Returns `null` when the stream
+ * carries no classifiable structured error (caller falls back to the generic
+ * `spawn_failed` label).
+ *
+ * # Truncation tolerance (LOAD-BEARING)
+ *
+ * Each line is JSON; per-line `JSON.parse` is wrapped in try/catch. A truncated
+ * final line — which a timeout / abort can leave behind mid-flush — is SKIPPED,
+ * never thrown. The whole scan degrades gracefully to `null` rather than
+ * propagating a parse error up through the escalation-synthesis path.
+ *
+ * SAFE: returns only the closed label — never any raw stream content.
+ */
+export declare function classifyFailureFromStdout(stdout: string): ReviewerFailureReason | null;

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.
  *