@adhdev/daemon-core 0.9.82-rc.364 → 0.9.82-rc.366

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

@@ -0,0 +1,76 @@
+/**
+ * RF-ROUTER HIGH family — shared types for the extracted high-coupling command
+ * handlers. Like the LOW and MED families, each handler is a function of
+ * (context, args) that returns the exact CommandRouterResult the original
+ * `executeDaemonCommand` switch case returned, so the router facade is unchanged.
+ *
+ * HIGH handlers are the most router-coupled of the three families: in addition to
+ * the MED collaborators (mesh resolution, owner gating, inline-cache), they reach
+ * the router's aggregate-status memory cache and running-refine-job table — state
+ * the router owns and the `mesh_status` aggregate render and `get_mesh_review_inbox`
+ * re-entry both depend on. The router binds those onto HighFamilyContext at
+ * dispatch; they are NOT reachable from `deps`.
+ *
+ * Registry dispatch: DaemonCommandRouter.executeDaemonCommand looks up the cmd in
+ * highFamilyRegistry AFTER the LOW and MED registries and BEFORE its remaining
+ * switch; a hit returns the handler result, a miss falls through to the switch
+ * (and ultimately CommandHandler delegation).
+ */
+import type {
+    CommandRouterDeps,
+    CommandRouterResult,
+    MeshGitProbeCache,
+    MeshRefineJobHandle,
+} from '../router.js';
+import type { ResolvedMeshForCommand } from '../med-family/types.js';
+
+/**
+ * Router-private collaborators injected at dispatch. Each is a bound method or
+ * field of DaemonCommandRouter; handlers that don't need a given collaborator
+ * simply ignore it. The router owns this instance state (inline-mesh cache,
+ * aggregate-status memory cache, running-refine-job table, git-probe cache), so
+ * it cannot be read from `deps` — the registry receives bound references instead.
+ */
+export interface HighFamilyContext {
+    deps: CommandRouterDeps;
+
+    /** Bound `DaemonCommandRouter.getMeshForCommand`. */
+    getMeshForCommand: (
+        meshId: string,
+        inlineMesh?: unknown,
+        options?: { preferInline?: boolean },
+    ) => Promise<ResolvedMeshForCommand>;
+
+    /** Bound `DaemonCommandRouter.getCachedAggregateMeshStatus`. */
+    getCachedAggregateMeshStatus: (
+        meshId: string,
+        mesh?: any,
+        options?: { requireDirectPeerTruth?: boolean },
+    ) => any | null;
+
+    /** Bound `DaemonCommandRouter.rememberAggregateMeshStatus`. */
+    rememberAggregateMeshStatus: (meshId: string, snapshot: any, refreshReason: string) => any;
+
+    /**
+     * Bound `DaemonCommandRouter.execute`. `get_mesh_review_inbox` re-enters the
+     * router with a `mesh_status` refresh to obtain computed node fields; this is
+     * the same self-call the inlined case made.
+     */
+    execute: (cmd: string, args: any, source?: string) => Promise<CommandRouterResult>;
+
+    /** Router's aggregate-status memory cache (`.has()` probe in mesh_status). */
+    aggregateMeshStatusCache: Map<string, { builtAt: number; snapshot: any; queueRevision: string }>;
+
+    /** Router's running-refine-job table (surfaced as activeRefineJobs in mesh_status). */
+    runningRefineJobs: Map<string, MeshRefineJobHandle>;
+
+    /** Router's inline-mesh cache (launch_mesh_coordinator caches cloud inline mesh). */
+    inlineMeshCache: Map<string, any>;
+
+    /** Router's mesh git-probe cache (shared probe dedup for mesh_status). */
+    meshGitProbeCache: MeshGitProbeCache;
+}
+
+export type HighFamilyHandler = (ctx: HighFamilyContext, args: any) => Promise<CommandRouterResult | null>;
+
+export type HighFamilyRegistry = Map<string, HighFamilyHandler>;

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

@@ -0,0 +1,218 @@
+/**
+ * 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);
+    },
+
+    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 */ }
+            }
+        }
+        const agentResult = await ctx.deps.cliManager.handleCliCommand('agent_command', args);
+        // Bug C fix (part 2): when dispatching a task to a mesh node session, override
+        // the dispatch acknowledgement risk reason to 'bootstrap_still_running' when
+        // the target node's worktree bootstrap is still running. Informational only —
+        // dispatch is NOT blocked.
+        const meshCtx = args?.meshContext as Record<string, unknown> | undefined;
+        const dispatchNodeId = readStringValue(meshCtx?.nodeId);
+        const dispatchMeshId = readStringValue(meshCtx?.meshId);
+        if (dispatchNodeId && dispatchMeshId && agentResult?.success !== false) {
+            try {
+                const { getMesh } = await import('../../config/mesh-config.js');
+                const meshObj = getMesh(dispatchMeshId) ?? ctx.getCachedInlineMesh(dispatchMeshId);
+                const nodeObj = Array.isArray(meshObj?.nodes)
+                    ? meshObj.nodes.find((n: any) => meshNodeIdMatches(n, dispatchNodeId))
+                    : undefined;
+                const bootstrapStatus = readStringValue(nodeObj?.worktreeBootstrap?.status);
+                if (bootstrapStatus === 'running') {
+                    return {
+                        success: true,
+                        ...agentResult,
+                        dispatchAcknowledgementRisk: true,
+                        dispatchAcknowledgementRiskReason: 'bootstrap_still_running',
+                        nextAction: 'Wait for worktree_bootstrap_complete event before dispatching work to this node.',
+                    };
+                }
+            } catch { /* best-effort */ }
+        }
+        return agentResult;
+    },
+
+    // ─── 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);
+    },
+};

package/src/commands/med-family/fast-forward.ts

@@ -0,0 +1,198 @@
+/**
+ * RF-ROUTER MED family — fast-forward / refine convergence commands.
+ *
+ * mesh_init, plan_mesh_refine_node, fast_forward_mesh_node, refine_mesh_node and
+ * batch_refine_mesh_nodes. These resolve the target node, forward to the owning
+ * daemon when the node is remote, and run (or plan) the fast-forward / refine
+ * convergence. Extracted verbatim from executeDaemonCommand; the async execute
+ * paths delegate back to the router's refine-job starters via ctx.
+ */
+import { daemonIdsEquivalent, meshNodeIdMatches } from '@adhdev/mesh-shared';
+import { fastForwardMeshNode } from '../../mesh/mesh-fast-forward.js';
+import { runMeshInit } from '../../mesh/mesh-init.js';
+import { detectCLIs } from '../../detection/cli-detector.js';
+import { buildMeshRefineValidationPlan } from '../router.js';
+import type { CommandRouterResult } from '../router.js';
+import type { MedFamilyContext, MedFamilyHandler } from './types.js';
+
+export const fastForwardHandlers: Record<string, MedFamilyHandler> = {
+    mesh_init: async (ctx: MedFamilyContext, args: any) => {
+        const workspace = typeof args?.workspace === 'string' && args.workspace.trim() ? args.workspace.trim() : process.cwd();
+        const mesh = args?.inlineMesh || {};
+        try {
+            const detected = await detectCLIs(ctx.deps.providerLoader, { includeVersion: true });
+            return { ...runMeshInit(mesh, workspace, detected, {
+                write: args?.write === true,
+                overwrite: args?.overwrite === true,
+            }) };
+        } catch (e: any) {
+            return { success: false, error: e?.message || String(e) };
+        }
+    },
+
+    plan_mesh_refine_node: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
+        if (!meshId || !nodeId) return { success: false, error: 'meshId and nodeId required' };
+        // preferInline: plan is the dry-run sibling of refine — clone nodes must resolve.
+        const meshRecord = await ctx.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+        const mesh = meshRecord?.mesh;
+        const node = mesh?.nodes?.find((n: any) => meshNodeIdMatches(n, nodeId));
+        if (!node?.workspace) return { success: false, error: `Node '${nodeId}' workspace not found` };
+        return {
+            success: true,
+            dryRun: true,
+            nodeId,
+            workspace: node.workspace,
+            validationPlan: buildMeshRefineValidationPlan(mesh, node.workspace),
+            mergeWillRun: false,
+            cleanupWillRun: false,
+        };
+    },
+
+    fast_forward_mesh_node: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
+        let workspace = typeof args?.workspace === 'string' ? args.workspace.trim() : '';
+        let submoduleIgnorePaths = Array.isArray(args?.submoduleIgnorePaths)
+            ? args.submoduleIgnorePaths.filter((value: unknown): value is string => typeof value === 'string')
+            : undefined;
+        let nodeDaemonId: string | undefined;
+        let allowAutoPublishSubmoduleMainCommits = false;
+        if (meshId && nodeId) {
+            // preferInline so fast-forward can resolve inline-cache-only clone worktree nodes.
+            const meshRecord = await ctx.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+            const mesh = meshRecord?.mesh;
+            const node = mesh?.nodes?.find((n: any) => meshNodeIdMatches(n, nodeId));
+            if (!workspace) {
+                workspace = typeof node?.workspace === 'string' ? node.workspace.trim() : '';
+            }
+            if (!submoduleIgnorePaths && Array.isArray(node?.policy?.submoduleIgnorePaths)) {
+                submoduleIgnorePaths = node.policy.submoduleIgnorePaths.filter((value: unknown): value is string => typeof value === 'string');
+            }
+            allowAutoPublishSubmoduleMainCommits = mesh?.policy?.allowAutoPublishSubmoduleMainCommits === true;
+            nodeDaemonId = typeof node?.daemonId === 'string' ? node.daemonId.trim() : undefined;
+        }
+        // If the target node belongs to a remote daemon, forward the command there.
+        // _meshDirectDispatch prevents re-forwarding (and P2P self-dial) when the stored
+        // daemonId uses a legacy format that doesn't match the receiving daemon's identity.
+        const selfDaemonId = ctx.deps.statusInstanceId;
+        // daemonIdsEquivalent: a legacy-form stored daemonId that resolves to THIS
+        // machine's core must be treated as local (not remote) so it is not forwarded /
+        // P2P self-dialed. Equivalent → local.
+        const isRemote = nodeDaemonId && selfDaemonId && !daemonIdsEquivalent(nodeDaemonId, selfDaemonId);
+        if (isRemote && ctx.deps.dispatchMeshCommand && !args?._meshDirectDispatch) {
+            const forwarded = await ctx.deps.dispatchMeshCommand(nodeDaemonId!, 'fast_forward_mesh_node', {
+                ...(typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}),
+                workspace,
+                _meshDirectDispatch: true,
+            });
+            return (forwarded ?? { success: false, error: 'no response from remote node' }) as CommandRouterResult;
+        }
+        const result = await (fastForwardMeshNode({
+            meshId: meshId || undefined,
+            nodeId: nodeId || undefined,
+            workspace,
+            branch: typeof args?.branch === 'string' ? args.branch : undefined,
+            execute: args?.execute === true,
+            dryRun: args?.dryRun === true,
+            updateSubmodules: args?.updateSubmodules === true,
+            submoduleIgnorePaths,
+            mode: args?.mode === 'push' ? 'push' : 'merge',
+            pushSubmodules: args?.pushSubmodules === true,
+            allowAutoPublishSubmoduleMainCommits,
+        }) as Promise<unknown>);
+        return result as CommandRouterResult;
+    },
+
+    refine_mesh_node: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
+        if (!meshId || !nodeId) return { success: false, error: 'meshId and nodeId required' };
+
+        // Remote forward: a worktree node lives on its OWN daemon's machine, so the
+        // refine (cd into node.workspace, merge → push → cleanup) must run on THAT
+        // daemon — not the coordinator, whose filesystem has no such path. The sibling
+        // fast_forward_mesh_node / clone_mesh_node handlers already forward to the
+        // node's daemon; refine_mesh_node was the gap (the coordinator would cd into a
+        // non-existent local path and fail), so remote-machine worktrees could not be
+        // converged at all. Forward both dry-run (plan reads the worktree git state)
+        // and execute (async merge job) so the same machine that owns the worktree
+        // resolves it.
+        //
+        // coordinatorDaemonId: refine is ASYNC — the completed/failed event is queued
+        // on the executing daemon's pending-events queue scoped to a coordinator id and
+        // recovered by the coordinator's reconcile loop (pullRemoteNodeQueues →
+        // get_pending_mesh_events). Without stamping our own status id, the remote
+        // daemon would fall back to ITS OWN statusInstanceId as the coordinator
+        // (startMeshRefineJob), scoping the terminal event to the wrong inbox where the
+        // real coordinator never pulls it. Stamp the canonical status id (which is in
+        // the coordinator's self-identity set used to scope the remote drain) so the
+        // event routes back here. Preserve any caller-supplied coordinatorDaemonId.
+        //
+        // _meshDirectDispatch prevents re-forwarding (and P2P self-dial) once the call
+        // has landed on the owning daemon — that daemon then executes locally even if
+        // the stored daemonId uses a legacy form that doesn't match its own identity.
+        {
+            const meshRecordForForward = await ctx.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+            const forwardNode = meshRecordForForward?.mesh?.nodes?.find((n: any) => meshNodeIdMatches(n, nodeId));
+            const nodeDaemonId = typeof forwardNode?.daemonId === 'string' ? forwardNode.daemonId.trim() : undefined;
+            const selfDaemonId = ctx.deps.statusInstanceId;
+            // daemonIdsEquivalent: a legacy-form daemonId resolving to this machine's core
+            // is local — execute locally instead of forwarding. Equivalent → local.
+            const isRemote = nodeDaemonId && selfDaemonId && !daemonIdsEquivalent(nodeDaemonId, selfDaemonId);
+            if (isRemote && ctx.deps.dispatchMeshCommand && !args?._meshDirectDispatch) {
+                const callerCoordinatorDaemonId = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
+                    ? args.coordinatorDaemonId.trim()
+                    : undefined;
+                const forwarded = await ctx.deps.dispatchMeshCommand(nodeDaemonId!, 'refine_mesh_node', {
+                    ...(typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}),
+                    coordinatorDaemonId: callerCoordinatorDaemonId || selfDaemonId,
+                    _meshDirectDispatch: true,
+                });
+                return (forwarded ?? { success: false, error: 'no response from remote node' }) as CommandRouterResult;
+            }
+        }
+
+        // Dry-run (plan-only) is the default and stays synchronous: it does no
+        // validation/merge/push and returns the plan instantly. Only execute=true
+        // (and not dry_run) goes through the async refine job that actually
+        // validates → merges → pushes → cleans up. Mirrors the
+        // batch_refine_mesh_nodes / fast_forward_mesh_node dry_run/execute contract.
+        const isDryRun = args?.dryRun !== false && args?.execute !== true;
+        if (isDryRun) {
+            // preferInline: plan is the dry-run sibling of refine — clone nodes must resolve.
+            const meshRecord = await ctx.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+            const mesh = meshRecord?.mesh;
+            const node = mesh?.nodes?.find((n: any) => meshNodeIdMatches(n, nodeId));
+            if (!node?.workspace) return { success: false, error: `Node '${nodeId}' workspace not found` };
+            return {
+                success: true,
+                dryRun: true,
+                nodeId,
+                workspace: node.workspace,
+                validationPlan: buildMeshRefineValidationPlan(mesh, node.workspace),
+                mergeWillRun: false,
+                cleanupWillRun: false,
+                hint: 'Dry-run only — no merge/push/cleanup performed. Re-invoke with execute:true to converge this node.',
+            };
+        }
+        return ctx.startMeshRefineJob(meshId, nodeId, args);
+    },
+
+    batch_refine_mesh_nodes: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        if (!meshId) return { success: false, error: 'meshId required' };
+        const requestedNodeIds = Array.isArray(args?.nodeIds)
+            ? (args.nodeIds as unknown[]).filter((v): v is string => typeof v === 'string' && v.trim().length > 0).map(v => v.trim())
+            : undefined;
+        // Dry-run (plan-only) stays synchronous: it does no validation/merge and
+        // returns instantly. Execute goes through the async batch job — immediate
+        // {async:true, status:'accepted'} + background convergence + terminal event,
+        // matching the single-node refine_mesh_node contract so long validation
+        // suites can't time out the IPC and strand the coordinator.
+        const isDryRun = args?.dryRun !== false && args?.execute !== true;
+        if (isDryRun) return ctx.batchRefineMeshNodes(meshId, requestedNodeIds, args);
+        return ctx.startMeshRefineBatchJob(meshId, requestedNodeIds, args);
+    },
+};

package/src/commands/med-family/ide.ts

@@ -0,0 +1,163 @@
+/**
+ * RF-ROUTER MED family — IDE lifecycle + provider/IDE detection commands.
+ *
+ * stop_ide, restart_ide, launch_ide, detect_provider, detect_ides. launch_ide
+ * spawns the IDE, connects CDP, registers extension providers and refreshes
+ * detection. restart_ide stops (with kill) then launches.
+ *
+ * launch_ide self-recursion: the original case bodies for restart_session
+ * (cli-agent family) and restart_ide re-entered `executeDaemonCommand('launch_ide')`.
+ * Lifting the launch_ide body into the module-level `launchIde(ctx, args)` helper
+ * lets those handlers invoke the launch directly (ctx.launchIde) without recursing
+ * back through the registry, while the launch_ide handler simply delegates to it.
+ */
+import { DaemonCdpManager } from '../../cdp/manager.js';
+import { registerExtensionProviders } from '../../cdp/setup.js';
+import { launchWithCdp } from '../../launch.js';
+import { loadConfig } from '../../config/config.js';
+import { loadState, saveState } from '../../config/state-store.js';
+import { resolveIdeLaunchWorkspace } from '../../config/workspaces.js';
+import { appendRecentActivity } from '../../config/recent-activity.js';
+import { detectIDEs } from '../../detection/ide-detector.js';
+import { detectCLI } from '../../detection/cli-detector.js';
+import { LOG } from '../../logging/logger.js';
+import type { CommandRouterResult } from '../router.js';
+import type { MedFamilyContext, MedFamilyHandler } from './types.js';
+
+/**
+ * IDE launch + CDP connect. Lifted verbatim from the original `launch_ide` switch
+ * case so restart_session / restart_ide can call it directly instead of recursing
+ * through executeDaemonCommand. Reads the router's CDP managers and detection
+ * caches via ctx.deps.
+ */
+export async function launchIde(ctx: MedFamilyContext, args: any): Promise<CommandRouterResult> {
+    const ideKey = args?.ideId || args?.ideType;
+    const resolvedWorkspace = resolveIdeLaunchWorkspace(
+        {
+            workspace: args?.workspace,
+            workspaceId: args?.workspaceId,
+            useDefaultWorkspace: args?.useDefaultWorkspace,
+        },
+        loadConfig(),
+    );
+    const launchArgs = {
+        ideId: ideKey,
+        workspace: resolvedWorkspace,
+        newWindow: args?.newWindow,
+    };
+    LOG.info('LaunchIDE', `target=${ideKey || 'auto'}`);
+    const result = await launchWithCdp(launchArgs);
+
+    if (result.success && result.port && result.ideId && !ctx.deps.cdpManagers.has(result.ideId)) {
+        const logFn = ctx.deps.getCdpLogFn
+            ? ctx.deps.getCdpLogFn(result.ideId)
+            : LOG.forComponent(`CDP:${result.ideId}`).asLogFn();
+        const provider = ctx.deps.providerLoader.getMeta(result.ideId);
+        const manager = new DaemonCdpManager(result.port, logFn, undefined, provider?.targetFilter);
+        const connected = await manager.connect();
+        if (connected) {
+            // Register active extension providers for this IDE in CDP manager
+            registerExtensionProviders(ctx.deps.providerLoader, manager, result.ideId);
+            ctx.deps.cdpManagers.set(result.ideId, manager);
+            LOG.info('CDP', `Connected: ${result.ideId} (port ${result.port})`);
+            LOG.info('CDP', `${ctx.deps.cdpManagers.size} IDE(s) connected`);
+
+            // Notify consumer (e.g. setupIdeInstance)
+            ctx.deps.onCdpManagerCreated?.(result.ideId, manager);
+        }
+    }
+    ctx.deps.onIdeConnected?.();
+    try {
+        const results = await detectIDEs(ctx.deps.providerLoader);
+        ctx.deps.detectedIdes.value = results;
+        ctx.deps.providerLoader.setIdeDetectionResults(results, true);
+    } catch { /* ignore detection refresh errors */ }
+    if (result.success && resolvedWorkspace) {
+        try {
+            const next = appendRecentActivity(loadState(), {
+                kind: 'ide',
+                providerType: result.ideId || ideKey,
+                providerName: result.ideId || ideKey,
+                workspace: resolvedWorkspace,
+                title: result.ideId || ideKey,
+            });
+            saveState(next);
+        } catch { /* ignore activity persist errors */ }
+    } else if (result.success && (result.ideId || ideKey)) {
+        try {
+            saveState(appendRecentActivity(loadState(), {
+                kind: 'ide',
+                providerType: result.ideId || ideKey,
+                providerName: result.ideId || ideKey,
+                title: result.ideId || ideKey,
+            }));
+        } catch { /* ignore activity persist errors */ }
+    }
+    return { ...result };
+}
+
+export const ideHandlers: Record<string, MedFamilyHandler> = {
+    // ─── IDE stop ───
+    stop_ide: async (ctx: MedFamilyContext, args: any) => {
+        const ideType = args?.ideType;
+        if (!ideType) throw new Error('ideType required');
+        const killProcess = args?.killProcess !== false; // default true
+        await ctx.stopIde(ideType, killProcess);
+        try {
+            const results = await detectIDEs(ctx.deps.providerLoader);
+            ctx.deps.detectedIdes.value = results;
+            ctx.deps.providerLoader.setIdeDetectionResults(results, true);
+        } catch { /* ignore detection refresh errors */ }
+        return { success: true, ideType, stopped: true, processKilled: killProcess };
+    },
+
+    // ─── IDE restart ───
+    restart_ide: async (ctx: MedFamilyContext, args: any) => {
+        const ideType = args?.ideType;
+        if (!ideType) throw new Error('ideType required');
+        await ctx.stopIde(ideType, true); // always kill process on restart
+        const launchResult = await ctx.launchIde({ ideType, enableCdp: true, workspace: args?.workspace });
+        return { success: true, ideType, restarted: true, launch: launchResult };
+    },
+
+    // ─── IDE launch + CDP connect ───
+    launch_ide: async (ctx: MedFamilyContext, args: any) => {
+        return launchIde(ctx, args);
+    },
+
+    // ─── Detect providers ───
+    detect_provider: async (ctx: MedFamilyContext, args: any) => {
+        const providerType = typeof args?.providerType === 'string' ? args.providerType.trim() : '';
+        if (!providerType) return { success: false, error: 'providerType is required' };
+        const normalizedType = ctx.deps.providerLoader.resolveAlias(providerType);
+        const provider = ctx.deps.providerLoader.getByAlias(providerType);
+        if (!provider) return { success: false, error: `Provider not found: ${providerType}` };
+        if (provider.category !== 'cli' && provider.category !== 'acp') {
+            return { success: false, error: `Provider detection is only supported for CLI/ACP providers: ${providerType}` };
+        }
+        if (!ctx.deps.providerLoader.isMachineProviderEnabled(normalizedType)) {
+            return { success: false, error: `Provider is disabled on this machine: ${providerType}` };
+        }
+        const detected = await detectCLI(normalizedType, ctx.deps.providerLoader, { includeVersion: false });
+        ctx.deps.providerLoader.setCliDetectionResults([{
+            id: normalizedType,
+            installed: !!detected,
+            path: detected?.path,
+        }], false);
+        ctx.deps.onStatusChange?.();
+        return {
+            success: true,
+            providerType: normalizedType,
+            detected: !!detected,
+            path: detected?.path || null,
+        };
+    },
+
+    // ─── Detect IDEs ───
+    detect_ides: async (ctx: MedFamilyContext, _args: any) => {
+        const results = await detectIDEs(ctx.deps.providerLoader);
+        ctx.deps.detectedIdes.value = results;
+        ctx.deps.providerLoader.setIdeDetectionResults(results, true);
+        return { success: true, detectedInfo: results };
+    },
+};