@quantiya/codevibe-core 2.0.5 → 2.0.7

package/README.md

@@ -1,13 +1,15 @@
 # @quantiya/codevibe-core
 
-Core library for CodeVibe plugins — shared keychain, crypto, AppSync, authentication, session lifecycle, and network-resilience functionality. Used by [`@quantiya/codevibe-claude-plugin`](https://www.npmjs.com/package/@quantiya/codevibe-claude-plugin), [`@quantiya/codevibe-gemini-plugin`](https://www.npmjs.com/package/@quantiya/codevibe-gemini-plugin), and [`@quantiya/codevibe-codex-plugin`](https://www.npmjs.com/package/@quantiya/codevibe-codex-plugin).
+Core library for CodeVibe plugins — shared keychain, crypto, AppSync,
+authentication, session lifecycle, and network-resilience functionality. Used
+by the Claude, Codex, and Antigravity Companion plugins.
 
-**Current version:** `1.0.3`
+**Current 2.x candidate:** `2.0.7` (`next`; 1.x remains `latest` until promotion)
 
 ## Installation
 
 ```bash
-npm install @quantiya/codevibe-core
+npm install @quantiya/codevibe-core@next
 ```
 
 ## Features
@@ -40,8 +42,8 @@ codevibe status
 # Reset device identity (destructive - old sessions become inaccessible)
 codevibe reset-device
 
-# Use specific environment
-codevibe --env development login
+# Use a non-production development environment
+ENVIRONMENT=development codevibe login
 ```
 
 ## API Usage

package/dist/agy-cli-contract.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared Antigravity 1.1.2 CLI constraints.
+ *
+ * Agy no longer accepts a one-shot prompt on stdin. The prompt must therefore
+ * be one argv value, which is both process-list-visible and subject to the
+ * platform's per-argument exec limit. Keep one conservative cross-platform
+ * ceiling for every Agy spawn surface and fail closed rather than truncating.
+ */
+export declare const AGY_ARG_PROMPT_MAX_UTF8_BYTES: number;
+export declare function validateAgyArgPrompt(prompt: string | undefined, context: string): string;
+/** Redact every Agy `--print` value before audit, shell metadata, or logging. */
+export declare function redactAgyPrintArgv(argv: readonly string[]): string[];
+/** Remove Agy prompt values from an error detail before it crosses a boundary. */
+export declare function redactAgyPrintValuesFromText(text: string, argv: readonly string[]): string;

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

@@ -76,6 +76,19 @@ export interface TaskGroupStatusResult {
     status: string;
     haltReason?: string;
 }
+/**
+ * A1e hosted blind-hold upload input. These are the ONLY client-supplied
+ * plaintext fields permitted by the shared-context ZK boundary. `expiresAt`
+ * is intentionally absent: AppSync derives it from the authoritative Session
+ * row so a stale/offline desktop cannot extend retention.
+ */
+export interface PutContextItemInput {
+    sessionId: string;
+    seq: string;
+    taskId?: string;
+    trackId?: string;
+    ciphertext: string;
+}
 /**
  * PHASE-CP-1-F.1 Part A (LOCK L2) — tolerant `AWSJSON!` object read.
  *
@@ -186,6 +199,12 @@ export declare class AppSyncGraphQLError extends Error {
         path?: unknown;
     });
 }
+export type AppSyncAuthenticationFailureKind = 'refresh_auth_rejected' | 'refresh_network';
+/** A foreground GraphQL 401 that token refresh could not recover. */
+export declare class AppSyncAuthenticationError extends Error {
+    readonly kind: AppSyncAuthenticationFailureKind;
+    constructor(kind: AppSyncAuthenticationFailureKind);
+}
 /**
  * PHASE-CP-10-MIN (#585) §2.3 — the parsed cross-device applyUserDecision
  * echo. Mirrors the quorum-core SDK's `UserDecisionAppliedEvent`
@@ -225,19 +244,16 @@ export declare function shouldDeliverSubscribedEvent(event: Pick<Event, 'source'
  * 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.
+ * Cognito refresh-token POST, or a credential-store failure that prevented
+ * the token read from completing.
  *
  * 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.
+ * `callCognitoRefresh`'s catch block). Recording the kind on every
+ * false-return path lets CLI callers distinguish a transient network
+ * failure from a genuine sign-in rejection.
  */
-export type AuthFailureKind = 'no_tokens' | 'refresh_auth_rejected' | 'refresh_network';
+export type AuthFailureKind = 'no_tokens' | 'refresh_auth_rejected' | 'refresh_network' | 'credential_storage_unavailable';
 /**
  * AppSync GraphQL client with WebSocket subscriptions
  */
@@ -250,8 +266,7 @@ export declare class AppSyncClient {
     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
+     * (and reset to `null` on success). Read by callers to discriminate auth-rejection
      * vs network-failure without re-running the auth call. Stage 2
      * round-1 Codex M1.
      */
@@ -288,23 +303,16 @@ export declare class AppSyncClient {
      * `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
+     * Stage 2 round-1 Codex M1. Callers 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).
+     * Credential-storage failure remains distinct because re-authentication
+     * cannot repair a locked or unavailable keyring.
      */
     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.
+     * failure rather than an auth-token rejection? Used for refresh-path
+     * discrimination. Stage 2 round-1 Codex M1.
      */
     private static isNetworkLikeMessage;
     /**
@@ -372,6 +380,13 @@ export declare class AppSyncClient {
      * Create a session
      */
     createSession(input: CreateSessionInput): Promise<Session>;
+    /**
+     * Blind-hold one canonical ContextItem. The mutation is idempotent only for
+     * an exact ciphertext+routing replay; a conflicting rewrite is rejected by
+     * the backend and therefore throws here, leaving the local durable outbox
+     * available for retry/diagnosis.
+     */
+    putContextItem(input: PutContextItemInput): Promise<void>;
     /**
      * Update a session
      */
@@ -402,6 +417,8 @@ export declare class AppSyncClient {
         agentType: string;
         status: string;
         lastHeartbeatAt: string | null;
+        createdAt: string | null;
+        updatedAt: string | null;
     }>>;
     /**
      * Mark stale ACTIVE sessions of a given agentType INACTIVE so they
@@ -409,19 +426,20 @@ export declare class AppSyncClient {
      * 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).
+     * Staleness rule: the newest usable timestamp among lastHeartbeatAt,
+     * createdAt, and updatedAt 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). createdAt/updatedAt cover a
+     * creator that dies before its first heartbeat.
      *
      * 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.
+     *   - A row with no parseable heartbeat/create/update timestamp is
+     *     skipped fail-safe; the sweeper never guesses its age.
      *   - updateSession failures are logged as warnings and don't abort
      *     the sweep — best-effort cleanup.
      *
@@ -922,6 +940,8 @@ export declare class AppSyncClient {
      */
     subscribeToEvents(sessionId: string, onEvent: (event: Event) => void, onError?: (error: Error) => void, options?: {
         receiveDesktopEvents?: boolean;
+        onSubscribed?: (isReconnect: boolean) => void;
+        onSessionRetired?: () => Promise<void> | void;
     }): () => void;
     /**
      * Build WebSocket URL
@@ -950,6 +970,7 @@ export declare class AppSyncClient {
      * Create WebSocket subscription
      */
     private createSubscription;
+    private handleSubscriptionStartAck;
     /**
      * Send subscription start message
      */
@@ -1059,11 +1080,17 @@ export declare class AppSyncClient {
     private handleApplyUserDecisionWatcherError;
     private cleanupApplyUserDecisionWatcherState;
     private heartbeatTimers;
+    /** Identity tokens invalidate in-flight pulses when a session is stopped. */
+    private heartbeatTokens;
+    /** Shared initial confirmation makes duplicate start calls idempotent. */
+    private heartbeatInitialPulses;
+    private heartbeatInitialOutcomes;
     /**
      * Start periodic heartbeat for a session.
      * Updates lastHeartbeatAt on the session every intervalMs (default 2 minutes).
      */
-    startHeartbeat(sessionId: string, intervalMs?: number): void;
+    startHeartbeat(sessionId: string, intervalMs?: number): Promise<boolean>;
+    private startHeartbeatOutcome;
     /**
      * Stop heartbeat for a session.
      */
@@ -1072,6 +1099,7 @@ export declare class AppSyncClient {
      * Send a single heartbeat update.
      */
     private sendHeartbeat;
+    private notifyRetiredSession;
     /**
      * Tear down the mobile-event subscription for a SINGLE session.
      *

package/dist/appsync/event-throttle.d.ts

@@ -1,3 +1,4 @@
+import type { Event } from '../types/events';
 /** Exposed for the single log line in createEvent. */
 export declare const CLIENT_THROTTLE_EVENTS_PER_WINDOW: number;
 interface RateWindow {
@@ -21,6 +22,38 @@ export declare function shouldSuppressEvent(sessionId: string, type: string, now
 export declare function consumeThrottleLogOnce(sessionId: string): RateWindow | undefined;
 /** Test-only: clears the per-process rate map. */
 export declare function resetThrottleState(): void;
+/**
+ * True iff a `createEvent` result is PROVEN durably persisted by the backend (a real
+ * stored Events row), as opposed to a NON-persisted synthetic acknowledgement that
+ * EITHER throttle layer returns over-cap:
+ *   - the CLIENT throttle above (`createEvent` short-circuit) → `eventId` prefixed
+ *     `local-throttled-`, no `writerAuthenticated`;
+ *   - the BACKEND Lambda's per-SESSION guardrail → fresh `generateId()`, no
+ *     `writerAuthenticated`;
+ *   - the BACKEND per-ACCOUNT guardrail → fresh `generateId()`, no
+ *     `writerAuthenticated` (its `rateLimitNotice` marker is not even in the
+ *     `createEvent` selection set, so it never reaches the client);
+ * none of which stored a row.
+ *
+ * The single reliable POSITIVE persistence signal is `writerAuthenticated`: the
+ * backend stamps it (a boolean — `false` for a non-writer emit, `true` for a writer-
+ * attested one) on EVERY persisted Event and returns it in the `createEvent`
+ * selection set (queries.ts). No synthetic populates it — the client synthetic omits
+ * it (→ `undefined`) and every backend synthetic omits it (→ `null` through GraphQL).
+ * `emittedBy` (the other persist-only attribute) is `EventAuthor!` (non-null) in the
+ * schema, so it CANNOT be selected on a mutation whose resolver may return a
+ * synthetic — a non-null field resolving to null would error the whole response —
+ * which is exactly why `writerAuthenticated` (nullable) is the only persist marker
+ * safely in the selection set. The `local-throttled-` guard is belt-and-suspenders.
+ *
+ * Deliberately CONSERVATIVE: returns true ONLY on positive proof, so any
+ * unrecognized / partial shape is treated as NOT-persisted. Callers use this to
+ * decide whether to record a legacy `TOOL_USE` id as "legacy-owned" (§4.8) — being
+ * wrong toward "not persisted" only forgoes a dedup (a cosmetic duplicate render),
+ * whereas being wrong toward "persisted" on a synthetic would suppress the
+ * consolidator re-derive and permanently SKIP the tool (G2). Never the latter.
+ */
+export declare function isPersistedEventResult(event: Pick<Event, 'eventId' | 'writerAuthenticated'> | null | undefined): boolean;
 /** Test-only: current size of the per-process rate map (eviction-bound check). */
 export declare function throttleMapSize(): number;
 /** Test-only: whether a session is currently tracked (eviction assertions). */

package/dist/appsync/index.d.ts

@@ -1,5 +1,6 @@
-export { AppSyncClient, AppSyncGraphQLError, DownloadUrlResponse } from './appsync-client';
+export { AppSyncClient, AppSyncAuthenticationError, AppSyncGraphQLError, DownloadUrlResponse, } from './appsync-client';
 export { coerceAwsJsonObject } from './appsync-client';
 export type { ClassBPacketEnvelopeMeta } from './appsync-client';
-export type { TaskReviewSummary, TaskReviewSummaryRound, TaskReviewSummaryReviewer, TaskGroupStatusResult, } from './appsync-client';
+export type { TaskReviewSummary, TaskReviewSummaryRound, TaskReviewSummaryReviewer, TaskGroupStatusResult, PutContextItemInput, } from './appsync-client';
 export { queries, mutations, subscriptions } from './queries';
+export { isPersistedEventResult } from './event-throttle';

package/dist/appsync/queries.d.ts

@@ -7,8 +7,9 @@ export declare const queries: {
      * 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.
+     * status to skip non-ACTIVE rows, lastHeartbeatAt for the usual age
+     * check, and createdAt/updatedAt as the startup-age fallback for rows
+     * whose creator died before its first heartbeat.
      */
     listSessions: string;
     getSubscriptionStatus: string;
@@ -23,6 +24,7 @@ export declare const queries: {
     getTaskReviewSummary: string;
 };
 export declare const mutations: {
+    putContextItem: string;
     createSession: string;
     updateSession: string;
     createEvent: string;

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

@@ -23,6 +23,31 @@ export type AuthFailureReason = 'port_in_use' | 'port_range_exhausted' | 'server
  * not user AFK).
  */
 export type AuthStage = 'server_start' | 'browser_open' | 'awaiting_callback' | 'exchanging_code' | 'storing_tokens' | 'unknown';
+/**
+ * Preserve the retired shell wrappers' exact activation-funnel identity.
+ * POSIX `echo` added a trailing newline before hashing, so omitting `\n` here
+ * would split the same machine across two GA4 client IDs after the A6 cutover.
+ */
+declare function getLegacyWrapperClientId(): string;
+/**
+ * Agent label used by the long-lived `wrapper_launched` activation-funnel
+ * event. Keep these values aligned with the historical public-wrapper event so
+ * the 2.x unified CLI continues the same GA4 series.
+ */
+export type CompanionActivationAgent = 'claude' | 'codex' | 'antigravity';
+declare function legacyWrapperBaseParams(): Record<string, string>;
+/**
+ * Preserve the final activation-funnel event after A6 retires the public
+ * `codevibe-*` wrappers. The unified Companion route calls this exactly once
+ * after resolving the selected agent and before handing off to its private
+ * launcher. The caller awaits the bounded best-effort transport before its
+ * synchronous child handoff blocks the event loop.
+ */
+export declare function fireWrapperLaunchedBeacon(agent: CompanionActivationAgent): Promise<void>;
+export declare const __testing: {
+    getLegacyWrapperClientId: typeof getLegacyWrapperClientId;
+    legacyWrapperBaseParams: typeof legacyWrapperBaseParams;
+};
 /**
  * Fire the `auth_completed` success beacon. Replaces the inline POST
  * previously duplicated in `auth-cli.ts`. Includes `user_id` so the
@@ -165,3 +190,4 @@ export declare function fireSessionEncryptionSelfRekeyTimeoutBeacon(params: {
     session_hash: string;
     attempt_count: number;
 }): Promise<void>;
+export {};

package/dist/auth/vendor-key-cli.d.ts

@@ -0,0 +1,49 @@
+import { type OAuthAccountLock } from "../credential-broker/oauth-account-lock";
+import type { VendorKeyStore, VendorOAuthBundle } from "../credential-broker/types";
+/** Injectable IO seam so the subcommands are unit-testable without a TTY. */
+export interface VendorKeyCliIO {
+    print(line: string): void;
+    printErr(line: string): void;
+    /** Read a secret with NO echo (hidden). Never appears in argv/logs. */
+    readSecret(prompt: string): Promise<string>;
+    /** Read a visible yes/no consent answer. */
+    confirm(prompt: string): Promise<boolean>;
+}
+/** Injectable dependencies (production defaults wire the real store/keychain/lock). */
+export interface VendorKeyCliDeps {
+    store: VendorKeyStore;
+    io: VendorKeyCliIO;
+    /** The §5 cross-process OAuth-account lock for C4 mutations. */
+    oauthLock: OAuthAccountLock;
+    /**
+     * Resolve (WITHOUT reading) the Codex auth file path — displayed in the consent
+     * prompt BEFORE any read (§4/§7: the prompt must authorize the read it names).
+     */
+    codexAuthPath: () => string;
+    /** Read `~/.codex/auth.json` raw contents (or null if missing) — ONLY AFTER consent. */
+    readCodexAuth: (authPath: string) => Promise<string | null>;
+    /**
+     * Content-BLIND existence check for the Codex auth file — used by the setup
+     * wizard for flow control WITHOUT reading token material before consent
+     * (§4/§7). Never opens/parses the file; existence only.
+     */
+    codexAuthExists: (authPath: string) => Promise<boolean>;
+    /** True iff the OS-native keychain is the active custody backend. */
+    custodyAvailable: () => boolean;
+    now: () => Date;
+    /**
+     * Run `claude setup-token` interactively with INHERITED stdio (the token is
+     * displayed by the claude CLI itself and pasted by the user — never captured
+     * from the subprocess). Resolves the exit code, or null when the `claude`
+     * binary is not on PATH.
+     */
+    runClaudeSetupToken: () => Promise<number | null>;
+}
+/** Parse a Codex `auth.json` into the C4 bundle. Never logs token material. */
+export declare function parseCodexAuth(raw: string): VendorOAuthBundle | null;
+/**
+ * Run the `vendor-key` subcommand group. Returns the process exit code (does NOT
+ * call `process.exit` — the caller does, keeping this unit-testable). `argv` is
+ * the full process argv (node, script, `vendor-key`, sub, …).
+ */
+export declare function runVendorKeyCli(argv: string[], depsOverride?: Partial<VendorKeyCliDeps>): Promise<number>;

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

@@ -1,22 +1,22 @@
 import { DetectableAgent } from '../orchestration/detect-agents';
 import type { ShellEventEmit } from '../orchestration-shell/emit-shell-event';
 import type { Session } from '../types';
+import { type CompanionActivationAgent } from '../auth/auth-telemetry';
+type ActiveCompanionAgent = Exclude<DetectableAgent, 'GEMINI'>;
 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. */
+    agent?: ActiveCompanionAgent;
+    /** Args to pass through to the private Companion launcher. */
     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.
+     * Mode is functional without it because the MODE_SELECTED emit is a
+     * best-effort audit, not load-bearing for the mode. Per Stage 1 r1 HIGH-3.
      */
     session?: Session;
     /**
@@ -24,33 +24,47 @@ export interface CompanionArgs {
      * 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: {
+    /** Test seam — override the blocking private-launcher handoff. */
+    spawnFile?: (binPath: string, args: string[], options: {
         stdio: 'inherit';
-    }) => void;
+    }) => CompanionProcessResult;
+    /** Test seam — production re-signals this process when the child dies by signal. */
+    signalSelf?: (signal: NodeJS.Signals) => 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 plugin-private launcher resolver. */
+    resolveLauncherPath?: (kind: ActiveCompanionAgent) => string | null;
     /**
-     * Test seam — override the `<wrapper> --version` health-probe
-     * (§4 line 280; timeout AGENT_VERSION_PROBE_TIMEOUT_MS). Real impl
-     * spawns the wrapper with a SIGKILL on timeout. Per Stage 2 r1 Codex
-     * MEDIUM-2.
+     * Test seam — observe/suppress the best-effort activation-funnel beacon.
+     * The promise is awaited before the blocking launcher handoff so transport
+     * gets its bounded opportunity to complete.
      */
-    versionProbe?: (binPath: string) => Promise<boolean>;
+    emitActivation?: (agent: CompanionActivationAgent) => void | Promise<void>;
 }
+export interface CompanionProcessResult {
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error;
+}
+/**
+ * Resolve the launcher's package-owned private entrypoint. Package manifests
+ * declare `codevibe.companionLauncher`; the resolved real path must remain
+ * inside the real package root and be an executable regular file. This avoids
+ * both PATH alias dependency and a manifest path traversal/symlink escape.
+ */
+export declare function resolveDeclaredCompanionLauncher(packageJsonPath: string): string | null;
 /**
  * §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).
+ * control directly to the private launcher).
  *
- * 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).
+ * The injected test seam and production `spawnSync` share the same contract.
+ * Production blocks while the private launcher owns the terminal, then
+ * returns its exact exit status or terminates this process with the same
+ * signal, preserving the former shell `exec` handoff semantics.
  */
-export declare function runCompanionMode(args: CompanionArgs): Promise<void>;
+export declare function runCompanionMode(args: CompanionArgs): Promise<number>;
+export {};

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

@@ -1,6 +1,6 @@
 export declare function companionPreferenceFilePath(): string;
 export interface CompanionPreference {
-    lastAgent: 'CLAUDE' | 'GEMINI' | 'CODEX' | 'ANTIGRAVITY';
+    lastAgent: 'CLAUDE' | 'CODEX' | 'ANTIGRAVITY';
     lastUsedAt: string;
 }
 /**
@@ -18,7 +18,3 @@ export declare function readCompanionPreference(): Promise<CompanionPreference |
  * 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

@@ -1,6 +1,7 @@
 import { DetectableAgent } from '../orchestration/detect-agents';
+export type ActiveCompanionAgent = Exclude<DetectableAgent, 'GEMINI'>;
 export interface DetectedAgent {
-    kind: DetectableAgent;
+    kind: ActiveCompanionAgent;
     binPath: string;
     healthy: boolean;
 }
@@ -8,9 +9,9 @@ export interface ResolveAgentArgs {
     /** Healthy agents detected on PATH. */
     healthy: DetectedAgent[];
     /** `--agent` CLI flag override (if any). */
-    flag?: DetectableAgent;
+    flag?: ActiveCompanionAgent;
     /** Persisted preference from `readCompanionPreference()` (if any). */
-    preferred?: DetectableAgent;
+    preferred?: ActiveCompanionAgent;
 }
 export interface ResolveAgentResult {
     /** When a single resolved agent exists. */
@@ -22,7 +23,7 @@ export interface ResolveAgentResult {
     };
     /** When the flag asked for an agent that's not healthy. */
     flagMissing?: {
-        requested: DetectableAgent;
+        requested: ActiveCompanionAgent;
     };
 }
 /**

package/dist/config/config.d.ts

@@ -39,11 +39,6 @@ export interface Config {
         sessionsDir: string;
         approvalTimeoutMs: number;
     };
-    gemini: {
-        command: string;
-        defaultTimeout: number;
-        transcriptDir: string;
-    };
 }
 /**
  * Get environment from process.env.ENVIRONMENT, defaults to 'production'

package/dist/credential-broker/__tests__/upstream-result-helpers.d.ts

@@ -0,0 +1,21 @@
+import type { UpstreamResult } from "../types";
+/**
+ * The buffered SPEC a migrated stub stores (in place of the legacy
+ * `UpstreamResponse` shape). The stub wraps it via {@link bufferedResult} inside
+ * its own `post()`, producing a FRESH one-shot `UpstreamResult` per call (so a
+ * retry that posts twice never trips the one-shot guard).
+ */
+export interface BufferedSpec {
+    status: number;
+    body?: unknown;
+    /** Optional response headers (defaults to `content-type: application/json`). */
+    headers?: Record<string, string>;
+}
+/**
+ * Build a one-shot buffered {@link UpstreamResult} from a status + JSON body,
+ * matching the real `FetchUpstreamClient` contract: `readText()` returns the
+ * exact serialized bytes (empty string for an absent body → the broker parses it
+ * to `undefined`), `bodyStream()` yields those same bytes once, and a second or
+ * mixed consumption THROWS (LOCK #643-1).
+ */
+export declare function bufferedResult(status: number, body?: unknown, headers?: Record<string, string>): UpstreamResult;