@quantiya/codevibe-core 2.0.1 → 2.0.3

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

@@ -1,6 +1,8 @@
 import { Session } from '../types/session';
 import type { StructuralSummary } from '../structural-summary/types';
-import type { GatePromptEnvelope } from './gate-prompts';
+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
@@ -17,7 +19,68 @@ export type PostDecisionAction = {
     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.
@@ -36,17 +99,24 @@ export type Mode = 'companion' | 'orchestration';
  * line 967-972 (CP-2 Stage A finalises shape).
  */
 export interface PlannerDecision {
-    action: 'start_task' | 'summarize_current_status' | 'advisory_response' | 'ask_user' | 'refuse';
+    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 type AgentKind = 'CLAUDE' | 'GEMINI' | 'CODEX';
+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
@@ -166,12 +236,54 @@ export type EventStreamEntry = ExecutionEventEntry | RefusalEventEntry | BypassE
  * 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;
@@ -180,6 +292,7 @@ export type ConversationEntry = {
     action: PlannerDecision['action'];
     rationale: string;
     taskId?: string;
+    brainstorm?: BrainstormContextMetadata;
 } | {
     kind: 'subagent-event';
     id: string;
@@ -235,6 +348,23 @@ export type ConversationEntry = {
         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;
     };
 };
 /**
@@ -262,6 +392,135 @@ export interface PendingClarification {
         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.
@@ -291,6 +550,55 @@ export interface OrchestrationState {
      * (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
@@ -326,10 +634,13 @@ export interface OrchestrationState {
 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;
@@ -384,11 +695,18 @@ export type OrchestrationAction = {
 } | {
     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;
@@ -396,6 +714,48 @@ export type OrchestrationAction = {
 } | {
     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';
 };

package/dist/orchestration-shell/vendor/ink-parse-keypress.d.ts

@@ -0,0 +1,42 @@
+/** Key names that are NOT printable text — `input` is blanked for these. */
+export declare const nonAlphanumericKeys: string[];
+export interface ParsedKeypress {
+    name: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    option: boolean;
+    sequence: string;
+    raw: string | undefined;
+    code?: string;
+}
+/** Verbatim port of Ink 5.2.1 `parseKeypress` (string input — Ink sets utf8). */
+export declare const parseKeypress: (s?: string | undefined) => ParsedKeypress;
+/** The `key` object shape Ink's `useInput` hands to its handler. */
+export interface InkKey {
+    upArrow: boolean;
+    downArrow: boolean;
+    leftArrow: boolean;
+    rightArrow: boolean;
+    pageDown: boolean;
+    pageUp: boolean;
+    return: boolean;
+    escape: boolean;
+    ctrl: boolean;
+    shift: boolean;
+    tab: boolean;
+    backspace: boolean;
+    delete: boolean;
+    meta: boolean;
+}
+/**
+ * Mirror of `ink/build/hooks/use-input.js` (5.2.1) lines 46-80: derive the
+ * `(input, key)` pair `useInput` would deliver for a raw data chunk. The Ctrl+C
+ * gate + `reconciler.batchedUpdates` dispatch from use-input.js are intentionally
+ * NOT here — the caller owns dispatch (Ctrl+C is already handled by Ink's
+ * `App.handleInput` before the chunk is emitted).
+ */
+export declare function toInkKey(data: string): {
+    input: string;
+    key: InkKey;
+};

package/dist/orchestration-shell/web/extract.d.ts

@@ -0,0 +1,11 @@
+export interface ExtractResult {
+    title: string;
+    text: string;
+}
+/** Test seam: drop the cached parse5 load so a re-stubbed ESM loader takes effect. */
+export declare function __resetExtractCacheForTest(): void;
+/**
+ * Extract a page title + visible body text from HTML via parse5. Async (parse5 is ESM-only) and
+ * NEVER throws — returns `{ title:'', text:'' }` on the size cap / load / parse failure.
+ */
+export declare function htmlToText(html: string): Promise<ExtractResult>;

package/dist/orchestration-shell/web/fetch.d.ts

@@ -0,0 +1,15 @@
+export type FetchFailureKind = 'blocked' | 'too_large' | 'timeout' | 'network' | 'bad_content' | 'too_many_redirects' | 'http_error';
+export declare class FetchError extends Error {
+    readonly kind: FetchFailureKind;
+    constructor(kind: FetchFailureKind, message: string);
+}
+export interface FetchResult {
+    finalUrl: string;
+    contentType: string;
+    body: string;
+}
+/**
+ * Guarded GET with manual redirect following (full guard re-run per hop). Returns
+ * decoded text or throws FetchError. `signal` lets the caller (Esc) abort.
+ */
+export declare function guardedFetch(rawUrl: string, signal?: AbortSignal): Promise<FetchResult>;

package/dist/orchestration-shell/web/ip.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonicalize + classify an address string. Accepts only a real IPv4/IPv6
+ * literal (the fetch guard passes addresses from `dns.lookup`, which are
+ * already canonical). Returns false for anything not provably public unicast
+ * (fail closed). Decimal/hex/octal "IP" host forms are NOT valid `net.isIP`
+ * literals, so they never reach here as a resolved address — and the host-level
+ * guard rejects non-IP, non-DNS hosts separately.
+ */
+export declare function isGlobalUnicastIp(addr: string): boolean;
+/**
+ * Reject hostnames that are obviously local even before DNS, and normalize a
+ * literal-IP host given in a non-canonical encoding (decimal `2130706433`, hex
+ * `0x7f000001`, dotted-hex/octal). Returns:
+ *   - { kind:'ip', addr } when the host is a literal IP (any encoding) → caller
+ *     validates `isGlobalUnicastIp(addr)` directly (no DNS).
+ *   - { kind:'name' } when it's a DNS name to resolve.
+ *   - { kind:'reject' } for `localhost` / `*.local` / unparseable.
+ */
+export declare function classifyHost(rawHost: string): {
+    kind: 'ip';
+    addr: string;
+} | {
+    kind: 'name';
+} | {
+    kind: 'reject';
+};

package/dist/orchestration-shell/web/sanitize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Strip terminal control / escape sequences from untrusted text, preserving
+ * only printable characters + deliberate whitespace (`\n`, `\t`, space, and CR
+ * which is normalized to `\n` by callers). Linear-time, single pass.
+ *
+ * Removed:
+ *   - CSI  `ESC [ … final`            (cursor/screen/SGR manipulation)
+ *   - OSC  `ESC ] … (BEL | ESC \)`    (e.g. OSC-52 clipboard, window title)
+ *   - DCS/SOS/PM/APC `ESC (P|X|^|_) … ST`
+ *   - two-char escapes `ESC <byte>`   (incl. a lone trailing ESC)
+ *   - C0 controls 0x00–0x1f EXCEPT \t (0x09) and \n (0x0a)  (CR 0x0d dropped — callers normalize EOL first)
+ *   - DEL 0x7f and C1 controls 0x80–0x9f (incl. 8-bit CSI 0x9b / OSC 0x9d)
+ */
+export declare function sanitizeForTerminal(input: string): string;

package/dist/orchestration-shell/web/search.d.ts

@@ -0,0 +1,16 @@
+export interface SearchResult {
+    url: string;
+    title: string;
+}
+/**
+ * Parse DDG HTML result anchors. DDG wraps targets as
+ * `//duckduckgo.com/l/?uddg=<encoded-target>&...`; we decode `uddg` to the real
+ * URL. Linear scan over anchor tags; tolerant of markup drift. Returns ≤limit
+ * http(s) results. NEVER throws.
+ */
+export declare function parseDdgResults(html: string, limit?: number): SearchResult[];
+/**
+ * Run a keyless web search. Returns ≤limit results, or [] on any failure
+ * (network/parse) — the caller decides the advisory. `signal` lets Esc abort.
+ */
+export declare function webSearch(query: string, signal?: AbortSignal, limit?: number): Promise<SearchResult[]>;

package/dist/planner/__tests__/local-gemma.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/planner/index.d.ts

@@ -3,3 +3,5 @@ export * from './adapter';
 export { PlannerCacheLayer } from './cache';
 export { PlannerHealthMachine } from './health-state';
 export { BackendPlannerClient, PlannerBudgetExceededError, PlannerTierGateRejectedError, type PlannerAppSyncTransport, type PlannerCryptoBridge, type SessionKeyResolver, type ShellEventEmit, type EmitShellEventFn, } from './client';
+export { LocalGemmaPlannerAdapter, parseLocalGemmaPlannerDecision, renderLocalGemmaPlannerPrompt, type LocalGemmaPlannerRunner, } from './local-gemma';
+export { parseLocalGemmaAdvisorySummary, renderLocalGemmaFamiliarizePrompt, type LocalGemmaAdvisoryRunner, } from './local-advisory';