@adhdev/daemon-core 0.9.82-rc.41 → 0.9.82-rc.410

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[];

package/dist/providers/spec/fsm-driver.d.ts

@@ -0,0 +1,407 @@
+import { type SpecPtyEvent } from './adapter.js';
+import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+import { type TraceEntry } from './evaluator.js';
+import { type TransitionEval } from './fsm-evaluator.js';
+import { chunkPreservingSurrogates as chunkPreservingSurrogatesShared } from '../../cli-adapters/pty-write-chunking.js';
+export type DashboardEvent = {
+    kind: 'pty_data';
+    chunk: string;
+} | {
+    kind: 'state_changed';
+    state: {
+        id: string;
+        label: string;
+        title: string | null;
+        status: 'idle' | 'generating' | 'approval';
+    };
+    modal: {
+        title: string | null;
+        buttons: {
+            index: number;
+            label: string;
+        }[];
+        kind: 'approval' | 'picker' | 'confirm' | null;
+    } | null;
+    controls: {
+        id: string;
+        label: string;
+        action_type: string;
+    }[];
+} | {
+    kind: 'notification';
+    id: string;
+    title: string;
+    body: string;
+} | {
+    kind: 'delegate';
+    id: string;
+    task: string;
+} | {
+    kind: 'spec_trace';
+    entries: TraceEntry[];
+} | {
+    kind: 'exit';
+    exit_code: number;
+} | {
+    kind: 'spec_error';
+    errors: string[];
+};
+export type DashboardCommand = {
+    kind: 'send_message';
+    text: string;
+} | {
+    kind: 'pty_write';
+    data: string;
+} | {
+    kind: 'click_control';
+    control_id: string;
+    payload?: unknown;
+} | {
+    kind: 'click_modal_button';
+    index: number;
+} | {
+    kind: 'attach_image';
+    blob: string;
+    mime: string;
+} | {
+    kind: 'resize';
+    cols: number;
+    rows: number;
+} | {
+    kind: 'cancel';
+} | {
+    kind: 'shutdown';
+};
+export interface DriverHistoryEntry {
+    stateId: string;
+    label: string;
+    at: number;
+    durationMs: number;
+    reason: string;
+    matchedStateId?: string;
+    matchedRules?: string[];
+    debounceKind?: string;
+    idleHoldMs?: number;
+    busyHoldMs?: number;
+    via?: string;
+}
+/**
+ * A frozen snapshot of the FULL FSM evaluation captured at the instant a
+ * transition fired — the rich `transitions[]` table (per-transition eligible /
+ * hold countdown / per-condition CondResult + remainingMs) that `getFsmDebug()`
+ * otherwise only computes live for the current instant. Kept in a separate ring
+ * buffer from `stateHistory` (which stays intentionally lightweight) so the
+ * "why did this rule fire just before the transition" question is answerable
+ * after the fact. before-only: this is the evaluation that PRODUCED the
+ * transition, not the post-transition state.
+ */
+export interface FsmSnapshotEntry {
+    /** State we transitioned out of. */
+    stateFrom: string;
+    /** State we transitioned into (the fired transition's destination). */
+    stateTo: string;
+    /** Wall-clock time the transition committed (ms). */
+    at: number;
+    /** The fired transition's destination state id (== stateTo; kept explicit
+     *  to mirror the rule that fired). */
+    firedTo: string;
+    /** Human label of the fired transition (e.g. "approval→busy"). */
+    firedLabel: string;
+    /** Why-it-fired summary, same shape produced for stateHistory.matchedRules. */
+    reason: string[];
+    /** Every outgoing transition from `stateFrom` as evaluated at `at`, each
+     *  with its eligible / hold / per-condition CondResult + remainingMs. This
+     *  is the full pre-transition evaluation table — the whole point of the
+     *  snapshot. */
+    transitions: TransitionEval[];
+}
+export interface ISpecDriver {
+    subscribe(listener: (ev: DashboardEvent) => void): () => void;
+    start(): void;
+    dispatch(cmd: DashboardCommand): void;
+    snapshot(): string;
+    getCursorPosition(): {
+        row: number;
+        col: number;
+    };
+    getScreen(): string;
+    getSpecPath(): string;
+    shutdown(): void;
+    getStateHistory(): ReadonlyArray<DriverHistoryEntry>;
+    getSections(): Array<{
+        id: string;
+        text: string;
+    }> | null;
+    getLastBusyAt(): number;
+    hasIdleHoldPending(): boolean;
+    hasSeenReady(): boolean;
+    getCompletionIdleDebounceState(): {
+        active: boolean;
+        ageMs: number;
+        holdMs: number;
+        forceAfterMs: number;
+    } | null;
+    getFsmDebug?(): unknown;
+    getFsmSnapshotHistory?(): ReadonlyArray<FsmSnapshotEntry>;
+    getEventTimeline?(limit?: number): ReadonlyArray<SpecPtyEvent>;
+}
+export interface SpecDriverOpts {
+    specPath: string;
+    workingDir: string;
+    extraEnv?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+    hotReload?: boolean;
+    emitTrace?: boolean;
+    transportFactory?: PtyTransportFactory;
+    extraCliArgs?: string[];
+}
+export declare function resolveSubmitDelayMs(specBeforeSubmit: number | undefined, text: string): number;
+/** Re-export of the shared surrogate-safe splitter so existing imports of
+ *  `chunkPreservingSurrogates` from this module keep working. The implementation
+ *  lives in ../../cli-adapters/pty-write-chunking so the spec driver and the
+ *  legacy adapter share one definition. */
+export declare const chunkPreservingSurrogates: typeof chunkPreservingSurrogatesShared;
+export declare function guessExt(mime: string): string;
+type HistoryEntry = DriverHistoryEntry;
+export declare class FsmDriver implements ISpecDriver {
+    private readonly opts;
+    private spec;
+    private adapter;
+    private listeners;
+    private currentStateId;
+    private stateEnteredAt;
+    private startedAtMs;
+    private prevScreenLines;
+    /** Per cursor_above region (key: cursor_above, -1 = whole screen) → last
+     *  time that region's content changed. Drives stable_ms conditions. */
+    private regionLastChangedAt;
+    /** Timer that re-runs evaluate() when a time-condition would flip true
+     *  with no PTY frame to trigger it. */
+    private wakeTimer;
+    /** Timer driving the focus-gated stall watchdog (refocus_when_stalled_ms).
+     *  Re-arms itself while the machine is generating so a re-prime can fire
+     *  even when the PTY has gone completely quiet. */
+    private stallTimer;
+    /** Wall-clock time the last stall re-prime was injected. The cooldown gate:
+     *  after a re-prime we don't re-inject until the screen changes (which
+     *  resets the stall reference) or another full stall window lapses. */
+    private lastRefocusAt;
+    /** Timer driving the win32 verification-based submit resend loop (see
+     *  WIN32_SUBMIT_* and scheduleWin32Submit). Re-arms itself until the FSM
+     *  leaves idle (submitted) or the resend budget is spent. */
+    private win32SubmitTimer;
+    /** Wall-clock (ms) of the most recent raw PTY output chunk. Advances on every
+     *  on_pty_data — including the echo of text written into the composer — so the
+     *  win32 submit settle-gate can tell when input has finished landing. */
+    private lastPtyDataAt;
+    /** Wall-clock (ms) of the most recent win32 message-body input write. Bridges
+     *  the gap between writing a chunk and its echo so the settle-gate does not
+     *  declare "quiet" mid-write. */
+    private lastWin32WriteAt;
+    /** Pending paced chunk-write timer for a large win32 body (see writeWin32Body). */
+    private win32WriteTimer;
+    /** Timer driving the win32 verification-based modal-confirm CR resend loop (see
+     *  scheduleWin32ModalConfirm). A lone CR that confirms an approval/picker choice
+     *  is absorbed by ConPTY the same way a send_message submit CR is, so the confirm
+     *  must be resent until the modal actually resolves (status leaves 'approval'). */
+    private win32ModalConfirmTimer;
+    private currentEval;
+    private stateHistory;
+    private prevStateAt;
+    private readySeenOnce;
+    private pendingSends;
+    private pickerInProgress;
+    private delegateTimers;
+    private specWatcher;
+    /** Last full FSM evaluation, kept for the debugger. */
+    private lastFsmEval;
+    /** Ring buffer (max 20) of the full FSM evaluation captured at each
+     *  transition — the rich pre-transition table that lastFsmEval only keeps
+     *  for the single most recent evaluation. Separate from stateHistory. */
+    private fsmSnapshotHistory;
+    constructor(opts: SpecDriverOpts);
+    subscribe(listener: (ev: DashboardEvent) => void): () => void;
+    start(): void;
+    private scheduleSpawnPrime;
+    /** Write the declared `send_on_spawn` sequences to the PTY once. Used both
+     *  at spawn (scheduleSpawnPrime) and, for focus-gated TUIs, by the stall
+     *  watchdog to re-inject the focus-in wake mid-turn. No-op when the spec
+     *  declares no prime, so non-focus-gated CLIs are never poked. */
+    private sendSpawnPrime;
+    dispatch(cmd: DashboardCommand): void;
+    snapshot(): string;
+    getCursorPosition(): {
+        row: number;
+        col: number;
+    };
+    getScreen(): string;
+    /** Scrollback-inclusive screen as line array — used only for modal/button
+     *  content extraction so a tall prompt's off-screen anchors stay matchable.
+     *  Falls back to the viewport snapshot if scrollback read is unavailable. */
+    private scrollbackLines;
+    getSpecPath(): string;
+    shutdown(): void;
+    getFsmDebug(): {
+        currentState: string;
+        label: string;
+        stateAgeMs: number;
+        status: string;
+        cursor: {
+            row: number;
+            col: number;
+        };
+        transitions: TransitionEval[];
+    };
+    getStateHistory(): ReadonlyArray<HistoryEntry>;
+    getFsmSnapshotHistory(): ReadonlyArray<FsmSnapshotEntry>;
+    /** Debug-only PTY input/output/resize/cursor timeline from the adapter. */
+    getEventTimeline(limit?: number): ReadonlyArray<SpecPtyEvent>;
+    getSections(): Array<{
+        id: string;
+        text: string;
+    }> | null;
+    /** v3-compat shims so the cli-adapter's existing debug snapshot keeps
+     *  working without branching on driver type. */
+    getLastBusyAt(): number;
+    hasIdleHoldPending(): boolean;
+    /**
+     * True once the machine has reached its first non-initial idle state (the
+     * prompt is genuinely drawn — see maybeMarkReady). The cli-adapter surfaces
+     * this on its idle status so CliProviderInstance can re-arm the queue-claim
+     * agent:ready on the first genuine ready, independent of the boot-time
+     * starting→idle one-shot (which is consumed too early for specs whose
+     * initial state already reports idle).
+     */
+    hasSeenReady(): boolean;
+    getCompletionIdleDebounceState(): {
+        active: boolean;
+        ageMs: number;
+        holdMs: number;
+        forceAfterMs: number;
+    } | null;
+    private loadSpecOrThrow;
+    private buildAdapterOpts;
+    private armSpecWatcher;
+    private emitInitialState;
+    private buildClock;
+    private evalFsmNow;
+    private reevaluate;
+    private commitTransition;
+    /** Snapshot the full FSM evaluation that produced a transition into the
+     *  separate fsmSnapshotHistory ring buffer (max 20). The transitions[]
+     *  table is captured by reference — it is freshly built per evaluation in
+     *  evaluateFsm and never mutated after, so no clone is needed. */
+    private pushFsmSnapshot;
+    /** Re-derive the visible modal + controls for the current state and emit a
+     *  state_changed if anything differs from the last emit. */
+    private emitStateChanged;
+    private deriveModal;
+    private deriveTitle;
+    private deriveControls;
+    /** Track which cursor_above regions changed since the previous frame so
+     *  stable_ms conditions can measure quiet time. We record every region
+     *  size referenced by a stable_ms condition in the spec, plus the whole
+     *  screen (-1). */
+    private trackRegionChanges;
+    /** All cursor_above region sizes referenced by stable_ms conditions in the
+     *  current state's outgoing transitions, plus whole-screen. Cached lazily
+     *  per spec load would be nicer but the set is tiny. */
+    private stableRegionSizes;
+    /** Schedule a re-evaluation for the soonest pending time-condition on any
+     *  outgoing transition (elapsed_ms / stable_ms / min_hold_ms). Without
+     *  this, a state whose only exit is time-based would never leave once the
+     *  PTY goes quiet. */
+    private scheduleWakeForState;
+    /** True when this spec opts into stall recovery (declares a positive
+     *  refocus window AND a wake sequence to re-inject). */
+    private stallRecoveryEnabled;
+    /** Wall-clock time the screen last changed in the current state, falling
+     *  back to state entry when it has not changed since (i.e. fully stalled
+     *  from the start of the state). */
+    private lastScreenChangeAt;
+    /** Arm a timer to re-inject the focus-in prime if the screen stays frozen
+     *  through a `generating` state. Only active for opted-in focus-gated specs;
+     *  a no-op (and cleared) for every other CLI and every non-generating state.
+     *  Re-arms itself so it keeps watching while the PTY is quiet. */
+    private scheduleStallWatchdog;
+    /** Fire when the stall window elapses: if the screen is still frozen and we
+     *  are still generating, re-inject the focus-in wake once, then re-arm. */
+    private onStallTick;
+    private maybeMarkReady;
+    private fireNotifications;
+    private armOrCancelDelegateTimers;
+    private fireDelegate;
+    private handleSendMessage;
+    private actuallySendMessage;
+    /** The agent's current coarse status, derived from the FSM node we're in. */
+    private currentStatus;
+    /** Record a win32 body write so the settle-gate counts it as input activity
+     *  even before the echo arrives. */
+    private markWin32Write;
+    /** Most recent win32 input activity — a write we issued OR a PTY output chunk
+     *  (echo). The submit settle-gate waits for this to go quiet. */
+    private lastWin32InputActivityAt;
+    /**
+     * Write the message body to the PTY for win32, paced into bounded chunks. A
+     * single unbounded ConPTY write can overflow the input pipe and drop leading
+     * bytes; splitting it with a short inter-chunk gap keeps the console input
+     * buffer from overflowing. Small bodies still go out in a single write. Each
+     * chunk advances lastWin32WriteAt so the submit settle-gate keeps waiting until
+     * the final chunk is out and echoed.
+     */
+    private writeWin32Body;
+    /**
+     * win32 submit. Two phases:
+     *
+     *  Phase 1 (echo-gate): hold the first CR until the body text is CONFIRMED in the
+     *  composer (its whitespace-collapsed tail appears in the rendered screen) AND the
+     *  PTY output is then quiet for WIN32_SUBMIT_SETTLE_MS (the full, possibly multi-KB
+     *  / multiline body has finished arriving). This replaces a bare output-quiet
+     *  settle: an early write that races claude's boot is buffered, not dropped, so the
+     *  screen can go quiet with the body NOT YET in the composer — a quiet-only gate
+     *  would then fire a CR into an empty composer (no submit). Waiting on the echo
+     *  closes that. Honors an initial minimum delay and a generous WIN32_ECHO_MAX_WAIT_MS
+     *  last-resort blind fire so a body that truly never confirms still submits (carried
+     *  by phase 2) rather than hanging. A settled session echoes immediately → no delay.
+     *
+     *  Phase 2 (verified resend — unchanged): send the submit key, wait a gap, and
+     *  if the FSM is still 'idle' (the CR was absorbed as a multiline-paste
+     *  newline) resend, up to WIN32_SUBMIT_MAX_RESENDS. The first CR always fires
+     *  (a stale/edge status never suppresses it); resends are gated on still being
+     *  idle and stop the instant the agent leaves idle (submitted → generating /
+     *  approval). This preserves the win32 lone-CR-swallow handling.
+     */
+    private scheduleWin32Submit;
+    private handleClickControl;
+    private handleClickModalButton;
+    /**
+     * Submit a modal-confirm key sequence (the choice key + its trailing CR).
+     *
+     * On win32 the trailing CR is the SAME lone-CR-swallow case as a send_message
+     * submit: ConPTY can absorb a single CR as a literal newline instead of a
+     * confirm, so the approval/picker modal never resolves and the FSM flaps
+     * approval↔busy while auto-approve keeps firing into the void (APPROVESTUCK).
+     * So we split any non-CR prefix (e.g. the "1" of "1\r") off, write it once, and
+     * resend the CR on a fixed cadence until the modal actually resolves (status
+     * leaves 'approval'). Non-win32 keeps the single direct write — its CR submits
+     * on the first try.
+     */
+    private submitModalConfirm;
+    /**
+     * win32 modal-confirm CR resend loop. Mirrors scheduleWin32Submit's phase-2
+     * verified resend, but gated on still being IN a modal (status 'approval')
+     * rather than still idle: the first CR fires immediately, then resends every
+     * WIN32_SUBMIT_RESEND_GAP_MS while the FSM is still showing the modal, up to
+     * WIN32_SUBMIT_MAX_RESENDS. The instant the modal resolves (status flips to
+     * generating/idle) we stop, so no stray CR leaks into the next turn's composer.
+     */
+    private scheduleWin32ModalConfirm;
+    private handleAttachImage;
+    private tryAdvancePicker;
+    private handleExit;
+    private pushHistory;
+    private specTag;
+    private emit;
+}
+export {};