@quantiya/codevibe-core 1.0.23 → 2.0.1

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

@@ -0,0 +1,57 @@
+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`
+ * (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'>, 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`,
+ * `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/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, type V1OrchestrationOption, type V1UserDecisionKind, } from './v1-options';

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