@adhdev/daemon-core 0.9.82-rc.43 → 0.9.82-rc.430

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

@@ -0,0 +1,422 @@
+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 type Win32SubmitMode = 'paste' | 'soft_newline';
+export declare function resolveWin32SubmitMode(env?: NodeJS.ProcessEnv): Win32SubmitMode;
+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
+     * write advances lastWin32WriteAt so the submit settle-gate keeps waiting until
+     * the final segment is out and echoed.
+     *
+     * FIX-B-v2: a body that contains an embedded newline cannot be written raw —
+     * on the real win32 Ink/ConPTY composer each '\n' SUBMITS the preceding line as
+     * its own entry, truncating the prompt to only the tail fragment. So a
+     * newline-bearing body is rewritten so its embedded newlines never submit:
+     *   - 'paste' (default): wrap the body in a bracketed-paste (ESC[200~ … ESC[201~)
+     *     — the composer takes the whole thing, newlines and all, as pasted text.
+     *   - 'soft_newline': replace each embedded newline with a non-submitting
+     *     Shift+Enter (CSI-u) so the body is typed as one multi-line entry.
+     * The trailing submit CR is NOT written here — it stays separate and is fired
+     * later by scheduleWin32Submit (concern (A)). The bracketed-paste markers are
+     * written as their own atomic segments (never chunked), so chunking can never
+     * split ESC[200~ / ESC[201~ mid-sequence regardless of body length.
+     */
+    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 {};

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

@@ -0,0 +1,76 @@
+import type { SectionDef } from './types.js';
+import { type ResolvedSection, type TraceEntry } from './evaluator.js';
+import { type CliSpecV4, type FsmCondition } from './fsm-types.js';
+export interface FsmClock {
+    /** Wall-clock now (ms). Passed in so the evaluator stays pure. */
+    now: number;
+    /** When the current state was entered (ms). */
+    stateEnteredAt: number;
+    /** Last-changed timestamp per cursor_above region. Key = cursor_above
+     *  value (0 / undefined → whole-screen, keyed as -1). Missing key means
+     *  "never observed changing" → treated as stable since stateEnteredAt. */
+    regionLastChangedAt: Map<number, number>;
+}
+/** Per-condition evaluation detail — the debugging payload. */
+export interface CondResult {
+    kind: 'regex' | 'changed' | 'elapsed' | 'stable' | 'all' | 'any' | 'not';
+    result: boolean;
+    detail: string;
+    /** Remaining ms until a time-based condition would flip to true. 0 if
+     *  already true or not applicable. Lets the UI show a countdown. */
+    remainingMs?: number;
+    /** Debug-only: the actual substring a TRUE regex condition matched, so the
+     *  snapshot shows WHAT text the rule fired on — not just which regex. Never
+     *  read by the FSM; purely for the Spec Debug Snapshot. */
+    matchedText?: string;
+    children?: CondResult[];
+}
+/** One evaluated transition with its full reasoning. */
+export interface TransitionEval {
+    to: string;
+    label: string;
+    /** Did the `from` clause include the current state? (Always true for the
+     *  transitions we return — kept for completeness.) */
+    eligible: boolean;
+    /** min_hold_ms guard satisfied? */
+    holdSatisfied: boolean;
+    holdRemainingMs: number;
+    /** Guard condition result (true if no `when`). */
+    condResult: boolean;
+    cond?: CondResult;
+    /** Overall: would this transition fire? */
+    fires: boolean;
+    priority: number;
+}
+export interface FsmEvaluation {
+    /** Sections resolved from the screen (shared with v3 shape). */
+    sections: ResolvedSection[];
+    /** Every outgoing transition from the current state, priority-ordered,
+     *  each annotated with why it fired or didn't. */
+    transitions: TransitionEval[];
+    /** The transition that fires (first in priority order with fires===true),
+     *  or null to stay in the current state. */
+    fired: TransitionEval | null;
+    /** v3-compatible trace lines for the legacy inspector. */
+    trace: TraceEntry[];
+}
+/**
+ * Evaluate the FSM: given the current state id and screen, return every
+ * outgoing transition annotated with why it fires/doesn't, plus the one that
+ * fires (if any).
+ */
+export declare function evaluateFsm(spec: CliSpecV4, currentStateId: string, screenText: string, cursor: {
+    row: number;
+    col: number;
+} | undefined, prevLines: string[] | undefined, clock: FsmClock): FsmEvaluation;
+/**
+ * Evaluate a single condition against a screen + section map — for the spec
+ * editor's live preview ("does this regex match the current screen right
+ * now?"). Time leaves (elapsed_ms/stable_ms) are evaluated against a synthetic
+ * clock where the state was just entered, so they report their countdown
+ * rather than firing; the preview is about screen-content match, not timing.
+ */
+export declare function evaluateConditionPreview(cond: FsmCondition, sections: Record<string, SectionDef> | undefined, screenText: string, cursor?: {
+    row: number;
+    col: number;
+}): CondResult;

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

@@ -0,0 +1,14 @@
+import { type CliSpecV4 } from './fsm-types.js';
+export interface FsmLoadOk {
+    ok: true;
+    spec: CliSpecV4;
+    sourcePath: string;
+}
+export interface FsmLoadErr {
+    ok: false;
+    errors: string[];
+    sourcePath: string;
+}
+export declare function loadFsmSpec(sourcePath: string): FsmLoadOk | FsmLoadErr;
+/** Pure validator — usable from a "validate before save" API in the panel. */
+export declare function validateFsmSpec(raw: unknown): string[];

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

@@ -0,0 +1,174 @@
+import type { RegexCondition, ChangedCondition, Control, NotificationRule, DelegateTrigger, NativeHistoryConfig, SectionDef, ExtractTitle, ExtractButtons } from './types.js';
+/** True once `ms` have elapsed since the current state was entered. */
+export interface ElapsedCondition {
+    elapsed_ms: number;
+}
+/** True once the region `cursor_above` lines above the cursor has been
+ *  unchanged for `ms`. A stability gate — the inverse of a busy signal. */
+export interface StableCondition {
+    stable_ms: number;
+    /** Lines above the cursor that must be stable. Default: whole screen. */
+    cursor_above?: number;
+}
+export interface FsmAllCondition {
+    all: FsmCondition[];
+}
+export interface FsmAnyCondition {
+    any: FsmCondition[];
+}
+/** Negation — true when the inner condition is false. Lets a transition say
+ *  "go busy unless the completion marker is present", etc. */
+export interface FsmNotCondition {
+    not: FsmCondition;
+}
+export type FsmCondition = RegexCondition | ChangedCondition | ElapsedCondition | StableCondition | FsmAllCondition | FsmAnyCondition | FsmNotCondition;
+export interface FsmState {
+    id: string;
+    label: string;
+    /** Exactly one state must be `initial: true` — the state at spawn. */
+    initial?: boolean;
+    /** Modal states (approval/picker) expose modal buttons in the UI and are
+     *  treated as "interesting" — the dashboard surfaces them distinctly. */
+    modal?: boolean;
+    /**
+     * For a modal state, what KIND of modal it is — the semantic distinction the
+     * status field (always 'approval' for any modal, so the dashboard surfaces it)
+     * deliberately loses. The auto-approve worker uses this to decide whether it
+     * may answer the modal on the user's behalf:
+     *
+     *   - 'approval' — a tool/command/trust consent prompt ("Allow Bash?",
+     *     "Trust this folder?"). Auto-approve MAY fire (a background mesh worker
+     *     should not stall on these).
+     *   - 'picker'   — a selection menu the user opened (/model, /mode, …). There
+     *     is no "correct" answer to auto-pick; blindly selecting the first option
+     *     silently changes the model/mode. Auto-approve must NOT fire — the user
+     *     chooses.
+     *   - 'confirm'  — a non-consent yes/no the user must decide. Left to the user.
+     *
+     * Defaults to 'approval' for a modal state that omits it (preserves the
+     * pre-existing "auto-approve any modal" behaviour for un-migrated specs;
+     * picker/confirm states declare their kind explicitly). Non-modal states
+     * have no modal_kind.
+     */
+    modal_kind?: 'approval' | 'picker' | 'confirm';
+    /** Status this state maps to for the dashboard/cli-adapter status field.
+     *  One of: idle | generating | approval. Defaults: modal→approval,
+     *  initial→idle, id==='busy'→generating, else idle. Explicit wins. */
+    status?: 'idle' | 'generating' | 'approval';
+    /** Optional extraction run whenever this state is the committed state —
+     *  used by modal states to surface a title + buttons. */
+    extract?: {
+        title?: ExtractTitle;
+        buttons?: ExtractButtons;
+    };
+}
+export interface FsmTransition {
+    /** Source state id, or list of source ids, or "*" for any state. */
+    from: string | string[];
+    /** Destination state id. */
+    to: string;
+    /** Guard condition. Omitted → always eligible (only gated by `from` +
+     *  min_hold_ms). Evaluated against the current screen + clock. */
+    when?: FsmCondition;
+    /** Minimum time the machine must have been in `from` before this edge can
+     *  fire. Replaces busy_hold_ms / idle_hold_ms (per-edge, not global). */
+    min_hold_ms?: number;
+    /** Higher priority transitions are evaluated first. Default 0. Ties broken
+     *  by declaration order. */
+    priority?: number;
+    /** Human label for the debugger. */
+    label?: string;
+}
+/**
+ * Declarative "trust this folder before spawn" config. Some agent CLIs gate the
+ * first run in a new folder behind an interactive trust prompt and persist the
+ * answer as a string array in a JSON settings file. Declaring this lets the
+ * engine add the workspace path to that array before spawn so the prompt never
+ * appears — the robust alternative to detecting and auto-clicking the modal.
+ * CLIs without such a gate omit this field and the engine does nothing.
+ */
+export interface PreLaunchTrust {
+    /** Path to the CLI's JSON settings file. A leading `~` expands to $HOME. */
+    settings_path: string;
+    /** Key of the string-array of trusted folder paths within that file. */
+    key: string;
+}
+export interface CliSpecV4 {
+    $schema: 'adhdev:cli/spec@4';
+    id: string;
+    name: string;
+    binary: string;
+    spawn_args?: string[];
+    env?: Record<string, string>;
+    cli_version_range?: string;
+    /**
+     * Optional raw byte sequences written to the PTY once, shortly after spawn,
+     * to prime a TUI that gates its input handling on a terminal event the
+     * daemon would otherwise never emit. The canonical case is a focus-event
+     * TUI (Ink `useStdin`/`useFocus`, e.g. antigravity's `agy`) that enables
+     * focus reporting (`CSI ?1004h`) and treats its input box as unfocused —
+     * silently dropping the first programmatic write — until it receives a
+     * focus-in event (`ESC [ I`). Declaring `[""]` here wakes the input
+     * stream on spawn so the first delegated message lands without a manual
+     * keystroke. CLIs that do not focus-gate input simply omit this field; the
+     * engine writes nothing extra for them, so it stays CLI-agnostic.
+     */
+    send_on_spawn?: string[];
+    /** Delay (ms) after spawn before writing `send_on_spawn`. Default 250. */
+    send_on_spawn_delay_ms?: number;
+    /**
+     * Opt-in stall recovery for focus-gated TUIs. The same CLIs that need
+     * `send_on_spawn` (focus-event TUIs like antigravity's `agy`) also stop
+     * rendering / flushing output the moment they believe they have lost focus
+     * MID-TURN — the screen freezes and only repaints once the user presses a
+     * key, which the daemon never does on its own. When this field is set and
+     * the machine is in a `generating`-status state whose screen has not changed
+     * for `refocus_when_stalled_ms`, the engine re-injects the `send_on_spawn`
+     * prime (the focus-in event) once to wake the render loop, then waits for the
+     * screen to change or for the stall window to lapse again before re-priming
+     * (a cooldown that prevents a tight re-prime loop). Requires `send_on_spawn`
+     * to carry the wake sequence; with no `send_on_spawn` there is nothing to
+     * re-inject and the engine does nothing. Omitted by every non-focus-gated
+     * CLI spec, so the engine stays CLI-agnostic.
+     */
+    refocus_when_stalled_ms?: number;
+    /**
+     * Optional pre-spawn folder-trust step. When present, the engine adds the
+     * launch workspace path to the declared trusted-folders array before
+     * spawning, so a CLI that gates first run on a "trust this folder?" prompt
+     * (e.g. antigravity's `agy`) starts trusted and never blocks. Omitted for
+     * CLIs without such a gate. See pre-launch-trust.ts.
+     */
+    pre_launch_trust?: PreLaunchTrust;
+    send_message: {
+        submit_key: string;
+        delay_ms_before_submit?: number;
+        delay_ms_per_char?: number;
+    };
+    sections: Record<string, SectionDef>;
+    states: FsmState[];
+    transitions: FsmTransition[];
+    control_bar?: Control[];
+    notifications?: NotificationRule[];
+    delegate?: DelegateTrigger[];
+    native_history?: NativeHistoryConfig;
+    requiresFinalAssistantBeforeIdle?: boolean;
+}
+export declare function isV4Spec(raw: unknown): raw is CliSpecV4;
+export declare function initialState(spec: CliSpecV4): FsmState;
+export declare function stateById(spec: CliSpecV4, id: string): FsmState | undefined;
+/** Outgoing transitions from `stateId`, highest priority first, declaration
+ *  order as tiebreak. Includes wildcard ("*") and list-membership sources. */
+export declare function outgoingTransitions(spec: CliSpecV4, stateId: string): FsmTransition[];
+/** Map a state to the dashboard status string, applying the documented
+ *  defaults when `status` is not explicit. */
+export declare function statusForState(state: FsmState): 'idle' | 'generating' | 'approval';
+/**
+ * The modal kind for a state, or null when the state is not modal. A modal state
+ * that omits `modal_kind` defaults to 'approval' so the established
+ * auto-approve-any-modal behaviour is preserved for specs that have not yet
+ * declared a kind; picker/confirm states must opt out by declaring their kind.
+ * This is the value the cli-adapter carries on `activeModal.kind` and the
+ * auto-approve gate reads — see cli-provider-instance.maybeAutoApproveStatus.
+ */
+export declare function modalKindForState(state: FsmState): 'approval' | 'picker' | 'confirm' | null;