@quantiya/codevibe-core 2.0.0 → 2.0.1

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

@@ -1,4 +1,5 @@
 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,7 +57,29 @@ 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;
     private deviceKeyWatcher;
+    private sessionUpdateWatchers;
     private environment;
     constructor();
     /**
@@ -26,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
      */
@@ -34,6 +122,47 @@ export declare class AppSyncClient {
      * Refresh expired tokens
      */
     private refreshTokens;
+    /**
+     * Do the work of refreshing tokens. Tries the caller-supplied tokens
+     * first; on failure, re-reads from storage and retries once with a
+     * potentially-fresher refresh token. This is the self-healing path
+     * that lets `codevibe login` (which writes new tokens to the
+     * keychain) recover running daemons without requiring a restart:
+     * the in-memory copy the daemon cached at boot may be invalid, but
+     * whatever the user just wrote from the login flow is still valid.
+     *
+     * Splitting the two attempts into a pure-network helper keeps the
+     * orchestration readable without duplicating the fetch + body-shape
+     * plumbing.
+     */
+    private performRefresh;
+    /**
+     * POST to Cognito's /oauth2/token with a refresh_token grant.
+     * Returns the parsed body on 200, or null on any failure (network
+     * error, non-2xx response, JSON parse failure). Caller decides how
+     * to proceed — this helper is side-effect-free beyond logging.
+     */
+    private callCognitoRefresh;
+    /**
+     * Apply a successful refresh response: update in-memory cache first,
+     * clear the backoff sentinel, then persist to storage. Success here
+     * is defined as "the process has usable fresh tokens in memory" —
+     * storage persistence is degraded-success, not a failure mode.
+     *
+     * Ordering matters. The API call to Cognito already succeeded, which
+     * means we hold valid access/id tokens right now. If we delayed the
+     * in-memory update until after persistence and the keychain write
+     * threw (keychain locked, disk full, file-backend permission error),
+     * we'd be stuck with stale-and-known-dead tokens in memory while
+     * holding valid fresh tokens in local scope that vanish at the end
+     * of this function. That would re-break both guarantees this hotfix
+     * makes: no-restart recovery becomes "restart required to escape
+     * the keychain-lock window," and backoff stays unarmed so the
+     * caller hot-loops against a working Cognito endpoint — R1's MEDIUM
+     * on round 1 of this review. Persistence-failure is loud-logged
+     * so operators can see degraded durability without losing availability.
+     */
+    private applyRefreshedTokens;
     /**
      * Check if authenticated
      */
@@ -70,10 +199,69 @@ export declare class AppSyncClient {
      * List events for a session
      */
     listEvents(sessionId: string, source?: EventSource, limit?: number): Promise<Event[]>;
+    /**
+     * List the authenticated user's sessions. Paginates automatically
+     * via nextToken so callers always get the complete set.
+     */
+    listSessions(limit?: number): Promise<Array<{
+        sessionId: string;
+        agentType: string;
+        status: string;
+        lastHeartbeatAt: string | null;
+    }>>;
+    /**
+     * Mark stale ACTIVE sessions of a given agentType INACTIVE so they
+     * stop appearing in the mobile app's session list. Called at daemon
+     * startup to clean up after daemons that died without running their
+     * graceful shutdown (crash, auth-loop death, force-kill, power loss).
+     *
+     * Staleness rule: lastHeartbeatAt is older than `staleThresholdMs`
+     * (default 15 min — a conservative ~7.5× the 2-min heartbeat
+     * interval, giving legitimately-active daemons on other machines
+     * ample margin before we consider their session abandoned).
+     *
+     * Safety:
+     *   - Only sessions with status === 'ACTIVE' are candidates.
+     *   - Sessions explicitly listed in `excludeSessionIds` are skipped
+     *     (caller can pass the session the daemon is about to attach to
+     *     if the ID is known before the sweep).
+     *   - Absent `lastHeartbeatAt` (never-heartbeated sessions — should
+     *     only happen for rows created within the last few seconds)
+     *     treats the session as fresh and skips.
+     *   - updateSession failures are logged as warnings and don't abort
+     *     the sweep — best-effort cleanup.
+     *
+     * Returns the number of sessions actually marked INACTIVE.
+     */
+    sweepOrphanSessions(opts: {
+        agentType: string;
+        staleThresholdMs?: number;
+        excludeSessionIds?: string[];
+    }): Promise<number>;
     /**
      * 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
      */
@@ -101,6 +289,18 @@ export declare class AppSyncClient {
      * 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
@@ -109,12 +309,140 @@ export declare class AppSyncClient {
      * 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
      */
     subscribeToEvents(sessionId: string, onEvent: (event: Event) => void, onError?: (error: Error) => void): () => void;
     /**
      * Build WebSocket URL
+     *
+     * AppSync exposes the realtime endpoint two different ways depending on
+     * the GraphQL endpoint shape:
+     *
+     *   1. Direct AppSync URL (`<id>.appsync-api.<region>.amazonaws.com`):
+     *      realtime is on a sibling subdomain — swap `appsync-api` →
+     *      `appsync-realtime-api` and keep the `/graphql` path.
+     *      → wss://<id>.appsync-realtime-api.<region>.amazonaws.com/graphql
+     *
+     *   2. Custom domain (`api.codevibe.quantiya.ai` and friends):
+     *      realtime is path-based on the SAME hostname — append `/realtime`
+     *      to the GraphQL path.
+     *      → wss://api.codevibe.quantiya.ai/graphql/realtime
+     *      AWS docs:
+     *        https://docs.aws.amazon.com/appsync/latest/devguide/custom-domain-name.html
+     *
+     * The naive `.replace('appsync-api', 'appsync-realtime-api')` only works
+     * for path 1; on a custom-domain URL it doesn't match anything and the
+     * resulting `wss://<custom>/graphql` URL never completes the handshake.
      */
     private buildRealtimeUrl;
     /**
@@ -153,6 +481,53 @@ export declare class AppSyncClient {
     private sendDeviceKeyWatcherStart;
     private resetDeviceKeyWatcherKeepAlive;
     private handleDeviceKeyWatcherError;
+    /**
+     * Subscribe to status changes on our own session and invoke
+     * onMobileEndRequested when status transitions to INACTIVE — typically
+     * meaning the user tapped "End Session" in the mobile app.
+     *
+     * The callback is invoked from the WebSocket message handler. The
+     * helper catches and logs WARN any error thrown by the callback so it
+     * does not propagate to the subscription handler (would tear down the
+     * WebSocket).
+     *
+     * Returns a stop() function the plugin MUST call BEFORE issuing its
+     * own updateSession({ status: INACTIVE }) mutation in the per-session
+     * cleanup handler — otherwise the desktop's own end-of-session
+     * mutation echoes back through this subscription as a self-caused
+     * callback. See §D.3.a in the design doc. Calling stop() more than
+     * once is idempotent.
+     *
+     * Replace-on-duplicate-sessionId semantics: calling watchForMobileEnd
+     * twice with the same sessionId stops the prior watcher and replaces
+     * it with the new one, so at most one watcher is alive per sessionId.
+     * Matches subscribeToEvents (above). Plugins should still call once
+     * per session lifecycle; the replace path exists to make resume /
+     * re-entry safe.
+     *
+     * Initial state assumed = ACTIVE: AppSync subscriptions are
+     * mutation-triggered (NOT current-state snapshots), and plugins only
+     * call this for sessions just created or resumed in ACTIVE state. The
+     * first delivered status=INACTIVE payload IS the real signal and
+     * fires the callback.
+     *
+     * Idempotent firing: callback fires AT MOST ONCE per helper instance.
+     * Subsequent INACTIVE payloads (or any payload after fire) are
+     * ignored. Plugin must rebuild the helper for a new session.
+     */
+    watchForMobileEnd(sessionId: string, onMobileEndRequested: () => Promise<void> | void): {
+        stop: () => void;
+    };
+    private createSessionUpdateWatcherConnection;
+    /**
+     * Process a delivered onSessionUpdated payload. Decides whether to
+     * fire the callback per the locked rules in §A.2 of the design doc.
+     */
+    private handleSessionUpdatePayload;
+    private sendSessionUpdateWatcherStart;
+    private resetSessionUpdateWatcherKeepAlive;
+    private handleSessionUpdateWatcherError;
+    private cleanupSessionUpdateWatcherState;
     private heartbeatTimers;
     /**
      * Start periodic heartbeat for a session.
@@ -171,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,16 @@ 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
+     * for the INACTIVE mutation, agentType for the per-plugin filter,
+     * status to skip non-ACTIVE rows, and lastHeartbeatAt for the age
+     * check.
+     */
+    listSessions: string;
+    getSubscriptionStatus: string;
 };
 export declare const mutations: {
     createSession: string;
@@ -12,9 +22,14 @@ export declare const mutations: {
     grantSessionKey: string;
     getAttachmentDownloadUrl: string;
     updateAvailableAgents: string;
+    updateAdapterCapabilities: string;
     updateReviewerPolicy: string;
+    classifyPlannerPrompt: string;
+    pingPlanner: string;
+    applyUserDecision: string;
 };
 export declare const subscriptions: {
     onEventCreated: string;
     onDeviceKeyRegistered: string;
+    onSessionUpdated: 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
@@ -40,10 +58,29 @@ export declare function fireAuthCompletedBeacon(userId: string): Promise<void>;
  * `reason` is constrained to the `AuthFailureReason` union — this
  * is the ONLY input path; passing a raw error message is a compile
  * error.
+ *
+ * Optional `errorFragment` is a diagnostic dimension reserved for
+ * `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 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)
+ * Reports concatenate both dims for display. Mirrors the install.sh
+ * `sanitize_fragment` / `sanitize_fragment_tail` shell helpers so
+ * fragments fired from either path follow the same redaction +
+ * slicing contract.
  */
 export declare function fireAuthFailedBeacon(reason: AuthFailureReason, extra?: {
     httpStatus?: number;
     stage?: AuthStage;
+    errorFragment?: string;
 }): Promise<void>;
 /**
  * Attach the reason + beaconed marker to an Error. Non-enumerable so
@@ -54,3 +91,59 @@ export declare function markErrorBeaconed(err: Error, reason: AuthFailureReason)
 export declare function errorWasBeaconed(err: unknown): boolean;
 /** Retrieve the tagged reason from a previously-marked error, if any. */
 export declare function getErrorReason(err: unknown): AuthFailureReason | undefined;
+export type DeviceCountBucket = '0' | '1' | '2-5' | '6+';
+/**
+ * Bucket a raw device count into a coarse range to prevent device-count
+ * fingerprinting via GA4 client_id stickiness. The `'0'` bucket exists as
+ * a safe default for callers that may pass 0; no current emitter actually
+ * fires with count 0 in production paths.
+ */
+export declare function bucketDeviceCount(count: number): DeviceCountBucket;
+/**
+ * SHA-256-truncate a sessionId for cross-beacon correlation without leaking
+ * the raw UUID. 8 hex chars = 32 bits ⇒ no practical reverse lookup absent
+ * a GA4 + DDB join.
+ */
+export declare function hashSessionId(sessionId: string): string;
+/**
+ * Bug B per-device: fired inside `createSessionKey`'s per-device catch.
+ * `session_hash` is optional because keychain-manager intentionally does
+ * not know which session is being keyed — the per-session aggregate in
+ * `fireSessionEncryptionPartialSuccessBeacon` provides the correlation.
+ */
+export declare function fireSessionEncryptionDeviceSkippedBeacon(params: {
+    skipped_count_bucket: DeviceCountBucket;
+    session_hash?: string;
+}): Promise<void>;
+/**
+ * Bug B per-session: fired once per session creation when at least one
+ * device was skipped. Caller MUST gate on `skippedDeviceIds.length > 0`.
+ */
+export declare function fireSessionEncryptionPartialSuccessBeacon(params: {
+    session_hash: string;
+    encrypted_count_bucket: DeviceCountBucket;
+    skipped_count_bucket: DeviceCountBucket;
+}): Promise<void>;
+/**
+ * Bug A2: fired when `rekeySessionForNewDevices` grants ≥1 device on resume.
+ * Caller MUST gate on `grantedCount > 0`.
+ */
+export declare function fireSessionEncryptionCatchUpGrantBeacon(params: {
+    session_hash: string;
+    granted_count_bucket: DeviceCountBucket;
+}): Promise<void>;
+/** Bug A1: fired when we enter the self-rekey path (our deviceId missing). */
+export declare function fireSessionEncryptionSelfRekeyRequestBeacon(params: {
+    session_hash: string;
+    other_device_count_bucket: DeviceCountBucket;
+}): Promise<void>;
+/** Bug A1: fired when polling resolves with our entry + decrypt succeeds. */
+export declare function fireSessionEncryptionSelfRekeySuccessBeacon(params: {
+    session_hash: string;
+    attempt_count: number;
+}): Promise<void>;
+/** Bug A1: fired when polling exhausts maxAttempts without our entry. */
+export declare function fireSessionEncryptionSelfRekeyTimeoutBeacon(params: {
+    session_hash: string;
+    attempt_count: number;
+}): Promise<void>;

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>;