@quantiya/codevibe-core 2.0.0 → 2.0.2

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

@@ -0,0 +1,777 @@
+import { Session } from '../types/session';
+import type { StructuralSummary } from '../structural-summary/types';
+import type { GatePromptEnvelope, ReviewSummaryPanelModel } from './gate-prompts';
+import type { TaskProgressEvent } from './task-progress';
+import type { ReviewerAgentSpec } from '../types/reviewer';
+/**
+ * Engine's reply to `applyUserDecision`. Surfaced by the SDK as
+ * `Promise<PostDecisionAction>`. Discriminated by `kind`; payload
+ * fields are snake_case to match the SDK's wire-form parse.
+ */
+export type PostDecisionAction = {
+    kind: 'terminate_gate';
+    notes: string | null;
+} | {
+    kind: 'open_new_round';
+    next_round: number;
+    user_notes: string;
+} | {
+    kind: 'restart_proposal';
+} | {
+    kind: 'abort_task';
+} | {
+    kind: 'final_approval_resolved';
+    decision: string;
+} | {
+    kind: 'continuation_switch_accepted';
+    target_agent: string;
+    next_gate_id: string;
+    next_round: number;
+    offer_id: string;
+} | {
+    kind: 'continuation_switch_declined';
+    offer_id: string;
+};
+/**
+ * CP-1.f execute-first (D5): does this `applyUserDecision` outcome mean the
+ * task's workspace shadow must be DISCARDED?
+ *
+ * ONLY genuinely non-authorize terminals discard:
+ *  - `abort_task`        — user aborted the task entirely.
+ *  - `restart_proposal`  — user rejected + restarted; a fresh round gets a
+ *                          fresh shadow.
+ *
+ * Everything else MUST NOT discard:
+ *  - `terminate_gate`    — the engine's reply for Accept/AcceptWithNotes on a
+ *                          halted/escalated gate ("gate terminally closed",
+ *                          codevibe-revision user_decision.rs) — an AUTHORIZE
+ *                          outcome. Discarding here raced the async
+ *                          TaskAuthorized promote and destroyed an approved
+ *                          diff (live dogfood 2026-06-10, task 5e16b2f9
+ *                          "promote no-op — no in-memory shadow"). On accept
+ *                          the shadow's fate belongs to the TaskAuthorized
+ *                          edge alone (#PR-1/#PR-3); promote cleans up, and a
+ *                          lost packet never reaps a pending shadow (#PR-4).
+ *  - `open_new_round`    — revise; the shadow persists across rounds (D6).
+ *  - `final_approval_resolved` — promote via the TaskAuthorized edge.
+ */
+export declare function postActionDiscardsShadow(kind: PostDecisionAction['kind']): boolean;
+/**
+ * #606 (FACE A) — map a per-track `applyUserDecision` `postAction` to the
+ * team-track RENDER-terminal state, MIRRORING the engine's authoritative
+ * `apply_user_decision::fire_deferred_track_terminal` disposition map so the
+ * desktop render flips out of `InFlight` the moment the user resolves the
+ * track's own gate (the #469 "stuck InFlight" gap):
+ *
+ *   - `terminate_gate`           → Accept/AcceptWithNotes on an escalation gate
+ *                                  (→ engine `Passed`)            → 'Passed'
+ *   - `final_approval_resolved`  → FinalApproval: Approve (→ `Passed`) vs Cancel
+ *                                  (→ `Failed`), distinguished by `decision`     →
+ *                                  'Passed' / 'Failed'
+ *   - `abort_task`               → AbortTask on an escalation (→ `Failed`)        →
+ *                                  'Failed'
+ *   - everything else (`open_new_round` / `restart_proposal` /
+ *     `continuation_switch_*`)  → a NEW gate follows; the track keeps working and
+ *                                  the engine fires NO terminal mark           → null
+ *
+ * `null` means "do NOT flip" — the render stays `InFlight` (the next gate's user
+ * edge resolves it). The `final_approval_resolved` `decision` discriminator
+ * matches the engine: `handle_final_approval` synthesizes the SAME
+ * `final_approval_resolved` kind for BOTH Approve and Cancel, carrying the
+ * submitted decision string; the engine maps Approve→Passed, Cancel→Failed.
+ */
+export declare function postActionTeamTrackState(postAction: PostDecisionAction): 'Passed' | 'Failed' | null;
+/**
+ * CP-1.a §2 LOCK. The literal union used for sticky-preference, mode
+ * selection, and the `MODE_SELECTED` EventType `metadata.mode` field.
+ */
+export type Mode = 'companion' | 'orchestration';
+/**
+ * Structural stub matching the design §6 5-action schema. CP-1.b
+ * replaces this with the real `PlannerDecision` from
+ * `codevibe-core/src/planner/adapter.ts`. CP-1.a only needs the
+ * SHAPE — never inspects field semantics beyond what `OrchestrationAction`
+ * consumes.
+ *
+ * Per §6 line 958-965: discriminated by `action`; `clarifying_question`
+ * present only when action === 'ask_user'; `advisory_summary` only
+ * when action === 'advisory_response'; `gateRequest` opaque per §6
+ * line 967-972 (CP-2 Stage A finalises shape).
+ */
+export interface PlannerDecision {
+    action: 'start_task' | 'summarize_current_status' | 'advisory_response' | 'ask_user' | 'refuse' | 'team_decompose' | 'familiarize' | 'brainstorm' | 'browse';
+    rationale: string;
+    clarifying_question?: string;
+    advisory_summary?: string;
+    /** WEB-BROWSING — explicit http(s) URLs to read. */
+    browseUrls?: string[];
+    /** WEB-BROWSING — a web-search query when no explicit URL is given. */
+    browseQuery?: string;
+    /**
+     * Opaque per §6 line 967-972; CP-1 NEVER inspects fields. CP-2 Stage A
+     * locks shape.
+     */
+    gateRequest?: Record<string, unknown>;
+}
+export interface BrainstormContextMetadata {
+    needsRepositoryContext: boolean;
+}
+export type AgentKind = 'CLAUDE' | 'GEMINI' | 'CODEX' | 'ANTIGRAVITY';
+/**
+ * Health-state surface from §8. CP-1.a stores this in
+ * `OrchestrationState.plannerHealth`; CP-1.b's state machine drives
+ * the transitions.
+ */
+export type PlannerHealthState = 'Available' | 'Degraded' | 'Outage';
+/**
+ * §5.1 store-shape LOCK (lines 537-545). Implementor subprocess
+ * lifecycle from spawn to clean exit.
+ */
+export interface RunningTaskState {
+    taskId: string;
+    agentKind: AgentKind;
+    pid: number;
+    startedAt: string;
+    status: 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed';
+    exitCode?: number;
+    bypassReason?: 'deterministic_shortcut' | 'planner_outage' | 'planner_degraded_explicit_override';
+}
+/**
+ * §5.1 LOCK (lines 547-556). Single reviewer subprocess identity +
+ * verdict. `reviewerKind` is hand-listed per CP-1 — CP-3 Stage A
+ * widens to the full reviewer-registry per `[DEFERRED TECH DEBT — CP-3]`
+ * note at design line 774.
+ */
+export interface ReviewerSeatState {
+    seatId: string;
+    reviewerKind: 'codex' | 'gemini' | 'claude';
+    status: 'queued' | 'running' | 'PASS' | 'REVISE' | 'BLOCK';
+    startedAt?: string;
+    elapsedMs?: number;
+    findingCount?: number;
+    verdictDigest?: string;
+}
+/**
+ * §5.1 LOCK (lines 558-569). Per-gate aggregate over reviewer-quorum +
+ * auto-revise round count. `autoReviseCap: 2 | 6` literal-union prevents
+ * accidental drift in implementor code per CP-0 §6 line 155 (Pro = 2,
+ * Max = 6).
+ */
+export interface GateState {
+    gateId: string;
+    taskId: string;
+    gateKind: 'code-review' | 'merge-gate' | 'continuation-handoff';
+    quorumRequired: number;
+    quorumAchieved: number;
+    autoReviseRound: number;
+    autoReviseCap: 2 | 6;
+    status: 'pending' | 'in_review' | 'PASS' | 'REVISE' | 'BLOCK' | 'merge_gate_pending';
+    finalizedAt?: string;
+}
+/**
+ * §5.1 LOCK lines 576-583. LE-originated Class A `EXECUTION_EVENT`
+ * messageType payloads. Five sub-kinds per CP-0 §2.4 verbatim.
+ */
+export interface ExecutionEventEntry {
+    eventId: string;
+    timestamp: string;
+    kind: 'PROCESS_SPAWNED' | 'FILE_CHANGE' | 'TOOL_USE' | 'VERIFICATION_RUN' | 'PROCESS_EXITED';
+    parentTaskId: string;
+    authorRole: 'implementor' | 'reviewer' | 'shell';
+    payload: Record<string, unknown>;
+}
+/**
+ * §5.1 LOCK lines 591-613. Separate Class A `EXECUTOR_REFUSAL`
+ * messageType per CP-0 §2.3 + §2.4. NOT an EXECUTION_EVENT sub-kind.
+ */
+export interface RefusalEventEntry {
+    eventId: string;
+    timestamp: string;
+    kind: 'EXECUTOR_REFUSAL';
+    parentTaskId: string;
+    authorRole: 'shell';
+    payload: {
+        refusedMessageId: string;
+        refusalCategory: 'authority_scope_conflict' | 'local_permission_denied' | 'signature_invalid' | 'ulid_replay' | 'auth_revoked_local' | 'transport_authority_mismatch';
+        refusalDetail: string;
+        recommendedRecovery: 'reauthorize_locally' | 'abort_task' | 'ask_user' | 'retry_after_resync';
+    };
+}
+/**
+ * §5.1 LOCK lines 621-628. CP-1 placeholder; payload shape is
+ * `[DEFERRED TECH DEBT — CP-2]` per design.
+ */
+export interface BypassEventEntry {
+    eventId: string;
+    timestamp: string;
+    kind: 'TASK_BYPASS';
+    parentTaskId: string;
+    authorRole: 'shell';
+    payload: {
+        bypassReason: string;
+    };
+}
+/**
+ * §5.1 LOCK lines 635-642. Mobile-replay EventType values that flow
+ * into the store without going through the Class A wire. `parentTaskId`
+ * is nullable per Stage 2 r3 Gemini M1 — `NOTIFICATION` events may be
+ * session-scope.
+ */
+export interface MobileEventEntry {
+    eventId: string;
+    timestamp: string;
+    kind: 'USER_PROMPT' | 'ASSISTANT_RESPONSE' | 'INTERACTIVE_PROMPT' | 'NOTIFICATION';
+    parentTaskId: string | null;
+    source: 'DESKTOP' | 'MOBILE';
+    payload: Record<string, unknown>;
+}
+/**
+ * §5.1 LOCK line 646. Discriminated union used inside
+ * `ConversationEntry.subagent-event`.
+ */
+export type EventStreamEntry = ExecutionEventEntry | RefusalEventEntry | BypassEventEntry | MobileEventEntry;
+/**
+ * §5.1 LOCK lines 527-534. Discriminated union; every entry carries
+ * `final: boolean`. Non-final entries re-render in place; final entries
+ * freeze in scrollback (migrate from `<ConversationPane>` into `<Static>`
+ * per design line 441-447).
+ */
+/**
+ * A LOCAL image-file reference attached to a user turn (IMAGE-ATTACHMENT-DESIGN.md
+ * §5). Desktop-only — carries a path + validated metadata, NEVER the bytes and
+ * NEVER an s3Key (bytes stay on disk; they reach the local model as base64 and the
+ * implementor as an in-worktree copy, both on-device). The strict planner
+ * text-in/JSON-out contract is unchanged — attachments ride on the runtime turn /
+ * task-scoped state, never on `PlannerDecision`/`PlannerInput`.
+ */
+export interface ImageAttachment {
+    /** ulid. */
+    id: string;
+    /**
+     * Resolved LEXICAL absolute path on the user's machine (the `O_NOFOLLOW` copy
+     * source, §4/§7.3). DISPLAY-only otherwise — never placed in the prompt/brief.
+     */
+    sourcePath: string;
+    /**
+     * EVERY exact matched SPAN that referenced this file — across the original turn
+     * AND clarification-answer turns — INCLUDING surrounding quotes/escapes
+     * (`~/foo.png`, `'…/a b.png'`, `/a\ b.png`). A LIST: the same file can be typed
+     * two ways; the COPY is deduped by `sourcePath` but the canonical-brief
+     * replacement (§8) must rewrite EVERY occurrence or an absolute span leaks.
+     */
+    rawTokens: string[];
+    /**
+     * Raw basename — DISPLAY-ONLY (the conversation chip). NEVER used in the
+     * in-worktree path or the prompt (a basename can carry control chars/newlines →
+     * injection). The in-worktree copy is named `<id>.<ext-from-sniffed-mime>`.
+     */
+    filename: string;
+    /** From the bounded magic-byte sniff (`image/png`, …), NOT the extension. */
+    mime: string;
+    sizeBytes: number;
+}
+export type ConversationEntry = {
+    kind: 'user-message';
+    id: string;
+    timestamp: string;
+    final: true;
+    text: string;
+    attachments?: ImageAttachment[];
+    /**
+     * §13 Option-2 — the ordered-with-DUPLICATES resolved carried-path list for this
+     * turn's `[Image #N]` chips (index N-1 ↔ chip #N). Distinct from `attachments`
+     * (deduped by `sourcePath`): dedup loses the count/order the number-based chip
+     * rewrite needs. Carried into `pending.attachmentPaths` when a clarification mints.
+     */
+    imagePaths?: string[];
+} | {
+    kind: 'planner-decision';
+    id: string;
+    timestamp: string;
+    final: true;
+    action: PlannerDecision['action'];
+    rationale: string;
+    taskId?: string;
+    brainstorm?: BrainstormContextMetadata;
+} | {
+    kind: 'subagent-event';
+    id: string;
+    timestamp: string;
+    final: true;
+    parentTaskId: string;
+    role: 'implementor' | 'reviewer';
+    event: EventStreamEntry;
+} | {
+    kind: 'reviewer-status-node';
+    id: string;
+    timestamp: string;
+    final: boolean;
+    taskId: string;
+    seats: ReviewerSeatState[];
+    quorumStatus: 'queued' | 'running' | 'PASS' | 'REVISE' | 'BLOCK';
+} | {
+    kind: 'gate-status-node';
+    id: string;
+    timestamp: string;
+    final: boolean;
+    taskId: string;
+    gate: GateState;
+} | {
+    kind: 'slash-output';
+    id: string;
+    timestamp: string;
+    final: true;
+    command: string;
+    output: string;
+} | {
+    kind: 'advisory';
+    id: string;
+    timestamp: string;
+    final: true;
+    source: 'planner' | 'shell';
+    text: string;
+} | {
+    kind: 'gate-prompt';
+    id: string;
+    timestamp: string;
+    final: false | true;
+    envelope: GatePromptEnvelope;
+    queue: ReadonlyArray<GatePromptEnvelope>;
+    uiState: {
+        phase: 'awaiting-number';
+    } | {
+        phase: 'awaiting-notes';
+        decisionDraft: string;
+    } | {
+        phase: 'submitting';
+    } | {
+        phase: 'resolved';
+        postAction: PostDecisionAction;
+        resolvedBy: 'self';
+    } | {
+        phase: 'resolved';
+        resolvedBy: 'server';
+        serverDecision: string | null;
+    };
+    reviewSummary?: ReviewSummaryPanelModel;
+} | {
+    kind: 'gate-panel';
+    id: string;
+    timestamp: string;
+    final: true;
+    panel: {
+        variant: 'prompt';
+        envelope: GatePromptEnvelope;
+    } | {
+        variant: 'summary';
+        reviewSummary: ReviewSummaryPanelModel;
+    };
+};
+/**
+ * §5.1 LOCK lines 485-490. Stage 2 r3 Gemini M4. Captures a
+ * PlannerDecision the user wants to run but cannot start yet because
+ * the prior task is still running.
+ */
+export interface QueuedTask {
+    queuedTaskId: string;
+    plannerDecision: PlannerDecision;
+    queuedAt: string;
+    blockedOnTaskId?: string;
+}
+/**
+ * §5.1 LOCK lines 496-500. Codex r2 M1. Captures the original prompt
+ * + every clarifying question the planner has asked so far + the user's
+ * answers. Next USER_INPUT under `pendingClarification !== null`
+ * resolves the most recent question and re-routes through
+ * `classifyPlannerPrompt` with the full `clarifications` array.
+ */
+export interface PendingClarification {
+    originalPrompt: string;
+    rounds: Array<{
+        question: string;
+        answer?: string;
+    }>;
+    conversationEntryId: string;
+    /**
+     * Accumulated image attachments across the ORIGINAL turn + every
+     * clarification-answer turn (IMAGE-ATTACHMENT-DESIGN.md §5, rev-4). The final
+     * task attachment set = original ∪ answer-turn attachments, deduped by
+     * `sourcePath`; `composeImplementationBrief` reads this when the task launches
+     * so an image attached before a planner question isn't lost.
+     */
+    attachments?: ImageAttachment[];
+    /**
+     * §13 Option-2 — the ordered-with-DUPLICATES resolved carried-path list ACCUMULATED
+     * across the original turn + every clarification-answer turn (index N-1 ↔ the globally
+     * cross-turn-renumbered chip #N). The number-based `[Image #N]` rewrite keys on this
+     * (path → deduped attachment) so a duplicate same-file drag and a multi-turn image
+     * both resolve to the correct ref. Grows by exactly this turn's `imagePaths` each turn.
+     */
+    attachmentPaths?: string[];
+}
+/**
+ * [ADDITIVE WIDENING — CP-12 W3, per PHASE-CP-12-DESIGN.md §3.5 "minimal
+ * multi-track status node; rich UX is #469"]. Per-track lifecycle state as the
+ * status node renders it. The deep 6-class failure UX + rich per-track timeline
+ * are [DEFERRED → CP-8 #469] — this carries ONLY the compact node's inputs.
+ *
+ * [ADDITIVE WIDENING — PHASE-589/469 W2] `Revising` — a transient NON-terminal
+ * state while a team track auto-revises (the engine minted a round-N+1 REVISE
+ * round on a revisable verification-failed marker, cap permitting). The track
+ * flips back to `InFlight` machinery on the re-spawn and resolves to
+ * `Passed`/`Failed` later; on cap-exhaust it terminal-fails to `Failed` (W1's
+ * render). NOT a terminal state — the group-terminal check treats only
+ * `Passed`/`Failed` as terminal.
+ */
+export type TeamTrackState = 'Pending' | 'InFlight' | 'Passed' | 'Failed' | 'Revising' | 'AwaitingDecision';
+/**
+ * [ADDITIVE WIDENING — CP-12 W3] The group MergeGate status as the compact
+ * status node renders it. `'none'` until a MergeGateDispatch arrives.
+ */
+export type TeamMergeGateStatus = 'none' | 'pending' | 'pass' | 'fail';
+/**
+ * Human label for a `TeamMergeGateStatus` — the SINGLE source of truth shared by
+ * the `<MultiTrackStatusNode>` header and the `/status` (`buildStatusSummary`)
+ * text, so the two never drift.
+ */
+export declare const MERGE_GATE_STATUS_LABEL: Record<TeamMergeGateStatus, string>;
+/**
+ * [ADDITIVE WIDENING — CP-12 W3] Minimal per-track entry for the status node.
+ */
+export interface TeamTrackEntry {
+    state: TeamTrackState;
+    taskId?: string;
+    agent?: string;
+}
+/**
+ * [ADDITIVE WIDENING — CP-12 W3] Minimal team state. `null` for
+ * single-track/Companion/stub sessions (no team → no status node). Populated
+ * when `/team` accepts a task group + per-track W2.b shell events arrive.
+ */
+export interface TeamState {
+    taskGroupId: string;
+    /** track_index → minimal track entry. */
+    tracks: Map<number, TeamTrackEntry>;
+    mergeGate: TeamMergeGateStatus;
+    /** Set when a TaskGroupHalted is surfaced (status node shows a halt line). */
+    haltReason: string | null;
+    /**
+     * [ADDITIVE WIDENING — PHASE-589+469 W1] `true` once the group's MergeGate
+     * resolves to a terminal outcome (the desktop consumed the AUTHORITATIVE
+     * `{ outcome }` returned by `submitMergeGateVerdict`). Drives the
+     * `MultiTrackStatusNode` footer (`Team complete` / `Team halted — <class>`).
+     * Stays `false` for an in-flight group.
+     */
+    groupResolved: boolean;
+    /**
+     * [ADDITIVE WIDENING — PHASE-589+469 W1] The AUTHORITATIVE engine outcome
+     * string (`"complete"` or a `halted_reason` const) once `groupResolved` is
+     * set; `undefined` until then. The footer renders `complete` vs the failure
+     * class from this value.
+     */
+    outcome?: string;
+    /**
+     * [ADDITIVE WIDENING — TUI-LIVE-TASK-STATUS-PHASE-1B-2 P1b] ISO wall-clock
+     * anchor stamped (strictly-monotonic, LE-side) when the merge gate first goes
+     * `'pending'`; carried forward and used to tick the merge-gate elapsed timer on
+     * `MultiTrackStatusNode`. Re-anchored on a genuine re-drain (strictly-newer
+     * `started_at`); undefined until the first `'pending'`.
+     */
+    mergeGateStartedAt?: string;
+    /**
+     * [ADDITIVE WIDENING — TUI-LIVE-TASK-STATUS-PHASE-1B-2 P1b] Frozen final elapsed
+     * (ms) of the merge gate. WRITE-ONCE: set by the FIRST terminal (convergence
+     * pass/fail, the local attempt-end, or the groupResolved/halted fallback) and
+     * never overwritten by a later shared-convergence emit; cleared (→ undefined) on
+     * a re-drain so the next generation can write. `null`/undefined ⇔ still ticking.
+     */
+    mergeGateElapsedMs?: number;
+}
+/**
+ * [ADDITIVE WIDENING — CP-1.f live progress surfacing] The single EPHEMERAL
+ * live status line shown between the StatusBar and the InputBar while a task is
+ * busy (implementor running, promote/discard in flight). `null` when idle / when
+ * the user is in control (a gate prompt is shown → `waiting_user` clears it).
+ * Milestones (diff captured, verdicts received, promoted, …) are NOT stored here
+ * — they are appended to `conversation` as persisted scrollback entries. This is
+ * desktop-LOCAL only: counts/labels/elapsed, never plaintext (see
+ * `task-progress.ts`).
+ */
+export interface LiveProgress {
+    /** The phase of the in-flight spinner line. */
+    phase: TaskProgressEvent['phase'];
+    /** The BOUNDED live label (counts/labels/paths only — no plaintext, no embedded timer). */
+    text: string;
+    /** When this line was last refreshed. Retained; currently unused (no component reads it). */
+    updatedAt: string;
+    /** ISO — when THIS busy window opened; the wall-clock timer anchor. */
+    startedAt: string;
+    /**
+     * The per-TASK origin epoch of the event that opened/last-refreshed this window
+     * (§2/§3). Undefined ONLY for the direct-dispatched classify/familiarize windows
+     * (they carry no epoch). The reducer's straggler guard no-ops any event whose
+     * epoch is strictly OLDER than this.
+     */
+    epoch?: number;
+    /**
+     * [ADDITIVE WIDENING — token counter, Phase 2 · P2-4] The per-TASK CUMULATIVE
+     * token total carried MONOTONICALLY across same-epoch OPEN/REFRESH builds
+     * (`Math.max(cur, event.tokens) || undefined`) so a token-less refresh keeps the
+     * prior count and a reopened window preserves it; reset on a new epoch. A bare
+     * count (invariant-safe). `undefined` until a source reports (segment omitted).
+     */
+    tokens?: number;
+}
+/**
+ * §5.1 LOCK lines 463-480. Owned by the orchestration-shell store.
+ * Bounded ring buffer on `conversation` (last 500 entries — design line
+ * 469).
+ */
+export interface OrchestrationState {
+    session: Session;
+    plannerHealth: PlannerHealthState;
+    conversation: ConversationEntry[];
+    runningTasks: Map<string, RunningTaskState>;
+    queuedTasks: QueuedTask[];
+    activeReviewerSeats: Map<string, ReviewerSeatState>;
+    currentGate: GateState | null;
+    pendingClarification: PendingClarification | null;
+    inputHistory: string[];
+    /**
+     * `[ADDITIVE WIDENING — CP-1.d]` per `PHASE-CP-1-D-DESIGN.md` §4.8
+     * lines 1011-1019. `null` until session-start generation completes (or
+     * the `/structural-summary --regenerate` side effect refreshes it).
+     * sha256 is stable per `assembler.ts` canonical-replacer.
+     */
+    structuralSummary: StructuralSummary | null;
+    /**
+     * `[ADDITIVE WIDENING — CP-1.d]` per `PHASE-CP-1-D-DESIGN.md` §4.8
+     * lines 1011-1019. Populated when `STRUCTURAL_SUMMARY_FAILED` fires
+     * (fail-closed per §4.7); cleared on next successful regeneration.
+     */
+    structuralSummaryError: string | null;
+    /**
+     * `[ADDITIVE WIDENING — CP-12 W3]` per PHASE-CP-12-DESIGN.md §3.5. `null`
+     * for single-track/Companion/stub sessions (the status node is hidden).
+     * Populated by `/team` (createTaskGroup accepted) + the W2.b per-track shell
+     * events. Rich per-track timeline + MergeGate result card are
+     * [DEFERRED → CP-8 #469].
+     */
+    team: TeamState | null;
+    /**
+     * `[ADDITIVE WIDENING — CP-1.f live progress surfacing]` The current ephemeral
+     * live status line (spinner). `null` when idle / waiting on the user. Updated
+     * in place by `TASK_PROGRESS` spinner phases; cleared by `waiting_user` and by
+     * the terminal milestone phases (`promoted` / `discarded`). Non-loop /
+     * Companion / stub sessions never dispatch `TASK_PROGRESS`, so this stays null.
+     */
+    progress: LiveProgress | null;
+    /**
+     * `[ADDITIVE WIDENING — /reviewer-setup wizard, 2026-06-29]` The active
+     * interactive reviewer-panel setup modal, or `null` when no wizard is open
+     * (the default — InputBar is shown). Opened by the `/reviewer-setup` slash
+     * command (`REVIEWER_WIZARD_OPEN`, after the entrypoint detects installed
+     * agents + reads the current policy); cleared on save/cancel
+     * (`REVIEWER_WIZARD_CLOSE`). While non-null, `<OrchestrationApp>` renders
+     * `<ReviewerSetupWizard>` IN PLACE OF the `<InputBar>` so the wizard owns
+     * keyboard focus. Non-team / Companion / CP-1.a sessions never open it.
+     */
+    reviewerWizard: ReviewerWizardState | null;
+}
+/**
+ * Snapshot threaded into the interactive `/reviewer-setup` wizard when it
+ * opens. The entrypoint (`handleShellUserInput`) gathers these BEFORE
+ * dispatching `REVIEWER_WIZARD_OPEN` so the wizard renders synchronously from
+ * props with no in-component network I/O:
+ *   - `tier` decides the seat budget (Pro = 2 seats, Max = 3).
+ *   - `installedAgents` is the host-detected agent set — the wizard offers ONLY
+ *     these as reviewer choices (mirrors the `codevibe orchestration configure`
+ *     CLI), so a user can never pick an uninstalled agent.
+ *   - `currentSeats` is shown as a CONTEXT line at the top of the wizard (the
+ *     user's existing panel) — display only; the wizard starts fresh at the
+ *     panel-choice step. Absent → "tier defaults".
+ *
+ * NB: there is no enable/disable state — the legacy `orchestrationEnabledDefault`
+ * opt-in was removed in CP-1 (2.0 orchestration is shell-driven, not a stored
+ * flag), so the wizard configures the reviewer PANEL only.
+ */
+export interface ReviewerWizardState {
+    tier: Tier;
+    installedAgents: Array<'CLAUDE' | 'GEMINI' | 'CODEX' | 'ANTIGRAVITY'>;
+    currentSeats: ReviewerAgentSpec[] | null;
+}
+/**
+ * §5.1 LOCK lines 502-513. Discriminated union over every state
+ * transition the reducer covers. `attachedTaskId` / `ATTACH` / `DETACH`
+ * variants are NOT present per §5.1.5 — `/attach` is DEFERRED to CP-1.1.
+ *
+ * [ADDITIVE WIDENING — CP-1.a, per Stage 1 r1 MEDIUM-1] CP-1.a widens the
+ * locked §5.1 OrchestrationAction with 5 additive surfaces (all required
+ * by the reducer + render pipeline; none change the locked semantics):
+ *
+ *   - `PLANNER_DECISION.taskId?: string` (optional) — populates
+ *     `state.runningTasks.taskId` when the decision spawns one. CP-1.b
+ *     will widen further when the planner client wires the real taskId.
+ *   - `REVIEWER_STATE_CHANGED.nodeId: string` — disambiguates which
+ *     `kind:'reviewer-status-node'` ConversationEntry to update in place
+ *     (multiple reviewer-quorum nodes can be live concurrently).
+ *   - `GATE_STATE_CHANGED.nodeId: string` — same disambiguation for
+ *     `kind:'gate-status-node'`.
+ *   - `TASK_LIFECYCLE` (new variant) — populates `state.runningTasks`
+ *     on spawn / cancel / completion. The design's §5.1 line 470 calls
+ *     for `runningTasks: Map<string, RunningTaskState>` but did not name
+ *     the action that writes to it; this is the gap-filling variant.
+ *   - `CLEAR_PENDING_CLARIFICATION` (new variant) — invoked by `cli.ts`
+ *     when the planner returns a non-`ask_user` decision and we need to
+ *     clear stale clarifications. Design §5.1 says the next USER_INPUT
+ *     resolves the question, but a non-ask_user decision returning
+ *     out-of-band needs an explicit reset.
+ *
+ * CP-1.b/c may further widen the union. Stage A LOCK invariant: every
+ * NEW variant or required field is tagged here before the reducer
+ * consumes it.
+ */
+export type OrchestrationAction = {
+    type: 'USER_INPUT';
+    text: string;
+    attachments?: ImageAttachment[];
+    imagePaths?: string[];
+} | {
+    type: 'PLANNER_DECISION';
+    decision: PlannerDecision;
+    taskId?: string;
+    brainstorm?: BrainstormContextMetadata;
+} | {
+    type: 'EVENT_RECEIVED';
+    event: EventStreamEntry;
+    role?: 'implementor' | 'reviewer';
+} | {
+    type: 'REVIEWER_STATE_CHANGED';
+    nodeId: string;
+    seatId: string;
+    newState: ReviewerSeatState;
+} | {
+    type: 'GATE_STATE_CHANGED';
+    nodeId: string;
+    gate: GateState;
+} | {
+    type: 'PLANNER_HEALTH_CHANGED';
+    newState: PlannerHealthState;
+} | {
+    type: 'SLASH_OUTPUT';
+    command: string;
+    output: string;
+} | {
+    type: 'CLARIFICATION_ANSWERED';
+    answer: string;
+} | {
+    type: 'TASK_QUEUED';
+    queuedTask: QueuedTask;
+} | {
+    type: 'TASK_DEQUEUED';
+    queuedTaskId: string;
+} | {
+    type: 'TASK_LIFECYCLE';
+    task: RunningTaskState;
+} | {
+    type: 'CLEAR_PENDING_CLARIFICATION';
+} | {
+    type: 'STRUCTURAL_SUMMARY_GENERATED';
+    summary: StructuralSummary;
+    elapsedMs: number;
+} | {
+    type: 'STRUCTURAL_SUMMARY_FAILED';
+    error: string;
+} | {
+    type: 'GATE_PROMPT_RECEIVED';
+    envelope: GatePromptEnvelope;
+} | {
+    type: 'GATE_PROMPT_NOTES_REQUESTED';
+    promptEntryId: string;
+    decisionDraft: string;
+} | {
+    type: 'GATE_PROMPT_SUBMIT_STARTED';
+    promptEntryId: string;
+} | {
+    type: 'GATE_PROMPT_RESOLVED';
+    promptEntryId: string;
+    gateId: string;
+    postAction: PostDecisionAction;
+} | {
+    type: 'GATE_PROMPT_SUBMIT_FAILED';
+    promptEntryId: string;
+    gateId: string;
+    error: string;
+} | {
+    type: 'GATE_PROMPT_RESOLVED_EXTERNALLY';
+    promptEntryId: string;
+    gateId: string;
+    serverDecision: string | null;
+} | {
+    type: 'SHELL_ADVISORY';
+    text: string;
+    source: 'shell';
+} | {
+    type: 'GATE_PROMPT_NOTES_CANCELLED';
+    promptEntryId: string;
+} | {
+    type: 'GATE_SUMMARY_LOADED';
+    gateId: string;
+    panelModel: ReviewSummaryPanelModel;
+} | {
+    type: 'TEAM_STARTED';
+    taskGroupId: string;
+} | {
+    type: 'TEAM_TRACK_ASSIGNED';
+    trackIndex: number;
+    state: TeamTrackState;
+    taskId?: string;
+    agent?: string;
+} | {
+    type: 'TEAM_MERGE_GATE';
+    status: TeamMergeGateStatus;
+    startedAt?: string;
+    endedAt?: string;
+} | {
+    type: 'TEAM_HALTED';
+    haltReason: string;
+} | {
+    type: 'TEAM_TRACK_TERMINAL';
+    trackIndex: number;
+    state: TeamTrackState;
+} | {
+    type: 'TEAM_TRACK_REVISING';
+    trackIndex: number;
+} | {
+    type: 'TEAM_TRACK_AWAITING_DECISION';
+    trackIndex: number;
+} | {
+    type: 'TEAM_GROUP_RESOLVED';
+    outcome: string;
+} | {
+    type: 'TASK_PROGRESS';
+    event: TaskProgressEvent;
+} | {
+    type: 'REVIEWER_WIZARD_OPEN';
+    wizard: ReviewerWizardState;
+} | {
+    type: 'REVIEWER_WIZARD_CLOSE';
+} | {
+    type: 'EXIT';
+};
+/**
+ * §2 LOCK lines 108-113. `~/.codevibe/last-mode.json` shape.
+ */
+export interface LastModeFile {
+    schemaVersion: 1;
+    mode: Mode;
+    pickedAt: string;
+    pickedByTier: 'PRO' | 'MAX';
+}
+/**
+ * Tier surface used by §2 mode-selection. Matches the runtime tiers
+ * carried by `getSubscriptionStatus` (FREE / PRO / MAX). CP-1.a only
+ * needs the literal union — the AppSync-side enum lives in
+ * `src/types/auth.ts` already.
+ */
+export type Tier = 'FREE' | 'PRO' | 'MAX';