@quantiya/codevibe-core 2.0.0 → 2.0.2

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

@@ -1,4 +1,160 @@
 import { CreateEventInput, CreateSessionInput, UpdateSessionInput, UpdateEventStatusInput, Event, Session, EventSource, DeviceKey, GrantSessionKeyInput, UpdateReviewerPolicyInput, UserReviewerPolicySnapshot } from '../types';
+import type { PostDecisionAction } from '../orchestration-shell/types';
+import type { CreateTaskGroupInput, CreateTaskGroupResult, SubmitMergeGateVerdictInput, SubmitMergeGateVerdictResult, SubmitTrackVerificationOutcomeInput, SubmitTrackVerificationOutcomeResult, ClaimGroupDecisionInput, ClaimGroupDecisionResult } from '../local-executor/task-group-types';
+import type { ReviewerVerdict, ReviewerRole, AgentKind as ReviewerAgentKind } from '../reviewer/types';
+import type { PlannerDecision } from '../planner/types';
+/**
+ * One assigned reviewer seat returned by `getInReviewAssignments`. Mirrors the
+ * engine `InReviewAssignment` serde (camelCase) in
+ * `codevibe-orchestration-lambda/src/types.rs::InReviewAssignment`.
+ */
+export interface InReviewAssignment {
+    /** Gate this assignment belongs to (UUID string). */
+    gateId: string;
+    /** NUMERIC seat-id (0-indexed). */
+    seatId: number;
+    /** snake_case reviewer lens. */
+    role: ReviewerRole;
+    /** Lowercase agent kind chosen by the resolver. */
+    agentKind: ReviewerAgentKind;
+    /** Round number of the gate (0-indexed). */
+    round: number;
+}
+/**
+ * CP-12 W4 (#593) — one non-terminal team track returned by the team-dispatch
+ * recovery queries (`getTaskGroupTracks` / `getInFlightTeamTracks`). A DISTINCT
+ * recovery-row type — NOT an extension of the live `TrackAssignedPayload` (so the
+ * live Class B contract stays unpolluted). Mirrors the engine handler's camelCase
+ * `TeamTrackRecoveryRow` serde:
+ *   - ALWAYS present: `taskGroupId`, `trackIndex`, `relaunch`, and `encryptedBrief?`
+ *     (omitted when the track had no description → recovery treats it as an empty
+ *     brief). `taskGroupId` is on EVERY row (seed-only too) so the desktop keys its
+ *     recovered brief + corrupt-brief tombstone by `(taskGroupId, trackIndex)` —
+ *     B.2 aggregates across groups, so a bare `trackIndex` key could cross-blend
+ *     two groups (#593 Stage-2 r2 Codex MEDIUM).
+ *   - ONLY when `relaunch === true` (flattened at top level): the full live
+ *     `TrackAssigned` wire-field set (`taskId`, `implementorAgent`,
+ *     `ownershipScope`, `isSharedTestOwner`, `stateDir`, `dispatchId`,
+ *     `dispatchGeneration`, `conflictContext`) PLUS recovery metadata (`gateRunId`,
+ *     `gateType`). These camelCase keys are byte-identical to the live
+ *     `TrackAssigned` Class B packet, so `normalizeTrackAssignedWire(row)` accepts
+ *     a relaunch row directly (it picks the expected keys and ignores the extras).
+ *
+ * Typed loosely (`unknown` payload past the always-present fields) because the
+ * relaunch keys are present-or-absent; the recovery loop runs the shared
+ * `normalizeTrackAssignedWire` + `isValidTrackAssignedPayload` validators on the
+ * raw row (never a divergent second validator), so the SDK does not re-type them.
+ */
+export interface TeamTrackRecoveryRow {
+    /**
+     * The owning task group's id — present on EVERY row (seed-only + relaunch) so
+     * recovered briefs + tombstones key by `(taskGroupId, trackIndex)` and B.2's
+     * cross-group aggregation can't collide on a shared `trackIndex` (#593 r2).
+     */
+    taskGroupId: string;
+    trackIndex: number;
+    /** Bare base64 ciphertext; absent when the track had no description. */
+    encryptedBrief?: string;
+    relaunch: boolean;
+    /** The round-0 gate id (relaunch rows only) — read off the row by recovery. */
+    gateRunId?: string;
+    /** `"reviewer_quorum"` (relaunch rows only). */
+    gateType?: string;
+    /** The relaunch rows carry the full TrackAssigned wire field set (see above). */
+    [key: string]: unknown;
+}
+/**
+ * PHASE-589/469 W3.1 (RESIDUAL 2 / #589-I) — the `getTaskGroupStatus` result. The
+ * group's authoritative TERMINAL status (the engine's snake_case
+ * `TaskGroupStatus` label, OR `"unknown"` for a vanished / unowned group) + the
+ * persisted halt reason (only on a `halted` group). Mirrors the engine
+ * `GetTaskGroupStatusOutput { taskGroupId, status, haltReason? }`. Used by the
+ * startup reconcile to drive the offline-lease-timeout auto-revert.
+ */
+export interface TaskGroupStatusResult {
+    taskGroupId: string;
+    status: string;
+    haltReason?: string;
+}
+/**
+ * PHASE-CP-1-F.1 Part A (LOCK L2) — tolerant `AWSJSON!` object read.
+ *
+ * AppSync delivers an `AWSJSON!` field to a consumer as EITHER an embedded
+ * object/array OR a (possibly double-encoded) JSON string — the producer
+ * stringifies the value into the field, and the delivery path may or may not
+ * re-wrap it. This mirrors the iOS normalization
+ * (`codevibe-ios/.../GraphQLClient.swift:1004-1009`).
+ *
+ * Coercion rules (the SINGLE AWSJSON object-read path for new nested-AWSJSON
+ * consumers):
+ *   1. `raw` is already a non-null, non-array object → use it directly.
+ *   2. `raw` is a string → `JSON.parse`. If the result is STILL a string
+ *      (double-encoded) → `JSON.parse` ONCE more (bounded: at most one extra
+ *      unwrap — a triple-encoded payload is treated as malformed).
+ *   3. The final value MUST be a non-null, non-array object → else throw
+ *      (fail-closed; we never silently accept null/array/scalar).
+ *
+ * @param raw the AWSJSON field value off the GraphQL response
+ * @param op  the operation name (for fail-closed error messages)
+ */
+export declare function coerceAwsJsonObject(raw: unknown, op: string): Record<string, unknown>;
+/** Result of `getReviewerPrompt` — the DECRYPTED rendered prompt + seat metadata. */
+export interface ReviewerPromptResult {
+    gateId: string;
+    seatId: number;
+    role: ReviewerRole;
+    /** Decrypted plaintext rendered prompt (UTF-8) → ReviewerSpec.prompt_template. */
+    prompt: string;
+}
+/** One reviewer seat in a round's `reviewers[]` (decrypted). */
+export interface TaskReviewSummaryReviewer {
+    /** ReviewerVerdict.seat_id (0-indexed). */
+    seatId: number;
+    /** ReviewerRole serde (snake_case): architecture | correctness | … */
+    role: string;
+    /** AgentKind serde (lowercase): claude | codex | gemini. */
+    agent: string;
+    /** VerdictKind serde (UPPERCASE): APPROVE | REJECT | REVISE | ESCALATE. */
+    decision: string;
+    /** ReviewerVerdict.reasoning verbatim. */
+    reasoning: string;
+    /** ReviewerVerdict.suggested_changes (may be empty). */
+    suggestedChanges: string[];
+}
+/** One round in the per-round summary (decrypted). */
+export interface TaskReviewSummaryRound {
+    /** gate_row.round_number (0-indexed). */
+    round: number;
+    /** Human-readable concat of problem/proposal/plan/expected-outputs. */
+    proposal: string;
+    /** Per-seat verdicts for this round. */
+    reviewers: TaskReviewSummaryReviewer[];
+    /** GateDecision serde: proceed | auto_revise | escalate. */
+    outcome: string;
+    /** Aggregated REVISE seat findings; present only when outcome==auto_revise. */
+    reviseNotes?: string;
+}
+/**
+ * Result of `getTaskReviewSummary` — the DECRYPTED per-round review summary the
+ * desktop renders at the final-approval gate. Mirrors the engine's allowlist
+ * projection; `truncatedForSize`/`omittedRounds` flag the size-cap degrade.
+ */
+export interface TaskReviewSummary {
+    rounds: TaskReviewSummaryRound[];
+    /** The resolution that produced the final-approval prompt (normally proceed). */
+    finalOutcome: string;
+    /** True when the size cap forced any truncation/omission. */
+    truncatedForSize: boolean;
+    /** Count of whole oldest rounds dropped under the size cap (0 when none). */
+    omittedRounds: number;
+}
+/** Result of `getClassBSigningPublicKey` — the engine's Ed25519 verifier key. */
+export interface ClassBSigningPublicKey {
+    /** Base64-encoded raw 32-byte Ed25519 public (verifying) key. */
+    publicKeyB64: string;
+    /** Rotation-aware key id (matches `signedEnvelope.publicKeyId`). */
+    keyId: string;
+}
 /**
  * Download URL response
  */
@@ -6,16 +162,117 @@ 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;
+    });
+}
+/**
+ * PHASE-CP-10-MIN (#585) §2.3 — the parsed cross-device applyUserDecision
+ * echo. Mirrors the quorum-core SDK's `UserDecisionAppliedEvent`
+ * (`quorum-core/src/types.ts:680`) + the backend `UserDecisionAppliedEvent`
+ * (`schema.graphql:1364-1371`): `decision` lowercase, `action` parsed to the
+ * typed `PostDecisionAction` via `coerceAwsJsonObject`.
+ */
+export interface UserDecisionAppliedEvent {
+    sessionId: string;
+    taskId: string;
+    gateId: string;
+    /** Lowercase `UserDecisionKind` string (the wire enum is SCREAMING_SNAKE; coerced to lowercase). */
+    decision: string;
+    /** The parsed `PostDecisionAction` (from the AWSJSON `payload`). */
+    action: PostDecisionAction;
+}
+/**
+ * CP-1.f — decides whether a subscribed event should be delivered to the
+ * caller's `onEvent` callback.
+ *
+ * - Companion plugin path (`receiveDesktopEvents` falsy): deliver ONLY
+ *   MOBILE-source events. The desktop plugin emits its own DESKTOP events and
+ *   must NOT re-receive them (the 2026-04-14 duplicate-mobile-event fix).
+ * - Orchestration shell path (`receiveDesktopEvents` true): ALSO deliver
+ *   DESKTOP-source events. Engine/backend emits gate prompts via the AppSync
+ *   SigV4 branch, which stamps `source = DESKTOP` (`emittedBy = SYSTEM`); for
+ *   an orchestration session those are the ONLY DESKTOP events (the shell
+ *   originates none), so this is exactly the set of engine-emitted prompts the
+ *   shell must render. MOBILE events (user messages from the phone) are still
+ *   delivered in both modes.
+ *
+ * Pure function so the delivery rule is unit-testable independently of the
+ * WebSocket message plumbing.
+ */
+export declare function shouldDeliverSubscribedEvent(event: Pick<Event, 'source'>, receiveDesktopEvents: boolean): boolean;
+/**
+ * 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
  */
 export declare class AppSyncClient {
+    #private;
     private authenticated;
     private currentUserId;
     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 applyUserDecisionWatchers;
+    private statusWriteChains;
     private environment;
     constructor();
     /**
@@ -26,6 +283,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 +315,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
      */
@@ -54,6 +376,7 @@ export declare class AppSyncClient {
      * Update a session
      */
     updateSession(input: UpdateSessionInput): Promise<Session>;
+    private doUpdateSession;
     /**
      * Get a session
      */
@@ -70,10 +393,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
      */
@@ -99,8 +481,27 @@ export declare class AppSyncClient {
      * (`CLAUDE` / `GEMINI` / `CODEX`). Idempotent — safe to call every
      * launch. Backend stores in `User.availableAgents`; used later to
      * derive tier-default reviewer seat assignments.
+     *
+     * CP-1.f LOCK RP-3 — `replace` semantics. Default `false` keeps the 1.x
+     * companion-daemon UNION contract (the backend merges the input into the
+     * cross-device set). The orchestration shell passes `true` so the
+     * backend SETs `availableAgents` to exactly the input set (REPLACE),
+     * dropping any stale agent (e.g. a `GEMINI` from a prior host that would
+     * otherwise be composed into the reviewer panel → `spawn gemini ENOENT`).
      */
-    updateAvailableAgents(agents: Array<'CLAUDE' | 'GEMINI' | 'CODEX'>): Promise<UserReviewerPolicySnapshot>;
+    updateAvailableAgents(agents: Array<'CLAUDE' | 'GEMINI' | 'CODEX' | 'ANTIGRAVITY'>, replace?: boolean): 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 +510,440 @@ 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;
+    }>;
+    /**
+     * CP-12 §2.1 — create a task group. The server validates disjointness
+     * (#C12-2) BEFORE creating any track and returns the
+     * `CreateTaskGroupResult` discriminated union (accepted arm with
+     * `taskGroupId` + `dispatchedTracks`, or rejected arm with `rejection`).
+     *
+     * The mutation returns `AWSJSON!` (a stringified JSON value), so the
+     * response field is a JSON string parsed here — identical AWSJSON handling
+     * to `applyUserDecision` + `recordExecutionEvent`. Validates the input
+     * minimally (mirrors the `applyUserDecision` pattern) and surfaces backend
+     * rejections as `AppSyncGraphQLError` (thrown by `graphqlRequest`).
+     *
+     * W2.a ships the SDK surface; the N-track spawn / scheduler wiring that
+     * consumes the result is W2.b.
+     */
+    createTaskGroup(input: CreateTaskGroupInput): Promise<CreateTaskGroupResult>;
+    /**
+     * CP-12 §2.1 / #C12-8 — submit a MergeGate verdict. The `classification`
+     * carries the LE-signed, server-readable structural metadata (the server
+     * verifies `classification.signatureB64` against the LE's Class A key
+     * before routing); `detail` is the E2E-encrypted human-readable payload.
+     * Idempotent replay on `verdictIdempotencyKey`.
+     *
+     * The mutation returns `AWSJSON!` (the resolved-outcome union as a
+     * stringified JSON value); parsed here like `createTaskGroup`. The caller
+     * is responsible for building + signing the classification (W2.b builds the
+     * real classification; the signing helper is `signMergeClassification` in
+     * `local-executor/class-a-sign.ts`). W2.a ships the SDK surface only.
+     */
+    submitMergeGateVerdict(input: SubmitMergeGateVerdictInput): Promise<SubmitMergeGateVerdictResult>;
+    /**
+     * PHASE-589/469 W1 (LOCK #589-F) — report that ONE team track HARD-FAILED
+     * its own local gate (a declared-test failure or an out-of-scope write). The
+     * engine marks the track `Failed` NOW so its existing scheduler drain +
+     * group-escalation resolves the group promptly (instead of the slow lease
+     * sweeper, with the wrong "timeout" reason). The marker carries NO proposal
+     * and MUST NOT fan out to reviewers (#598's guarantee). `outcome` is the
+     * CONTENT-FREE closed reason label — NEVER raw test output.
+     *
+     * The mutation returns `AWSJSON!` (`{ trackState }` as a stringified JSON
+     * value); parsed here like `submitMergeGateVerdict`. The desktop caller
+     * treats this as BEST-EFFORT (W1): it does not depend on the return to
+     * render — it flips its own track + renders the group-terminal from local
+     * state; the engine lease sweeper is the backstop if the call fails.
+     */
+    submitTrackVerificationOutcome(input: SubmitTrackVerificationOutcomeInput): Promise<SubmitTrackVerificationOutcomeResult>;
+    /**
+     * PHASE-589/469 W3.2 — `claimGroupDecision` two-phase group-escalation resolve
+     * (LOCK #589-J). Mirror of `submitTrackVerificationOutcome`'s AWSJSON
+     * passthrough shape. CLAIM (`phase:"claim"`) atomically locks the group to the
+     * first acting surface; COMMIT (`phase:"commit"`, echoing the CLAIM's
+     * `claimToken`) drives the group terminal AFTER the desktop revert side-effect.
+     * The optional `*_WITH_NOTES` `notes` ride E2E-encrypted (the engine never
+     * decrypts them); they are encrypted by the caller before reaching here.
+     */
+    claimGroupDecision(input: ClaimGroupDecisionInput, sessionKeyBase64?: string): Promise<ClaimGroupDecisionResult>;
+    /**
+     * §3.A.1 / §3.C.20 — drive the engine Idle → GatePlanInFlight transition.
+     * The planner's `start_task` decision (action + optional gateRequest) is
+     * plaintext on the wire (no E2E-sensitive prose beyond the opaque
+     * gateRequest blob). Returns the resulting workflow-state label so the
+     * caller can confirm the engine spawned a gate plan.
+     *
+     * CP-1.f LOCK RP-6 — `availableAgents` carries THIS orchestration host's
+     * detected coding agents (UPPERCASE `CLAUDE` / `CODEX` / `GEMINI`) so the
+     * gate row's availability is stamped race-free from the request, instead
+     * of the engine reading the shared per-user `User.availableAgents` field
+     * (which a legacy 1.x companion daemon on another device can union a
+     * stale agent back into). The `Some([])` vs absent distinction is
+     * load-bearing engine-side: pass `[]` (a definitive "nothing detected" →
+     * Claude-only fail-safe) rather than omitting the field. The field rides
+     * inside `$input` (the `StartTaskInput!` GraphQL type gained
+     * `availableAgents: [String]`); the mutation document is unchanged. When
+     * `availableAgents` is `undefined` the field is omitted entirely (an
+     * older desktop's behavior → engine Users-table fallback).
+     */
+    startTask(input: {
+        taskId: string;
+        sessionId: string;
+        decision: PlannerDecision;
+        availableAgents?: string[];
+    }): Promise<{
+        workflowState: string;
+    }>;
+    /**
+     * §3.A.3 / §3.C.20 / §3.C.23 — submit the E2E-encrypted implementor proposal
+     * for the in-flight gate (round-0 startTask gate OR a round-N+1 revise gate).
+     * `rawOutput` is the primary-agent raw output the engine parses + renders.
+     * Returns `{ gateId, workflowState }`.
+     */
+    submitImplementorOutput(input: {
+        taskId: string;
+        gateId: string;
+        sessionId: string;
+        roundNumber: number;
+        rawOutput: string;
+    }, sessionKeyBase64: string): Promise<{
+        gateId: string;
+        workflowState: string;
+    }>;
+    /**
+     * §3.C.22 — submit one reviewer seat's verdict. The full `ReviewerVerdict`
+     * JSON is E2E-encrypted under the session key (#C1F-6). Returns the parsed
+     * `GateResolvedEvent.payload` (the discriminated `SubmitReviewerVerdictOutput`
+     * — `acknowledged` for seats 1..N-1, `reviewGateResolved` for the last seat).
+     */
+    submitReviewerVerdict(input: {
+        gateId: string;
+        sessionId: string;
+        seatId: number;
+        verdict: ReviewerVerdict;
+    }, sessionKeyBase64: string): Promise<unknown>;
+    /**
+     * §3.A.7 / §3.C.21 — fetch + DECRYPT the engine-rendered reviewer prompt for
+     * one seat. `seatId` is the NUMERIC seat (the caller extracts it from the
+     * dispatch packet's resolved seat-id string). The engine returns an
+     * `EncryptedPayload` (inline-nonce ciphertext of the raw prompt bytes); this
+     * decrypts it under the session key → plaintext prompt for the ReviewerSpec.
+     *
+     * Throws (NotFound surfaced as a GraphQL error) when the pending handle
+     * hasn't propagated yet — the caller retries-with-backoff then fail-closed
+     * synthesizes ESCALATE (#C1F-8).
+     */
+    getReviewerPrompt(gateId: string, seatId: number, sessionKeyBase64: string): Promise<ReviewerPromptResult>;
+    /**
+     * PHASE-CP-1-F.1 Part B (LOCK L3/L6) — fetch + DECRYPT the per-round review
+     * summary for a final-approval gate. `gateId` is the final-approval prompt's
+     * gateId (the HEAD of the proposal-gate `revision_of` lineage); `taskId` is
+     * the auth/scoping anchor. The engine walks the lineage backward, projects an
+     * exhaustive allowlist over each round, and returns the E2E-encrypted summary
+     * re-keyed for the session.
+     *
+     * Wire (bare `AWSJSON!`, read via the SAME tolerant `coerceAwsJsonObject` as
+     * Part A): `{ taskId, sessionId, summary: { ciphertextB64, sessionId,
+     * keyVersion } }`. `summary` is the DEDICATED `TaskReviewSummaryEnvelope`
+     * (inline-nonce AES-256-GCM; the 12-byte nonce is prepended INSIDE
+     * `ciphertextB64`, NO separate nonce field) — decrypt with
+     * `cryptoService.decryptContent` (NOT decryptMetadata), identical to
+     * `getReviewerPrompt`. The decrypted plaintext is the §2.3 `{rounds,
+     * finalOutcome, …}` object.
+     *
+     * Throws on a missing/malformed envelope or a decrypt/parse failure — the
+     * caller (the base-first dispatch in `orchestration-shell/index.ts`) catches
+     * every throw and fails OPEN (the prompt renders with no panel, never
+     * ciphertext).
+     */
+    getTaskReviewSummary(taskId: string, gateId: string, sessionKeyBase64: string): Promise<TaskReviewSummary>;
+    /**
+     * §3.B.15 / §3.C.18 — fetch the engine's Ed25519 Class-B signing PUBLIC key
+     * + rotation-aware keyId. The desktop caches this and verifies every Class B
+     * packet's signature against it (fail-closed). No E2E — a public verifier
+     * key.
+     */
+    getClassBSigningPublicKey(): Promise<ClassBSigningPublicKey>;
+    /**
+     * §3.B.15 / §3.C.21b — the dropped-packet recovery primitive. Returns every
+     * seat assigned to the caller across any `in_review` gate of the task; the
+     * desktop spawns any seat NOT already running-in-memory or verdict-submitted.
+     */
+    getInReviewAssignments(taskId: string): Promise<InReviewAssignment[]>;
+    /**
+     * CP-12 W4 (#593) B.1 — strong (`ConsistentRead`) read of the just-created
+     * team group's in-flight tracks. The desktop knows the `taskGroupId`
+     * `createTaskGroup` just returned, so this is the deterministic initial-connect
+     * recovery for the proven emit-before-subscribe race (no GSI, no eventual
+     * consistency). Returns every NON-terminal track as a `TeamTrackRecoveryRow`;
+     * the desktop seeds all briefs (PASS 1) and re-launches the relaunch subset
+     * (PASS 2). Mirrors `getInReviewAssignments` (`{ tracks: [...] }` wrapper).
+     */
+    getTaskGroupTracks(taskGroupId: string): Promise<TeamTrackRecoveryRow[]>;
+    /**
+     * CP-12 W4 (#593) B.2 — discover the caller's in-flight team tracks across
+     * UNKNOWN groups (restart / reconnect), via the `session_id-status-index` GSI.
+     * The desktop has no remembered `taskGroupId` after a restart, so B.1 cannot
+     * fire; this is the only path that recovers a team interrupted by a process
+     * restart. Eventual-consistency on the GSI is acceptable (a bounded retry
+     * covers propagation, §4.2); the handler always re-reads the authoritative
+     * `tg#{group}` row with a `ConsistentRead` before deciding `relaunch`. Returns
+     * every NON-terminal track as a `TeamTrackRecoveryRow` (same wrapper).
+     */
+    getInFlightTeamTracks(sessionId: string): Promise<TeamTrackRecoveryRow[]>;
+    /**
+     * PHASE-589/469 W3.1 (RESIDUAL 2 / #589-I) — read a team group's authoritative
+     * TERMINAL status + halt reason for the startup reconcile. The recovery queries
+     * above only surface IN-FLIGHT tracks, so they cannot distinguish a `complete`
+     * (kept) group from a `halted` (rejected — incl. a sweeper-driven lease-timeout
+     * the desktop MISSED while offline) from a TTL'd one. This reads the group row's
+     * status directly so the reconcile can auto-revert a terminal-rejected-but-
+     * locally-dirty tree before a backend expiry strands it. CONTENT-FREE (status +
+     * halt-reason label only; no decrypt). A vanished / unowned group fails closed
+     * server-side to `status: "unknown"`. Mirrors `getTaskGroupTracks` (a top-level
+     * `taskGroupId` arg; returns the bare AWSJSON object).
+     */
+    getTaskGroupStatus(taskGroupId: string): Promise<TaskGroupStatusResult>;
+    /**
+     * CP-6 LOCK #C6-A-10.4.10.2 — record an LE-written continuation
+     * packet's authoritative hash on the backend audit table. Called
+     * DIRECTLY by `createContinuationPacketWriter` after the atomic
+     * packet write completes; NOT routed through `emitShellEvent` (per
+     * §11 row 25).
+     *
+     * Wire-form per `RecordContinuationPacketWrittenInput`
+     * (`schema.graphql:1086-1093`):
+     *   - `taskId`: ULID/UUID
+     *   - `offerId`: nullable ULID (None for LE-initiated writes)
+     *   - `packetHash`: 64-char lowercase hex SHA-256
+     *   - `packetRelativePath`: relative to `~/.codevibe/tasks/`
+     *   - `sourceAgent`: CLAUDE | CODEX | GEMINI | ANTIGRAVITY (all four
+     *     accepted by the Rust handler as of AGY-2.0 Phase C)
+     *   - `blockedReason`: §6:827 wire value
+     *     (`quota_exhausted | auth_failed | timeout | user_requested`)
+     *
+     * Returns the design-locked discriminated union:
+     *   - `{ kind: 'ok', auditEventId, alreadyExists }` on success
+     *   - `{ kind: 'error', reason }` on any GraphQL error
+     *
+     * Does NOT throw — every failure surfaces as `{ kind: 'error' }`.
+     * The writer's F-GY-3 contract unlinks the local packet ONLY when
+     * this method returns `{ kind: 'error' }`.
+     */
+    recordContinuationPacketWritten(input: {
+        taskId: string;
+        offerId: string | null;
+        packetHash: string;
+        packetRelativePath: string;
+        sourceAgent: 'CLAUDE' | 'CODEX' | 'GEMINI' | 'ANTIGRAVITY';
+        blockedReason: 'quota_exhausted' | 'auth_failed' | 'timeout' | 'user_requested';
+        /**
+         * PHASE-CP-10-MIN (#585) M-B — the additive `gateId: ID` input. The
+         * handler `fetch_row`s it, cross-checks `gate_row.task_id == input.task_id`,
+         * stamps `handoff_pending` (#C10M-14), and emits the handoff prompt for it.
+         * Optional (the Rust DTO is `#[serde(default)] gate_id: Option<Uuid>`);
+         * required at the handler for #585's two triggers. The mutation passes
+         * `{ input }` directly, so the additive field rides without a query change.
+         */
+        gateId?: string;
+    }): Promise<{
+        kind: 'ok';
+        auditEventId: string;
+        alreadyExists: boolean;
+    } | {
+        kind: 'error';
+        reason: string;
+    }>;
+    /**
+     * CP-6 Stage 2 R1 H-1 fix — dedicated existence-check for the
+     * `continuation_packet_written` audit row. Replaces the legacy
+     * `queryAudit` usage in `packet-reader.ts` which was incompatible
+     * with the real backend audit shape (entries[].payload is encrypted,
+     * so the reader cannot extract `packet_hash` from the payload to
+     * verify F-GY-3).
+     *
+     * The backend handler computes the dedup_key from the public
+     * `(taskId, packetHash)` pair via the same
+     * `continuation_packet_written_key` formula used at write time,
+     * then does a single DDB point-read on the audit dedup table.
+     *
+     * Returns the design-locked discriminated union:
+     *   - `{ kind: 'ok', exists: boolean }` on success
+     *   - `{ kind: 'error', reason: string }` on any GraphQL/transport
+     *     error (fail-CLOSED: caller treats this as "unverified" per
+     *     F-GY-3 — better to refuse the read than silently accept).
+     *
+     * Does NOT throw — every failure surfaces as `{ kind: 'error' }`
+     * (mirrors `recordContinuationPacketWritten` discipline).
+     */
+    verifyContinuationPacketWritten(input: {
+        taskId: string;
+        offerId: string | null;
+        packetHash: string;
+    }): Promise<{
+        kind: 'ok';
+        exists: boolean;
+    } | {
+        kind: 'error';
+        reason: string;
+    }>;
+    /**
+     * Backend `queryAudit` query — generic audit-row retrieval keyed on
+     * `(taskId, sessionId)`. Backend resolver returns AWSJSON; this
+     * method parses the string envelope into a typed shape. The AWSJSON
+     * contract is best-effort normalized — callers should treat the
+     * `rows[]` as untyped and filter on the `kind` / `packet_hash`
+     * fields themselves.
+     *
+     * @deprecated for the CP-6 F-GY-3 verification path — use
+     *   `verifyContinuationPacketWritten` instead. The legacy
+     *   `queryAudit` returns encrypted `entries[].payload` shapes that
+     *   the reader cannot inspect for `packet_hash`. Kept on the client
+     *   because other CP-6-unrelated code may use it.
+     */
+    queryAudit(input: {
+        taskId: string;
+        sessionId: string;
+        kind?: string;
+    }): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
     /**
      * Subscribe to events for a session
      */
-    subscribeToEvents(sessionId: string, onEvent: (event: Event) => void, onError?: (error: Error) => void): () => void;
+    subscribeToEvents(sessionId: string, onEvent: (event: Event) => void, onError?: (error: Error) => void, options?: {
+        receiveDesktopEvents?: boolean;
+    }): () => 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 +982,82 @@ 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;
+    /**
+     * PHASE-CP-10-MIN (#585) §2.3 / Codex-H3 — subscribe to the cross-device
+     * `onApplyUserDecision` echo for a session. The orchestration shell uses
+     * this so a FOREIGN (mobile-originated) `continuation_switch_accepted`
+     * decision resumes the desktop that owns the implementor (the shell did NOT
+     * subscribe before; the V1-bridge plugins do via the quorum-core SDK —
+     * `codevibe-claude-plugin/src/server.ts:4493`). Mirrors the
+     * `watchForMobileEnd` per-session watcher (replace-on-duplicate, two-phase
+     * reconnect, keep-alive). Delivers a parsed `UserDecisionAppliedEvent`
+     * (`decision` lowercased; `action` coerced from the AWSJSON payload).
+     * Returns a `stop()` handle (idempotent).
+     */
+    subscribeToApplyUserDecision(sessionId: string, onDecision: (event: UserDecisionAppliedEvent) => void, onError?: (error: Error) => void): {
+        stop: () => void;
+    };
+    private createApplyUserDecisionWatcherConnection;
+    /**
+     * Parse one delivered `onApplyUserDecision` payload into a typed
+     * `UserDecisionAppliedEvent` and fire the callback OFF the message-handler
+     * stack (so a throwing consumer cannot tear down the socket). The `payload`
+     * is the AWSJSON `PostDecisionAction` — coerced with the SAME tolerant
+     * `coerceAwsJsonObject` the `applyUserDecision` mutation uses (no casing
+     * transform, so the snake_case continuation action fields land verbatim).
+     */
+    private handleApplyUserDecisionPayload;
+    private sendApplyUserDecisionWatcherStart;
+    private resetApplyUserDecisionWatcherKeepAlive;
+    private handleApplyUserDecisionWatcherError;
+    private cleanupApplyUserDecisionWatcherState;
     private heartbeatTimers;
     /**
      * Start periodic heartbeat for a session.
@@ -167,8 +1072,126 @@ export declare class AppSyncClient {
      * Send a single heartbeat update.
      */
     private sendHeartbeat;
+    /**
+     * Tear down the mobile-event subscription for a SINGLE session.
+     *
+     * Use this when a session ends or is superseded by a /resume while the
+     * daemon keeps running — cleanupSubscriptions() tears down ALL
+     * subscriptions and is only appropriate on full daemon shutdown.
+     *
+     * Without per-session teardown, an ended session's WebSocket survives in
+     * the still-running daemon. When AppSync idle-closes it (code 1000) the
+     * reconnect path in the start_ack handler re-runs startHeartbeat() and
+     * re-asserts status: ACTIVE — resurrecting the ended session as a
+     * duplicate row that the mobile app shows as a second live session.
+     * cleanupSubscriptionState() sets state.destroyed = true, which is exactly
+     * the flag the start_ack and 'close' handlers check to bail out, so this
+     * closes the resurrection path.
+     *
+     * (Confirmed in production logs 2026-06-04: a resumed-over Claude session
+     * was marked INACTIVE at 00:23:34 and resurrected to ACTIVE at 03:02:05
+     * when its leaked subscription reconnected after an AppSync code-1000
+     * close.)
+     *
+     * Idempotent: a no-op if no subscription is tracked for sessionId.
+     */
+    cleanupSubscription(sessionId: string): void;
     /**
      * 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.
+     *
+     * The `onClassBPacket(userId)` stream delivers EVERY packet for the user —
+     * across ALL of their active sessions. The second `onPacket` argument
+     * surfaces the AppSync `ClassBPacket` ENVELOPE metadata (`sessionId`,
+     * `taskId`, `packetId`, `issuedAt`) so a multi-session consumer (the
+     * orchestration shell) can drop packets that belong to a different session
+     * BEFORE acting on them (CP-12 W3 Stage-2 session-isolation fix). The inner
+     * parsed `packetJson` (the typed `ClassBInbound`) is the FIRST argument and
+     * is unchanged.
+     *
+     * CP-1.f §3.C.17 — the live WebSocket transport is now wired on the same
+     * two-phase reconnect engine that powers `subscribeToEvents` /
+     * `subscribeToDeviceKeyRegistered` (idToken auth via the realtime URL). The
+     * `_deliverClassBPacketForTests` seam is preserved (it routes through the
+     * SAME `classBPacketHandlers` registry the live socket dispatches into), so
+     * unit tests inject packets without standing up a real socket. `onReconnect`
+     * fires after a successful recovery so the shell can run the §3.C.21b
+     * dropped-packet recovery poll.
+     */
+    subscribeToClassBPackets(userId: string, handlers: {
+        onPacket: (packet: unknown, envelope: ClassBPacketEnvelopeMeta) => void | Promise<void>;
+        onError?: (err: Error) => void;
+        onReconnect?: () => void | Promise<void>;
+        /**
+         * CP-12 W4 (#593) — fired on EVERY subscription establishment (initial
+         * connect + reconnect). `isReconnect=false` on the first connect (the
+         * restart-discovery signal B.2 needs), `true` on a reconnect.
+         */
+        onSubscribed?: (isReconnect: boolean) => void | Promise<void>;
+    }): {
+        unsubscribe: () => Promise<void>;
+    };
+    /**
+     * Public stop for the Class B watcher. Used at shell teardown.
+     */
+    stopClassBWatcher(): void;
+    private stopClassBWatcherInternal;
+    private createClassBWatcherConnection;
+    private sendClassBWatcherStart;
+    private resetClassBWatcherKeepAlive;
+    private handleClassBWatcherError;
+    /**
+     * Parse + route one live Class B packet through the registered handler.
+     * Shared by the live WebSocket `data` path AND `_deliverClassBPacketForTests`
+     * so both exercise the exact same parse → onPacket → onError flow.
+     */
+    private dispatchClassBPacket;
+    /**
+     * 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.
+     *
+     * `envelope` mirrors the AppSync `ClassBPacket` envelope fields that the
+     * real subscription surfaces (`{ packetId, userId, sessionId, taskId,
+     * issuedAt }`); the wire envelope's `userId` always equals the subscription
+     * `userId`, so it is filled in here. `sessionId` defaults to '' for the
+     * legacy CP-1.e parse/error tests that do not exercise session isolation.
+     *
+     * @internal
+     */
+    _deliverClassBPacketForTests(userId: string, rawPacketJson: string, envelope?: Partial<ClassBPacketEnvelopeMeta>): Promise<void>;
+    private classBWatcher;
+    private readonly classBPacketHandlers;
+}
+/**
+ * Envelope metadata surfaced alongside each Class B packet — the AppSync
+ * `ClassBPacket` GraphQL type carries `{ packetId, userId, sessionId, taskId,
+ * packetJson, issuedAt }`. `parseClassBPacketPayload` parses `packetJson`
+ * (the inner typed packet); this type carries the OUTER envelope fields the
+ * consumer needs for routing/isolation. `sessionId` is load-bearing for the
+ * orchestration shell's per-session packet filter (CP-12 W3).
+ */
+export interface ClassBPacketEnvelopeMeta {
+    /** The session this packet was minted for. Used for shell session isolation. */
+    sessionId: string;
+    /** Always equals the subscription `userId`. */
+    userId: string;
+    taskId?: string;
+    packetId?: string;
+    issuedAt?: string;
 }