@adhdev/daemon-core 0.9.82-rc.46 → 0.9.82-rc.461

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,241 @@
+/**
+ * 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 */ }
+            }
+        }
+        // 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);
+    },
+};

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

@@ -0,0 +1,230 @@
+/**
+ * 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) => {
+        // The whole handler is wrapped: the safety-gate evaluation (mesh resolution,
+        // git status/stash/submodule fan-out) can throw on some platforms — notably a
+        // win32 daemon whose git invocation parsing or slow submodule probe raises
+        // before fastForwardMeshNode's own guarded body runs. router.execute re-throws,
+        // so an escaping throw surfaces to the coordinator as an opaque
+        // "Daemon IPC command failed" instead of the structured blockingReasons result
+        // a mac node returns cleanly. Catch it and return the same blocked shape so the
+        // coordinator can read the reason and route, never an IPC crash. Mirrors the
+        // mesh_init handler's try-catch contract.
+        const workspaceForError = typeof args?.workspace === 'string' ? args.workspace.trim() : '';
+        const meshIdForError = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const nodeIdForError = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
+        try {
+            const meshId = meshIdForError;
+            const nodeId = nodeIdForError;
+            let workspace = workspaceForError;
+            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;
+        } catch (e: any) {
+            const errorMessage = e?.message || String(e);
+            return {
+                success: false,
+                code: 'fast_forward_safety_gate_error',
+                ...(meshIdForError ? { meshId: meshIdForError } : {}),
+                ...(nodeIdForError ? { nodeId: nodeIdForError } : {}),
+                workspace: workspaceForError,
+                mode: args?.mode === 'push' ? 'push' : 'merge',
+                allowed: false,
+                willRun: false,
+                executed: false,
+                // Surface the throw as a blocking reason instead of an opaque IPC crash
+                // so the coordinator gets the same structured shape a clean node returns.
+                blockingReasons: ['fast_forward_safety_gate_error'],
+                operationError: errorMessage,
+                error: errorMessage,
+            } 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);
+    },
+};