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

package/src/commands/low-family/refine-config.ts

@@ -0,0 +1,106 @@
+/**
+ * RF-ROUTER LOW family — mesh refine-config / change-impact config commands.
+ *
+ * Schema/validate/suggest endpoints for the repo mesh refine config and the
+ * change-impact config. Pure: every handler is a function of args only (it reads
+ * no router deps), so ctx is unused. Extracted verbatim from executeDaemonCommand;
+ * the config helpers are imported from their source modules, identical to router.ts.
+ */
+import {
+    CHANGE_IMPACT_CONFIG_LOCATIONS,
+    CHANGE_IMPACT_CONFIG_SCHEMA,
+    loadChangeImpactConfig,
+    suggestChangeImpactConfig,
+    validateChangeImpactConfig,
+} from '../../git/change-impact-config.js';
+import {
+    MESH_REFINE_CONFIG_LOCATIONS,
+    MESH_REFINE_CONFIG_SCHEMA,
+    loadMeshRefineConfig,
+    suggestMeshRefineConfig,
+    validateMeshRefineConfig,
+} from '../../mesh/refine-config.js';
+import {
+    MESH_WORKTREE_BOOTSTRAP_CONFIG_LOCATIONS,
+    MESH_WORKTREE_BOOTSTRAP_CONFIG_SCHEMA,
+} from '../../mesh/worktree-bootstrap-config.js';
+import type { LowFamilyContext, LowFamilyHandler } from './types.js';
+
+export const refineConfigHandlers: Record<string, LowFamilyHandler> = {
+    get_mesh_refine_config_schema: async (_ctx: LowFamilyContext, _args: any) => {
+        return {
+            success: true,
+            schema: MESH_REFINE_CONFIG_SCHEMA,
+            locations: MESH_REFINE_CONFIG_LOCATIONS,
+            worktreeBootstrap: {
+                schema: MESH_WORKTREE_BOOTSTRAP_CONFIG_SCHEMA,
+                locations: MESH_WORKTREE_BOOTSTRAP_CONFIG_LOCATIONS,
+                sourceOfTruth: 'repo worktree bootstrap config',
+                runBehavior: 'When present and enabled, clone_mesh_node runs commands after submodule initialization and records status on the worktree node.',
+            },
+            sourceOfTruth: 'repo mesh/refine config',
+            heuristicRole: 'suggestions_only_not_execution_path',
+        };
+    },
+
+    validate_mesh_refine_config: async (_ctx: LowFamilyContext, args: any) => {
+        const workspace = typeof args?.workspace === 'string' ? args.workspace : process.cwd();
+        const mesh = args?.inlineMesh || {};
+        const loaded = args?.config !== undefined
+            ? { config: args.config, source: 'inline', sourceType: 'mesh_policy' as const }
+            : loadMeshRefineConfig(mesh, workspace);
+        const validation = loaded.config
+            ? validateMeshRefineConfig(loaded.config, loaded.source)
+            : { valid: false, errors: [((loaded as { error?: string }).error) || 'repo mesh/refine config unavailable'], commands: [], rejectedCommands: [] };
+        return { success: validation.valid, ...loaded, ...validation };
+    },
+
+    suggest_mesh_refine_config: async (_ctx: LowFamilyContext, args: any) => {
+        const workspace = typeof args?.workspace === 'string' ? args.workspace : process.cwd();
+        const mesh = args?.inlineMesh || {};
+        return {
+            success: true,
+            ...suggestMeshRefineConfig(mesh, workspace),
+            note: 'Suggestions are heuristic scaffold only; Refinery will not execute them until saved into repo mesh/refine config.',
+        };
+    },
+
+    get_mesh_change_impact_config_schema: async (_ctx: LowFamilyContext, _args: any) => {
+        return {
+            success: true,
+            schema: CHANGE_IMPACT_CONFIG_SCHEMA,
+            locations: CHANGE_IMPACT_CONFIG_LOCATIONS,
+            sourceOfTruth: 'repo change-impact config',
+            heuristicRole: 'suggestions_only_not_execution_path',
+            note: 'Declarative config only — JSON/YAML are parsed but never executed. Defines which package/file changes require a daemon rebuild/restart vs. a web-only redeploy vs. nothing.',
+        };
+    },
+
+    validate_mesh_change_impact_config: async (_ctx: LowFamilyContext, args: any) => {
+        const workspace = typeof args?.workspace === 'string' ? args.workspace : process.cwd();
+        if (args?.config !== undefined) {
+            const validation = validateChangeImpactConfig(args.config, 'inline');
+            return { success: validation.valid, source: 'inline', sourceType: 'mesh_policy', ...validation };
+        }
+        const loaded = loadChangeImpactConfig(workspace);
+        if (loaded.sourceType === 'repo_file') {
+            const validation = validateChangeImpactConfig(loaded.config, loaded.source);
+            return { success: validation.valid, ...loaded, ...validation };
+        }
+        return {
+            success: false,
+            ...loaded,
+            valid: false,
+            errors: [loaded.error || 'repo change-impact config unavailable'],
+        };
+    },
+
+    suggest_mesh_change_impact_config: async (_ctx: LowFamilyContext, args: any) => {
+        const workspace = typeof args?.workspace === 'string' ? args.workspace : process.cwd();
+        return {
+            success: true,
+            ...suggestChangeImpactConfig(workspace),
+            note: 'Suggestions are heuristic scaffold only; the draft must be reviewed and saved into repo change-impact config before it takes effect. Nothing is executed.',
+        };
+    },
+};

package/src/commands/low-family/session-host.ts

@@ -0,0 +1,274 @@
+/**
+ * RF-ROUTER LOW family — session-host control commands.
+ *
+ * Extracted verbatim from DaemonCommandRouter.executeDaemonCommand. Each handler
+ * reads only ctx.deps.sessionHostControl (+ cliManager for the resume/restart
+ * hosted-session restore) and returns the same CommandRouterResult as before.
+ * The trace/summarize helpers were `this`-free module functions in router.ts and
+ * are relocated here unchanged.
+ */
+import type { HostedCliRuntimeDescriptor } from '../cli-manager.js';
+import { recordDebugTrace } from '../../logging/debug-trace.js';
+import { getSessionHostSurfaceKind, partitionSessionHostRecords } from '../../session-host/runtime-surface.js';
+import type { LowFamilyContext, LowFamilyHandler } from './types.js';
+
+function toHostedCliRuntimeDescriptor(record: any): HostedCliRuntimeDescriptor | null {
+    if (!record || typeof record !== 'object') return null;
+    const runtimeId = typeof record.sessionId === 'string' ? record.sessionId : '';
+    const cliType = typeof record.providerType === 'string' ? record.providerType : '';
+    const workspace = typeof record.workspace === 'string' ? record.workspace : '';
+    if (!runtimeId || !cliType || !workspace) return null;
+    return {
+        runtimeId,
+        runtimeKey: typeof record.runtimeKey === 'string' ? record.runtimeKey : undefined,
+        displayName: typeof record.displayName === 'string' ? record.displayName : undefined,
+        workspaceLabel: typeof record.workspaceLabel === 'string' ? record.workspaceLabel : undefined,
+        lifecycle: typeof record.lifecycle === 'string' ? record.lifecycle as HostedCliRuntimeDescriptor['lifecycle'] : undefined,
+        recoveryState: typeof record.meta?.runtimeRecoveryState === 'string'
+            ? String(record.meta.runtimeRecoveryState)
+            : null,
+        cliType,
+        workspace,
+        cliArgs: Array.isArray(record.meta?.cliArgs) ? record.meta.cliArgs as string[] : [],
+        providerSessionId: typeof record.meta?.providerSessionId === 'string'
+            ? String(record.meta.providerSessionId)
+            : undefined,
+    };
+}
+
+function getWriteConflictOwnerClientId(error: unknown): string | undefined {
+    const message = typeof error === 'string'
+        ? error
+        : error instanceof Error
+            ? error.message
+            : '';
+    const match = /^Write owned by\s+(.+)$/.exec(message.trim());
+    return match?.[1]?.trim() || undefined;
+}
+
+function summarizeSessionHostRecord(result: unknown): Record<string, unknown> {
+    if (!result || typeof result !== 'object') return {};
+    const record = result as Record<string, any>;
+    return {
+        runtimeKey: typeof record.runtimeKey === 'string' ? record.runtimeKey : undefined,
+        lifecycle: typeof record.lifecycle === 'string' ? record.lifecycle : undefined,
+        surfaceKind: getSessionHostSurfaceKind(record as any),
+        attachedClientCount: Array.isArray(record.attachedClients) ? record.attachedClients.length : undefined,
+        hasWriteOwner: !!record.writeOwner,
+        writeOwnerClientId: typeof record.writeOwner?.clientId === 'string' ? record.writeOwner.clientId : undefined,
+    };
+}
+
+function summarizeSessionHostRecords(result: unknown): Record<string, unknown> {
+    const records = Array.isArray(result) ? result : [];
+    const groups = partitionSessionHostRecords(records as any[]);
+    return {
+        sessionCount: records.length,
+        liveRuntimeCount: groups.liveRuntimes.length,
+        recoverySnapshotCount: groups.recoverySnapshots.length,
+        inactiveRecordCount: groups.inactiveRecords.length,
+    };
+}
+
+function summarizeSessionHostDiagnostics(result: unknown): Record<string, unknown> {
+    const diagnostics = result && typeof result === 'object' ? result as Record<string, any> : {};
+    const sessions = Array.isArray(diagnostics.sessions) ? diagnostics.sessions : [];
+    return {
+        runtimeCount: typeof diagnostics.runtimeCount === 'number' ? diagnostics.runtimeCount : undefined,
+        ...summarizeSessionHostRecords(sessions),
+    };
+}
+
+function summarizeSessionHostPruneResult(result: unknown): Record<string, unknown> {
+    const value = result && typeof result === 'object' ? result as Record<string, any> : {};
+    return {
+        duplicateGroupCount: typeof value.duplicateGroupCount === 'number' ? value.duplicateGroupCount : undefined,
+        prunedCount: Array.isArray(value.prunedSessionIds) ? value.prunedSessionIds.length : undefined,
+        keptCount: Array.isArray(value.keptSessionIds) ? value.keptSessionIds.length : undefined,
+    };
+}
+
+async function traceSessionHostAction<T>(
+    action: string,
+    args: any,
+    run: () => Promise<T>,
+    summarizeResult?: (result: T) => Record<string, unknown>,
+): Promise<T> {
+    const interactionId = typeof args?._interactionId === 'string' ? args._interactionId : undefined;
+    const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : undefined;
+    const requestedPayload: Record<string, unknown> = { action };
+    if (sessionId) requestedPayload.sessionId = sessionId;
+    if (typeof args?.clientId === 'string') requestedPayload.clientId = args.clientId;
+    if (typeof args?.signal === 'string') requestedPayload.signal = args.signal;
+    if (typeof args?.providerType === 'string') requestedPayload.providerType = args.providerType;
+    if (typeof args?.workspace === 'string') requestedPayload.workspace = args.workspace;
+    if (typeof args?.dryRun === 'boolean') requestedPayload.dryRun = args.dryRun;
+
+    recordDebugTrace({
+        interactionId,
+        category: 'session_host',
+        stage: 'action_requested',
+        level: 'info',
+        sessionId,
+        payload: requestedPayload,
+    });
+
+    try {
+        const result = await run();
+        recordDebugTrace({
+            interactionId,
+            category: 'session_host',
+            stage: 'action_result',
+            level: 'info',
+            sessionId,
+            payload: {
+                ...requestedPayload,
+                success: true,
+                ...(summarizeResult ? summarizeResult(result) : {}),
+            },
+        });
+        return result;
+    } catch (error: any) {
+        recordDebugTrace({
+            interactionId,
+            category: 'session_host',
+            stage: 'action_failed',
+            level: 'error',
+            sessionId,
+            payload: {
+                ...requestedPayload,
+                error: error?.message || String(error),
+                failureKind: getWriteConflictOwnerClientId(error) ? 'write_conflict' : 'request_failed',
+                conflictOwnerClientId: getWriteConflictOwnerClientId(error),
+            },
+        });
+        throw error;
+    }
+}
+
+export const sessionHostHandlers: Record<string, LowFamilyHandler> = {
+    session_host_get_diagnostics: async (ctx: LowFamilyContext, args: any) => {
+        if (!ctx.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+        const diagnostics = await traceSessionHostAction('session_host_get_diagnostics', args, () => ctx.deps.sessionHostControl!.getDiagnostics({
+            includeSessions: args?.includeSessions !== false,
+            limit: Number(args?.limit) || undefined,
+        }), (result) => ({
+            includeSessions: args?.includeSessions !== false,
+            limit: Number(args?.limit) || undefined,
+            ...summarizeSessionHostDiagnostics(result),
+        }));
+        return { success: true, diagnostics };
+    },
+
+    session_host_list_sessions: async (ctx: LowFamilyContext, args: any) => {
+        if (!ctx.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+        const sessions = await traceSessionHostAction('session_host_list_sessions', args, () => ctx.deps.sessionHostControl!.listSessions(), (records) => summarizeSessionHostRecords(records));
+        return { success: true, sessions };
+    },
+
+    session_host_stop_session: async (ctx: LowFamilyContext, args: any) => {
+        if (!ctx.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+        const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+        if (!sessionId) return { success: false, error: 'sessionId required' };
+        const record = await traceSessionHostAction('session_host_stop_session', args, () => ctx.deps.sessionHostControl!.stopSession(sessionId), (result) => summarizeSessionHostRecord(result));
+        return { success: true, record };
+    },
+
+    session_host_resume_session: async (ctx: LowFamilyContext, args: any) => {
+        if (!ctx.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+        const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+        if (!sessionId) return { success: false, error: 'sessionId required' };
+        const record = await traceSessionHostAction('session_host_resume_session', args, async () => {
+            const nextRecord = await ctx.deps.sessionHostControl!.resumeSession(sessionId);
+            const hosted = toHostedCliRuntimeDescriptor(nextRecord);
+            if (hosted) {
+                await ctx.deps.cliManager.restoreHostedSessions([hosted]);
+            }
+            return nextRecord;
+        }, (result) => ({
+            ...summarizeSessionHostRecord(result),
+            restoredHostedSession: !!toHostedCliRuntimeDescriptor(result),
+        }));
+        return { success: true, record };
+    },
+
+    session_host_restart_session: async (ctx: LowFamilyContext, args: any) => {
+        if (!ctx.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+        const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+        if (!sessionId) return { success: false, error: 'sessionId required' };
+        const record = await traceSessionHostAction('session_host_restart_session', args, async () => {
+            const nextRecord = await ctx.deps.sessionHostControl!.restartSession(sessionId);
+            const hosted = toHostedCliRuntimeDescriptor(nextRecord);
+            if (hosted) {
+                await ctx.deps.cliManager.restoreHostedSessions([hosted]);
+            }
+            return nextRecord;
+        }, (result) => ({
+            ...summarizeSessionHostRecord(result),
+            restoredHostedSession: !!toHostedCliRuntimeDescriptor(result),
+        }));
+        return { success: true, record };
+    },
+
+    session_host_send_signal: async (ctx: LowFamilyContext, args: any) => {
+        if (!ctx.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+        const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+        const signal = typeof args?.signal === 'string' ? args.signal : '';
+        if (!sessionId) return { success: false, error: 'sessionId required' };
+        if (!signal) return { success: false, error: 'signal required' };
+        const record = await traceSessionHostAction('session_host_send_signal', args, () => ctx.deps.sessionHostControl!.sendSignal(sessionId, signal), (result) => summarizeSessionHostRecord(result));
+        return { success: true, record };
+    },
+
+    session_host_force_detach_client: async (ctx: LowFamilyContext, args: any) => {
+        if (!ctx.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+        const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+        const clientId = typeof args?.clientId === 'string' ? args.clientId : '';
+        if (!sessionId) return { success: false, error: 'sessionId required' };
+        if (!clientId) return { success: false, error: 'clientId required' };
+        const record = await traceSessionHostAction('session_host_force_detach_client', args, () => ctx.deps.sessionHostControl!.forceDetachClient(sessionId, clientId), (result) => summarizeSessionHostRecord(result));
+        return { success: true, record };
+    },
+
+    session_host_prune_duplicate_sessions: async (ctx: LowFamilyContext, args: any) => {
+        if (!ctx.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+        const result = await traceSessionHostAction('session_host_prune_duplicate_sessions', args, () => ctx.deps.sessionHostControl!.pruneDuplicateSessions({
+            providerType: typeof args?.providerType === 'string' ? args.providerType : undefined,
+            workspace: typeof args?.workspace === 'string' ? args.workspace : undefined,
+            dryRun: args?.dryRun === true,
+        }), (value) => summarizeSessionHostPruneResult(value));
+        return { success: true, result };
+    },
+
+    session_host_acquire_write: async (ctx: LowFamilyContext, args: any) => {
+        if (!ctx.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+        const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+        const clientId = typeof args?.clientId === 'string' ? args.clientId : '';
+        const ownerType = args?.ownerType === 'agent' ? 'agent' : 'user';
+        if (!sessionId) return { success: false, error: 'sessionId required' };
+        if (!clientId) return { success: false, error: 'clientId required' };
+        const record = await traceSessionHostAction('session_host_acquire_write', args, () => ctx.deps.sessionHostControl!.acquireWrite({
+            sessionId,
+            clientId,
+            ownerType,
+            force: args?.force !== false,
+        }), (result) => ({
+            ...summarizeSessionHostRecord(result),
+            ownerType,
+        }));
+        return { success: true, record };
+    },
+
+    session_host_release_write: async (ctx: LowFamilyContext, args: any) => {
+        if (!ctx.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+        const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+        const clientId = typeof args?.clientId === 'string' ? args.clientId : '';
+        if (!sessionId) return { success: false, error: 'sessionId required' };
+        if (!clientId) return { success: false, error: 'clientId required' };
+        const record = await traceSessionHostAction('session_host_release_write', args, () => ctx.deps.sessionHostControl!.releaseWrite({
+            sessionId,
+            clientId,
+        }), (result) => summarizeSessionHostRecord(result));
+        return { success: true, record };
+    },
+};

package/src/commands/low-family/spec-providerdev.ts

@@ -0,0 +1,217 @@
+/**
+ * RF-ROUTER LOW family — provider-dev / spec debug commands.
+ *
+ * Powers the dev console's spec editor: read/write a session's spec.json, validate
+ * an in-progress spec, and preview condition/section resolution against a live
+ * session's screen. Extracted verbatim from executeDaemonCommand; reads only
+ * ctx.deps.sessionRegistry + ctx.deps.cliManager. resolveSpecPathInProviders (a
+ * `this`-free module helper) is relocated here unchanged.
+ */
+import type { LowFamilyContext, LowFamilyHandler } from './types.js';
+
+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 };
+}
+
+export const specProviderDevHandlers: Record<string, LowFamilyHandler> = {
+    get_spec_debug: async (ctx: LowFamilyContext, args: any) => {
+        const sessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim()
+            : typeof args?.sessionId === 'string' ? args.sessionId.trim() : '';
+        if (!sessionId) return { success: false, error: 'targetSessionId required' };
+        const target = ctx.deps.sessionRegistry.get(sessionId);
+        if (!target) return { success: false, error: 'Session not found', sessionId };
+        const adapterObj = ctx.deps.cliManager.findAdapter(target.providerType, { instanceKey: sessionId })?.adapter;
+        const snapshot = adapterObj
+            ? (typeof (adapterObj as any).getDebugSnapshot === 'function'
+                ? (adapterObj as any).getDebugSnapshot()
+                : typeof (adapterObj as any).getDebugState === 'function'
+                    ? (adapterObj as any).getDebugState()
+                    : null)
+            : null;
+        return {
+            success: true,
+            sessionId,
+            providerType: target.providerType,
+            isSpecProvider: snapshot !== null,
+            snapshot,
+        };
+    },
+
+    // ── 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.
+    get_spec_source: async (ctx: LowFamilyContext, args: any) => {
+        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 = ctx.deps.sessionRegistry.get(sessionId);
+            const adapterObj = target ? ctx.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 };
+        }
+    },
+
+    write_spec_source: async (_ctx: LowFamilyContext, args: any) => {
+        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.
+    validate_spec: async (_ctx: LowFamilyContext, args: any) => {
+        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.
+    eval_condition_preview: async (ctx: LowFamilyContext, args: any) => {
+        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 = ctx.deps.sessionRegistry.get(sessionId);
+        if (!target) return { success: false, error: 'Session not found', sessionId };
+        const adapterObj = ctx.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. Accepts an in-progress sections map so it previews
+    //    unsaved edits.
+    resolve_section_preview: async (ctx: LowFamilyContext, args: any) => {
+        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 = ctx.deps.sessionRegistry.get(sessionId);
+        if (!target) return { success: false, error: 'Session not found', sessionId };
+        const adapterObj = ctx.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}` };
+        }
+    },
+};