@quantiya/codevibe-core 2.0.1 → 2.0.3

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

@@ -1,5 +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
  */
@@ -31,6 +186,41 @@ export declare class AppSyncGraphQLError extends Error {
         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
@@ -52,6 +242,7 @@ export type AuthFailureKind = 'no_tokens' | 'refresh_auth_rejected' | 'refresh_n
  * AppSync GraphQL client with WebSocket subscriptions
  */
 export declare class AppSyncClient {
+    #private;
     private authenticated;
     private currentUserId;
     private currentEmail;
@@ -80,6 +271,8 @@ export declare class AppSyncClient {
     private static readonly REFRESH_BACKOFF_MS;
     private deviceKeyWatcher;
     private sessionUpdateWatchers;
+    private applyUserDecisionWatchers;
+    private statusWriteChains;
     private environment;
     constructor();
     /**
@@ -183,6 +376,7 @@ export declare class AppSyncClient {
      * Update a session
      */
     updateSession(input: UpdateSessionInput): Promise<Session>;
+    private doUpdateSession;
     /**
      * Get a session
      */
@@ -287,8 +481,15 @@ 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
@@ -418,10 +619,310 @@ export declare class AppSyncClient {
         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
      *
@@ -528,6 +1029,35 @@ export declare class AppSyncClient {
     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.
@@ -542,6 +1072,30 @@ 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
      */
@@ -560,27 +1114,84 @@ export declare class AppSyncClient {
      * 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.
+     * 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) => void | Promise<void>;
+        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): Promise<void>;
+    _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;
+}