@quantiya/codevibe-core 2.0.0 → 2.0.1

package/dist/orchestration-shell/cohort-flag.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Filesystem location of the cohort-flag file (`~/.codevibe/cohort-flags.json`).
+ * Exposed as a function so test code can monkey-patch via env override.
+ */
+export declare function cohortFlagFilePath(): string;
+/**
+ * Reads the named cohort flag for the given session/user. Returns
+ * `false` on every failure mode (file missing, malformed JSON, flag
+ * unset, non-boolean value). This is fail-closed by design — per §3
+ * H6 mitigation, the cohort gate MUST default off until Phase 4 flips
+ * the flag.
+ *
+ * `sessionId` is accepted in the signature for future per-session
+ * cohort overrides; CP-1.a ignores it.
+ */
+export declare function getCohortFlag(name: string, _sessionId: string): Promise<boolean>;

package/dist/orchestration-shell/components/CodeVibeLogo.d.ts

@@ -0,0 +1,2 @@
+import * as React from 'react';
+export declare function CodeVibeLogo(): React.ReactElement;

package/dist/orchestration-shell/components/ConversationPane.d.ts

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { ConversationEntry } from '../types';
+export interface ConversationPaneProps {
+    entries: ConversationEntry[];
+}
+export declare function renderConversationEntry(entry: ConversationEntry): React.ReactElement;
+export declare function ConversationPane(props: ConversationPaneProps): React.ReactElement;

package/dist/orchestration-shell/components/GatePromptEntry.d.ts

@@ -0,0 +1,9 @@
+import * as React from 'react';
+import { ConversationEntry } from '../types';
+export interface GatePromptEntryProps {
+    entry: Extract<ConversationEntry, {
+        kind: 'gate-prompt';
+    }>;
+}
+export declare function GatePromptEntry(props: GatePromptEntryProps): React.ReactElement;
+export default GatePromptEntry;

package/dist/orchestration-shell/components/InputBar.d.ts

@@ -0,0 +1,41 @@
+import * as React from 'react';
+/**
+ * Gate-prompt-aware input modes per PHASE-CP-8-MIN-DESIGN.md §7
+ * + #C8M-5. `maxOption: number` (NOT a `2 | 5` literal union) per
+ * #C8M-1 server-derived purity — the parent derives it from
+ * `envelope.options.length` at the active gate-prompt entry.
+ */
+export type GatePromptMode = {
+    kind: 'awaiting-number';
+    maxOption: number;
+} | {
+    kind: 'awaiting-notes';
+    decisionDraft: string;
+} | {
+    kind: 'submitting';
+} | null;
+/**
+ * Sentinel string emitted via `onSubmit` when the user types the exact
+ * literal `/cancel` (case-sensitive) in `awaiting-notes` mode. The parent
+ * (`<OrchestrationApp>`) MUST intercept this sentinel and dispatch
+ * `GATE_PROMPT_NOTES_CANCELLED` instead of treating the text as notes
+ * plaintext. Without this sentinel, `/cancel` would be submitted AS the
+ * notes string to `applyUserDecision`, destroying user intent
+ * (Stage 2 r2 Codex NEW-HIGH-1). Sentinel string is intentionally
+ * non-printable / non-collidable with any plausible notes content.
+ */
+export declare const GATE_PROMPT_NOTES_CANCEL_SENTINEL = "__GATE_PROMPT_NOTES_CANCEL__";
+export interface InputBarProps {
+    onSubmit: (text: string) => void;
+    /** Optional placeholder shown when value is empty. */
+    placeholder?: string;
+    /** Initial value (used for history recall). */
+    initialValue?: string;
+    /**
+     * CP-8 min Wave 1B. When non-null, restricts/disables input per the
+     * gate-prompt mode; when null, normal text-input behavior. See module
+     * docstring for the four states.
+     */
+    gatePromptMode?: GatePromptMode;
+}
+export declare function InputBar(props: InputBarProps): React.ReactElement;

package/dist/orchestration-shell/components/OrchestrationApp.d.ts

@@ -0,0 +1,63 @@
+import * as React from 'react';
+import { OrchestrationStore } from '../store';
+import { PostDecisionAction, Tier } from '../types';
+/**
+ * Minimal SDK contract for the applyUserDecision wire. Structurally
+ * compatible with the full `AppSyncClient.applyUserDecision` signature
+ * — keeps the orchestration shell decoupled from the heavier AppSync
+ * surface (tests can inject a stub).
+ */
+export interface ApplyUserDecisionClient {
+    applyUserDecision(input: {
+        gateId: string;
+        taskId: string;
+        sessionId: string;
+        currentRound: number;
+        decision: string;
+        notes?: string;
+    }, sessionKeyBase64?: string): Promise<{
+        decision: string;
+        postAction: PostDecisionAction;
+    }>;
+}
+export interface OrchestrationAppProps {
+    store: OrchestrationStore;
+    tier: Tier;
+    /** Hook called when `<InputBar>` submits text AND there is no active
+     * gate-prompt. The host wires this to the slash router / planner
+     * classifier. Gate-prompt submits are intercepted internally per
+     * #C8M-11 and never reach `onUserInput`. */
+    onUserInput: (text: string) => void;
+    /**
+     * CP-8 min Stage 1 R1 closure + Stage 2 r1 Codex HIGH-1 (REQUIRED). The
+     * desktop-side AppSync transport surface (codevibe-core's own
+     * AppSyncClient — see #C8M-6 deviation). Required so production gate
+     * submits cannot silently fail-closed at the SDK edge with "AppSync
+     * client not configured". The shell entry (`runOrchestrationShell`)
+     * always has an authenticated client by the
+     * `RunOrchestrationShellArgs` contract; tests inject a stub.
+     * Future omissions will fail TypeScript compile rather than break at
+     * runtime.
+     */
+    appsyncClient: ApplyUserDecisionClient;
+    /**
+     * Session-key resolver invoked just-in-time when a gate-prompt submit
+     * includes notes. Returns the base64 session key for the caller's
+     * session, or `null` if the session is not E2E-encrypted.
+     *
+     * Stage 2 r2 Codex NEW-HIGH-2: this prop is now REQUIRED (non-optional)
+     * because the underlying `AppSyncClient.applyUserDecision` enforces
+     * `sessionKeyBase64 !== undefined` whenever `notes` is supplied. Without
+     * the resolver, production Path B `_WITH_NOTES` submits throw at the
+     * SDK edge with "sessionKeyBase64 is required when notes are
+     * supplied" — masked by Tests 21/22 which stub the resolver. Production
+     * callers (`runOrchestrationShell`) bind this to
+     * `keychainManager.getSessionKey(sessionId)`. Tests inject a stub.
+     *
+     * If the resolver returns `null` AND `notes` are present, the submit
+     * handler dispatches `GATE_PROMPT_SUBMIT_FAILED` with a locked error
+     * message — it MUST NOT silently submit unencrypted notes.
+     */
+    getSessionKey: (sessionId: string) => Promise<string | null>;
+}
+export declare function OrchestrationApp(props: OrchestrationAppProps): React.ReactElement;

package/dist/orchestration-shell/components/StatusBar.d.ts

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { PlannerHealthState, Tier } from '../types';
+export interface StatusBarProps {
+    plannerHealth: PlannerHealthState;
+    tier: Tier;
+}
+export declare function StatusBar(props: StatusBarProps): React.ReactElement;

package/dist/orchestration-shell/components/nodes/AdvisoryEntry.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { ConversationEntry } from '../../types';
+export interface AdvisoryEntryProps {
+    entry: Extract<ConversationEntry, {
+        kind: 'advisory';
+    }>;
+}
+export declare function AdvisoryEntry(props: AdvisoryEntryProps): React.ReactElement;

package/dist/orchestration-shell/components/nodes/GateStatusNode.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { ConversationEntry } from '../../types';
+export interface GateStatusNodeProps {
+    entry: Extract<ConversationEntry, {
+        kind: 'gate-status-node';
+    }>;
+}
+export declare function GateStatusNode(props: GateStatusNodeProps): React.ReactElement;

package/dist/orchestration-shell/components/nodes/PlannerDecisionEntry.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { ConversationEntry } from '../../types';
+export interface PlannerDecisionEntryProps {
+    entry: Extract<ConversationEntry, {
+        kind: 'planner-decision';
+    }>;
+}
+export declare function PlannerDecisionEntry(props: PlannerDecisionEntryProps): React.ReactElement;

package/dist/orchestration-shell/components/nodes/ReviewerQuorumStatusNode.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { ConversationEntry } from '../../types';
+export interface ReviewerQuorumStatusNodeProps {
+    entry: Extract<ConversationEntry, {
+        kind: 'reviewer-status-node';
+    }>;
+}
+export declare function ReviewerQuorumStatusNode(props: ReviewerQuorumStatusNodeProps): React.ReactElement;

package/dist/orchestration-shell/components/nodes/SlashOutputEntry.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { ConversationEntry } from '../../types';
+export interface SlashOutputEntryProps {
+    entry: Extract<ConversationEntry, {
+        kind: 'slash-output';
+    }>;
+}
+export declare function SlashOutputEntry(props: SlashOutputEntryProps): React.ReactElement;

package/dist/orchestration-shell/components/nodes/SubagentEventEntry.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { ConversationEntry } from '../../types';
+export interface SubagentEventEntryProps {
+    entry: Extract<ConversationEntry, {
+        kind: 'subagent-event';
+    }>;
+}
+export declare function SubagentEventEntry(props: SubagentEventEntryProps): React.ReactElement;

package/dist/orchestration-shell/components/nodes/UserMessageEntry.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { ConversationEntry } from '../../types';
+export interface UserMessageEntryProps {
+    entry: Extract<ConversationEntry, {
+        kind: 'user-message';
+    }>;
+}
+export declare function UserMessageEntry(props: UserMessageEntryProps): React.ReactElement;

package/dist/orchestration-shell/emit-shell-event.d.ts

@@ -0,0 +1,64 @@
+import { AppSyncClient } from '../appsync';
+/**
+ * §3 LOCK lines 173-181. Names + per-type metadata shapes are part of
+ * the Stage A contract. CP-1.a ships the union; CP-1.b/c/d add call
+ * sites for each emit type.
+ */
+export type NewEventTypeKind = 'MODE_SELECTED' | 'PLANNER_DECISION' | 'PLANNER_CACHE_HIT' | 'PLANNER_DEGRADED' | 'PLANNER_OUTAGE' | 'PLANNER_RECOVERED' | 'SLASH_COMMAND_INVOKED' | 'STRUCTURAL_SUMMARY_GENERATED' | 'LOCAL_AUTHORITY_REFUSAL' | 'NOTIFICATION';
+/**
+ * §3 LOCK lines 160-170. ShellEventEmit contract.
+ *
+ * Per Stage 2 r1 Codex HIGH-2: `source` and `isEncrypted` MUST be
+ * present on every call. The Stage A LOCK on §3 fixes both: every CP-1
+ * shell event is DESKTOP-sourced and E2E-encrypted under the session
+ * key. Making them required (vs optional) prevents accidental plaintext
+ * fall-through if a caller forgets either field.
+ */
+export interface ShellEventEmit {
+    /** Current Session.sessionId; orchestration shell tracks this. */
+    sessionId: string;
+    /** One of the 9 new EventType enums (plus NOTIFICATION reuse). */
+    type: NewEventTypeKind;
+    /** Shell is desktop-side; mobile uses its own emit path. REQUIRED. */
+    source: 'DESKTOP';
+    /** Human-readable summary; encrypted under session key. */
+    content?: string;
+    /** Event-specific structured payload; encrypted; per-type shape per §3. */
+    metadata?: Record<string, unknown>;
+    /** All CP-1 shell events are E2E encrypted per existing pattern. REQUIRED. */
+    isEncrypted: true;
+    /** RFC3339; if omitted, server fills in via existing VTL. */
+    timestamp?: string;
+}
+/**
+ * Test seam — allows the unit tests to swap the AppSync client without
+ * mounting the full singleton. Production code calls
+ * `emitShellEvent(args)` which uses `getDefaultClient()`.
+ */
+export interface EmitShellEventDeps {
+    appsyncClient: Pick<AppSyncClient, 'createEvent'>;
+    getSessionKey: (sessionId: string) => Promise<string | null>;
+    getCohortFlag: (name: string, sessionId: string) => Promise<boolean>;
+}
+/**
+ * §3 LOCK lines 184-207. Single chokepoint enforcing the cohort-flag
+ * gate + encryption invariants for all 9 new EventTypes.
+ *
+ * When the cohort flag is off: log at debug and return without
+ * touching AppSync. When on: encrypt content + metadata under the
+ * session key, call `createEvent` via Pattern B Lambda resolver
+ * (existing surface, no schema change).
+ *
+ * `deps` is the test seam. Production callers omit it and the function
+ * resolves the default `keychainManager` + `cryptoService` references.
+ * The AppSync client is REQUIRED — there is no global default in
+ * codevibe-core (each plugin instantiates its own `AppSyncClient`).
+ */
+export declare function emitShellEvent(args: ShellEventEmit, deps: EmitShellEventDeps): Promise<void>;
+/**
+ * Convenience helper for production callers — binds default
+ * dependencies (`keychainManager` for session-key lookup,
+ * `getCohortFlag` for the flag read) and accepts the AppSync client
+ * separately because there's no global default in `codevibe-core`.
+ */
+export declare function createShellEventEmitter(appsyncClient: Pick<AppSyncClient, 'createEvent'>): (args: ShellEventEmit) => Promise<void>;

package/dist/orchestration-shell/gate-prompts.d.ts

@@ -0,0 +1,123 @@
+import { Event } from '../types/events';
+/**
+ * `metadata.prompt_kind` value for the 5-option Path B (Halted-resolution)
+ * gate prompt. Mirrors `METADATA_PROMPT_KIND` at `appsync_emit.rs:68`.
+ *
+ * Cross-impl literal parity is a load-bearing invariant — see Test 23
+ * (`hostile-grep.test.ts`).
+ */
+export declare const ORCHESTRATION_ESCALATED_GATE_PROMPT_KIND: "orchestration_escalated_gate";
+/**
+ * `metadata.prompt_kind` value for the 2-option Path A (FinalApproval)
+ * gate prompt. Mirrors `METADATA_PROMPT_KIND_FINAL_APPROVAL` at
+ * `appsync_emit.rs:297`.
+ */
+export declare const ORCHESTRATION_FINAL_APPROVAL_PROMPT_KIND: "orchestration_final_approval";
+/**
+ * Source-of-truth string literals for the hostile-grep cross-impl parity
+ * test (`__tests__/hostile-grep.test.ts`, Test 23). Mirrors the Rust
+ * emitter at
+ * `codevibe-core-rs/crates/codevibe-orchestration-lambda/src/appsync_emit.rs`
+ * lines 63 / 68 / 297 / 312-340 / 351-364.
+ *
+ * Do NOT remove or reorder — Test 23 greps this module for each literal
+ * verbatim. Drift here = silent cross-platform breakage:
+ *   - tool_name discriminator        → `metadata.tool_name`
+ *   - prompt_kind discriminators     → `metadata.prompt_kind`
+ *   - 5-tuple escalation option ids  → `metadata.payload.options[*].id`
+ *     (position-ordered: ACCEPT, ACCEPT_WITH_NOTES, REJECT_WITH_NOTES,
+ *      REJECT_RESTART, ABORT_TASK)
+ *   - 2-tuple final-approval ids     → `metadata.payload.options[*].id`
+ *     (position-ordered: APPROVE, CANCEL)
+ *
+ * NB: the option ids themselves are NEVER referenced as TS string
+ * constants at runtime — the renderer + mapper read them from the wire
+ * per #C8M-1. This block exists purely as a hostile-grep anchor so any
+ * Rust-side reordering or rename trips the parity test on the TS side
+ * as well.
+ */
+export declare const SOURCE_OF_TRUTH_LITERALS: {
+    readonly toolName: "OrchestrationGate";
+    readonly escalatedPromptKind: "orchestration_escalated_gate";
+    readonly finalApprovalPromptKind: "orchestration_final_approval";
+    readonly escalationOptionIds: readonly ["ACCEPT", "ACCEPT_WITH_NOTES", "REJECT_WITH_NOTES", "REJECT_RESTART", "ABORT_TASK"];
+    readonly finalApprovalOptionIds: readonly ["APPROVE", "CANCEL"];
+};
+/**
+ * Discriminated union over the two prompt kinds CP-8 min routes through
+ * the gate-prompt path. Anything outside this union flows to the
+ * existing `subagent-event` / `mobile-event-replay` path per #C8M-3.
+ */
+export type GatePromptKind = typeof ORCHESTRATION_ESCALATED_GATE_PROMPT_KIND | typeof ORCHESTRATION_FINAL_APPROVAL_PROMPT_KIND;
+/**
+ * One option entry on the wire — matches the Rust struct projected by
+ * `build_escalation_options()` / `build_final_approval_options()`.
+ */
+export interface GatePromptOption {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+}
+/**
+ * Locked design §4 #C8M-9. The plaintext-parsed envelope the
+ * dispatcher hands to the reducer via `GATE_PROMPT_RECEIVED`. Captures
+ * everything the renderer + submit path need; no other field is read
+ * from `event.metadata` after extraction.
+ *
+ * Field provenance (Rust `appsync_emit.rs::build_metadata_json` lines
+ * 1459-1493):
+ *   - `promptKind`         from `metadata.prompt_kind`
+ *   - `taskId` / `gateId`  from `metadata.payload.outcome.{taskId,gateId}`
+ *   - `currentRound`       from `metadata.payload.outcome.round`
+ *   - `options`            from `metadata.payload.options` (5 or 2 entries)
+ *   - `reason`             from `metadata.payload.outcome.reason` (Path B only)
+ *   - `summary`            from `metadata.summary`
+ *   - `receivedAt`         from `event.timestamp` (server-set; ISO 8601)
+ */
+export interface GatePromptEnvelope {
+    readonly promptKind: GatePromptKind;
+    readonly taskId: string;
+    readonly gateId: string;
+    readonly currentRound: number;
+    readonly options: ReadonlyArray<GatePromptOption>;
+    readonly reason?: string;
+    readonly summary?: string;
+    readonly receivedAt: string;
+}
+/**
+ * Defensive validator (per #C8M-1 + #C8M-2). Returns `null` on ANY of:
+ *   - event is not an INTERACTIVE_PROMPT
+ *   - metadata absent / un-parseable
+ *   - `prompt_kind` not one of the two orchestration discriminators
+ *   - `payload.options` not an array, OR wrong length
+ *     (5 for escalation, 2 for final-approval)
+ *   - any entry missing `id` / `label` / `description` or with non-string
+ *     `id`
+ *   - `outcome.{taskId,gateId,round}` missing or wrong type
+ *
+ * The caller (dispatcher in `index.ts`) is responsible for emitting the
+ * `kind: 'advisory'` ConversationEntry on null-return per #C8M-1.
+ */
+export declare function extractGatePromptEnvelope(event: Event): GatePromptEnvelope | null;
+/**
+ * Per #C8M-1: typed_number N (1-based) → `lowercase(envelope.options[N-1].id)`.
+ * Result is the `decision` value the caller passes to
+ * `sdk.applyUserDecision({ decision, ... })`. The SDK uppercases via
+ * `toWireEnum` before AppSync wire-send (see `client.ts:244-246`).
+ *
+ * Returns `null` for ANY of:
+ *   - `n` is not an integer (NaN, fractional, non-number)
+ *   - `n < 1` or `n > envelope.options.length`
+ *
+ * `needsNotes` is `true` iff the resolved kind ends with `_with_notes`,
+ * driving the InputBar transition to the notes-entry sub-prompt per
+ * #C8M-5. For Path A's APPROVE / CANCEL, `needsNotes` is always false.
+ *
+ * The caller MUST treat `null` as a typo / out-of-range and reject the
+ * submit — silent fallback to a default kind would destroy or accept
+ * the user's work without consent (matches the v1-options rule).
+ */
+export declare function mapTypedNumberToDecisionKind(envelope: GatePromptEnvelope, n: number): {
+    kind: string;
+    needsNotes: boolean;
+} | null;

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

@@ -0,0 +1,100 @@
+import { AppSyncClient } from '../appsync';
+import { Session } from '../types';
+import { OrchestrationStore } from './store';
+import { createShellEventEmitter } from './emit-shell-event';
+import { Tier } from './types';
+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';
+export interface RunOrchestrationShellArgs {
+    /** Authenticated AppSync client (caller is responsible for `authenticateWithStoredTokens`). */
+    appsyncClient: AppSyncClient;
+    /** Resolved session (caller ran `resumeOrCreateSession` already). */
+    session: Session;
+    /** Current tier — used by the StatusBar + downstream tier gating. */
+    tier: Tier;
+    /**
+     * CP-1.b IMPL r2 H-3 — Optional planner adapter. When supplied,
+     * `runOrchestrationShell` binds the active session via
+     * `plannerAdapter.setActiveSession(sessionId)` immediately after
+     * startup, and clears it on session teardown. The
+     * `PlannerAdapter.probe()` contract (CP-1.b §4.10) reads the
+     * session from this binding. CP-1.a callers may omit; CP-1.b+
+     * wires the real `BackendPlannerClient`.
+     */
+    plannerAdapter?: PlannerAdapter;
+    /**
+     * CP-1.b IMPL r2 M-3 — Optional planner cache layer. With LOCK #18
+     * write-through removed, normal session exit (no LRU eviction, no
+     * TTL deletion) would lose pending in-memory inserts. When
+     * supplied, `runOrchestrationShell` calls `cache.flush()` from
+     * every teardown path (`/quit`, non-TTY EOF, SIGINT/SIGTERM,
+     * finally-block cleanup).
+     */
+    plannerCache?: PlannerCacheLayer;
+}
+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 { routeSlashCommand, applySlashOutput, type SlashOutput, type ShellAction, } from './slash-router';
+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';
+/**
+ * §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>;
+/**
+ * Higher-level entrypoint used by the `cli.ts` glue. CP-1.a ships the
+ * basic argv parse — full plumbing (session resume, AppSync client
+ * bootstrap, tier read) lands when CP-1.b/c hooks the rest of the
+ * sub-phases.
+ */
+export interface RunOrchestrationCliArgs {
+    argv: string[];
+    /** Test seam — runOrchestrationShell injected for unit tests. */
+    runOrchestrationShellFn?: typeof runOrchestrationShell;
+    /** Test seam — invoked when CP-1.a needs Companion Mode handoff (§4). */
+    runCompanionModeFn?: (args: {
+        agent?: string;
+        passthrough: string[];
+    }) => Promise<void>;
+}
+interface StructuralSummaryRunDeps {
+    store: OrchestrationStore;
+    args: RunOrchestrationShellArgs;
+    emitShellEventBound: ReturnType<typeof createShellEventEmitter>;
+    generator: StructuralSummaryGenerator;
+}
+/**
+ * Test seam — accepts an injected `addBodyPath` so unit tests can drive
+ * the dispatch logic without touching the filesystem. Production callers
+ * use the default which imports the real one from `../structural-summary`.
+ */
+export interface HandleShellUserInputDeps extends StructuralSummaryRunDeps {
+    text: string;
+    /** Test seam — defaults to the real `addBodyPath`. */
+    addBodyPathFn?: (path: string, tier: Tier) => Promise<unknown>;
+    /** Test seam — defaults to the real `regenerateStructuralSummary`. */
+    regenerateStructuralSummaryFn?: (deps: StructuralSummaryRunDeps) => Promise<void>;
+    /**
+     * CP-1.b IMPL r4 H-1 — Optional override for the natural-language
+     * classify dispatch. Defaults to `args.plannerAdapter?.classify`. Tests
+     * may inject a stub to drive the conversion to PLANNER_DECISION
+     * without spinning up the BackendPlannerClient.
+     */
+    classifyFn?: (input: PlannerInput) => Promise<PlannerDecisionRuntime>;
+}
+/**
+ * Slash + natural-language dispatch. Extracted from `runOrchestrationShell`
+ * so unit tests can drive the §4.8 wiring (REGENERATE / OPT_IN_BODY_PATH
+ * / default `/structural-summary` placeholder rewrite) without spinning
+ * up the full TUI. Behaves identically to the inline closure in
+ * `runOrchestrationShell`.
+ */
+export declare function handleShellUserInput(deps: HandleShellUserInputDeps): Promise<void>;

package/dist/orchestration-shell/ink-runtime.d.ts

@@ -0,0 +1,64 @@
+interface InkExports {
+    Box: any;
+    Text: any;
+    Static: any;
+    render: (tree: any) => {
+        waitUntilExit(): Promise<void>;
+        unmount(): void;
+    };
+    useApp: () => {
+        exit: (err?: Error) => void;
+    };
+    useInput: (handler: (input: string, key: any) => void) => void;
+    useStdin: () => {
+        stdin: any;
+        setRawMode: (raw: boolean) => void;
+        isRawModeSupported: boolean;
+    };
+}
+interface InkTextInputExports {
+    default: any;
+}
+interface InkSpinnerExports {
+    default: any;
+}
+interface InkSelectInputExports {
+    default: any;
+}
+interface GradientStringExports {
+    default: (colors: string[] | string) => (s: string) => string;
+}
+interface InkRuntime {
+    ink: InkExports;
+    inkTextInput: InkTextInputExports;
+    inkSpinner: InkSpinnerExports;
+    inkSelectInput: InkSelectInputExports;
+    gradientString: GradientStringExports;
+}
+/**
+ * Test seam — replace the ESM loader (e.g., for Vitest, which gets
+ * the dynamic-import error via the VM).
+ */
+export declare function __setEsmLoaderForTest(loader: <T>(name: string) => Promise<T>): void;
+/**
+ * Resets the ESM loader to the production default.
+ */
+export declare function __resetEsmLoaderForTest(): void;
+/**
+ * Loads the ESM-only ink packages. Idempotent — second call returns
+ * the cached runtime. Throws if any package fails to load.
+ */
+export declare function initInkRuntime(): Promise<InkRuntime>;
+/**
+ * Synchronous accessor. Components call this AFTER the entrypoint
+ * `await initInkRuntime()` succeeds. Throws if ink isn't loaded — that
+ * indicates a programming error in the entrypoint sequencing.
+ */
+export declare function getInkRuntime(): InkRuntime;
+/**
+ * Test seam — lets the unit tests inject a fake runtime so component
+ * tests can render without launching real terminals. Production code
+ * never calls this.
+ */
+export declare function __setInkRuntimeForTest(rt: InkRuntime | null): void;
+export {};

package/dist/orchestration-shell/mode-selection.d.ts

@@ -0,0 +1,46 @@
+import { Mode, Tier } from './types';
+/**
+ * Thrown when a Free-tier user explicitly requests `--mode orchestration`.
+ * Per §2 + §16 LOCK #1: Orchestration Mode is Pro/Max-gated; Free-tier
+ * users hit this error with the upgrade URL.
+ */
+export declare class TierError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parsed arguments the entrypoint hands to `pickMode`. Either flag is
+ * optional; a value of `undefined` means "not specified".
+ */
+export interface ParsedModeArgs {
+    /** `--mode companion` | `--mode orchestration` | undefined */
+    mode?: Mode;
+}
+/**
+ * Test seam — lets the unit tests inject a deterministic prompt
+ * callback instead of opening a real TTY.
+ */
+export interface ModeSelectionDeps {
+    readStickyPreference: (tier: Tier) => Promise<Mode | null>;
+    writeStickyPreference: (args: {
+        mode: Mode;
+        pickedByTier: 'PRO' | 'MAX';
+    }) => Promise<void>;
+    promptUserForMode: (tier: 'PRO' | 'MAX') => Promise<Mode>;
+}
+/**
+ * §2 LOCK lines 80-99. Pure decision function — only filesystem I/O is
+ * the sticky-preference read via `deps.readStickyPreference`.
+ *
+ * Rules:
+ *   1. Free-tier + `--mode orchestration` → `TierError` with upgrade URL.
+ *   2. Explicit `--mode` flag → honor it.
+ *   3. Free-tier (no flag) → 'companion'.
+ *   4. Pro/Max (no flag) + sticky present → sticky mode.
+ *   5. Pro/Max (no flag) + no sticky → prompt user; write sticky after pick.
+ */
+export declare function pickMode(args: ParsedModeArgs, tier: Tier, deps?: ModeSelectionDeps): Promise<Mode>;
+/**
+ * Default deps wiring — production callers can omit `deps` from
+ * `pickMode()` and get this. Tests override via the optional 3rd arg.
+ */
+export declare function defaultDeps(): ModeSelectionDeps;