@quantiya/codevibe-claude-plugin 1.0.36 → 1.0.37

package/node_modules/@quantiya/codevibe-core/dist/orchestration/setup-types.d.ts

@@ -0,0 +1,140 @@
+import type { ReviewerRole as PolicyReviewerRole } from '../reviewer/types.js';
+import type { AgentKind } from '../reviewer/types.js';
+import { AgentType } from '../types/session.js';
+import { ReviewerRole as SchemaReviewerRole } from '../types/reviewer.js';
+/**
+ * Tier returned by `getSubscriptionStatus`. Drives seat budget +
+ * tier-gate at bootstrap.
+ *
+ * UPPERCASE wire format matches `codevibe-backend/graphql/schema.graphql:209`
+ * (`enum SubscriptionTier { FREE PRO MAX }`).
+ */
+export type WizardTier = 'FREE' | 'PRO' | 'MAX';
+/**
+ * Tier-aware seat budget. Mirrors
+ * `codevibe-backend/lambda/user-management/index.ts:184-188`'s
+ * `REVIEWER_SEAT_COUNT` map. Free has no seats — orchestration is not
+ * permitted at that tier; the wizard short-circuits at bootstrap with
+ * the §6 upgrade interstitial.
+ */
+export declare const SEAT_BUDGET: Record<WizardTier, number | null>;
+/**
+ * The 3-role lock from PHASE-3-A-DESIGN.md: the wizard offers ONLY
+ * `architecture` / `correctness` / `security`. The schema's
+ * `ReviewerRole` enum at `codevibe-backend/graphql/schema.graphql:167-177`
+ * still has 9 variants for backward compat / 2.0.x custom-roles
+ * (#80) — but the wizard NEVER sends a non-3-role seat to
+ * `updateReviewerPolicy`.
+ *
+ * snake_case matches `codevibe-core/src/reviewer/types.ts:52-61` (the
+ * reviewer-module wire). The wizard converts to AppSync UPPERCASE at
+ * the save boundary via `roleToAppSync()`.
+ */
+export declare const WIZARD_ROLES: readonly ["architecture", "correctness", "security"];
+export type WizardRole = (typeof WIZARD_ROLES)[number];
+/**
+ * Tier-aware default role for each seat (§1 "Default-role fallback").
+ * Seat 0 = architecture, Seat 1 = correctness, Seat 2 = security.
+ * When the canonical default is already taken by a previous seat, the
+ * wizard falls back to the first remaining role in canonical order.
+ */
+export declare const DEFAULT_ROLE_BY_SEAT: WizardRole[];
+/**
+ * Canonical agent ordering used for wizard defaults. The first
+ * installed agent in this order is the default for each seat unless
+ * the user picks otherwise.
+ */
+export declare const AGENT_PRIORITY: AgentKind[];
+/**
+ * The wizard's terminal outcomes. Drives `wizard_completed` /
+ * `wizard_aborted` GA4 events and the exit code.
+ */
+export type WizardOutcome = {
+    kind: 'ok';
+    saved: true;
+    seats: ReadonlyArray<WizardSeatPick>;
+} | {
+    kind: 'saved_after_test_warning';
+    saved: true;
+    seats: ReadonlyArray<WizardSeatPick>;
+} | {
+    kind: 'aborted';
+    reason: WizardAbortReason;
+    lastStep: WizardStep;
+};
+/**
+ * Reasons the wizard exited without saving. Mirror the
+ * `wizard_aborted.reason` taxonomy in PHASE-3-A-DESIGN.md §7.
+ */
+export type WizardAbortReason = 'ctrl_c' | 'tier_gate_free' | 'no_clis' | 'step_user_exit' | 'step_save_failed_exit' | 'auth_expired' | 'bootstrap_failure';
+/**
+ * Wizard step taxonomy — used for `wizard_step_started`/`completed`/
+ * `failed` and `wizard_aborted.last_step`.
+ */
+export type WizardStep = 'bootstrap' | 'seat_assignment' | 'test_my_agents' | 'save';
+/**
+ * Per-step `wizard_step_failed.reason` codes. Mirror the table in
+ * PHASE-3-A-DESIGN.md §7. Each step has its own bounded reason set;
+ * `seat_assignment` has no failure modes (the picker filters out
+ * invalid choices UI-side).
+ */
+export type WizardStepFailureReason = 'tier_gate_free' | 'not_signed_in' | 'subscription_status_network' | 'no_clis_installed' | 'test_revise' | 'test_reject' | 'test_escalate' | 'test_parse_failure' | 'test_spawn_failure' | 'test_timeout' | 'update_policy_network' | 'update_policy_5xx' | 'update_policy_throttle' | 'auth_token_expired';
+/**
+ * One seat the user picked in Step 1. The wizard converts these to
+ * `ReviewerAgentSpecInput[]` at save time by uppercase-mapping role +
+ * agent (the schema's wire form).
+ */
+export interface WizardSeatPick {
+    seatId: number;
+    agent: AgentKind;
+    role: WizardRole;
+}
+/**
+ * Latency bucket for GA4 `latency_bucket_s` / `total_latency_bucket_s`
+ * dimensions. Bounded set — keeps GA4 cardinality tractable per R2
+ * round-1 MEDIUM (PHASE-3-A-DESIGN.md §7).
+ */
+export type LatencyBucket = '<2' | '2-5' | '5-10' | '10-30' | '30+';
+/**
+ * Categorical bucket for "how many agents are installed" /
+ * "how many seats". Locked at "1" / "2" / "3" — there is no "4+"
+ * because Max is the ceiling.
+ */
+export type CountBucket = '1' | '2' | '3';
+/**
+ * Entry point identifier — distinguishes meta CLI invocation from
+ * each plugin's alias (`codevibe-{claude,gemini,codex} orchestration setup`).
+ */
+export type WizardEntry = 'meta_cli' | 'claude_alias' | 'gemini_alias' | 'codex_alias';
+/**
+ * Bucket a wall-clock duration into one of the 5 latency-bucket values.
+ * Used by telemetry for per-step + total-wizard timing dimensions.
+ */
+export declare function bucketLatencySeconds(seconds: number): LatencyBucket;
+/**
+ * Bucket an integer count into "1" / "2" / "3", clamping anything
+ * higher to "3". Used for `seats_bucket`, `agents_distinct_bucket`,
+ * `roles_distinct_bucket`, `installed_agents_bucket`.
+ */
+export declare function bucketCount(n: number): CountBucket;
+/**
+ * Map a wizard role (snake_case) to the reviewer-module's snake_case
+ * `ReviewerRole` literal type — used when building a `ReviewerSpec`
+ * for `createSubprocessReviewerRegistry().evaluate()`. Pass-through
+ * because `WizardRole` is a strict subset of `PolicyReviewerRole`.
+ */
+export declare function roleToReviewerSpec(role: WizardRole): PolicyReviewerRole;
+/**
+ * Map a wizard role (snake_case) to the AppSync schema's UPPERCASE
+ * `ReviewerRole` enum — used when building a `ReviewerAgentSpecInput`
+ * for the `updateReviewerPolicy` mutation. The wizard locks to 3
+ * roles, so this mapping is exhaustive over `WizardRole` and never
+ * produces one of the 6 non-3-role variants.
+ */
+export declare function roleToAppSync(role: WizardRole): SchemaReviewerRole;
+/**
+ * Map AgentKind (lowercase reviewer-module wire) to the AppSync
+ * `AgentType` enum (UPPERCASE). Used at save time when building the
+ * `ReviewerAgentSpecInput[]` for `updateReviewerPolicy`.
+ */
+export declare function agentToAppSync(agent: AgentKind): AgentType;

package/node_modules/@quantiya/codevibe-core/dist/orchestration/setup-wizard.d.ts

@@ -0,0 +1,57 @@
+import { DetectableAgent } from './detect-agents.js';
+import { WizardEntry } from './setup-types.js';
+import { PickerIO } from './setup-seat-picker.js';
+import { AppSyncClient } from '../appsync/appsync-client.js';
+import type { ReviewerSpec, ReviewerVerdict } from '../reviewer/index.js';
+/**
+ * Parse `--entry=<value>` from argv. Defaults to `meta_cli` if absent
+ * or invalid. Plugin wrappers pass `--entry=claude_alias` /
+ * `gemini_alias` / `codex_alias` per the §4 alias contract.
+ */
+export declare function parseEntry(argv: string[]): WizardEntry;
+/**
+ * Injectable dependencies for `runSetupWizardWithDeps`. Factored out
+ * so unit tests can drive the whole state machine deterministically
+ * (no real readline, no real subprocess spawn, no real network).
+ *
+ * Production callers use `runSetupWizard`, which wires the production
+ * deps + calls `process.exit(result.exitCode)`.
+ */
+export interface SetupWizardDeps {
+    /** Builds an authenticated AppSyncClient or returns null if unauthenticated. */
+    clientFactory: () => Promise<AppSyncClient | null>;
+    /** Returns the subset of agents present on PATH. */
+    agentDetector: () => DetectableAgent[];
+    /** Optional reviewer registry (Step 2). Default: real subprocess registry. */
+    registryFactory?: () => {
+        evaluate: (spec: ReviewerSpec, gateId: string) => Promise<ReviewerVerdict>;
+    };
+    /** Output writer — writes the line as-is (caller controls newlines). */
+    write: (line: string) => void;
+    /** Build a fresh PickerIO + close handle for the next interactive prompt. */
+    createPickerIO: () => {
+        io: PickerIO;
+        close: () => void;
+    };
+}
+/**
+ * Result of the wizard's state machine. The public `runSetupWizard`
+ * wrapper translates this to a `process.exit(exitCode)`.
+ */
+export interface SetupWizardResult {
+    exitCode: number;
+}
+/**
+ * Production entry point. Called from `runOrchestrationCli` when
+ * `argv[3] === 'setup'`. Builds production deps + calls process.exit
+ * with the wizard's exit code. Drives the full state machine via
+ * `runSetupWizardWithDeps`.
+ */
+export declare function runSetupWizard(argv: string[]): Promise<void>;
+/**
+ * Testable wizard core. Exits with code 0 on success or any user-
+ * initiated abort; exit 1 on a failure the user couldn't recover
+ * from in the recourse loop. SIGINT is registered + cleaned up
+ * around the call (no-op for tests when SIGINT is never fired).
+ */
+export declare function runSetupWizardWithDeps(argv: string[], deps: SetupWizardDeps): Promise<SetupWizardResult>;

package/node_modules/@quantiya/codevibe-core/dist/orchestration/v1-options.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Discriminator value emitted by the engine on
+ * `metadata.prompt_kind` for orchestration-escalated gate prompts.
+ *
+ * Sources of truth (any drift breaks the V1 bridge):
+ *   - Engine emit: codevibe-core-rs `appsync_emit.rs:847-862`
+ *     (`build_metadata_json` — emits exactly 5 keys: `tool_name`,
+ *     `payload`, `prompt_kind`, `summary`, `timeline`).
+ *   - iOS branch: MessageBubble.swift `extractInteractivePromptOptions`.
+ *   - Android branch: MessageBubble.kt `extractOptions`.
+ */
+export declare const V1_ORCHESTRATION_PROMPT_KIND: "orchestration_escalated_gate";
+/**
+ * V1 user-decision kind (3-position subset of the 5-kind enum).
+ *
+ * Lowercase snake_case matches `@quantiya/quorum-core`'s `UserDecisionKind`
+ * caller-facing type at `codevibe-core-rs/packages/quorum-core/src/types.ts:232-238`.
+ * The quorum-core SDK's `applyUserDecision` mutator accepts this lowercase
+ * form and internally uppercases via `toWireEnum` before AppSync wire-send
+ * (`client.ts:244-246` + line 474). Plugins pass lowercase; the SDK is the
+ * conversion layer.
+ *
+ * iOS + Android pin UPPERCASE in their own enums because they call AppSync
+ * GraphQL directly via Amplify (no SDK conversion layer in their path).
+ * Both are correct at their respective layers.
+ *
+ * The two `_WITH_NOTES` variants from the full 5-kind enum are V2 — they
+ * require a `notes: EncryptedPayloadInput` value alongside the kind, and
+ * V1's "type a number" UX has no notes-input surface. They are deliberately
+ * EXCLUDED from this union; `mapOptionNumberToUserDecisionKind` cannot
+ * return them.
+ */
+export type V1UserDecisionKind = 'accept' | 'reject_restart' | 'abort_task';
+/**
+ * One row of the V1 orchestration option table.
+ *
+ * `number` is a string (`"1"` / `"2"` / `"3"`) to match iOS' tuple shape
+ * `(number: String, text: String)` and the existing
+ * `InteractivePromptOption` shape elsewhere in the mobile renderers.
+ */
+export interface V1OrchestrationOption {
+    readonly number: string;
+    readonly label: string;
+    readonly kind: V1UserDecisionKind;
+}
+/**
+ * The V1 hardcoded 3-position option table.
+ *
+ * Order is LOAD-BEARING — `V1_ORCHESTRATION_OPTIONS[i].kind` is the kind
+ * sent to the server when the user types option-number `i+1`. Drift from
+ * iOS / Android = wrong `UserDecisionKind` on the wire (engine has no
+ * server-side validation).
+ *
+ *   position 1 -> accept          -> "Accept"
+ *   position 2 -> reject_restart  -> "Reject (restart proposal)"
+ *   position 3 -> abort_task      -> "Abort task"
+ *
+ * (Kind values are lowercase to match the SDK caller-facing type — see
+ * the header comment on the SDK conversion layer. iOS + Android pin
+ * UPPERCASE in their own constant tables because they hit AppSync
+ * directly without the SDK.)
+ *
+ * Frozen with `as const` so callers cannot mutate the array nor swap
+ * entries in place at runtime.
+ */
+export declare const V1_ORCHESTRATION_OPTIONS: readonly [
+    V1OrchestrationOption,
+    V1OrchestrationOption,
+    V1OrchestrationOption
+];
+/**
+ * Map a 1-based option number typed by the user to the matching V1
+ * `UserDecisionKind`. Returns `null` for ANY number outside 1..3 —
+ * callers MUST surface an error and abort the submit on null (the
+ * engine would reject `_WITH_NOTES` kinds without a notes payload in
+ * V1, and ANY out-of-range number means the user hit a typo, an
+ * accidental keystroke, or a malformed prompt).
+ *
+ * Out-of-range MUST return null — NOT fall back to `ACCEPT` or any
+ * default. A silent fallback would silently destroy or accept the
+ * user's work without their consent. Pinned by the
+ * `out-of-range returns null` test.
+ *
+ * @param optionNumber 1-based option position as typed by the user.
+ * @returns The matching `V1UserDecisionKind`, or `null` when out of range.
+ */
+export declare function mapOptionNumberToUserDecisionKind(optionNumber: number): V1UserDecisionKind | null;
+/**
+ * Shorter alias of `mapOptionNumberToUserDecisionKind`. Matches the helper
+ * name used in `PHASE-3-B-MOBILE-V1-BRIDGE-DESIGN.md` §3.1 + §6 Test 9 +
+ * §8 source-map row (`mapOptionToUserDecisionKind`). Both names point at
+ * the same function — pick whichever reads cleaner at the call site.
+ *
+ * Plugins can `import { mapOptionToUserDecisionKind }` per the design
+ * doc's call-site example at §3.1.
+ */
+export declare const mapOptionToUserDecisionKind: typeof mapOptionNumberToUserDecisionKind;
+/**
+ * Lowercase-to-uppercase conversion: `V1UserDecisionKind` (caller-facing,
+ * matches `@quantiya/quorum-core` SDK) → `UserDecisionKind` wire enum
+ * (matches AppSync schema). Plugins that call `AppSyncClient.applyUserDecision`
+ * directly (no SDK in path) use this helper to bridge the V1 option table's
+ * lowercase kind to the wire form.
+ *
+ * Total over the 3 V1 kinds — never returns null for a valid
+ * `V1UserDecisionKind` input.
+ */
+export declare function mapV1KindToWire(kind: V1UserDecisionKind): 'ACCEPT' | 'REJECT_RESTART' | 'ABORT_TASK';

package/node_modules/@quantiya/codevibe-core/dist/reviewer/__tests__/integration.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/reviewer/__tests__/mocks.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/reviewer/__tests__/output-parser.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/reviewer/__tests__/registry.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/reviewer/__tests__/subprocess.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/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/node_modules/@quantiya/codevibe-core/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/node_modules/@quantiya/codevibe-core/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/node_modules/@quantiya/codevibe-core/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/node_modules/@quantiya/codevibe-core/dist/reviewer/providers/__tests__/claude-live-smoke.test.d.ts

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