@quantiya/codevibe-core 2.0.1 → 2.0.2

package/dist/orchestration-shell/index.d.ts

@@ -1,12 +1,27 @@
 import { AppSyncClient } from '../appsync';
 import { Session } from '../types';
 import { OrchestrationStore } from './store';
+import type { ImageAttachment } from './types';
+import { type GroupDecisionSubmitDeps } from './gate-decision-submit';
+import { type ContinuationCliResult, type ContinuationCliDeps } from './slash-routes/continuation';
+import { loadReviewerWizardData } from './slash-routes/reviewers';
 import { createShellEventEmitter } from './emit-shell-event';
+import { type RunAuditBrowserResult } from './audit-runner';
 import { Tier } from './types';
+import type { PendingClarification } from './types';
+import { type GatePromptEnvelope, type DecryptedReviewSummaryInput } from './gate-prompts';
+import type { Event } from '../types/events';
 import { type StructuralSummaryGenerator } from '../structural-summary';
 import type { PlannerAdapter } from '../planner/adapter';
 import type { PlannerCacheLayer } from '../planner/cache';
 import type { PlannerInput, PlannerDecision as PlannerDecisionRuntime } from '../planner/types';
+import type { LocalGemmaAdvisoryRunner } from '../planner/local-advisory';
+import type { LocalExecutor } from '../local-executor';
+import type { WorkItemInput, DisjointnessRejection, RevertManifestStore } from '../local-executor';
+import type { QuorumLoop } from './quorum-loop';
+import { ensureFreshContextStore } from './context-store';
+import type { EnsureFreshResult } from './context-store';
+import { type TaskProgressEvent } from './task-progress';
 export interface RunOrchestrationShellArgs {
     /** Authenticated AppSync client (caller is responsible for `authenticateWithStoredTokens`). */
     appsyncClient: AppSyncClient;
@@ -33,22 +48,478 @@ export interface RunOrchestrationShellArgs {
      * finally-block cleanup).
      */
     plannerCache?: PlannerCacheLayer;
+    /**
+     * Local Gemma planner M1/M2 — disables automatic structural-summary refreshes
+     * at shell startup and before natural-language classification. The local
+     * planner path must not scan or summarize the repository before route-source
+     * safety and an accepted local route exist. Accepted local routes such as
+     * `familiarize` may still run their own route-scoped refresh.
+     */
+    disableStructuralContextRefresh?: boolean;
+    /**
+     * Local Gemma planner migration state. `hosted` keeps the legacy backend
+     * planner semantics. `local_gemma_qat` means natural-language decisions came
+     * from the local runtime and need shell-owned M1 safety/milestone gates.
+     * `local_unavailable` means the user opted into local-model orchestration but
+     * the verified runtime is not usable; no hosted fallback is allowed.
+     */
+    plannerRuntimeKind?: 'hosted' | 'local_gemma_qat' | 'local_unavailable';
+    /**
+     * TUI redesign (2026-06-29) — display label for the local planner model
+     * (e.g. `gemma4`), surfaced in the status-bar planner badge. Set by `cli.ts`
+     * from the resolved local-model config; absent on hosted/legacy callers.
+     */
+    plannerRuntimeLabel?: string;
+    /**
+     * TUI redesign (2026-06-29) — the PLAINTEXT working directory for the status
+     * bar (process.cwd() captured at shell entry). Threaded explicitly because
+     * `session.projectPath` is AES-GCM-encrypted at rest in E2E sessions and is
+     * never decrypted (Stage-1 HIGH). Absent → the component falls back to
+     * process.cwd().
+     */
+    cwd?: string;
+    /**
+     * Local Gemma M3 advisory runtime. This is intentionally separate from the
+     * planner adapter interface: classification remains schema-only, while
+     * familiarization uses a bounded read-only advisory prompt after route
+     * safety, local runtime eligibility, and repository context refresh pass.
+     */
+    localAdvisoryRunner?: LocalGemmaAdvisoryRunner;
+    /**
+     * CP-12 W3 §3.5 — the team-mode Local Executor. Present ONLY for an
+     * Agent-Teams session: `cli.ts` constructs ONE per session (honoring the
+     * CP-1.a singleton-per-sessionId guard) and threads it here ALONG WITH its
+     * team deps wired. When present, `runOrchestrationShell`:
+     *   (a) subscribes `subscribeToClassBPackets(session.userId)` →
+     *       `localExecutor.consumeClassB(packet)` (item 2) + teardown cleanup;
+     *   (b) enables the `/team` slash command (item 5).
+     * A single-track/Companion/stub session OMITS this — no Class B
+     * subscription, no team mode, no status node (byte-identical behavior).
+     */
+    localExecutor?: LocalExecutor;
+    /**
+     * CP-12 W3 §3.5 — store-tap installed by `cli.ts` so the team-mode LE's
+     * per-track shell events (W2.b `emitTrackProgress` NOTIFICATIONs carrying
+     * `metadata.track_index` + `task_id`, and the `task_group_halted`
+     * NOTIFICATION) are routed into THIS shell's store. `cli.ts` builds the LE
+     * with an emitter that calls `teamShellEventTap.fn(args)` BEFORE the real
+     * emit chokepoint; `runOrchestrationShell` installs the store-dispatching
+     * `fn` at startup. Omitted for non-team sessions.
+     */
+    teamShellEventTap?: {
+        fn: (args: TeamTapEvent) => void;
+    };
+    /**
+     * CP-1.f §3.C.20 — the desktop reviewer-quorum loop driver. Present for a
+     * real Max session (constructed in `cli.ts` alongside the team LE). When
+     * present, `runOrchestrationShell`:
+     *   (a) wires its `classBConsumerDeps` (real Ed25519 verify + GATE_DISPATCH
+     *       gateDispatch + REVIEWER_DISPATCH spawnReviewers + REVISE_FEEDBACK
+     *       runReviseRound) into the LE consumer;
+     *   (b) runs `recoverInReviewAssignments` on Class B (re)connect (§3.C.21b);
+     *   (c) drives `startTask` on a `start_task` planner decision (§3.C.20); the
+     *       round-0 implementor spawn then fires from the GATE_DISPATCH consumer.
+     *       A non-Max / stub / Companion session OMITS this.
+     */
+    quorumLoop?: QuorumLoop;
+    /**
+     * CP-1.f live progress surfacing — the desktop-local progress tap holder
+     * (`cli.ts` builds it alongside the loop). When present,
+     * `runOrchestrationShell` installs the store-dispatching `fn` so the loop's
+     * `onProgress` events render as an ephemeral spinner line + persisted
+     * milestones, and emits `waiting_user` when a gate prompt arrives. A non-loop
+     * / Companion / stub session OMITS this — no spinner line ever renders.
+     */
+    progressTap?: {
+        fn: (event: TaskProgressEvent) => void;
+    };
+    /**
+     * Audited-path fix (Fix 1) — the desktop-local PolicyRejection tap holder
+     * (`cli.ts` builds it alongside the loop). When present,
+     * `runOrchestrationShell` installs the store-dispatching `fn` so a hosted-side
+     * PolicyRejection becomes a classified `SHELL_ADVISORY` in the conversation
+     * (the existing mobile NOTIFICATION path is unchanged). The shadow-discard side
+     * is handled by `cli.ts` (which holds the QuorumLoop reference). A non-loop /
+     * Companion / stub session OMITS this.
+     */
+    policyRejectionTap?: {
+        fn: (info: {
+            detail: string;
+            category: string;
+            recommendedRecovery: string;
+        }) => void;
+    };
+    /**
+     * PHASE-589/469 W3.2 — the two-phase group-escalation decision deps, built in
+     * `cli.ts` alongside the team LE (the keychain/E2E/signing-heavy assembly:
+     * `claimGroupDecision` SDK client, the `revertGroup` runner over the durable
+     * manifest, `markAccepted`, the per-track render flip via
+     * `driveGroupDecisionConvergence`, and the `reissueTeam` callback). Threaded
+     * into the SHARED `gateDecisionDeps.groupDecision` so a synthesized
+     * `task_group_halted` 5-option prompt resolves through `submitGroupDecision`
+     * on BOTH the TTY + non-TTY surfaces. A non-team session OMITS this — no group
+     * prompt can ever appear, so it is never consulted.
+     *
+     * The `store` is OMITTED here — it is created INSIDE `runOrchestrationShell`,
+     * which completes the deps with its own store (mirroring how `gateDecisionDeps`
+     * is assembled). `cli.ts` supplies only the keychain/E2E/signing-heavy half
+     * (`claimClient` / `revertGroup` / `markAccepted` / `driveGroupConvergence` /
+     * `reissueTeam` / `getSessionKey`).
+     */
+    groupDecisionDeps?: Omit<GroupDecisionSubmitDeps, 'store'>;
+    /**
+     * PHASE-589/469 W3.1 (C4) — the startup reconcile-before-GC over the durable
+     * revert manifests (LOCK #589-I). Built in `cli.ts` over the same
+     * `RevertManifestStore` + `revertGroup` runner the group decision uses, plus a
+     * `probeEngineState` that asks the engine for each group's terminal view. Run
+     * ONCE at team-wiring startup, BEFORE the live Class B loop consumes packets,
+     * so a backend lease-timeout `Halted` (driven while the desktop was offline)
+     * reverts the applied tree before its manifest could be GC'd. A non-team
+     * session OMITS this. NEVER throws.
+     */
+    reconcileRevertManifests?: () => Promise<void>;
+}
+/**
+ * CP-12 W3 — the minimal shape `runOrchestrationShell` inspects when routing
+ * the team-mode LE's emitted shell events into the store. Structural subset of
+ * the LE's `EmitShellEventFn` arg (we only read `metadata`).
+ */
+export interface TeamTapEvent {
+    metadata?: Record<string, unknown>;
 }
 export { processMarkers, withRoleMarker } from './process-markers';
 export { emitShellEvent, createShellEventEmitter, type ShellEventEmit, type NewEventTypeKind, } from './emit-shell-event';
 export { pickMode, TierError, type ParsedModeArgs, type ModeSelectionDeps, } from './mode-selection';
 export { readStickyPreference, writeStickyPreference, stickyPreferenceFilePath, } from './sticky-preference';
 export { getCohortFlag, cohortFlagFilePath } from './cohort-flag';
+export { deriveWorkspaceId, deriveRepoId, normalizeRepoRelativePath, contextStoreDir, loadContextStore, writeContextStore, computeSummaryInputHash, probeFreshness, ensureFreshContextStore, mintContextRef, resolveContextRef, sliceSummary, type ContextRef, type SliceSelector, type SliceSelectorEntry, type ContextStoreMetadata, type ContextStoreEntry, type ResolvedContextSlice, type FreshnessProbeResult, type EnsureFreshResult, type EnsureFreshDeps, } from './context-store';
 export { routeSlashCommand, applySlashOutput, type SlashOutput, type ShellAction, } from './slash-router';
+export { buildAuditBrowserModel, routeAuditEntry, auditKindLabel, auditKindCopy, renderAuditBrowserText, renderAuditEntryText, ENTRY_DETAILS_UNAVAILABLE, NO_AUDIT_ENTRIES, AUDIT_LOG_TOO_LARGE, AUDIT_LOG_TITLE, AUDIT_BROWSER_MAX_HEADLINE, WIRE_PUBLIC_PLAINTEXT_KINDS, type AuditBrowserModel, type AuditEntryModel, type AuditReviewerVerdictModel, type AuditTaskAuthorizedModel, type DecryptContentFn, } from './audit-browser';
+export { runAuditBrowser, renderAuditResultText, AUDIT_BROWSER_UPGRADE_HINT, type RunAuditBrowserResult, type RunAuditBrowserDeps, } from './audit-runner';
+export { AuditLogPanel } from './components/AuditLogPanel';
 export { reducer } from './reducer';
 export { createOrchestrationStore, type OrchestrationStore } from './store';
-export type { Mode, Tier, PlannerDecision, AgentKind, PlannerHealthState, RunningTaskState, ReviewerSeatState, GateState, ExecutionEventEntry, RefusalEventEntry, BypassEventEntry, MobileEventEntry, EventStreamEntry, ConversationEntry, QueuedTask, PendingClarification, OrchestrationState, OrchestrationAction, LastModeFile, } from './types';
+export type { Mode, Tier, PlannerDecision, AgentKind, PlannerHealthState, RunningTaskState, ReviewerSeatState, GateState, ExecutionEventEntry, RefusalEventEntry, BypassEventEntry, MobileEventEntry, EventStreamEntry, ConversationEntry, QueuedTask, PendingClarification, OrchestrationState, OrchestrationAction, LastModeFile, TeamState, TeamTrackEntry, TeamTrackState, TeamMergeGateStatus, LiveProgress, } from './types';
+export { formatElapsed, isSpinnerPhase, renderProgressLine, type TaskProgressEvent, type OnProgress, } from './task-progress';
+export { runDeclaredTestSurfaces, DECLARED_TEST_TIMEOUT_MS, type DeclaredTestResult, type DeclaredTestReason, type RunDeclaredTestSurfacesArgs, } from './declared-test-runner';
 /**
  * §5 lines 336-365 LOCK + §16 LOCK #14. Single entrypoint that wires
  * the store + emit chokepoint + slash router and either mounts the
  * Ink TUI (TTY) or falls back to line-log (non-TTY).
  */
 export declare function runOrchestrationShell(args: RunOrchestrationShellArgs): Promise<void>;
+/**
+ * PHASE-CP-1-F.1 Part B (LOCK L7) — the bound on the async per-round summary
+ * fetch fired AFTER a final-approval prompt is queued. The decision never
+ * blocks on this; if the fetch doesn't resolve within the bound, the prompt
+ * simply renders with no review panel (fail-open).
+ */
+export declare const TASK_REVIEW_SUMMARY_FETCH_TIMEOUT_MS = 5000;
+/**
+ * Plaintext-first dispatcher per #C8M-7 (Stage 1 R1 M6 lock):
+ *   1. If `event.metadata` is an object, use it directly. Otherwise try
+ *      `JSON.parse` (AWSJSON delivery path is typically already-parsed,
+ *      but accept both).
+ *   2. If `metadata.prompt_kind` is one of the two orchestration
+ *      constants, call `extractGatePromptEnvelope`. If it returns an
+ *      envelope, dispatch `GATE_PROMPT_RECEIVED`; if it returns null
+ *      (defensive validation tripped), dispatch a malformed-prompt
+ *      `advisory` per #C8M-1 via `SHELL_ADVISORY`.
+ *   3. Anything else (other prompt_kinds, USER_PROMPT, etc.) returns
+ *      without further action — see "Stage 2 r1 Codex HIGH-2 scope
+ *      clarification" below for why this is correct.
+ *
+ * Plaintext-first is safe because orchestration prompts are wire-public
+ * per CP-0 §2.F.12 and the AppSync subscription is Cognito-auth-gated
+ * (an attacker capable of injecting plaintext fakes already has
+ * `createEvent` rights and can do arbitrary harm).
+ *
+ * ──────────────────────────────────────────────────────────────────────
+ * Stage 2 r1 Codex HIGH-2 scope clarification (Hendry-approved 2026-05-19):
+ *
+ * The locked design #C8M-7 dispatcher contract says "Otherwise (any other
+ * prompt_kind, OR plaintext parse failed, OR metadata wrapped in
+ * `{ encrypted: "..." }`): route to the existing decrypt path
+ * (`cryptoService.decryptMetadata(...)`) and dispatch as
+ * `kind:'subagent-event'`/`kind:'mobile-event-replay'` per the prior
+ * `ConversationEntry` variants."
+ *
+ * [RESOLVED — CP-8 full §A.6 (#472)] CP-8 min deferred the non-gate
+ * INTERACTIVE_PROMPT decrypt path because the shell had no session-key
+ * plumbing at the dispatcher. CP-8 full §A.6 closes it: the dispatcher now
+ * accepts a `sessionKeyResolver` (`keychainManager.getSessionKey`, the same
+ * path the gate-prompt notes submit uses) and routes the agent's OWN
+ * AskUserQuestion prompts (E2E-encrypted `{ encrypted: "..." }` metadata,
+ * UNLIKE the plaintext server gate metadata) through
+ * `cryptoService.decryptMetadata` → a `MobileEventEntry` dispatched via
+ * `EVENT_RECEIVED` (which the reducer renders as a `subagent-event`
+ * ConversationEntry). The gate path (plaintext) is UNCHANGED — only the
+ * non-gate encrypted path is added.
+ *
+ * Fail-closed: when the session key is unavailable OR `decryptMetadata`
+ * throws, the dispatcher logs + pushes a `SHELL_ADVISORY` (mirroring the
+ * malformed-gate advisory below) — it NEVER crashes and NEVER renders
+ * ciphertext.
+ * ──────────────────────────────────────────────────────────────────────
+ */
+/**
+ * PHASE-CP-1-F.1 Part B (LOCK L7) — the bounded review-summary fetcher the
+ * dispatcher fires AFTER the base final-approval prompt is queued. Returns the
+ * DECRYPTED summary on success, or `null`/throws on any failure (the
+ * dispatcher fails OPEN — no panel, never a blocked decision). Injected so the
+ * dispatcher stays decoupled from the SDK + session-key plumbing (and is
+ * unit-testable with a mock).
+ */
+export type ReviewSummaryFetcher = (taskId: string, gateId: string, sessionId: string) => Promise<DecryptedReviewSummaryInput | null>;
+export declare function handleSubscribedEvent(event: Event, store: OrchestrationStore, sessionKeyResolver?: (sessionId: string) => Promise<string | null>, reviewSummaryFetcher?: ReviewSummaryFetcher, maybeAutoContinue?: (envelope: GatePromptEnvelope) => boolean): void;
+/**
+ * Route ONE team-mode LE shell event into the store's minimal `team` state.
+ * The W2.b `emitTrackProgress` emits a NOTIFICATION carrying
+ * `metadata.track_index` + `task_id` (+ `source: 'track_progress'`); the
+ * `haltTaskGroup` path emits a NOTIFICATION with `source: 'task_group_halted'`.
+ * We discriminate on `metadata.source` so non-team NOTIFICATIONs (planner
+ * health, late-arrival audits) are IGNORED — they have no team `source` tag.
+ *
+ * Pure mapping → store dispatch; no rich rendering (that is [DEFERRED → CP-8
+ * #469]). Called from the `teamShellEventTap.fn` installed at startup.
+ */
+export declare function routeTeamShellEventToStore(store: OrchestrationStore, evt: TeamTapEvent): void;
+/**
+ * PHASE-590 §3.D step 0 / §4.4 — compose the LOSSLESS implementation brief.
+ *
+ * Factored from the existing `start_task` brief-compose logic (formerly inline
+ * at the routing branch): when THIS turn answered a live clarification
+ * (`pending` non-null + answered), rebuild a unified brief = the original
+ * request + the answered rounds; otherwise the brief is just the latest turn.
+ *
+ * Reused by THREE call sites with IDENTICAL semantics (no behavior change at the
+ * `start_task` site): the `start_task` branch, the `team_decompose` decomposer
+ * input + single-task fallback, AND the `groupIdempotencyKey` hash. Never use
+ * the raw latest turn — after a clarification loop it drops the original request
+ * and collides on common answers like "yes".
+ *
+ * `pending` is the PRE-`PLANNER_DECISION` snapshot (the live store may have
+ * cleared `pendingClarification` on the dispatch); the caller passes whether
+ * THIS turn answered it (`answered`) so a stale/in-flight pending is treated as
+ * a fresh prompt (the brief is the latest turn).
+ */
+export declare function composeImplementationBrief(pending: PendingClarification | null, latestTurn: string, answered: boolean, options?: {
+    priorWorkflowHandoffTurns?: string[];
+    priorBrainstormTurns?: string[];
+    attachments?: ImageAttachment[];
+    attachmentPaths?: string[];
+}): string;
+export declare function composeTeamTrackBrief(trackDescription: string, sourceBrief: string): string;
+/**
+ * PHASE-590 §3.D / §3.E / §4.4 — the STRUCTURED outcome of `launchTeamFromWorkItems`.
+ *
+ * The manual `/team` `handleTeamCommand` collapses BOTH a server `accepted:false`
+ * (disjointness rejection — no group exists) AND any thrown/transport error to
+ * `null`. The PLANNER auto-launch path MUST distinguish them, because the safety
+ * of auto-falling-back differs (a disjointness reject is safe to fall back; an
+ * unknown create error MAY have created the group → falling back would double-run).
+ */
+export type LaunchTeamOutcome = {
+    kind: 'accepted';
+    taskGroupId: string;
+} | {
+    kind: 'disjointness_rejected';
+    rejection: DisjointnessRejection;
+} | {
+    kind: 'unknown_create_error';
+    err: unknown;
+};
+/**
+ * PHASE-590 §3.D / §4.4 — the SHARED `/team` launch block, factored WHOLE from
+ * the live `/team` dispatch so both the manual command AND the planner path
+ * reuse it verbatim: `markTeamSessionActive` → brief-encrypt loop →
+ * `runTeamCreateUnderSeedBarrier(createTaskGroup)` → `setTeamBriefs` +
+ * `armB1Recovery`. The #593 seed-barrier ordering is load-bearing (a round-0
+ * GateDispatch can race the create response).
+ *
+ * Unlike `handleTeamCommand`, this returns a STRUCTURED `LaunchTeamOutcome` union
+ * so the caller distinguishes accepted / disjointness-rejected / unknown-create-
+ * error and only auto-falls-back on the SAFE classes (§3.E).
+ *
+ * `workItems` MUST already be the wire shape (no `description`); briefs are
+ * passed separately in `briefsByTrackIndex` and E2E-encrypted here under the
+ * team session key (the PLAINTEXT brief NEVER goes on the wire).
+ */
+export declare function launchTeamFromWorkItems(deps: {
+    store: OrchestrationStore;
+    appsyncClient: AppSyncClient;
+    quorumLoop?: QuorumLoop;
+    sessionId: string;
+    workItems: WorkItemInput[];
+    briefsByTrackIndex: Map<number, string>;
+    groupIdempotencyKey: string;
+    /**
+     * PHASE-589/469 W3.2 RESIDUAL 1 — the durable store the ORIGINAL launch spec is
+     * retained onto (keyed by the created `taskGroupId`), so a later `REJECT_RESTART`
+     * can re-dispatch the WHOLE team from it (the engine retains nothing). ABSENT
+     * (single-impl / tests / non-team) → no retention (a restart degrades to the
+     * user re-running `/team`, the design-accepted fallback). Best-effort: a
+     * retention error NEVER blocks the launch (mirrors the brief-encrypt degrade).
+     */
+    durableStore?: RevertManifestStore;
+    /**
+     * IMAGE-ATTACHMENT-DESIGN.md §5 — GROUP-wide image attachments. Armed on the
+     * loop (`setTeamAttachments`) before any TrackAssigned so each track's round-0
+     * spawn copies them, AND retained in the durable launch spec so a REJECT_RESTART
+     * reissue re-copies from `sourcePath`. Absent/empty on non-image launches.
+     */
+    attachments?: ImageAttachment[];
+    /**
+     * §13 Option-2 — the ordered-with-DUPLICATES resolved carried-path list aligned with
+     * the `[Image #N]` chip numbers in the per-track briefs, so the number-based chip
+     * rewrite resolves each chip to the right ref. Retained for REJECT_RESTART reissue.
+     */
+    attachmentPaths?: string[];
+}): Promise<LaunchTeamOutcome>;
+/**
+ * PHASE-589/469 W3.2 RESIDUAL 1 — re-dispatch the WHOLE team for a
+ * `REJECT_RESTART` decision, from the desktop's OWN retained original `/team`
+ * launch spec (the engine retains nothing). Reads the retained
+ * `{ workItems, briefs }` off the durable store (persisted at the original launch,
+ * survives a restart), then drives the SAME validated launch path
+ * `launchTeamFromWorkItems` — exactly as if the user re-ran the original `/team`
+ * (same brief-encrypt + seed-barrier + createTaskGroup; disjointness re-validated
+ * server-side). A FRESH per-launch idempotency key (timestamp) mints a NEW group;
+ * the new group's spec is retained durably too (so a restart of the restart still
+ * works).
+ *
+ * THROWS when no retained spec exists OR the re-launch did not produce a fresh
+ * group — `submitGroupDecision` catches the throw and surfaces the design-accepted
+ * "re-run /team" advisory (the single source of that user message).
+ */
+export declare function reissueTeamFromRetainedSpec(deps: {
+    store: OrchestrationStore;
+    appsyncClient: AppSyncClient;
+    quorumLoop?: QuorumLoop;
+    sessionId: string;
+    durableStore: RevertManifestStore;
+}, taskGroupId: string): Promise<void>;
+/**
+ * PHASE-590 §3.D — the `team_decompose` routing path. Runs the local decomposer,
+ * shape-checks (the schema is applied inside the decomposer parse) +
+ * availability-validates agents, computes the deterministic per-turn idempotency
+ * key, and auto-launches via `launchTeamFromWorkItems` — distinguishing the
+ * structured outcome union and only auto-falling-back on SAFE classes. Any
+ * irreparable decomposition (no-decompose / parse-fail / empty / no-agent /
+ * pass-error) → synthesized single `start_task`.
+ */
+export declare function routeTeamDecompose(deps: {
+    store: OrchestrationStore;
+    appsyncClient: AppSyncClient;
+    quorumLoop: QuorumLoop;
+    localExecutor: LocalExecutor;
+    sessionId: string;
+    rationale: string;
+    composedBrief: string;
+    /** IMAGE-ATTACHMENT-DESIGN.md §5/§7.5 — group attachments; the decomposer brief is text-only, tracks get the images. */
+    attachments?: ImageAttachment[];
+    /** §13 Option-2 — ordered-with-dups carried paths for the number-based chip rewrite (decomposer briefs are chip-free, so usually unused; threaded for the single-fallback + robustness). */
+    attachmentPaths?: string[];
+    /**
+     * The brief for a team→single FALLBACK (Stage-2 agy MED): carries the in-worktree
+     * REL-REFS (not the decomposer's text-only marker). Defaults to `composedBrief`.
+     */
+    singleFallbackBrief?: string;
+    /** Stage-2 R3 HIGH — the loop's durable store, so the live launch persists the retained spec + attachments. */
+    durableStore?: RevertManifestStore;
+}): Promise<void>;
+/**
+ * CP-4 §4.1 (#600) — `familiarize` desktop route: the context-priming task.
+ *
+ * "read the codebase to get familiar" used to mis-route to
+ * `summarize_current_status` (the deterministic workflow-state answerer) because
+ * the 6-action taxonomy had no home for "read the repo to build context". The
+ * planner-proxy now emits the 7th `familiarize` action; this route is its
+ * desktop handler (placed beside `routeTeamDecompose`, the precedent for a
+ * desktop-intercepted action that never reaches the engine).
+ *
+ * Behavior (v1 — the LOAD-BEARING #600 fix):
+ *  1. advisory "Reading the codebase to get familiar…".
+ *  2. write-or-reuse the CP-4 §4.2 context store via `refreshStructuralSummaryIntoStore`
+ *     (the SINGLE refresh entry point — Codex r1 M1). Because the SAME function
+ *     runs in the pre-classify step immediately before this route is reached,
+ *     this call is a CACHE HIT on the unchanged tree — it renders from the
+ *     already-refreshed store and DOES NOT re-walk. (Pre-unify, this route ran a
+ *     SECOND `runStructuralSummarySessionStart` walk on top of pre-classify's,
+ *     which itself walked because session-start never seeded the store — three
+ *     walks for one familiarize. Now: at most one walk, gated by the probe.)
+ *  3. surface the deterministic structural-summary preview as the answer (the
+ *     "I'm now familiar with X repos / Y files" overview). This is the
+ *     ALWAYS-AVAILABLE floor (§4.1 fallback) — it depends on no local agent and
+ *     no planner availability.
+ *
+ * SCOPE NOTE (separable follow-ons, NOT required for #600 to be fixed):
+ *  - The §4.1 happy-path local-AGENT prose render (a read-only `spawnImplementor`
+ *    plan-mode pass for a richer overview) is the quality UPGRADE; the design
+ *    makes it explicitly best-effort with this deterministic preview as the
+ *    floor. Not built here.
+ *
+ * Best-effort: a structural-summary failure is recorded as STRUCTURAL_SUMMARY_FAILED
+ * by the refresh; the preview renderer surfaces that failure text, so the user
+ * always gets *some* answer and the route never throws.
+ */
+export declare function routeFamiliarize(deps: {
+    store: OrchestrationStore;
+    args: RunOrchestrationShellArgs;
+    emitShellEventBound: ReturnType<typeof createShellEventEmitter>;
+    generator: StructuralSummaryGenerator;
+    /**
+     * Test seam — the SINGLE refresh entry point. Defaults to
+     * `refreshStructuralSummaryIntoStore` (probe → recompute-if-stale → persist →
+     * mirror into the orchestration store). The probe makes this a no-op walk when
+     * the store is already fresh (the unify — Codex r1 M1).
+     */
+    refreshFn?: typeof refreshStructuralSummaryIntoStore;
+    /** Test seam — forwarded to the refresh (the pre-classify context-store seam). */
+    ensureFreshContextStoreFn?: typeof ensureFreshContextStore;
+    /** Current user turn, used only for the local familiarization advisory prompt. */
+    userPrompt?: string;
+}): Promise<void>;
+export declare function routeBrainstorm(deps: {
+    store: OrchestrationStore;
+    args: RunOrchestrationShellArgs;
+    emitShellEventBound: ReturnType<typeof createShellEventEmitter>;
+    generator: StructuralSummaryGenerator;
+    refreshFn?: typeof refreshStructuralSummaryIntoStore;
+    ensureFreshContextStoreFn?: typeof ensureFreshContextStore;
+    userPrompt: string;
+    needsRepositoryContext?: boolean;
+    priorTurns?: string[];
+    /** RAW base64 images (IMAGE-ATTACHMENT-DESIGN.md §6) — Ollama-runtime only; text-mode. */
+    images?: string[];
+}): Promise<void>;
+/**
+ * The MULTIMODAL image answerer for `advisory_response` + ≥1 attached image
+ * (IMAGE-ATTACHMENT-DESIGN.md §6 Role B). "Describe this screenshot / read this
+ * diagram / what does this error say" is normally answered inline by the
+ * classifier's `advisory_summary` — but that path is blind to the image. When an
+ * image is attached, the reducer's inline render is suppressed (strip
+ * summary+clarifying_question+rationale, §6/rev-13) and THIS produces the sole
+ * answer: text-mode `generateAdvisory` with the RAW base64 `images[]` to the LOCAL
+ * Ollama model, image framed as untrusted data, output `sanitizeForTerminal`-scrubbed.
+ * 100% on-device. `browse`/`familiarize` are excluded (their answer is grounded on
+ * other context). All-images-failed → the caller passes an empty `images` and we
+ * proceed text-only.
+ */
+export declare function routeAdvisory(deps: {
+    store: OrchestrationStore;
+    args: RunOrchestrationShellArgs;
+    userPrompt: string;
+    images: string[];
+}): Promise<void>;
+export declare function parseTeamWorkItems(rawArg: string): {
+    ok: true;
+    workItems: WorkItemInput[];
+    briefsByTrackIndex: Map<number, string>;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * Higher-level entrypoint used by the `cli.ts` glue. CP-1.a ships the
  * basic argv parse — full plumbing (session resume, AppSync client
@@ -78,6 +549,13 @@ interface StructuralSummaryRunDeps {
  */
 export interface HandleShellUserInputDeps extends StructuralSummaryRunDeps {
     text: string;
+    /**
+     * IMAGE-ATTACHMENT-DESIGN.md §13 (Option 2) — resolved image path(s) carried
+     * out-of-band from the InputBar's `[Image #N]` chips. When present, the ingest
+     * builds attachments from THESE (the `text` holds chip labels, not raw paths),
+     * and the `[Image #N]` labels are stripped from the classify prompt.
+     */
+    images?: string[];
     /** Test seam — defaults to the real `addBodyPath`. */
     addBodyPathFn?: (path: string, tier: Tier) => Promise<unknown>;
     /** Test seam — defaults to the real `regenerateStructuralSummary`. */
@@ -89,6 +567,44 @@ export interface HandleShellUserInputDeps extends StructuralSummaryRunDeps {
      * without spinning up the BackendPlannerClient.
      */
     classifyFn?: (input: PlannerInput) => Promise<PlannerDecisionRuntime>;
+    /**
+     * CP-6 Stage 2 R1 H-2 fix — Test seam for the async
+     * `/continuation status/show/verify` dispatch. Defaults to building
+     * a `ContinuationPacketReader` over `args.appsyncClient` and calling
+     * `runContinuationCli`. Tests inject a stub to drive the rewrite of
+     * the PENDING placeholder without spinning up real reader I/O.
+     */
+    runContinuationCliFn?: (args: string[]) => Promise<ContinuationCliResult>;
+    /**
+     * CP-8 Slice C (#570) — Test seam for the async `/audit <task-id>` dispatch.
+     * Defaults to `runAuditBrowser` over `args.appsyncClient` + `args.tier` +
+     * `args.session.sessionId`. Tests inject a stub to drive the PENDING-marker
+     * rewrite without live fetch / decrypt.
+     */
+    runAuditBrowserFn?: (taskId: string) => Promise<RunAuditBrowserResult>;
+    /**
+     * CP-4 §4.2 — Test seam for the pre-classify context-store refresh. Defaults
+     * to the real `ensureFreshContextStore` (probe → recompute-if-stale → persist
+     * the store → return the fresh digest). Tests inject a stub to drive the
+     * `structuralSummaryDigest` + `ask_user`-on-refresh-failure paths without
+     * touching the filesystem / git.
+     */
+    ensureFreshContextStoreFn?: typeof ensureFreshContextStore;
+    /**
+     * `/reviewer-setup` wizard (2026-06-29) — Test seam for the async wizard-open
+     * data load. Defaults to the real `loadReviewerWizardData` (detect installed
+     * agents → `updateAvailableAgents` round-trip). Tests inject a stub to drive
+     * the REVIEWER_WIZARD_OPEN dispatch (and the no-agents / error advisory) without
+     * a real PATH probe or transport call.
+     */
+    loadReviewerWizardDataFn?: typeof loadReviewerWizardData;
+    /**
+     * `/reviewer-setup` wizard (2026-06-29) — Test seam for the TTY check that gates
+     * the Ink modal (non-TTY → advisory instead of a silent store flag). Defaults to
+     * the real `isInteractiveTty`. Tests inject `() => true` to exercise the open
+     * path (vitest runs non-TTY) and `() => false` for the fallback advisory.
+     */
+    isInteractiveTtyFn?: () => boolean;
 }
 /**
  * Slash + natural-language dispatch. Extracted from `runOrchestrationShell`
@@ -97,4 +613,100 @@ export interface HandleShellUserInputDeps extends StructuralSummaryRunDeps {
  * up the full TUI. Behaves identically to the inline closure in
  * `runOrchestrationShell`.
  */
+/**
+ * CP-1.f (Stage-2 Codex r3+r4) — wrap a shell input handler so natural-language
+ * submissions are processed STRICTLY SEQUENTIALLY (one planner turn in flight at
+ * a time). The TTY fires `onUserInput` fire-and-forget (InputBar
+ * `onSubmit: (text) => void`), so without serialization two handler invocations
+ * could overlap and interleave the clarification state machine
+ * (USER_INPUT bookkeeping + classify + PLANNER_DECISION), corrupting it.
+ *
+ * Slash commands (`text.startsWith('/')`, matching `handleShellUserInput`'s own
+ * routing) bypass the queue: they're fast, never trigger a planner classify,
+ * never touch clarification state, and include `/quit` — so they must stay
+ * responsive instead of waiting behind a slow/hung planner turn.
+ *
+ * The returned function preserves the caller-visible contract: it returns the
+ * promise for THIS submission's processing (so an awaiting caller still gets the
+ * real result/rejection), while the internal queue swallows rejections so one
+ * failed turn can't break serialization for later submissions.
+ */
+export declare function serializeShellSubmissions(handler: (text: string, images?: string[]) => Promise<void>): (text: string, images?: string[]) => Promise<void>;
+/**
+ * Process one shell submission (slash command or natural-language → planner).
+ *
+ * IMPORTANT (Stage-2 Codex r5): natural-language submissions MUST be serialized.
+ * Concurrent invocations interleave the clarification state machine (USER_INPUT
+ * bookkeeping + classify + PLANNER_DECISION) and corrupt it. Production callers
+ * MUST route through `serializeShellSubmissions` (as `runOrchestrationShell`
+ * does). The reducer's non-mutating defensive path + the dispatcher's
+ * `answeredThisTurn` gate are defense-in-depth only — they do NOT make it safe to
+ * call this directly with overlapping NL turns. Tests may call it directly
+ * because they await each call sequentially.
+ */
+/**
+ * PHASE-CP-10-MIN (#585) #C10M-9/16 — build the `/continue request` + `/continue
+ * accept` action deps for `runContinuationCli`. Wires the QuorumLoop's
+ * `requestContinuation` / `resumeFromContinuation` + the `applyUserDecision`
+ * mutation. Returns empty (no action capability) when no loop is wired (the
+ * slash route then reports "unavailable").
+ */
+export declare function buildContinuationActionDeps(args: RunOrchestrationShellArgs, store: OrchestrationStore): Partial<ContinuationCliDeps>;
+/**
+ * WEB-BROWSING deterministic fast-path detector (docs/WEB-BROWSING-DESIGN.md).
+ * Returns the http(s) URL(s) to read when the prompt is unambiguously a "read
+ * this URL" request, else null. Tight by design:
+ *   - SUPPRESSED while a clarification is pending (don't hijack a pending
+ *     start_task whose answer happens to be a URL) — the classifier handles it.
+ *     This is correct for EVERY pending clarification: a `browse` decision never
+ *     emits a clarifying_question (the parser invariant forbids advisory_summary/
+ *     clarifying_question on browse), so a pending clarification is ALWAYS from a
+ *     non-browse route — there is no "pending browse clarification" to preserve.
+ *   - fires ONLY when the prompt is URL-leading OR a read-intent verb governs the
+ *     URL clause (so "fix the CORS bug, API at https://…" stays start_task).
+ * The URL regex is copied from `protectUrls` (unexported in local-advisory.ts).
+ */
+export declare function detectBrowseFastPath(text: string, pending: PendingClarification | null): string[] | null;
 export declare function handleShellUserInput(deps: HandleShellUserInputDeps): Promise<void>;
+/**
+ * CP-4 §4.2 (Codex r1 M1 — the double-walk unify) — the SINGLE structural-
+ * summary refresh entry point. Drives the context store via
+ * `ensureFreshContextStore` (probe → recompute-if-stale → persist) and mirrors
+ * its result into the orchestration store so the `/structural-summary` preview,
+ * the familiarize overview, and the classify packet all read ONE summary.
+ *
+ * Before this unify there were up to THREE walks for a single familiarize after
+ * startup: session-start walked (but never seeded the store), pre-classify
+ * walked again (store still empty → cold), then `routeFamiliarize` walked a
+ * THIRD time via `runStructuralSummarySessionStart`. Now session-start AND
+ * pre-classify both go through this one function — which write-or-reuses the
+ * store — so a cache HIT on the unchanged tree means NO redundant walk, and
+ * `routeFamiliarize` renders from the already-refreshed store.
+ *
+ *  - On a RECOMPUTE (cold / drift / input-hash change): dispatch
+ *    STRUCTURAL_SUMMARY_GENERATED + emit the wire event + slow/truncation
+ *    notifications (preserving the §4.8 session-start behavior).
+ *  - On a CACHE REUSE (`reason: 'fresh'`): dispatch STRUCTURAL_SUMMARY_GENERATED
+ *    so the in-memory store reflects the reused summary, but DO NOT re-emit the
+ *    wire event (nothing changed for mobile) and DO NOT re-walk.
+ *  - On a REFRESH FAILURE: dispatch STRUCTURAL_SUMMARY_FAILED (the familiarize
+ *    floor renders the failure text). Best-effort — never throws.
+ *
+ * Returns the `EnsureFreshResult` so the pre-classify caller reads the fresh
+ * `digest` (FAIL-CLOSED empty on failure → the Lambda's empty-digest gate).
+ */
+declare function refreshStructuralSummaryIntoStore(deps: StructuralSummaryRunDeps & {
+    ensureFreshContextStoreFn?: typeof ensureFreshContextStore;
+    /**
+     * Emit the `STRUCTURAL_SUMMARY_GENERATED` WIRE event even when the store was
+     * REUSED (cache hit, not recomputed). Session-start passes `true` to
+     * preserve the legacy `runStructuralSummarySessionStart` behavior (it
+     * emitted on EVERY boot) so a mobile device connecting during a reuse-launch
+     * still receives the session's summary timeline event (Stage-1 r1 MEDIUM).
+     * The per-NL-turn callers (pre-classify / familiarize) leave it `false` so a
+     * `"hi"`/status turn on a fresh store does NOT spam a duplicate event. The
+     * slow/truncation NOTIFICATIONs stay gated on `recomputed` regardless (they
+     * describe the walk that just ran).
+     */
+    emitOnReuse?: boolean;
+}): Promise<EnsureFreshResult>;