@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

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}` };
+        }
+    },
+};

package/src/commands/low-family/status-meta.ts

@@ -0,0 +1,112 @@
+/**
+ * RF-ROUTER LOW family — status/metadata + user-name commands.
+ *
+ * Extracted verbatim from DaemonCommandRouter.executeDaemonCommand. Each handler
+ * reads only ctx.deps (+ process-global config/status builders) and returns the
+ * same CommandRouterResult the inlined case did. get_session_info aggregates the
+ * session/coordinator registries the router already holds via deps; none of these
+ * touch the router's inline-mesh cache or other instance state.
+ */
+import { loadConfig, updateConfig } from '../../config/config.js';
+import { buildMachineInfo, buildStatusSnapshot } from '../../status/snapshot.js';
+import { getDaemonBuildInfo } from '../../build-info.js';
+import { getCoordinatorForSession } from '../../mesh/coordinator-registry.js';
+import type { LowFamilyContext, LowFamilyHandler } from './types.js';
+
+export const statusMetaHandlers: Record<string, LowFamilyHandler> = {
+    set_user_name: async (_ctx: LowFamilyContext, args: any) => {
+        const name = args?.userName;
+        if (!name || typeof name !== 'string') throw new Error('userName required');
+        updateConfig({ userName: name });
+        return { success: true, userName: name };
+    },
+
+    get_status_metadata: async (ctx: LowFamilyContext, _args: any) => {
+        const snapshot = buildStatusSnapshot({
+            allStates: ctx.deps.instanceManager.collectAllStates(),
+            cdpManagers: ctx.deps.cdpManagers,
+            providerLoader: ctx.deps.providerLoader,
+            detectedIdes: ctx.deps.detectedIdes.value,
+            instanceId: ctx.deps.statusInstanceId || loadConfig().machineId || 'daemon',
+            version: ctx.deps.statusVersion || 'unknown',
+            profile: 'metadata',
+        });
+        // Surface the daemon's build stamp so coordinators (mesh_status)
+        // can detect a running daemon that predates a just-merged fix and
+        // is awaiting deploy/restart. Sibling of `status` to avoid
+        // perturbing the dashboard status snapshot shape.
+        return { success: true, status: snapshot, daemonBuild: getDaemonBuildInfo() };
+    },
+
+    get_machine_runtime_stats: async (_ctx: LowFamilyContext, _args: any) => {
+        return {
+            success: true,
+            machine: buildMachineInfo('full'),
+            timestamp: Date.now(),
+        };
+    },
+
+    // Session-info popup data. Aggregates whatever the daemon knows
+    // about a single live session into one envelope so the dashboard
+    // doesn't need to stitch together status + coordinator registry +
+    // session registry on the client. Includes the actual system
+    // prompt that was injected at launch when the session is a mesh
+    // coordinator — that's the "what prompt did the agent see?"
+    // question the info-icon dialog is meant to answer.
+    get_session_info: 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' };
+        // Fetch both lookups up front. We used to bail with "Session not
+        // found" when sessionRegistry forgot the SID (auto-cleanup,
+        // daemon restart with the session not yet restored, etc), which
+        // hid the coordinator-side metadata even though the
+        // coordinator-registry still has it. Now we return whichever
+        // side we have. The dashboard renders "no coordinator-specific
+        // prompt" only when *neither* side knows the session.
+        const target = ctx.deps.sessionRegistry.get(sessionId);
+        const coord = getCoordinatorForSession(sessionId);
+        if (!target && !coord) return { success: false, error: 'Session not found', sessionId };
+        const adapter = target
+            ? ctx.deps.cliManager.findAdapter(target.providerType, { instanceKey: sessionId })?.adapter
+            : undefined;
+        const runtimeMeta = (adapter && typeof (adapter as any).getRuntimeMetadata === 'function')
+            ? (adapter as any).getRuntimeMetadata()
+            : undefined;
+        // Launch metadata (args / cwd / extra-env keys / providerSessionId) is
+        // derived from the live adapter's spawn plan; only available while the
+        // adapter is alive (resumed-from-history sessions report nothing here).
+        const launchInfo = (adapter && typeof (adapter as any).getLaunchInfo === 'function')
+            ? (adapter as any).getLaunchInfo()
+            : undefined;
+        const providerType = target?.providerType || coord?.cliType || '';
+        const providerMetaForSession = providerType
+            ? ctx.deps.providerLoader.resolve?.(providerType) || ctx.deps.providerLoader.getMeta(providerType)
+            : undefined;
+        return {
+            success: true,
+            session: {
+                sessionId,
+                providerType,
+                providerName: providerMetaForSession?.name,
+                transport: target?.transport,
+                workspace: (target as any)?.workspace || coord?.workspace,
+                spawnedAtMs: (target as any)?.spawnedAtMs || coord?.startedAt,
+                // providerSessionId now comes from the live adapter's launch info
+                // (the registry target never carried it — it was always undefined).
+                providerSessionId: launchInfo?.providerSessionId || (target as any)?.providerSessionId,
+                runtimeMetadata: runtimeMeta,
+                launch: launchInfo,
+            },
+            coordinator: coord ? {
+                meshId: coord.meshId,
+                startedAt: coord.startedAt,
+                cliType: coord.cliType,
+                systemPrompt: coord.systemPrompt,
+                extraSystemPrompt: coord.extraSystemPrompt,
+                injection: coord.injection,
+                mcpConfigPath: coord.mcpConfigPath,
+            } : null,
+        };
+    },
+};

package/src/commands/low-family/types.ts

@@ -0,0 +1,39 @@
+/**
+ * RF-ROUTER LOW family — shared types for the extracted low-coupling command
+ * handlers. Each handler is a pure function of (context, args): it reads only the
+ * router deps it needs and returns the exact CommandRouterResult the original
+ * `executeDaemonCommand` switch case returned, so the router facade is unchanged.
+ *
+ * Registry dispatch: DaemonCommandRouter.executeDaemonCommand looks up the cmd in
+ * lowFamilyRegistry BEFORE its switch; a hit returns the handler result, a miss
+ * falls through to the remaining switch (and ultimately CommandHandler delegation).
+ */
+import type { CommandRouterDeps, CommandRouterResult } from '../router.js';
+
+/** Mesh record resolved from the router's inline-mesh cache + local config. */
+export type ResolvedMeshForCommand = {
+    mesh: any;
+    inline: boolean;
+    source: 'inline_cache' | 'inline_bootstrap' | 'local_config';
+} | null;
+
+export interface LowFamilyContext {
+    deps: CommandRouterDeps;
+    /**
+     * Bound `DaemonCommandRouter.getMeshForCommand`. A handful of LOW handlers
+     * (mesh-node-logs) must resolve a mesh node's owning daemonId from the
+     * router's inline-mesh cache, which is router instance state not present in
+     * `deps`. The router injects it at dispatch; handlers that don't need it
+     * ignore it. Optional so unit tests can omit it (and assert the guarded
+     * fallback) without constructing a full router.
+     */
+    getMeshForCommand?: (
+        meshId: string,
+        inlineMesh?: unknown,
+        options?: { preferInline?: boolean },
+    ) => Promise<ResolvedMeshForCommand>;
+}
+
+export type LowFamilyHandler = (ctx: LowFamilyContext, args: any) => Promise<CommandRouterResult>;
+
+export type LowFamilyRegistry = Map<string, LowFamilyHandler>;

package/src/commands/med-family/cli-agent.ts

@@ -0,0 +1,270 @@
+/**
+ * RF-ROUTER MED family — CLI/ACP agent + saved-session + restart commands.
+ *
+ * launch_cli, stop_cli / set_cli_view_mode / record_provider_pty, agent_command,
+ * list_saved_sessions and restart_session. launch_cli and agent_command stamp
+ * mesh-worker relay metadata and surface worktree-bootstrap-pending hints around a
+ * delegation to cliManager. restart_session dispatches IDE restarts (via ctx.stopIde
+ * + ctx.launchIde — no executeDaemonCommand recursion) or CLI/ACP restarts.
+ * Extracted verbatim from executeDaemonCommand.
+ */
+import { meshNodeIdMatches } from '@adhdev/mesh-shared';
+import { supportsExplicitSessionResume } from '../cli-manager.js';
+import { loadState } from '../../config/state-store.js';
+import { getRecentActivity } from '../../config/recent-activity.js';
+import { getSavedProviderSessions } from '../../config/saved-sessions.js';
+import { listProviderHistorySessions } from '../../config/chat-history.js';
+import { buildMeshWorkerRelayStamp } from '../../mesh/mesh-events-utils.js';
+import { readStringValue } from '../router.js';
+import type { MedFamilyContext, MedFamilyHandler } from './types.js';
+
+export const cliAgentHandlers: Record<string, MedFamilyHandler> = {
+    launch_cli: async (ctx: MedFamilyContext, args: any) => {
+        // The coordinator routing anchor (meshCoordinatorDaemonId) is stamped
+        // upstream by mesh_launch_session, which resolves
+        // coordinatorNode.daemonId || ctx.localDaemonId || ctx.localMachineId and
+        // fail-closes for a remote node when none resolve. We deliberately do NOT
+        // self-stamp this daemon's own id when the field is missing: for a
+        // P2P-relayed remote worker launch, stamping the worker's own id would make
+        // the self-forward gate (mesh-events-coordinator: daemonIdsEquivalent) treat the
+        // worker as its own coordinator, suppressing the spontaneous completion-event
+        // forward and leaving the event in the pending inbox until a read_chat
+        // reconcile drains it. If the anchor is genuinely absent here, leave it
+        // absent rather than poison the routing.
+        const launchResult = await ctx.deps.cliManager.handleCliCommand('launch_cli', args);
+        // Bug C fix (part 1): when launching a mesh node worker session, surface
+        // bootstrapPending:true if the node's worktree bootstrap is still running.
+        // This is informational — the launch is NOT blocked here (blocking is done
+        // upstream by getWorktreeBootstrapLaunchBlock in the MCP layer).
+        const meshNodeId = readStringValue((args?.settings as any)?.meshNodeId);
+        const meshId = readStringValue((args?.settings as any)?.meshNodeFor);
+        if (meshNodeId && meshId && launchResult?.success !== false) {
+            try {
+                const { getMesh } = await import('../../config/mesh-config.js');
+                const meshObj = getMesh(meshId) ?? ctx.getCachedInlineMesh(meshId);
+                const nodeObj = Array.isArray(meshObj?.nodes)
+                    ? meshObj.nodes.find((n: any) => meshNodeIdMatches(n, meshNodeId))
+                    : undefined;
+                const bootstrapStatus = readStringValue(nodeObj?.worktreeBootstrap?.status);
+                if (bootstrapStatus === 'running') {
+                    return { success: true, ...launchResult, bootstrapPending: true };
+                }
+            } catch { /* best-effort — do not fail launch for bootstrap probe errors */ }
+        }
+        return launchResult;
+    },
+
+    stop_cli: async (ctx: MedFamilyContext, args: any) => {
+        return ctx.deps.cliManager.handleCliCommand('stop_cli', args);
+    },
+    set_cli_view_mode: async (ctx: MedFamilyContext, args: any) => {
+        return ctx.deps.cliManager.handleCliCommand('set_cli_view_mode', args);
+    },
+    record_provider_pty: async (ctx: MedFamilyContext, args: any) => {
+        return ctx.deps.cliManager.handleCliCommand('record_provider_pty', args);
+    },
+
+    // Daemon-owned per-session user Mute/Hide. Replaces the old browser-local
+    // localStorage layer: the user's manual hide/mute for a conversation is stored
+    // in-memory on the live session's settings (userHidden / userMuted) and rides
+    // the SAME status snapshot pipeline as the coordinator-policy surfaceHidden
+    // flag, so every client of this daemon sees the same state. In-memory only —
+    // resets on daemon restart (coordinator-spawned sessions re-derive their hidden
+    // default from mesh policy on relaunch). Passing null/undefined for a field
+    // leaves it unchanged; pass an explicit boolean to set, or false to clear an
+    // earlier hide/mute (e.g. unmute a coordinator-spawned worker overrides the
+    // policy default until restart).
+    set_conversation_prefs: async (ctx: MedFamilyContext, args: any) => {
+        const sessionId = readStringValue(args?.sessionId, (args as any)?.targetSessionId, (args as any)?.instanceId);
+        if (!sessionId) return { success: false, error: 'sessionId required' };
+        const inst = ctx.deps.instanceManager.getInstance(sessionId);
+        if (!inst || typeof inst.updateSettings !== 'function') {
+            return { success: false, error: 'Session not found or does not support preferences' };
+        }
+        const patch: Record<string, unknown> = {};
+        if (typeof args?.hidden === 'boolean') patch.userHidden = args.hidden;
+        if (typeof args?.muted === 'boolean') patch.userMuted = args.muted;
+        if (!Object.keys(patch).length) return { success: false, error: 'Nothing to update (hidden and/or muted required)' };
+        inst.updateSettings(patch);
+        // Push a fresh status snapshot so all clients see the updated
+        // surfaceHidden/muted immediately (cloud path). The standalone server has a
+        // parallel broadcast gate keyed on the command name (see daemon-standalone).
+        ctx.deps.onStatusChange?.();
+        return { success: true, sessionId, ...patch };
+    },
+
+    agent_command: async (ctx: MedFamilyContext, args: any) => {
+        // Relay-safety stamp: a dispatch carrying meshContext.coordinatorDaemonId
+        // (mesh_send_task / queue assignment over P2P) is the worker daemon's chance
+        // to persist the coordinator routing anchor onto the target session BEFORE the
+        // turn runs. Without meshCoordinatorDaemonId on the session, the core forwarder
+        // (injectMeshSystemMessage) cannot resolve a remote coordinator target, so the
+        // completion event sits in the pending queue until a read_chat reconcile drains
+        // it. Stamping here makes a reused/relaunched remote session relay-safe at
+        // dispatch time even when it was not launched via mesh_launch_session.
+        {
+            const dispatchSessionId = readStringValue(args?.targetSessionId, (args as any)?.sessionId, (args as any)?.instanceId);
+            const dispatchMeshContext = args?.meshContext as Record<string, unknown> | undefined;
+            if (dispatchSessionId && dispatchMeshContext) {
+                try {
+                    const inst = ctx.deps.instanceManager.getInstance(dispatchSessionId);
+                    if (inst && typeof inst.updateSettings === 'function') {
+                        const stamp = buildMeshWorkerRelayStamp(
+                            inst.getState?.()?.settings as Record<string, unknown> | undefined,
+                            {
+                                meshId: dispatchMeshContext.meshId,
+                                nodeId: dispatchMeshContext.nodeId,
+                                coordinatorDaemonId: dispatchMeshContext.coordinatorDaemonId,
+                                // Session-level anchor: preserved across the P2P dispatch to a
+                                // remote worker so its completion echoes back to the right session.
+                                coordinatorSessionId: dispatchMeshContext.coordinatorSessionId,
+                            },
+                        );
+                        if (stamp) inst.updateSettings(stamp);
+                    }
+                } catch { /* best-effort — dispatch still proceeds without the stamp */ }
+            }
+        }
+        // Bug C fix / bootstrapPending dispatch gap: a task dispatched to a mesh node
+        // whose worktree bootstrap is STILL running must NOT be injected yet. Before this
+        // gate the dispatch proceeded and the prompt landed in the session's input buffer
+        // while the provider (e.g. claude CLI) was not yet ready to consume it — the inject
+        // was silently swallowed (the chat bubble showed the text but the session never
+        // transitioned to generating and never claimed the task). The prior code only
+        // ANNOTATED the already-completed dispatch with 'bootstrap_still_running' after the
+        // fact, which did not close the gap. Defer instead: refuse the inject with a
+        // recoverable signal so the coordinator re-sends once the node is ready (the
+        // confirmed "re-send to a ready session works" path), mirroring the queued-delivery
+        // contract for busy sessions. send_chat only — non-task actions still pass through.
+        const meshCtx = args?.meshContext as Record<string, unknown> | undefined;
+        const dispatchNodeId = readStringValue(meshCtx?.nodeId);
+        const dispatchMeshId = readStringValue(meshCtx?.meshId);
+        const isSendChat = args?.action === 'send_chat';
+        if (isSendChat && dispatchNodeId && dispatchMeshId) {
+            try {
+                const { getMesh } = await import('../../config/mesh-config.js');
+                // COMPLETION-PROPAGATION F6 (C1 SSOT): read the router's synchronous inline mesh
+                // cache FIRST, falling back to getMesh only when the inline view has nothing. The
+                // inline cache is the authoritative bootstrap-status source — markWorktreeBootstrapTerminalState
+                // stamps 'complete'/'failed' into it SYNCHRONOUSLY, then persists to local config
+                // (what getMesh reads) via a DETACHED async import chain that lags. Reading getMesh
+                // first therefore observed a stale 'running' and deferred a dispatch whose worktree
+                // was already bootstrapped — the stale-'running' defer this eliminates. Inline-first
+                // makes the freshest single source of truth win for both the running and terminal states.
+                const meshObj = ctx.getCachedInlineMesh(dispatchMeshId) ?? getMesh(dispatchMeshId);
+                const nodeObj = Array.isArray(meshObj?.nodes)
+                    ? meshObj.nodes.find((n: any) => meshNodeIdMatches(n, dispatchNodeId))
+                    : undefined;
+                // COMPLETION-PROPAGATION F7 (C2): the single shared consume-ready/bootstrap-pending
+                // defer predicate (honors the stale-'running' git-clean backstop internally), reused
+                // by the local queue-claim gate too so remote and local dispatch agree on when to defer.
+                const { shouldDeferDispatchForBootstrap } = await import('../../mesh/worktree-bootstrap-config.js');
+                if (shouldDeferDispatchForBootstrap(nodeObj as any)) {
+                    return {
+                        success: false,
+                        recoverable: true,
+                        dispatched: false,
+                        code: 'mesh_node_bootstrap_pending',
+                        reason: 'bootstrap_still_running',
+                        nodeId: dispatchNodeId,
+                        meshId: dispatchMeshId,
+                        ...(readStringValue(meshCtx?.taskId) ? { taskId: readStringValue(meshCtx?.taskId) } : {}),
+                        error: `Node '${dispatchNodeId}' worktree bootstrap is still running; a task injected now would land in the session input buffer before the provider is ready to consume it and be silently lost. Dispatch deferred.`,
+                        nextAction: 'Wait for the worktree_bootstrap_complete event (or poll mesh_status until the node session is ready), then re-send the task with mesh_send_task. Alternatively use mesh_enqueue_task so the queue auto-assigns it once a ready session is available.',
+                    };
+                }
+            } catch { /* best-effort — if the bootstrap probe fails, fall through and dispatch */ }
+        }
+        return ctx.deps.cliManager.handleCliCommand('agent_command', args);
+    },
+
+    // ─── Logs ───
+    list_saved_sessions: async (ctx: MedFamilyContext, args: any) => {
+        const providerType = typeof args?.providerType === 'string'
+            ? args.providerType.trim()
+            : typeof args?.agentType === 'string'
+                ? args.agentType.trim()
+                : '';
+        const kind = args?.kind === 'acp' ? 'acp' : 'cli';
+        if (!providerType) {
+            return { success: false, error: 'providerType required' };
+        }
+
+        const wantsAll = args?.all === true;
+        const offset = wantsAll ? 0 : Math.max(0, Number(args?.offset) || 0);
+        const limit = wantsAll ? Number.MAX_SAFE_INTEGER : Math.max(1, Math.min(100, Number(args?.limit) || 30));
+        const requestedWorkspace = typeof args?.workspace === 'string' ? args.workspace.trim() : '';
+        const requestedProviderSessionId = typeof args?.providerSessionId === 'string'
+            ? args.providerSessionId.trim()
+            : typeof args?.activeProviderSessionId === 'string'
+                ? args.activeProviderSessionId.trim()
+                : '';
+        const providerMeta = ctx.deps.providerLoader.resolve?.(providerType) || ctx.deps.providerLoader.getMeta(providerType);
+        const { sessions: historySessions, hasMore, source } = listProviderHistorySessions(providerType, {
+            canonicalHistory: providerMeta?.nativeHistory,
+            offset,
+            limit,
+            historyBehavior: providerMeta?.historyBehavior,
+            scripts: providerMeta?.scripts as any,
+        });
+        const state = loadState();
+        const savedSessions = getSavedProviderSessions(state, { providerType, kind });
+        const recentSessions = getRecentActivity(state, 200)
+            .filter(entry => entry.providerType === providerType && entry.kind === kind && entry.providerSessionId);
+        const savedSessionById = new Map(savedSessions.map(entry => [entry.providerSessionId, entry]));
+        const recentSessionById = new Map(recentSessions.map(entry => [entry.providerSessionId!, entry]));
+        const canResumeById = supportsExplicitSessionResume(providerMeta?.resume);
+
+        return {
+            success: true,
+            sessions: historySessions.map(session => {
+                const saved = savedSessionById.get(session.historySessionId);
+                const recent = recentSessionById.get(session.historySessionId);
+                const workspace = saved?.workspace
+                    || recent?.workspace
+                    || session.workspace
+                    || (requestedWorkspace && requestedProviderSessionId === session.historySessionId ? requestedWorkspace : undefined);
+                return {
+                    id: session.historySessionId,
+                    providerSessionId: session.historySessionId,
+                    providerType,
+                    providerName: saved?.providerName || recent?.providerName || providerType,
+                    kind: saved?.kind || recent?.kind || kind,
+                    title: saved?.title || recent?.title || session.sessionTitle || session.preview || providerType,
+                    workspace,
+                    summaryMetadata: saved?.summaryMetadata || recent?.summaryMetadata,
+                    preview: session.preview,
+                    messageCount: session.messageCount,
+                    firstMessageAt: session.firstMessageAt,
+                    lastMessageAt: session.lastMessageAt,
+                    canResume: !!workspace && canResumeById,
+                    historySource: session.source,
+                    sourcePath: session.sourcePath,
+                    sourceMtimeMs: session.sourceMtimeMs,
+                };
+            }),
+            hasMore,
+            source,
+        };
+    },
+
+    // ─── restart_session: IDE / CLI / ACP unified ───
+    restart_session: async (ctx: MedFamilyContext, args: any) => {
+        const targetType = args?.cliType || args?.agentType || args?.ideType;
+        if (!targetType) throw new Error('cliType or ideType required');
+
+        // Check if IDE (in cdpManagers or provider category is ide)
+        const isIde = ctx.deps.cdpManagers.has(targetType) ||
+            ctx.deps.providerLoader.getMeta(targetType)?.category === 'ide';
+
+        if (isIde) {
+            // IDE restart: stop (with process kill) → launch
+            await ctx.stopIde(targetType, true);
+            const launchResult = await ctx.launchIde({ ideType: targetType, enableCdp: true, workspace: args?.workspace });
+            return { success: true, restarted: true, ideType: targetType, launch: launchResult };
+        }
+
+        // CLI/ACP restart: delegate to CliManager
+        return ctx.deps.cliManager.handleCliCommand('restart_session', args);
+    },
+};