@adhdev/daemon-core 0.9.82-rc.363 → 0.9.82-rc.365

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

@@ -198,6 +198,11 @@ export declare class FsmDriver implements ISpecDriver {
     private lastWin32WriteAt;
     /** Pending paced chunk-write timer for a large win32 body (see writeWin32Body). */
     private win32WriteTimer;
+    /** Timer driving the win32 verification-based modal-confirm CR resend loop (see
+     *  scheduleWin32ModalConfirm). A lone CR that confirms an approval/picker choice
+     *  is absorbed by ConPTY the same way a send_message submit CR is, so the confirm
+     *  must be resent until the modal actually resolves (status leaves 'approval'). */
+    private win32ModalConfirmTimer;
     private currentEval;
     private stateHistory;
     private prevStateAt;
@@ -358,6 +363,28 @@ export declare class FsmDriver implements ISpecDriver {
     private scheduleWin32Submit;
     private handleClickControl;
     private handleClickModalButton;
+    /**
+     * Submit a modal-confirm key sequence (the choice key + its trailing CR).
+     *
+     * On win32 the trailing CR is the SAME lone-CR-swallow case as a send_message
+     * submit: ConPTY can absorb a single CR as a literal newline instead of a
+     * confirm, so the approval/picker modal never resolves and the FSM flaps
+     * approval↔busy while auto-approve keeps firing into the void (APPROVESTUCK).
+     * So we split any non-CR prefix (e.g. the "1" of "1\r") off, write it once, and
+     * resend the CR on a fixed cadence until the modal actually resolves (status
+     * leaves 'approval'). Non-win32 keeps the single direct write — its CR submits
+     * on the first try.
+     */
+    private submitModalConfirm;
+    /**
+     * win32 modal-confirm CR resend loop. Mirrors scheduleWin32Submit's phase-2
+     * verified resend, but gated on still being IN a modal (status 'approval')
+     * rather than still idle: the first CR fires immediately, then resends every
+     * WIN32_SUBMIT_RESEND_GAP_MS while the FSM is still showing the modal, up to
+     * WIN32_SUBMIT_MAX_RESENDS. The instant the modal resolves (status flips to
+     * generating/idle) we stop, so no stray CR leaks into the next turn's composer.
+     */
+    private scheduleWin32ModalConfirm;
     private handleAttachImage;
     private tryAdvancePicker;
     private handleExit;

package/dist/system/hash.d.ts

@@ -0,0 +1,8 @@
+/** Full lowercase hex SHA-256 digest of `input`. */
+export declare function sha256Hex(input: string): string;
+/**
+ * Truncated SHA-256 hex digest — the first `length` hex chars (default 16).
+ * Used for stable short identifiers (workspace hashes, token ids, coordinator
+ * home dirs) where collision risk at 16 hex chars (64 bits) is negligible.
+ */
+export declare function shortHash(input: string, length?: number): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.363",
+  "version": "0.9.82-rc.365",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.363",
+    "@adhdev/mesh-shared": "0.9.82-rc.365",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/commands/cli-manager.ts

@@ -18,6 +18,7 @@ import { loadConfig } from '../config/config.js';
 import { loadState, saveState } from '../config/state-store.js';
 import { getWorkspaceState, resolveLaunchDirectory } from '../config/workspaces.js';
 import { appendRecentActivity } from '../config/recent-activity.js';
+import { shortHash } from '../system/hash.js';
 import { unregisterMeshCoordinator, getCoordinatorForSession } from '../mesh/coordinator-registry.js';
 import { upsertSavedProviderSession } from '../config/saved-sessions.js';
 import { buildLegacyModelModeSummaryMetadata, normalizeProviderSummaryMetadata } from '../providers/summary-metadata.js';
@@ -301,7 +302,7 @@ function hasConfigOverride(args: string[], key: string): boolean {
 function ensureEmptyDelegatedMcpConfig(workspace: string): string {
     const baseDir = path.join(os.tmpdir(), 'adhdev-delegated-agent-empty-mcp');
     mkdirSync(baseDir, { recursive: true });
-    const workspaceHash = crypto.createHash('sha256').update(path.resolve(workspace || os.tmpdir())).digest('hex').slice(0, 16);
+    const workspaceHash = shortHash(path.resolve(workspace || os.tmpdir()));
     const filePath = path.join(baseDir, `${workspaceHash}.json`);
     writeFileSync(filePath, JSON.stringify({ mcpServers: {} }, null, 2), 'utf-8');
     return filePath;

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