@quantiya/codevibe-core 2.0.1 → 2.0.3

package/dist/orchestration-shell/quorum-loop.d.ts

@@ -0,0 +1,1900 @@
+import type { AppSyncClient, TeamTrackRecoveryRow } from '../appsync/appsync-client';
+import type { Session } from '../types';
+import type { LocalExecutor } from '../local-executor';
+import type { ImageAttachment } from './types';
+import { type ImplementorMode } from '../local-executor/implementor-argv';
+import type { ConflictModelCaller } from '../local-executor/class2-resolver';
+import type { ConflictResolverContext } from '../local-executor/merge-conflict-resolve';
+import type { AgentKind } from '../local-executor/types';
+import type { GateDispatchPayload, ReviewerDispatchPayload, ReviseFeedbackPayload } from '../local-executor/types';
+import type { TeamTrackFailureReason } from '../local-executor/task-group-types';
+import { WorkspaceShadow, type ShadowEnv } from '../local-executor/workspace-shadow';
+import type { RevertManifestStore } from '../local-executor/durable-store';
+import { type TeamExecution } from '../local-executor/team-execution-flag';
+import { type RenderedConflict, type TrackIntentDiff } from '../local-executor/wb2-review-bundle';
+import { ReviewerRegistry } from '../reviewer/registry';
+import { type ReviewerFailureReason } from '../reviewer/provider';
+import type { SubstrateHandle } from '../substrate/types';
+import type { VerdictClassifier } from '../reviewer/verdict-classifier';
+import type { AgentKind as ReviewerAgentKind, ReviewerRole } from '../reviewer/types';
+import type { OnProgress } from './task-progress';
+import { runShellCommand } from '../local-executor/verification-gates/shell-runner';
+import type { PostDecisionAction, Tier } from './types';
+import type { ContinuationPacketWriter } from '../continuation/packet-writer';
+import type { ContinuationPacketReader } from '../continuation/packet-reader';
+import type { HandoffReason } from '../continuation/types';
+/**
+ * CP-1.f — the clean, user-facing one-liner for a synthesized ESCALATE verdict
+ * whose origin is a reviewer subprocess failure. Built ONLY from the closed
+ * `ReviewerFailureReason` + the agent display name via the fixed template
+ * table. Never derived from raw provider output. Exported for the
+ * sanitization test.
+ */
+export declare function failureReasonTemplate(agentKind: ReviewerAgentKind, reason: ReviewerFailureReason): string;
+/**
+ * CP-1.f implementor-round-failure surfacing (dogfood fix 2026-06-10) — classify
+ * a thrown implementor-round error into a SAFE, classified label. NEVER returns
+ * the raw error message / stderr (the wire-safety rule shared with progress
+ * events + synthesized reviewer reasoning).
+ *
+ *   - `AuthorityError` → the closed-category label (`authority_scope_conflict` →
+ *     "blocked by the local authority allowlist", etc.).
+ *   - A spawn/start failure (ENOENT / "spawn" / "not found" on the agent binary)
+ *     → a generic "the agent could not be started" label.
+ *   - Anything else → a generic "an unexpected error occurred" label.
+ *
+ * Exported for the sanitization test (proves no raw message leaks).
+ */
+export declare function classifyImplementorRoundFailure(err: unknown): string;
+/**
+ * PHASE-CP-10-MIN (#585) §3.6 H-C / L1 — classify an implementor failure as a
+ * QUOTA exhaustion (a usage-limit / rate-limit error from the coding-agent CLI).
+ * Returns ONLY a boolean (the `quota_exhausted` label); `resetAt` extraction is
+ * CP-13's, not #585's (Non-goal §1.3).
+ *
+ * The discriminator is the `text` (`exitCode` is informational context — a
+ * usage-limit exit is typically nonzero, but the stderr text is authoritative).
+ * Reads the raw stderr / error message LOCALLY ONLY — never on the wire
+ * (wire-safety; only the closed `quota_exhausted` LABEL crosses the wire).
+ *
+ * Fixtures (L1):
+ *   - Codex (PINNED — CP-13 §0/§2-D1 live sample): `You've hit your usage limit
+ *     … try again at <date>` → match on `usage limit` (case-insensitive).
+ *   - Claude / Gemini: TBD — CP-13 has not captured real samples. Inventing
+ *     strings risks a FALSE-NEGATIVE classifier that misses a real quota error,
+ *     so they are left as additive one-liners to fill once real samples land.
+ *     An UNMATCHED quota error degrades FAIL-SAFE to the existing born-halt
+ *     `surfaceHalt` (the user just doesn't get auto-continuation; identical to
+ *     today) — NOT fail-open.
+ *
+ * Exported for the L1 fixture test (I5).
+ */
+export declare function classifyImplementorQuotaFailure(exitCode: number | undefined, text: string): boolean;
+/**
+ * Audited-path fix (Fix 1) — build the SAFE, no-plaintext desktop advisory text
+ * for a hosted-side PolicyRejection. Uses ONLY the closed `category` classifier
+ * label (a hosted-side enum, NOT user prose — already carried on the existing
+ * mobile NOTIFICATION) + the closed `recommendedRecovery` enum's recovery hint.
+ * The raw `detail` (potential plaintext) is NEVER included. Exported for the
+ * sanitization test. An unknown recovery value falls back to the generic
+ * `ask_user` hint so the advisory always reads cleanly.
+ */
+export declare function policyRejectionAdvisoryText(info: {
+    category: string;
+    recommendedRecovery: string;
+}): string;
+/**
+ * Audited-path fix (Fix 5) — select the implementor `AgentKind` for a START.
+ *
+ *   - An explicit `override` (from `/task --agent codex|claude`) wins, BUT only
+ *     when that agent was actually detected on this host (else fail-closed to the
+ *     default — we never spawn a binary the host doesn't have).
+ *   - Otherwise: CLAUDE when it is among the detected agents (the documented
+ *     default), else the FIRST detected agent, else CLAUDE as the universal
+ *     fail-safe (matches the engine's Claude-only fallback when the host detected
+ *     nothing). The implementor argv allowlist already covers all three agents,
+ *     so any returned kind is spawnable without widening it.
+ *
+ * Returns `{ agent, note }` — `note` is a non-null user-facing string ONLY when
+ * an explicit override could not be honored (so the shell can surface it); null
+ * when the selection was clean. NEVER throws.
+ */
+export declare function selectImplementorAgent(detected: readonly AgentKind[], override?: AgentKind | null): {
+    agent: AgentKind;
+    note: string | null;
+};
+/**
+ * CP-14 WB2 §2.4 (LOCK #C14-WB2-TIER2-INDEPENDENT / #C14-MOAT output-review half) — pick the
+ * final-tip Tier-2 reviewer agent: the strongest HOST-DETECTED reviewer, best-effort INDEPENDENT
+ * of the class-2 resolver agent(s) this gate.
+ *
+ *   - `override` (forward-compat; no desktop surface today) wins, but ONLY when host-detected
+ *     (never spawn an undetected binary — same posture as {@link selectImplementorAgent}).
+ *   - else the strongest detected agent (lowest {@link TIER2_REVIEWER_RANK} index) whose kind is
+ *     NOT in `resolverAgents` (independence). If every detected agent also resolved (single-agent
+ *     host, or ≥2 resolver agents covering all detected), fall back to the strongest detected
+ *     overall — a same-agent Tier-2 is still a FRESH adversarial review of the output.
+ *   - empty detected → `null` → the gate NO-PROMOTEs (the moat's output-review half).
+ *
+ * Inputs/outputs are LE-UPPERCASE `AgentKind`; the dispatcher bridges the result to the lowercase
+ * reviewer wire kind via {@link leAgentToReviewerAgent}. `resolverAgents` is a set of raw strings
+ * (the §4.5 record's `implementorAgent`); non-AgentKind values are simply absent from `.has`.
+ * Pure; NEVER throws.
+ */
+export declare function selectFinalTier2Reviewer(detected: readonly AgentKind[], resolverAgents: ReadonlySet<string>, override?: AgentKind | null): AgentKind | null;
+/**
+ * CP-14 WB2 §2.4 fallback (dogfood-pinned 2026-07-03) — the FULL ordered Tier-2
+ * candidate list, same selection rules as {@link selectFinalTier2Reviewer}
+ * (which is now its head): an explicit host-detected override first, then the
+ * independent candidates by rank, then the resolver-agent candidates by rank
+ * (a same-agent Tier-2 is still a fresh adversarial review of the output — the
+ * documented last resort). The dispatcher walks this list when a candidate
+ * fails to SPAWN/confine (host run 16: the top-ranked independent reviewer
+ * (Codex) died in-sandbox at boot and the merge REJECTED with two healthy
+ * reviewers standing by). A real VERDICT — pass or reject — is authoritative
+ * and never falls through. Pure; NEVER throws.
+ */
+export declare function selectFinalTier2Candidates(detected: readonly AgentKind[], resolverAgents: ReadonlySet<string>, override?: AgentKind | null): AgentKind[];
+/**
+ * CP-7 §8 (Stage-1-resolved) — the narrow result the QuorumLoop consumes from
+ * the reviewer substrate engager. Mirrors `SubstrateLaunch.EngageResult` /
+ * `LocalExecutorImpl.SubstrateEngageResult` but is declared STRUCTURALLY here
+ * (not importing the concrete `engageSubstrate`) so the loop module stays
+ * decoupled and tests inject a stub. Two variants:
+ *  - `substrate` (the moat is ON for this seat — the loop threads
+ *    `substrateHandle` into `evaluate` + calls `teardown()` when the seat
+ *    completes, on EVERY path).
+ *  - `reduced_trust` (the moat is OFF for this seat — A5 coarse host with no
+ *    runtime / Gemini non-Trusted: the loop runs the reviewer on the LEGACY
+ *    unsandboxed path + surfaces the reduced-trust badge).
+ *
+ * THROW semantics (fail-closed): the engager THROWS for a Trusted agent when
+ * the broker cannot start (or any non-`reduced_trust` engage failure). The
+ * loop treats a throw as FAIL-CLOSED — it does NOT silently fall back to the
+ * ambient-cred legacy path (that would defeat the moat); it synthesizes a
+ * clean ESCALATE so the gate resolves rather than hangs.
+ */
+export type ReviewerSubstrateEngageResult = {
+    mode: 'substrate';
+    tier: 'docker' | 'sandbox_exec';
+    reducedTrust: boolean;
+    reducedTrustReason?: string;
+    substrateHandle: SubstrateHandle;
+    teardown(): Promise<void>;
+} | {
+    mode: 'reduced_trust';
+    reducedTrust: true;
+    reducedTrustReason: string;
+    teardown(): Promise<void>;
+};
+/**
+ * CP-7 §8 (Stage-1-resolved) — engage the CP-7 trusted-execution substrate +
+ * broker for ONE reviewer seat (mirrors the implementor's per-spawn engager).
+ * The orchestration shell wires this to `SubstrateLaunch.engageSubstrate`
+ * (with `role: 'reviewer'`), translating the reviewer's lowercase `agent`
+ * (`claude`/`codex`/`gemini`) into the engager's UPPERCASE `agentKind`.
+ *
+ * ABSENT on `QuorumLoopDeps` (legacy / companion / tests) → reviewers take the
+ * legacy unsandboxed path UNCHANGED (byte-identical non-regression). PRESENT →
+ * each Trusted-agent reviewer seat engages the moat (no ambient vendor creds;
+ * model call via the broker), with the §6 Q4 GEMINI / reduced-trust handling
+ * the engager performs internally (returns `reduced_trust`).
+ */
+export type ReviewerSubstrateEngager = (input: {
+    taskId: string;
+    /** The reviewer's lowercase agent (the loop maps it to UPPERCASE inside the wiring). */
+    agent: ReviewerAgentKind;
+    /** Canonical host workdir the sandbox mounts (the loop's working dir). */
+    workdir: string;
+}) => Promise<ReviewerSubstrateEngageResult>;
+export interface QuorumLoopDeps {
+    appsyncClient: AppSyncClient;
+    session: Session;
+    /** The team-mode LE (used for spawnImplementor + spawnReviewer). */
+    localExecutor: LocalExecutor;
+    /** Reviewer registry (production: createSubprocessReviewerRegistry()). */
+    reviewerRegistry: ReviewerRegistry;
+    /**
+     * REVIEWER-VERDICT-GEMMA-CLASSIFIER-DESIGN.md (D1/§Wiring) — the local-Gemma
+     * verdict classifier, forwarded on the `evaluate` opts at BOTH reviewer sites
+     * (per-seat + Wave-B Tier-2) so every reviewer verdict is determined by the
+     * fail-closed classifier instead of the regex `parseVerdictOutput`. Under the
+     * default `gemma` mode this is ALWAYS present (the real classifier, or a dummy
+     * always-ESCALATE classifier when the Gemma runner is null at boot). ABSENT ⇒
+     * the providers use the regex parser — reachable ONLY when the operator sets
+     * `CODEVIBE_REVIEWER_VERDICT_CLASSIFIER=regex` (a deliberate `undefined`,
+     * NEVER an accidental missing-classifier fallback).
+     */
+    classifyVerdict?: VerdictClassifier;
+    /** Resolve the session key for E2E encrypt/decrypt. */
+    getSessionKey: (sessionId: string) => Promise<string | null>;
+    /** Working dir for spawned subprocesses (canonicalized). */
+    workingDir: string;
+    /**
+     * CP-14 Wave A — the team execution model. `worktree_merge` makes each team
+     * track commit to a persistent branch (the merge-before-push spine) instead of
+     * the merge-train promote (the only model since the §10 retirement). Omitted keeps the
+     * shipped path byte-identical. Resolved from `CODEVIBE_TEAM_EXECUTION` when
+     * unset (see {@link resolveTeamExecution}).
+     */
+    teamExecution?: TeamExecution;
+    /**
+     * CP-7 Stage-2 r3 (Codex) HIGH — ARM the LE's current/authorized task id so
+     * the round-0 (and revise) implementor spawn engages the CP-7 trusted-execution
+     * substrate instead of the pre-TaskAuthorized reduced-trust path. `startTask`
+     * threads the minted taskId here BEFORE the round-0 spawn drains (and rolls it
+     * back to `null` on a START rejection); production wires it to
+     * `LocalExecutorImpl.setActiveTaskId`. ABSENT (legacy/tests) → the LE's task id
+     * is unchanged (the pre-fix behavior); production MUST wire it so the
+     * implementor never spawns unbadged/unsandboxed. The same state
+     * (`LocalExecutorImpl.taskId`) drives `engageSubstrateForSpawn` (local-executor-
+     * impl.ts:566) to call `substrateEngager` rather than emit a `tier:'none'` badge.
+     */
+    armLeTaskId?: (taskId: string | null) => void;
+    /**
+     * CP-7 §8 (Stage-1-resolved) — engage the CP-7 trusted-execution substrate +
+     * broker for ONE reviewer seat. When wired (production via cli.ts →
+     * `SubstrateLaunch.engageSubstrate` with `role: 'reviewer'`), each Trusted-
+     * agent reviewer runs INSIDE the sandbox with no ambient vendor creds and a
+     * broker-routed model call — closing the CP-14 §8/§13 reviewer-sandbox gap.
+     * ABSENT (legacy / companion / tests) → reviewers take the legacy unsandboxed
+     * path BYTE-IDENTICAL (§7 non-regression). Reviewer-sandboxing is ALSO gated
+     * behind an opt-in env flag (`CODEVIBE_SANDBOX_REVIEWERS=1`, read in
+     * `engageSeatSubstrate` on the `spawnOneSeat` path) that DEFAULTS OFF — so
+     * even when this engager is wired,
+     * reviewers stay on the legacy path until the broker round-trip is observed
+     * green in a configured env (see `reviewerSandboxingEnabled`). The flag is
+     * independent of implementor sandboxing (which has its own engager).
+     */
+    engageReviewerSubstrate?: ReviewerSubstrateEngager;
+    /**
+     * CP-1.f LOCK RP-6 — this orchestration host's detected coding agents
+     * (UPPERCASE `CLAUDE` / `CODEX` / `GEMINI`), computed ONCE by `cli.ts` via
+     * `detectInstalledAgents` (the SAME UPPERCASE string form
+     * `pushDetectedAgents` sends). Threaded here so `startTask` carries it IN
+     * the request and the gate row's availability is stamped race-free from
+     * THIS host — closing the cross-device shared-`User.availableAgents`
+     * TOCTOU (a legacy companion daemon on another device can no longer union
+     * a stale agent back in between the host's write and the engine's read).
+     *
+     * The `[]` vs ABSENT distinction is load-bearing engine-side: an EMPTY
+     * array (`[]` — host detected nothing) is sent VERBATIM (→ Claude-only
+     * fail-safe, no Users read). ONLY a fully-absent dep (legacy/tests →
+     * `undefined`) omits the field (→ engine Users-table fallback). So
+     * production wires this to a (possibly empty) array; it does NOT leave it
+     * `undefined`.
+     */
+    detectedAgents?: string[];
+    /**
+     * #585 auto-continuation (Max) — the resolved subscription tier (from
+     * `resumeOrCreateSession`: env override → getSubscriptionStatus → FREE).
+     * MAX → a quota-exhausted continuation handoff AUTO-ACCEPTS on the strongest
+     * available agent (no prompt). Pro/Free/unresolved/absent → the existing
+     * `continuation_offer_handoff` prompt (fail-closed). Auto-continuation only
+     * affects the user's OWN agents, so the resolved tier is sufficient (no
+     * separate per-request entitlement fetch).
+     */
+    tier?: Tier;
+    /** Sleep helper (injected for deterministic tests). */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * CP-1.f execute-first (§4) — shadow lifecycle environment (state/shadow dir
+     * roots, TTL, child-kill hook, sleep). Injected for deterministic tests;
+     * production uses the defaults (`~/.codevibe/shadow-state`, `os.tmpdir()`).
+     */
+    shadowEnv?: ShadowEnv;
+    /**
+     * CP-1.f execute-first (#EF-1 / #SR-2) — surface a user-visible halt /
+     * fail-closed message to the orchestration timeline. Wired by the shell to an
+     * `emitShellEvent` NOTIFICATION. ABSENT (tests) → logged only.
+     */
+    surfaceHalt?: (message: string) => void;
+    /**
+     * PHASE-589/469 W1 (LOCK #589-E) — flip the desktop's OWN team track to
+     * `Failed` + render the group-terminal from LOCAL state. Wired by the TEAM
+     * shell to emit a `team_track_terminal` (state `Failed`) shell event through
+     * the SAME store-tap chokepoint the MergeGate convergence uses, then evaluate
+     * local `all-terminal && any-failed` → render "Team halted — track N
+     * failed". TEAM-only — ABSENT on the single-impl path (and in tests) → no-op.
+     * The QuorumLoop reports the engine marker (`submitTrackVerificationOutcome`)
+     * separately; this callback drives the DESKTOP-side render only.
+     */
+    onTeamTrackFailed?: (args: {
+        taskGroupId: string;
+        trackIndex: number;
+        reason: TeamTrackFailureReason;
+    }) => void;
+    /**
+     * PHASE-589/469 W2 — flip the desktop's OWN team track to `Revising` while an
+     * auto-revise round is in flight. Wired by the TEAM shell to emit a
+     * `team_track_terminal` (state `Revising`) shell event through the SAME
+     * store-tap chokepoint the convergence + W1-fail render use. Fired ONLY when
+     * the engine's `submitTrackVerificationOutcome` marker AUTO-REVISED (the
+     * returned `trackState` is NOT `Failed`) — the track stays InFlight and the
+     * desktop re-spawns its implementor on the inbound `REVISE_FEEDBACK`. On
+     * cap-exhaust the marker returns `Failed` instead and `onTeamTrackFailed`
+     * fires (W1's terminal render). TEAM-only — ABSENT on single-impl (and in
+     * tests) → no-op.
+     */
+    onTeamTrackRevising?: (args: {
+        taskGroupId: string;
+        trackIndex: number;
+    }) => void;
+    /**
+     * #606 (FACE A) — flip the desktop's OWN team track terminal the moment the
+     * USER resolves that track's per-track gate (final_approval Approve/Cancel, or
+     * the escalation 5-option Accept/Abort). Closes the #469 "track stuck
+     * InFlight" gap: the per-track USER decision reached NONE of the render-
+     * terminal writers (only `emitGroupConvergence` + the W1 marker path did), so a
+     * user-resolved track stayed `InFlight` in the render until the slow engine
+     * convergence/sweeper. Emits a `team_track_terminal` (state Passed/Failed)
+     * shell event through the SAME `leEmitShellEvent` chokepoint the convergence +
+     * W1/W2 callbacks use — but withOUT a `reason` label, so `routeTeamShell
+     * EventToStore` does the track flip ONLY (it does NOT take the W1 local group-
+     * terminal render branch, which is `reason`-gated; the all-or-nothing GROUP
+     * gate is driven authoritatively by the engine's `TaskGroupHalted` emit, #606
+     * FACE B). TEAM-only — ABSENT on the single-impl path (and in tests) → no-op.
+     */
+    onTeamTrackUserResolved?: (args: {
+        taskGroupId: string;
+        trackIndex: number;
+        state: 'Passed' | 'Failed';
+    }) => void;
+    /**
+     * PHASE-589/469 W3.1 (C1) — the durable revert-manifest store. For a TEAM
+     * track promote, the pre-image manifest is captured + persisted BEFORE the
+     * tree mutates (LOCK #589-I), so a later group reject can revert every applied
+     * track. TEAM-only — ABSENT on single-impl (and in tests) → promote runs the
+     * legacy no-capture path (byte-identical). Wired by the TEAM shell to a single
+     * process-wide `RevertManifestStore`.
+     */
+    durableStore?: RevertManifestStore;
+    /**
+     * CP-1.f live progress surfacing — desktop-LOCAL progress phases (shadow
+     * created, implementor running + periodic tick, diff captured, submitting,
+     * reviewers dispatched, per-seat + verdict progress, revise, promote/discard,
+     * waiting-on-user). Wired by the shell to the Ink store (an ephemeral spinner
+     * line + persisted milestone lines). ABSENT (tests / non-loop sessions) →
+     * no-op. NO backend/wire/schema change: progress NEVER becomes a createEvent.
+     *
+     * SECURITY INVARIANT: events carry ONLY counts/labels/paths/elapsed — never
+     * diff content, file contents, reviewer reasoning, prompts, or any decrypted
+     * plaintext (the `TaskProgressEvent` union is the allowlist). The loop wraps
+     * every emit so a throwing listener can NEVER break the loop.
+     */
+    onProgress?: OnProgress;
+    /**
+     * PHASE-598 — the declared-test EXECUTOR subprocess seam. The per-track
+     * declared-`test_surfaces` runner spawns `node <file>` through this primitive
+     * (default `runShellCommand`, the SAME primitive the CP-3 verification gates
+     * use). Injected so integration tests can stub the executor's `node` runs
+     * without a live `node` subprocess. ABSENT → the real `runShellCommand`.
+     */
+    runShell?: typeof runShellCommand;
+    /**
+     * PHASE-CP-10-MIN (#585) §3.5 — the continuation packet WRITER (the trigger
+     * transport). The `user_requested` (`/continue request`) + `quota_exhausted`
+     * (born-halt fork) triggers call `write()` directly (local CONTINUATION.md +
+     * the `recordContinuationPacketWritten` mutation → server stamps + emits the
+     * handoff prompt). ABSENT (tests / legacy) → the continuation triggers are
+     * unavailable (the quota fork degrades to the generic `surfaceHalt`).
+     */
+    continuationWriter?: ContinuationPacketWriter;
+    /**
+     * PHASE-CP-10-MIN (#585) §3.5 — the continuation packet READER. The resume
+     * (`resumeFromContinuation`) reads the CP-6 `CONTINUATION.md` via this reader,
+     * which hash-verifies + backend-audit-row-verifies (refusing a
+     * `PacketUnverified` packet — the pre-spawn fidelity gate). ABSENT → resume
+     * is unavailable.
+     */
+    continuationReader?: ContinuationPacketReader;
+    /**
+     * PHASE-CP-10-MIN (#585) L-A — clock for minting a fresh per-request
+     * `expiresAt` (`now + TTL`, millisecond precision). Injected for deterministic
+     * tests; production uses `Date.now`.
+     */
+    clock?: () => number;
+    /**
+     * PHASE-CP-10-MIN (#585) §3.5 — the continuation packet TTL (ms) used to mint
+     * `expiresAt = now + TTL`. ABSENT → the default `CONTINUATION_EXPIRES_TTL_MS`.
+     */
+    continuationTtlMs?: number;
+}
+/**
+ * Map the lowercase wire `AgentKind` (`"claude"`) used by the engine dispatch
+ * + the reviewer registry to the UPPERCASE LE `AgentKind` (`"CLAUDE"`) the
+ * spawn path uses. Append-only.
+ */
+declare function reviewerAgentToLeAgent(agent: ReviewerAgentKind): AgentKind;
+/**
+ * Extract the NUMERIC seat-id from the resolved seat-id STRING the engine
+ * dispatch carries (`"1::codex"` → 1, bare `"1"` → 1). Returns null when the
+ * leading token isn't a non-negative integer.
+ */
+export declare function numericSeatId(resolvedSeatId: string): number | null;
+export declare class QuorumLoop {
+    private readonly deps;
+    private readonly sleep;
+    /** The active task this desktop is driving (set at start_task). */
+    private activeTaskId;
+    private taskEpoch;
+    private readonly epochByTaskId;
+    private readonly tokensByTaskId;
+    private readonly tokensCountedGates;
+    /**
+     * The implementor brief for the active task (set at start_task). The
+     * GATE_DISPATCH consumer reads this to drive the round-0 implementor spawn —
+     * the brief is no longer threaded inline through the spawn call (the spawn
+     * moved out of `startTask` into the GATE_DISPATCH consumer, §3.C.20 FIX).
+     */
+    private activeBrief;
+    /**
+     * IMAGE-ATTACHMENT-DESIGN.md §5 — TASK-SCOPED image attachments (parallel to
+     * `activeBrief`/`activeBriefByTask`). The single-impl path uses `activeAttachments`;
+     * the team path keys by the child `taskId` in `activeAttachmentsByTask` (armed at
+     * `registerTeamTaskBrief`, before its buffered GATE_DISPATCH drains). Re-copied
+     * into EACH round's shadow at `runImplementorRound` (round-0, revise, continuation,
+     * per track). A LOCAL-file reference (sourcePath + metadata), never bytes/wire.
+     */
+    private activeAttachments;
+    private readonly activeAttachmentsByTask;
+    /** IMAGE-ATTACHMENT-DESIGN.md §5 — GROUP-keyed team attachments, armed at launch, fanned per-track at `registerTeamTaskBrief`. */
+    private readonly teamAttachmentsByGroup;
+    /**
+     * CP-12 W2.b (§3.C.2 / §3.C.3 / M5) — per-task brief + agent + trackIndex for
+     * the TEAM path. Replaces the single `activeBrief` singleton for multi-task
+     * routing: a `GATE_DISPATCH` whose OUTER envelope `task_id` is a known team
+     * task resolves `{ brief, agent }` HERE (keyed by the track's child `task_id`),
+     * rather than from the single `activeTaskId`/`activeBrief`. Populated by the
+     * brief→task_id bridge at `TrackAssigned` (the shell's `launchTrack` looks up
+     * the parse-time `briefsByTrackIndex.get(track_index)` and inserts here via the
+     * `registerTeamTaskBrief` callback). The single-impl path is UNAFFECTED — its
+     * dispatch carries `envelopeTaskId === this.activeTaskId` (the engine stamps the
+     * owning task on EVERY dispatch), so `handleGateDispatch`'s
+     * `envelopeTaskId !== this.activeTaskId` discriminator falls it through to the
+     * single `activeTaskId`/`activeBrief` spawn (byte-identical to today).
+     */
+    /**
+     * CP-12 W2.b (§3.C.2 / §3.C.4) — TRUE once a `/team` has been issued THIS shell
+     * session (the shell calls `markTeamSessionActive()` at `/team` parse time).
+     * Disambiguates the two cases where a team `GATE_DISPATCH` arrives for a task
+     * NOT yet in `activeBriefByTask`:
+     *   - active (a `/team` ran this session) → an EARLY-PACKET race: the
+     *     `GATE_DISPATCH` beat its track's `TrackAssigned`; BUFFER + drain on
+     *     registration (§3.C.2).
+     *   - NOT active (post-restart: the in-memory brief map is gone, no `/team`
+     *     re-issued) → FAIL LOUD with the §3.C.4 remediation (never spawn an
+     *     empty-brief implementor).
+     */
+    private teamSessionActive;
+    /**
+     * CP-12 W2.b (§3.C.3 / M4) — the per-track briefs, keyed by the COMPOSITE
+     * `teamBriefKey(taskGroupId, trackIndex)`. Captured at `/team` time via
+     * `setTeamBriefs(taskGroupId, …)` (after `createTaskGroup` returns the id) AND
+     * seeded by recovery PASS 1. The `registerTeamTask` bridge + recovery launch read
+     * `getTeamBrief(taskGroupId, trackIndex)` when `TrackAssigned` correlates a track.
+     * Desktop-local — NEVER on the wire.
+     *
+     * CP-12 W4 (#593 Stage-2 r2): keyed by `(taskGroupId, trackIndex)`, NOT bare
+     * `trackIndex` — B.2 (`getInFlightTeamTracks`) aggregates rows across ALL
+     * in-flight groups for the session, so a bare-index key let two groups that
+     * share a `trackIndex` overwrite each other's brief.
+     */
+    private teamBriefsByKey;
+    private readonly activeBriefByTask;
+    /**
+     * CP-1.f revise-context fix (dogfood task 2ac68708, 2026-06-11) — the BINDING
+     * user-requested changes for a task, accumulated across ALL revise rounds.
+     *
+     * Each Reject-with-notes the user submits (desktop OR mobile) is delivered by
+     * the engine on a single synthetic `seat_id === 'user'` finding inside the
+     * `REVISE_FEEDBACK` payload (engine `workflow.rs::open_user_revise_round`).
+     * `handleReviseFeedback` records it here via `recordUserNote` BEFORE composing
+     * the round's brief — a SINGLE capture point that covers both surfaces (the
+     * old `index.ts onTerminalDecision` capture fired only for DESKTOP decisions,
+     * silently dropping mobile-originated notes). The revise brief then re-states
+     * EVERY accumulated note as a BINDING requirement so a later round can never
+     * silently drop an earlier user requirement (the live bug: round-1's JSDoc
+     * requirement evaporated by round 2 because the round-2 implementor brief
+     * carried ONLY round-1's reviewer findings — no original task, no prior user
+     * note). Keyed by taskId so an overlapping terminal signal resolves the right
+     * task's notes.
+     */
+    private readonly userNotesByTask;
+    /** Seats with a reviewer subprocess currently running, keyed `gateId::seatId`. */
+    private readonly runningSeats;
+    /** Seats whose verdict has been submitted, keyed `gateId::seatId`. */
+    private readonly submittedSeats;
+    /**
+     * CP-1.f live progress surfacing — per-gate progress bookkeeping. The
+     * single-task loop receives REVIEWER_DISPATCH packets ONE seat at a time
+     * (no upfront total on the wire), so we count seats DISPATCHED on this desktop
+     * as the "expected" denominator and verdicts SUBMITTED as the numerator. Keyed
+     * by gateId → set of seatIds (idempotent under re-delivery / recovery).
+     */
+    private readonly dispatchedSeatsByGate;
+    private readonly verdictedSeatsByGate;
+    /** Gates with an implementor round currently running. */
+    private readonly inFlightImplementorGates;
+    /** Gates whose implementor output has been submitted. */
+    private readonly submittedOutputGates;
+    /**
+     * PHASE-CP-10-MIN (#585) #C10M-16 / Codex-H1 — the per-task ACTIVE
+     * implementor context. `runImplementorRound` populates it at spawn (wiring
+     * the abort `signal`) + clears it in `finally`. A mid-flight `/continue
+     * request` — or the foreign-accept consumer — sets `handoffClaimed = true` +
+     * calls `handle.abort()` so the still-running original implementor is
+     * suppressed: the post-`await handle.done` path then SKIPS
+     * captureDiff/submit/surfaceHalt/round_failed and just `discardShadow`s. The
+     * DDB mutual exclusion (#C10M-14) only blocks a late `mark_resolved`; this
+     * desktop suppression closes the late-LOCAL-submit race. Keyed by taskId.
+     */
+    private readonly activeImplementorByTask;
+    /**
+     * PHASE-CP-10-MIN (#585) §2.3 / #C10M-16 — offers already resumed (the
+     * dedupe set; keyed on `offer_id`, the same axis as the audit slot #C10M-4).
+     * A LOCAL accept adds the offerId + resumes inline; the `onApplyUserDecision`
+     * consumer suppresses an own-echo whose `offer_id` is already in the set and
+     * drives the resume only for a FOREIGN (mobile-originated) accept. First-add
+     * wins; the second observation is a no-op. `offer_id`-keyed (NOT
+     * `gate_id`-only) because a CANCEL→re-request puts two offers on one gate.
+     */
+    private readonly resumedOffers;
+    /**
+     * PHASE-CP-10-MIN (#585) #C10M-12 / M6 — agents that have quota-failed for
+     * the active task (bounds the quota-substitution loop). Before firing a
+     * quota offer, if EVERY distinct configured agent is already in the set →
+     * terminal `surfaceHalt` instead of another offer. Keyed by taskId; a desktop
+     * restart resets it (acceptable — the user re-decides).
+     */
+    private readonly quotaFailedAgentsByTask;
+    /**
+     * #585 auto-continuation (Max) — offerIds minted by the QUOTA auto-fork
+     * (`handleQuotaExhaustedFork → requestContinuation`), as opposed to the
+     * user-requested `/continue request` path (which mints its OWN distinct
+     * offerId). Max auto-continuation MUST fire ONLY for quota-origin offers; a
+     * user-requested handoff is the user's explicit choice to pick a target and
+     * must NEVER be auto-accepted (Stage-2 Codex+agy HIGH — gate on quota ORIGIN,
+     * not prompt KIND). Bounded by the quota loop (≤ one offer per agent per task).
+     * A desktop restart empties this → a pre-restart quota offer falls back to the
+     * manual prompt (fail-closed; the Max user is prompted instead of auto-resumed).
+     */
+    private readonly quotaContinuationOffers;
+    /** REVISE_FEEDBACK ids already consumed (deterministic dedup). */
+    private readonly seenReviseFeedbackIds;
+    /**
+     * CP-12 W2.b (dogfood team-revise fix, 2026-06-13) — `gateId → taskId` for every
+     * dispatched implementor round. A `ReviseFeedback` packet carries ONLY gate ids
+     * (`ReviseFeedbackPayload` has no per-track `taskId`/`trackIndex`), so the revise
+     * handler has no other way to learn WHICH track (child `task_id`) the revise is
+     * for. Without this the team revise round fell back to the single-impl globals
+     * (`activeTaskId`/`activeImplementorAgent`/`activeBrief`) — empty/wrong in a team
+     * session — and re-spawned the implementor against an empty taskId, throwing
+     * "an unexpected error occurred". Populated at EVERY `runImplementorRound`
+     * (round-0 + revise, single-impl + team) so `payload.gateId` (the parent gate
+     * that produced the REVISE) resolves to the right track. The single-impl path
+     * resolves to `activeTaskId` here too (so NO single-vs-team discriminator — the
+     * downstream `?? this.activeX` fallbacks keep single-impl byte-identical).
+     * Set-only + unbounded, mirroring the sibling `seenReviseFeedbackIds` /
+     * `seenGateDispatchRunIds` / `activeBriefByTask` per-round desktop maps (gate
+     * cardinality is bounded by those same dedup sets).
+     */
+    private readonly taskByGateId;
+    /**
+     * GATE_DISPATCH `gateRunId`s already consumed (idempotent re-delivery dedup).
+     * A sweeper / WS re-deliver of the SAME round-0 dispatch must NOT double-spawn
+     * the implementor. Symmetric to `seenReviseFeedbackIds` (§3.C.20 FIX). The
+     * `runImplementorRound` in-flight/submitted double-guard is the second layer.
+     */
+    private readonly seenGateDispatchRunIds;
+    /**
+     * §4.2 (team recovery double-launch fix — dogfood 2026-06-15) — gateRunIds
+     * whose track `launchRecoveredTrack` has CLAIMED for recovery, stamped
+     * SYNCHRONOUSLY at the dedup point BEFORE the `await recoverLaunch`. Distinct
+     * from `seenGateDispatchRunIds`, which `handleTeamGateDispatch` stamps only
+     * AFTER its async work — leaving a window where a concurrent B.2 recovery
+     * passes the dedup, runs `recoverLaunch` → the `'duplicate'` repair →
+     * `registerTeamTaskBrief` a SECOND time → duplicate gate/verdict/applied/
+     * convergence emits (the dogfood "Applied 1 file…" ×3 / duplicate final_approval;
+     * no data impact, exactly 2 files). Claiming here, before any await, makes the
+     * "recover once" dedup actually atomic. Kept SEPARATE from
+     * `seenGateDispatchRunIds` so the legitimate round-0 gate dispatch still runs
+     * (stamping that set here would suppress the implementor entirely).
+     */
+    private readonly recoveredGateRunIds;
+    /**
+     * §4.1 — DURABLE per-track tombstone for a present-but-CORRUPT brief
+     * ciphertext (decrypt threw during recovery PASS 1). Blocks BOTH recovery
+     * relaunch (PASS 2) AND any future LIVE `TrackAssigned`/drain for that track
+     * (§4.3) — a corrupt brief must NEVER spawn an empty-brief implementor on
+     * EITHER path. The track times out via the engine sweeper (bounded). Distinct
+     * from a `null` `encryptedBrief` (a legit empty brief).
+     *
+     * CP-12 W4 (#593 Stage-2 r2): keyed by the COMPOSITE `teamBriefKey(taskGroupId,
+     * trackIndex)`, NOT bare `trackIndex` — B.2 aggregates across groups, so a
+     * tombstone on group A's track 0 must not block group B's (valid) track 0.
+     */
+    private readonly corruptBriefTracks;
+    /**
+     * #592 PROVENANCE GUARD (2026-06-26) — the task-group ids THIS desktop
+     * ORIGINATED (recorded in `armB1Recovery`, right after a successful
+     * `createTaskGroup`). Class B team packets broadcast PER-USER, and B.2 recovery
+     * (`recoverTeamTracks`) discovers EVERY in-flight group session-wide — so a
+     * SECOND desktop/container on the same account receives + processes this
+     * desktop's `TrackAssigned`/`GateDispatch`. WITHOUT this guard a desktop that
+     * already owns a group pins a FOREIGN group's base on its OWN workspace and
+     * submits an empty round-0 → born-halts the REAL originator's gate (dogfood
+     * 2026-06-26, proven: `bold_lewin` killed another run's gate `7681a432`). When
+     * NON-EMPTY, recovery + live team dispatch DROP any group not in this set. EMPTY
+     * (fresh process / post-crash) → no filter, so legitimate crash-recovery of an
+     * own in-flight group is preserved (the rare two-cold-desktops edge is unchanged).
+     */
+    private readonly ownedGroupIds;
+    /**
+     * CP-12 W4 (#593 Stage-2 r2) — the composite key for `teamBriefsByKey` +
+     * `corruptBriefTracks`. `(taskGroupId, trackIndex)` so two in-flight groups
+     * that share a `trackIndex` (B.2 aggregates session-wide) never collide.
+     */
+    private teamBriefKey;
+    /**
+     * PHASE-589/469 W3.1 (C1) — the GROUP-WIDE monotonic promote-order counter,
+     * keyed by `taskGroupId`. Each team track promote reserves
+     * `[base, base + appliedCount)` so the durable manifest's `promoteOrder` is a
+     * single increasing sequence ACROSS every track in the group — the reverse of
+     * which drives reverse-apply (last-applied reverted first, LOCK #589-I).
+     * In-memory: a crash loses the counter, but the durable manifest already
+     * persists each entry's `promoteOrder`, so the FIRST reservation per group in
+     * this process re-seeds the counter from the manifest's high-water mark
+     * (see {@link reservePromoteOrder}), and a recovery sorts off the persisted
+     * values.
+     */
+    private readonly groupPromoteOrder;
+    /**
+     * PHASE-589/469 (M1) — groups whose `groupPromoteOrder` has already been
+     * seeded from the durable manifest's high-water mark IN THIS PROCESS. The
+     * seed runs ONCE per group per process (the first `reservePromoteOrder`);
+     * thereafter the in-memory counter is authoritative.
+     */
+    private readonly promoteOrderSeeded;
+    /**
+     * PHASE-589/469 W3-H1 (Stage-2 Codex r2) — per-GROUP async MUTEX for
+     * `reservePromoteOrder`. The seed-then-reserve body is a check-then-`await`-then-
+     * act sequence: it marks `promoteOrderSeeded` SYNCHRONOUSLY, then `await`s the
+     * durable manifest high-water read BEFORE setting `groupPromoteOrder`. A SECOND
+     * same-group reservation entering during that await would see `seeded === true`
+     * yet `groupPromoteOrder === undefined`, skip the seed, and reserve `base = 0` —
+     * so two same-group tracks could BOTH reserve base 0 (and the slow first reserve
+     * then clobbers the second's counter write). Two tracks at the same
+     * `(promoteOrder, path)` make `appendPromote` overwrite the older manifest entry
+     * (it dedups idempotently on `(promoteOrder, path)`), losing the original
+     * pre-image so the all-or-nothing revert can't restore baseline.
+     *
+     * The shadow promote mutex (`promoteShadowLocked` / {@link runExclusiveShadowOp})
+     * is keyed per-TASK, but `promoteOrder` is per-GROUP, so this needs its OWN
+     * per-group serialization. Same promise-chain shape as `runExclusiveShadowOp`
+     * (predecessor-rejection-isolated, entry GC'd when the tail it stored settles).
+     */
+    private readonly promoteOrderOpsByGroup;
+    /**
+     * Serialize one `reservePromoteOrder` body for `taskGroupId` behind any in-flight
+     * reservation for the SAME group (mirror of {@link runExclusiveShadowOp}, keyed
+     * per-group not per-task). A predecessor's rejection is isolated at the
+     * sequencing layer; the map entry is GC'd once the tail we appended is still the
+     * current tail (an idle group leaks no entry).
+     */
+    private runExclusivePromoteOrderOp;
+    /**
+     * Reserve `count` contiguous group-wide promote-order slots; returns the base.
+     *
+     * PHASE-589/469 (M1) — on the FIRST reservation for a given `taskGroupId` in
+     * this process, seed the in-memory counter from the durable manifest's
+     * high-water mark (`max(promoteOrder) + 1`) so a post-crash second track (or a
+     * re-promote after the in-memory Map was emptied by a restart) continues ABOVE
+     * the persisted orders and NEVER reuses one. Without this, a crash that empties
+     * `groupPromoteOrder` would let a recovered second track restart at base 0 and
+     * collide with track 0's already-persisted orders — leaving two manifest
+     * entries at the same `promoteOrder` for different paths, whose reverse-apply
+     * order is then undefined (a shared file could be deleted-before-restored).
+     *
+     * TEAM-only + best-effort: the seed reads the durable store only when one is
+     * wired (team tracks); if the manifest read throws, fall back to the current
+     * in-memory base (log a warning, never block the promote).
+     *
+     * Serialized PER-GROUP ({@link runExclusivePromoteOrderOp}, W3-H1) so the whole
+     * seed-then-reserve body is atomic w.r.t. concurrent same-group calls: a second
+     * concurrent reservation WAITS, then reads the now-SEEDED counter and reserves
+     * the next contiguous slot (distinct, non-overlapping bases — never duplicate 0).
+     */
+    private reservePromoteOrder;
+    private reservePromoteOrderLocked;
+    /**
+     * §4.3 — the startup ORDERING BARRIER as a REFCOUNT (Stage-2 r1 Codex HIGH).
+     * `0` ⇒ no recovery seeding in flight ⇒ barrier UP (live TEAM packets consume
+     * normally; single-impl / no-recovery path byte-identical). `> 0` ⇒ at least
+     * one recovery op (B.1 / a B.2 attempt sequence) is seeding ⇒ barrier DOWN
+     * (live TEAM packets BUFFER). It is a refcount, not a boolean, so the barrier
+     * spans the ENTIRE recovery window — incremented SYNCHRONOUSLY at the start of
+     * each recovery op (before its first GSI query, so a live packet arriving
+     * DURING the query is buffered, not consumed empty) and decremented in a
+     * `finally`; the buffered queue is drained ONCE when the count returns to 0.
+     * This also makes concurrent B.1+B.2 safe (no per-op toggle race).
+     */
+    private recoverySeedingDepth;
+    /**
+     * §4.3 — TEAM Class B packets buffered while the recovery seed barrier is up
+     * (`recoverySeedingDepth > 0`). Drained through the normal live handlers AFTER
+     * seeding completes (which now read the seeded brief / hit the corrupt
+     * tombstone). Single-impl / non-team packets are NEVER buffered here.
+     */
+    private readonly bufferedTeamPackets;
+    /**
+     * §4.2 B.1 two-condition latch — TRUE once the Class B subscription has been
+     * established (the `onSubscribed` signal). B.1 fires only when BOTH this AND a
+     * pending `taskGroupId` are set (covers the common case where the subscription
+     * was ALREADY up before `createTaskGroup` returned).
+     */
+    private subscriptionReady;
+    /**
+     * §4.2 B.1 two-condition latch — the `taskGroupId` `createTaskGroup` just
+     * returned, awaiting the subscription-ready condition. CLEARED immediately on
+     * B.1 fire so a later reconnect's `onSubscribed` does not re-run B.1 for an
+     * already-handled group (reconnect recovery is B.2's job).
+     */
+    private pendingB1TaskGroupId;
+    /**
+     * Stage-2 r2 (Codex) FIX A — START in-flight flag. The engine emits
+     * GATE_DISPATCH from INSIDE the `startTask` handler (workflow.rs:3097), BEFORE
+     * the mutation response returns, so the live `onClassBPacket` WS can deliver
+     * GATE_DISPATCH to the desktop BEFORE `await appsyncClient.startTask(...)`
+     * resolves. `startTask` arms the active task + sets this flag BEFORE the
+     * await; while it is set, `handleGateDispatch` BUFFERS the packet (into
+     * `pendingGateDispatches`) instead of spawning, so we never spawn an
+     * implementor for a gate whose START is not yet CONFIRMED. The buffer is
+     * DRAINED only after `startTask` resolves successfully (run the spawn then);
+     * on `startTask` rejection the active context is rolled back + the buffer
+     * discarded (a buffered packet whose START failed never spawns).
+     */
+    private startTaskInFlight;
+    /**
+     * Stage-2 r2 (Codex) FIX A — GATE_DISPATCH payloads that arrived while
+     * `startTask` was in flight (single-impl early-packet race), OR (CP-12 W2.b,
+     * §3.C.2 / agy MEDIUM-2) a TEAM GATE_DISPATCH that arrived BEFORE its track's
+     * `TrackAssigned` registered the brief in `activeBriefByTask`.
+     *
+     * Each entry retains `envelopeTaskId` (the OUTER envelope's `task_id`) so a
+     * buffered TEAM dispatch keeps its routing key — the payload carries no
+     * `taskId`, and the `TrackAssigned` that registers the brief may land AFTER the
+     * `GATE_DISPATCH` under fire-and-forget consumption. The replay-on-registration
+     * drain routes each entry by its buffered `envelopeTaskId`
+     * (`handleGateDispatch(entry.payload, entry.envelopeTaskId)`). For the
+     * single-impl early-packet race the buffered `envelopeTaskId` equals the active
+     * task (the engine stamps the owning task on every dispatch), so the re-invoked
+     * `handleGateDispatch` sees `envelopeTaskId === this.activeTaskId` and falls
+     * through to the single-impl spawn (byte-identical to today).
+     */
+    private readonly pendingGateDispatches;
+    /**
+     * CP-1.f execute-first (§4) — the per-task SHADOW workspace. Created BEFORE the
+     * round-0 implementor spawn, retained across all revise rounds + the review
+     * window, and PROMOTED on `TaskAuthorized` (#PR-1/#PR-3) or DISCARDED on every
+     * other terminal. Keyed by taskId so the class-B consumer + terminal handler
+     * resolve it without threading it through the packet path. One active task per
+     * loop, but a Map keeps the lookup robust across overlapping terminal signals.
+     */
+    private readonly shadowsByTask;
+    /**
+     * PHASE-598 (Codex impl-r5 / LOCK #598-11) — the REVIEWED diff snapshot per TEAM
+     * task, stored when a round's gate goes live (reviewers dispatched). `promoteShadow`
+     * fails-closed if the live shadow drifts from it before promote — the airtight
+     * backstop for a declared test that spawns a DETACHED writer (the test runner waits
+     * only on the direct child, so such a writer can mutate the shadow AFTER the
+     * post-test re-capture passes but BEFORE promote). Presence ⇔ team task: single-impl
+     * never stores, so its promote path is unchanged. Cleared on promote/discard.
+     */
+    private readonly reviewedSnapshotByTask;
+    /** Guards concurrent shadow-create for the same task (round-0 + an early re-deliver). */
+    private readonly shadowCreateInFlight;
+    /**
+     * CP-14 Wave A — the ONE pinned base SHA per task group (`worktree_merge`),
+     * captured (memoized) at the first track of the group BEFORE any shadow is
+     * created, so EVERY track branches from the same base → a deterministic
+     * merge-train input (Stage-1 plan-review MED-3). Promise-memoized so concurrent
+     * track registrations share a single `git rev-parse HEAD`.
+     */
+    private readonly groupBaseShaInFlight;
+    /**
+     * Per-task async MUTEX for shadow LIFECYCLE mutations (restart-race fix,
+     * 2026-06-11 Stage-2 Codex r2). A promise-chain serializes EVERY map/stateDir-
+     * touching shadow op for a task — `ensureShadow`'s create-or-get section,
+     * `discardShadow`, `replaceShadowForRound0`, and `promoteShadow`'s
+     * map/stateDir section — so a check-then-act guard's snapshot (mapped vs the
+     * captured instance) stays TRUE for the whole critical section. Eliminates the
+     * "matched at entry, then replaced while awaiting" class of interleaving (the
+     * third found one-at-a-time: orphan double-discard → unmapped window → full-A-
+     * discard overlapping a restart replacement deleting B's #PR-4 marker).
+     *
+     * The chain holds the LAST queued op's settle promise; `runExclusiveShadowOp`
+     * appends `fn` to run after it, swallows the predecessor's rejection at the
+     * sequencing layer (errors propagate to the OWNING caller, never poison the
+     * chain for the next op), and clears the entry once the tail it stored is the
+     * one that settled (so an idle task leaks no entry). The serialized region is
+     * fs/git-only with NO nested `runExclusiveShadowOp` call (the wrapped methods
+     * never call each other), so it cannot self-deadlock.
+     */
+    private readonly shadowOpsByTask;
+    /**
+     * Serialize one shadow lifecycle op for `taskId` behind any in-flight op for
+     * the same task. The op's result/rejection is returned to ITS caller; a
+     * predecessor's rejection is isolated (caught at the sequencing layer) so it
+     * never poisons a later op. The map entry is cleared only when the tail we
+     * appended is still the current tail (no later op queued behind us).
+     */
+    private runExclusiveShadowOp;
+    /**
+     * The last terminal workspace outcome (promote / discard) this loop applied,
+     * for the `summarize_current_status` shell answer (Fix 2). RELATIVE file paths
+     * only — never any diff content (the user owns the workspace, so paths are
+     * permitted per the promote/discard surface exception; content is not). `null`
+     * until the first promote/discard lands. Updated ONLY when a promote actually
+     * MATERIALIZES files (a re-delivered no-op packet does NOT overwrite it).
+     */
+    private lastWorkspaceOutcome;
+    constructor(deps: QuorumLoopDeps);
+    /** The current active task id (for the recovery poll). */
+    get activeTask(): string | null;
+    /**
+     * Audited-path fix (Fix 5) — the host's detected implementor agents
+     * (UPPERCASE `AgentKind`), as threaded into the loop at construction. Used by
+     * the `/task` deterministic shortcut + the planner `start_task` path to select
+     * which implementor to spawn (default CLAUDE when present, else the first
+     * detected). Returns a shallow copy so callers can't mutate the loop's record.
+     * Empty when the host passed none (a definitive "nothing detected" →
+     * `selectImplementorAgent` falls back to CLAUDE).
+     */
+    /**
+     * IMAGE-ATTACHMENT-DESIGN.md §5 (Stage-2 R3 HIGH): expose the loop's durable
+     * store so the LIVE team-launch sites can persist the RetainedTeamLaunchSpec
+     * (incl. attachments) — otherwise `setTeamLaunchSpec` never runs on a live launch
+     * and `recoverTeamTracks`'s restore has nothing to read. Same instance the loop
+     * uses for reissue/recovery/promote.
+     */
+    getDurableStore(): RevertManifestStore | undefined;
+    getDetectedAgents(): AgentKind[];
+    /**
+     * #585 auto-continuation (Max) — pick the agent to AUTO-CONTINUE on when the
+     * implementor for `taskId` hit a quota wall, or `null` to fall through to the
+     * existing `continuation_offer_handoff` prompt. Returns a target ONLY when:
+     *   (a) tier === MAX (the "don't bother me" automation tier — mirrors auto-revise), AND
+     *   (b) ≥1 host-detected agent is NOT already quota-failed for this task.
+     * The pick is the STRONGEST such agent (`TIER2_REVIEWER_RANK`), deterministic. The
+     * quota-failed set (populated by `handleQuotaExhaustedFork` BEFORE the offer) already
+     * contains the just-failed source agent, so the result is never the agent that just
+     * hit quota. All detected agents quota-failed → `null` (the existing terminal halt
+     * fires). Non-MAX / unresolved / absent tier → `null` (fail-closed to the prompt).
+     * Pure read; never throws.
+     */
+    pickAutoContinuationTarget(taskId: string): AgentKind | null;
+    /**
+     * #585 auto-continuation (Max) — true iff `offerId` was minted by the QUOTA
+     * auto-fork (`handleQuotaExhaustedFork`). Max auto-continuation gates on THIS,
+     * not the prompt kind, so a user-requested `/continue request` handoff (a
+     * distinct offerId) is NEVER auto-accepted (Stage-2 Codex+agy HIGH). Empty
+     * after a desktop restart → returns false → the manual prompt (fail-closed).
+     * Pure read; never throws.
+     */
+    isQuotaContinuationOffer(offerId: string): boolean;
+    /**
+     * PHASE-590 §3.B — the canonicalized real working dir (the repo). The local
+     * team decomposer (`runLocalDecomposer`) spawns a read-only `plan`-mode
+     * implementor against THIS dir so it can read the tree before emitting the
+     * `WorkItemInput[]` decomposition. Read-only accessor (the decomposer never
+     * writes here — `plan` mode).
+     */
+    getWorkingDir(): string;
+    /**
+     * Read-only accessor for the last terminal workspace outcome (promote with its
+     * RELATIVE file paths, or discard). Used by the shell's
+     * `summarize_current_status` answer to name the files last applied. Returns a
+     * shallow copy so a caller can't mutate the loop's record. `null` until the
+     * first promote/discard.
+     */
+    getLastWorkspaceOutcome(): {
+        kind: 'promoted';
+        files: string[];
+    } | {
+        kind: 'discarded';
+    } | null;
+    /** The DI callbacks the shell wires into its ClassBConsumer. */
+    classBConsumerDeps(): {
+        classBSignatureVerifier: (packet: import('../local-executor/types').ClassBInbound) => Promise<boolean>;
+        gateDispatch: (payload: GateDispatchPayload, envelopeTaskId?: string) => Promise<void>;
+        spawnReviewers: (payload: ReviewerDispatchPayload) => Promise<void>;
+        runReviseRound: (payload: ReviseFeedbackPayload) => Promise<void>;
+    };
+    private cachedSigningKey;
+    private verifySignature;
+    /**
+     * Drive the engine START from a planner `start_task` decision. Mints the
+     * taskId, ARMS the active task (taskId/brief/agent), calls the `startTask` SDK
+     * mutation, then DRAINS any GATE_DISPATCH buffered during the START window.
+     *
+     * CP-1.f Wave 3 FIX — the implementor is NOT spawned here. The engine creates
+     * the round-0 `reviewer_quorum` gate with a deterministic gate_id and emits a
+     * GATE_DISPATCH packet carrying it as `gateRunId`; the `startTask` mutation
+     * response carries ONLY the workflow-state LABEL string ("gate_plan_in_flight")
+     * — NOT the gate_id. So the desktop spawns the implementor + submits its
+     * output against `gateRunId` in `handleGateDispatch`. Using `taskId` as the
+     * gate correlation (the prior wiring) is rejected by `submitImplementorOutput`
+     * — it needs the engine's gate_id.
+     *
+     * Stage-2 r2 (Codex) FIX A — the engine emits GATE_DISPATCH from INSIDE the
+     * `startTask` handler (workflow.rs:3097), BEFORE its mutation response returns,
+     * so the live WS can deliver that round-0 GATE_DISPATCH to the desktop BEFORE
+     * the SDK `await` below resolves. To avoid spawning before the START is
+     * confirmed (and to avoid the Stage-1 FIX-3 "drop forever" no-op that hangs the
+     * loop), we ARM the active context + set `startTaskInFlight` BEFORE the await;
+     * an early GATE_DISPATCH is then BUFFERED (not spawned) and DRAINED here once
+     * the START resolves successfully. On rejection the armed context is rolled
+     * back + the buffer discarded (a buffered packet whose START failed never
+     * spawns). Invariant: an early GATE_DISPATCH is never dropped, and the
+     * implementor is never spawned until `startTask` succeeds.
+     *
+     * Best-effort: a backend error is logged + surfaced advisory by the caller
+     * (returns the taskId on success, null on failure so the caller can render the
+     * error). No `gateId` is returned — it is not known until GATE_DISPATCH.
+     */
+    startTask(args: {
+        decision: import('../planner/types').PlannerDecision;
+        brief: string;
+        agent: AgentKind;
+        /** IMAGE-ATTACHMENT-DESIGN.md §5 — task-scoped image attachments, armed before the drain. */
+        attachments?: ImageAttachment[];
+    }): Promise<{
+        taskId: string;
+    } | null>;
+    /**
+     * CP-1.f Wave 3 FIX — consume a GATE_DISPATCH packet. The engine emits this
+     * after `startTask` creates the round-0 `reviewer_quorum` gate; its
+     * `gateRunId` is the round-0 gate_id the desktop submits the implementor
+     * output against (the `startTask` mutation response does NOT carry it).
+     *
+     * Only `gateType === "reviewer_quorum"` spawns the implementor (at START
+     * `reviewerSeats` is absent — the proposal hasn't arrived; the per-seat
+     * fan-out is driven later by REVIEWER_DISPATCH once `submitImplementorOutput`
+     * lands). `verification` gates are CP-3 (out of scope for CP-1.f single-task)
+     * and `final_approval` surfaces via `onEventCreated` INTERACTIVE_PROMPT (§2),
+     * NOT GATE_DISPATCH — both are logged + ignored (no spawn).
+     *
+     * Idempotent: deduped on `gateRunId` (a sweeper / WS re-deliver must not
+     * double-spawn), and `runImplementorRound` is itself double-guarded
+     * (in-flight / already-submitted per gate). Best-effort: errors are logged,
+     * never thrown upward.
+     */
+    handleGateDispatch(payload: GateDispatchPayload, envelopeTaskId?: string): Promise<void>;
+    /**
+     * CP-12 W2.b (§3.C.2 / §3.C.3) — mark a `/team` issued THIS shell session, so
+     * a team `GATE_DISPATCH` for a not-yet-registered track is BUFFERED (early
+     * race) rather than failed-loud (post-restart). The shell calls this at `/team`
+     * parse time (the same parse that captures `briefsByTrackIndex`).
+     */
+    markTeamSessionActive(): void;
+    /**
+     * CP-12 W2.b (§3.C.3 / M4) — bind the parse-time per-track briefs to their
+     * task group + mark the team session active. The shell calls this from the
+     * `/team` command dispatch AFTER `createTaskGroup` returns the `taskGroupId`
+     * (the parse-time briefs are keyed by array `trackIndex`; this re-keys them by
+     * the composite `(taskGroupId, trackIndex)`). Two synchronous statements after
+     * the `createTaskGroup` await, BEFORE `armB1Recovery` — no live `TrackAssigned`
+     * can interleave (single-threaded), so the bridge always finds the brief.
+     *
+     * CP-12 W4 (#593 Stage-2 r2): composite-keyed so two in-flight groups that
+     * share a `trackIndex` never overwrite each other's brief. Desktop-local
+     * (NEVER on the wire). A subsequent `/team` for a NEW group adds its OWN keys.
+     */
+    setTeamBriefs(taskGroupId: string, briefsByTrackIndex: Map<number, string>): void;
+    /**
+     * IMAGE-ATTACHMENT-DESIGN.md §5 — arm the GROUP's image attachments at team
+     * launch (alongside `setTeamBriefs`), BEFORE any `TrackAssigned`.
+     * `registerTeamTaskBrief` fans them per-track into `activeAttachmentsByTask` before
+     * that track's buffered GATE_DISPATCH drains, so the round-0 spawn copies them in.
+     */
+    setTeamAttachments(taskGroupId: string, attachments: ImageAttachment[]): void;
+    /**
+     * CP-12 W2.b (§3.C.3) — read the brief for `(taskGroupId, trackIndex)`. The
+     * `registerTeamTask` bridge (wired in the shell) reads this when `TrackAssigned`
+     * correlates a track to its child `task_id`; recovery PASS 2 reads it for a
+     * relaunched track. Empty string when the user issued no `description` for the
+     * track (a track with no brief runs an empty-brief round-0; the engine's #EF-1
+     * born-halt surfaces it). Composite-keyed (#593 Stage-2 r2) — see `teamBriefKey`.
+     */
+    getTeamBrief(taskGroupId: string, trackIndex: number): string;
+    /**
+     * CP-12 W2.b (§3.C.3 / M5) — the brief→task_id bridge. `launchTrack` calls this
+     * at `TrackAssigned` (the FIRST surface carrying both `track_index` AND the
+     * track's child `task_id`), having resolved the parse-time
+     * `briefsByTrackIndex.get(track_index)` for the brief. Inserts the per-task
+     * brief/agent/scope into `activeBriefByTask`, THEN drains any team
+     * `GATE_DISPATCH` for this `task_id` that arrived BEFORE the track registered
+     * (the §3.C.2 early-packet race). Idempotent: a duplicate `TrackAssigned`
+     * (same generation) re-registers the same entry + the buffered dispatch (if
+     * any) is already drained, so the drain is a no-op.
+     */
+    registerTeamTaskBrief(taskId: string, entry: {
+        brief: string;
+        agent: AgentKind;
+        taskGroupId: string;
+        trackIndex: number;
+        writePaths: string[];
+        autoModifiedFiles: string[];
+        testSurfaces: string[];
+    }): Promise<void>;
+    /**
+     * CP-12 W2.b (§3.C.2) — the TEAM analogue of the single-impl round-0 spawn.
+     * Routes by the OUTER envelope's `task_id` (the payload has none): resolves
+     * `{ brief, agent, write scope }` from `activeBriefByTask`, runs the EXISTING
+     * `runImplementorRound` machinery against the track's child `task_id` + the
+     * scheduler-minted round-0 `gateRunId`, and validates the captured diff against
+     * the track's declared write scope (§3.C.2b option a) before submit.
+     *
+     * - NOT-yet-registered + a `/team` ran this session → BUFFER (early race,
+     *   drained by `registerTeamTaskBrief`).
+     * - NOT-yet-registered + NO `/team` this session (post-restart) → FAIL LOUD
+     *   (§3.C.4) — never spawn an empty-brief implementor.
+     */
+    private handleTeamGateDispatch;
+    /**
+     * INVARIANT enforcement (live dogfood "Reject and restart" race, 2026-06-11):
+     * before a NEW round-0 spawn, drop any STALE shadow still mapped for this task
+     * so `ensureShadow` re-creates a FRESH one. A restart reuses the SAME taskId;
+     * the rejected attempt's shadow may still be mapped here. Tear it down (its
+     * uuid-suffixed dir is owned solely by that instance, so this never affects a
+     * sibling) and clear the task's accumulated binding user notes — a restart is a
+     * fresh round-0 of the ORIGINAL task, so the rejected attempt's revise-context
+     * notes must not bleed into the restart. Clearing notes HERE (the dispatch side)
+     * AND in the matching-instance `discardShadow` path makes BOTH race orders
+     * converge on "restart starts clean." No-op when nothing is mapped (the normal
+     * start_task → first round-0, where the shadow does not yet exist).
+     */
+    private replaceShadowForRound0;
+    private replaceShadowForRound0Locked;
+    /**
+     * CP-14 P1 — the team execution model this session SIGNALS on
+     * `createTaskGroup` (`executionModel`). Always `worktree_merge` since the
+     * §10 retirement (2026-07-03): overlapping-track dispatch with the
+     * merge-train + the server contract gate as the authority.
+     */
+    teamExecutionModel(): TeamExecution;
+    /**
+     * CP-14 Wave A — the ONE pinned group base SHA (memoized): `git rev-parse HEAD`
+     * in the workspace, captured at the FIRST track of the group, BEFORE any track
+     * shadow/branch is created, so every track roots at the same base (Stage-1
+     * MED-3). Concurrent callers share one rev-parse via the in-flight promise.
+     * Throws if HEAD can't be resolved (a non-git workspace is ineligible upstream).
+     */
+    private ensureGroupBaseSha;
+    /**
+     * CP-1.f execute-first (§4) — ensure the per-task SHADOW exists, creating it
+     * BEFORE the round-0 spawn. Idempotent: round-0 + an early GATE_DISPATCH
+     * re-deliver, and revise rounds, all reuse the SAME shadow (the diff is
+     * cumulative shadow-vs-real across revise rounds, D6). Fail-closed (#SR-2): a
+     * create failure throws so the caller never spawns against a half-built shadow.
+     */
+    private ensureShadow;
+    private ensureShadowLocked;
+    /** The shadow for `taskId` (introspection / the terminal promote/discard handlers). */
+    shadowForTask(taskId: string): WorkspaceShadow | undefined;
+    /**
+     * Spawn the EXECUTE-mode implementor for one round in the task's SHADOW,
+     * capture the shadow-vs-real diff, and submit it as the execute-first
+     * artifact (§E1). Factored so round-0 (start_task) + round-N+1 (revise) share
+     * the path; the shadow is reused across revise rounds (D6). The submit return
+     * carries `workflowState` — on `"halted"`/`"idle"` (empty diff / born-halt)
+     * the halt is surfaced SYNCHRONOUSLY (#EF-1), not via the ≤5min sweeper.
+     *
+     * Double-guarded: a gate already in-flight OR already submitted is a no-op.
+     */
+    runImplementorRound(args: {
+        taskId: string;
+        gateId: string;
+        roundNumber: number;
+        brief: string;
+        agent: AgentKind;
+        sessionKey: string;
+        mode?: ImplementorMode;
+        /**
+         * CP-12 W2.b (§3.C.2b option a / H3) — TEAM only. After `captureDiff` and
+         * BEFORE submit, validate every changed file against the track's declared
+         * write scope (`writePaths ∪ autoModifiedFiles ∪ testSurfaces`); an
+         * out-of-scope write FAILS the round LOUDLY (no submit, no promote).
+         * `testSurfaces` is the track's own-module test files (#590), disjointness-
+         * validated by the engine. Absent for the single-impl path (no per-track
+         * confinement).
+         */
+        validateDiffScope?: {
+            writePaths: string[];
+            autoModifiedFiles: string[];
+            testSurfaces: string[];
+            trackIndex: number;
+        };
+    }): Promise<void>;
+    /**
+     * Extract the agent's informational stdout summary (audit-only; reviewers
+     * never see it — they review the captured diff). Best-effort: a failure to
+     * read the summary is NON-fatal (the diff is the source of truth). For Codex
+     * the clean reply is the `--output-last-message` temp file; for Gemini it is
+     * the JSON envelope's `.response`; Claude `--print` is clean stdout.
+     */
+    private extractAgentSummary;
+    /**
+     * [token counter — Phase 2 · P2-2] Best-effort per-round IMPLEMENTOR token count
+     * (input+output). Mirrors `extractAgentSummary`'s capture split: Codex emits its
+     * `--json` usage on stdout even though the SUMMARY is file-captured, so sum that
+     * JSONL stream; Claude parses the `--output-format json` envelope's `usage`.
+     * Gemini/Antigravity are out of scope (undefined). NEVER throws — a read/parse
+     * failure yields `undefined` (segment simply omitted), never breaks the round.
+     */
+    private extractImplementorTokens;
+    /**
+     * PHASE-589/469 W1+W2 (LOCK #589-E/F/H) — on a TEAM track local hard-fail (any
+     * of the 4 closed reasons: `verification_failure` / `out_of_scope_write` /
+     * `review_integrity_violation` / `promote_failure`), report the engine marker
+     * + render the desktop's OWN track from the AUTHORITATIVE returned state:
+     *   (a) report the engine marker (`submitTrackVerificationOutcome`). For a
+     *       REVISABLE reason (`verification_failure` / `out_of_scope_write`) thread
+     *       the round-N `gateId` so the engine can mint the round-N+1 revise round
+     *       (cap permitting). **BEST-EFFORT** — on any failure log a warn and STILL
+     *       proceed (the engine lease sweeper backstops); a marker failure must
+     *       NEVER crash the loop;
+     *   (b) render the desktop's OWN track from the marker's RETURNED `trackState`
+     *       (authoritative, no optimistic divergence):
+     *         - W2 auto-revise (returned state NOT `Failed`, track stays InFlight)
+     *           → `onTeamTrackRevising` (render `Revising`); the engine emits
+     *           `REVISE_FEEDBACK` → `handleReviseFeedback` re-spawns the implementor;
+     *         - terminal-fail (returned `Failed`: a TERMINAL reason, OR a revisable
+     *           reason at cap-exhaust) → `onTeamTrackFailed` (render `Failed` +
+     *           group-terminal from LOCAL state);
+     *         - a thrown marker (state unknown) → `onTeamTrackFailed` (the honest
+     *           "round failed, couldn't drive a revise" render; the lease sweeper
+     *           eventually terminal-fails the engine track to match).
+     * TEAM-only — caller guards on `validateDiffScope`; single-impl never calls
+     * this. The `taskGroupId` is resolved from the per-task team registry
+     * (`activeBriefByTask`); if it is absent (a non-team task) this is a no-op.
+     * W2 scope: NO revert, NO engine halt-emit (those are W3).
+     *
+     * `gateId` is the track's CURRENT round-N reviewer_quorum gate; REQUIRED for a
+     * revisable reason (the engine rejects a revisable marker without it). The
+     * TERMINAL-reason callers omit it.
+     */
+    private reportTeamTrackFailure;
+    /**
+     * No-op UX (#1) — report the BENIGN no-change terminal for a TEAM track that
+     * produced an empty diff. Sends the engine the `no_change` outcome (→ the engine
+     * marks the track `TrackState::Passed` via `pass_track_and_schedule`; the
+     * scheduler fires the MergeGate on all-terminal-no-failure — NEVER the all-or-
+     * nothing revert) and flips the desktop's OWN track render out of `InFlight` to
+     * `Passed` via the no-`reason` `onTeamTrackUserResolved` chokepoint (track flip
+     * ONLY; the GROUP terminal stays engine-authoritative). Best-effort: a marker
+     * failure is backstopped by the engine lease sweeper. The PARALLEL of
+     * `reportTeamTrackFailure`, but for the benign no-change outcome (no `gateId` —
+     * `no_change` is non-revisable). TEAM-only.
+     */
+    private reportTeamTrackNoChange;
+    /**
+     * #606 (FACE A) — flip the desktop's OWN team track render-terminal from a
+     * per-track USER decision. Called by the shell's `onTerminalDecision` (the
+     * shared TTY + non-TTY gate-resolution chokepoint) AFTER a successful
+     * `applyUserDecision`, with the task's id + the engine's returned `postAction`.
+     *
+     * Resolves the track via the EXISTING `(taskId → taskGroupId, trackIndex)`
+     * correlation (`activeBriefByTask`, registered at TrackAssigned), maps the
+     * `postAction` to the render-terminal state via the locked
+     * `postActionTeamTrackState` (which MIRRORS the engine's
+     * `fire_deferred_track_terminal` disposition), and fires
+     * `onTeamTrackUserResolved` so the shell emits a `team_track_terminal`
+     * (Passed/Failed) through the SAME chokepoint the W1/W2 callbacks use.
+     *
+     * NO-OP (single-impl byte-identical) when:
+     *   - the task is not in `activeBriefByTask` (single-impl / unknown task), or
+     *   - its `taskGroupId` is empty (single-impl registration), or
+     *   - the `postAction` is non-terminal (`open_new_round` / `restart_proposal` /
+     *     `continuation_switch_*` → a new gate follows; the track keeps working).
+     *
+     * Best-effort: a throwing listener can NEVER break the decision path (the
+     * desktop never fails a user's decision on a render-flip emit error; the engine
+     * `TaskGroupHalted` convergence is the authoritative group resolution).
+     */
+    reportTeamTrackUserResolved(taskId: string, postAction: PostDecisionAction): void;
+    /**
+     * CP-1.f execute-first — discard the task's shadow (a non-TaskAuthorized
+     * terminal). Best-effort: a teardown failure is logged + leaves the durable
+     * marker for the next-startup GC (#GC-2 lazy cleanup). Forgets the in-memory
+     * handle so a later promote can't run against a torn-down shadow.
+     *
+     * INSTANCE-PINNED (live dogfood race 2026-06-11, option-4 "Reject and restart"):
+     * a RESTART reuses the SAME taskId. The decision-time discard fires
+     * asynchronously (after the `applyUserDecision` SDK await) while the engine
+     * ALSO emits a fresh round-0 GATE_DISPATCH for the restart — which replaces
+     * the task's map entry with the NEW round's shadow. An instance-BLIND
+     * `shadowsByTask.get(taskId)` here would then discard the NEW shadow out from
+     * under the starting implementor ("Implementor round 0 failed — could not be
+     * started"). So the caller captures the shadow INSTANCE at decision time (BEFORE
+     * the SDK await, before the restart dispatch can win the race) and threads it as
+     * `expected`. When `expected` is given:
+     *   • it MATCHES the currently-mapped shadow → discard it as before (this round
+     *     is genuinely terminal); clear the notes (terminal, no more revise rounds).
+     *   • it does NOT match (a NEWER shadow replaced it — the restart dispatch won)
+     *     → the captured instance is ORPHANED: tear down ITS directory directly
+     *     (each shadow owns a uuid-suffixed dir, so this never touches the live
+     *     sibling), but LEAVE the map + the new shadow + the notes untouched (the
+     *     restart's fresh-shadow dispatch already cleared + now owns the notes), and
+     *     do NOT print the "discarded — tree unchanged" milestone (a debug log only).
+     *
+     * When `expected` is omitted (the internal born-halt / round-failure callers at
+     * runImplementorRound) the behavior is exactly as before — discard whatever is
+     * currently mapped for the task.
+     */
+    discardShadow(taskId: string, expected?: WorkspaceShadow): Promise<void>;
+    private discardShadowLocked;
+    /**
+     * CP-1.f execute-first (#PR-1/#PR-3) — promote the task's shadow onto the real
+     * tree. Driven ONLY by the `TaskAuthorized` Class-B edge (covers all 3
+     * authorize paths). Idempotent (#PR-4): a second call (packet + recovery
+     * double-fire) is a safe no-op via the durable `promoted` marker. Fail-closed
+     * (#SR-2): conflicts/errors are surfaced to the user, never a silent
+     * half-applied tree.
+     */
+    promoteShadow(taskId: string): Promise<void>;
+    /**
+     * CP-12 W2.b (§3.C.2b (d) / H3-4) — promote-quiescence BARRIER for `taskId`.
+     * Enqueues an EMPTY critical section behind any in-flight shadow lifecycle op
+     * (notably `promoteShadow`) for this task on the SAME per-task
+     * `runExclusiveShadowOp` mutex, so it resolves only once that task's shadow-op
+     * chain has fully drained. `runMergeGate` (on `LocalExecutorImpl`) cannot call
+     * the private `runExclusiveShadowOp` directly, so this PUBLIC delegator is the
+     * surface the team LE dep `awaitTaskShadowQuiescent` wires to — mirroring how
+     * `promoteShadow` (above) is the public delegator over the same private mutex.
+     * It awaits any in-flight promote for the task before MergeGate's integration
+     * check reads the real tree, with NO new locking primitive.
+     */
+    awaitTaskShadowQuiescent(taskId: string): Promise<void>;
+    private promoteShadowLocked;
+    private promoteShadowLockedInner;
+    /**
+     * [live task status timer §3] The promote TAIL — (re)opens the busy window with
+     * `promoting`, applies the reviewed `diff`, then emits either the `promoted`
+     * milestone (success) or returns silently (marker-flip no-op / apply-conflict).
+     * Extracted from `promoteShadowLockedInner` so that method's `try/finally` wraps
+     * EXACTLY the post-`promoting` strand exits — never the pre-`promoting`
+     * no-op/re-delivery/discard returns (which must stay silent). All emits carry the
+     * caller-resolved `originEpoch`.
+     */
+    private promoteApplyLocked;
+    /** #SR-2 — surface a halt/fail-closed message to the user (or log if unwired). */
+    private surfaceHalt;
+    /**
+     * PHASE-598 — the thin wiring that supplies the real fs/shell deps to the pure
+     * `runDeclaredTestSurfaces` executor (unit tests inject mocks into the free
+     * function; integration tests stub the executor's `node` runs via
+     * `QuorumLoopDeps.runShell`). `readdir` is wrapped to `{ withFileTypes: true }`
+     * so the executor sees `Dirent`s (the directory-expansion symlink discriminate).
+     */
+    private runDeclaredTestSurfaces;
+    /**
+     * [live task status timer §3] Origin epoch for an emit context. Resolves from
+     * the ORIGINATING task's id (never `this.taskEpoch` read at emit time — an async
+     * re-delivery may run after a LATER `startTask`). Callers pass their in-scope
+     * taskId (or the `taskByGateId[gateId]` bridge). `?? this.taskEpoch` defends a
+     * post-restart entry (a bounded residual, per design).
+     */
+    private originEpochFor;
+    /**
+     * CP-1.f live progress surfacing — emit ONE desktop-local progress phase.
+     * Failure-safe: a throwing listener is caught + logged, NEVER propagated into
+     * the loop (a render bug must not break the quorum). Synchronous — never
+     * awaited, never blocks the loop. No-op when unwired (tests / non-loop).
+     */
+    private emitProgress;
+    /**
+     * [token counter — Phase 2 · P2-2] Strictly-ADDITIVE per-task token accrual.
+     * `n` is clamped by `finiteToken` (P2-0) so a malformed CLI field contributes 0,
+     * never poisons the accumulator (→ `NaN`/regression). Additive-only means the
+     * reducer's `Math.max` tick-refresh carry is idempotent (a re-delivery never
+     * decreases). No-op for a null taskId or a 0 clamp.
+     */
+    private addTaskTokens;
+    /**
+     * [token counter — Phase 2 · P2-2] The per-task CUMULATIVE total for stamping.
+     * Null-tolerant (MED-1: `seat_update`/`verdicts_progress` resolve taskId via
+     * `taskByGateId[gateId]`, `undefined` after a restart). The `|| undefined`
+     * (falsy-collapse, NOT `??`) is load-bearing: a `0`/absent entry OMITS the
+     * ` · ↓ <tokens>` segment rather than rendering `↓ 0`. Mirrors `originEpochFor`.
+     */
+    private tokensFor;
+    /**
+     * [token counter — Phase 2 · P2-3] Emit a progress phase with BOTH the entry-
+     * cached `originEpoch` AND the LIVE token total injected at CALL time. CRITICAL
+     * (Codex-H3): `tokensFor(taskId)` is read HERE, per emit — NOT cached at function
+     * entry — because `addTaskTokens` (implementor exit, reviewer success) runs BEFORE
+     * the same function's later `diff_captured`/`submitting_diff`/`verdicts_progress`
+     * emits; caching at entry would stamp the OLD total and the last reviewer's tokens
+     * would vanish when `waiting_user` closes the window. Only `originEpoch` is entry-
+     * cached (correct — the epoch is fixed for the task); tokens are read fresh.
+     */
+    private emitProgressForTask;
+    /**
+     * CP-1.f live progress surfacing — cheap, best-effort, time-bounded count of
+     * the files changed so far in the shadow for the per-tick status line. Bounded
+     * to the tracked set; SKIPPED (returns undefined) when the workspace is large
+     * (`TICK_SCAN_MAX_TRACKED`) or the scan exceeds `TICK_SCAN_TIMEOUT_MS`. NEVER
+     * throws + NEVER blocks the loop (the tick fire-and-forgets it). Returns ONLY
+     * a count — never any file content or path payload.
+     */
+    private tickFileChangeCount;
+    /**
+     * Submit the execute-first artifact with NotFound retry-with-backoff, and
+     * RETURN the engine's `{ gateId, workflowState }` so the caller can read the
+     * SYNCHRONOUS born-halt label (#EF-1 / agy M4). On exhausted retries the last
+     * error propagates (the caller surfaces it fail-closed).
+     */
+    private submitImplementorOutputWithRetry;
+    private handleReviewerDispatch;
+    /**
+     * §3.C.21 — spawn + run ONE reviewer seat, then submit its verdict.
+     * Double-guarded (§3.C.21b LOCK): a seat already running-in-memory OR
+     * already verdict-submitted is a no-op, so a live packet + a recovery
+     * re-spawn never double-run the same seat. On a reviewer error/timeout, a
+     * synthesized ESCALATE verdict is submitted (#C1F-8) so the gate never hangs.
+     */
+    spawnOneSeat(args: {
+        gateId: string;
+        seatId: number;
+        role: ReviewerRole;
+        agentKind: ReviewerAgentKind;
+    }): Promise<void>;
+    /**
+     * Audited-path fix (Fix 9) — run `reviewerRegistry.evaluate` under the
+     * DEFENSE-IN-DEPTH per-seat wall-clock guard. Returns the verdict if `evaluate`
+     * settles within `SEAT_EVALUATE_TIMEOUT_MS`; throws `SeatTimeoutError` if the
+     * guard fires first. The abandoned `evaluate` promise is given a no-op `.catch`
+     * so a late rejection (the subprocess `runReviewer` self-kill at 5 min throws a
+     * `timeout` ReviewerError) does NOT surface as an unhandled rejection. The guard
+     * never touches any process — `runReviewer` owns + kills its own child.
+     */
+    private evaluateSeatWithTimeout;
+    /**
+     * CP-7 §8 (Stage-1-resolved) — engage the trusted-execution substrate +
+     * broker for ONE reviewer seat (mirrors the implementor's per-spawn engage).
+     * Returns `{ handle?, teardown }`:
+     *   - `handle` PRESENT → sandboxed; the seat's model call routes through the
+     *     broker (no ambient vendor creds reach the reviewer subprocess).
+     *   - `handle` ABSENT → the seat runs the LEGACY unsandboxed path.
+     *   - THROWS `ReviewerErrorClass` (spawn_failed) → FAIL-CLOSED: a Trusted-
+     *     agent broker-engage failure. The caller turns this into a clean
+     *     synthesized ESCALATE — it does NOT fall back to the ambient-cred legacy
+     *     path (that defeats the moat).
+     *
+     * TRI-STATE (decided here, mirroring the implementor LE):
+     *   1. No engager wired OR `CODEVIBE_SANDBOX_REVIEWERS` not opted in (DEFAULT
+     *      OFF; opt in with `=1`/`=true`) → LEGACY (byte-identical non-regression).
+     *      No badge.
+     *   1b. No resolvable taskId (cannot scope a per-task broker) → LEGACY + a
+     *      reduced-trust badge (Stage-2 r1 Codex LOW — a trust-downgrade must be
+     *      VISIBLE, never a silent ambient-cred fallback; see
+     *      `surfaceReviewerReducedTrust` at the no-taskId branch below).
+     *   2. GEMINI (non-Trusted, §6 Q4) → LEGACY + reduced-trust badge. We do NOT
+     *      call the engager for Gemini (it would throw the non-Trusted error);
+     *      pre-checking the agent kind avoids string-matching that throw and keeps
+     *      a Gemini seat RUNNING (just unsandboxed + badged), never escalated.
+     *   3. Engager returns `reduced_trust` (no runtime / coarse host) → LEGACY +
+     *      reduced-trust badge.
+     *   4. Engager returns `substrate` → SANDBOXED. A `reducedTrust` (A5 coarse)
+     *      result still runs sandboxed but surfaces the coarse badge.
+     *   5. Engager THROWS for a Trusted agent (broker-start failure, etc.) →
+     *      FAIL-CLOSED (re-thrown as ReviewerErrorClass spawn_failed).
+     *
+     * `teardown()` is ALWAYS safe to call (a no-op on the legacy path); the caller
+     * invokes it in a `finally` so a sandbox never leaks.
+     */
+    private engageSeatSubstrate;
+    /**
+     * CP-7 §8 (Stage-1-resolved) — surface the PROMINENT reduced-trust badge for a
+     * reviewer seat (mirrors the implementor's badge, scoped to the loop's
+     * available NOTIFICATION channel). The moat being OFF/coarse for a reviewer is
+     * VISIBLE + auditable, never silent: a user-visible NOTIFICATION (via
+     * `surfaceHalt`, the loop's NOTIFICATION surface) + a WARN log. Best-effort —
+     * unlike the implementor's `tier:'none'` path this is NOT delivery-gated,
+     * because a reviewer reduced-trust badge does not change whether the seat
+     * RUNS (it always runs; the badge only informs the user).
+     */
+    private surfaceReviewerReducedTrust;
+    /**
+     * Wave B §2.1 confinement TRI-STATE for a merge-gate model/reviewer invocation
+     * (LOCK #C14-MOAT). Path A: the CP-7 substrate/broker (opted in + a Trusted agent
+     * + engage succeeds → a handle; no ambient vendor cred in the child). Path B: a
+     * trusted-container boundary (legacy spawn confined by the OUTER container — the
+     * dogfood/E2E path). Path C: neither → NOT confined. A path-A engage that
+     * throws/reduced-trusts falls through to B/C (both safe: B confined, C refuses),
+     * so a broker hiccup never silently runs unconfined.
+     */
+    private engageWaveBConfinement;
+    /**
+     * Wave B §2.1 — build the CONFINED class-2 model caller for a merge gate, or
+     * `null` on path C (no confinement → the gate runs without a resolver; conflicts
+     * halt to the human gate; no unconfined LLM resolver ever runs — LOCK #C14-MOAT).
+     * The model call reuses the proven reviewer subprocess (`runReviewer`, `claude
+     * --print`, read-only allowlist), routed through the substrate broker on path A
+     * or the trusted-container legacy spawn on path B.
+     */
+    makeConflictModelCaller(args: {
+        ownerTaskId: string;
+    }): Promise<{
+        caller: ConflictModelCaller;
+        teardown: () => Promise<void>;
+    } | null>;
+    /**
+     * CP-14 WB2 §2.1/§2.2/§2.3 — build the AGENTIC class-2 resolver, or `null` on
+     * path C (no confinement). When wired, a slot's class-2 conflicts are resolved
+     * by re-dispatching the INCOMING track's implementor (read+write) inside a
+     * disposable repo, then fd-safe selective-importing ONLY the conflicted files.
+     * SECURITY-CRITICAL — fail-closed on BOTH layers:
+     *
+     *   1. CONSTRUCTION-time (mirrors `makeConflictModelCaller` returning null): probe
+     *      `engageWaveBConfinement` ONCE against the loop workdir; path C → return
+     *      `null` → `resolveAgentic` is NOT set on the context → a fresh class-2
+     *      conflict takes the legacy `caller` path (which on path C is the
+     *      CONFINEMENT-UNAVAILABLE caller → human-gate). Byte-identical to today.
+     *   2. DISPATCH-time (Stage-2 Codex HIGH — confinement BOUND TO THE ACTUAL SPAWN):
+     *      `dispatchImplementor` spawns with `requireConfined: true`, so
+     *      `LocalExecutor.spawnImplementor` → `engageSubstrateForSpawn` THROWS
+     *      `SpawnConfinementUnavailable` on EVERY non-substrate-engaged outcome (no
+     *      engager / pre-task / `reduced_trust`) instead of returning the legacy
+     *      unsandboxed args. The closure maps that throw → `AgenticDispatchUnconfinedError`
+     *      → `resolveAgenticSlot` → a clean `human_gate`. NEVER an unconfined spawn.
+     *
+     * The confining substrate is established by `spawnImplementor` itself
+     * (`engageSubstrateForSpawn`, keyed on the real `taskId` + `workingDir =
+     * realpath(disposableRepo)`), which mounts ONLY the disposable repo. There is NO
+     * separate per-resolve probe (the prior "prove then tear down then spawn" design
+     * proved confinement on a handle the LE discarded — Codex correctly flagged that the
+     * separate engage could still yield `reduced_trust`; the `requireConfined` spawn IS
+     * now the sole, correctly-bound dispatch-time gate). The construction probe (layer 1)
+     * is only the coarse wire-vs-legacy decision. On a path-B host with no FS-scoping
+     * substrate (the dogfood — bwrap can't namespace a nested container) WB2 fail-closes
+     * here; a successful resolve requires a real path-A substrate (production).
+     */
+    makeAgenticResolver(args: {
+        ownerTaskId: string;
+    }): Promise<{
+        resolveAgentic: NonNullable<ConflictResolverContext['resolveAgentic']>;
+        teardown: () => Promise<void>;
+    } | null>;
+    /**
+     * Wave B §2.3 (LOCK #C14-FINAL-TIER2 / #C14-MOAT) — dispatch the mandatory
+     * final-tip Tier-2 reviewer over the integration diff (base → tip), CONFINED via
+     * the §2.1 tri-state. Returns `confined: false` on path C (the gate fails closed,
+     * NO-PROMOTE). A non-APPROVE verdict OR a reviewer error → `reject` (fail-safe: an
+     * LLM byte never promotes on an unclear Tier-2). Reuses the per-gate reviewer
+     * registry + the read-only reviewer allowlist over the resolved review surface.
+     */
+    dispatchFinalTier2Review(args: {
+        ownerTaskId: string;
+        repoDir: string;
+        baseSha: string;
+        integrationTip: string;
+        /** CP-14 WB2 §2.4 — the class-2 resolver agent(s) this gate (for independent selection). */
+        resolverAgents?: ReadonlySet<string>;
+        /** Forward-compat desktop override (no surface today; honored only when host-detected). */
+        tier2ReviewerOverride?: AgentKind | null;
+        /**
+         * CP-14 WB2 §2.6 (additive) — the per-conflict 3-way CONTENT + per-track INTENT
+         * diffs to fold into the reviewer prompt. ALL OPTIONAL: absent ⇒ today's bare
+         * base→tip diff (graceful degrade). The aggregate bundle is byte-bounded with
+         * fail-closed overflow (over `WAVE_B_TIER2_MAX_BUNDLE_BYTES` → reject/NO-PROMOTE).
+         */
+        conflictBundle?: readonly RenderedConflict[];
+        trackIntentDiffs?: readonly TrackIntentDiff[];
+    }): Promise<{
+        verdict: 'pass' | 'reject';
+        confined: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Synthesize an ESCALATE verdict for a seat that could NOT produce a real
+     * verdict, so the gate resolves instead of hanging (#C1F-8).
+     *
+     * CP-1.f sanitization invariant (LOAD-BEARING): the wire `reasoning` is a
+     * CLEAN, classified one-liner from the fixed template table — NEVER raw
+     * stderr / stdout / the raw `spawn_failed.reason`. The `synthesized ESCALATE
+     * (#C1F-8): …` audit prefix lives ONLY in logs (the caller logs it), never
+     * on the wire.
+     *
+     * @param reasoning the final clean wire `reasoning` (already a fixed template).
+     */
+    private synthesizeEscalate;
+    private submitVerdict;
+    /**
+     * On WS (re)connect/startup, poll for the seats assigned to this desktop for
+     * any in_review gate of the active task and spawn any seat NEITHER already
+     * running-in-memory NOR already verdict-submitted (double-guard). Without
+     * this, a REVIEWER_DISPATCH dropped during a WS gap hangs the gate forever.
+     */
+    recoverInReviewAssignments(): Promise<void>;
+    /**
+     * CP-1.f execute-first (#GC-1 / #PR-4) — on session-start/WS-resync, GC
+     * orphaned shadow dirs (un-signalled auto-halts leave NO terminal edge, so
+     * their temp dirs would leak) while NEVER deleting an authorized-but-pending
+     * shadow. The active task's shadow is KEPT (it may still promote/discard); a
+     * `promoted`-or-expired orphan is reaped.
+     *
+     * Promote-on-recovery (#PR-4) of a dropped `TaskAuthorized`: the durable
+     * `pending`→`promoted` marker makes promote idempotent, so a re-delivered
+     * `TaskAuthorized` packet after reconnect promotes safely (the live edge is
+     * the recovery path). A `getTaskState` query for an eager promote of an
+     * authorized-but-pending shadow whose packet was permanently lost is the only
+     * residual — until then the GC reaper KEEPS such a shadow (it is never reaped
+     * while `pending` and un-expired), so the approved code is never lost; a
+     * re-delivered packet (or the next live edge) promotes it.
+     */
+    recoverShadows(): Promise<void>;
+    /**
+     * §4.3 — true while a team recovery is seeding briefs (the startup barrier is
+     * down). The Class B consume path checks this to BUFFER a live TEAM packet
+     * instead of consuming it before PASS-1 seeding finishes. Single-impl /
+     * non-team packets are unaffected (the barrier is team-scoped — the caller
+     * only buffers TEAM packets).
+     */
+    isRecoverySeeding(): boolean;
+    /**
+     * §4.3 (Stage-2 r1 Codex MED) — true if `(taskGroupId, trackIndex)` carries a
+     * corrupt-brief TOMBSTONE. The LE consults this at the TOP of `launchTrack`
+     * (before any register / spawn / lease-renewing progress emit) so a tombstoned
+     * track is refused on the LIVE path as early as on the recovery path — never
+     * spawning an empty-brief implementor or mutating registry state for it. The
+     * engine sweeper times the un-launched track out (bounded).
+     *
+     * CP-12 W4 (#593 Stage-2 r2): keyed by `(taskGroupId, trackIndex)` so a corrupt
+     * brief in group A never blocks a different group B's track with the same index.
+     */
+    isTrackTombstoned(taskGroupId: string, trackIndex: number): boolean;
+    /**
+     * #592 PROVENANCE GUARD (live path) — true if `taskGroupId` is a team group this
+     * desktop did NOT originate AND this desktop owns ≥1 group. Wired to the LE's
+     * `isForeignTeamGroup` team-dep, consulted at the TOP of `launchTrack` (right
+     * after the tombstone gate) so a foreign group's LIVE `TrackAssigned` is refused
+     * before any spawn — the symmetric counterpart to the recovery-path filter in
+     * `recoverTeamTracks` / `launchRecoveredTrack`. Returns FALSE when the owned-set
+     * is empty (fresh process / post-crash) so own-group launch + crash-recovery are
+     * unaffected. See `ownedGroupIds`.
+     */
+    isForeignTeamGroup(taskGroupId: string): boolean;
+    /**
+     * §4.3 — buffer a live TEAM Class B packet while the recovery seed barrier is
+     * down. Returns true if buffered (the caller must NOT consume it live). The
+     * caller (`index.ts` onPacket / the LE consume path) only routes TEAM packets
+     * here; single-impl / non-team packets bypass this entirely.
+     */
+    bufferTeamPacketDuringSeeding(kind: 'trackAssigned' | 'gateDispatch', payload: unknown, envelopeTaskId?: string): boolean;
+    /**
+     * §4.3 — drain the buffered live TEAM packets through the normal live handlers
+     * AFTER the recovery seed barrier lifts (`recoverySeedingDepth === 0`). Each
+     * handler now reads the SEEDED brief (or hits the corrupt tombstone and refuses
+     * to launch). `seenGateDispatchRunIds` dedups a packet both recovery and the
+     * drained-live path would drive. Best-effort — a per-packet throw is logged.
+     */
+    private drainBufferedTeamPackets;
+    /**
+     * §4.3 (Stage-2 r1 Codex HIGH) — run a recovery op UNDER the refcount barrier.
+     * Increments `recoverySeedingDepth` SYNCHRONOUSLY (before `fn`'s first GSI
+     * query, so a live TEAM packet arriving during that query is buffered, not
+     * consumed with an empty brief), then decrements in `finally`; the buffered
+     * queue drains ONCE when the count returns to 0 (so concurrent B.1+B.2 share
+     * one barrier window and drain exactly once after BOTH finish). `fn` is
+     * already fail-open internally; a throw still releases the barrier + drains.
+     */
+    private withRecoveryBarrier;
+    /**
+     * §4.2 / §4.3 (Stage-2 r2 Stage-1 M1) — run the `/team` CREATE + brief-bind under
+     * the SAME refcount seed barrier the recovery path uses. The parse-time briefs
+     * can only be bound by `(taskGroupId, trackIndex)` AFTER `createTaskGroup`
+     * returns the group id; the engine emits the per-track `TrackAssigned`/round-0
+     * `GateDispatch` BEFORE that response, so when the Class B subscription is
+     * already up a live packet can be delivered DURING the create round-trip. Running
+     * the whole create+bind under this barrier makes such an in-window packet BUFFER
+     * (`isRecoverySeeding()` true → `bufferTeamPacketDuringSeeding`) instead of
+     * registering with an empty brief; the barrier releases + drains AFTER the briefs
+     * are bound, so the buffered packet re-consumes with the correct brief. The
+     * `seenGateDispatchRunIds` dedup makes the subsequent B.1 a no-op for an
+     * already-launched track. Generic — returns the fn's value (the new group id).
+     */
+    runTeamCreateUnderSeedBarrier<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * §4.2 B.1 — arm the B.1 two-condition latch with the just-created
+     * `taskGroupId`. If the subscription is already established, fire B.1
+     * immediately (the common case where the subscription was up before
+     * `createTaskGroup` returned).
+     */
+    armB1Recovery(taskGroupId: string): void;
+    /**
+     * §4.2 — the subscription-establishment signal (`onSubscribed`). Sets the
+     * `subscriptionReady` latch (firing a pending B.1) and ALWAYS runs B.2
+     * discovery. Fires on the INITIAL connect (`isReconnect=false`, the restart
+     * case B.2 exists for) AND a reconnect (`isReconnect=true`). B.1 and B.2 each
+     * take the refcount barrier (`withRecoveryBarrier`) which is incremented
+     * SYNCHRONOUSLY here (before this returns), so any live TEAM packet processed
+     * after this point buffers until BOTH recovery ops finish seeding.
+     */
+    onSubscriptionReady(isReconnect: boolean): void;
+    /**
+     * §4.2 B.1 — strong-read the just-created group's in-flight tracks and recover
+     * them UNDER the barrier. Capture + CLEAR `pendingB1TaskGroupId` immediately
+     * so a later reconnect's `onSubscribed` does not re-run B.1 for an
+     * already-handled group. Fail-open: a query throw warns + returns (the barrier
+     * still releases + drains via `withRecoveryBarrier`'s `finally`).
+     */
+    private fireB1;
+    /**
+     * §4.2 B.2 — discovery on subscription establishment, with a bounded GSI-lag
+     * retry. Each attempt queries the GSI then IMMEDIATELY recovers that attempt's
+     * rows (NOT accumulate-then-recover — `relaunch` is decided from the lease live
+     * at query time, so recovering each attempt's rows immediately avoids a
+     * near-expiring lease lapsing during backoff). Keeps querying across the
+     * bounded window to catch GSI-lagged groups (does NOT stop on first non-empty).
+     * Idempotent via `seenGateDispatchRunIds`. Retry-skip optimization (§4.2): on a
+     * RECONNECT where no team work ran this session AND the first query is empty,
+     * skip the remaining retries (no GSI lag possible). On the INITIAL connect the
+     * full retry ALWAYS runs (a restarted process has `teamSessionActive`
+     * stale-false yet may have orphaned team work). Fail-open per attempt.
+     */
+    runB2Recovery(isReconnect: boolean): Promise<void>;
+    private runB2RecoveryAttempts;
+    /**
+     * §4.1 — the TWO-PASS recovery core. PASS 1 decrypts + seeds EVERY brief for
+     * all non-terminal tracks (the SEED set, incl. `Pending`) BEFORE any launch, so
+     * the live launch plumbing (bridge → getTeamBrief → registerTeamTaskBrief →
+     * drain), any buffered-dispatch drain, AND a LATER live dispatch of a
+     * capacity-held `Pending` track all read the CORRECT brief — no empty window.
+     * PASS 2 relaunches ONLY the relaunch subset. The ordering BARRIER (§4.3) is
+     * owned by the CALLER (`fireB1` / `runB2Recovery` via `withRecoveryBarrier`),
+     * which holds it across the WHOLE recovery window + drains once at the end —
+     * so this method just seeds + relaunches (it is always invoked under a barrier
+     * that is already down, and may run multiple times within one barrier window).
+     */
+    recoverTeamTracks(rows: TeamTrackRecoveryRow[]): Promise<void>;
+    /**
+     * §4.1 PASS 2 (one row) — validate → recoverLaunchTrack → repair-on-duplicate →
+     * drive the round-0 gate. Honors the corrupt-brief tombstone + the
+     * `seenGateDispatchRunIds` dedup + the #592 provenance guard. Called ONLY from
+     * `recoverTeamTracks` PASS 2 (the recovery dispatch chokepoint); the buffered
+     * live-TrackAssigned drain (§4.3) routes through `consumeClassB` →
+     * `LocalExecutorImpl.launchTrack` (NOT here), where the LE's `isForeignTeamGroup`
+     * gate is the live-path counterpart (Stage-1 r1 HIGH / Stage-2 advisory). Pre: the
+     * brief is already seeded (PASS 1) or legitimately empty.
+     */
+    private launchRecoveredTrack;
+    /**
+     * §4.1 — reconstruct the round-0 `GateDispatchPayload` from a recovery row.
+     * Round-0 is SEAT-LESS (the proposal hasn't arrived, no reviewer seats yet), so
+     * `verificationChecks` / `reviewerSeats` / `finalApprovalSurface` are absent —
+     * matching the live round-0 emit (`start_ports.rs` sets `reviewer_seats: None`).
+     */
+    private reconstructRound0GateDispatch;
+    private handleReviseFeedback;
+    /** The implementor agent the loop spawns (set at start_task). */
+    private activeImplementorAgent;
+    setActiveImplementorAgent(agent: AgentKind): void;
+    /**
+     * #585 #C10M-9 — resolve the active task's request context for `/continue
+     * request` (the entrypoint wires this to the slash route's
+     * `getActiveRequestContext`). Returns `null` when no implementor round is
+     * active (no gate to hand off from). The `gateId`/`roundNumber` come from the
+     * ACTIVE implementor registry (the round currently running); the brief +
+     * source agent come from the loop's active state.
+     */
+    getActiveContinuationRequestContext(): {
+        taskId: string;
+        gateId: string;
+        roundNumber: number;
+        brief: string;
+        sourceAgent: AgentKind;
+    } | null;
+    /**
+     * #585 L-A — mint a fresh `expiresAt = now + TTL` at millisecond precision
+     * (RFC-3339). Fresh per request so a CANCEL→re-request produces a distinct
+     * hash preimage → distinct `packet_hash` → the FRESH-write path re-fires the
+     * prompt (#C10M-12). NEW behavior #585 adds (no production minting site
+     * existed; `expiresAt` is a caller-supplied `PacketWriteInput` field).
+     */
+    private mintExpiresAt;
+    /**
+     * #585 L2 — resolve the text used to classify a quota failure. In TEST mode
+     * ONLY (`NODE_ENV === 'test'`), the force-quota env var (assembled from
+     * fragments below, see the inline comment) injects a synthetic usage-limit
+     * stderr for the named agent so the `continuation-handoff-quota` E2E scenario
+     * is reproducible in CI (the real quota error is not naturally reproducible).
+     * The force-quota literal is asserted ABSENT from the published esbuild bundle
+     * by the `verify-no-test-hooks` build step (§5.5 / dimension-8
+     * prod-unreachability) — hence the fragment-assembled key + the verbatim
+     * literal NEVER appearing in this file. The branch is `NODE_ENV==='test'`-gated
+     * so it is never evaluated in prod regardless.
+     */
+    /**
+     * #585 §5.5 / L2 — the SINGLE source of the force-quota test gate. Returns true
+     * when (a) `NODE_ENV === 'test'` AND (b) the fragment-assembled force-quota env
+     * var names `agent`. The env-var KEY is assembled from fragments so the
+     * force-quota literal NEVER appears verbatim in the published bundle (the
+     * `verify-no-test-hooks` CI grep asserts its absence);
+     * the whole gate is ALSO `NODE_ENV==='test'`-gated so it is never evaluated in
+     * prod. Drives BOTH the synthetic quota stderr (`resolveQuotaClassificationText`)
+     * AND the forced empty-diff born-halt (`runImplementorRound` capture site) — the
+     * two halves that make the `continuation-handoff-quota` E2E reproducible (a real
+     * model will not deterministically exit with NO diff, which the quota fork
+     * requires).
+     */
+    private isForcedQuotaAgent;
+    /**
+     * Test seam — force the ROUND-0 implementor agent (overriding the session
+     * default). `NODE_ENV==='test'`-gated; the env key is fragment-assembled so the
+     * literal never appears in a published bundle (`verify-no-test-hooks` greps for
+     * it). Makes the `codex-implementor-edits` E2E deterministic: a Codex
+     * implementor exercises `codex exec` end-to-end (the substrate-aware sandbox
+     * rewrite) where the session default would otherwise pick Claude. Returns the
+     * forced agent, or null when unset / in prod.
+     */
+    private resolveForcedImplementorAgent;
+    private resolveQuotaClassificationText;
+    /**
+     * #585 §3.5 / §3.6 — the `quota_exhausted` fork. The implementor halted on a
+     * quota error (born-halt or, defensively, a throw). Bound-check the
+     * quota-substitution loop (#C10M-12), discard the shadow (the real tree was
+     * never touched), emit the `continuation_offered` milestone (NOT
+     * `round_failed`, L-B), and fire `writer.write()` with
+     * `blockedReason:'quota_exhausted'` + the dead round's gateId + a fresh ms
+     * `expiresAt` — the server stamps the gate + emits the handoff prompt.
+     */
+    private handleQuotaExhaustedFork;
+    /**
+     * #585 §3.5 / #C10M-3/9/16 — the trigger transport. Builds a
+     * `PacketWriteInput` (fresh ULID `offerId`, the trigger's `blockedReason`,
+     * the round's `gateId`, a fresh ms `expiresAt`) and calls
+     * `ContinuationPacketWriter.write()` DIRECTLY (local CONTINUATION.md + the
+     * already-wired `recordContinuationPacketWritten` mutation → the server
+     * stamps `handoff_pending` + emits the prompt). For the `user_requested`
+     * trigger (`abortActive: true`) it FIRST claims the handoff + aborts the
+     * running implementor (Codex-H1/#C10M-16) so the original implementor is
+     * suppressed. Returns the minted `offerId` (or null on failure).
+     */
+    requestContinuation(input: {
+        taskId: string;
+        gateId: string;
+        sourceAgent: AgentKind;
+        blockedReason: HandoffReason;
+        brief: string;
+        abortActive: boolean;
+        targetAgent?: AgentKind;
+        onOfferMinted?: (offerId: string) => void;
+    }): Promise<{
+        offerId: string;
+    } | null>;
+    /**
+     * #585 #C10M-16 — claim the handoff for the active task: set
+     * `handoffClaimed = true` + abort the running implementor's spawn so the
+     * post-`await handle.done` path suppresses the late capture/submit/surfaceHalt.
+     * Idempotent; a no-op when no implementor is active for the task.
+     */
+    private claimHandoffForActiveTask;
+    /**
+     * #585 §2.3 / #C10M-16 — the `onApplyUserDecision` consumer for the
+     * orchestration shell. Routes a `continuation_switch_accepted` action to
+     * `resumeFromContinuation`, deduped against the local-accept path via
+     * `resumedOffers` keyed on `action.offer_id`. A LOCAL accept already added
+     * its `offer_id` (so its own echo is SUPPRESSED here); a FOREIGN
+     * (mobile-originated) accept drives EXACTLY ONE resume. A `declined` echo
+     * clears the prompt state (handled by the reducer via the SUBMIT path; here
+     * it is a no-op for the resume side). Wired by the shell to the
+     * `AppSyncClient.subscribeToApplyUserDecision` callback.
+     */
+    onApplyUserDecisionEcho(event: {
+        taskId: string;
+        gateId: string;
+        decision: string;
+        action: PostDecisionAction;
+    }): Promise<void>;
+    /**
+     * #585 §3.5 / #C10M-11/13 — resume the task with the user's chosen agent.
+     * The SERVER has ALREADY minted the `nextGateId` row + advanced to
+     * `GatePlanInFlight{nextGateId}` (agy-H1) — the desktop does NOT mint a gate;
+     * it spawns into the server-created gate. Reads the CP-6 `CONTINUATION.md`
+     * (hash + backend-audit verified — refuses a `PacketUnverified` packet, the
+     * pre-spawn fidelity gate), builds the resume brief from the packet's
+     * WORK-CONTEXT fields ONLY (NEVER `packet.targetAgent` — the user's choice is
+     * authoritative, #C10M-13), `setActiveImplementorAgent(targetAgent)`, and
+     * re-enters `runImplementorRound` with the SERVER-supplied `nextGateId`/
+     * `nextRound`. Idempotent on the deterministic `nextGateId` via the
+     * `inFlightImplementorGates`/`submittedOutputGates` double-guard.
+     */
+    resumeFromContinuation(input: {
+        taskId: string;
+        targetAgent: AgentKind;
+        nextGateId: string;
+        nextRound: number;
+    }): Promise<boolean>;
+    /**
+     * #585 #C10M-13 — build the resume brief from the packet's WORK-CONTEXT
+     * fields ONLY. MUST NOT include `packet.targetAgent` or any agent-name
+     * directive (so it can never contradict the user's chosen agent). Pure +
+     * deterministic.
+     */
+    private buildResumeBrief;
+    /**
+     * #585 #C10M-16 — record that a LOCAL accept (typed-digit or `/continue
+     * accept`) drove `resumeFromContinuation` inline, so the `onApplyUserDecision`
+     * own-echo for that SAME offer is suppressed (exactly ONE resume per offer).
+     * Called by the local-accept path BEFORE driving the resume.
+     */
+    markOfferResumed(offerId: string): void;
+    /** @internal — test introspection for the active-implementor registry. */
+    get _activeImplementorForTests(): ReadonlyMap<string, {
+        gateId: string;
+        handoffClaimed: boolean;
+    }>;
+    /** @internal — test introspection for the resume dedupe set. */
+    get _resumedOffersForTests(): ReadonlySet<string>;
+    /**
+     * CP-1.f revise-context fix (dogfood task 2ac68708, 2026-06-11) — record a
+     * BINDING user-requested change for a task. Called from `handleReviseFeedback`
+     * when the `REVISE_FEEDBACK` payload carries the engine's synthetic
+     * `seat_id === 'user'` finding (a Reject-with-notes, desktop OR mobile); its
+     * `findings` text becomes a binding requirement re-stated in EVERY subsequent
+     * revise round so no round can silently drop an earlier user requirement.
+     *
+     * Empty / whitespace-only notes are ignored (a defensive guard — the engine
+     * already fails closed on empty notes upstream). Idempotent against an exact
+     * consecutive repeat (a re-delivered packet must not duplicate the binding
+     * requirement). Public so tests can drive the capture directly.
+     */
+    recordUserNote(taskId: string, note: string): void;
+    /**
+     * CP-1.f revise-context fix (dogfood task 2ac68708, 2026-06-11) — build the
+     * CUMULATIVE round-N+1 revise brief from the original task brief
+     * (`activeBrief`, set at start_task), every BINDING user note recorded for
+     * this task, and the current round's reviewer findings. The SAME brief is
+     * used as the implementor stdin AND the execute-first `task_brief` rendered
+     * into the reviewer prompts, so reviewers and the implementor share one
+     * source of truth (the REAL requested task) and no round drops an earlier
+     * user requirement.
+     */
+    private buildReviseBrief;
+    /** @internal — test introspection. */
+    get _runningSeatsForTests(): ReadonlySet<string>;
+    /** @internal — test introspection. */
+    get _submittedSeatsForTests(): ReadonlySet<string>;
+    /** @internal — test seam to set the active task without start_task. */
+    _setActiveTaskForTests(taskId: string, brief?: string): void;
+    /** @internal — read a task's accumulated binding user notes. */
+    _userNotesForTests(taskId: string): readonly string[];
+    /** @internal — read the consumed REVISE_FEEDBACK dedup ids (Stage-2 r1 guard). */
+    get _seenReviseFeedbackIdsForTests(): ReadonlySet<string>;
+    /** @internal — read the live in-memory shadow handle for a task (or undefined). */
+    _getShadowForTests(taskId: string): WorkspaceShadow | undefined;
+    /** @internal — re-arm a (recovered) shadow handle so a double-fire hits the marker short-circuit. */
+    _armShadowForTests(taskId: string, shadow: WorkspaceShadow): void;
+    /**
+     * @internal — drop a task's shadow-map entry WITHOUT touching its dir/marker.
+     * Reproduces the transient UNMAPPED window inside `replaceShadowForRound0`:
+     * the map entry is `delete`d before the (slow) stale teardown awaits and before
+     * the replacement shadow B is created, so `discardShadow` can observe
+     * `mapped === undefined`.
+     */
+    _unmapShadowForTests(taskId: string): void;
+    /**
+     * @internal — NEGATIVE-CONTROL seams (restart-race mutex, 2026-06-11 Codex r2):
+     * invoke the UNLOCKED `*Locked` bodies directly, BYPASSING `runExclusiveShadowOp`.
+     * Used ONLY by the mutex regression test to prove that without serialization a
+     * matched discard overlapping a restart replacement destroys the #PR-4 marker.
+     * Production code MUST always go through the locked public wrappers.
+     */
+    _discardShadowUnlockedForTests(taskId: string, expected?: WorkspaceShadow): Promise<void>;
+    _replaceShadowForRound0UnlockedForTests(taskId: string): Promise<void>;
+    _ensureShadowUnlockedForTests(taskId: string): Promise<WorkspaceShadow>;
+}
+export { reviewerAgentToLeAgent };