@quantiya/codevibe-core 2.0.0 → 2.0.1

package/dist/local-executor/types.d.ts

@@ -0,0 +1,183 @@
+import type { ChildProcess } from 'node:child_process';
+import type { AuthorityRefusal, AuthorityScope } from './authority';
+export type ProcessRole = 'implementor' | 'reviewer' | 'health_probe' | 'auth_probe' | 'model_probe';
+export type AgentKind = 'CLAUDE' | 'GEMINI' | 'CODEX';
+export type FailureClass = null | 'quota_exhausted' | 'auth_failed' | 'timeout' | 'unavailable' | 'user_aborted';
+export interface SpawnArgs {
+    argv: string[];
+    workingDir: string;
+    role: ProcessRole;
+    agentKind?: AgentKind;
+    timeoutMs: number | null;
+    envOverrides?: Record<string, string>;
+    stdinTty?: boolean;
+    stdinPayload?: string;
+    signal?: AbortSignal;
+    onProcessSpawned?: ProcessSpawnedHook;
+    onProcessExited?: ProcessExitedHook;
+}
+export interface ProcessSpawnedInfo {
+    pid: number;
+    role: ProcessRole;
+    agentKind: AgentKind | undefined;
+    spawnedAt: string;
+}
+export interface ProcessExitedInfo {
+    pid: number;
+    exitCode: number;
+    failureClass: FailureClass;
+    exitedAt: string;
+    runtimeMs: number;
+}
+export type ProcessSpawnedHook = (info: ProcessSpawnedInfo) => void;
+export type ProcessExitedHook = (info: ProcessExitedInfo) => void;
+export interface SpawnHandleBase {
+    pid: number;
+    role: ProcessRole;
+    agentKind: AgentKind | undefined;
+    spawnedAt: string;
+    /** Resolves when the child exits, regardless of cause. */
+    done: Promise<ProcessExitedInfo>;
+    /** Forcibly terminate (SIGKILL + cleanup). Idempotent. */
+    abort(): Promise<void>;
+    /** Captured stdout/stderr — local-only, never crosses the wire. */
+    stdout(): string;
+    stderr(): string;
+}
+export interface ImplementorHandle extends SpawnHandleBase {
+    kind: 'implementor';
+}
+export interface ReviewerHandle extends SpawnHandleBase {
+    kind: 'reviewer';
+}
+export interface ProbeHandle extends SpawnHandleBase {
+    kind: 'probe';
+}
+export declare class SpawnArgsInvalid extends Error {
+    readonly reason: string;
+    readonly offendingKey?: string | undefined;
+    constructor(reason: string, offendingKey?: string | undefined);
+}
+export declare const MARKER_ENV_KEYS: {
+    readonly CHILD: "CODEVIBE_CHILD_PROCESS";
+    readonly ROLE: "CODEVIBE_PROCESS_ROLE";
+    readonly QUORUM: "QUORUM_REVIEWER_SUBPROCESS";
+};
+export declare const MARKER_KEY_SET: ReadonlySet<string>;
+export type AuthorityAction = {
+    kind: 'Write';
+    path: string;
+} | {
+    kind: 'Read';
+    path: string;
+} | {
+    kind: 'Network';
+    urlOrHost: string;
+} | {
+    kind: 'Command';
+    command: string;
+    argv: string[];
+};
+export interface SignedEnvelope {
+    algorithm: 'ed25519' | 'p384-ecdsa';
+    publicKeyId: string;
+    signatureB64: string;
+    issuedAt: string;
+    nonceUlid: string;
+}
+export type ClassBInbound = {
+    kind: 'PlannerDecisionApproved';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'GateDispatch';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'ContinuationOffer';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'TaskAuthorized';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'PolicyRejection';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+};
+export type ExecutorError = {
+    kind: 'AuthorityRefusal';
+    refusal: AuthorityRefusal;
+} | {
+    kind: 'SpawnFailed';
+    detail: string;
+} | {
+    kind: 'SubprocessIo';
+    detail: string;
+} | {
+    kind: 'SignatureVerification';
+    detail: string;
+} | {
+    kind: 'MalformedClassB';
+    detail: string;
+} | {
+    kind: 'PolicyMismatch';
+    detail: string;
+};
+export type FileChangeKind = 'Created' | 'Modified' | 'Deleted';
+export type HookEvent = {
+    kind: 'ToolUse';
+    sessionId: string;
+    toolName: string;
+    toolInput: unknown;
+    timestamp: string;
+} | {
+    kind: 'FileChange';
+    sessionId: string;
+    path: string;
+    change: FileChangeKind;
+    timestamp: string;
+} | {
+    kind: 'ProcessExited';
+    sessionId: string;
+    pid: number;
+    exitCode: number;
+    timestamp: string;
+    failureClass?: FailureClass | undefined;
+    failureSignal?: NodeJS.Signals | undefined;
+} | {
+    kind: 'UserPrompt';
+    sessionId: string;
+    contentB64: string;
+    timestamp: string;
+} | {
+    kind: 'AssistantText';
+    sessionId: string;
+    contentB64: string;
+    timestamp: string;
+};
+export interface LocalExecutor {
+    spawnImplementor(args: SpawnArgs): Promise<ImplementorHandle>;
+    spawnReviewer(args: SpawnArgs): Promise<ReviewerHandle>;
+    spawnHealthProbe(args: SpawnArgs): Promise<ProbeHandle>;
+    /**
+     * Single-entrypoint authority gate. Dispatches to `enforceWrite` /
+     * `enforceRead` / `enforceNetwork` / `enforceCommand` based on `action.kind`.
+     * Throws `AuthorityError` on refusal (master §9:1284).
+     */
+    enforceAuthority(action: AuthorityAction): Promise<void>;
+    ingestHookEvent(event: HookEvent): Promise<void>;
+    /** Read-only view of the current TASK_AUTHORIZED.authorityScope. */
+    authorityScope(): Readonly<AuthorityScope>;
+    /** CP-1.c STUB; CP-1.e wires real AppSync subscription + signature verification. */
+    consumeClassB(packet: ClassBInbound): Promise<void>;
+}
+export interface SpawnedProcess {
+    child: ChildProcess;
+    pid: number;
+    role: ProcessRole;
+    agentKind: AgentKind | undefined;
+    spawnedAt: string;
+    spawnedAtMs: number;
+}

package/dist/local-executor/verification-gates/build.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface BuildGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runBuildGate(args: BuildGateArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-gates/deploy-preflight.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface DeployPreflightGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runDeployPreflightGate(args: DeployPreflightGateArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-gates/diff-sanity.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface DiffSanityGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runDiffSanityGate(args: DiffSanityGateArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-gates/hostile-grep.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface HostileGrepGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runHostileGrepGate(args: HostileGrepGateArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-gates/lint.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface LintGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runLintGate(args: LintGateArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-gates/shell-runner.d.ts

@@ -0,0 +1,40 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { GateRunResult } from '../verification-runner';
+export declare const VERIFICATION_RUNNER_ROLE = "verification_runner";
+export interface ShellRunArgs {
+    /** Command to execute (e.g. "cargo", "npm", "git"). */
+    command: string;
+    /** Arguments to pass to the command. */
+    args: string[];
+    /** Working directory — caller (gate wrapper) MUST pass the repo root. */
+    cwd: string;
+    /** Per-gate timeout budget in milliseconds. Required (LOCK #C3E-4). */
+    timeoutMs: number;
+    /** Optional extra env overrides on top of the marker injection. */
+    extraEnv?: Record<string, string>;
+    /** Optional clock seam for tests. Defaults to Date.now. */
+    nowMs?: () => number;
+    /**
+     * Test seam — injects a fake spawner. Production callers leave this
+     * undefined and the real `child_process.spawn` is used. The seam returns
+     * a minimal interface (write events, exit event) so test fixtures
+     * don't have to model the full Node ChildProcess surface.
+     */
+    spawnFn?: typeof nodeSpawn;
+}
+/**
+ * Run a single command-line under the verification-runner marker. Returns
+ * a `GateRunResult` matching what verification-runner.ts consumes.
+ *
+ * Captures FULL stdout/stderr (the runner truncates per LOCK #C3E-1) and
+ * fires the timeout race per LOCK #C3E-4. On timeout, the subprocess is
+ * killed (SIGKILL) and `timedOut: true` is set so the runner can apply
+ * the wire-form `exit_code = 124` regardless of what the platform
+ * returned for the killed process.
+ *
+ * NOTE: this primitive does NOT participate in authority enforcement.
+ * The orchestration shell establishes the authority scope BEFORE the
+ * verification runner is invoked, and the gates themselves operate on
+ * the user's own working tree which is implicitly readable.
+ */
+export declare function runShellCommand(args: ShellRunArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-gates/source-traceability.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface SourceTraceabilityGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runSourceTraceabilityGate(args: SourceTraceabilityGateArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-gates/tests.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface TestsGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runTestsGate(args: TestsGateArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-gates/typecheck.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface TypecheckGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runTypecheckGate(args: TypecheckGateArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-runner.d.ts

@@ -0,0 +1,28 @@
+import type { ClassAEmitter, ClassAEmitterContext, VerificationGateKind, VerificationResultPayload } from './class-a-emit';
+export declare const DEFAULT_GATE_TIMEOUT_MS = 300000;
+export declare const TIMEOUT_EXIT_CODE = 124;
+export declare const SUMMARY_CAP_BYTES = 4096;
+export interface VerificationGateRequest {
+    gateId: string;
+    taskId: string;
+    sessionId: string;
+    gateKinds: VerificationGateKind[];
+    cwd: string;
+    timeoutMsOverride?: number;
+}
+export interface GateRunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    timedOut?: boolean;
+}
+export interface VerificationRunnerDeps {
+    emitter: ClassAEmitter;
+    classAContext: ClassAEmitterContext;
+    nowMs?: () => number;
+    onResultEmitted?: (result: VerificationResultPayload) => void;
+}
+export declare function runVerificationGates(req: VerificationGateRequest, deps: VerificationRunnerDeps): Promise<VerificationResultPayload[]>;
+export declare function truncateUtf8Safe(input: string, maxBytes: number): string;
+export declare const NO_OP_PASS: GateRunResult;

package/dist/orchestration/__tests__/setup-bootstrap.test.d.ts

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

package/dist/orchestration/__tests__/setup-failure-recourse.test.d.ts

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

package/dist/orchestration/__tests__/setup-save.test.d.ts

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

package/dist/orchestration/__tests__/setup-seat-picker.test.d.ts

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

package/dist/orchestration/__tests__/setup-telemetry.test.d.ts

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

package/dist/orchestration/__tests__/setup-test-agents.test.d.ts

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

package/dist/orchestration/__tests__/setup-types.test.d.ts

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

package/dist/orchestration/__tests__/setup-wizard.test.d.ts

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

package/dist/orchestration/__tests__/v1-options.test.d.ts

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

package/dist/orchestration/detect-agents.d.ts

@@ -1,5 +1,6 @@
 import { Logger } from '../logger';
 import { AppSyncClient } from '../appsync';
+import { CapabilityRegistry } from '../adapter/capabilities';
 export type DetectableAgent = 'CLAUDE' | 'GEMINI' | 'CODEX';
 /**
  * Returns the subset of agents present on PATH. Uses `command -v`
@@ -26,7 +27,7 @@ export declare function detectInstalledAgents(): DetectableAgent[];
  * @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>;
+export declare function pushDetectedAgents(client: AppSyncClient, log: Pick<Logger, 'info' | 'warn'>, capabilityRegistry?: CapabilityRegistry, detectFn?: () => DetectableAgent[]): Promise<void>;
 /**
  * Quorum 2.0 (2f.0.a.6) per-session orchestration CLI override applier.
  * All three plugin wrappers (`codevibe-claude`, `codevibe-gemini`,

package/dist/orchestration/index.d.ts

@@ -1,2 +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, type V1OrchestrationOption, type V1UserDecisionKind, } from './v1-options';

package/dist/orchestration/orchestration-cli.d.ts

@@ -1,9 +1,12 @@
 /**
  * Dispatch for the `orchestration` subcommand. Called by runAuthCli
- * when it sees `argv[2] === 'orchestration'`. Supports four sub-actions:
+ * 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/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/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/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;