@quantiya/codevibe-core 1.0.23 → 2.0.1

package/dist/appsync/appsync-client.d.ts

@@ -1,4 +1,5 @@
-import { CreateEventInput, CreateSessionInput, UpdateSessionInput, UpdateEventStatusInput, Event, Session, EventSource, DeviceKey, GrantSessionKeyInput } from '../types';
+import { CreateEventInput, CreateSessionInput, UpdateSessionInput, UpdateEventStatusInput, Event, Session, EventSource, DeviceKey, GrantSessionKeyInput, UpdateReviewerPolicyInput, UserReviewerPolicySnapshot } from '../types';
+import type { PostDecisionAction } from '../orchestration-shell/types';
 /**
  * Download URL response
  */
@@ -6,6 +7,47 @@ export interface DownloadUrlResponse {
     downloadUrl: string;
     expiresAt: string;
 }
+/**
+ * CP-1.b IMPL r2 M-4 — Typed GraphQL error that preserves AppSync's
+ * `errorType` and `extensions` fields, alongside the human-readable
+ * `message`. Stage 2 r1's `graphqlRequest()` threw a plain
+ * `Error("GraphQL error: <message>")` and silently dropped
+ * `errorType`, which broke `BackendPlannerClient.classifyTransportError`
+ * (it discriminates on `err.errorType` to separate
+ * `BudgetExceeded` / `TierGateRejected` from provider-health failures).
+ *
+ * Callers may catch this class to inspect `errorType` directly. Code
+ * paths that still parse error.message will continue to work because
+ * the message is unchanged ("GraphQL error: <message>").
+ */
+export declare class AppSyncGraphQLError extends Error {
+    readonly errorType?: string;
+    readonly extensions?: unknown;
+    readonly path?: unknown;
+    constructor(opts: {
+        message: string;
+        errorType?: string;
+        extensions?: unknown;
+        path?: unknown;
+    });
+}
+/**
+ * Discriminator for the most recent `authenticateWithStoredTokens()`
+ * failure. Lets callers distinguish a genuine "no tokens / refresh
+ * rejected" outcome from a transient network failure during the
+ * Cognito refresh-token POST.
+ *
+ * Stage 2 round-1 Codex M1: the production refresh path returns
+ * `false` on every error (including network blow-ups inside
+ * `callCognitoRefresh`'s catch block), so the wizard's auth-vs-network
+ * heuristic — which only ran on caught throws — never fired in
+ * production. Recording the kind on every false-return path lets
+ * `setup-bootstrap.ts:defaultClientFactory()` route network-shaped
+ * refresh failures to `subscription_status_network` (per §6 row
+ * "transient 5xx during refresh") instead of misleading the user with
+ * a "not signed in" abort.
+ */
+export type AuthFailureKind = 'no_tokens' | 'refresh_auth_rejected' | 'refresh_network';
 /**
  * AppSync GraphQL client with WebSocket subscriptions
  */
@@ -15,6 +57,24 @@ export declare class AppSyncClient {
     private currentEmail;
     private tokens;
     private activeSubscriptions;
+    /**
+     * Set by `authenticateWithStoredTokens()` on every false-return path
+     * (and reset to `null` on success). Read by callers (e.g., the
+     * wizard's `defaultClientFactory`) to discriminate auth-rejection
+     * vs network-failure without re-running the auth call. Stage 2
+     * round-1 Codex M1.
+     */
+    private lastAuthFailureKind;
+    /**
+     * Sentinel set inside `performRefresh` / `callCognitoRefresh` when
+     * the refresh round-trip fails with a network-shaped error (DNS,
+     * socket reset, fetch failed, 5xx). Reset to `false` at the start
+     * of each `performRefresh`. Read by `authenticateWithStoredTokens`
+     * to classify a `refreshTokens()=false` return as
+     * `refresh_network` vs `refresh_auth_rejected`. Internal — never
+     * exposed.
+     */
+    private lastRefreshNetworkError;
     private pendingRefresh;
     private lastRefreshFailureAt;
     private static readonly REFRESH_BACKOFF_MS;
@@ -30,6 +90,30 @@ export declare class AppSyncClient {
      * Get the current authenticated user email
      */
     getCurrentUserEmail(): string | null;
+    /**
+     * Returns the kind of the most recent
+     * `authenticateWithStoredTokens()` failure, or `null` if the call
+     * succeeded (or has never been called).
+     *
+     * Stage 2 round-1 Codex M1. Callers (today: `setup-bootstrap.ts
+     * :defaultClientFactory`) use this to distinguish network blow-ups
+     * during the Cognito refresh-token POST from genuine auth
+     * rejections. The wizard maps `'refresh_network'` to
+     * `subscription_status_network` (don't tell a signed-in user to
+     * re-login when their tokens are valid and the network is broken)
+     * and the other two kinds to `not_signed_in` (preserves
+     * pre-Codex-M1 behavior).
+     */
+    getLastAuthFailureKind(): AuthFailureKind | null;
+    /**
+     * Heuristic — does the error message look like a transient network
+     * failure rather than an auth-token rejection? Mirrors
+     * `setup-bootstrap.ts:isNetworkLikeError` byte-for-byte so the same
+     * classifier runs both inside the client (for refresh-path
+     * discrimination) and at the bootstrap boundary (for caught-throw
+     * routing). Stage 2 round-1 Codex M1.
+     */
+    private static isNetworkLikeMessage;
     /**
      * Authenticate using stored OAuth tokens from keychain
      */
@@ -158,6 +242,26 @@ export declare class AppSyncClient {
      * List user device keys
      */
     listUserDeviceKeys(): Promise<DeviceKey[]>;
+    /**
+     * CP-1.b IMPL r4 H-2 — list BACKEND_SERVICE device keys per design
+     * §4.9 schema delta bullet 5 + §6.1 service-device flow.
+     *
+     * Returns every device row with `kind = BACKEND_SERVICE` regardless of
+     * the caller's `userId` (the only such row in CP-1.b is the
+     * planner-proxy's ECDH P-256 keypair under `deviceId =
+     * planner-proxy-{env}`). Callers union this list with
+     * `listUserDeviceKeys()` when minting `encryptedKeys[]` for new
+     * sessions so the planner-proxy Lambda can decrypt session-bound
+     * payloads via ECDH+HKDF against its own private key.
+     *
+     * The backend resolver is auth-mode widened (`@aws_cognito_user_pools
+     * @aws_iam`) — Cognito callers query for the planner-proxy public key
+     * at session-creation time; IAM callers (planner-proxy bootstrap) may
+     * also call. The CDK-backed GSI `kind-deviceId-index` partitions the
+     * device-keys table by `kind`, so this is a single GSI query, not a
+     * full scan.
+     */
+    listServiceDeviceKeys(): Promise<DeviceKey[]>;
     /**
      * Register device key
      */
@@ -178,6 +282,142 @@ export declare class AppSyncClient {
      * Get attachment download URL
      */
     getAttachmentDownloadUrl(s3Key: string): Promise<DownloadUrlResponse>;
+    /**
+     * Plugin startup pushes the user's locally-detected agents
+     * (`CLAUDE` / `GEMINI` / `CODEX`). Idempotent — safe to call every
+     * launch. Backend stores in `User.availableAgents`; used later to
+     * derive tier-default reviewer seat assignments.
+     */
+    updateAvailableAgents(agents: Array<'CLAUDE' | 'GEMINI' | 'CODEX'>): Promise<UserReviewerPolicySnapshot>;
+    /**
+     * CP-5.c — push the per-agent capability snapshot. Dual-write
+     * alongside `updateAvailableAgents` per LOCK #C5-C-4 (the legacy
+     * field stays for V1 client backward compat; this surface carries
+     * the full 9-field record per AgentKind).
+     *
+     * `capabilities` is serialized to JSON before transit (AppSync
+     * accepts `AWSJSON` as a stringified payload). Backend Lambda
+     * persists to `Users.adapterCapabilities` and returns the updated
+     * User row.
+     */
+    updateAdapterCapabilities(capabilities: unknown[]): Promise<UserReviewerPolicySnapshot>;
+    /**
+     * Persist the user's orchestration opt-in default and/or custom
+     * reviewer panel. Backend validates seat-count against tier, seat_id
+     * uniqueness + range, and role uniqueness. Throws on validation
+     * failure — error message is user-facing (surfaced to the
+     * configure-reviewers wizard).
+     */
+    updateReviewerPolicy(input: UpdateReviewerPolicyInput): Promise<UserReviewerPolicySnapshot>;
+    /**
+     * Fetch the user's subscription tier + status. Used by the Phase 3.a
+     * setup wizard (#190) at bootstrap to gate Free → upgrade interstitial
+     * and to size the seat budget (Pro=2, Max=3).
+     *
+     * Backend resolver returns a default FREE row when the user has no
+     * Users-table entry yet (Lambda resolver — lambda/subscription/index.ts).
+     * Network failure / auth expiry surface as graphqlRequest exceptions.
+     */
+    getSubscriptionStatus(): Promise<{
+        tier: 'FREE' | 'PRO' | 'MAX';
+        status: 'ACTIVE' | 'EXPIRED' | 'GRACE_PERIOD' | 'BILLING_RETRY';
+        expiresAt: string | null;
+    }>;
+    /**
+     * CP-1.b IMPL r4 H-1 — `classifyPlannerPrompt` AppSync mutation.
+     *
+     * Implements `PlannerAppSyncTransport.classifyPlannerPrompt` from
+     * `codevibe-core/src/planner/client.ts`. Encrypted-input wire shape
+     * is locked at design §4.10 + §4.11: `prompt` is raw base64 AES-GCM
+     * ciphertext under the session key; `clarifications`, `sessionContext`,
+     * `budgetHint` are AWSJSON envelope strings of the form
+     * `'{"encrypted":"<base64 ciphertext>"}'`. Response `decision` is RAW
+     * base64 ciphertext (NOT envelope-wrapped) per LOCK #27.
+     *
+     * Typed errors (`BudgetExceeded`, `TierGateRejected`, etc.) surface
+     * via `AppSyncGraphQLError.errorType` so the planner client can
+     * discriminate policy events from provider-health failures per
+     * Stage 2 r2 M-3.
+     */
+    classifyPlannerPrompt(input: {
+        sessionId: string;
+        prompt: string;
+        clarifications: string;
+        sessionContext: string;
+        budgetHint: string;
+    }): Promise<{
+        decision: string;
+        cacheHit: boolean;
+        cacheKind: string | null;
+        serverLatencyMs: number;
+        providerUsed: string;
+    }>;
+    /**
+     * CP-1.b IMPL r4 H-1 — `pingPlanner` AppSync mutation.
+     *
+     * Implements `PlannerAppSyncTransport.pingPlanner`. Separate mutation
+     * from `classifyPlannerPrompt` per Stage A LOCK #31. Input carries
+     * only `sessionId` (no encryption, no clarifications, no budgetHint).
+     * Response shape `{ ok, ms }` ONLY (no `providerHealthState` —
+     * shell-side `PlannerHealthMachine` is the sole authority).
+     */
+    pingPlanner(input: {
+        sessionId: string;
+    }): Promise<{
+        ok: boolean;
+        ms: number;
+    }>;
+    /**
+     * CP-8 min Stage 1 R1 HIGH-1 closure (Hendry-approved 2026-05-19).
+     *
+     * Submits an orchestration gate-prompt decision (Path A FinalApproval
+     * or Path B Halted-resolution) to the engine and returns the typed
+     * `PostDecisionAction` reply.
+     *
+     * **Implementation deviation from `PHASE-CP-8-MIN-DESIGN.md` #C8M-6
+     * literal wording:** the design says "use `@quantiya/quorum-core`'s
+     * `applyUserDecision` SDK method." codevibe-core deliberately does
+     * NOT depend on `@quantiya/quorum-core` at runtime — see the
+     * structural-typing pattern at `src/orchestration/v1-options.ts:44-47`.
+     * The locked INVARIANT of #C8M-6 ("single typed transport surface,
+     * no direct GraphQL in the orchestration-shell tree") is honored by
+     * exposing this method here on codevibe-core's own AppSyncClient,
+     * which is THE desktop-side transport surface. Shape mirrors the
+     * quorum-core SDK at `client.ts:464-504` byte-for-byte:
+     *   - Wraps `notes` (when present) in `EncryptedPayloadInput`
+     *     (AES-256-GCM under the session key, base64 ciphertext +
+     *     `sessionId` + `keyVersion`).
+     *   - Uppercases `decision` to UPPER_SNAKE wire enum (matches the
+     *     SDK's `toWireEnum` pattern).
+     *   - Parses the `payload` AWSJSON string to the 4-variant
+     *     `PostDecisionAction` discriminated union.
+     *
+     * See `PHASE-CP-8-MIN-DESIGN.md` §4 #C8M-6 deviation footer for the
+     * sealed rationale.
+     *
+     * @param input Caller passes the lowercase TS `decision` kind (one of
+     *              the 7 `UserDecisionKind` values). Encoding to wire
+     *              UPPER_SNAKE happens here.
+     * @param sessionKeyBase64 Optional. REQUIRED only when `input.notes`
+     *              is provided — used to AES-GCM-encrypt the notes plaintext
+     *              under the session key. When `notes` is undefined, this
+     *              parameter is ignored.
+     * @returns Parsed `{ decision, postAction }` per the engine's reply.
+     *          `decision` is echoed in lowercase TS form for caller
+     *          ergonomics (e.g. dispatcher routing without re-mapping the
+     *          UPPER_SNAKE wire value).
+     */
+    applyUserDecision(input: {
+        gateId: string;
+        taskId: string;
+        sessionId: string;
+        currentRound: number;
+        decision: string;
+        notes?: string;
+    }, sessionKeyBase64?: string): Promise<{
+        decision: string;
+        postAction: PostDecisionAction;
+    }>;
     /**
      * Subscribe to events for a session
      */
@@ -306,4 +546,41 @@ export declare class AppSyncClient {
      * Cleanup all subscriptions and heartbeats
      */
     cleanupSubscriptions(): void;
+    /**
+     * Parse a raw `ClassBPacket.packetJson` AWSJSON string into the typed
+     * discriminated-union packet. Throws `Error` on malformed input — the caller
+     * (subscription handler in CP-2) bridges this to `onError` per §7.2.
+     *
+     * Exposed for unit testing per design §7.4 row 1
+     * (`appsync_client_subscribeToClassBPackets_parses_packetJson_into_typed_packet`).
+     */
+    parseClassBPacketPayload(packetJson: string): unknown;
+    /**
+     * Subscribe to AppSync `onClassBPacket(userId)` and dispatch typed packets
+     * to `onPacket`. Errors during parsing OR transport are forwarded to
+     * `onError`. Returns an unsubscribe handle.
+     *
+     * CP-1.e ships the handler surface + parser; full WebSocket wiring on the
+     * `subscribeToEvents`-style two-phase reconnect engine completes in CP-2
+     * Stage A when the hosted producer side comes online. Until then the method
+     * registers the handler and returns a working unsubscribe — callers (the
+     * orchestration shell) can wire it during CP-1.e bootstrap with no
+     * behavioral change once CP-2 lights up the wire.
+     */
+    subscribeToClassBPackets(userId: string, handlers: {
+        onPacket: (packet: unknown) => void | Promise<void>;
+        onError?: (err: Error) => void;
+    }): {
+        unsubscribe: () => Promise<void>;
+    };
+    /**
+     * Test seam — deliver a raw envelope payload to the registered handler.
+     * Used by §7.4 unit tests to assert parse + forward semantics without
+     * standing up a real WebSocket. Production code path (CP-2) will call the
+     * same internal flow.
+     *
+     * @internal
+     */
+    _deliverClassBPacketForTests(userId: string, rawPacketJson: string): Promise<void>;
+    private readonly classBPacketHandlers;
 }

package/dist/appsync/index.d.ts

@@ -1,2 +1,2 @@
-export { AppSyncClient, DownloadUrlResponse } from './appsync-client';
+export { AppSyncClient, AppSyncGraphQLError, DownloadUrlResponse } from './appsync-client';
 export { queries, mutations, subscriptions } from './queries';

package/dist/appsync/queries.d.ts

@@ -2,6 +2,7 @@ export declare const queries: {
     getSession: string;
     listEvents: string;
     listUserDeviceKeys: string;
+    listServiceDeviceKeys: string;
     /**
      * Minimal session listing used by the orphan-sweep path. Only the
      * fields needed to decide whether a session row is stale — sessionId
@@ -10,6 +11,7 @@ export declare const queries: {
      * check.
      */
     listSessions: string;
+    getSubscriptionStatus: string;
 };
 export declare const mutations: {
     createSession: string;
@@ -19,6 +21,12 @@ export declare const mutations: {
     registerDeviceKey: string;
     grantSessionKey: string;
     getAttachmentDownloadUrl: string;
+    updateAvailableAgents: string;
+    updateAdapterCapabilities: string;
+    updateReviewerPolicy: string;
+    classifyPlannerPrompt: string;
+    pingPlanner: string;
+    applyUserDecision: string;
 };
 export declare const subscriptions: {
     onEventCreated: string;

package/dist/audit-keys/__tests__/audit-keys-parity.test.d.ts

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

package/dist/audit-keys/index.d.ts

@@ -0,0 +1,41 @@
+export type Uuid = string;
+/**
+ * `TaskCreated` — one per task lifecycle. Identity: `(task_id, kind)`.
+ */
+export declare function dedupKeyForTaskCreated(taskId: Uuid): string;
+/**
+ * `TaskTerminated` — one per task lifecycle. Identity: `(task_id, kind)`.
+ */
+export declare function dedupKeyForTaskTerminated(taskId: Uuid): string;
+/**
+ * `ProgressEvent` — keyed on `(task_id, kind, caller_event_id)`.
+ *
+ * `callerEventId` is REQUIRED (no `Option<&str>` fallback per the
+ * 2f.2 §5.2 lock). Callers without a stable id must invent one
+ * (e.g., a UUID at emit time); silently deriving from payload
+ * bytes would re-introduce the dedup-drift bug the lock prevents.
+ */
+export declare function dedupKeyForProgressEvent(taskId: Uuid, callerEventId: string): string;
+/**
+ * `ToolUse` — keyed on `(task_id, kind, caller_event_id)`. Same
+ * REQUIRED-not-optional rule as `dedupKeyForProgressEvent`.
+ */
+export declare function dedupKeyForToolUse(taskId: Uuid, callerEventId: string): string;
+/**
+ * `DestructiveActionEscalated` — keyed on `(gate_id, kind, action_id)`.
+ *
+ * Multiple destructive actions can be escalated within one gate
+ * (e.g., a turn that proposes both `rm -rf` and `git push --force`).
+ * `actionId` is the engine's internal id for the specific
+ * destructive call (NOT the gate, NOT the round).
+ */
+export declare function dedupKeyForDestructiveActionEscalated(gateId: Uuid, actionId: string): string;
+/**
+ * `FlagBadApproval` — keyed on `(flagged_entry_id, kind)`.
+ *
+ * A user flagging the same prior approval twice should dedupe to
+ * one flag. The Rust formula identifies the flag by the audit
+ * entry being flagged (not by a synthesized "bad-approval id"
+ * passed alongside).
+ */
+export declare function dedupKeyForFlagBadApproval(flaggedEntryId: Uuid): string;

package/dist/auth/__tests__/auth-telemetry.test.d.ts

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

package/dist/auth/auth-telemetry.d.ts

@@ -1,11 +1,15 @@
 /**
  * Typed taxonomy of auth-flow failure reasons.
  *
- * Every value is a sanitized enum literal — never a raw error message,
- * never a truncated user input, never any byte from Cognito's response.
- * Adding a new failure mode means extending this union; the compiler
- * then forces every emit site to either use a known value or produce
- * a type error.
+ * Every value in THIS union is a sanitized enum literal — never a raw
+ * error message, never a truncated user input, never any byte from
+ * Cognito's response. Adding a new failure mode means extending this
+ * union; the compiler then forces every emit site to either use a known
+ * value or produce a type error.
+ *
+ * (Note: the `error_fragment` parameter on the auth_failed beacon DOES
+ * carry redacted error material — see `sanitizeAuthErrorFragment`. The
+ * `reason` taxonomy below remains the analytics-safe primary key.)
  *
  * Keep values snake_case to match GA4 custom-dimension conventions
  * used elsewhere in the codebase (`step`, `source`, `reason`).
@@ -29,6 +33,20 @@ export type AuthStage = 'server_start' | 'browser_open' | 'awaiting_callback' |
  * address.
  */
 export declare function fireAuthCompletedBeacon(userId: string): Promise<void>;
+/**
+ * Bytes 0-99 of the sanitized fragment (GA4 dim: error_fragment).
+ * See `sanitizeAuthErrorFragmentFull` for the redaction contract.
+ */
+export declare function sanitizeAuthErrorFragment(msg: string): string;
+/**
+ * Bytes 100-199 of the sanitized fragment (GA4 dim: error_fragment_2).
+ * Returns empty string when the redacted message is ≤100 chars (the
+ * typical short-error case), which is what we want — no
+ * `error_fragment_2` param fires unless there's something past byte
+ * 100 worth carrying. Works around GA4 Measurement Protocol's 100-char
+ * per-param limit.
+ */
+export declare function sanitizeAuthErrorFragmentTail(msg: string): string;
 /**
  * Fire the `auth_failed` failure beacon with a sanitized `reason`
  * literal. Optional `httpStatus` captures the numeric HTTP status
@@ -45,9 +63,12 @@ export declare function fireAuthCompletedBeacon(userId: string): Promise<void>;
  * `reason: 'unknown'`. The outer `auth-cli` catch passes the first
  * portion of `error.message` here so the next analytics pass can
  * see what's hiding in `unknown` and we can ship a typed reason in
- * a follow-up. Sanitized inside: ANSI escape sequences stripped,
- * newlines/tabs/quotes/backslashes replaced with spaces, non-ASCII
- * dropped, then split into two GA4 dimensions to work around the
+ * a follow-up. Sanitized inside via `sanitizeAuthErrorFragment` (head)
+ * + `sanitizeAuthErrorFragmentTail` (tail) — ANSI stripped, $HOME /
+ * USERPROFILE / `/Users/<name>/` / `/home/<name>/` / email substrings
+ * redacted (Windows backslashes normalized first so `C:\Users\Alice\…`
+ * matches the same path regex as POSIX form), control + non-ASCII
+ * bytes dropped, then split into two GA4 dimensions to work around the
  * Measurement Protocol 100-char per-param limit:
  *   - `error_fragment`   = bytes 0-99
  *   - `error_fragment_2` = bytes 100-199 (only set when input >100 chars)

package/dist/companion-mode/__tests__/persist-preference.test.d.ts

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

package/dist/companion-mode/__tests__/resolve-agent.test.d.ts

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

package/dist/companion-mode/agent-picker.d.ts

@@ -0,0 +1,9 @@
+import { DetectedAgent } from './resolve-agent';
+export interface PickAgentArgs {
+    healthy: DetectedAgent[];
+    defaultIndex: number;
+    /** Test seam — override stdin/stdout. */
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}
+export declare function pickAgent(args: PickAgentArgs): Promise<DetectedAgent>;

package/dist/companion-mode/index.d.ts

@@ -0,0 +1,55 @@
+import { DetectableAgent } from '../orchestration/detect-agents';
+import type { ShellEventEmit } from '../orchestration-shell/emit-shell-event';
+import type { Session } from '../types';
+export declare class NoAgentInstalledError extends Error {
+    constructor(message: string);
+}
+export interface CompanionArgs {
+    /** Optional `--agent <kind>` CLI override. */
+    agent?: DetectableAgent;
+    /** Args to pass through to the agent wrapper. */
+    passthrough: string[];
+    /** When set, clears the persisted preference before resolving. */
+    forgetAgent?: boolean;
+    /**
+     * Session context for §3 emitShellEvent fan-out. When provided
+     * together with `emitter`, MODE_SELECTED is emitted before the exec
+     * handoff. When either is omitted, the emit is skipped — Companion
+     * Mode is functional without it because the cohort flag gates every
+     * emit anyway (CP-1.a default OFF). Per Stage 1 r1 HIGH-3.
+     */
+    session?: Session;
+    /**
+     * Bound emitter (typically `createShellEventEmitter(appsyncClient)`).
+     * Required for the MODE_SELECTED emit when `session` is also set.
+     */
+    emitter?: (args: ShellEventEmit) => Promise<void>;
+    /** Test seam — override the `execFileSync` handoff. */
+    execFile?: (binPath: string, args: string[], options: {
+        stdio: 'inherit';
+    }) => void;
+    /** Test seam — override `detectInstalledAgents`. */
+    detect?: () => DetectableAgent[];
+    /** Test seam — override bin-path resolver (real impl uses `command -v`). */
+    resolveBinPath?: (kind: DetectableAgent) => string | null;
+    /**
+     * Test seam — override the `<wrapper> --version` 2s health-probe
+     * (§4 line 280). Real impl spawns the wrapper with a SIGKILL on
+     * timeout. Per Stage 2 r1 Codex MEDIUM-2.
+     */
+    versionProbe?: (binPath: string) => Promise<boolean>;
+}
+/**
+ * §4 LOCK lines 232-273. Detect → resolve → persist → exec.
+ *
+ * On a TTY with multiple agents, this calls `pickAgent` for the
+ * interactive readline picker. The function does NOT mount the Ink
+ * TUI — Companion Mode does not need it (the picker hands terminal
+ * control directly to the wrapper).
+ *
+ * NOTE: the function returns when the test seam `execFile` is
+ * provided; in production the `execFileSync` call replaces the process
+ * (`stdio: 'inherit'`) so `process.exit(0)` is unreachable but kept
+ * as a defensive fallback (§4 line 273).
+ */
+export declare function runCompanionMode(args: CompanionArgs): Promise<void>;

package/dist/companion-mode/persist-preference.d.ts

@@ -0,0 +1,24 @@
+export declare function companionPreferenceFilePath(): string;
+export interface CompanionPreference {
+    lastAgent: 'CLAUDE' | 'GEMINI' | 'CODEX';
+    lastUsedAt: string;
+}
+/**
+ * §4 lines 304-316 LOCK. Reads + validates the preference file.
+ * Returns `null` on every failure mode named in the design:
+ *   - file missing
+ *   - loose permissions (any group/world bits set)
+ *   - malformed JSON
+ *   - schema mismatch
+ */
+export declare function readCompanionPreference(): Promise<CompanionPreference | null>;
+/**
+ * Writes the preference file with mode 0600. Creates parent dir if
+ * missing. Self-heals loose perms (writes 0o600 explicitly on every
+ * write).
+ */
+export declare function persistCompanionPreference(pref: CompanionPreference): Promise<void>;
+/**
+ * Clears the preference file (used by `--forget-agent` flag per §4).
+ */
+export declare function clearCompanionPreference(): Promise<void>;

package/dist/companion-mode/resolve-agent.d.ts

@@ -0,0 +1,41 @@
+import { DetectableAgent } from '../orchestration/detect-agents';
+export interface DetectedAgent {
+    kind: DetectableAgent;
+    binPath: string;
+    healthy: boolean;
+}
+export interface ResolveAgentArgs {
+    /** Healthy agents detected on PATH. */
+    healthy: DetectedAgent[];
+    /** `--agent` CLI flag override (if any). */
+    flag?: DetectableAgent;
+    /** Persisted preference from `readCompanionPreference()` (if any). */
+    preferred?: DetectableAgent;
+}
+export interface ResolveAgentResult {
+    /** When a single resolved agent exists. */
+    agent?: DetectedAgent;
+    /** When multiple healthy agents exist and the picker should run. */
+    needsPicker?: {
+        healthy: DetectedAgent[];
+        defaultIndex: number;
+    };
+    /** When the flag asked for an agent that's not healthy. */
+    flagMissing?: {
+        requested: DetectableAgent;
+    };
+}
+/**
+ * §4 resolution order LOCK:
+ *   1. flag > preference > picker > single-agent fast-path
+ *
+ *   - If `flag` is set and a matching healthy agent exists → return it.
+ *   - If `flag` is set and no matching healthy agent → `flagMissing`.
+ *   - Single-agent fast-path: exactly 1 healthy agent → return it
+ *     (regardless of preference).
+ *   - Multiple healthy + `preferred` set + matches → picker with that
+ *     row pre-selected (caller may decide to auto-accept).
+ *   - Multiple healthy + no preference → picker with first row
+ *     pre-selected.
+ */
+export declare function resolveAgent(args: ResolveAgentArgs): ResolveAgentResult;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { KeychainManager, keychainManager, KeychainError } from './keychain';
 export { CryptoService, cryptoService, CryptoError, ENCRYPTION_VERSION } from './crypto';
-export { AppSyncClient, DownloadUrlResponse } from './appsync';
+export { AppSyncClient, AppSyncGraphQLError, DownloadUrlResponse } from './appsync';
 export { queries, mutations, subscriptions } from './appsync';
 export { AuthService, authService } from './auth';
 export { runAuthCli } from './auth';
@@ -13,4 +13,16 @@ export { parseInteractivePrompt, normalizeSnapshot, } from './prompt-parser';
 export type { ParsedInteractivePrompt, PromptKind, InteractivePromptOption, } from './prompt-parser';
 export { resumeOrCreateSession, prepareSessionEncryption, rekeySessionForNewDevices, startDeviceKeyWatcher, registerDeviceEncryptionKey, } from './session';
 export type { ResumeOrCreateSessionInput, ResumeOrCreateSessionResult } from './session';
+export { detectInstalledAgents, pushDetectedAgents, applyPerSessionOrchestrationOverride, runOrchestrationCli, V1_ORCHESTRATION_PROMPT_KIND, V1_ORCHESTRATION_OPTIONS, mapOptionNumberToUserDecisionKind, mapOptionToUserDecisionKind, } from './orchestration';
+export type { DetectableAgent, V1OrchestrationOption, V1UserDecisionKind, } from './orchestration';
+export * as Reviewer from './reviewer';
+export * as AuditKeys from './audit-keys';
 export * from './types';
+export * as Planner from './planner';
+export * as StructuralSummary from './structural-summary';
+export { runOrchestrationShell } from './orchestration-shell';
+export { runCompanionMode } from './companion-mode';
+export { pickMode, TierError } from './orchestration-shell';
+export { emitShellEvent, createShellEventEmitter } from './orchestration-shell';
+export { processMarkers, withRoleMarker } from './orchestration-shell';
+export type { Mode, Tier, PlannerDecision, AgentKind, PlannerHealthState, OrchestrationState, OrchestrationAction, ConversationEntry, RunningTaskState, ReviewerSeatState, GateState, ExecutionEventEntry, RefusalEventEntry, BypassEventEntry, MobileEventEntry, EventStreamEntry, QueuedTask, PendingClarification, LastModeFile, } from './orchestration-shell';