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

package/src/providers/spec/fsm-evaluator.ts

@@ -0,0 +1,272 @@
+/**
+ * FSM evaluator — pure transition evaluation for adhdev:cli/spec@4.
+ *
+ * Given the current state, the screen, and a clock context (when the current
+ * state was entered, when each cursor_above region last changed), decides
+ * which outgoing transition fires — and records WHY every transition did or
+ * did not fire. That "why" trace is the whole point: it is what makes the FSM
+ * debuggable from the daemon API without guessing.
+ *
+ * Screen-content leaves (regex / changed) are delegated to the shared v3
+ * condition evaluator. Time leaves (elapsed_ms / stable_ms) are evaluated here
+ * against the clock context the driver passes in. No wall-clock reads happen
+ * in this file — the driver owns `now` so the function stays pure & testable.
+ */
+'use strict';
+
+import type { Condition, SectionDef } from './types.js';
+import {
+    resolveSections, evaluateCondition, sectionText, type ResolvedSection, type TraceEntry,
+} from './evaluator.js';
+import {
+    type CliSpecV4, type FsmCondition, type FsmTransition,
+    outgoingTransitions, stateById,
+} 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[];
+}
+
+const WHOLE_SCREEN = -1;
+
+function regionKey(cursorAbove: number | undefined): number {
+    return cursorAbove && cursorAbove > 0 ? cursorAbove : WHOLE_SCREEN;
+}
+
+function isRegex(c: FsmCondition): c is import('./types.js').RegexCondition {
+    return 'matches' in c;
+}
+function isChanged(c: FsmCondition): c is import('./types.js').ChangedCondition {
+    return 'cursor_above' in c && 'changed' in c;
+}
+function isElapsed(c: FsmCondition): c is import('./fsm-types.js').ElapsedCondition {
+    return 'elapsed_ms' in c;
+}
+function isStable(c: FsmCondition): c is import('./fsm-types.js').StableCondition {
+    return 'stable_ms' in c;
+}
+function isAll(c: FsmCondition): c is import('./fsm-types.js').FsmAllCondition {
+    return 'all' in c;
+}
+function isAny(c: FsmCondition): c is import('./fsm-types.js').FsmAnyCondition {
+    return 'any' in c;
+}
+function isNot(c: FsmCondition): c is import('./fsm-types.js').FsmNotCondition {
+    return 'not' in c;
+}
+
+/**
+ * Evaluate a single FSM condition into a {result, detail, remainingMs, children}.
+ * Recurses through all/any/not; defers regex/changed to the shared evaluator;
+ * handles elapsed_ms/stable_ms against the clock.
+ */
+function evalCond(
+    cond: FsmCondition,
+    sections: ResolvedSection[],
+    fullScreen: string,
+    cursor: { row: number; col: number } | undefined,
+    prevLines: string[] | undefined,
+    clock: FsmClock,
+    legacyTrace: TraceEntry[],
+    stateId: string,
+): CondResult {
+    if (isAll(cond)) {
+        const children = cond.all.map(c =>
+            evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId));
+        const result = children.every(c => c.result);
+        const remainingMs = result ? 0 : Math.max(0, ...children.filter(c => !c.result).map(c => c.remainingMs ?? 0));
+        return { kind: 'all', result, detail: `all(${children.length})`, remainingMs, children };
+    }
+    if (isAny(cond)) {
+        const children = cond.any.map(c =>
+            evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId));
+        const result = children.some(c => c.result);
+        // remaining = the soonest child that could flip true
+        const pending = children.filter(c => !c.result).map(c => c.remainingMs ?? Infinity);
+        const remainingMs = result ? 0 : (pending.length ? Math.min(...pending) : 0);
+        return { kind: 'any', result, detail: `any(${children.length})`, remainingMs: Number.isFinite(remainingMs) ? remainingMs : 0, children };
+    }
+    if (isNot(cond)) {
+        const child = evalCond(cond.not, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId);
+        return { kind: 'not', result: !child.result, detail: `not`, remainingMs: 0, children: [child] };
+    }
+    if (isElapsed(cond)) {
+        const age = clock.now - clock.stateEnteredAt;
+        const result = age >= cond.elapsed_ms;
+        const remainingMs = result ? 0 : cond.elapsed_ms - age;
+        return { kind: 'elapsed', result, detail: `elapsed ${age}ms / ${cond.elapsed_ms}ms`, remainingMs };
+    }
+    if (isStable(cond)) {
+        const key = regionKey(cond.cursor_above);
+        // If we never saw the region change, treat it as stable since the
+        // state was entered (conservative — avoids a premature "stable" on
+        // the very first frame).
+        const lastChanged = clock.regionLastChangedAt.get(key) ?? clock.stateEnteredAt;
+        const stableFor = clock.now - lastChanged;
+        const result = stableFor >= cond.stable_ms;
+        const remainingMs = result ? 0 : cond.stable_ms - stableFor;
+        const where = key === WHOLE_SCREEN ? 'screen' : `cursor_above=${cond.cursor_above}`;
+        return { kind: 'stable', result, detail: `stable ${where} ${stableFor}ms / ${cond.stable_ms}ms`, remainingMs };
+    }
+    // regex / changed → shared evaluator (operates on v3 Condition shape)
+    if (isRegex(cond) || isChanged(cond)) {
+        const result = evaluateCondition(cond as Condition, sections, fullScreen, cursor, prevLines, legacyTrace, stateId);
+        const kind = isRegex(cond) ? 'regex' : 'changed';
+        const detail = isRegex(cond)
+            ? `${(cond as any).section ?? '*'}~/${(cond as any).matches}/`
+            : `cursor_above=${(cond as any).cursor_above} changed=${(cond as any).changed}`;
+        // Debug-only: when a regex condition is TRUE, also capture the substring
+        // it matched so the snapshot can show the exact text the rule fired on.
+        // This re-runs the regex (read-only) and CANNOT change `result` above —
+        // the FSM decision is still entirely owned by evaluateCondition().
+        let matchedText: string | undefined;
+        if (result && isRegex(cond)) {
+            try {
+                const hay = sectionText(sections, (cond as any).section, fullScreen);
+                const re = new RegExp((cond as any).matches, (cond as any).flags ?? 'i');
+                const m = re.exec(hay);
+                if (m && m[0]) matchedText = m[0].replace(/\s+/g, ' ').trim().slice(0, 160);
+            } catch { /* capture is best-effort; never affects result */ }
+        }
+        return matchedText ? { kind, result, detail, matchedText } : { kind, result, detail };
+    }
+    return { kind: 'all', result: false, detail: 'unknown condition' };
+}
+
+function fromLabel(t: FsmTransition): string {
+    const from = Array.isArray(t.from) ? t.from.join('|') : t.from;
+    return t.label ?? `${from}→${t.to}`;
+}
+
+/**
+ * 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 function evaluateFsm(
+    spec: CliSpecV4,
+    currentStateId: string,
+    screenText: string,
+    cursor: { row: number; col: number } | undefined,
+    prevLines: string[] | undefined,
+    clock: FsmClock,
+): FsmEvaluation {
+    const legacyTrace: TraceEntry[] = [];
+    const lines = screenText.split('\n').map(l => l.endsWith('\r') ? l.slice(0, -1) : l);
+    const cleanScreen = lines.join('\n');
+    const sections = resolveSections(spec.sections ?? {}, lines);
+
+    const outgoing = outgoingTransitions(spec, currentStateId);
+    const transitions: TransitionEval[] = [];
+    let fired: TransitionEval | null = null;
+
+    for (const t of outgoing) {
+        const holdMs = t.min_hold_ms ?? 0;
+        const heldFor = clock.now - clock.stateEnteredAt;
+        const holdSatisfied = heldFor >= holdMs;
+        const holdRemainingMs = holdSatisfied ? 0 : holdMs - heldFor;
+
+        let cond: CondResult | undefined;
+        let condResult = true;
+        if (t.when) {
+            cond = evalCond(t.when, sections, cleanScreen, cursor, prevLines, clock, legacyTrace, `${currentStateId}→${t.to}`);
+            condResult = cond.result;
+        }
+
+        const fires = holdSatisfied && condResult;
+        const te: TransitionEval = {
+            to: t.to,
+            label: fromLabel(t),
+            eligible: true,
+            holdSatisfied,
+            holdRemainingMs,
+            condResult,
+            cond,
+            fires,
+            priority: t.priority ?? 0,
+        };
+        transitions.push(te);
+        if (fires && !fired) fired = te;
+    }
+
+    // Validate destination exists (defensive — loader should catch this).
+    if (fired && !stateById(spec, fired.to)) {
+        legacyTrace.push({ kind: 'state_skip', text: `transition target ${fired.to} not found` });
+        fired = null;
+    }
+
+    return { sections, transitions, fired, trace: legacyTrace };
+}
+
+/**
+ * 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 function evaluateConditionPreview(
+    cond: FsmCondition,
+    sections: Record<string, SectionDef> | undefined,
+    screenText: string,
+    cursor?: { row: number; col: number },
+): CondResult {
+    const lines = screenText.split('\n').map(l => l.endsWith('\r') ? l.slice(0, -1) : l);
+    const cleanScreen = lines.join('\n');
+    const resolved = resolveSections(sections ?? {}, lines);
+    const clock: FsmClock = { now: 0, stateEnteredAt: 0, regionLastChangedAt: new Map() };
+    return evalCond(cond, resolved, cleanScreen, cursor, undefined, clock, [], 'preview');
+}

package/src/providers/spec/fsm-loader.ts

@@ -0,0 +1,120 @@
+/**
+ * FSM spec (adhdev:cli/spec@4) loader + validator.
+ *
+ * Validation is intentionally code-based (not AJV) so a spec authored live in
+ * the debug panel gets precise, human-readable errors ("transition[2].to
+ * references unknown state 'budy'") instead of a JSON-schema path. Every error
+ * is something a spec author can act on without reading the engine.
+ */
+'use strict';
+
+import * as fs from 'node:fs';
+import { type CliSpecV4, type FsmCondition, isV4Spec } from './fsm-types.js';
+
+export interface FsmLoadOk { ok: true; spec: CliSpecV4; sourcePath: string; }
+export interface FsmLoadErr { ok: false; errors: string[]; sourcePath: string; }
+
+export function loadFsmSpec(sourcePath: string): FsmLoadOk | FsmLoadErr {
+    let raw: unknown;
+    try {
+        raw = JSON.parse(fs.readFileSync(sourcePath, 'utf8'));
+    } catch (err) {
+        return { ok: false, errors: [`Failed to read/parse spec: ${(err as Error).message}`], sourcePath };
+    }
+    const errors = validateFsmSpec(raw);
+    if (errors.length) return { ok: false, errors, sourcePath };
+    return { ok: true, spec: raw as CliSpecV4, sourcePath };
+}
+
+/** Pure validator — usable from a "validate before save" API in the panel. */
+export function validateFsmSpec(raw: unknown): string[] {
+    const errs: string[] = [];
+    if (!isV4Spec(raw)) return ['$schema must be "adhdev:cli/spec@4"'];
+    const spec = raw as CliSpecV4;
+
+    if (!spec.id) errs.push('id is required');
+    if (!spec.binary) errs.push('binary is required');
+    if (!spec.send_message?.submit_key) errs.push('send_message.submit_key is required');
+
+    if (spec.pre_launch_trust !== undefined) {
+        const t = spec.pre_launch_trust as { settings_path?: unknown; key?: unknown };
+        if (!t || typeof t !== 'object' || Array.isArray(t)) {
+            errs.push('pre_launch_trust must be an object');
+        } else {
+            if (typeof t.settings_path !== 'string' || !t.settings_path) errs.push('pre_launch_trust.settings_path is required');
+            if (typeof t.key !== 'string' || !t.key) errs.push('pre_launch_trust.key is required');
+        }
+    }
+
+    if (spec.refocus_when_stalled_ms !== undefined) {
+        if (typeof spec.refocus_when_stalled_ms !== 'number' || !(spec.refocus_when_stalled_ms > 0)) {
+            errs.push('refocus_when_stalled_ms must be a positive number');
+        } else if (!Array.isArray(spec.send_on_spawn) || spec.send_on_spawn.length === 0) {
+            errs.push('refocus_when_stalled_ms requires send_on_spawn (the wake sequence to re-inject)');
+        }
+    }
+
+    if (!Array.isArray(spec.states) || spec.states.length === 0) {
+        errs.push('states[] must be a non-empty array');
+        return errs;
+    }
+    if (!Array.isArray(spec.transitions)) {
+        errs.push('transitions[] must be an array');
+        return errs;
+    }
+
+    const ids = new Set<string>();
+    let initialCount = 0;
+    for (const [i, s] of spec.states.entries()) {
+        if (!s.id) { errs.push(`states[${i}].id is required`); continue; }
+        if (ids.has(s.id)) errs.push(`states[${i}].id "${s.id}" is duplicated`);
+        ids.add(s.id);
+        if (!s.label) errs.push(`states[${i}].label is required`);
+        if (s.initial) initialCount += 1;
+        if (s.status && !['idle', 'generating', 'approval'].includes(s.status)) {
+            errs.push(`states[${i}].status "${s.status}" must be idle|generating|approval`);
+        }
+    }
+    if (initialCount === 0) errs.push('exactly one state must have initial:true (none found)');
+    if (initialCount > 1) errs.push(`exactly one state must have initial:true (${initialCount} found)`);
+
+    const sectionIds = new Set(Object.keys(spec.sections ?? {}));
+    for (const [i, t] of spec.transitions.entries()) {
+        const froms = t.from === '*' ? [] : (Array.isArray(t.from) ? t.from : [t.from]);
+        for (const f of froms) {
+            if (!ids.has(f)) errs.push(`transitions[${i}].from references unknown state "${f}"`);
+        }
+        if (t.from !== '*' && froms.length === 0) errs.push(`transitions[${i}].from is required`);
+        if (!t.to) errs.push(`transitions[${i}].to is required`);
+        else if (!ids.has(t.to)) errs.push(`transitions[${i}].to references unknown state "${t.to}"`);
+        if (t.when) errs.push(...validateCondition(t.when, sectionIds, `transitions[${i}].when`));
+    }
+
+    // Section refs in state.extract
+    for (const [i, s] of spec.states.entries()) {
+        const sec = s.extract?.title?.section;
+        if (sec && !sectionIds.has(sec)) errs.push(`states[${i}].extract.title.section "${sec}" unknown`);
+        const bsec = s.extract?.buttons?.section;
+        if (bsec && !sectionIds.has(bsec)) errs.push(`states[${i}].extract.buttons.section "${bsec}" unknown`);
+    }
+
+    return errs;
+}
+
+function validateCondition(c: FsmCondition, sectionIds: Set<string>, path: string): string[] {
+    const errs: string[] = [];
+    const w = c as any;
+    if ('all' in w) { w.all.forEach((x: FsmCondition, i: number) => errs.push(...validateCondition(x, sectionIds, `${path}.all[${i}]`))); return errs; }
+    if ('any' in w) { w.any.forEach((x: FsmCondition, i: number) => errs.push(...validateCondition(x, sectionIds, `${path}.any[${i}]`))); return errs; }
+    if ('not' in w) { errs.push(...validateCondition(w.not, sectionIds, `${path}.not`)); return errs; }
+    if ('matches' in w) {
+        if (w.section && !sectionIds.has(w.section)) errs.push(`${path}.section "${w.section}" unknown`);
+        try { new RegExp(w.matches, w.flags ?? 'i'); } catch (e) { errs.push(`${path}.matches invalid regex: ${(e as Error).message}`); }
+        return errs;
+    }
+    if ('cursor_above' in w && 'changed' in w) return errs;
+    if ('elapsed_ms' in w) { if (typeof w.elapsed_ms !== 'number') errs.push(`${path}.elapsed_ms must be a number`); return errs; }
+    if ('stable_ms' in w) { if (typeof w.stable_ms !== 'number') errs.push(`${path}.stable_ms must be a number`); return errs; }
+    errs.push(`${path} is not a recognized condition`);
+    return errs;
+}

package/src/providers/spec/fsm-types.ts

@@ -0,0 +1,273 @@
+/**
+ * adhdev:cli/spec@4 — declarative FSM spec.
+ *
+ * A v4 spec describes a finite state machine the same way a Unity animator
+ * layer does: states are nodes, transitions are directed edges with a guard
+ * condition. The engine (fsm-driver.ts) holds ZERO CLI-specific knowledge —
+ * every concept that used to live in the driver as a hard-coded debounce
+ * (startup grace, busy hold, completion marker, idle hold) is now expressed
+ * declaratively as either a state, a transition condition, or a transition
+ * guard. To support a new CLI you write a spec; you never touch the engine.
+ *
+ * Reuses v3's section system (sections{}) and condition system (regex /
+ * changed / all / any) verbatim — see types.ts. v4 only adds the FSM layer
+ * (states[] + transitions[]) on top and two new leaf conditions that are
+ * inherently time-based:
+ *
+ *   - elapsed_ms : true once N ms have passed since the CURRENT state was
+ *                  entered. Replaces startup_grace_ms (a `starting` state with
+ *                  one `elapsed_ms` transition to idle).
+ *   - stable_ms  : true once the cursor_above region has been UNCHANGED for
+ *                  N ms. Replaces screen_active_hold_ms / the old changed:false
+ *                  + stable_ms combo. Pure region-stability gate.
+ *
+ * Both are evaluated by the driver (which owns the clock); the shared
+ * condition evaluator handles the screen-content leaves (regex / changed).
+ */
+'use strict';
+
+import type {
+    RegexCondition, ChangedCondition,
+    Control, NotificationRule, DelegateTrigger,
+    NativeHistoryConfig, SectionDef, ExtractTitle, ExtractButtons,
+} from './types.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Conditions (v4)
+//
+// Superset of v3 conditions. Adds the two time-based leaves. The shared
+// evaluator handles regex/changed; the driver handles elapsed_ms/stable_ms
+// because they need the wall clock and per-region change timestamps.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 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;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// States & transitions (v4)
+// ─────────────────────────────────────────────────────────────────────────────
+
+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;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CliSpecV4 — the v4 runtime spec
+// ─────────────────────────────────────────────────────────────────────────────
+
+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 function isV4Spec(raw: unknown): raw is CliSpecV4 {
+    return !!raw && typeof raw === 'object'
+        && (raw as { $schema?: string }).$schema === 'adhdev:cli/spec@4';
+}
+
+export function initialState(spec: CliSpecV4): FsmState {
+    return spec.states.find(s => s.initial) ?? spec.states[0];
+}
+
+export function stateById(spec: CliSpecV4, id: string): FsmState | undefined {
+    return spec.states.find(s => s.id === id);
+}
+
+/** Outgoing transitions from `stateId`, highest priority first, declaration
+ *  order as tiebreak. Includes wildcard ("*") and list-membership sources. */
+export function outgoingTransitions(spec: CliSpecV4, stateId: string): FsmTransition[] {
+    const matches = spec.transitions.filter(t => {
+        if (t.from === '*') return true;
+        if (Array.isArray(t.from)) return t.from.includes(stateId);
+        return t.from === stateId;
+    });
+    // Stable sort by priority desc; Array.prototype.sort is stable in V8 so
+    // equal-priority edges keep declaration order.
+    return matches
+        .map((t, i) => ({ t, i }))
+        .sort((a, b) => (b.t.priority ?? 0) - (a.t.priority ?? 0) || a.i - b.i)
+        .map(x => x.t);
+}
+
+/** Map a state to the dashboard status string, applying the documented
+ *  defaults when `status` is not explicit. */
+export function statusForState(state: FsmState): 'idle' | 'generating' | 'approval' {
+    if (state.status) return state.status;
+    if (state.modal) return 'approval';
+    if (state.id === 'busy' || state.id === 'generating') return 'generating';
+    return 'idle';
+}
+
+/**
+ * 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 function modalKindForState(state: FsmState): 'approval' | 'picker' | 'confirm' | null {
+    if (state.modal_kind) return state.modal_kind;
+    if (state.modal) return 'approval';
+    return null;
+}