@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/local-model/manager.d.ts

@@ -0,0 +1,119 @@
+import { spawn } from 'child_process';
+import type { Tier } from '../orchestration-shell/types';
+import { type LocalModelState, type LocalModelStateStore } from './state';
+import type { LocalGemmaPlannerRunner } from '../planner/local-gemma';
+export type LocalModelCommand = 'install' | 'status' | 'remove' | 'enable' | 'warm' | 'health-check';
+export type LocalModelEntitlementSource = 'backend' | 'unauthenticated' | 'unavailable';
+export interface LocalModelEntitlement {
+    tier: Tier | 'UNKNOWN';
+    source: LocalModelEntitlementSource;
+}
+export interface LocalModelArtifactConfig {
+    artifactId: string | null;
+    downloadUrl: string | null;
+    sha256: string | null;
+    expectedBytes?: number | null;
+    cacheDir: string;
+    ollamaModel?: string | null;
+}
+export interface LocalModelStore {
+    artifactExists(config: LocalModelArtifactConfig): Promise<boolean>;
+    removeArtifact(config: LocalModelArtifactConfig): Promise<boolean>;
+}
+export interface LocalModelInstaller {
+    install(config: LocalModelArtifactConfig): Promise<void>;
+}
+export interface LocalModelDownloadTransport {
+    downloadToFile(url: URL, destinationPath: string, expectedBytes: number): Promise<void>;
+}
+export interface LocalModelRuntimeFactory {
+    createRunner(config: LocalModelArtifactConfig): Promise<LocalGemmaPlannerRunner | null>;
+}
+export interface RunLocalModelCommandOptions {
+    command: LocalModelCommand;
+    entitlement: LocalModelEntitlement;
+    config?: LocalModelArtifactConfig;
+    store?: LocalModelStore;
+    stateStore?: LocalModelStateStore;
+    installer?: LocalModelInstaller;
+    runtimeFactory?: LocalModelRuntimeFactory;
+    stdout?: (s: string) => void;
+    stderr?: (s: string) => void;
+    /** TEST SEAM — the capability-aware default model for a BARE install. Defaults to
+     *  {@link resolveDefaultOllamaModelForInstall}; tests inject a deterministic thunk. */
+    resolveInstallModel?: () => Promise<string>;
+}
+export declare function loadLocalModelArtifactConfigFromEnv(env?: NodeJS.ProcessEnv): LocalModelArtifactConfig;
+/** The curated local-planner Ollama models (benchmarked 2026-07-02, gemma4 family). */
+export declare const CAPABLE_OLLAMA_MODEL = "gemma4:12b-it-qat";
+export declare const BASELINE_OLLAMA_MODEL = "gemma4:latest";
+/** True iff the Ollama version string (e.g. "0.31.1", tolerating a leading "v") is ≥ MIN_OLLAMA_MAJOR.MINOR. */
+export declare function ollamaVersionAtLeast(version: string | undefined, major?: number, minor?: number): boolean;
+/**
+ * The DEFAULT Ollama model for `codevibe model install` when the user set neither
+ * `CODEVIBE_LOCAL_MODEL_OLLAMA_MODEL` nor a pinned artifact — CAPABILITY-AWARE per the
+ * CP-4 plan (2026-07-02 benchmark): the stronger 12B QAT (`gemma4:12b-it-qat`) ONLY when
+ * the host has enough RAM (~16 GB) AND Ollama ≥ 0.31 (the 12B tags need it — 0.24 rejects
+ * the pull); otherwise the broadly-compatible 8B (`gemma4:latest`). Fails SOFT to the 8B
+ * on any uncertainty (Ollama unreachable / unparseable version) so install never breaks.
+ */
+export declare function resolveDefaultOllamaModelForInstall(deps?: {
+    ollamaHost?: string;
+    totalMemBytes?: number;
+    fetchImpl?: typeof fetch;
+    log?: (s: string) => void;
+}): Promise<string>;
+export declare function isLocalModelEntitled(entitlement: LocalModelEntitlement): entitlement is LocalModelEntitlement & {
+    tier: 'PRO' | 'MAX';
+};
+export declare function localModelArtifactPath(config: LocalModelArtifactConfig): string | null;
+export declare const defaultLocalModelStore: LocalModelStore;
+export declare const defaultLocalModelDownloadTransport: LocalModelDownloadTransport;
+export interface LocalModelProcessPuller {
+    pull(model: string, localOllamaHost?: string): Promise<void>;
+}
+type SpawnOllamaPull = typeof spawn;
+export declare class OllamaProcessPuller implements LocalModelProcessPuller {
+    private readonly command;
+    private readonly spawnPull;
+    constructor(command?: string, spawnPull?: SpawnOllamaPull);
+    pull(model: string, localOllamaHost?: string): Promise<void>;
+}
+/**
+ * Build the Ollama runtime config for a pull that HONORS the caller's `model` argument
+ * (the config/CLI is authoritative), sourcing host + timeout from env. Without this, the
+ * pullers re-read `CODEVIBE_LOCAL_MODEL_OLLAMA_MODEL` from env — which is UNSET on a bare
+ * `codevibe model install`, so the capability-resolved default (12B/8B) would never reach
+ * the puller and the install would throw. For an explicit install the arg equals the env
+ * model → identical result. Host (default 127.0.0.1) + timeout (default) resolve when unset.
+ */
+export declare function ollamaEnvForModel(model: string, baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Fill an env-derived artifact config's `ollamaModel` + `artifactId` from PERSISTED state
+ * when env didn't supply them — so a bare `codevibe model install` (which recorded the
+ * resolved model in state) is usable by the shell + status/enable/warm without the user
+ * setting `CODEVIBE_LOCAL_MODEL_OLLAMA_MODEL`. Env ALWAYS wins (explicit override); state
+ * only fills the gaps, and only when a model was actually installed (`choice === 'enabled'`).
+ */
+export declare function applyPersistedSelection(config: LocalModelArtifactConfig, state: Pick<LocalModelState, 'choice' | 'artifactId' | 'ollamaModel'>): LocalModelArtifactConfig;
+export declare class DefaultOllamaPuller implements LocalModelProcessPuller {
+    private readonly httpPuller;
+    private readonly processPuller;
+    constructor(httpPuller?: LocalModelProcessPuller, processPuller?: LocalModelProcessPuller);
+    pull(model: string): Promise<void>;
+}
+export declare class OllamaLocalModelInstaller implements LocalModelInstaller {
+    private readonly puller;
+    constructor(puller?: LocalModelProcessPuller);
+    install(config: LocalModelArtifactConfig): Promise<void>;
+}
+export declare class HttpsLocalModelInstaller implements LocalModelInstaller {
+    private readonly transport;
+    constructor(transport?: LocalModelDownloadTransport);
+    install(config: LocalModelArtifactConfig): Promise<void>;
+    private tryDigestExistingArtifact;
+}
+export declare const defaultLocalModelInstaller: LocalModelInstaller;
+export declare const defaultLocalModelRuntimeFactory: LocalModelRuntimeFactory;
+export declare function runLocalModelCommand(options: RunLocalModelCommandOptions): Promise<number>;
+export {};

package/dist/local-model/ollama.d.ts

@@ -0,0 +1,27 @@
+import type { PlannerProbeResult } from '../planner/adapter';
+import type { LocalGemmaAdvisoryOptions } from '../planner/local-advisory';
+import type { LocalGemmaPlannerRunner } from '../planner/local-gemma';
+export interface OllamaRuntimeConfig {
+    model: string;
+    host: string;
+    timeoutMs: number;
+}
+export type OllamaRuntimeConfigResult = {
+    ok: true;
+    config: OllamaRuntimeConfig;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function isSafeOllamaModelName(model: string | null | undefined): model is string;
+export declare function parseLocalOllamaHost(raw: string | undefined): string | null;
+export declare function loadOllamaRuntimeConfigFromEnv(env?: NodeJS.ProcessEnv): OllamaRuntimeConfigResult;
+export declare function requestOllamaPull(config: OllamaRuntimeConfig): Promise<void>;
+export declare class OllamaGemmaPlannerRunner implements LocalGemmaPlannerRunner {
+    private readonly config;
+    readonly runtimeLabel: string;
+    constructor(config: OllamaRuntimeConfig);
+    classify(promptText: string): Promise<string>;
+    generateAdvisory(promptText: string, options?: LocalGemmaAdvisoryOptions): Promise<string>;
+    probe(): Promise<PlannerProbeResult>;
+}

package/dist/local-model/runtime.d.ts

@@ -0,0 +1,27 @@
+import type { PlannerProbeResult } from '../planner/adapter';
+import type { LocalGemmaAdvisoryOptions } from '../planner/local-advisory';
+import type { LocalGemmaPlannerRunner } from '../planner/local-gemma';
+export interface LocalGemmaRuntimeConfig {
+    command: string;
+    args: string[];
+    modelPath: string;
+    timeoutMs: number;
+    env: NodeJS.ProcessEnv;
+}
+export type LocalGemmaRuntimeConfigResult = {
+    ok: true;
+    config: LocalGemmaRuntimeConfig;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function loadLocalGemmaRuntimeConfigFromEnv(modelPath: string, env?: NodeJS.ProcessEnv): LocalGemmaRuntimeConfigResult;
+export declare class LocalGemmaProcessRunner implements LocalGemmaPlannerRunner {
+    private readonly config;
+    readonly runtimeLabel: string;
+    constructor(config: LocalGemmaRuntimeConfig);
+    classify(promptText: string): Promise<string>;
+    generateAdvisory(promptText: string, options?: LocalGemmaAdvisoryOptions): Promise<string>;
+    probe(): Promise<PlannerProbeResult>;
+    private invoke;
+}

package/dist/local-model/state.d.ts

@@ -0,0 +1,32 @@
+export type LocalModelChoice = 'not_configured' | 'skipped' | 'enabled';
+export interface LocalModelState {
+    schemaVersion: 1;
+    choice: LocalModelChoice;
+    artifactId: string | null;
+    /**
+     * The installed Ollama model tag (e.g. `gemma4:12b-it-qat`), persisted so a BARE
+     * `codevibe model install` (which resolves the model dynamically, not from env) is
+     * usable afterward — the shell + status/enable/warm resolve it from here when
+     * `CODEVIBE_LOCAL_MODEL_OLLAMA_MODEL` is unset. Null for non-Ollama / legacy state.
+     */
+    ollamaModel: string | null;
+    updatedAt: string;
+}
+export interface LocalModelStateStore {
+    read(): Promise<LocalModelState>;
+    write(state: LocalModelState): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function defaultLocalModelState(): LocalModelState;
+export declare function localModelStateFilePath(env?: NodeJS.ProcessEnv): string;
+export declare class FileSystemLocalModelStateStore implements LocalModelStateStore {
+    private readonly filePath;
+    constructor(filePath?: string);
+    read(): Promise<LocalModelState>;
+    write(state: LocalModelState): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare const defaultLocalModelStateStore: LocalModelStateStore;
+export declare function readLocalModelState(store?: LocalModelStateStore): Promise<LocalModelState>;
+export declare function markLocalModelEnabled(artifactId: string | null, ollamaModel?: string | null, store?: LocalModelStateStore): Promise<void>;
+export declare function markLocalModelSkipped(store?: LocalModelStateStore): Promise<void>;

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,6 +1,7 @@
 import { Logger } from '../logger';
 import { AppSyncClient } from '../appsync';
-export type DetectableAgent = 'CLAUDE' | 'GEMINI' | 'CODEX';
+import { CapabilityRegistry } from '../adapter/capabilities';
+export type DetectableAgent = 'CLAUDE' | 'GEMINI' | 'CODEX' | 'ANTIGRAVITY';
 /**
  * Returns the subset of agents present on PATH. Uses `command -v`
  * (POSIX-standard) rather than `which` for portability across macOS
@@ -21,12 +22,25 @@ export declare function detectInstalledAgents(): DetectableAgent[];
  * and log but not abort startup — Quorum 2.0 auto-enable degrades
  * to "use last-pushed agent set" when the mutation fails).
  *
+ * CP-1.f LOCK RP-3 — `replace` semantics. `User.availableAgents` is a
+ * cross-device UNION by default (`replace=false`), which never removes a
+ * stale agent (a `GEMINI` from a prior device/install would linger and
+ * get composed into the reviewer panel → `spawn gemini ENOENT`). The
+ * orchestration shell passes `replace=true` so the stored set is EXACTLY
+ * the current orchestration host's installed agents, AND — also per
+ * RP-3 — always writes even on zero detection (no skip-on-empty) so a
+ * stale set cannot linger. The 1.x companion-daemon callers keep the
+ * default `replace=false` (union) path, preserving their contract.
+ *
  * @param client  AppSyncClient that's already been authenticated via
  *                authenticateWithStoredTokens()
  * @param log     Logger — warn-level when no agents detected, info
  *                on success
+ * @param replace When true (orchestration shell), REPLACE the stored set
+ *                with exactly the detected set and write even when empty.
+ *                Default false (1.x companion union path).
  */
-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[], replace?: boolean): 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;

package/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/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 {};