@adhdev/daemon-core 0.9.82-rc.44 → 0.9.82-rc.441

package/dist/providers/sdk/v1/types/common/index.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Shared types across provider categories.
+ *
+ * Extracted at build time into the Apache 2.0 npm package
+ * `@adhdev/provider-types`. External provider authors import from there;
+ * daemon-core imports from this file directly.
+ */
+export interface BooleanSettingDef {
+    type: 'boolean';
+    default: boolean;
+    public?: boolean;
+    label?: string;
+    description?: string;
+}
+export interface NumberSettingDef {
+    type: 'number';
+    default: number;
+    public?: boolean;
+    label?: string;
+    description?: string;
+    min?: number;
+    max?: number;
+}
+export interface StringSettingDef {
+    type: 'string';
+    default: string;
+    public?: boolean;
+    label?: string;
+    description?: string;
+}
+export interface SelectSettingDef {
+    type: 'select';
+    default: string;
+    options: ReadonlyArray<string | {
+        value: string;
+        label?: string;
+    }>;
+    public?: boolean;
+    label?: string;
+    description?: string;
+}
+export type SettingDef = BooleanSettingDef | NumberSettingDef | StringSettingDef | SelectSettingDef;
+export type SettingsDef = Readonly<Record<string, SettingDef>>;
+export interface CapabilityInputDef {
+    multipart?: boolean;
+    mediaTypes?: ReadonlyArray<'text' | 'image' | 'audio' | string>;
+    strategies?: ReadonlyArray<{
+        mediaType: string;
+        strategies: ReadonlyArray<string>;
+        native?: boolean;
+        degradation?: ReadonlyArray<string>;
+    }>;
+}
+export interface CapabilityOutputDef {
+    richContent?: boolean;
+    mediaTypes?: ReadonlyArray<string>;
+}
+export interface CapabilityControlsDef {
+    typedResults?: boolean;
+}
+export interface CapabilitiesDef {
+    input?: CapabilityInputDef;
+    output?: CapabilityOutputDef;
+    controls?: CapabilityControlsDef;
+}
+export interface EnvVarAuthDef {
+    type: 'env_var';
+    id: string;
+    name: string;
+    vars: ReadonlyArray<{
+        name: string;
+        description?: string;
+    }>;
+    link?: string;
+}
+export interface CliCommandAuthDef {
+    type: 'cli_command';
+    id: string;
+    name: string;
+    command: string;
+    link?: string;
+}
+export type AuthDef = EnvVarAuthDef | CliCommandAuthDef;
+export interface SpawnDef {
+    command: string;
+    args?: ReadonlyArray<string>;
+    shell?: boolean;
+    env?: Readonly<Record<string, string>>;
+}
+export interface TimeoutsDef {
+    /** Gap between writes before considering a chunk settled (ms). */
+    ptyFlush?: number;
+    /** Delay before sending an approval key (ms). */
+    dialogAccept?: number;
+    /** Window during which a freshly resolved modal is suppressed (ms). */
+    approvalCooldown?: number;
+    /** Fallback "still generating" assumption window (ms). */
+    generatingIdle?: number;
+    /** Grace before declaring generating→idle final (ms). */
+    idleFinish?: number;
+    /** Second-pass confirmation window (ms). */
+    idleFinishConfirm?: number;
+    /** PTY-quiet threshold before marking activity ended (ms). */
+    statusActivityHold?: number;
+    /** Hard upper bound on a single generation (ms). */
+    maxResponse?: number;
+    /** SIGTERM→SIGKILL window (ms). */
+    shutdownGrace?: number;
+    /** Post-write debounce (ms). */
+    outputSettle?: number;
+}
+export type StopStrategy = 'command' | 'ctrl_c' | 'signal';
+export type SessionIdFormat = 'uuid' | 'free' | 'string';
+export interface ResumeDef {
+    supported: boolean;
+    stopStrategy?: StopStrategy;
+    stopCommand?: string;
+    shutdownGraceMs?: number;
+    sessionIdFormat?: SessionIdFormat;
+    /** Args appended to spawn.args when starting a session under a daemon-issued id. `{{id}}` is replaced at launch. */
+    newSessionArgs?: ReadonlyArray<string>;
+    /** Args appended when resuming a specific session id. */
+    resumeSessionArgs?: ReadonlyArray<string>;
+    /** Args appended when "continue most recent" semantics are wanted. */
+    resumeArgs?: ReadonlyArray<string>;
+}
+export interface McpConfigDef {
+    mode: 'manual' | 'auto_import';
+    format?: string;
+    path?: string;
+    configPathCommand?: string;
+    serverName?: string;
+    requiresRestart?: boolean;
+    instructions?: string;
+    /** Template string used by daemon to render the actual config snippet at install time. */
+    template?: string;
+}
+export interface MeshCoordinatorDef {
+    supported: boolean;
+    mcpConfig?: McpConfigDef;
+    systemPromptInjection?: MeshCoordinatorSystemPromptInjectionDef;
+    delegatedWorkerIsolation?: MeshCoordinatorDelegatedWorkerIsolationDef;
+}
+export type MeshCoordinatorSystemPromptInjectionDef = {
+    mode: 'cli_arg';
+    flag: string;
+} | {
+    mode: 'config_override';
+    flag: string;
+    template: string;
+} | {
+    mode: 'context_file';
+    path: string;
+    wrapper?: string;
+} | {
+    mode: 'env_var';
+    name: string;
+};
+export interface MeshCoordinatorDelegatedWorkerIsolationDef {
+    env?: {
+        unset?: ReadonlyArray<string>;
+    };
+    args?: ReadonlyArray<MeshCoordinatorDelegatedWorkerArgRuleDef>;
+}
+export type MeshCoordinatorDelegatedWorkerArgRuleDef = {
+    mode: 'empty_mcp_config';
+    flag: string;
+    strictFlag?: string;
+} | {
+    mode: 'config_override';
+    flag: string;
+    key: string;
+    value: string;
+    dedupeKey?: string;
+};
+export interface CompatibilityEntryDef {
+    /** SemVer range against the agent's own version. Optional. */
+    ideVersion?: string;
+    /** Script subdirectory to load when this entry matches. e.g. "scripts/1.0". */
+    scriptDir: string;
+}
+export type ControlType = 'select' | 'action' | 'toggle';
+export interface ControlDef {
+    id: string;
+    type: ControlType;
+    label: string;
+    icon?: string;
+    placement?: string;
+    order?: number;
+    dynamic?: boolean;
+    hidden?: boolean;
+    options?: ReadonlyArray<unknown>;
+    listScript?: string;
+    setScript?: string;
+    invokeScript?: string;
+    readFrom?: string;
+    resultDisplay?: string;
+    defaultValue?: unknown;
+    confirmTitle?: string;
+    confirmMessage?: string;
+    confirmLabel?: string;
+}
+export type ProviderLifecycleStatus = 'Stable' | 'Beta' | 'Experimental' | 'Deprecated';

package/dist/providers/sdk/v1/validators/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Validators — public surface.
+ */
+export { analyzeOverrideTaint, formatTaintResult, type TaintLevel, type TaintCategory, type TaintFinding, type TaintResult, } from './taint.js';
+export { validateCliProviderManifest, formatManifestValidationIssues, type ManifestValidationIssue, type ManifestValidationResult, } from './manifest.js';

package/dist/providers/sdk/v1/validators/manifest.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Manifest validators — runtime JSON Schema check for v1 provider manifests.
+ *
+ * The schemas live under `schemas/{category}/provider.schema.json` and are
+ * the authoritative contract for what a v1 manifest may contain. Daemon
+ * code that loads a manifest at install or boot time runs it through
+ * `validateCliProviderManifest()` first; failures are reported back to
+ * the caller with structured paths so manifest authors can locate the
+ * offending field without guessing.
+ *
+ * Validation lives in the SDK layer (not in provider-loader) so dashboards,
+ * registry workers, and the provider publish flow can all reuse the
+ * same code path and produce identical error messages.
+ */
+export interface ManifestValidationIssue {
+    /** JSON Pointer-style path into the manifest. Empty string for the root. */
+    path: string;
+    /** Schema-keyword that failed. */
+    keyword: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Allowed values when the failure is an `enum` / `const` / `additionalProperties`. */
+    allowed?: unknown;
+}
+export interface ManifestValidationResult {
+    ok: boolean;
+    issues: ManifestValidationIssue[];
+}
+/**
+ * Validate a CLI provider.v1.json manifest. Returns `{ ok: true, issues: [] }`
+ * on success and `{ ok: false, issues: [...] }` on failure with each issue
+ * pointing at the offending field. Never throws — manifest parse errors
+ * should be caught by the caller before this is called.
+ */
+export declare function validateCliProviderManifest(manifest: unknown): ManifestValidationResult;
+/**
+ * Render a list of validation issues as a single multi-line string,
+ * suitable for log lines or daemon command error fields.
+ */
+export declare function formatManifestValidationIssues(issues: ManifestValidationIssue[]): string;

package/dist/providers/sdk/v1/validators/taint.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Static taint analyzer for extended-tier override JS.
+ *
+ * Goal: classify the override JS shipped with an extended-tier provider into
+ * one of three risk tiers, so the dashboard + daemon trust prompt can
+ * surface accurate language to the operator instead of a single generic
+ * "this provider contains JS" warning.
+ *
+ *   - clean    : no flagged APIs at all. The override looks like pure string
+ *                manipulation. Still extended-tier, but the warning copy is
+ *                "this provider contains JS; nothing dangerous was detected".
+ *   - elevated : touches process / dynamic codegen / dynamic require / eval
+ *                / Function constructor / child_process. The warning copy is
+ *                explicit ("this provider can run shell commands / dynamically
+ *                load code").
+ *   - hostile  : combines elevated APIs with network egress, AND uses obvious
+ *                obfuscation (base64-decoded strings fed into Function / eval).
+ *                The publish endpoint should reject these.
+ *
+ * Implementation note: this is a *static* analyzer — string + light AST scan
+ * via Node's built-in parser. It is intentionally fail-loud: anything that
+ * looks suspicious is flagged. False positives are fine; this exists to gate
+ * the trust prompt, not to be a real sandbox. The real sandbox lives in
+ * Phase 5 (isolated-vm).
+ *
+ * Used by:
+ *   - `adhdev provider validate` (CLI tier classification)
+ *   - registry publish endpoint static-check
+ *   - daemon at provider-load time, to size the warning
+ */
+export type TaintLevel = 'clean' | 'elevated' | 'hostile';
+export interface TaintFinding {
+    /** What was found, e.g. "child_process.exec". */
+    api: string;
+    /** Coarse category. */
+    category: TaintCategory;
+    /** File the finding came from. */
+    file: string;
+    /** Line number (1-indexed) of the first character of the matched token. */
+    line: number;
+    /** The surrounding source excerpt, trimmed. */
+    excerpt: string;
+}
+export type TaintCategory = 'process-control' | 'shell-exec' | 'fs-write' | 'fs-read' | 'network' | 'dynamic-codegen' | 'dynamic-require' | 'obfuscation' | 'global-mutation';
+export interface TaintResult {
+    level: TaintLevel;
+    findings: TaintFinding[];
+    files: string[];
+}
+export declare function analyzeOverrideTaint(manifestPath: string): TaintResult;
+/** Format a result as a single CLI-friendly block. */
+export declare function formatTaintResult(result: TaintResult): string;

package/dist/providers/spec/adapter.d.ts

@@ -0,0 +1,91 @@
+import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+export type { PtyTransportFactory };
+export interface TerminalAdapterOpts {
+    binary: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    /**
+     * When true, `env` is already a COMPLETE, sanitized environment (the spawn
+     * planner merged + stripped process.env already) and must be passed to the
+     * PTY verbatim — NOT overlaid on top of process.env. Overlaying would
+     * re-introduce the npm_/PNPM_/parent-session keys the planner explicitly
+     * stripped, so the spec path's spawn env would diverge from the legacy
+     * path's. Defaults to false (legacy overlay behaviour) for any caller that
+     * still passes a partial env.
+     */
+    envIsComplete?: boolean;
+    cols?: number;
+    rows?: number;
+    /** Coalesce screen snapshots: emit on_screen_changed at most this often. */
+    screenChangeDebounceMs?: number;
+    tickIntervalMs?: number;
+    transportFactory?: PtyTransportFactory;
+}
+export interface TerminalAdapterHandlers {
+    init?(info: {
+        pid: number;
+    }): void;
+    on_pty_data?(chunk: string): void;
+    on_screen_changed?(snapshot: string): void;
+    on_exit?(info: {
+        exitCode: number;
+    }): void;
+    tick?(): void;
+}
+/**
+ * One entry in the PTY input/output event timeline (debug-only). Captured at
+ * the single common point every spec@4 provider funnels through — this adapter
+ * — so the Spec Debug Snapshot can answer "what input / output preceded a status
+ * transition?". Observation only; nothing here feeds the FSM decision.
+ */
+export interface SpecPtyEvent {
+    /** Wall-clock ms. */
+    ts: number;
+    kind: 'spawn' | 'input' | 'output' | 'resize' | 'cursor' | 'exit';
+    /** Human-readable, control-char-escaped, length-capped preview. */
+    content: string;
+    /** Raw byte length before truncation (output/input only). */
+    bytes?: number;
+}
+export declare class TerminalAdapter {
+    private readonly opts;
+    private readonly handlers;
+    private rows;
+    private cols;
+    private readonly screenDebounceMs;
+    private readonly tickIntervalMs;
+    private readonly factory;
+    private screen;
+    private pty;
+    private screenTimer;
+    private tickTimer;
+    private lastScreen;
+    /** Debug-only ring buffer of PTY input/output/resize/cursor events. */
+    private events;
+    private lastCursorKey;
+    constructor(opts: TerminalAdapterOpts, handlers: TerminalAdapterHandlers);
+    start(): void;
+    resize(cols: number, rows: number): void;
+    snapshot(): string;
+    /**
+     * Full-buffer snapshot including scrollback history. Unlike snapshot()
+     * (visible viewport only), this survives a tall prompt whose top has
+     * scrolled off-screen — used for content-pattern extraction (modal
+     * buttons / approval anchors), NOT for cursor-relative conditions.
+     */
+    snapshotWithScrollback(): string;
+    getCursorPosition(): {
+        row: number;
+        col: number;
+    };
+    send_keys(text: string): void;
+    /** Debug-only: most-recent PTY input/output/resize/cursor events, oldest
+     *  first. Pure observation — never consulted by the FSM. */
+    getEventTimeline(limit?: number): SpecPtyEvent[];
+    private recordEvent;
+    kill(): void;
+    private onChunk;
+    private computeScreen;
+    private stopTimers;
+}

package/dist/providers/spec/cli-adapter.d.ts

@@ -0,0 +1,223 @@
+import type { CliAdapter, CliAdapterStatus } from '../../cli-adapter-types.js';
+import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+import { type InteractivePromptResponse } from '../types/interactive-prompt.js';
+export declare class SpecCliAdapter implements CliAdapter {
+    readonly cliType: string;
+    readonly cliName: string;
+    readonly workingDir: string;
+    /**
+     * Marker the daemon's finalization gate checks: `getStatus()` returns
+     * `messages: []` by design here (chat history lives in the daemon's
+     * native-history pipeline, not the adapter). Without this flag,
+     * cli-provider-instance's `missing_final_assistant` gate would stall
+     * every turn until the 30s safety timeout because it expects the
+     * adapter to surface the final assistant message.
+     */
+    readonly chatMessagesOwnedExternally: true;
+    private driver;
+    /** Common spec fields the adapter reads, present in both v3 and v4. */
+    private spec;
+    private lastEvent;
+    private latestState;
+    private latestModal;
+    private statusCallback;
+    private ptyDataCallback;
+    private partialResponse;
+    private activeInteractivePrompt;
+    private interactivePromptTransport;
+    private claudeTuiPromptCaptureInFlight;
+    /**
+     * Wall clock of the first frame on which a held interactive prompt was
+     * observed to have left the screen. Mirrors the approval FSM's
+     * `modalLostAt` hysteresis (see cli-state-engine.ts): claude-cli's TUI
+     * repaints the choice picker as several PTY chunks, so a single frame
+     * with no "Enter to select" footer is not proof the prompt is gone — it
+     * may just be mid-repaint. We only clear the held prompt once it has
+     * been absent across a short grace window. Reset to null the moment the
+     * prompt footer reappears.
+     *
+     * Without this, a choice prompt resolved *directly in the terminal* (the
+     * user picked an option without going through ADHDev's
+     * setInteractivePromptResponse) was never cleared from
+     * `activeInteractivePrompt`, so getStatus() re-emitted the same prompt
+     * forever — the choice-resolve-stuck bug.
+     */
+    private interactivePromptLostAt;
+    private jsonLineTail;
+    private exited;
+    private spawned;
+    private providerSessionId;
+    /** Wall clock at the moment spawn() ran. Used as the cutoff for
+     *  native-history file selection so a prior session's transcript
+     *  can't leak into this session before the agent has written its
+     *  own records. */
+    private spawnedAtMs;
+    /** Env vars the daemon set on the spawned child. Mesh coordinator
+     *  points hermes at a per-coordinator HERMES_HOME so the dashboard's
+     *  native-history reader needs that override to find the right
+     *  state.db; without it the reader sees ~/.hermes/state.db which
+     *  the coordinator-launched hermes never writes to. The choice to
+     *  redirect HERMES_HOME is a workaround for an unresolved hermes
+     *  upstream feature gap (see hermes-agent#23130 — runtime-supplied
+     *  MCP config), so this routing keeps the dashboard honest until
+     *  hermes ships a runtime MCP override. */
+    private spawnedEnv;
+    constructor(specPath: string, workingDir: string, cliArgs: string[], extraEnv: Record<string, string>, transportFactory?: PtyTransportFactory);
+    spawn(): Promise<void>;
+    sendMessage(text: string): Promise<void>;
+    getStatus(): CliAdapterStatus;
+    private maybeRefreshNativeHistory;
+    getScriptParsedStatus(): unknown;
+    getPartialResponse(): string;
+    shutdown(): void;
+    cancel(): void;
+    isProcessing(): boolean;
+    isReady(): boolean;
+    setOnStatusChange(cb: () => void): void;
+    setOnPtyData(cb: (data: string) => void): void;
+    writeRaw(data: string): void;
+    resize(cols: number, rows: number): void;
+    resolveModal(buttonIndex: number): void;
+    resolveAction(data: unknown): Promise<void>;
+    setInteractivePromptResponse(response: InteractivePromptResponse): Promise<void>;
+    isApprovalRecentlyResolved(): boolean;
+    clearHistory(): void;
+    updateRuntimeSettings(): void;
+    setServerConn(): void;
+    /**
+     * Map an invokeScript(name, args) call onto a control_bar entry.
+     *
+     * scriptName is matched against control.id. The control's action.type
+     * drives the dispatch:
+     *
+     *   send_keys     → click_control                   (e.g. stop)
+     *   open_picker   → two roles, driven by the screen, not a hardcoded list:
+     *                   - LIST  (no choice arg): open the picker, wait for it
+     *                     to render, parse the on-screen options via
+     *                     `extract_choices`, and return them as
+     *                     `controlResult.options` (+ `currentValue`). This is
+     *                     how the dashboard's Model/Mode controls learn what is
+     *                     actually selectable in this CLI right now.
+     *                   - SELECT (args.choiceIndex / args.choiceLabel): drive
+     *                     the picker to that option using `submit_key`.
+     *   attach_image  → attach_image dispatch; expects args.blob (data url
+     *                   or base64) and args.mime
+     *
+     * Callers that pass an unknown control id get a { not_found } response.
+     * No control matched, no driver call — keeps the surface honest.
+     */
+    invokeScript(scriptName: string, args?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Open an `open_picker` control and return the options the CLI is showing,
+     * parsed live from the screen via `extract_choices`. Nothing is selected —
+     * the picker is left open so a follow-up SELECT invoke can commit a choice.
+     */
+    private openPickerAndListChoices;
+    /**
+     * Drive an already-listable picker to a specific option. The option can be
+     * named (choiceLabel — matched against the parsed on-screen labels) or
+     * positional (choiceIndex — the on-screen number). The actual keystrokes
+     * come from the spec's `submit_key` with `{index}` substituted, so the spec
+     * — not this code — decides how a selection is keyed for each CLI.
+     */
+    private selectPickerChoice;
+    /** Parse the picker choices only if the picker already appears rendered on
+     *  the live screen (its `wait_for` condition currently matches and at least
+     *  one choice parses). Returns the parsed choices when open, else null so
+     *  the caller knows it must send the trigger to open it. Used to de-dup the
+     *  picker open in {@link selectPickerChoice}. */
+    private extractPickerChoicesIfRendered;
+    /** Poll the live screen until the picker's `wait_for` condition matches,
+     *  up to a short budget. Returns true if it rendered, false on timeout. */
+    private waitForPickerRendered;
+    /** Parse the picker's `extract_choices` pattern against the live screen.
+     *  Each match yields { index, label, current }. `current` is true for the
+     *  line the CLI marks with its cursor glyph (❯ ›). Purely screen-driven —
+     *  no model/mode names are baked in. */
+    private extractPickerChoices;
+    /** Live text of a named screen section (or the whole screen when no
+     *  section is named), resolved from the driver's current sections. */
+    private readScreenSectionText;
+    getDebugSnapshot(): unknown;
+    getRuntimeMetadata(): unknown;
+    updateRuntimeMeta(meta?: Record<string, unknown>): void;
+    refreshProviderDefinition(): void;
+    private handleEvent;
+    private detectInteractivePromptFromPtyChunk;
+    private readCurrentScreenSections;
+    private extractProviderSessionIdFromScreen;
+    private readClaudeScreenAssistantMessages;
+    /**
+     * Grace window a held interactive prompt must be absent from the screen
+     * before we treat it as resolved-in-terminal and clear it. claude-cli
+     * repaints the picker across multiple PTY chunks, so a single
+     * footer-less frame is not proof the prompt is gone. Sized in the same
+     * spirit as the approval FSM's `approvalCooldown` modal-lost hysteresis.
+     */
+    private static readonly INTERACTIVE_PROMPT_LOST_GRACE_MS;
+    /**
+     * Multi-question TUI capture: after Tabbing to a page, re-snapshot at this
+     * interval until its checkbox glyph column has settled, up to the timeout.
+     * The interval matches the legacy single fixed wait (120ms); the timeout
+     * bounds total capture time so a single-select page (which never shows
+     * glyphs) doesn't stall the capture indefinitely.
+     */
+    private static readonly CLAUDE_TUI_PAGE_POLL_INTERVAL_MS;
+    private static readonly CLAUDE_TUI_PAGE_SETTLE_TIMEOUT_MS;
+    /**
+     * Clear a held interactive prompt once the user has resolved it directly
+     * in the terminal (the choice picker leaves the screen without going
+     * through setInteractivePromptResponse). The approval path already does
+     * this via the FSM's modal-lost hysteresis; the interactive-prompt path
+     * had no equivalent, so a terminal-side answer left activeInteractivePrompt
+     * set and getStatus() re-emitted the same choice modal forever.
+     *
+     * Detection mirrors capture: the claude TUI picker is on-screen exactly
+     * while its "Enter to select" footer is rendered. When the footer is gone
+     * for INTERACTIVE_PROMPT_LOST_GRACE_MS the prompt is genuinely resolved.
+     */
+    private maybeClearResolvedClaudeTuiPrompt;
+    private maybeCaptureClaudeTuiPrompt;
+    /**
+     * The TUI prompt is captured on the FIRST frame that renders the
+     * "Enter to select" footer. At that instant the option rows' checkbox
+     * column may not have drawn yet, so `detectClaudeTuiMultiSelect` returns
+     * false and the prompt is frozen as single-select — the dashboard then
+     * renders radio buttons even though the picker is multi-select.
+     *
+     * While the same TUI prompt is still on screen, re-check the live snapshot:
+     * if checkbox glyphs have since appeared, promote any single-select
+     * question to multi-select and re-emit status. Promotion is one-way
+     * (false→true only) — once a question is known multi-select we never demote
+     * it, since the glyph column can scroll out of view on later frames.
+     *
+     * For MULTI-question prompts the per-page Tab capture is the actual source
+     * of the bug: pages 2..N are snapshotted ~120ms after the Tab keypress,
+     * before their option-row glyph column has redrawn, so those questions
+     * freeze as single-select while page 1 (already settled) is correct. We
+     * cannot upgrade blindly — the live snapshot shows only ONE focused page —
+     * but we CAN read that page's question text/header and upgrade the matching
+     * question. As the user navigates the picker (or it settles), each page is
+     * eventually re-read and repaired.
+     */
+    private maybeUpgradeClaudeTuiMultiSelect;
+    private readClaudeTuiHeaders;
+    /**
+     * Snapshot the currently-focused claude TUI page, polling until its
+     * option-row checkbox glyph column has settled (or a bounded timeout).
+     *
+     * Why poll: right after a Tab keypress the newly-focused page's glyph
+     * column has not redrawn yet, so an immediate snapshot shows the question +
+     * option labels but NO per-option checkbox markers — freezing that page as
+     * single-select. A fixed delay either races (too short) or is wasteful (too
+     * long). Instead we re-snapshot at a fixed interval and stop as soon as the
+     * frame shows multi-select glyphs, falling back to the last frame at the
+     * timeout. Single-select pages never show glyphs, so they always poll to the
+     * timeout — bounded small to keep capture snappy.
+     */
+    private snapshotSettledClaudeTuiPage;
+    private captureClaudeTuiPrompt;
+    getDebugState(): Record<string, any>;
+    getTraceState(limit?: number): Record<string, any>;
+    getProviderResolutionMeta(): Record<string, any>;
+}

package/dist/providers/spec/evaluator.d.ts

@@ -0,0 +1,45 @@
+import type { SectionDef, Condition, ExtractTitle, ExtractButtons } from './types.js';
+export interface ResolvedSection {
+    id: string;
+    fromLine: number;
+    toLine: number;
+    text: string;
+}
+export interface TraceEntry {
+    kind: 'section' | 'state_match' | 'state_skip' | 'modal' | 'control' | 'notification' | 'delegate';
+    text: string;
+}
+export declare function resolveSections(sectionsObj: Record<string, SectionDef>, lines: string[]): ResolvedSection[];
+export declare function sectionText(sections: ResolvedSection[], sectionId: string | undefined, fullScreen: string): string;
+export declare function evaluateCondition(cond: Condition, sections: ResolvedSection[], fullScreen: string, cursor: {
+    row: number;
+    col: number;
+} | undefined, prevLines: string[] | undefined, trace: TraceEntry[], stateId: string): boolean;
+export declare function extractTitle(rule: ExtractTitle, sections: ResolvedSection[], fullScreen: string): string | null;
+export declare function extractButtonsFromRule(rule: ExtractButtons, hay: string): {
+    index: number;
+    label: string;
+    key: string;
+    current: boolean;
+}[];
+/**
+ * Reduce a top→bottom-ordered list of parsed numbered entries to only the
+ * bottom-most contiguous block — the run whose indices descend by exactly 1
+ * scanning upward from the last entry.
+ *
+ * Picker and approval choices always render as the LAST contiguous numbered
+ * block at the bottom of the modal section. The conversation history above can
+ * carry its own stray "1./2./3." numbered lists (and blockquote `>` lines), and
+ * because section anchoring can pull body lines into the modal section, a naive
+ * top-down scan would bind the low option indices to those body lines and drop
+ * the real choices (the dashboard would show, and an arrow-key picker would
+ * commit, the wrong row). Selecting the bottom block makes the on-screen picker
+ * win regardless of body content. Since pickers number their options 1..N
+ * contiguously and bodies use indices ≥ 1, the upward chain always breaks the
+ * moment it would need a "0." above the picker's "1." — so the picker block is
+ * isolated cleanly. Entries are assumed already in screen order; the returned
+ * slice keeps that order.
+ */
+export declare function lastContiguousNumberedBlock<T extends {
+    index: number;
+}>(entries: T[]): T[];