@quantiya/codevibe-claude-plugin 1.0.36 → 1.0.37

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

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

package/node_modules/@quantiya/codevibe-core/dist/reviewer/providers/__tests__/codex-live-smoke.test.d.ts

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

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

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

package/node_modules/@quantiya/codevibe-core/dist/reviewer/providers/__tests__/gemini-live-smoke.test.d.ts

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

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

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

package/node_modules/@quantiya/codevibe-core/dist/reviewer/providers/claude.d.ts

@@ -0,0 +1,59 @@
+import { type ReviewerProvider, type ReviewerSpec } from '../provider.js';
+import { type SubprocessOutcome } from '../subprocess.js';
+import type { ReviewerVerdict } from '../types.js';
+/**
+ * Built command shape — split out so tests can inspect args / env without
+ * spawning a process. `runReviewer` consumes this shape directly.
+ */
+export interface BuiltCommand {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+}
+/** Construction options. */
+export interface ClaudeReviewerProviderOptions {
+    /** Override the `claude` executable path. Production callers pass nothing
+     *  (PATH lookup); integration tests can stub Claude with a shell-script
+     *  fixture. */
+    executable?: string;
+}
+/**
+ * Real Claude Code reviewer provider. Wraps the `claude` CLI.
+ *
+ * Construct with `new ClaudeReviewerProvider()` for the standard `claude`
+ * binary, or `new ClaudeReviewerProvider({ executable: '/opt/bin/mock-claude' })`
+ * for tests that point at a fixture CLI on a controlled PATH.
+ */
+export declare class ClaudeReviewerProvider implements ReviewerProvider {
+    private readonly executable;
+    constructor(opts?: ClaudeReviewerProviderOptions);
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}
+/**
+ * Construct the Claude CLI invocation. Split out from `evaluate` so unit
+ * tests can assert on the built arg list + env without actually spawning a
+ * process.
+ *
+ * Locked flag set:
+ * - `--print` — non-interactive mode; emit the response and exit, rather
+ *   than waiting for further turns. Required so the subprocess actually
+ *   terminates on its own.
+ * - `--allowed-tools <CSV>` — design-locked sandbox. `ReviewerSpec.tool_allowlist`
+ *   is populated from the engine's policy; the provider trusts the spec
+ *   rather than hard-coding the list.
+ * - `--model <hint>` — optional; omitted when `spec.model_hint` is `null`,
+ *   deferring to Claude's default.
+ *
+ * # QUORUM_REVIEWER_SUBPROCESS env var
+ *
+ * Set unconditionally to `'1'` in the child's environment. See module docs
+ * for the rationale and why `--bare` was rejected as the primary defense.
+ */
+export declare function buildCommand(executable: string, spec: ReviewerSpec): 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;

package/node_modules/@quantiya/codevibe-core/dist/reviewer/providers/codex.d.ts

@@ -0,0 +1,67 @@
+import { type ReviewerProvider, type ReviewerSpec } from '../provider.js';
+import { type SubprocessOutcome } from '../subprocess.js';
+import type { ReviewerVerdict } from '../types.js';
+import type { BuiltCommand } from './claude.js';
+/** Construction options. */
+export interface CodexReviewerProviderOptions {
+    /** Override the `codex` executable path. Production callers pass nothing
+     *  (PATH lookup); integration tests can stub Codex with a shell-script
+     *  fixture. */
+    executable?: string;
+}
+/**
+ * Real Codex CLI reviewer provider. Wraps the `codex exec` subcommand.
+ */
+export declare class CodexReviewerProvider implements ReviewerProvider {
+    private readonly executable;
+    constructor(opts?: CodexReviewerProviderOptions);
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}
+/**
+ * Construct the Codex CLI invocation. Split out from `evaluate` so unit
+ * tests can assert on the built arg list without actually spawning a
+ * process.
+ *
+ * Locked flag set:
+ * - `exec` — the non-interactive subcommand (the interactive default
+ *   would block forever waiting for user input).
+ * - `--sandbox read-only` — design-locked read-only sandbox.
+ * - `--skip-git-repo-check` — reviewer subprocesses must run in any cwd,
+ *   not just git working trees.
+ * - `--color never` — strip ANSI escapes from any incidental stdout
+ *   output (the JSONL stream is not affected, but logs and error
+ *   messages are).
+ * - `--json` — emit JSONL events to stdout for token-count parsing.
+ * - `--ephemeral` — do NOT write a session JSONL under
+ *   `~/.codex/sessions/`.
+ * - `--output-last-message <path>` — write the model's final agent
+ *   message verbatim to `path`.
+ * - `--model <hint>` — optional; omitted when `spec.model_hint` is `null`.
+ * - `-` (final arg) — read prompt from stdin.
+ */
+export declare function buildCommand(executable: string, spec: ReviewerSpec, lastMessagePath: string): 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;
+/**
+ * Sum `usage.input_tokens + usage.output_tokens` across every
+ * `turn.completed` JSONL event in `stdout`. Returns `null` when no
+ * `turn.completed` event reported any token count, so dashboards can
+ * distinguish "no data" from a real zero.
+ *
+ * Lenient: malformed JSONL lines are silently skipped (Codex's stream is
+ * designed to be append-only, so partial flushes during timeout could
+ * leave a final truncated line).
+ */
+export declare function sumCodexTokens(stdout: string): number | null;
+/**
+ * Generate a unique-per-spawn path for `--output-last-message`. Lives in
+ * 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.
+ */
+export declare function makeLastMessagePath(): string;

package/node_modules/@quantiya/codevibe-core/dist/reviewer/providers/common.d.ts

@@ -0,0 +1,25 @@
+import type { AgentKind } from '../types.js';
+import type { ReviewerError } from '../provider.js';
+import type { SubprocessError } from '../subprocess.js';
+/**
+ * Map a subprocess-layer error into a `ReviewerError` for the given agent.
+ * Mirrors Rust's `providers::claude::map_subprocess_error` byte-for-byte:
+ *
+ * - `spawn_failed` → `ReviewerError::SpawnFailed { agent, reason }`
+ * - `timeout` → `ReviewerError::Timeout { agent, elapsed_ms }`
+ * - `io` → `ReviewerError::SpawnFailed { agent, reason: "io error: <msg>" }`
+ *   (deliberate; an IO failure during spawn is a spawn failure from the
+ *   audit log's perspective — the reviewer never produced a verdict)
+ * - `cancelled` → `ReviewerError` cancelled (no agent attribution; the
+ *   Rust enum omits the agent field on Cancelled because cancellation
+ *   can fire on any reviewer in flight)
+ *
+ * The Rust source's `map_subprocess_error` handles only three variants
+ * (`SpawnFailed`, `Timeout`, `Io`) because the Rust subprocess layer
+ * doesn't have a Cancelled variant — engine-driven cancellation in Rust
+ * is handled at a higher layer via `tokio::select!` against the abort
+ * future, never surfacing as a `SubprocessError`. The TS port carries
+ * cancellation in the subprocess layer (via `AbortSignal`), so we
+ * include it here.
+ */
+export declare function mapSubprocessError(agent: AgentKind, err: SubprocessError): ReviewerError;

package/node_modules/@quantiya/codevibe-core/dist/reviewer/providers/gemini.d.ts

@@ -0,0 +1,108 @@
+import { type ReviewerProvider, type ReviewerSpec } from '../provider.js';
+import { type SubprocessOutcome } from '../subprocess.js';
+import type { ReviewerVerdict } from '../types.js';
+import type { BuiltCommand } from './claude.js';
+/** Construction options. */
+export interface GeminiReviewerProviderOptions {
+    /** Override the `gemini` executable path. Production callers pass nothing
+     *  (PATH lookup); integration tests can stub Gemini with a shell-script
+     *  fixture. */
+    executable?: string;
+}
+/**
+ * JSON envelope shape emitted by `gemini --output-format json`. We only care
+ * about `response`; the other fields (`session_id`, `stats`) are consumed by
+ * the JSON deserializer but not surfaced on `ReviewerVerdict` directly.
+ *
+ * Tolerates missing or extra top-level keys for cross-version compatibility.
+ */
+export interface GeminiEnvelope {
+    response: string;
+    /** Gemini 0.38.2 emits this; older versions may not. */
+    session_id?: string;
+    stats?: GeminiStats;
+}
+export interface GeminiStats {
+    /** Map of model name → per-model stats. Token usage MUST be summed across
+     *  every entry (R2 "telemetry timebomb" lesson — picking an arbitrary one
+     *  via `Object.values()[0]` would under-report when Gemini reports
+     *  auxiliary models). */
+    models?: Record<string, GeminiModelStats>;
+}
+export interface GeminiModelStats {
+    tokens?: {
+        /** Prompt + response tokens combined. Populated by Gemini's
+         *  `stats.models.<name>.tokens.total`; used for cost telemetry. */
+        total?: number;
+    };
+}
+/**
+ * Real Gemini CLI reviewer provider. Wraps the `gemini` binary.
+ */
+export declare class GeminiReviewerProvider implements ReviewerProvider {
+    private readonly executable;
+    constructor(opts?: GeminiReviewerProviderOptions);
+    evaluate(spec: ReviewerSpec, gateId: string): Promise<ReviewerVerdict>;
+}
+/**
+ * Construct the Gemini CLI invocation. Split out from `evaluate` so unit
+ * tests can assert on the built arg list + env without actually spawning a
+ * process.
+ *
+ * Locked flag set:
+ * - `-p ''` — non-interactive mode, empty inline prompt so the full prompt
+ *   is read from stdin (consistent with Claude path).
+ * - `--approval-mode plan` — read-only sandbox.
+ * - `--output-format json` — structured reply envelope that survives
+ *   user-hook stdout pollution.
+ * - `--model <hint>` — optional; omitted when `spec.model_hint` is `null`.
+ *
+ * `spec.tool_allowlist` is **intentionally unused** for Gemini. Plan mode
+ * is the design-locked sandbox; mapping the Claude-style allowlist to
+ * Gemini's (deprecated) `--allowed-tools` flag would hit the known
+ * non-interactive bugs flagged in the module docs.
+ *
+ * # QUORUM_REVIEWER_SUBPROCESS env var
+ *
+ * Set unconditionally to `'1'` in the child's environment. The user's
+ * Gemini plugin checks this at the top of `hooks/common.sh` and
+ * short-circuits every hook — without this gate, reviewer spawns would
+ * each create a new backend session and mark the user's primary Gemini
+ * session INACTIVE (empirically observed 2026-04-21 during Phase 2c.2
+ * local testing).
+ */
+export declare function buildCommand(executable: string, spec: ReviewerSpec): 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;
+/**
+ * Parse the FIRST complete JSON object in `stdout`, discarding any trailing
+ * bytes. User-level hooks (e.g., CodeVibe's own Gemini plugin hooks
+ * installed in `~/.gemini/settings.json`) append log lines to stdout AFTER
+ * the model's reply envelope. This walks the text byte-by-byte tracking
+ * brace depth + string escapes to find where the first JSON object ends,
+ * then `JSON.parse` that slice — the equivalent of Rust's
+ * `serde_json::Deserializer::into_iter().next()` for our purposes.
+ *
+ * Returns `null` if stdout contains no valid JSON value at all, the
+ * extracted slice fails strict JSON parsing, OR the parsed value isn't a
+ * shape-conformant `GeminiEnvelope` (i.e. missing or non-string
+ * `response`). The caller routes any of these to ParseFailure with raw
+ * stdout — matching Rust's serde-deserialization-failure path.
+ *
+ * # Why runtime shape validation
+ *
+ * Rust's `serde_json::Deserializer` rejects `{}` or `{"response":123}`
+ * during deserialization because `GeminiEnvelope { response: String, ... }`
+ * makes the field required at the type-system layer. TypeScript's
+ * `JSON.parse(slice) as GeminiEnvelope` is a compile-time-only assertion
+ * with no runtime check, so we reproduce serde's behavior with an
+ * explicit `validateGeminiEnvelope` step. Without this, a syntactically-
+ * valid-but-shape-bad envelope would land an `undefined.replace()`
+ * TypeError up the call stack instead of a structured ParseFailure
+ * (R1 finding on Phase 2f.1.b round 1).
+ */
+export declare function parseFirstJsonEnvelope(stdout: string): GeminiEnvelope | null;

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

@@ -0,0 +1,87 @@
+import { type ReviewerProvider, type ReviewerSpec } from './provider.js';
+import type { AgentKind, ReviewerVerdict } from './types.js';
+/**
+ * Per-agent reviewer dispatch.
+ *
+ * Build with the fluent `with()` builder for the common production
+ * case (register all known agents up front), or the mutating
+ * `register()` helper when the set is determined at runtime.
+ * `providerFor` exposes the underlying provider for callers (e.g.,
+ * test harnesses) that need direct access without going through the
+ * `evaluate` method.
+ *
+ * `ReviewerRegistry` itself implements `ReviewerProvider` so it
+ * slots into anything that takes a single provider — including
+ * another `ReviewerRegistry`. (Compose-of-compose works for free.)
+ */
+export declare class ReviewerRegistry implements ReviewerProvider {
+    private readonly providers;
+    /**
+     * Builder-style register: returns `this` with `agent` mapped to
+     * `provider`. Intended for the production "register all three at
+     * startup" pattern:
+     *
+     * ```ts
+     * const registry = new ReviewerRegistry()
+     *   .with('claude', new ClaudeReviewerProvider())
+     *   .with('gemini', new GeminiReviewerProvider())
+     *   .with('codex',  new CodexReviewerProvider());
+     * ```
+     *
+     * Re-registering the same agent overwrites the previous provider —
+     * useful for tests that swap in a fixture provider after construction.
+     */
+    with(agent: AgentKind, provider: ReviewerProvider): this;
+    /**
+     * Mutating register. Equivalent to `with()` but returns void; use
+     * when chaining isn't readable (e.g., conditional registration in
+     * a loop).
+     */
+    register(agent: AgentKind, provider: ReviewerProvider): void;
+    /**
+     * Lookup the provider for `agent`. Returns `undefined` if no
+     * provider is registered. Callers should prefer using the
+     * `evaluate` method on the registry itself, which handles the
+     * missing-provider case as a typed `ReviewerError`. This method
+     * is exposed for test harnesses that need direct provider access
+     * (e.g., to call provider methods that aren't part of the
+     * interface).
+     */
+    providerFor(agent: AgentKind): ReviewerProvider | undefined;
+    /**
+     * Returns the set of agents that have registered providers, in
+     * insertion order. Useful for callers that want to log the
+     * configured registry shape or for a future startup-time validator
+     * that checks the policy snapshot's reviewer_agents are all covered.
+     */
+    registeredAgents(): AgentKind[];
+    /**
+     * Dispatch by `spec.agent` to the registered provider. If no
+     * provider is registered for that agent, throw
+     * `ReviewerErrorClass` with `kind: 'spawn_failed'` so the engine's
+     * 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>;
+}
+/**
+ * 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
+ * `withSubprocessProviders()` napi factory.
+ *
+ * Plugins call this once at startup and hand the registry to the
+ * engine fan-out path. Inert registrations cost nothing — no
+ * subprocess fires until the policy actually references that agent.
+ *
+ * For tests / dev environments that need to override binary paths,
+ * construct the providers manually:
+ *
+ * ```ts
+ * const registry = new ReviewerRegistry()
+ *   .with('claude', new ClaudeReviewerProvider({ executable: '/opt/bin/claude' }))
+ *   .with('gemini', new GeminiReviewerProvider({ executable: '/opt/bin/gemini' }))
+ *   .with('codex',  new CodexReviewerProvider({  executable: '/opt/bin/codex' }));
+ * ```
+ */
+export declare function createSubprocessReviewerRegistry(): ReviewerRegistry;

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

@@ -0,0 +1,117 @@
+/**
+ * Successful subprocess run. Exit status may still be failure (non-zero
+ * code); the caller decides whether to treat that as a reviewer spawn error
+ * or as a parse failure with whatever stdout it produced.
+ */
+export interface SubprocessOutcome {
+    /** Captured stdout decoded as UTF-8. Reviewers that emit non-UTF-8 are
+     *  misbehaving by contract; lossy decode keeps the parser running rather
+     *  than returning an IO error for what is really a "reviewer is broken"
+     *  scenario. */
+    stdout: string;
+    /** Captured stderr (same lossy-decode policy). Surfaced to callers so
+     *  audit records can include it. */
+    stderr: string;
+    /** Wall-clock milliseconds from `spawn()` to exit. Populated even on
+     *  non-zero exit because per-reviewer latency is a cost / reliability
+     *  telemetry input. */
+    elapsed_ms: number;
+    /** Whether the process exited with status 0. Separate from the stdout
+     *  contents — a reviewer that printed its verdict and then crashed on
+     *  shutdown is still "failed" from an audit perspective even if the
+     *  verdict parses cleanly. */
+    exit_success: boolean;
+}
+/**
+ * Subprocess-layer errors. Discriminated union; callers (per-agent
+ * providers) map these into `ReviewerError` with their own `AgentKind`.
+ */
+export type SubprocessError = {
+    /** The child process could not be spawned at all (binary not on
+     *  PATH, permission denied, fork/exec failed). */
+    kind: 'spawn_failed';
+    reason: string;
+} | {
+    /** The child exceeded its `timeout_ms` budget. The child has been
+     *  (or will be) killed via SIGKILL by the time this error is
+     *  returned. */
+    kind: 'timeout';
+    /** The timeout budget in ms, for telemetry. */
+    elapsed_ms: number;
+} | {
+    /** A non-timeout IO failure occurred while running the subprocess
+     *  (stdin write failed, stdout read failed, etc.). */
+    kind: 'io';
+    reason: string;
+} | {
+    /** Caller signalled abort via the `signal` option before the child
+     *  exited. The child has been killed via SIGKILL. Distinct from
+     *  `timeout` so the audit log can attribute "reviewer cancelled by
+     *  engine" separately from "reviewer ran past budget." */
+    kind: 'cancelled';
+};
+/** Class wrapper so callers can `throw`/`catch` typed errors. */
+export declare class SubprocessErrorClass extends Error {
+    readonly detail: SubprocessError;
+    constructor(detail: SubprocessError);
+}
+/**
+ * Inputs to `runReviewer`. Callers (per-agent providers) build this struct
+ * with their agent-specific binary + args + env, then hand off lifecycle
+ * management to this module.
+ */
+export interface RunReviewerOptions {
+    /** Path or command name to spawn. */
+    command: string;
+    /** Arguments to pass to the command. */
+    args: readonly string[];
+    /**
+     * Environment variables to set. **MUST include
+     * `QUORUM_REVIEWER_SUBPROCESS: '1'`** — this is the plugin-isolation env
+     * guard that prevents reviewer hook fires from evicting the user's
+     * 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.
+     */
+    env: NodeJS.ProcessEnv;
+    /** Working directory; falls back to `process.cwd()`. */
+    cwd?: string;
+    /**
+     * Prompt to write to the child's stdin. Always followed by stdin EOF.
+     * Most reviewer CLIs finish reading the prompt then begin emitting
+     * output — a reviewer that blocks on a stuck stdin pipe is the §3.1
+     * test scenario.
+     */
+    prompt: string;
+    /**
+     * Wall-clock timeout (ms) bounding the whole spawn-to-exit window,
+     * INCLUDING the stdin write. This is the load-bearing detail per §3.1:
+     * an earlier (Rust v1) implementation wrapped only the wait-for-exit,
+     * which let a child that refused to drain stdin block the parent in
+     * pipe-full back-pressure indefinitely. Wrapping write+wait under one
+     * timeout is the fix.
+     */
+    timeout_ms: number;
+    /**
+     * Optional `AbortSignal` for engine-driven cancellation (e.g., user
+     * abort, sibling reviewer hard-rejecting). Aborting after a clean exit
+     * is a no-op; aborting mid-flight teardown is a `cancelled` error.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Run a preconfigured command as a reviewer subprocess.
+ *
+ * Contract:
+ * - Stdin, stdout, stderr are piped (caller cannot override; output capture
+ *   is the whole purpose of the call).
+ * - `prompt` is written to the child's stdin then stdin is closed (EOF).
+ * - The whole spawn → write-stdin → wait-for-exit lifecycle races against
+ *   `timeout_ms` AND any `signal` abort. On timeout / abort the streams
+ *   are explicitly destroyed and the child is SIGKILL'd before throwing.
+ *
+ * Throws `SubprocessErrorClass` on failure; the `.detail.kind` discriminator
+ * tells the caller which path tripped (`spawn_failed` / `timeout` / `io` /
+ * `cancelled`).
+ */
+export declare function runReviewer(opts: RunReviewerOptions): Promise<SubprocessOutcome>;

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

@@ -0,0 +1,101 @@
+/**
+ * Three 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.
+ */
+export type AgentKind = 'claude' | 'gemini' | 'codex';
+/**
+ * Review lens a reviewer seat evaluates through.
+ *
+ * snake_case wire format matches `codevibe_policy::ReviewerRole`'s
+ * `#[serde(rename_all = "snake_case")]` attribute, locked in Phase 2f.0.a.1.
+ * **Append-only post-launch** — these strings are cryptographically bound
+ * into the audit hash chain once used. Renaming or removing a value would
+ * break chain verification on every prior entry. Adding new values is fine
+ * (Custom roles slipped to 2.0.1 per the locked design).
+ *
+ * Code-artifact lenses: architecture, correctness, security.
+ * Docs-artifact lenses: accuracy, clarity, completeness.
+ * Mixed-artifact composite lenses: architecture_and_accuracy,
+ *   correctness_and_clarity, security_and_completeness.
+ *
+ * The AppSync-facing `ReviewerRole` enum in `src/types/reviewer.ts` uses
+ * UPPERCASE GraphQL convention; this snake_case version is for the Rust
+ * engine wire. Translation between the two layers is the AppSync resolver's
+ * job, not the reviewer module's.
+ */
+export type ReviewerRole = 'architecture' | 'correctness' | 'security' | 'accuracy' | 'clarity' | 'completeness' | 'architecture_and_accuracy' | 'correctness_and_clarity' | 'security_and_completeness';
+/**
+ * Reviewer verdict kinds. Four values, each maps to a different path through
+ * the consensus engine.
+ *
+ * UPPERCASE wire format matches `codevibe_reviewer::VerdictKind`'s
+ * `#[serde(rename_all = "UPPERCASE")]` attribute. Append-only post-launch.
+ *
+ * - `APPROVE` — plan/artifact is sound, proceed.
+ * - `REJECT` — plan/artifact has fundamental problems; do not proceed.
+ * - `REVISE` — plan/artifact is close but needs specific changes. Requires
+ *   populated `suggested_changes` per the parser's locked invariant.
+ * - `ESCALATE` — reviewer cannot decide confidently; surface to user.
+ */
+export type VerdictKind = 'APPROVE' | 'REJECT' | 'REVISE' | 'ESCALATE';
+/**
+ * Newtype-equivalent for `ReviewerVerdict.verdict_id`. Mirrors Rust's
+ * `VerdictId(pub Uuid)` with `#[serde(transparent)]` — wire form is just the
+ * UUID string, no envelope.
+ */
+export type VerdictId = string;
+/**
+ * One reviewer's verdict at one gate. Records reasoning plus perf/cost
+ * metadata for telemetry (review latency, token cost per task, etc.).
+ *
+ * `gate_id` is a plain UUID string (matches Rust's `Uuid` field — the engine
+ * wraps this in its own `GateId` newtype, but the reviewer crate stays
+ * agnostic to avoid an engine→reviewer→engine cycle).
+ *
+ * # Identity
+ *
+ * Per Phase 2f.0.a's seat/role pivot, verdicts are keyed on `seat_id` +
+ * `role`, NOT on `reviewer_agent`. Consensus dedup + audit attribution
+ * happen via `seat_id`; `reviewer_agent` stays for cost-attribution metadata
+ * only and is NOT a uniqueness key (two seats may share an agent in the
+ * single-vendor case).
+ *
+ * Field ordering + names match the Rust struct verbatim — the audit chain's
+ * SHA-256 hashes serialised JSON, so any change to field order or naming
+ * would invalidate every prior chain entry. Append-only after launch.
+ */
+export interface ReviewerVerdict {
+    /** Primary key. UUID v4 string. */
+    verdict_id: VerdictId;
+    /** Foreign key to `ReviewGate`. Plain UUID string per the reviewer crate's
+     *  agnostic-to-engine design. */
+    gate_id: string;
+    /** Seat that produced the verdict. Primary identity key for dedup +
+     *  audit attribution. Providers MUST copy this from `ReviewerSpec.seat_id`. */
+    seat_id: number;
+    /** Lens the seat reviewed through. Copied from `ReviewerSpec.role` verbatim. */
+    role: ReviewerRole;
+    /** Agent that produced the verdict. Descriptive metadata (cost attribution,
+     *  per-agent reliability); NOT an identity key. */
+    reviewer_agent: AgentKind;
+    /** The verdict itself. */
+    verdict: VerdictKind;
+    /** Reviewer's free-form reasoning. */
+    reasoning: string;
+    /** Ordered list of specific changes. **Required** when `verdict === 'REVISE'`;
+     *  empty for other verdicts (enforced by the output parser). */
+    suggested_changes: string[];
+    /** Model identifier used (for cost attribution). */
+    model_used: string | null;
+    /** Tokens consumed by this reviewer. */
+    tokens_used: number | null;
+    /** End-to-end latency for this reviewer's verdict (ms). */
+    latency_ms: number | null;
+    /** ISO 8601 UTC timestamp string when the reviewer returned the verdict. */
+    submitted_at: string;
+}

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

@@ -2,3 +2,5 @@ export * from './events';
 export * from './session';
 export * from './encryption';
 export * from './auth';
+export * from './reviewer';
+export * from './orchestration';

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

@@ -0,0 +1,57 @@
+/**
+ * Wire-shape `UserDecisionKind` enum — matches AppSync schema directly
+ * (`codevibe-backend/graphql/schema.graphql:716-722`). Append-only post-launch.
+ *
+ * V1 ships only the 3 no-notes kinds (`ACCEPT`, `REJECT_RESTART`,
+ * `ABORT_TASK`); the two `_WITH_NOTES` variants are defined here for
+ * completeness against the schema but are NOT in V1's hardcoded option
+ * table — they require a `notes: EncryptedPayloadInput` value alongside
+ * the kind, which the V1 "type a number" UX has no surface for.
+ */
+export declare enum UserDecisionKind {
+    ACCEPT = "ACCEPT",
+    ACCEPT_WITH_NOTES = "ACCEPT_WITH_NOTES",
+    REJECT_WITH_NOTES = "REJECT_WITH_NOTES",
+    REJECT_RESTART = "REJECT_RESTART",
+    ABORT_TASK = "ABORT_TASK"
+}
+/**
+ * Input shape for `applyUserDecision` mutation. Matches AppSync schema
+ * (`codevibe-backend/graphql/schema.graphql:775-790`).
+ *
+ * REQUIRED fields: `gateId`, `taskId`, `sessionId`, `currentRound`, `decision`.
+ * OPTIONAL field: `notes` (only used for `_WITH_NOTES` decision kinds, which
+ * are V2-only in V1).
+ */
+export interface ApplyUserDecisionInput {
+    gateId: string;
+    taskId: string;
+    sessionId: string;
+    currentRound: number;
+    decision: UserDecisionKind;
+    notes?: never;
+}
+/**
+ * `UserDecisionAppliedEvent` envelope — returned by `applyUserDecision`
+ * mutation AND streamed via `onApplyUserDecision` subscription per
+ * Phase 3.b mobile V1 bridge §1.1. Top-level `sessionId` is the
+ * subscription filter key (mirrors `GateResolvedEvent` precedent at
+ * `schema.graphql:815-821`).
+ *
+ * `payload` is `AWSJSON` on the wire — AppSync delivers it as a
+ * JSON-encoded string that callers must `JSON.parse` before treating
+ * as the typed `PostDecisionAction` shape from
+ * `codevibe-revision/src/user_decision.rs:109`. V1 desktop-plugin
+ * callers do NOT consume `payload` (the engine-determined next-gate
+ * action is handled server-side by the orchestration loop, NOT
+ * client-side in V1); the field is preserved on the envelope for
+ * forward-compat.
+ */
+export interface UserDecisionAppliedEvent {
+    sessionId: string;
+    taskId: string;
+    gateId: string;
+    decision: UserDecisionKind;
+    /** AWSJSON-encoded `PostDecisionAction` shape; opaque to V1 plugin callers. */
+    payload: string;
+}