@quantiya/codevibe-core 1.0.23 → 2.0.1

package/dist/planner/client.d.ts

@@ -0,0 +1,103 @@
+import type { PlannerInput, PlannerDecision, PlannerProbeResult, Tier } from './types';
+import type { PlannerAdapter } from './adapter';
+import type { PlannerCacheLayer } from './cache';
+import type { PlannerHealthMachine } from './health-state';
+/**
+ * AppSync transport interface. Minimal shape so unit tests can inject
+ * a stub without mounting the full @quantiya/codevibe-core AppSyncClient.
+ */
+export interface PlannerAppSyncTransport {
+    classifyPlannerPrompt(input: {
+        sessionId: string;
+        prompt: string;
+        clarifications: string;
+        sessionContext: string;
+        budgetHint: string;
+    }): Promise<{
+        decision: string;
+        cacheHit: boolean;
+        cacheKind: string | null;
+        serverLatencyMs: number;
+        providerUsed: string;
+    }>;
+    pingPlanner(input: {
+        sessionId: string;
+    }): Promise<{
+        ok: boolean;
+        ms: number;
+    }>;
+}
+/**
+ * Crypto bridge — `encryptString` + `encryptJson` + `decryptJson`
+ * variants the adapter needs. Mirrors the existing
+ * codevibe-core CryptoService surface; injectable for tests.
+ */
+export interface PlannerCryptoBridge {
+    /** Encrypt a UTF-8 string to base64 AES-GCM ciphertext. */
+    encryptString(plaintext: string, sessionKeyB64: string): string;
+    /** Decrypt base64 AES-GCM → UTF-8 string. */
+    decryptString(ciphertextB64: string, sessionKeyB64: string): string;
+    /** Encrypt JSON-serializable value → base64 ciphertext. */
+    encryptJson(obj: unknown, sessionKeyB64: string): string;
+}
+export interface SessionKeyResolver {
+    getSessionKey(sessionId: string): Promise<string | null>;
+}
+export interface ShellEventEmit {
+    sessionId: string;
+    type: 'PLANNER_DECISION' | 'PLANNER_CACHE_HIT' | 'PLANNER_DEGRADED' | 'PLANNER_OUTAGE' | 'PLANNER_RECOVERED';
+    metadata?: Record<string, unknown>;
+}
+export type EmitShellEventFn = (args: ShellEventEmit) => Promise<void>;
+/**
+ * CP-1.b Stage 2 r2 M-3 — Typed errors that must NOT degrade health.
+ *
+ * The Lambda surfaces tier-gate / budget rejections as named-error
+ * GraphQL responses. Stage 2 r1's catch block recorded EVERY failure
+ * as a provider-health failure via `health.recordCall(elapsed, false)`,
+ * incorrectly driving the health machine toward Degraded/Outage on
+ * what are user-tier policy events (not provider outages). The
+ * client now classifies errors and ONLY records provider failures
+ * against health; tier/budget rejections emit NOTIFICATION events
+ * and throw without touching the machine.
+ */
+export declare class PlannerBudgetExceededError extends Error {
+    constructor(msg: string);
+}
+export declare class PlannerTierGateRejectedError extends Error {
+    constructor(msg: string);
+}
+export declare class BackendPlannerClient implements PlannerAdapter {
+    private transport;
+    private cache;
+    private health;
+    private crypto;
+    private sessionKeyResolver;
+    private emitShellEvent;
+    /** Shell-side tier-change detection (LOCK #30). */
+    lastClassifyTier: Tier | null;
+    /**
+     * CP-1.b Stage 2 r2 M-4 — Active session for probe(). The probe
+     * mutation requires a sessionId for ownership check; carrying the
+     * session in client state lets callers use the canonical
+     * `PlannerAdapter.probe()` contract. Set via `setActiveSession()`
+     * by orchestration-shell on session start.
+     */
+    private activeSessionId;
+    constructor(transport: PlannerAppSyncTransport, cache: PlannerCacheLayer, health: PlannerHealthMachine, crypto: PlannerCryptoBridge, sessionKeyResolver: SessionKeyResolver, emitShellEvent: EmitShellEventFn);
+    /**
+     * CP-1.b Stage 2 r2 M-4 — Set the active session ID used by
+     * `probe()`. Called by the orchestration-shell on session start
+     * (and cleared to `null` on session end).
+     */
+    setActiveSession(sessionId: string | null): void;
+    classify(input: PlannerInput): Promise<PlannerDecision>;
+    /**
+     * CP-1.b Stage 2 r2 M-4 — Honor the `PlannerAdapter.probe()`
+     * contract by reading the session from client state (set via
+     * `setActiveSession()`). Stage 2 r1 threw unconditionally and
+     * required callers to use the now-removed `probeWithSession()`
+     * method, which violated the adapter interface.
+     */
+    probe(): Promise<PlannerProbeResult>;
+}

package/dist/planner/health-state.d.ts

@@ -0,0 +1,24 @@
+import type { PlannerHealthState, PlannerHealthTransition } from './types';
+export type { PlannerHealthState, PlannerHealthTransition };
+export declare class PlannerHealthMachine {
+    private emitFn;
+    state: PlannerHealthState;
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+    recentLatenciesMs: number[];
+    private readonly URGENT_FAILURE_FOR_DEGRADE;
+    private readonly P95_DEGRADE_THRESHOLD_MS;
+    private readonly P95_RECOVER_THRESHOLD_MS;
+    private readonly DEGRADED_TO_OUTAGE_FAILURES;
+    private readonly RECOVER_SUCCESSES_NEEDED;
+    private readonly RING_BUFFER_SIZE;
+    private readonly DEGRADED_PROBE_INTERVAL_MS;
+    private readonly OUTAGE_PROBE_INTERVAL_MS;
+    private lastProbeAt;
+    constructor(emitFn: (transition: PlannerHealthTransition) => void);
+    recordCall(latencyMs: number, success: boolean): PlannerHealthState;
+    shouldProbe(): boolean;
+    markProbeFired(): void;
+    private deriveNextState;
+    private p95Of;
+}

package/dist/planner/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './adapter';
+export { PlannerCacheLayer } from './cache';
+export { PlannerHealthMachine } from './health-state';
+export { BackendPlannerClient, PlannerBudgetExceededError, PlannerTierGateRejectedError, type PlannerAppSyncTransport, type PlannerCryptoBridge, type SessionKeyResolver, type ShellEventEmit, type EmitShellEventFn, } from './client';

package/dist/planner/types.d.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+export type Tier = 'FREE' | 'PRO' | 'MAX';
+export interface SessionContext {
+    sessionId: string;
+    userId: string;
+    tier: Tier;
+    currentTaskState: 'none' | 'in_progress' | 'awaiting_user' | 'awaiting_review' | 'merge_gate_pending';
+    structuralSummaryDigest: string;
+    recentEventCount: number;
+}
+export declare const SessionContextSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    userId: z.ZodString;
+    tier: z.ZodEnum<["FREE", "PRO", "MAX"]>;
+    currentTaskState: z.ZodEnum<["none", "in_progress", "awaiting_user", "awaiting_review", "merge_gate_pending"]>;
+    structuralSummaryDigest: z.ZodString;
+    recentEventCount: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    userId: string;
+    structuralSummaryDigest: string;
+    tier: "FREE" | "PRO" | "MAX";
+    currentTaskState: "none" | "merge_gate_pending" | "in_progress" | "awaiting_user" | "awaiting_review";
+    recentEventCount: number;
+}, {
+    sessionId: string;
+    userId: string;
+    structuralSummaryDigest: string;
+    tier: "FREE" | "PRO" | "MAX";
+    currentTaskState: "none" | "merge_gate_pending" | "in_progress" | "awaiting_user" | "awaiting_review";
+    recentEventCount: number;
+}>;
+export interface BudgetHint {
+    wallClockMsRemaining: number;
+    reviseAttempts: number;
+}
+export declare const BudgetHintSchema: z.ZodObject<{
+    wallClockMsRemaining: z.ZodNumber;
+    reviseAttempts: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    wallClockMsRemaining: number;
+    reviseAttempts: number;
+}, {
+    wallClockMsRemaining: number;
+    reviseAttempts: number;
+}>;
+export interface Clarification {
+    question: string;
+    answer: string;
+}
+export declare const ClarificationSchema: z.ZodObject<{
+    question: z.ZodString;
+    answer: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    question: string;
+    answer: string;
+}, {
+    question: string;
+    answer: string;
+}>;
+export interface PlannerInput {
+    prompt: string;
+    clarifications: Clarification[];
+    sessionContext: SessionContext;
+    budgetHint: BudgetHint;
+}
+export interface PlannerDecision {
+    action: 'start_task' | 'summarize_current_status' | 'advisory_response' | 'ask_user' | 'refuse';
+    rationale: string;
+    clarifying_question?: string;
+    advisory_summary?: string;
+    /** Opaque per parent §6 lines 967-972; CP-1 NEVER inspects fields. */
+    gateRequest?: Record<string, unknown>;
+}
+export declare const PlannerDecisionSchema: z.ZodObject<{
+    action: z.ZodEnum<["start_task", "summarize_current_status", "advisory_response", "ask_user", "refuse"]>;
+    rationale: z.ZodString;
+    clarifying_question: z.ZodOptional<z.ZodString>;
+    advisory_summary: z.ZodOptional<z.ZodString>;
+    gateRequest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    action: "start_task" | "summarize_current_status" | "advisory_response" | "ask_user" | "refuse";
+    rationale: string;
+    clarifying_question?: string | undefined;
+    advisory_summary?: string | undefined;
+    gateRequest?: Record<string, unknown> | undefined;
+}, {
+    action: "start_task" | "summarize_current_status" | "advisory_response" | "ask_user" | "refuse";
+    rationale: string;
+    clarifying_question?: string | undefined;
+    advisory_summary?: string | undefined;
+    gateRequest?: Record<string, unknown> | undefined;
+}>;
+export interface PlannerProbeResult {
+    ok: boolean;
+    latencyMs: number;
+    errorClass?: 'timeout' | 'rate_limited' | 'unreachable' | 'malformed_response' | 'auth_failed';
+}
+export type ClassificationKind = 'workflow_status_query' | 'workflow_audit_query' | 'workflow_review_query' | 'workflow_continuation_query' | 'advisory_response_safe' | 'ask_user_clarification';
+export interface CachedClassification {
+    kind: ClassificationKind;
+    clarifyingQuestion?: string;
+    advisorySummary?: string;
+}
+export type PlannerHealthState = 'Available' | 'Degraded' | 'Outage';
+export interface PlannerHealthTransition {
+    newState: PlannerHealthState;
+    fromState: PlannerHealthState;
+    reason: string;
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+    p95Ms: number;
+}

package/dist/reviewer/__tests__/integration.test.d.ts

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

package/dist/reviewer/__tests__/mocks.test.d.ts

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

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

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

package/dist/reviewer/__tests__/registry.test.d.ts

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

package/dist/reviewer/__tests__/subprocess.test.d.ts

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

package/dist/reviewer/index.d.ts

@@ -0,0 +1,15 @@
+export type { AgentKind, ReviewerRole, ReviewerVerdict, VerdictId, VerdictKind, } from './types.js';
+export type { ReviewerError, ReviewerProvider, ReviewerSpec, } from './provider.js';
+export { ReviewerErrorClass } from './provider.js';
+export type { ParseResult, ParsedVerdict, VerdictParseError, } from './output-parser.js';
+export { parseVerdictOutput, VerdictParseErrorClass } from './output-parser.js';
+export type { RunReviewerOptions, SubprocessError, SubprocessOutcome, } from './subprocess.js';
+export { runReviewer, SubprocessErrorClass } from './subprocess.js';
+export type { ClaudeReviewerProviderOptions } from './providers/claude.js';
+export { ClaudeReviewerProvider } from './providers/claude.js';
+export type { GeminiEnvelope, GeminiModelStats, GeminiReviewerProviderOptions, GeminiStats, } from './providers/gemini.js';
+export { GeminiReviewerProvider } from './providers/gemini.js';
+export type { CodexReviewerProviderOptions } from './providers/codex.js';
+export { CodexReviewerProvider } from './providers/codex.js';
+export { ReviewerRegistry, createSubprocessReviewerRegistry, } from './registry.js';
+export { MockReviewerSpawner, StaticReviewerMock } from './mocks.js';

package/dist/reviewer/mocks.d.ts

@@ -0,0 +1,80 @@
+import { type ReviewerProvider, type ReviewerSpec } from './provider.js';
+import type { AgentKind, ReviewerVerdict, VerdictKind } from './types.js';
+import { type ReviewerError } from './provider.js';
+/**
+ * Scripted `ReviewerProvider` for tests. Each `evaluate(spec, gateId)`
+ * pops the next response from the FIFO queue keyed by
+ * `(spec.agent, gateId)`. If no script remains, returns a SpawnFailed
+ * error with a diagnostic so test setup bugs surface loudly.
+ *
+ * Use the `script_*` methods to queue responses before tests call
+ * `evaluate`.
+ */
+export declare class MockReviewerSpawner implements ReviewerProvider {
+    private readonly scripts;
+    private static key;
+    /**
+     * Script a verdict (with empty `suggested_changes`) for the next
+     * `evaluate(agent, gateId)` call. Use `scriptVerdictWithChanges`
+     * when `kind === 'REVISE'` (the parser-locked invariant requires
+     * non-empty changes for REVISE).
+     */
+    scriptVerdict(agent: AgentKind, gateId: string, kind: VerdictKind, reasoning: string): void;
+    /**
+     * Script a verdict with explicit `suggested_changes`. Required when
+     * `kind === 'REVISE'`.
+     */
+    scriptVerdictWithChanges(agent: AgentKind, gateId: string, kind: VerdictKind, reasoning: string, suggested_changes: string[]): void;
+    /** Script an error to return on the next `evaluate(agent, gateId)` call. */
+    scriptError(agent: AgentKind, gateId: string, error: ReviewerError): void;
+    /**
+     * How many scripted responses remain for the given key. Useful for
+     * test post-conditions ("all scripts were consumed").
+     */
+    remaining(agent: AgentKind, gateId: string): number;
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}
+/**
+ * Stateless `ReviewerProvider` for engine-level integration tests and
+ * smoke tests. Ignores `gateId`; returns a fixed verdict per agent
+ * (or a global default).
+ *
+ * Construct via static factories:
+ * - `StaticReviewerMock.allApprove()` / `.allReject()` / `.allRevise(changes)`
+ *   / `.allEscalate()` — global default, every agent returns the same.
+ * - `StaticReviewerMock.allError(err)` — every agent returns the same error.
+ *
+ * Stack per-agent overrides on top:
+ * - `.withAgentVerdict(agent, kind)` — override one agent's verdict.
+ * - `.withAgentError(agent, err)` — override one agent's error.
+ *
+ * Stacking models mixed-verdict scenarios: e.g.
+ * `StaticReviewerMock.allApprove().withAgentVerdict('gemini', 'REJECT')`
+ * → Claude approves + Gemini rejects + Codex approves → engine escalates.
+ */
+export declare class StaticReviewerMock implements ReviewerProvider {
+    private defaultResponse;
+    private readonly perAgent;
+    /** Empty mock. Returns SpawnFailed with a diagnostic on every
+     *  `evaluate` call until a default or per-agent override is set. */
+    static new(): StaticReviewerMock;
+    /** All reviewers return APPROVE. */
+    static allApprove(): StaticReviewerMock;
+    /** All reviewers return REJECT. */
+    static allReject(): StaticReviewerMock;
+    /** All reviewers return REVISE with the given suggested changes.
+     *  Empty `changes` falls back to a placeholder. */
+    static allRevise(changes: string[]): StaticReviewerMock;
+    /** All reviewers return ESCALATE. */
+    static allEscalate(): StaticReviewerMock;
+    /** All reviewers return the given error. */
+    static allError(err: ReviewerError): StaticReviewerMock;
+    /**
+     * Override the response for one agent. Stacks on top of whatever
+     * default was configured. Returns `this` for fluent chaining.
+     */
+    withAgentVerdict(agent: AgentKind, kind: VerdictKind): this;
+    /** Override to return an error for one specific agent. */
+    withAgentError(agent: AgentKind, err: ReviewerError): this;
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}

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

@@ -0,0 +1,95 @@
+import type { VerdictKind } from './types.js';
+/**
+ * Successfully parsed reviewer reply. The engine's fan-out layer lifts
+ * these fields into a `ReviewerVerdict` alongside telemetry (agent, tokens,
+ * latency, model) supplied by the subprocess layer.
+ */
+export interface ParsedVerdict {
+    /** The verdict the reviewer returned. */
+    kind: VerdictKind;
+    /**
+     * Free-form reasoning text (joined with blank-line paragraph separators
+     * preserved). Never empty by the time we reach here — reviewers that
+     * return only a verdict line fail parsing via `reasoning_missing`.
+     */
+    reasoning: string;
+    /**
+     * Ordered list of specific changes. Always non-empty when
+     * `kind === 'REVISE'`; always empty otherwise (enforced by the parser
+     * via `revise_missing_changes` / `suggested_changes_require_revise`).
+     */
+    suggested_changes: string[];
+}
+/**
+ * Why a reviewer's reply failed the locked-format check. Discriminated
+ * union; the subprocess layer maps any of these into `ReviewerError` with
+ * `kind: 'parse_failure'` and the raw output attached.
+ *
+ * Mirrors Rust's `VerdictParseError` enum 1:1.
+ */
+export type VerdictParseError = {
+    /** The entire reply was whitespace or empty. A reviewer that wrote
+     *  nothing has effectively timed out. */
+    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.
+     *
+     * 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).
+     */
+    kind: 'invalid_verdict';
+    /** The offending line, trimmed but otherwise verbatim. */
+    found: string;
+} | {
+    /** Verdict was parsed but no reasoning followed. The locked contract
+     *  requires reasoning text so the audit record and user-facing
+     *  disagreement UI have something to show; a bare APPROVE / REJECT
+     *  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. */
+    kind: 'revise_missing_changes';
+} | {
+    /** A non-REVISE verdict was followed by a bulleted list, which the
+     *  locked contract reserves for REVISE only. */
+    kind: 'suggested_changes_require_revise';
+    /** The non-REVISE verdict that erroneously had bullets. */
+    found: VerdictKind;
+};
+/**
+ * Class wrapper around a `VerdictParseError` so callers can `throw`/`catch`
+ * structured errors via JS idioms. `.detail` carries the discriminated
+ * union; `Error.message` is a human-readable formatting.
+ */
+export declare class VerdictParseErrorClass extends Error {
+    readonly detail: VerdictParseError;
+    constructor(detail: VerdictParseError);
+}
+/**
+ * Result type for `parseVerdictOutput`. Discriminated by `ok`. Mirrors
+ * Rust's `Result<ParsedVerdict, VerdictParseError>` without forcing TS
+ * callers to `try/catch` — most call sites want to inspect failure types
+ * directly to feed the audit log.
+ */
+export type ParseResult = {
+    ok: true;
+    verdict: ParsedVerdict;
+} | {
+    ok: false;
+    error: VerdictParseError;
+};
+/**
+ * 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`.
+ *
+ * Mirrors Rust's `parse_verdict_output` byte-for-byte. Test coverage
+ * matches the Rust unit-test set verbatim.
+ */
+export declare function parseVerdictOutput(raw: string): ParseResult;

package/dist/reviewer/provider.d.ts

@@ -0,0 +1,153 @@
+import type { AgentKind, ReviewerRole, ReviewerVerdict } from './types.js';
+/**
+ * Spec for spawning one reviewer at one gate. Constructed by the engine
+ * from `ReviewerAgentSpec` (from `PolicySnapshot`) + the context bundle for
+ * the gate.
+ *
+ * # Identity
+ *
+ * Per the 2026-04-23 seat/role pivot, the spec's primary identity is
+ * `seat_id` — position in the review panel — NOT `agent`. `agent` may
+ * repeat across seats within a single gate (single-vendor case: two Claude
+ * seats with different roles). Downstream consensus + verdict validation
+ * dedup on `seat_id`, never on `agent`. Providers echo `seat_id` + `role`
+ * back on the returned `ReviewerVerdict` so the audit trail can attribute
+ * verdicts by lens rather than by agent kind.
+ */
+export interface ReviewerSpec {
+    /**
+     * Position in the review panel, 0-indexed. For an N-seat policy this is
+     * in `0..N`. The primary identity key for this reviewer across the
+     * engine, audit log, and FFI — providers MUST echo this value back on
+     * the produced `ReviewerVerdict.seat_id`.
+     */
+    seat_id: number;
+    /**
+     * The lens this seat reviews through — Architecture / Correctness /
+     * Security for code; Accuracy / Clarity / Completeness for docs;
+     * composites for mixed. Drives the role-specific prompt prefix and is
+     * echoed back on the verdict for audit attribution. Unique within a
+     * policy (a duplicate role defeats the orthogonality purpose).
+     */
+    role: ReviewerRole;
+    /**
+     * Which agent to spawn. MAY repeat across seats when roles differ — the
+     * single-vendor case the 2026-04-23 pivot enables.
+     */
+    agent: AgentKind;
+    /**
+     * Tool names the reviewer is allowed to invoke. Typically
+     * `["Read", "Grep", "Glob"]` per the read-only reviewer invariant. Shape
+     * is agent-agnostic here; each provider enforces the sandbox in its own
+     * way:
+     * - Claude: `--allowed-tools Read,Grep,Glob` CLI flag.
+     * - Gemini: `--approval-mode plan` (Gemini's first-class read-only mode).
+     *   The `tool_allowlist` is intentionally unused by the Gemini provider;
+     *   plan mode is the sandbox contract. 2.0.x task #62 tracks adding
+     *   `--policy <tempfile>` as defense-in-depth.
+     * - Codex: `--sandbox read-only --skip-git-repo-check` flags + per-spawn
+     *   ephemeral output file.
+     */
+    tool_allowlist: string[];
+    /**
+     * Pre-rendered reviewer prompt. Engine renders per artifact type
+     * (code / docs / mixed) with a role-specific prefix prepended before
+     * calling `evaluate`.
+     */
+    prompt_template: string;
+    /**
+     * Wall-clock timeout for one reviewer's verdict. After this elapses the
+     * provider should throw `ReviewerError` with `kind: 'timeout'` and
+     * cancel the underlying process.
+     */
+    timeout_ms: number;
+    /**
+     * Optional per-reviewer model preference. `null` defers to the agent's
+     * CLI default.
+     */
+    model_hint: string | null;
+}
+/**
+ * Typed error thrown by `ReviewerProvider.evaluate`. Discriminated union
+ * matching Rust's `#[serde(tag = "kind", rename_all = "snake_case")]` enum.
+ *
+ * The engine's consensus path treats any thrown error as equivalent to a
+ * `VerdictKind::Escalate` for routing (so safety-defaults-to-escalation
+ * holds), but the distinct variants matter for the audit log and the
+ * user-facing error message.
+ */
+export type ReviewerError = {
+    /** Reviewer exceeded its `timeout_ms` budget. */
+    kind: 'timeout';
+    /** Which agent timed out (carried so the audit entry can attribute
+     *  cost / reliability back to the specific agent). */
+    agent: AgentKind;
+    /** Wall-clock ms elapsed before timeout fired. */
+    elapsed_ms: number;
+} | {
+    /** Reviewer process could not be launched (CLI missing, spawn syscall
+     *  failed, etc.). */
+    kind: 'spawn_failed';
+    agent: AgentKind;
+    /** Human-readable cause. */
+    reason: string;
+} | {
+    /** Reviewer returned but its output couldn't be parsed into a valid
+     *  verdict. Raw output is preserved for the audit log. */
+    kind: 'parse_failure';
+    agent: AgentKind;
+    /** Raw output (truncated to a reasonable length by the caller if
+     *  needed). */
+    raw_output: string;
+} | {
+    /** Reviewer was cancelled by the engine before completing (e.g.,
+     *  user abort, a sibling reviewer already hard-rejected). No
+     *  per-agent attribution because cancellation can fire on any
+     *  reviewer in flight. */
+    kind: 'cancelled';
+} | {
+    /** A reviewer's task panicked or was aborted before returning a
+     *  verdict. Mirror of the Rust `InternalJoinFailure` variant. The
+     *  variant deliberately has no `agent` field — attributing a panic
+     *  to a specific agent would be a telemetry lie. */
+    kind: 'internal_join_failure';
+    reason: string;
+};
+/**
+ * Class wrapper around a `ReviewerError` so callers can `throw` typed
+ * errors and `try { ... } catch (e) { if (e instanceof ReviewerErrorClass) {
+ * /* type-narrow on e.detail.kind *\/ } }` from JS-idiom code paths.
+ *
+ * The `.detail` property carries the discriminated union; `Error.message`
+ * is a human-readable formatting matching Rust's `#[error(...)]` strings.
+ */
+export declare class ReviewerErrorClass extends Error {
+    /** The structured error detail. Use `.kind` to narrow. */
+    readonly detail: ReviewerError;
+    constructor(detail: ReviewerError);
+}
+/**
+ * Engine's contract with reviewer implementations.
+ *
+ * **Engine owns lifecycle:** implementations must spawn, await verdict,
+ * enforce timeout, cancel, and capture logs internally. The engine calls
+ * `evaluate` and awaits — it never holds a handle that could outlive the
+ * call.
+ *
+ * Errors are thrown as `ReviewerErrorClass` instances; callers narrow via
+ * the `.detail.kind` discriminator.
+ */
+export interface ReviewerProvider {
+    /**
+     * Spawn one reviewer per the spec, collect its verdict, enforce timeout.
+     *
+     * @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`.
+     * @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>;
+}

package/dist/reviewer/providers/__tests__/claude-live-smoke.test.d.ts

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

package/dist/reviewer/providers/__tests__/claude.test.d.ts

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

package/dist/reviewer/providers/__tests__/codex-live-smoke.test.d.ts

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

package/dist/reviewer/providers/__tests__/codex.test.d.ts

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

package/dist/reviewer/providers/__tests__/gemini-live-smoke.test.d.ts

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

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

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