@quantiya/codevibe-claude-plugin 1.0.36 → 1.0.37

package/node_modules/@quantiya/codevibe-core/dist/orchestration/__tests__/setup-bootstrap.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/orchestration/__tests__/setup-failure-recourse.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/orchestration/__tests__/setup-save.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/orchestration/__tests__/setup-seat-picker.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/orchestration/__tests__/setup-telemetry.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/orchestration/__tests__/setup-test-agents.test.d.ts

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

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

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

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

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

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

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

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

@@ -0,0 +1,56 @@
+import { Logger } from '../logger';
+import { AppSyncClient } from '../appsync';
+export type DetectableAgent = 'CLAUDE' | 'GEMINI' | 'CODEX';
+/**
+ * Returns the subset of agents present on PATH. Uses `command -v`
+ * (POSIX-standard) rather than `which` for portability across macOS
+ * and Linux. Runs synchronously — the whole probe is <10ms in practice
+ * even when agents are absent.
+ *
+ * Safe to call repeatedly; no caching here because the set of
+ * installed agents CAN change between plugin launches (user installs
+ * a new agent) and the caller decides how often to re-probe.
+ */
+export declare function detectInstalledAgents(): DetectableAgent[];
+/**
+ * Detect-and-push convenience for plugin daemon startup. All three
+ * plugins (Claude, Gemini, Codex) call this once at start(). Runs
+ * the local PATH probe, then pushes the set to the backend via
+ * updateAvailableAgents. Idempotent — the backend dedupes and stores.
+ * Non-fatal on the network failure path (caller should `.catch()`
+ * and log but not abort startup — Quorum 2.0 auto-enable degrades
+ * to "use last-pushed agent set" when the mutation fails).
+ *
+ * @param client  AppSyncClient that's already been authenticated via
+ *                authenticateWithStoredTokens()
+ * @param log     Logger — warn-level when no agents detected, info
+ *                on success
+ */
+export declare function pushDetectedAgents(client: AppSyncClient, log: Pick<Logger, 'info' | 'warn'>): Promise<void>;
+/**
+ * Quorum 2.0 (2f.0.a.6) per-session orchestration CLI override applier.
+ * All three plugin wrappers (`codevibe-claude`, `codevibe-gemini`,
+ * `codevibe-codex`) export `CODEVIBE_ORCHESTRATION_OVERRIDE=true|false`
+ * to the tmux env when the user passes `--orchestration` /
+ * `--no-orchestration`. The daemon inherits this via the hook env
+ * chain and calls THIS function after every session-creation site
+ * to pin the per-session decision — wins outright over the server's
+ * User.orchestrationEnabledDefault auto-populate.
+ *
+ * Called from each plugin's daemon at every session-creation call
+ * site. Claude has one (handleSessionStart covers new + /resume
+ * because Claude Code fires SessionStart on /resume). Gemini has
+ * two (handleSessionStart + switchToResumedSession — /resume doesn't
+ * fire SessionStart in Gemini). Codex has two (createLaunchSession
+ * + handleSessionStarted — launch session gets replaced by runtime
+ * session_meta).
+ *
+ * Non-fatal on error — a failed override doesn't block session setup;
+ * the server's auto-populate decision stands and the user can flip
+ * the session via mobile toggle after the fact.
+ *
+ * @param client     AppSyncClient authenticated for the session's owner
+ * @param sessionId  Backend session ID (post-resumeOrCreateSession)
+ * @param log        Logger
+ */
+export declare function applyPerSessionOrchestrationOverride(client: AppSyncClient, sessionId: string, log: Pick<Logger, 'info' | 'warn'>): Promise<void>;

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

@@ -0,0 +1,3 @@
+export { detectInstalledAgents, pushDetectedAgents, applyPerSessionOrchestrationOverride, type DetectableAgent, } from './detect-agents';
+export { runOrchestrationCli } from './orchestration-cli';
+export { V1_ORCHESTRATION_PROMPT_KIND, V1_ORCHESTRATION_OPTIONS, mapOptionNumberToUserDecisionKind, mapOptionToUserDecisionKind, mapV1KindToWire, type V1OrchestrationOption, type V1UserDecisionKind, } from './v1-options';

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

@@ -0,0 +1,12 @@
+/**
+ * Dispatch for the `orchestration` subcommand. Called by runAuthCli
+ * when it sees `argv[2] === 'orchestration'`. Supports five sub-actions:
+ *   enable    — set orchestrationEnabledDefault = true
+ *   disable   — set orchestrationEnabledDefault = false
+ *   status    — print current policy snapshot + installed agents
+ *   configure — interactive wizard (toggle + panel customization)
+ *   setup     — Phase 3.a (#190) 3-step locked setup wizard with Test
+ *               My Agents (locked role taxonomy: architecture /
+ *               correctness / security)
+ */
+export declare function runOrchestrationCli(argv: string[]): Promise<void>;

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

@@ -0,0 +1,146 @@
+import { AppSyncClient } from '../appsync/appsync-client.js';
+import { DetectableAgent } from './detect-agents.js';
+import { CountBucket, WizardEntry, WizardTier } from './setup-types.js';
+import type { AgentKind } from '../reviewer/types.js';
+import type { UserReviewerPolicySnapshot } from '../types/reviewer.js';
+/**
+ * Thrown by `defaultClientFactory` when `authenticateWithStoredTokens`
+ * returns false AND the most recent failure kind is `'refresh_network'`
+ * (transient 5xx / DNS / socket-reset during the Cognito refresh-token
+ * POST). The wizard's `runBootstrap` catch routes this to
+ * `subscription_status_network` — same recourse as
+ * `getSubscriptionStatus` blowing up, but distinct from a genuine
+ * `not_signed_in` (which we still surface as `not_signed_in` so the
+ * user is told to re-authenticate).
+ *
+ * Stage 2 round-1 Codex M1. The error message is intentionally
+ * network-shaped so the existing `isNetworkLikeError(message)` regex
+ * also matches — defense in depth in case a future caller throws this
+ * outside the bootstrap path.
+ */
+export declare class AuthRefreshNetworkError extends Error {
+    constructor(cause: string);
+}
+/**
+ * Successful bootstrap output. The wizard's state machine consumes
+ * this to seed Step 1 (seat assignment).
+ *
+ * R1/R2 round-1 finding M1+L3+M6 (resolved 2026-05-08): the
+ * authenticated `client` and the user's `email` are exposed here so
+ * the wizard can render `✓ Signed in as <email>` per design §1
+ * lines 47-50 and avoid double-authenticating before save.
+ */
+export interface BootstrapResult {
+    tier: WizardTier;
+    /** Pro=2, Max=3. Free can't reach success (tier-gated above). */
+    seatBudget: number;
+    /** Lower-cased agent kinds detected on PATH, in canonical order. */
+    installedAgents: AgentKind[];
+    /** Pre-bucketed for telemetry; saved here so Step 1's emit doesn't recompute. */
+    installedAgentsBucket: CountBucket;
+    /**
+     * The authenticated AppSyncClient. Wizard reuses this for the save
+     * step rather than re-running `authenticateWithStoredTokens()` —
+     * eliminates the auth-evicted-between-bootstrap-and-save telemetry
+     * gap (R1 round-1 M1) and the wasteful double-auth (R1 round-1 L3).
+     */
+    client: AppSyncClient;
+    /**
+     * Email of the signed-in user (Cognito `email` claim), or null if
+     * the claim is not present. Used by the wizard's bootstrap-summary
+     * UI per design §1 lines 47-50.
+     */
+    userEmail: string | null;
+    /**
+     * Stage 2 round-1 Codex M2: the user's saved reviewer policy at
+     * bootstrap time, so the wizard can pre-populate seat-picker
+     * defaults on a re-run instead of always falling back to the
+     * tier-default agent / role priority. `null` when the snapshot
+     * fetch failed (the wizard then proceeds without saved-defaults —
+     * the canonical priority order is the fallback).
+     *
+     * Fetched via the existing `updateAvailableAgents` mutation, which
+     * is idempotent + already called by every plugin startup
+     * (`appsync-client.ts:721-724`). The wizard repeating it is safe
+     * and avoids introducing a new wire contract just to read three
+     * fields back.
+     */
+    savedPolicy: UserReviewerPolicySnapshot | null;
+}
+/**
+ * Failure shape — discriminated by `kind`. The wizard surfaces a
+ * user-facing message and exits with code 1; telemetry is fired by
+ * `runBootstrap()` before the result is returned (so callers don't
+ * re-fire on their failure path).
+ */
+export type BootstrapFailure = {
+    kind: 'tier_gate_free';
+    tier: 'FREE';
+} | {
+    kind: 'not_signed_in';
+} | {
+    kind: 'subscription_status_network';
+    cause: string;
+} | {
+    kind: 'no_clis_installed';
+};
+export type BootstrapOutput = {
+    ok: true;
+    result: BootstrapResult;
+} | {
+    ok: false;
+    failure: BootstrapFailure;
+};
+/**
+ * Inputs for `runBootstrap`. Threads the wizard run id through so
+ * telemetry events stitch by `wizard_run_id`.
+ *
+ * `clientFactory` is injected so tests can swap in a mock AppSync
+ * client; production passes `defaultClientFactory`.
+ *
+ * `agentDetector` defaults to `detectInstalledAgents` (the production
+ * PATH walk) but is swappable for unit tests.
+ *
+ * `entry` is threaded in so `runBootstrap` can fire `wizard_started`
+ * itself — Stage 2 round-1 Codex M3 moved the emit from the wizard
+ * (where it skipped Free / no_clis users) into bootstrap (where it
+ * fires post-tier-and-agents-known, before any gate).
+ */
+export interface BootstrapDeps {
+    wizardRunId: string;
+    clientFactory: () => Promise<AppSyncClient | null>;
+    agentDetector: () => DetectableAgent[];
+    entry: WizardEntry;
+}
+/**
+ * Production client factory. Builds an AppSyncClient and authenticates
+ * with stored tokens. Returns null on `'no_tokens'` /
+ * `'refresh_auth_rejected'` (the wizard maps both to `not_signed_in`);
+ * THROWS `AuthRefreshNetworkError` on `'refresh_network'` so the
+ * wizard's `runBootstrap` catch routes the user to
+ * `subscription_status_network` instead of mistakenly telling a
+ * signed-in user to re-login when their refresh-token POST hit a
+ * transient 5xx.
+ *
+ * Stage 2 round-1 Codex M1: pre-fix, `authenticateWithStoredTokens`
+ * returned false on every error path, including network failures
+ * inside `callCognitoRefresh`'s catch block; the bootstrap's
+ * `isNetworkLikeError` check only ran on caught throws and so never
+ * fired in production for refresh-network failures.
+ */
+export declare function defaultClientFactory(): Promise<AppSyncClient | null>;
+/**
+ * Run Step 0. Emits `wizard_step_started{step:'bootstrap'}` on entry,
+ * then either `wizard_step_completed` on success OR
+ * `wizard_step_failed` + `wizard_aborted` on failure. Returns the
+ * `BootstrapOutput` in either case so the caller can render UX before
+ * exiting.
+ *
+ * Stage 2 round-1 Codex M3: `wizard_started` is emitted from here,
+ * post-tier-and-agents-known, BEFORE the tier-gate / no-CLIs check.
+ * Free + no_clis users now fire `wizard_started` (so analytics has
+ * the funnel-entry numerator); auth/network bootstrap-aborts skip
+ * `wizard_started` (no tier known) and surface as
+ * `wizard_aborted{auth_expired | bootstrap_failure}` instead.
+ */
+export declare function runBootstrap(deps: BootstrapDeps): Promise<BootstrapOutput>;

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

@@ -0,0 +1,23 @@
+import type { PickerIO } from './setup-seat-picker.js';
+export type Step2Choice = 'retry' | 'save_anyway' | 'exit';
+export type Step3Choice = 'retry' | 'exit';
+/**
+ * Render the Step 2 recourse menu after a Test My Agents failure.
+ * Loops on invalid input. Returns the user's choice. The caller is
+ * responsible for emitting `wizard_aborted` if `exit` is chosen.
+ *
+ * `canSaveAnyway` controls whether the `[s]` option is offered. When
+ * false (spawn_failure / timeout), only `[r]` and `[x]` are accepted.
+ */
+export declare function askStep2Recourse(io: PickerIO, canSaveAnyway: boolean): Promise<Step2Choice>;
+/**
+ * Render the Step 3 recourse menu after a save failure. The caller's
+ * retry loop preserves the in-memory `seats` state so retry is free.
+ *
+ * `recoverable` honors the §6 outcome table: when false
+ * (auth_token_expired), `[r]` is suppressed because retry can only
+ * fail again — the user must re-run `codevibe login` and start a new
+ * wizard. The recourse menu collapses to a single `[x] exit` choice
+ * with a re-auth instruction line. (R1 round-1 M3 / R2 round-1 M4.)
+ */
+export declare function askStep3Recourse(io: PickerIO, recoverable?: boolean): Promise<Step3Choice>;

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

@@ -0,0 +1,47 @@
+import type { AppSyncClient } from '../appsync/appsync-client.js';
+import { WizardSeatPick, WizardStepFailureReason } from './setup-types.js';
+export type SaveResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: WizardStepFailureReason;
+    /**
+     * Whether `[r] retry` makes sense for this failure. Network /
+     * 5xx / throttle are retryable (transient). auth_token_expired
+     * is NOT retryable in-process — the user must re-run `codevibe
+     * login` and start a new wizard run.
+     */
+    recoverable: boolean;
+};
+export interface SaveDeps {
+    wizardRunId: string;
+    client: AppSyncClient;
+    seats: WizardSeatPick[];
+    /**
+     * Whether the user reached this step via "save anyway" after a
+     * Test My Agents warning. Drives the wizard_completed.outcome
+     * value at the wizard's terminal exit (`'ok' | 'saved_after_test_warning'`).
+     * Not used here — Step 3 just persists; the top-level wizard
+     * threads the outcome value into the final `wizard_completed` event.
+     */
+    savedAfterTestWarning: boolean;
+}
+/**
+ * Run Step 3. Emits `wizard_step_started{step:'save'}` on entry,
+ * `wizard_step_completed` on success, or `wizard_step_failed` with
+ * the classified reason. Returns a SaveResult the wizard's recourse
+ * loop consumes.
+ */
+export declare function runSave(deps: SaveDeps): Promise<SaveResult>;
+/**
+ * Classify a thrown error from `updateReviewerPolicy` into one of the
+ * §7 save-step reason codes. Best-effort matching against the AppSync
+ * client's error message conventions:
+ *   - 401 / "Unauthorized" / "Token expired" → auth_token_expired
+ *   - 429 / "Throttling" / "Rate exceeded" → update_policy_throttle
+ *   - 5xx / "Internal" / "InternalServerError" → update_policy_5xx
+ *   - everything else (fetch threw, ECONNRESET, DNS) → update_policy_network
+ *
+ * Exposed for tests to assert classification mapping.
+ */
+export declare function classifySaveError(err: unknown): WizardStepFailureReason;

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

@@ -0,0 +1,72 @@
+import * as readline from 'readline';
+import { WizardSeatPick, WizardRole } from './setup-types.js';
+import type { AgentKind } from '../reviewer/types.js';
+/**
+ * One entry in the optional `savedSeats` array — the user's previously
+ * persisted reviewer policy, threaded in by the wizard on a re-run so
+ * the picker pre-fills per-seat agent + role defaults. Stage 2 round-1
+ * Codex M2.
+ *
+ * Stale entries (agent no longer installed, role not in
+ * `WIZARD_ROLES`, role already taken by a previous seat) are silently
+ * ignored — the picker falls back to the canonical priority defaults
+ * for that seat.
+ */
+export interface SavedSeatHint {
+    seatId: number;
+    agent: AgentKind;
+    role: WizardRole;
+}
+/**
+ * Reader/writer abstraction so tests can drive the picker with
+ * scripted answers instead of an interactive readline. Production
+ * passes a Node readline.Interface; tests pass a fake.
+ */
+export interface PickerIO {
+    /** Render a line to the user. No newline appended; pass '\n' if needed. */
+    write: (line: string) => void;
+    /** Prompt the user and return the trimmed answer (without trailing newline). */
+    ask: (prompt: string) => Promise<string>;
+}
+export interface SeatPickerDeps {
+    wizardRunId: string;
+    installedAgents: AgentKind[];
+    seatBudget: number;
+    io: PickerIO;
+    /**
+     * Optional per-seat hints from the user's saved reviewer policy
+     * (Stage 2 round-1 Codex M2). When present and valid (agent
+     * installed; role still available for that seat), the picker uses
+     * the hint as the default instead of the canonical
+     * AGENT_PRIORITY / DEFAULT_ROLE_BY_SEAT priority.
+     *
+     * Indexed by `seatId` (NOT array position) — the implementation
+     * looks up `savedSeats.find(s => s.seatId === seatId)` so absent /
+     * out-of-order entries are fine.
+     */
+    savedSeats?: ReadonlyArray<SavedSeatHint>;
+}
+/**
+ * Run Step 1. Returns the user's per-seat picks. Caller is
+ * responsible for closing the readline interface.
+ */
+export declare function runSeatPicker(deps: SeatPickerDeps): Promise<WizardSeatPick[]>;
+/**
+ * Default-role-fallback rule (PHASE-3-A-DESIGN.md §1). Seat 0 wants
+ * `architecture`, Seat 1 wants `correctness`, Seat 2 wants `security`.
+ * If the canonical pick is gone (taken by a previous seat), fall
+ * back to the first remaining role in canonical order.
+ *
+ * Stage 2 round-1 Codex M2: when `savedRole` is provided AND that
+ * role is in `WIZARD_ROLES` AND it's still in `availableRoles` (not
+ * taken by a previous seat), use it as the default instead of the
+ * canonical-default-by-seat priority. Stale saved values (role
+ * already taken, or a non-3-role value from a 2.0.x custom-roles
+ * future expansion) are silently ignored.
+ */
+export declare function pickDefaultRole(seatId: number, availableRoles: ReadonlyArray<WizardRole>, savedRole?: WizardRole): WizardRole;
+/**
+ * Build a `PickerIO` from a Node readline interface. Production
+ * callers use this; tests construct their own `PickerIO` directly.
+ */
+export declare function readlinePickerIO(rl: readline.Interface): PickerIO;

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

@@ -0,0 +1,54 @@
+import type { WizardStep, WizardStepFailureReason, WizardAbortReason, WizardEntry, WizardTier, CountBucket, LatencyBucket } from './setup-types.js';
+/**
+ * Generate a fresh `wizard_run_id` for one wizard invocation. Returned
+ * by `runSetupWizard()` entry and threaded into every emit call.
+ *
+ * v4 UUID — uses Node's crypto.randomUUID when available (Node 14.17+);
+ * otherwise falls back to a manual v4 derivation. Either path produces
+ * a 36-char hex-with-dashes string suitable for the GA4 custom-dimension
+ * `wizard_run_id` registered in `register-custom-dimensions.py`.
+ */
+export declare function newWizardRunId(): string;
+export declare function emitWizardStarted(args: {
+    wizardRunId: string;
+    tier: WizardTier;
+    entry: WizardEntry;
+    installedAgentsBucket: CountBucket;
+}): Promise<void>;
+export declare function emitWizardStepStarted(args: {
+    wizardRunId: string;
+    step: WizardStep;
+}): Promise<void>;
+export declare function emitWizardStepCompleted(args: {
+    wizardRunId: string;
+    step: WizardStep;
+    latencyBucket: LatencyBucket;
+}): Promise<void>;
+export declare function emitWizardStepFailed(args: {
+    wizardRunId: string;
+    step: WizardStep;
+    reason: WizardStepFailureReason;
+    latencyBucket: LatencyBucket;
+}): Promise<void>;
+export declare function emitWizardCompleted(args: {
+    wizardRunId: string;
+    outcome: 'ok' | 'saved_after_test_warning';
+    tier: WizardTier;
+    seatsBucket: CountBucket;
+    agentsDistinctBucket: CountBucket;
+    rolesDistinctBucket: CountBucket;
+    totalLatencyBucket: LatencyBucket;
+}): Promise<void>;
+export declare function emitWizardAborted(args: {
+    wizardRunId: string;
+    reason: WizardAbortReason;
+    lastStep: WizardStep;
+}): Promise<void>;
+type BeaconRecord = {
+    name: string;
+    params: Record<string, string | number>;
+};
+type BeaconSink = (record: BeaconRecord) => void;
+export declare function __setBeaconSink(sink: BeaconSink): void;
+export declare function __resetBeaconSink(): void;
+export {};

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

@@ -0,0 +1,108 @@
+import { WizardSeatPick, WizardStepFailureReason } from './setup-types.js';
+import type { ReviewerSpec, ReviewerVerdict } from '../reviewer/index.js';
+/**
+ * Canned proposal — byte-identical across all installations. Locked
+ * 2026-05-03 per PHASE-3-A-DESIGN.md §3. Do NOT edit without going
+ * through a re-review of the entire Test My Agents protocol; the
+ * prose is part of the wizard's contract test surface (the new-contract
+ * row at PHASE-3-A-DESIGN.md:495 asserts byte-identicality).
+ *
+ * The proposal is intentionally trivial + read-only. The wizard does
+ * NOT actually create /tmp/quorum_test_hello.py — APPROVE is the
+ * expected outcome from a working reviewer.
+ */
+export declare const CANNED_PROPOSAL = "## Problem\nAdd a one-line Python \"Hello, World\" script to a new file.\n\n## Proposal\nCreate a single Python file at /tmp/quorum_test_hello.py containing the\nsingle line: print(\"hello world\")\n\n## Implementation Plan\n1. Create the file at /tmp/quorum_test_hello.py\n2. Write print(\"hello world\") on line 1 followed by a trailing newline\n3. Make no other changes\n\n## Expected Outputs\n- /tmp/quorum_test_hello.py \u2014 exists, contains the single-line script\n";
+/**
+ * Per-seat timeout. PHASE-3-A-DESIGN.md §6 "Timeout (60s/seat)".
+ * Conservative — gives a slow CLI room to start + respond on a
+ * cold-spawned reviewer process. Shorter would pollute the failure
+ * recourse menu with false positives on first-run latency.
+ */
+export declare const PER_SEAT_TIMEOUT_MS = 60000;
+/**
+ * Per-seat outcome rendered by the wizard. Returned by
+ * `runTestMyAgents` in the `seatOutcomes` array so the recourse menu
+ * can display each seat's status individually (per §3 "per-seat
+ * outputs ... are tagged with the seat ID and rendered together").
+ */
+export interface SeatOutcome {
+    seatId: number;
+    agent: WizardSeatPick['agent'];
+    role: WizardSeatPick['role'];
+    /** Wall-clock seconds elapsed for this seat's evaluate() call. */
+    elapsedSeconds: number;
+    /** Discriminated outcome — APPROVE plus the 6 failure shapes. */
+    result: {
+        kind: 'approve';
+    } | {
+        kind: 'revise';
+    } | {
+        kind: 'reject';
+    } | {
+        kind: 'escalate';
+    } | {
+        kind: 'parse_failure';
+    } | {
+        kind: 'spawn_failure';
+        reason: string;
+    } | {
+        kind: 'timeout';
+        elapsedMs: number;
+    } | {
+        kind: 'unknown_error';
+        message: string;
+    };
+}
+export type TestMyAgentsResult = {
+    ok: true;
+    seatOutcomes: SeatOutcome[];
+} | {
+    ok: false;
+    reason: WizardStepFailureReason;
+    canSaveAnyway: boolean;
+    seatOutcomes: SeatOutcome[];
+};
+/**
+ * Inputs for `runTestMyAgents`. The registry factory is injected so
+ * tests can swap in a mock; production passes
+ * `createSubprocessReviewerRegistry`.
+ */
+export interface TestMyAgentsDeps {
+    wizardRunId: string;
+    seats: WizardSeatPick[];
+    registryFactory?: () => {
+        evaluate: (spec: ReviewerSpec, gateId: string) => Promise<ReviewerVerdict>;
+    };
+    /**
+     * Status renderer. Tests pass a buffer; production passes a function
+     * that writes to process.stdout. Each call gets one line (no
+     * trailing newline added — caller controls).
+     */
+    write?: (line: string) => void;
+    /**
+     * Test seam: a synthetic gateId. Phase 3.a's wizard is wholly
+     * client-side (PHASE-3-A-DESIGN.md §5 "Wizard never spawns through
+     * OrchestrationClient.connect()"), so the gateId is a local
+     * synthetic UUID — providers echo it back on the verdict but the
+     * wizard does not persist it. Tests can pin a known value.
+     */
+    gateId?: string;
+}
+/**
+ * Run Step 2. Emits `wizard_step_started`, dispatches all seats in
+ * parallel via Promise.allSettled, classifies each outcome, emits
+ * `wizard_step_completed` (all APPROVE) or `wizard_step_failed` with
+ * the worst-blocker reason. Returns per-seat outcomes for the
+ * wizard's recourse renderer.
+ */
+export declare function runTestMyAgents(deps: TestMyAgentsDeps): Promise<TestMyAgentsResult>;
+/**
+ * Render a per-failure-kind explanatory sentence per the §6 outcome
+ * table + §1 line 140 "Display the structured error describing what
+ * failed" requirement. The wizard prints this before the recourse
+ * menu so users see WHY each non-APPROVE seat failed, not just a
+ * status line.
+ *
+ * R1 round-1 M3 (resolved 2026-05-08).
+ */
+export declare function humanizeStep2Failures(outcomes: SeatOutcome[]): string[];