@adhdev/daemon-core 0.9.82-rc.39 → 0.9.82-rc.391

package/src/commands/med-family/mesh-host-pairing.ts

@@ -0,0 +1,234 @@
+/**
+ * RF-ROUTER MED family — Mesh Host manual-pairing commands.
+ *
+ * get_mesh_host_pairing, configure_mesh_host_pairing,
+ * create_mesh_host_pairing_token, apply_mesh_host_join and
+ * join_mesh_host_pairing. These read/mutate the mesh host pairing metadata and,
+ * for join, apply the request to the host over mesh-command dispatch or a
+ * standalone HTTP command. Extracted verbatim from executeDaemonCommand; pairing
+ * helpers are imported from router.js, identical to the original references.
+ */
+import { resolveMeshHostStatus } from '../../mesh/mesh-host-ownership.js';
+import { buildMemberJoinNode, normalizeStandaloneHostCommandUrl } from '../router.js';
+import type { MedFamilyContext, MedFamilyHandler } from './types.js';
+
+export const meshHostPairingHandlers: Record<string, MedFamilyHandler> = {
+    get_mesh_host_pairing: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        if (!meshId) return { success: false, error: 'meshId required' };
+        const meshRecord = await ctx.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+        const mesh = meshRecord?.mesh;
+        if (!mesh) return { success: false, error: 'Mesh not found' };
+        const meshHost = resolveMeshHostStatus(mesh);
+        const pairingStatus = meshHost.pairing?.status || 'not_configured';
+        return {
+            success: true,
+            code: pairingStatus === 'not_configured' ? 'mesh_host_pairing_not_configured' : 'mesh_host_pairing_pending',
+            meshId,
+            hostAddress: meshHost.hostAddress,
+            meshHost,
+            manualPairing: {
+                status: pairingStatus,
+                joinImplemented: true,
+                protocol: 'standalone_command_direct_v1',
+                description: 'Standalone manual pairing can save address/token metadata, apply a host join over direct standalone command HTTP or injected mesh command dispatch, and check persisted status. P2P signaling remains outside this slice.',
+            },
+        };
+    },
+
+    configure_mesh_host_pairing: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const hostAddress = typeof args?.hostAddress === 'string' ? args.hostAddress.trim() : '';
+        const token = typeof args?.token === 'string' ? args.token.trim() : '';
+        if (!meshId) return { success: false, error: 'meshId required' };
+        if (!hostAddress || !token) return { success: false, error: 'hostAddress and token required' };
+        try {
+            const { configureMeshHostPairing } = await import('../../config/mesh-config.js');
+            const configured = configureMeshHostPairing(meshId, { hostAddress, token });
+            if (!configured) return { success: false, error: 'Mesh not found' };
+            ctx.inlineMeshCache.set(meshId, configured.mesh);
+            const meshHost = resolveMeshHostStatus(configured.mesh);
+            return {
+                success: true,
+                code: 'mesh_host_pairing_pending',
+                meshId,
+                hostAddress: configured.hostAddress,
+                meshHost,
+                manualPairing: {
+                    status: meshHost.pairing?.status || 'pairing',
+                    joinImplemented: true,
+                    protocol: 'standalone_command_direct_v1',
+                    description: 'Manual Mesh Host pairing config was saved locally. Use join_mesh_host_pairing to apply it to the host. Raw token was not persisted.',
+                },
+            };
+        } catch (e: any) {
+            return { success: false, code: 'mesh_host_pairing_invalid', meshId, hostAddress, error: e.message };
+        }
+    },
+
+    create_mesh_host_pairing_token: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        if (!meshId) return { success: false, error: 'meshId required' };
+        try {
+            const { createMeshHostPairingToken } = await import('../../config/mesh-config.js');
+            const created = createMeshHostPairingToken(meshId, {
+                token: typeof args?.token === 'string' ? args.token : undefined,
+                expiresAt: typeof args?.expiresAt === 'string' ? args.expiresAt : undefined,
+            });
+            if (!created) return { success: false, error: 'Mesh not found' };
+            ctx.inlineMeshCache.set(meshId, created.mesh);
+            ctx.invalidateAggregateMeshStatus(meshId);
+            return {
+                success: true,
+                code: 'mesh_host_pairing_token_created',
+                meshId,
+                token: created.token,
+                tokenId: created.tokenId,
+                expiresAt: created.expiresAt,
+                meshHost: resolveMeshHostStatus(created.mesh),
+                warning: 'Raw token is returned once and is not persisted; share it with member daemons over a trusted channel.',
+            };
+        } catch (e: any) {
+            return { success: false, code: 'mesh_host_pairing_token_invalid', meshId, error: e.message };
+        }
+    },
+
+    apply_mesh_host_join: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const token = typeof args?.token === 'string' ? args.token.trim() : '';
+        const memberNode = args?.memberNode && typeof args.memberNode === 'object' && !Array.isArray(args.memberNode)
+            ? args.memberNode
+            : null;
+        if (!meshId) return { success: false, error: 'meshId required' };
+        if (!token || !memberNode) return { success: false, error: 'token and memberNode required' };
+        try {
+            const { applyMeshHostJoinRequest } = await import('../../config/mesh-config.js');
+            const applied = applyMeshHostJoinRequest(meshId, {
+                token,
+                memberNode: memberNode as any,
+                memberMeshId: typeof args?.memberMeshId === 'string' ? args.memberMeshId : undefined,
+            });
+            if (!applied) return { success: false, error: 'Mesh not found' };
+            if (!applied.accepted) {
+                return {
+                    success: false,
+                    code: 'mesh_host_join_rejected',
+                    meshId,
+                    tokenId: applied.tokenId,
+                    meshHost: applied.meshHost ? resolveMeshHostStatus({ meshHost: applied.meshHost }) : undefined,
+                    error: applied.reason,
+                };
+            }
+            ctx.inlineMeshCache.set(meshId, applied.mesh);
+            ctx.invalidateAggregateMeshStatus(meshId);
+            try {
+                const { appendLedgerEntry } = await import('../../mesh/mesh-ledger.js');
+                appendLedgerEntry(meshId, {
+                    kind: 'node_joined',
+                    nodeId: applied.node.id,
+                    payload: { role: 'member', tokenId: applied.tokenId, workspace: applied.node.workspace },
+                });
+            } catch { /* ledger append is best-effort */ }
+            return {
+                success: true,
+                code: 'mesh_host_join_accepted',
+                meshId,
+                node: applied.node,
+                tokenId: applied.tokenId,
+                meshHost: resolveMeshHostStatus(applied.mesh),
+            };
+        } catch (e: any) {
+            return { success: false, code: 'mesh_host_join_failed', meshId, error: e.message };
+        }
+    },
+
+    join_mesh_host_pairing: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const token = typeof args?.token === 'string' ? args.token.trim() : '';
+        if (!meshId) return { success: false, error: 'meshId required' };
+        if (!token) return { success: false, error: 'token required because raw pairing tokens are not persisted' };
+        const meshRecord = await ctx.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+        const mesh = meshRecord?.mesh;
+        if (!mesh) return { success: false, error: 'Mesh not found' };
+        const meshHost = resolveMeshHostStatus(mesh);
+        if (meshHost.role !== 'member') {
+            return { success: false, code: 'mesh_host_join_not_member', meshId, meshHost, error: 'join_mesh_host_pairing must run from a member daemon configured with a Mesh Host address/token.' };
+        }
+        try {
+            const { tokenIdForManualPairing, markMeshHostPairingJoined } = await import('../../config/mesh-config.js');
+            const tokenId = tokenIdForManualPairing(token);
+            if (meshHost.pairing?.tokenId && meshHost.pairing.tokenId !== tokenId) {
+                return { success: false, code: 'mesh_host_join_rejected', meshId, tokenId, meshHost, error: 'invalid pairing token' };
+            }
+            const memberNode = buildMemberJoinNode(mesh, args, ctx.deps.statusInstanceId);
+            if (!memberNode) return { success: false, error: 'member node metadata unavailable' };
+            const hostMeshId = typeof args?.hostMeshId === 'string' && args.hostMeshId.trim() ? args.hostMeshId.trim() : meshId;
+            const hostDaemonId = typeof args?.hostDaemonId === 'string' && args.hostDaemonId.trim()
+                ? args.hostDaemonId.trim()
+                : meshHost.hostDaemonId;
+            let hostResult: any;
+            let transport: string;
+            if (hostDaemonId && ctx.deps.dispatchMeshCommand) {
+                transport = 'mesh_command_dispatch';
+                hostResult = await ctx.deps.dispatchMeshCommand(hostDaemonId, 'apply_mesh_host_join', {
+                    meshId: hostMeshId,
+                    token,
+                    memberMeshId: meshId,
+                    memberNode,
+                });
+            } else if (meshHost.hostAddress) {
+                transport = 'standalone_http_command';
+                const commandUrl = normalizeStandaloneHostCommandUrl(meshHost.hostAddress);
+                const response = await fetch(commandUrl, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ type: 'apply_mesh_host_join', payload: { meshId: hostMeshId, token, memberMeshId: meshId, memberNode } }),
+                });
+                hostResult = await response.json().catch(() => ({ success: false, error: `Host returned HTTP ${response.status}` }));
+                if (!response.ok && hostResult?.success !== false) hostResult = { success: false, error: `Host returned HTTP ${response.status}` };
+            } else {
+                return {
+                    success: false,
+                    code: 'mesh_host_join_transport_unavailable',
+                    meshId,
+                    meshHost,
+                    error: 'No hostDaemonId dispatch path or hostAddress HTTP command path is available. P2P signaling join is not implemented in this slice.',
+                };
+            }
+            if (!hostResult?.success) {
+                return { success: false, code: hostResult?.code || 'mesh_host_join_rejected', meshId, meshHost, transport, error: hostResult?.error || 'Mesh Host rejected join request', hostResult };
+            }
+            const joined = meshRecord.inline
+                ? null
+                : markMeshHostPairingJoined(meshId, {
+                    tokenId: hostResult.tokenId || tokenId,
+                    hostDaemonId: hostResult.meshHost?.hostDaemonId || hostDaemonId,
+                    hostNodeId: hostResult.meshHost?.hostNodeId,
+                    joinedAt: hostResult.meshHost?.pairing?.joinedAt,
+                });
+            if (joined) {
+                ctx.inlineMeshCache.set(meshId, joined.mesh);
+                ctx.invalidateAggregateMeshStatus(meshId);
+            }
+            return {
+                success: true,
+                code: 'mesh_host_join_applied',
+                meshId,
+                hostMeshId,
+                transport,
+                node: hostResult.node,
+                tokenId: hostResult.tokenId || tokenId,
+                meshHost: joined ? resolveMeshHostStatus(joined.mesh) : { ...meshHost, pairing: { ...(meshHost.pairing || {}), status: 'paired', tokenId: hostResult.tokenId || tokenId } },
+                hostResult,
+                manualPairing: {
+                    status: 'paired',
+                    joinImplemented: true,
+                    protocol: 'standalone_command_direct_v1',
+                    description: 'Mesh Host accepted the join and local member pairing status was marked paired. P2P runtime signaling remains outside this slice.',
+                },
+            };
+        } catch (e: any) {
+            return { success: false, code: 'mesh_host_join_failed', meshId, meshHost, error: e.message };
+        }
+    },
+};

package/src/commands/med-family/mesh-queue.ts

@@ -0,0 +1,131 @@
+/**
+ * RF-ROUTER MED family — mesh work-queue commands.
+ *
+ * get_mesh_queue (view with dependency annotation), cancel_mesh_queue_task,
+ * requeue_mesh_queue_task and trigger_mesh_queue. The mutating commands gate on
+ * the Mesh Host owner check (ctx.requireMeshHostMutationOwner). trigger preflights
+ * a preferred-node claim before the round-robin trigger. Extracted verbatim from
+ * executeDaemonCommand.
+ */
+import { readStringValue } from '../router.js';
+import type { MedFamilyContext, MedFamilyHandler } from './types.js';
+
+export const meshQueueHandlers: Record<string, MedFamilyHandler> = {
+    get_mesh_queue: async (_ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        if (!meshId) return { success: false, error: 'meshId required' };
+        try {
+            const { getMeshQueueStats, getQueue, describeTaskDependencyState } = await import('../../mesh/mesh-work-queue.js');
+            const status = Array.isArray(args?.status)
+                ? args.status.map((s: any) => typeof s === 'string' ? s.trim() : '').filter(Boolean)
+                : undefined;
+            const rawQueue = getQueue(meshId, { status: status as any });
+            // M1: annotate dependency state at view time (waitingOn / dependenciesSatisfied).
+            const statusById = new Map(getQueue(meshId).map(task => [task.id, task.status]));
+            const queue = rawQueue.map(task =>
+                Array.isArray(task.dependsOn) && task.dependsOn.length > 0
+                    ? { ...task, ...describeTaskDependencyState(task, statusById) }
+                    : task);
+            const summary = getMeshQueueStats(meshId);
+            return {
+                success: true,
+                queue,
+                summary,
+                sourceOfTruth: {
+                    kind: 'mesh_work_queue_file',
+                    activeStatuses: ['pending', 'assigned'],
+                    historicalStatuses: ['completed', 'failed', 'cancelled'],
+                    notes: 'pending/assigned are active work; completed/failed/cancelled are historical records.',
+                },
+            };
+        } catch (e: any) {
+            return { success: false, error: e.message };
+        }
+    },
+
+    cancel_mesh_queue_task: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const taskId = typeof args?.taskId === 'string' ? args.taskId.trim() : '';
+        if (!meshId || !taskId) return { success: false, error: 'meshId and taskId required' };
+        const ownerFailure = await ctx.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'queue cancellation');
+        if (ownerFailure) return ownerFailure;
+        try {
+            const { cancelTask } = await import('../../mesh/mesh-work-queue.js');
+            const reason = typeof args?.reason === 'string' ? args.reason : undefined;
+            const task = cancelTask(meshId, taskId, { reason });
+            if (!task) return { success: false, error: `Queue task '${taskId}' not found` };
+            return { success: true, task };
+        } catch (e: any) {
+            return { success: false, error: e.message };
+        }
+    },
+
+    requeue_mesh_queue_task: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const taskId = typeof args?.taskId === 'string' ? args.taskId.trim() : '';
+        if (!meshId || !taskId) return { success: false, error: 'meshId and taskId required' };
+        const ownerFailure = await ctx.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'queue requeue');
+        if (ownerFailure) return ownerFailure;
+        try {
+            const { requeueTask } = await import('../../mesh/mesh-work-queue.js');
+            const task = requeueTask(meshId, taskId, {
+                reason: typeof args?.reason === 'string' ? args.reason : undefined,
+                targetNodeId: typeof args?.targetNodeId === 'string' ? args.targetNodeId.trim() : undefined,
+                targetSessionId: typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim() : undefined,
+                clearTargetNode: args?.clearTargetNode === true,
+                clearTargetSession: args?.clearTargetSession !== false,
+            });
+            if (!task) return { success: false, error: `Queue task '${taskId}' not found` };
+            return { success: true, task };
+        } catch (e: any) {
+            return { success: false, error: e.message };
+        }
+    },
+
+    trigger_mesh_queue: async (ctx: MedFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        if (!meshId) return { success: false, error: 'meshId required' };
+        const ownerFailure = await ctx.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'queue trigger');
+        if (ownerFailure) return ownerFailure;
+        try {
+            const { triggerMeshQueue, tryAssignQueueTask } = await import('../../mesh/mesh-events.js');
+
+            // Bug A fix: when preferredNodeId is provided, attempt to claim a pending
+            // task for the preferred node's idle session first, before the general
+            // round-robin trigger picks a different node.
+            const preferredNodeId = typeof args?.preferredNodeId === 'string' ? args.preferredNodeId.trim() : '';
+            if (preferredNodeId) {
+                const cliInstances = ctx.deps.instanceManager.getByCategory('cli');
+                // Sort: preferred node's sessions first, others after
+                const sorted = [...cliInstances].sort((a, b) => {
+                    const aSettings = a.getState().settings as Record<string, unknown> || {};
+                    const bSettings = b.getState().settings as Record<string, unknown> || {};
+                    const aNode = readStringValue(aSettings.meshNodeId, aSettings.nodeId);
+                    const bNode = readStringValue(bSettings.meshNodeId, bSettings.nodeId);
+                    return (aNode === preferredNodeId ? -1 : 0) - (bNode === preferredNodeId ? -1 : 0);
+                });
+                for (const inst of sorted) {
+                    const state = inst.getState();
+                    const settings = state.settings as Record<string, unknown> || {};
+                    const nodeId = readStringValue(settings.meshNodeId, settings.nodeId);
+                    if (!nodeId || nodeId !== preferredNodeId) continue;
+                    const meshNodeFor = readStringValue(settings.meshNodeFor);
+                    if (meshNodeFor !== meshId) continue;
+                    const status = (readStringValue(state.status) || '').toLowerCase();
+                    if (status !== 'idle') continue;
+                    const sessionId = typeof state.instanceId === 'string' ? state.instanceId : '';
+                    const providerType = readStringValue(state.type, settings.providerType) || '';
+                    if (sessionId && providerType) {
+                        tryAssignQueueTask(ctx.deps as any, meshId, nodeId, sessionId, providerType);
+                        break;
+                    }
+                }
+            }
+
+            const trigger = await triggerMeshQueue(ctx.deps as any, meshId);
+            return { success: true, trigger };
+        } catch (e: any) {
+            return { success: false, error: e.message };
+        }
+    },
+};

package/src/commands/med-family/mesh-restart.ts

@@ -0,0 +1,92 @@
+/**
+ * RF-ROUTER MED family — coordinator-triggered daemon restart.
+ *
+ * restart_daemon_node exposes the existing dashboard "preview update" path
+ * (low-family daemon_upgrade: update-to-latest-on-channel + detached restart) as
+ * a mesh command, so a coordinator can roll a worker daemon onto a freshly
+ * deployed version without a manual restart round-trip. It mirrors
+ * fast_forward_mesh_node's remote-forward shape — resolve the target node, and
+ * if it belongs to a remote daemon forward the command there so the owning
+ * daemon (not the coordinator) restarts itself — and adds an idle-gate: a node
+ * with a generating / waiting_approval / starting session is refused so an
+ * in-flight turn is never killed mid-restart.
+ *
+ * v1 reuses daemon_upgrade verbatim rather than adding a restart-only path:
+ * the goal is "pick up a just-deployed version", which inherently needs the
+ * npm reinstall the upgrade helper already performs. Already-latest is a no-op
+ * (no restart), matching the dashboard button.
+ */
+import { daemonIdsEquivalent, meshNodeIdMatches } from '@adhdev/mesh-shared';
+import { daemonLifecycleHandlers } from '../low-family/daemon-lifecycle.js';
+import type { CommandRouterResult } from '../router.js';
+import type { MedFamilyContext, MedFamilyHandler } from './types.js';
+
+// Session states that must block a restart: an in-flight turn or a pending
+// approval would be lost when the daemon exits to re-spawn. Mirrors the
+// daemon-cloud mandatory-update idle-gate (hasBlockingSessionsForMandatoryUpdate).
+const RESTART_BLOCKING_STATES = new Set(['generating', 'waiting_approval', 'starting']);
+
+function hasBlockingSessions(ctx: MedFamilyContext): boolean {
+    const states = ctx.deps.instanceManager.collectAllStates();
+    for (const state of states) {
+        if (RESTART_BLOCKING_STATES.has(String(state.status || ''))) return true;
+        const childStates = 'extensions' in state && Array.isArray((state as any).extensions)
+            ? (state as any).extensions
+            : [];
+        for (const child of childStates) {
+            if (RESTART_BLOCKING_STATES.has(String(child?.status || ''))) return true;
+        }
+    }
+    return false;
+}
+
+export const meshRestartHandlers: Record<string, MedFamilyHandler> = {
+    restart_daemon_node: async (ctx: MedFamilyContext, args: any): Promise<CommandRouterResult> => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
+
+        // Resolve the target node's owning daemon so a command that lands on a
+        // non-owner daemon is forwarded rather than restarting the wrong daemon.
+        // preferInline so inline-cache-only worktree nodes still resolve.
+        let nodeDaemonId: string | undefined;
+        if (meshId && nodeId) {
+            const meshRecord = await ctx.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+            const node = meshRecord?.mesh?.nodes?.find((n: any) => meshNodeIdMatches(n, nodeId));
+            nodeDaemonId = typeof node?.daemonId === 'string' ? node.daemonId.trim() : undefined;
+        }
+
+        const selfDaemonId = ctx.deps.statusInstanceId;
+        // daemonIdsEquivalent: a legacy-form daemonId resolving to this machine's
+        // core is local — execute here instead of forwarding (and P2P self-dial).
+        // Equivalent → local. _meshDirectDispatch prevents re-forwarding once the
+        // call has landed on the owning daemon.
+        const isRemote = nodeDaemonId && selfDaemonId && !daemonIdsEquivalent(nodeDaemonId, selfDaemonId);
+        if (isRemote && ctx.deps.dispatchMeshCommand && !args?._meshDirectDispatch) {
+            const forwarded = await ctx.deps.dispatchMeshCommand(nodeDaemonId!, 'restart_daemon_node', {
+                ...(typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}),
+                _meshDirectDispatch: true,
+            });
+            return (forwarded ?? { success: false, error: 'no response from remote node' }) as CommandRouterResult;
+        }
+
+        // Idle-gate: refuse if any session on THIS daemon is mid-turn / awaiting
+        // approval / starting. The coordinator restarts other (idle) nodes freely;
+        // restarting the coordinator's OWN daemon is naturally refused while its
+        // calling turn is 'generating' (accepted v1 limitation — call other nodes
+        // first, the coordinator last when it has gone idle).
+        if (hasBlockingSessions(ctx)) {
+            return {
+                success: false,
+                restarted: false,
+                code: 'blocking_sessions',
+                reason: 'Daemon has an active session (generating / waiting_approval / starting); restart refused to avoid interrupting in-flight work. Retry when the node is idle.',
+            };
+        }
+
+        // Reuse the battle-tested dashboard "preview update" path: update to the
+        // latest published version on the resolved channel, then detached-restart.
+        // Already-latest is a no-op (no restart), matching the dashboard button.
+        const result = await daemonLifecycleHandlers.daemon_upgrade({ deps: ctx.deps }, args);
+        return { ...result, restarted: (result as any)?.restarting === true };
+    },
+};

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

@@ -0,0 +1,120 @@
+/**
+ * RF-ROUTER MED family — shared types for the extracted medium-coupling command
+ * handlers. Like the LOW family, 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.
+ *
+ * Unlike the LOW family, MED handlers need a handful of router-private
+ * collaborators (mesh resolution, owner gating, inline-cache mutation, worktree /
+ * session cleanup, refine job starters, IDE launch). The router binds these onto
+ * MedFamilyContext at dispatch; they are NOT reachable from `deps`. The IDE family
+ * also needs `launchIde` to break the original `launch_ide`/`restart_*`
+ * self-recursion through executeDaemonCommand.
+ *
+ * Registry dispatch: DaemonCommandRouter.executeDaemonCommand looks up the cmd in
+ * medFamilyRegistry 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, MeshGitProbeCache } from '../router.js';
+import type { RepoMeshSessionCleanupMode } from '../../repo-mesh-types.js';
+import type { WorktreeBootstrapState } from '../../mesh/worktree-bootstrap-config.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;
+
+/** Result of the router's local worktree-node cleanup. */
+export type CleanupLocalWorktreeNodeResult =
+    | { success: true; skipped?: boolean; removedPath?: string; repoRoot?: string; reason?: string; fallback?: string; forced?: boolean; convergence?: Record<string, unknown>; recovered?: boolean; residue?: boolean; residueWarning?: string; residueError?: string }
+    | { success: false; code: string; error: string; recoveryHint: string; convergence?: Record<string, unknown> };
+
+/**
+ * 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 cache, session/worktree cleanup, refine jobs), so it cannot be
+ * read from `deps` — the registry receives bound references instead.
+ */
+export interface MedFamilyContext {
+    deps: CommandRouterDeps;
+
+    /** Bound `DaemonCommandRouter.getMeshForCommand`. */
+    getMeshForCommand: (
+        meshId: string,
+        inlineMesh?: unknown,
+        options?: { preferInline?: boolean },
+    ) => Promise<ResolvedMeshForCommand>;
+
+    /** Bound `DaemonCommandRouter.getCachedInlineMesh`. */
+    getCachedInlineMesh: (meshId: string, inlineMesh?: unknown) => any | undefined;
+
+    /** Bound `DaemonCommandRouter.requireMeshHostMutationOwner` (owner gate). */
+    requireMeshHostMutationOwner: (meshId: string, inlineMesh: unknown, operation: string) => Promise<CommandRouterResult | null>;
+
+    /** Bound `DaemonCommandRouter.invalidateAggregateMeshStatus`. */
+    invalidateAggregateMeshStatus: (meshId: string) => void;
+
+    /** Bound `DaemonCommandRouter.updateInlineMeshNode`. */
+    updateInlineMeshNode: (meshId: string, mesh: any, node: any) => void;
+
+    /** Bound `DaemonCommandRouter.removeInlineMeshNode`. */
+    removeInlineMeshNode: (meshId: string, mesh: any, nodeId: string) => boolean;
+
+    /** Bound `DaemonCommandRouter.normalizeMeshSessionCleanupMode`. */
+    normalizeMeshSessionCleanupMode: (value: unknown) => RepoMeshSessionCleanupMode;
+
+    /** Bound `DaemonCommandRouter.cleanupMeshSessions`. */
+    cleanupMeshSessions: (args: {
+        meshId: string;
+        nodeId: string;
+        node: any;
+        mode: RepoMeshSessionCleanupMode;
+        sessionIds?: string[];
+        dryRun?: boolean;
+        source?: 'mesh_cleanup_sessions' | 'mesh_remove_node';
+    }) => Promise<{ success: boolean; [key: string]: unknown }>;
+
+    /** Bound `DaemonCommandRouter.cleanupLocalWorktreeNode`. */
+    cleanupLocalWorktreeNode: (args: {
+        mesh: any;
+        node: any;
+        nodeId: string;
+        force?: boolean;
+    }) => Promise<CleanupLocalWorktreeNodeResult>;
+
+    /** Bound `DaemonCommandRouter.startMeshRefineJob` (async execute path). */
+    startMeshRefineJob: (meshId: string, nodeId: string, args: any) => Promise<CommandRouterResult>;
+
+    /** Bound `DaemonCommandRouter.batchRefineMeshNodes` (dry-run batch plan). */
+    batchRefineMeshNodes: (meshId: string, requestedNodeIds: string[] | undefined, args: any) => Promise<CommandRouterResult>;
+
+    /** Bound `DaemonCommandRouter.startMeshRefineBatchJob` (async batch execute). */
+    startMeshRefineBatchJob: (meshId: string, requestedNodeIds: string[] | undefined, args: any) => Promise<CommandRouterResult>;
+
+    /** Bound `DaemonCommandRouter.stopIde` (CDP disconnect + cleanup + optional kill). */
+    stopIde: (ideType: string, killProcess?: boolean) => Promise<void>;
+
+    /**
+     * Module-level `launchIde` helper bound to this context. The original
+     * `launch_ide` case body, lifted into a free function so `restart_session` /
+     * `restart_ide` can invoke the IDE launch directly instead of recursing
+     * through `executeDaemonCommand('launch_ide')` (which would re-enter the
+     * registry). Byte-identical to the original case body.
+     */
+    launchIde: (args: any) => Promise<CommandRouterResult>;
+
+    /** Router's inline-mesh cache (read/write of resolved mesh records). */
+    inlineMeshCache: Map<string, any>;
+
+    /** Router's mesh git-probe cache (reused direct-truth probes for get_mesh). */
+    meshGitProbeCache: MeshGitProbeCache;
+}
+
+export type MedFamilyHandler = (ctx: MedFamilyContext, args: any) => Promise<CommandRouterResult | null>;
+
+export type MedFamilyRegistry = Map<string, MedFamilyHandler>;
+
+export type { WorktreeBootstrapState };