@adhdev/daemon-core 0.9.82-rc.217 → 0.9.82-rc.218

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

@@ -15,6 +15,7 @@ export declare class SpecCliAdapter implements CliAdapter {
      */
     readonly chatMessagesOwnedExternally: true;
     private driver;
+    /** Common spec fields the adapter reads, present in both v3 and v4. */
     private spec;
     private lastEvent;
     private latestState;

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

@@ -68,6 +68,54 @@ export type DashboardCommand = {
 } | {
     kind: 'shutdown';
 };
+/** One state-history entry — the union of fields produced by the v3 SpecDriver
+ *  (debounce-based) and the v4 FsmDriver (transition-based). The cli-adapter
+ *  and debug panel read this shape from either driver. */
+export interface DriverHistoryEntry {
+    stateId: string;
+    label: string;
+    at: number;
+    durationMs: number;
+    reason: string;
+    matchedStateId?: string;
+    matchedRules?: string[];
+    debounceKind?: string;
+    idleHoldMs?: number;
+    busyHoldMs?: number;
+    /** v4: the transition that fired, e.g. "idle→busy". */
+    via?: string;
+}
+/** The surface the cli-adapter drives. Implemented by both SpecDriver (v3,
+ *  debounce) and FsmDriver (v4, FSM). Lets the adapter hold either without
+ *  branching on the concrete type. */
+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;
+    getCompletionIdleDebounceState(): {
+        active: boolean;
+        ageMs: number;
+        holdMs: number;
+        forceAfterMs: number;
+    } | null;
+    /** v4 only — present on FsmDriver. Returns the live transition table. */
+    getFsmDebug?(): unknown;
+}
 export interface SpecDriverOpts {
     specPath: string;
     workingDir: string;
@@ -102,7 +150,7 @@ export declare function matchesCompletionIdleTargetState(spec: CliSpec, ev: Spec
     row: number;
     col: number;
 }): boolean;
-export declare class SpecDriver {
+export declare class SpecDriver implements ISpecDriver {
     private readonly opts;
     private spec;
     private adapter;
@@ -236,3 +284,4 @@ export declare class SpecDriver {
     private handleExit;
     private emit;
 }
+export declare function guessExt(mime: string): string;

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

@@ -1,4 +1,4 @@
-import type { CliSpec } from './types.js';
+import type { CliSpec, SectionDef, Condition, ExtractTitle, ExtractButtons } from './types.js';
 export interface ResolvedSection {
     id: string;
     fromLine: number;
@@ -44,6 +44,22 @@ export interface SpecEvaluation {
     sections: ResolvedSection[];
     trace: TraceEntry[];
 }
+/**
+ * Resolve v3 sections{} object into an ordered array of ResolvedSection.
+ * Two-pass: first anchor/positional, then apply `until` cross-references.
+ */
+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;
+}[];
 export declare function evaluate(spec: CliSpec, screenText: string, 
 /** Optional cursor position (0-based row and col). */
 cursor?: {

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

@@ -0,0 +1,110 @@
+import { type TransitionEval } from './fsm-evaluator.js';
+import { type DashboardEvent, type DashboardCommand, type SpecDriverOpts, type ISpecDriver, type DriverHistoryEntry } from './driver.js';
+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;
+    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;
+    constructor(opts: SpecDriverOpts);
+    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;
+    getFsmDebug(): {
+        currentState: string;
+        label: string;
+        stateAgeMs: number;
+        status: string;
+        cursor: {
+            row: number;
+            col: number;
+        };
+        transitions: TransitionEval[];
+    };
+    getStateHistory(): ReadonlyArray<HistoryEntry>;
+    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;
+    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;
+    /** 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;
+    private maybeMarkReady;
+    private fireNotifications;
+    private armOrCancelDelegateTimers;
+    private fireDelegate;
+    private handleSendMessage;
+    private actuallySendMessage;
+    private handleClickControl;
+    private handleClickModalButton;
+    private handleAttachImage;
+    private tryAdvancePicker;
+    private handleExit;
+    private pushHistory;
+    private specTag;
+    private emit;
+}
+export {};

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

@@ -0,0 +1,72 @@
+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;
+    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,91 @@
+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;
+    /** 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;
+}
+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;
+    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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.217",
+  "version": "0.9.82-rc.218",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/commands/router.ts

@@ -2322,6 +2322,48 @@ function normalizeCommandArgsWithInteractionId(args: any): Record<string, unknow
     return base;
 }
 
+/**
+ * Confine a spec path to ~/.adhdev/providers, defeating both prefix-bypass
+ * (e.g. ".../providers-evil") and symlink escape. Resolves the real path of
+ * the *parent* directory (the file may not exist yet for writes), requires the
+ * basename to be a literal `*.json`, and re-joins under the verified parent so
+ * the returned path can't point outside the tree. Used by get/write_spec_source.
+ */
+function resolveSpecPathInProviders(
+    specPath: string,
+    fsm: typeof import('node:fs'),
+    pathm: typeof import('node:path'),
+    osm: typeof import('node:os'),
+): { ok: true; path: string } | { ok: false; error: string } {
+    let rootReal: string;
+    try {
+        rootReal = fsm.realpathSync(pathm.join(osm.homedir(), '.adhdev', 'providers'));
+    } catch (e) {
+        return { ok: false, error: `providers root unavailable: ${(e as Error).message}` };
+    }
+    const resolved = pathm.resolve(specPath);
+    const base = pathm.basename(resolved);
+    if (!/^[\w.-]+\.json$/.test(base)) {
+        return { ok: false, error: 'refused: spec file must be a *.json basename' };
+    }
+    let parentReal: string;
+    try {
+        parentReal = fsm.realpathSync(pathm.dirname(resolved));
+    } catch (e) {
+        return { ok: false, error: `spec directory not found: ${(e as Error).message}` };
+    }
+    if (parentReal !== rootReal && !parentReal.startsWith(rootReal + pathm.sep)) {
+        return { ok: false, error: 'refused: spec path must be under the providers root' };
+    }
+    const safe = pathm.join(parentReal, base);
+    // Reject if the final file itself is a symlink pointing elsewhere.
+    try {
+        const st = fsm.lstatSync(safe);
+        if (st.isSymbolicLink()) return { ok: false, error: 'refused: spec path is a symlink' };
+    } catch { /* file may not exist yet (write case) — fine */ }
+    return { ok: true, path: safe };
+}
+
 function toHostedCliRuntimeDescriptor(record: any): HostedCliRuntimeDescriptor | null {
     if (!record || typeof record !== 'object') return null;
     const runtimeId = typeof record.sessionId === 'string' ? record.sessionId : '';
@@ -4641,6 +4683,156 @@ export class DaemonCommandRouter {
                 };
             }
 
+            // ── Spec source read/write for the debug panel's live editor.
+            //    Lets the dashboard load a session's spec.json, edit it, and
+            //    save it back — the driver's fs.watch picks up the change and
+            //    hot-reloads the FSM with no restart. Writes are confined to
+            //    files under ~/.adhdev/providers to avoid arbitrary fs access.
+            case 'get_spec_source': {
+                const fsm = await import('node:fs');
+                const pathm = await import('node:path');
+                const osm = await import('node:os');
+                const sessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim()
+                    : typeof args?.sessionId === 'string' ? args.sessionId.trim() : '';
+                let specPath = typeof args?.specPath === 'string' ? args.specPath : '';
+                if (!specPath && sessionId) {
+                    const target = this.deps.sessionRegistry.get(sessionId);
+                    const adapterObj = target ? this.deps.cliManager.findAdapter(target.providerType, { instanceKey: sessionId })?.adapter : null;
+                    const snap = adapterObj && typeof (adapterObj as any).getDebugSnapshot === 'function' ? (adapterObj as any).getDebugSnapshot() : null;
+                    specPath = snap?.specPath ?? '';
+                }
+                if (!specPath) return { success: false, error: 'specPath or resolvable targetSessionId required' };
+                // Confine reads to the providers tree, resolving symlinks so a
+                // crafted path can't escape via a symlinked spec file.
+                const safe = resolveSpecPathInProviders(specPath, fsm, pathm, osm);
+                if (!safe.ok) return { success: false, error: safe.error, specPath };
+                try {
+                    const content = fsm.readFileSync(safe.path, 'utf8');
+                    return { success: true, specPath: safe.path, content };
+                } catch (e) {
+                    return { success: false, error: `read failed: ${(e as Error).message}`, specPath };
+                }
+            }
+
+            case 'write_spec_source': {
+                const fsm = await import('node:fs');
+                const pathm = await import('node:path');
+                const osm = await import('node:os');
+                const specPath = typeof args?.specPath === 'string' ? args.specPath : '';
+                const content = typeof args?.content === 'string' ? args.content : '';
+                if (!specPath) return { success: false, error: 'specPath required' };
+                if (!content) return { success: false, error: 'content required' };
+                // Confine writes to the providers tree (symlink-safe — see helper).
+                const safe = resolveSpecPathInProviders(specPath, fsm, pathm, osm);
+                if (!safe.ok) return { success: false, error: safe.error };
+                // Validate JSON + (if v4) FSM structure before writing so a bad
+                // edit can't break the live session — return precise errors.
+                let parsed: unknown;
+                try { parsed = JSON.parse(content); }
+                catch (e) { return { success: false, error: `invalid JSON: ${(e as Error).message}` }; }
+                if ((parsed as any)?.$schema === 'adhdev:cli/spec@4') {
+                    const { validateFsmSpec } = await import('../providers/spec/fsm-loader.js');
+                    const errs = validateFsmSpec(parsed);
+                    if (errs.length) return { success: false, error: 'spec invalid', validationErrors: errs };
+                }
+                try {
+                    fsm.writeFileSync(safe.path, content, 'utf8');
+                    return { success: true, specPath: safe.path };
+                } catch (e) {
+                    return { success: false, error: `write failed: ${(e as Error).message}` };
+                }
+            }
+
+            // ── Validate an in-progress spec (string or object) without writing.
+            //    The form builder calls this on every change so Save can stay
+            //    disabled while there are structural / reference / regex errors.
+            case 'validate_spec': {
+                let parsed: unknown = args?.spec;
+                if (typeof args?.content === 'string') {
+                    try { parsed = JSON.parse(args.content); }
+                    catch (e) { return { success: true, valid: false, errors: [`invalid JSON: ${(e as Error).message}`] }; }
+                }
+                if (!parsed || typeof parsed !== 'object') {
+                    return { success: true, valid: false, errors: ['spec must be an object or content string'] };
+                }
+                const schema = (parsed as any).$schema;
+                if (schema === 'adhdev:cli/spec@4') {
+                    const { validateFsmSpec } = await import('../providers/spec/fsm-loader.js');
+                    const errors = validateFsmSpec(parsed);
+                    return { success: true, valid: errors.length === 0, errors };
+                }
+                // v1/v3 left to the legacy loader path; the builder is v4-only.
+                return { success: true, valid: false, errors: [`unsupported $schema "${schema}" — form builder is v4-only`] };
+            }
+
+            // ── Evaluate a single condition against a live session's current
+            //    screen — powers the editor's "does this match right now?"
+            //    preview. Returns the recursive match tree.
+            case 'eval_condition_preview': {
+                const sessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim()
+                    : typeof args?.sessionId === 'string' ? args.sessionId.trim() : '';
+                if (!sessionId) return { success: false, error: 'targetSessionId required' };
+                if (!args?.condition || typeof args.condition !== 'object') return { success: false, error: 'condition required' };
+                const target = this.deps.sessionRegistry.get(sessionId);
+                if (!target) return { success: false, error: 'Session not found', sessionId };
+                const adapterObj = this.deps.cliManager.findAdapter(target.providerType, { instanceKey: sessionId })?.adapter as any;
+                const snap = adapterObj && typeof adapterObj.getDebugSnapshot === 'function' ? adapterObj.getDebugSnapshot() : null;
+                if (!snap?.screen) return { success: false, error: 'no live screen for session' };
+                // Reconstruct the sections map the spec would resolve. We pass
+                // the spec's sections so section-scoped regexes resolve the same
+                // way they do at runtime; fall back to the on-disk spec.
+                let sectionsDef: Record<string, unknown> | undefined;
+                try {
+                    const fsm2 = await import('node:fs');
+                    if (snap.specPath) {
+                        const raw = JSON.parse(fsm2.readFileSync(snap.specPath, 'utf8'));
+                        sectionsDef = raw?.sections;
+                    }
+                } catch { /* fall back to whole-screen matching */ }
+                const { evaluateConditionPreview } = await import('../providers/spec/fsm-evaluator.js');
+                try {
+                    const result = evaluateConditionPreview(
+                        args.condition,
+                        sectionsDef as any,
+                        snap.screen,
+                        snap.cursorPosition ?? undefined,
+                    );
+                    return { success: true, result, sections: snap.sections ?? null };
+                } catch (e) {
+                    return { success: false, error: `eval failed: ${(e as Error).message}` };
+                }
+            }
+
+            // ── Resolve a sections map against a live session's screen — the
+            //    section editor's "test" button. Returns, for each section id,
+            //    the line range + the text it captures, so the author can SEE
+            //    whether a from_top/until/anchor definition carves the screen
+            //    the way they intend. Accepts an in-progress sections map so it
+            //    previews unsaved edits.
+            case 'resolve_section_preview': {
+                const sessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim()
+                    : typeof args?.sessionId === 'string' ? args.sessionId.trim() : '';
+                if (!sessionId) return { success: false, error: 'targetSessionId required' };
+                if (!args?.sections || typeof args.sections !== 'object') return { success: false, error: 'sections map required' };
+                const target = this.deps.sessionRegistry.get(sessionId);
+                if (!target) return { success: false, error: 'Session not found', sessionId };
+                const adapterObj = this.deps.cliManager.findAdapter(target.providerType, { instanceKey: sessionId })?.adapter as any;
+                const snap = adapterObj && typeof adapterObj.getDebugSnapshot === 'function' ? adapterObj.getDebugSnapshot() : null;
+                if (!snap?.screen) return { success: false, error: 'no live screen for session' };
+                const { resolveSections } = await import('../providers/spec/evaluator.js');
+                try {
+                    const lines = String(snap.screen).split('\n').map((l: string) => l.endsWith('\r') ? l.slice(0, -1) : l);
+                    const resolved = resolveSections(args.sections as any, lines);
+                    return {
+                        success: true,
+                        screenLineCount: lines.length,
+                        sections: resolved.map(s => ({ id: s.id, fromLine: s.fromLine, toLine: s.toLine, text: s.text })),
+                    };
+                } catch (e) {
+                    return { success: false, error: `resolve failed: ${(e as Error).message}` };
+                }
+            }
+
             // ── User-level coordinator-prompt files (~/.adhdev/coordinator-prompts/).
             //    These live on this daemon's filesystem and never sync to the
             //    cloud / other daemons — they're per-machine config. The

package/src/providers/provider-loader.ts

@@ -1247,29 +1247,39 @@ export class ProviderLoader {
           // Hand the resolved spec path off to route.ts via a hidden field
           // so the routing layer doesn't have to repeat the candidate walk.
           (resolved as any)._resolvedSpecPath = specPath;
-          const r = loadSpec(specPath);
+          // Extract control_bar + native_history in a schema-agnostic way.
+          // v3 goes through loadSpec (validates/migrates); v4 (FSM) reads the
+          // header fields directly from JSON since loadSpec only knows v1/v3.
+          let specControls: any[] | undefined;
+          let nh: any | undefined;
+          try {
+            const rawSpec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+            if (rawSpec?.$schema === 'adhdev:cli/spec@4') {
+              specControls = rawSpec.control_bar;
+              nh = rawSpec.native_history;
+            } else {
+              const r = loadSpec(specPath);
+              if (r.ok) { specControls = r.spec.control_bar; nh = r.spec.native_history; }
+            }
+          } catch { /* unreadable spec — leave controls/native unavailable */ }
           // Stub each control_bar entry as a provider.scripts.<id>. The
           // upstream invoke_provider_script gate checks that the script
           // name exists on provider.scripts before calling adapter.invokeScript;
           // for spec providers the *actual* dispatch happens inside
           // SpecCliAdapter.invokeScript which maps the name to control_bar.
           // The stub is just a presence marker so the gate doesn't reject.
-          if (r.ok) {
-            const controls = r.spec.control_bar ?? [];
-            if (controls.length > 0) {
-              resolved.scripts = { ...(resolved.scripts || {}) };
-              for (const ctl of controls) {
-                if (!(resolved.scripts as any)[ctl.id]) {
-                  (resolved.scripts as any)[ctl.id] = (..._args: unknown[]) => ({
-                    __spec_control: true,
-                    controlId: ctl.id,
-                    actionType: ctl.action.type,
-                  });
-                }
+          if (specControls && specControls.length > 0) {
+            resolved.scripts = { ...(resolved.scripts || {}) };
+            for (const ctl of specControls) {
+              if (!(resolved.scripts as any)[ctl.id]) {
+                (resolved.scripts as any)[ctl.id] = (..._args: unknown[]) => ({
+                  __spec_control: true,
+                  controlId: ctl.id,
+                  actionType: ctl.action.type,
+                });
               }
             }
           }
-          const nh = r.ok ? r.spec.native_history : undefined;
           if (nh) {
             let reader: ((input: any) => any) | null = null;
             let format = 'spec';