@adhdev/daemon-core 0.9.82-rc.5 → 0.9.82-rc.500

package/src/commands/router.ts

@@ -9,615 +9,106 @@
  *   3. Everything else → delegated to commandHandler.handle()
  */
 
+
 import { DaemonCdpManager } from '../cdp/manager.js';
-import { registerExtensionProviders } from '../cdp/setup.js';
 import { DaemonCommandHandler } from './handler.js';
+import { lowFamilyRegistry } from './low-family/index.js';
+import { medFamilyRegistry } from './med-family/index.js';
+import { launchIde } from './med-family/ide.js';
+import type { MedFamilyContext } from './med-family/index.js';
+import { highFamilyRegistry } from './high-family/index.js';
+import type { HighFamilyContext } from './high-family/index.js';
 import { DaemonCliManager } from './cli-manager.js';
-import { supportsExplicitSessionResume } from './cli-manager.js';
-import type { HostedCliRuntimeDescriptor } from './cli-manager.js';
 import type { ProviderLoader } from '../providers/provider-loader.js';
 import type { ProviderInstanceManager } from '../providers/provider-instance-manager.js';
-import { launchWithCdp, killIdeProcess, isIdeRunning } from '../launch.js';
-import { loadConfig, saveConfig, updateConfig } from '../config/config.js';
-import { loadState, saveState } from '../config/state-store.js';
-import { resolveIdeLaunchWorkspace } from '../config/workspaces.js';
-import { appendRecentActivity, getRecentActivity, markSessionSeen, dismissSessionNotification, markSessionNotificationUnread } from '../config/recent-activity.js';
-import { getSavedProviderSessions } from '../config/saved-sessions.js';
-import { listProviderHistorySessions } from '../config/chat-history.js';
-import { detectIDEs } from '../detection/ide-detector.js';
-import { detectCLI } from '../detection/cli-detector.js';
-import { getGitRepoStatus } from '../git/git-status.js';
-import type { GitSubmoduleStatus } from '../git/git-types.js';
+import { killIdeProcess, isIdeRunning } from '../launch.js';
+import { normalizeMeshNodeId, meshNodeIdMatches } from '@adhdev/mesh-shared';
 import { SessionRegistry } from '../sessions/registry.js';
 import { LOG } from '../logging/logger.js';
 import { logCommand } from '../logging/command-log.js';
 import type { CommandLogEntry } from '../logging/command-log.js';
-import * as yaml from 'js-yaml';
-import { getRecentLogs, LOG_PATH } from '../logging/logger.js';
-import { createInteractionId, getRecentDebugTrace, recordDebugTrace } from '../logging/debug-trace.js';
-import { getSessionHostSurfaceKind, partitionSessionHostRecords } from '../session-host/runtime-surface.js';
-import { createHermesManualMeshCoordinatorSetup, resolveMeshCoordinatorSetup } from './mesh-coordinator.js';
-import { buildSessionEntries } from '../status/builders.js';
-import { handleMeshForwardEvent, drainPendingMeshCoordinatorEvents } from '../mesh/mesh-events.js';
-import { buildMachineInfo, buildStatusSnapshot } from '../status/snapshot.js';
-import { getSessionCompletionMarker } from '../status/snapshot.js';
-import { execNpmCommandSync, resolveCurrentGlobalInstallSurface, spawnDetachedDaemonUpgradeHelper } from './upgrade-helper.js';
+import { createInteractionId, recordDebugTrace } from '../logging/debug-trace.js';
+import { getSessionHostSurfaceKind } from '../session-host/runtime-surface.js';
+import { handleMeshForwardEvent, queuePendingMeshCoordinatorEvent } from '../mesh/mesh-events.js';
+import { buildMeshHostRequiredFailure, resolveMeshHostStatus } from '../mesh/mesh-host-ownership.js';
+import { analyzeMeshRefineNodeChangeArea, orderMeshRefineBatchNodes } from '../mesh/mesh-refine-batch.js';
+import type { WorktreeBootstrapState } from '../mesh/worktree-bootstrap-config.js';
+import { getMeshQueueRevision } from '../mesh/mesh-work-queue.js';
 import type { RepoMeshSessionCleanupMode } from '../repo-mesh-types.js';
-import { homedir } from 'os';
-import { join as pathJoin, resolve as pathResolve } from 'path';
+import { DEFAULT_MESH_POLICY, magiAutoLaunchedSessionCleanupDecision } from '../repo-mesh-types.js';
+import { resolve as pathResolve } from 'path';
 import * as fs from 'fs';
-
-type ReleaseChannel = 'stable' | 'preview';
-const CHANNEL_NPM_TAG: Record<ReleaseChannel, 'latest' | 'next'> = { stable: 'latest', preview: 'next' };
-const CHANNEL_SERVER_URL: Record<ReleaseChannel, string> = {
-    stable: 'https://api.adhf.dev',
-    preview: 'https://api-preview.adhf.dev',
-};
-
-function normalizeReleaseChannel(value: unknown): ReleaseChannel | null {
-    if (typeof value !== 'string') return null;
-    const normalized = value.trim().toLowerCase();
-    if (normalized === 'stable' || normalized === 'latest') return 'stable';
-    if (normalized === 'preview' || normalized === 'next') return 'preview';
-    return null;
-}
-
-function resolveUpgradeChannel(args: any): ReleaseChannel {
-    return normalizeReleaseChannel(args?.channel)
-        || normalizeReleaseChannel(args?.updatePolicy?.channel)
-        || normalizeReleaseChannel(args?.npmTag)
-        || normalizeReleaseChannel(loadConfig().updateChannel)
-        || 'stable';
-}
-
-function readProviderPriorityFromPolicy(policy: unknown): string[] {
-    const record = policy && typeof policy === 'object' && !Array.isArray(policy)
-        ? policy as Record<string, unknown>
-        : {};
-    const raw = record.providerPriority;
-    if (!Array.isArray(raw)) return [];
-    const seen = new Set<string>();
-    return raw
-        .map(type => typeof type === 'string' ? type.trim() : '')
-        .filter(Boolean)
-        .filter(type => {
-            if (seen.has(type)) return false;
-            seen.add(type);
-            return true;
-        });
-}
-
-function readObjectRecord(value: unknown): Record<string, any> {
-    return value && typeof value === 'object' && !Array.isArray(value)
-        ? value as Record<string, any>
-        : {};
-}
-
-function readStringValue(...values: unknown[]): string | undefined {
-    for (const value of values) {
-        if (typeof value === 'string' && value.trim()) return value.trim();
-    }
-    return undefined;
-}
-
-function readNumberValue(...values: unknown[]): number | undefined {
-    for (const value of values) {
-        if (typeof value === 'number' && Number.isFinite(value)) return value;
-    }
-    return undefined;
-}
-
-function readBooleanValue(...values: unknown[]): boolean | undefined {
-    for (const value of values) {
-        if (typeof value === 'boolean') return value;
-    }
-    return undefined;
-}
-
-function readGitSubmodules(value: unknown): GitSubmoduleStatus[] | undefined {
-    if (!Array.isArray(value)) return undefined;
-    const submodules = value
-        .map(entry => {
-            const submodule = readObjectRecord(entry);
-            const path = readStringValue(submodule.path);
-            const commit = readStringValue(submodule.commit);
-            const repoPath = readStringValue(submodule.repoPath, submodule.repo_root);
-            if (!path || !commit || !repoPath) return null;
-            return {
-                path,
-                commit,
-                repoPath,
-                dirty: readBooleanValue(submodule.dirty) ?? false,
-                outOfSync: readBooleanValue(submodule.outOfSync, submodule.out_of_sync) ?? false,
-                lastCheckedAt: readNumberValue(submodule.lastCheckedAt, submodule.last_checked_at) ?? Date.now(),
-                ...(readStringValue(submodule.error) ? { error: readStringValue(submodule.error) } : {}),
-            };
-        })
-        .filter((entry): entry is GitSubmoduleStatus => entry !== null);
-    return submodules.length > 0 ? submodules : undefined;
-}
-
-function buildCachedInlineMeshGitStatus(node: any): Record<string, unknown> | undefined {
-    const cachedStatus = readObjectRecord(node?.cachedStatus);
-    const cachedGit = readObjectRecord(cachedStatus.git);
-    if (Object.keys(cachedGit).length) {
-        const conflictFiles = Array.isArray(cachedGit.conflictFiles)
-            ? cachedGit.conflictFiles.filter((value: unknown): value is string => typeof value === 'string')
-            : [];
-        const conflictCount = readNumberValue(cachedGit.conflicts) ?? conflictFiles.length;
-        const hasConflicts = readBooleanValue(cachedGit.hasConflicts) ?? conflictCount > 0;
-        const isGitRepo = readBooleanValue(cachedGit.isGitRepo);
-        if (isGitRepo !== undefined) {
-            const submodules = readGitSubmodules(cachedGit.submodules);
-            return {
-                workspace: readStringValue(cachedGit.workspace, node?.workspace) || '',
-                repoRoot: readStringValue(cachedGit.repoRoot, node?.repoRoot, node?.workspace) || null,
-                isGitRepo,
-                branch: readStringValue(cachedGit.branch) ?? null,
-                headCommit: readStringValue(cachedGit.headCommit) ?? null,
-                headMessage: readStringValue(cachedGit.headMessage) ?? null,
-                upstream: readStringValue(cachedGit.upstream) ?? null,
-                ahead: readNumberValue(cachedGit.ahead) ?? 0,
-                behind: readNumberValue(cachedGit.behind) ?? 0,
-                staged: readNumberValue(cachedGit.staged) ?? 0,
-                modified: readNumberValue(cachedGit.modified) ?? 0,
-                untracked: readNumberValue(cachedGit.untracked) ?? 0,
-                deleted: readNumberValue(cachedGit.deleted) ?? 0,
-                renamed: readNumberValue(cachedGit.renamed) ?? 0,
-                hasConflicts,
-                conflictFiles,
-                stashCount: readNumberValue(cachedGit.stashCount) ?? 0,
-                lastCheckedAt: readNumberValue(cachedGit.lastCheckedAt) ?? Date.now(),
-                ...(submodules ? { submodules } : {}),
-            };
-        }
-    }
-
-    const rawGit = readObjectRecord(node?.lastGit ?? node?.last_git);
-    const gitResult = readObjectRecord(rawGit.result);
-    const directStatus = readObjectRecord(rawGit.status);
-    const nestedStatus = readObjectRecord(gitResult.status);
-    const rawProbe = readObjectRecord(node?.lastProbe ?? node?.last_probe);
-    const probeGit = readObjectRecord(rawProbe.git);
-    const probeGitResult = readObjectRecord(probeGit.result);
-    const probeDirectStatus = readObjectRecord(probeGit.status);
-    const probeNestedStatus = readObjectRecord(probeGitResult.status);
-    const status = Object.keys(directStatus).length
-        ? directStatus
-        : Object.keys(nestedStatus).length
-            ? nestedStatus
-            : Object.keys(probeDirectStatus).length
-                ? probeDirectStatus
-                : Object.keys(probeNestedStatus).length
-                    ? probeNestedStatus
-                    : {};
-    const isGitRepo = readBooleanValue(status.isGitRepo);
-    if (!Object.keys(status).length || isGitRepo === undefined) return undefined;
-    const conflictFiles = Array.isArray(status.conflictFiles)
-        ? status.conflictFiles.filter((value: unknown): value is string => typeof value === 'string')
-        : [];
-    const conflictCount = readNumberValue(status.conflicts) ?? conflictFiles.length;
-    const hasConflicts = readBooleanValue(status.hasConflicts) ?? conflictCount > 0;
-    const submodules = readGitSubmodules(status.submodules);
-    return {
-        workspace: readStringValue(status.workspace, node?.workspace) || '',
-        repoRoot: readStringValue(status.repoRoot, node?.repoRoot, node?.workspace) || null,
-        isGitRepo,
-        branch: readStringValue(status.branch) ?? null,
-        headCommit: readStringValue(status.headCommit) ?? null,
-        headMessage: readStringValue(status.headMessage) ?? null,
-        upstream: readStringValue(status.upstream) ?? null,
-        ahead: readNumberValue(status.ahead) ?? 0,
-        behind: readNumberValue(status.behind) ?? 0,
-        staged: readNumberValue(status.staged) ?? 0,
-        modified: readNumberValue(status.modified) ?? 0,
-        untracked: readNumberValue(status.untracked) ?? 0,
-        deleted: readNumberValue(status.deleted) ?? 0,
-        renamed: readNumberValue(status.renamed) ?? 0,
-        hasConflicts,
-        conflictFiles,
-        stashCount: readNumberValue(status.stashCount) ?? 0,
-        lastCheckedAt: Date.now(),
-        ...(submodules ? { submodules } : {}),
-    };
-}
-
-function applyCachedInlineMeshNodeStatus(status: Record<string, unknown>, node: any): boolean {
-    const cachedStatus = readObjectRecord(node?.cachedStatus);
-    const git = buildCachedInlineMeshGitStatus(node);
-    const error = readStringValue(cachedStatus.error, node?.error);
-    const health = readStringValue(cachedStatus.health, node?.health);
-    const machineStatus = readStringValue(cachedStatus.machineStatus, node?.machineStatus);
-    if (!git && !error && !health) return false;
-    if (!machineStatus && !git && !error) return false;
-    if (git) status.git = git;
-    if (error) status.error = error;
-    if (health) {
-        status.health = health;
-        return true;
-    }
-    if (git) {
-        const dirty = Number(git.staged || 0) + Number(git.modified || 0) + Number(git.untracked || 0) + Number(git.deleted || 0) + Number(git.renamed || 0) > 0;
-        status.health = git.isGitRepo === false ? 'degraded' : dirty ? 'dirty' : 'online';
-        return true;
-    }
-    return false;
-}
-
-async function resolveProviderTypeFromPriority(args: {
-    nodeId: string;
-    providerPriority: string[];
-    providerLoader: ProviderLoader;
-    onStatusChange?: () => void;
-}): Promise<{ providerType?: string; error?: string }> {
-    if (!args.providerPriority.length) {
-        return { error: `Node '${args.nodeId}' has no providerPriority policy; pass cliType explicitly or configure node.policy.providerPriority` };
-    }
-
-    const failed: string[] = [];
-    for (const requestedType of args.providerPriority) {
-        const normalizedType = args.providerLoader.resolveAlias(requestedType);
-        if (!args.providerLoader.isMachineProviderEnabled(normalizedType)) {
-            failed.push(`${requestedType}: disabled`);
-            continue;
-        }
-        const detected = await detectCLI(normalizedType, args.providerLoader, { includeVersion: false });
-        args.providerLoader.setCliDetectionResults([{
-            id: normalizedType,
-            installed: !!detected,
-            path: detected?.path,
-        }], false);
-        args.onStatusChange?.();
-        if (detected) return { providerType: normalizedType };
-        failed.push(`${requestedType}: not detected`);
-    }
-
-    return { error: `No usable provider detected for node '${args.nodeId}' from providerPriority: ${failed.join('; ')}` };
-}
-type MeshCoordinatorConfigFormat = 'claude_mcp_json' | 'hermes_config_yaml';
-type MeshRefineValidationStatus = 'passed' | 'failed' | 'skipped';
-type MeshRefineValidationCommand = {
-    command: string;
-    args: string[];
-    displayCommand: string;
-    category: string;
-    source: string;
-};
-
-type MeshRefineValidationSummary = {
-    status: MeshRefineValidationStatus;
-    required: true;
-    commandsRun: Array<Record<string, unknown>>;
-    rejectedCommands: Array<Record<string, unknown>>;
-    skippedReason?: string;
-    timeoutMs: number;
-    outputLimitBytes: number;
-};
-
-const REFINE_VALIDATION_CATEGORIES = ['typecheck', 'test', 'lint', 'build'] as const;
-const REFINE_VALIDATION_TIMEOUT_MS = 120_000;
-const REFINE_VALIDATION_OUTPUT_LIMIT_BYTES = 128 * 1024;
-const REFINE_VALIDATION_SUMMARY_CHARS = 2_000;
-const REFINE_VALIDATION_MAX_COMMANDS = 4;
-
-function truncateValidationOutput(value: unknown): string {
-    const text = typeof value === 'string' ? value : value == null ? '' : String(value);
-    if (text.length <= REFINE_VALIDATION_SUMMARY_CHARS) return text;
-    return `${text.slice(0, REFINE_VALIDATION_SUMMARY_CHARS)}\n[truncated ${text.length - REFINE_VALIDATION_SUMMARY_CHARS} chars]`;
-}
-
-function readPackageScripts(workspace: string): Record<string, string> {
-    try {
-        const packageJsonPath = pathJoin(workspace, 'package.json');
-        const parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-        return parsed?.scripts && typeof parsed.scripts === 'object' && !Array.isArray(parsed.scripts)
-            ? parsed.scripts as Record<string, string>
-            : {};
-    } catch {
-        return {};
-    }
-}
-
-function tokenizeValidationCommand(command: string): string[] | null {
-    const trimmed = command.trim();
-    if (!trimmed) return null;
-    // Fail closed: the gate never hands shell syntax to a shell. Package-manager
-    // scripts are invoked via execFile(binary, args), and metacharacters/quotes are
-    // rejected before tokenization so `npm run test && rm -rf` cannot be smuggled in.
-    if (/[;&|<>`$\\\n\r'\"]/.test(trimmed)) return null;
-    const tokens = trimmed.split(/\s+/).filter(Boolean);
-    if (!tokens.length) return null;
-    if (tokens.some(token => !/^[A-Za-z0-9_@./:=+-]+$/.test(token))) return null;
-    return tokens;
-}
-
-function scriptMatchesValidationCategory(scriptName: string, category: string): boolean {
-    return scriptName === category || scriptName.startsWith(`${category}:`);
-}
-
-function parsePackageManagerValidationCommand(
-    rawCommand: string,
-    category: string,
-    scripts: Record<string, string>,
-    source: string,
-): { command?: MeshRefineValidationCommand; rejected?: Record<string, unknown> } {
-    const tokens = tokenizeValidationCommand(rawCommand);
-    if (!tokens) {
-        return { rejected: { command: rawCommand, category, source, reason: 'unsafe command string is not allowlisted' } };
-    }
-
-    const [binary, second, third, ...rest] = tokens;
-    let scriptName = '';
-    let command = binary;
-    let args: string[] = [];
-
-    if ((binary === 'npm' || binary === 'pnpm' || binary === 'bun') && second === 'run' && third) {
-        scriptName = third;
-        args = ['run', scriptName, ...rest];
-    } else if (binary === 'npm' && second === 'test' && !third) {
-        scriptName = 'test';
-        args = ['test'];
-    } else if (binary === 'yarn' && second === 'run' && third) {
-        scriptName = third;
-        args = ['run', scriptName, ...rest];
-    } else if (binary === 'yarn' && second && !third) {
-        scriptName = second;
-        args = [scriptName];
-    } else {
-        return { rejected: { command: rawCommand, category, source, reason: 'command is not a supported package-manager script invocation' } };
-    }
-
-    if (!scriptName || !Object.prototype.hasOwnProperty.call(scripts, scriptName)) {
-        return { rejected: { command: rawCommand, category, source, script: scriptName, reason: 'script is not declared in package.json' } };
-    }
-    if (!scriptMatchesValidationCategory(scriptName, category)) {
-        return { rejected: { command: rawCommand, category, source, script: scriptName, reason: 'script name is outside the validation category allowlist' } };
-    }
-
-    return {
-        command: {
-            command,
-            args,
-            displayCommand: [command, ...args].join(' '),
-            category,
-            source,
-        },
-    };
-}
-
-function collectProjectContextValidationCandidates(mesh: any): Array<{ command: string; category: string; source: string; confidence?: string }> {
-    const commands = mesh?.projectContext?.commands;
-    if (!commands || typeof commands !== 'object' || Array.isArray(commands)) return [];
-    const candidates: Array<{ command: string; category: string; source: string; confidence?: string }> = [];
-    for (const category of REFINE_VALIDATION_CATEGORIES) {
-        const entries = Array.isArray(commands[category]) ? commands[category] : [];
-        for (const entry of entries) {
-            if (typeof entry?.command !== 'string') continue;
-            candidates.push({
-                command: entry.command,
-                category,
-                source: typeof entry.sourcePath === 'string' ? entry.sourcePath : 'projectContext.commands',
-                confidence: typeof entry.confidence === 'string' ? entry.confidence : undefined,
-            });
-        }
-    }
-    return candidates.sort((a, b) => {
-        const rank = (value?: string) => value === 'high' ? 0 : value === 'medium' ? 1 : 2;
-        return rank(a.confidence) - rank(b.confidence);
-    });
-}
-
-function collectPolicyValidationCandidates(mesh: any): Array<{ command: string; category: string; source: string }> {
-    const policy = mesh?.policy && typeof mesh.policy === 'object' && !Array.isArray(mesh.policy) ? mesh.policy : {};
-    const configured = Array.isArray(policy.validationCommands)
-        ? policy.validationCommands
-        : Array.isArray(policy.validationGate?.commands)
-            ? policy.validationGate.commands
-            : [];
-    return configured
-        .map((entry: any) => typeof entry === 'string' ? { command: entry, category: '', source: 'mesh.policy.validationCommands' } : entry)
-        .filter((entry: any) => entry && typeof entry.command === 'string')
-        .map((entry: any) => {
-            const commandText = entry.command.trim();
-            const category = REFINE_VALIDATION_CATEGORIES.find(cat => commandText.includes(` ${cat}`)) ?? '';
-            return { command: commandText, category, source: 'mesh.policy.validationCommands' };
-        })
-        .filter((entry: any) => !!entry.category);
-}
-
-function selectMeshRefineValidationCommands(mesh: any, workspace: string): { commands: MeshRefineValidationCommand[]; rejectedCommands: Array<Record<string, unknown>>; source: string } {
-    const scripts = readPackageScripts(workspace);
-    const rejectedCommands: Array<Record<string, unknown>> = [];
-    const selected: MeshRefineValidationCommand[] = [];
-    const seen = new Set<string>();
-    const candidates = [
-        ...collectPolicyValidationCandidates(mesh),
-        ...collectProjectContextValidationCandidates(mesh),
-    ];
-
-    for (const candidate of candidates) {
-        const parsed = parsePackageManagerValidationCommand(candidate.command, candidate.category, scripts, candidate.source);
-        if (parsed.rejected) {
-            rejectedCommands.push(parsed.rejected);
-            continue;
-        }
-        if (!parsed.command || seen.has(parsed.command.displayCommand)) continue;
-        selected.push(parsed.command);
-        seen.add(parsed.command.displayCommand);
-        if (selected.length >= REFINE_VALIDATION_MAX_COMMANDS) break;
-    }
-
-    if (!selected.length && candidates.length === 0) {
-        for (const category of REFINE_VALIDATION_CATEGORIES) {
-            if (!Object.prototype.hasOwnProperty.call(scripts, category)) continue;
-            const fallback = parsePackageManagerValidationCommand(`npm run ${category}`, category, scripts, 'package.json:scripts');
-            if (fallback.command && !seen.has(fallback.command.displayCommand)) {
-                selected.push(fallback.command);
-                seen.add(fallback.command.displayCommand);
-            } else if (fallback.rejected) {
-                rejectedCommands.push(fallback.rejected);
-            }
-            if (selected.length >= 2) break;
-        }
-    }
-
-    return {
-        commands: selected,
-        rejectedCommands,
-        source: selected.some(command => command.source === 'mesh.policy.validationCommands')
-            ? 'mesh_policy'
-            : selected.some(command => command.source !== 'package.json:scripts')
-                ? 'project_context'
-                : selected.length
-                    ? 'package_json_scripts'
-                    : 'unavailable',
-    };
-}
-
-async function runMeshRefineValidationGate(mesh: any, workspace: string): Promise<MeshRefineValidationSummary> {
-    const { execFile } = await import('node:child_process');
-    const { promisify } = await import('node:util');
-    const execFileAsync = promisify(execFile);
-    const selection = selectMeshRefineValidationCommands(mesh, workspace);
-    const summary: MeshRefineValidationSummary = {
-        status: 'skipped',
-        required: true,
-        commandsRun: [],
-        rejectedCommands: selection.rejectedCommands,
-        skippedReason: undefined,
-        timeoutMs: REFINE_VALIDATION_TIMEOUT_MS,
-        outputLimitBytes: REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
-    };
-
-    if (!selection.commands.length) {
-        summary.skippedReason = 'validation_unavailable: no allowlisted projectContext, mesh policy, or package.json build/test/typecheck/lint command was available';
-        return summary;
-    }
-
-    for (const candidate of selection.commands) {
-        const startedAt = Date.now();
-        try {
-            const result = await execFileAsync(candidate.command, candidate.args, {
-                cwd: workspace,
-                encoding: 'utf8',
-                timeout: REFINE_VALIDATION_TIMEOUT_MS,
-                maxBuffer: REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
-                env: { ...process.env, CI: process.env.CI || '1' },
-            });
-            summary.commandsRun.push({
-                command: candidate.command,
-                args: candidate.args,
-                displayCommand: candidate.displayCommand,
-                category: candidate.category,
-                source: candidate.source,
-                passed: true,
-                exitCode: 0,
-                durationMs: Date.now() - startedAt,
-                stdout: truncateValidationOutput(result.stdout),
-                stderr: truncateValidationOutput(result.stderr),
-            });
-        } catch (error: any) {
-            summary.commandsRun.push({
-                command: candidate.command,
-                args: candidate.args,
-                displayCommand: candidate.displayCommand,
-                category: candidate.category,
-                source: candidate.source,
-                passed: false,
-                exitCode: typeof error?.code === 'number' ? error.code : null,
-                signal: typeof error?.signal === 'string' ? error.signal : null,
-                timedOut: error?.killed === true || /timed out/i.test(String(error?.message || '')),
-                durationMs: Date.now() - startedAt,
-                stdout: truncateValidationOutput(error?.stdout),
-                stderr: truncateValidationOutput(error?.stderr || error?.message),
-            });
-            summary.status = 'failed';
-            return summary;
-        }
-    }
-
-    summary.status = 'passed';
-    return summary;
-}
-
-function loadYamlModule(): { load: (input: string) => any; dump: (input: any, options?: Record<string, any>) => string } {
-    return yaml as { load: (input: string) => any; dump: (input: any, options?: Record<string, any>) => string };
-}
-
-function getMcpServersKey(format: MeshCoordinatorConfigFormat): 'mcpServers' | 'mcp_servers' {
-    return format === 'hermes_config_yaml' ? 'mcp_servers' : 'mcpServers';
-}
-
-function parseMeshCoordinatorMcpConfig(text: string, format: MeshCoordinatorConfigFormat): Record<string, any> {
-    if (!text.trim()) return {};
-    if (format === 'claude_mcp_json') return JSON.parse(text);
-    const parsed = loadYamlModule().load(text);
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
-}
-
-function serializeMeshCoordinatorMcpConfig(config: Record<string, any>, format: MeshCoordinatorConfigFormat): string {
-    if (format === 'claude_mcp_json') return JSON.stringify(config, null, 2);
-    return loadYamlModule().dump(config, { noRefs: true, lineWidth: 120 });
-}
-
-function resolveHermesUserHome(): string {
-    const explicitHome = process.env.HERMES_HOME?.trim();
-    return explicitHome || pathJoin(homedir(), '.hermes');
-}
-
-function loadHermesCoordinatorBaseConfig(targetConfigPath: string): { config: Record<string, any>; sourceHome: string; sourceConfigPath: string } {
-    const sourceHome = resolveHermesUserHome();
-    const sourceConfigPath = pathJoin(sourceHome, 'config.yaml');
-    if (!fs.existsSync(sourceConfigPath)) return { config: {}, sourceHome, sourceConfigPath };
-    if (pathResolve(sourceConfigPath) === pathResolve(targetConfigPath)) return { config: {}, sourceHome, sourceConfigPath };
-
-    const parsed = parseMeshCoordinatorMcpConfig(fs.readFileSync(sourceConfigPath, 'utf-8'), 'hermes_config_yaml');
-    const { mcp_servers: _mcpServers, ...baseConfig } = parsed;
-    return { config: baseConfig, sourceHome, sourceConfigPath };
-}
-
-function stripHermesCoordinatorTempModelProviderOverrides(config: Record<string, any>): Record<string, any> {
-    const {
-        model: _model,
-        provider: _provider,
-        default_model: _defaultModel,
-        defaultProvider: _defaultProvider,
-        default_provider: _defaultProviderSnake,
-        modelProvider: _modelProvider,
-        model_provider: _modelProviderSnake,
-        ...sanitized
-    } = config;
-    const delegation = sanitized.delegation;
-    if (delegation && typeof delegation === 'object' && !Array.isArray(delegation)) {
-        const {
-            model: _delegationModel,
-            provider: _delegationProvider,
-            modelProvider: _delegationModelProvider,
-            model_provider: _delegationModelProviderSnake,
-            ...delegationRest
-        } = delegation;
-        if (Object.keys(delegationRest).length > 0) {
-            sanitized.delegation = delegationRest;
-        } else {
-            delete sanitized.delegation;
-        }
-    }
-    return sanitized;
-}
-
-function copyHermesCoordinatorCredentialFiles(sourceHome: string, targetHome: string) {
-    if (pathResolve(sourceHome) === pathResolve(targetHome)) return;
-    for (const fileName of ['.env', 'auth.json']) {
-        const sourcePath = pathJoin(sourceHome, fileName);
-        const targetPath = pathJoin(targetHome, fileName);
-        if (!fs.existsSync(sourcePath)) continue;
-        try {
-            fs.copyFileSync(sourcePath, targetPath);
-        } catch (error: any) {
-            LOG.warn('MeshCoordinator', `Could not copy Hermes ${fileName} into isolated coordinator home: ${error?.message || error}`);
-        }
-    }
-}
+import { execFileSync } from 'node:child_process';
+
+// ─── Extracted-module imports (symbols the dispatch class consumes) ───
+import {
+    foldMeshNodeIdentityToCanonical,
+    inlineMeshCarriesTransientNodeTruth,
+    MESH_DIRECT_PROBE_REUSE_MS,
+    MeshGitProbeCache,
+    normalizeInlineMeshNodeIdentity,
+    readInlineMeshNodeId,
+    readObjectRecord,
+    readStringValue,
+    reconcileInlineMeshCache,
+    sanitizeInlineMesh,
+} from '../mesh/mesh-node-identity.js';
+import {
+    alignRefinerySubmodulesAfterMerge,
+    buildMeshRefineValidationPlan,
+    buildSubmodulePublishRequiredNextStep,
+    checkWorktreeChangesPatchEquivalentInRef,
+    MeshRefineAsyncJobStatus,
+    MeshRefineBatchJobHandle,
+    MeshRefineBatchJobStatus,
+    MeshRefineBatchTerminalJob,
+    MeshRefineJobHandle,
+    MeshRefineTerminalJob,
+    MeshWorktreePatchContainmentSummary,
+    recordMeshRefineStage,
+    RefineContext,
+    RefineExecFileAsync,
+    RefineStageOutcome,
+    resolveRefineryAutoPublishSubmoduleMainCommits,
+    runMeshRefineEffectiveDiffGate,
+    runMeshRefinePatchEquivalenceGate,
+    runMeshRefineSubmoduleReachabilityGate,
+    runMeshRefineValidationGate,
+    truncateValidationOutput,
+} from '../mesh/mesh-refine-gates.js';
+// ─── Refinery job orchestration (bodies extracted from this file) ───
+import {
+    batchRefineMeshNodes,
+    resumePendingRefineJobsOnStartup,
+    startMeshRefineBatchJob,
+    startMeshRefineJob,
+} from './router-refine.js';
+// ─── Worktree / mesh-session cleanup (bodies extracted from this file) ───
+import {
+    bestEffortRemoveWorktreeDir,
+    cleanupLocalWorktreeNode,
+    cleanupMeshSessions,
+    getWorktreeForceCleanupConvergence,
+    isCompletedHostedSession,
+    precheckLocalWorktreeRemovable,
+    recordIntentionalMeshSessionStop,
+    sessionMatchesMeshNode,
+} from './router-worktree-cleanup.js';
+// ─── Aggregate mesh-status cache (bodies extracted from this file) ───
+import {
+    getCachedAggregateMeshStatus,
+    hydrateCachedAggregateMeshStatusFromInline,
+    rememberAggregateMeshStatus,
+} from './router-aggregate-status.js';
+// ─── Remote mesh-session owner resolution (bodies extracted from this file) ───
+import { resolveRemoteMeshSessionOwnerDaemonId } from './router-mesh-session-owner.js';
+
+// ─── Barrel re-exports: node-identity / git-freshness, refine gates, coordinator config ───
+// These modules were split out of router.ts. Re-export their public surface so the
+// many existing `from '.../commands/router.js'` named imports keep resolving here.
+export * from '../mesh/mesh-node-identity.js';
+export * from '../mesh/mesh-refine-gates.js';
+export * from '../mesh/mesh-coordinator-config.js';
 
 // ─── Types ───
 
@@ -644,12 +135,14 @@ export interface CommandRouterDeps {
     /** Reference to detected IDEs array (mutable — router updates it) */
     detectedIdes: { value: any[] };
     sessionRegistry: SessionRegistry;
-    /** Callback for CDP manager creation after launch_ide */
+    /** Callback after CDP manager created (transport-specific extras) */
     onCdpManagerCreated?: (ideType: string, manager: DaemonCdpManager) => void;
     /** Callback after IDE connected (e.g., startAgentStreamPolling) */
     onIdeConnected?: () => void;
     /** Callback after status change (stop_ide, restart) */
     onStatusChange?: () => void;
+    /** Callback when a mesh state is invalidated */
+    onMeshStateChange?: (meshId: string) => void;
     /** Callback after chat-related commands */
     onPostChatCommand?: () => void;
     /** Get a connected CDP manager (for agent stream reset check) */
@@ -661,6 +154,10 @@ export interface CommandRouterDeps {
     statusVersion?: string;
     /** Session host control plane */
     sessionHostControl?: SessionHostControlPlane | null;
+    /** Selected-coordinator mesh peer telemetry surface for target daemons, when supported by the runtime. */
+    getMeshPeerConnectionStatus?: (daemonId: string) => Record<string, unknown> | null;
+    /** Dispatch a command to a remote mesh node via P2P/relay. Injected by cloud runtime; absent in standalone. */
+    dispatchMeshCommand?: (daemonId: string, cmd: string, args: Record<string, unknown>) => Promise<unknown>;
 }
 
 export interface CommandRouterResult {
@@ -673,7 +170,30 @@ const CHAT_COMMANDS = [
     'send_chat', 'new_chat', 'switch_chat', 'set_mode',
     'change_model',
 ];
-const READ_DEBUG_ENABLED = process.argv.includes('--dev') || process.env.ADHDEV_READ_DEBUG === '1';
+
+// [Z] Session-scoped commands that must be forwarded to the owning REMOTE worker daemon
+// when their target session is not hosted on this coordinator. These are the interactive
+// controlbar / modal mutations the dashboard issues against a specific session:
+//   - invoke_provider_script: controlbar Model/Mode selectors run a provider script
+//   - resolve_action:         approve/reject a modal prompt
+//   - set_mode / change_model / set_thought_level: direct control mutations
+// send_chat is intentionally NOT here — it already reaches the worker by its own route and
+// double-forwarding would be redundant. read_chat is also excluded: it can serve historical
+// transcript data locally and has its own inactive-session fallback in the CommandHandler.
+const MESH_FORWARDABLE_SESSION_COMMANDS = new Set([
+    'invoke_provider_script',
+    'resolve_action',
+    'set_mode',
+    'change_model',
+    'set_thought_level',
+    // agent_command (send_chat / clear_history / stop) is session-scoped too: a command
+    // explicitly naming a targetSessionId MUST reach that session wherever it lives, never a
+    // different local session. Without forwarding, a misrouted/relayed send_chat for a REMOTE
+    // worker session that reaches the wrong daemon used to fuzzy-inject the task body into that
+    // daemon's own CLI session (TASKECHO coordinator self-echo). Forwarding to the owning daemon
+    // delivers it to the real worker instead. (findAdapter is also fail-closed as the backstop.)
+    'agent_command',
+]);
 
 function normalizeCommandSource(source: string): CommandLogEntry['source'] {
     switch (source) {
@@ -696,140 +216,458 @@ function normalizeCommandArgsWithInteractionId(args: any): Record<string, unknow
     return base;
 }
 
-function toHostedCliRuntimeDescriptor(record: any): HostedCliRuntimeDescriptor | null {
-    if (!record || typeof record !== 'object') return null;
-    const runtimeId = typeof record.sessionId === 'string' ? record.sessionId : '';
-    const cliType = typeof record.providerType === 'string' ? record.providerType : '';
-    const workspace = typeof record.workspace === 'string' ? record.workspace : '';
-    if (!runtimeId || !cliType || !workspace) return null;
-    return {
-        runtimeId,
-        runtimeKey: typeof record.runtimeKey === 'string' ? record.runtimeKey : undefined,
-        displayName: typeof record.displayName === 'string' ? record.displayName : undefined,
-        workspaceLabel: typeof record.workspaceLabel === 'string' ? record.workspaceLabel : undefined,
-        lifecycle: typeof record.lifecycle === 'string' ? record.lifecycle as HostedCliRuntimeDescriptor['lifecycle'] : undefined,
-        recoveryState: typeof record.meta?.runtimeRecoveryState === 'string'
-            ? String(record.meta.runtimeRecoveryState)
-            : null,
-        cliType,
-        workspace,
-        cliArgs: Array.isArray(record.meta?.cliArgs) ? record.meta.cliArgs as string[] : [],
-        providerSessionId: typeof record.meta?.providerSessionId === 'string'
-            ? String(record.meta.providerSessionId)
-            : undefined,
-    };
-}
-
-function getWriteConflictOwnerClientId(error: unknown): string | undefined {
-    const message = typeof error === 'string'
-        ? error
-        : error instanceof Error
-            ? error.message
-            : '';
-    const match = /^Write owned by\s+(.+)$/.exec(message.trim());
-    return match?.[1]?.trim() || undefined;
-}
-
-function summarizeSessionHostRecord(result: unknown): Record<string, unknown> {
-    if (!result || typeof result !== 'object') return {};
-    const record = result as Record<string, any>;
-    return {
-        runtimeKey: typeof record.runtimeKey === 'string' ? record.runtimeKey : undefined,
-        lifecycle: typeof record.lifecycle === 'string' ? record.lifecycle : undefined,
-        surfaceKind: getSessionHostSurfaceKind(record as any),
-        attachedClientCount: Array.isArray(record.attachedClients) ? record.attachedClients.length : undefined,
-        hasWriteOwner: !!record.writeOwner,
-        writeOwnerClientId: typeof record.writeOwner?.clientId === 'string' ? record.writeOwner.clientId : undefined,
-    };
-}
-
-function summarizeSessionHostRecords(result: unknown): Record<string, unknown> {
-    const records = Array.isArray(result) ? result : [];
-    const groups = partitionSessionHostRecords(records as any[]);
-    return {
-        sessionCount: records.length,
-        liveRuntimeCount: groups.liveRuntimes.length,
-        recoverySnapshotCount: groups.recoverySnapshots.length,
-        inactiveRecordCount: groups.inactiveRecords.length,
-    };
-}
-
-function summarizeSessionHostDiagnostics(result: unknown): Record<string, unknown> {
-    const diagnostics = result && typeof result === 'object' ? result as Record<string, any> : {};
-    const sessions = Array.isArray(diagnostics.sessions) ? diagnostics.sessions : [];
-    return {
-        runtimeCount: typeof diagnostics.runtimeCount === 'number' ? diagnostics.runtimeCount : undefined,
-        ...summarizeSessionHostRecords(sessions),
+/**
+ * Confine a spec path to ~/.adhdev/providers, defeating both prefix-bypass
+ * (e.g. ".../providers-evil") and symlink escape. Resolves the real path of
+ * the *parent* directory (the file may not exist yet for writes), requires the
+ * basename to be a literal `*.json`, and re-joins under the verified parent so
+ * the returned path can't point outside the tree. Used by get/write_spec_source.
+ */
+export function normalizeStandaloneHostCommandUrl(hostAddress: string): string {
+    const raw = hostAddress.trim();
+    if (!raw) throw new Error('hostAddress required');
+    const url = new URL(raw.replace(/^ws:/, 'http:').replace(/^wss:/, 'https:'));
+    url.pathname = '/api/v1/command';
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+
+export function buildMemberJoinNode(mesh: any, args: any, fallbackDaemonId?: string): Record<string, unknown> | null {
+    const requestedNodeId = typeof args?.memberNodeId === 'string' ? args.memberNodeId.trim() : '';
+    const explicit = args?.memberNode && typeof args.memberNode === 'object' && !Array.isArray(args.memberNode)
+        ? args.memberNode as Record<string, any>
+        : null;
+    const configured = Array.isArray(mesh?.nodes)
+        ? (requestedNodeId
+            ? mesh.nodes.find((node: any) => meshNodeIdMatches(node, requestedNodeId))
+            : mesh.nodes[0])
+        : null;
+    const source = explicit || configured;
+    const workspace = typeof source?.workspace === 'string' && source.workspace.trim()
+        ? source.workspace.trim()
+        : typeof args?.workspace === 'string' && args.workspace.trim()
+            ? args.workspace.trim()
+            : process.cwd();
+    if (!workspace) return null;
+    const nodeId = typeof source?.id === 'string' && source.id.trim()
+        ? source.id.trim()
+        : typeof source?.nodeId === 'string' && source.nodeId.trim()
+            ? source.nodeId.trim()
+            : undefined;
+    const baseOverrides = source?.userOverrides && typeof source.userOverrides === 'object' && !Array.isArray(source.userOverrides)
+        ? source.userOverrides as Record<string, unknown>
+        : {};
+    // This payload is built ON THE MEMBER DAEMON, so process.platform/process.arch
+    // are the member's OWN machine. Stamp them into userOverrides so the host
+    // stores the member's real platform/arch on the node record — the coordinator's
+    // buildMeshNodeCapabilityTags then advertises os=<member-os> instead of the
+    // coordinator's own platform. Only fill values the operator hasn't already set.
+    const userOverrides: Record<string, unknown> = {
+        ...baseOverrides,
+        ...(typeof baseOverrides.platform === 'string' && baseOverrides.platform.trim() ? {} : { platform: process.platform }),
+        ...(typeof baseOverrides.arch === 'string' && baseOverrides.arch.trim() ? {} : { arch: process.arch }),
     };
-}
-
-function summarizeSessionHostPruneResult(result: unknown): Record<string, unknown> {
-    const value = result && typeof result === 'object' ? result as Record<string, any> : {};
     return {
-        duplicateGroupCount: typeof value.duplicateGroupCount === 'number' ? value.duplicateGroupCount : undefined,
-        prunedCount: Array.isArray(value.prunedSessionIds) ? value.prunedSessionIds.length : undefined,
-        keptCount: Array.isArray(value.keptSessionIds) ? value.keptSessionIds.length : undefined,
+        ...(nodeId ? { id: nodeId } : {}),
+        workspace,
+        ...(typeof source?.repoRoot === 'string' && source.repoRoot.trim() ? { repoRoot: source.repoRoot.trim() } : {}),
+        ...(typeof source?.daemonId === 'string' && source.daemonId.trim() ? { daemonId: source.daemonId.trim() } : fallbackDaemonId ? { daemonId: fallbackDaemonId } : {}),
+        ...(typeof source?.machineId === 'string' && source.machineId.trim() ? { machineId: source.machineId.trim() } : {}),
+        userOverrides,
+        policy: source?.policy && typeof source.policy === 'object' && !Array.isArray(source.policy) ? source.policy : {},
+        role: 'member',
     };
 }
 
 export class DaemonCommandRouter {
-    private deps: CommandRouterDeps;
+    /** Public (not private) so the extracted ./router-refine.ts orchestration can reach it via `self`. */
+    deps: CommandRouterDeps;
     /** In-memory cache for cloud-originating meshes passed via inlineMesh.
      *  Allows the MCP server to query mesh data via get_mesh even when
      *  the mesh doesn't exist in the local meshes.json file. */
     private inlineMeshCache = new Map<string, any>();
+    /** Tombstones for inline mesh nodes removed via remove_mesh_node, keyed by
+     *  meshId → set of removed nodeIds. The dashboard keeps echoing the removed
+     *  node in the inlineMesh it attaches to every command; without a tombstone,
+     *  reconcileInlineMeshCache MERGEs it straight back (resurrection). A
+     *  tombstoned node is skipped during reconcile only while its workspace is
+     *  absent from disk — a genuine re-registration (same nodeId, workspace back
+     *  on disk) clears the tombstone and merges normally, preserving clone
+     *  worktree visibility and legitimate node re-creation. */
+    private removedInlineMeshNodeIds = new Map<string, Set<string>>();
+    /** Coordinator-owned whole-mesh aggregate status snapshots. Browser callers read this by default.
+     *  Public (not private) so the extracted ./router-aggregate-status.ts orchestration can reach it via `self`. */
+    aggregateMeshStatusCache = new Map<string, { builtAt: number; snapshot: any; queueRevision: string }>();
+    /** Shared per-peer git_status probe dedup + recently-probed reuse gate.
+     *  Spans separate mesh_status/get_mesh calls so the dashboard auto-retry
+     *  loop cannot storm a slow peer with back-to-back refreshUpstream probes. */
+    private meshGitProbeCache = new MeshGitProbeCache(MESH_DIRECT_PROBE_REUSE_MS);
+    /** Meshes with a background SWR freshen (async mesh_status refresh) already in
+     *  flight — so a burst of interactive detail-opens serves the cached snapshot
+     *  and coalesces onto ONE background refresh instead of storming the peers. */
+    private swrRefreshInFlight = new Set<string>();
+    /** In-memory async Refinery jobs keyed by meshId:nodeId to reject/return duplicate in-flight requests.
+     *  Public (not private) so the extracted ./router-refine.ts orchestration can reach it via `self`. */
+    runningRefineJobs = new Map<string, MeshRefineJobHandle>();
+    /** Terminal async Refinery jobs preserve a clear answer after the worktree node has been removed. */
+    terminalRefineJobs = new Map<string, MeshRefineTerminalJob>();
+    /** In-memory async batch Refinery jobs keyed by meshId (one batch convergence per mesh at a time). */
+    runningRefineBatchJobs = new Map<string, MeshRefineBatchJobHandle>();
+    /** Terminal async batch Refinery jobs preserve the last batch outcome for late readers. */
+    terminalRefineBatchJobs = new Map<string, MeshRefineBatchTerminalJob>();
 
     constructor(deps: CommandRouterDeps) {
         this.deps = deps;
     }
 
+    // ─── Aggregate mesh-status cache ────────────────────────────────────
+    // Implementation lives in ./router-aggregate-status.ts (behavior-preserving
+    // code move). Kept here as thin delegators: getCachedAggregateMeshStatus /
+    // rememberAggregateMeshStatus are bound into HighFamilyContext, so callers
+    // reach these via `self.` for correct instance dispatch.
+
+    private hydrateCachedAggregateMeshStatusFromInline(snapshot: any, mesh: any, options?: { requireDirectPeerTruth?: boolean }): any {
+        return hydrateCachedAggregateMeshStatusFromInline(this, snapshot, mesh, options);
+    }
+
+    private getCachedAggregateMeshStatus(
+        meshId: string,
+        mesh?: any,
+        options?: { requireDirectPeerTruth?: boolean; allowStalePending?: boolean },
+    ): any | null {
+        return getCachedAggregateMeshStatus(this, meshId, mesh, options);
+    }
+
+    private rememberAggregateMeshStatus(meshId: string, snapshot: any, refreshReason: string): any {
+        return rememberAggregateMeshStatus(this, meshId, snapshot, refreshReason);
+    }
+
+    public getCachedInlineMeshNodes(): any[] {
+        const nodes: any[] = [];
+        for (const mesh of this.inlineMeshCache.values()) {
+            if (Array.isArray(mesh?.nodes)) {
+                nodes.push(...mesh.nodes);
+            }
+        }
+        return nodes;
+    }
+
+    // ─── Remote mesh-session owner resolution ───────────────────────────
+    // Implementation lives in ./router-mesh-session-owner.ts (behavior-preserving
+    // code move). resolveRemoteMeshSessionOwnerDaemonId stays public (the [Z]
+    // session-scoped forward in executeDaemonCommand and a unit test call it), so
+    // it's kept here as a thin delegator.
+
+    public resolveRemoteMeshSessionOwnerDaemonId(sessionId: string, ownerNodeIdHint?: string): string | undefined {
+        return resolveRemoteMeshSessionOwnerDaemonId(this, sessionId, ownerNodeIdHint);
+    }
+
     public getCachedInlineMesh(meshId: string, inlineMesh?: unknown): any | undefined {
         if (inlineMesh && typeof inlineMesh === 'object') {
-            this.inlineMeshCache.set(meshId, inlineMesh as any);
-            return inlineMesh as any;
+            return this.warmInlineMeshCache(meshId, inlineMesh);
         }
         return this.inlineMeshCache.get(meshId);
     }
 
-    private async getMeshForCommand(
+    private warmInlineMeshCache(meshId: string, inlineMesh?: unknown): any | undefined {
+        if (!inlineMesh || typeof inlineMesh !== 'object') return undefined;
+        // Save-boundary node-id normalization: reconcile each node's identity so
+        // `id` and `nodeId` agree before it enters the cache, so reconcile keys
+        // and the round-trip through the status serializer stay form-stable.
+        const sanitizedInlineMesh = this.applyInlineMeshNodeTombstones(
+            meshId,
+            sanitizeInlineMesh(normalizeInlineMeshNodeIdentity(inlineMesh as any)),
+        );
+        const cached = this.inlineMeshCache.get(meshId);
+        if (cached) {
+            const merged = reconcileInlineMeshCache(cached, sanitizedInlineMesh);
+            this.inlineMeshCache.set(meshId, merged);
+            return merged;
+        }
+        this.inlineMeshCache.set(meshId, sanitizedInlineMesh as any);
+        return sanitizedInlineMesh as any;
+    }
+
+    async getMeshForCommand(
         meshId: string,
         inlineMesh?: unknown,
         options?: { preferInline?: boolean },
-    ): Promise<{ mesh: any; inline: boolean } | null> {
-        const preferInline = options?.preferInline === true;
+    ): Promise<{ mesh: any; inline: boolean; source: 'inline_cache' | 'inline_bootstrap' | 'local_config' } | null> {
+        // Default to inline-cache-preferred: a caller that omits the flag still sees
+        // inline-cache-only (worktree clone) nodes in the resolved mesh view, closing
+        // the CLAIMSTALL gap where a missed `preferInline: true` silently dropped them.
+        // An explicit `preferInline: false` is still honored for any local-config-only
+        // read that deliberately bypasses the inline cache.
+        const preferInline = options?.preferInline !== false;
         if (preferInline) {
-            const cached = this.getCachedInlineMesh(meshId, inlineMesh);
-            if (cached) return { mesh: cached, inline: true };
+            const cached = this.getCachedInlineMesh(meshId);
+            if (cached) {
+                if (inlineMeshCarriesTransientNodeTruth(inlineMesh)) {
+                    const merged = reconcileInlineMeshCache(
+                        cached,
+                        this.applyInlineMeshNodeTombstones(meshId, inlineMesh as any),
+                    );
+                    this.inlineMeshCache.set(meshId, sanitizeInlineMesh(normalizeInlineMeshNodeIdentity(merged)));
+                    return { mesh: merged, inline: true, source: 'inline_cache' };
+                }
+                return { mesh: cached, inline: true, source: 'inline_cache' };
+            }
+            if (inlineMeshCarriesTransientNodeTruth(inlineMesh)) {
+                this.warmInlineMeshCache(meshId, inlineMesh);
+                return { mesh: inlineMesh, inline: true, source: 'inline_bootstrap' };
+            }
         }
         try {
             const { getMesh } = await import('../config/mesh-config.js');
             const mesh = getMesh(meshId);
-            if (mesh) return { mesh, inline: false };
+            if (mesh) return { mesh, inline: false, source: 'local_config' };
         } catch { /* fall through to inline cache */ }
-        const cached = this.getCachedInlineMesh(meshId, inlineMesh);
-        return cached ? { mesh: cached, inline: true } : null;
+        const cached = this.getCachedInlineMesh(meshId);
+        if (cached) return { mesh: cached, inline: true, source: 'inline_cache' };
+        const warmedInline = this.warmInlineMeshCache(meshId, inlineMesh);
+        return warmedInline ? { mesh: warmedInline, inline: true, source: 'inline_bootstrap' } : null;
+    }
+
+    invalidateAggregateMeshStatus(meshId: string): void {
+        this.aggregateMeshStatusCache.delete(meshId);
+        this.deps.onMeshStateChange?.(meshId);
+    }
+
+    /**
+     * Build the MedFamilyContext handed to RF-ROUTER MED family handlers. Binds the
+     * router-private collaborators those handlers need (mesh resolution, owner
+     * gating, inline-cache mutation, worktree / session cleanup, refine job
+     * starters, IDE stop/launch) plus the inline-mesh and git-probe caches. The
+     * `launchIde` field closes over the freshly-built context so restart_session /
+     * restart_ide invoke the IDE launch directly instead of recursing through
+     * executeDaemonCommand('launch_ide').
+     */
+    private buildMedFamilyContext(): MedFamilyContext {
+        const ctx: MedFamilyContext = {
+            deps: this.deps,
+            getMeshForCommand: this.getMeshForCommand.bind(this),
+            getCachedInlineMesh: this.getCachedInlineMesh.bind(this),
+            requireMeshHostMutationOwner: this.requireMeshHostMutationOwner.bind(this),
+            invalidateAggregateMeshStatus: this.invalidateAggregateMeshStatus.bind(this),
+            updateInlineMeshNode: this.updateInlineMeshNode.bind(this),
+            removeInlineMeshNode: this.removeInlineMeshNode.bind(this),
+            normalizeMeshSessionCleanupMode: this.normalizeMeshSessionCleanupMode.bind(this),
+            cleanupMeshSessions: this.cleanupMeshSessions.bind(this),
+            cleanupLocalWorktreeNode: this.cleanupLocalWorktreeNode.bind(this),
+            precheckLocalWorktreeRemovable: this.precheckLocalWorktreeRemovable.bind(this),
+            startMeshRefineJob: this.startMeshRefineJob.bind(this),
+            batchRefineMeshNodes: this.batchRefineMeshNodes.bind(this),
+            startMeshRefineBatchJob: this.startMeshRefineBatchJob.bind(this),
+            stopIde: this.stopIde.bind(this),
+            launchIde: (args: any) => launchIde(ctx, args),
+            inlineMeshCache: this.inlineMeshCache,
+            meshGitProbeCache: this.meshGitProbeCache,
+        };
+        return ctx;
+    }
+
+    /**
+     * Build the HighFamilyContext handed to RF-ROUTER HIGH family handlers. Binds
+     * the router-private collaborators those handlers need (mesh resolution, the
+     * aggregate-status memory cache + its bound read/write helpers, the
+     * running-refine-job table, inline-mesh + git-probe caches, and the router's
+     * own `execute` for the get_mesh_review_inbox mesh_status re-entry). HIGH
+     * handlers reach more router-owned state than MED, but the binding shape is
+     * the same: bound methods + direct field references, none reachable from
+     * `deps`.
+     */
+    private buildHighFamilyContext(): HighFamilyContext {
+        return {
+            deps: this.deps,
+            getMeshForCommand: this.getMeshForCommand.bind(this),
+            getCachedAggregateMeshStatus: this.getCachedAggregateMeshStatus.bind(this),
+            rememberAggregateMeshStatus: this.rememberAggregateMeshStatus.bind(this),
+            execute: this.execute.bind(this),
+            aggregateMeshStatusCache: this.aggregateMeshStatusCache,
+            swrRefreshInFlight: this.swrRefreshInFlight,
+            runningRefineJobs: this.runningRefineJobs,
+            inlineMeshCache: this.inlineMeshCache,
+            meshGitProbeCache: this.meshGitProbeCache,
+        };
+    }
+
+
+    private async requireMeshHostMutationOwner(meshId: string, inlineMesh: unknown, operation: string): Promise<CommandRouterResult | null> {
+        const meshRecord = await this.getMeshForCommand(meshId, inlineMesh, { preferInline: true });
+        const mesh = meshRecord?.mesh;
+        if (!mesh) return { success: false, error: 'Mesh not found' };
+        const meshHost = resolveMeshHostStatus(mesh);
+        if (!meshHost.canOwnCoordinator || !meshHost.canOwnQueue) {
+            return { ...buildMeshHostRequiredFailure(mesh, operation), success: false, meshId };
+        }
+        return null;
     }
 
     private updateInlineMeshNode(meshId: string, mesh: any, node: any): void {
-        if (!mesh || !Array.isArray(mesh.nodes) || !node?.id) return;
-        const idx = mesh.nodes.findIndex((entry: any) => entry?.id === node.id || entry?.nodeId === node.id);
+        const incomingId = normalizeMeshNodeId(node);
+        if (!mesh || !Array.isArray(mesh.nodes) || !incomingId) return;
+        const idx = mesh.nodes.findIndex((entry: any) => meshNodeIdMatches(entry, incomingId));
         if (idx >= 0) mesh.nodes[idx] = node;
         else mesh.nodes.push(node);
         mesh.updatedAt = new Date().toISOString();
+        // Canonicalize node identity in place (id and nodeId kept equal): clone
+        // nodes are created with `id` and re-inserted here (bypassing
+        // warmInlineMeshCache), so this is a second save boundary. In-place
+        // folding preserves the caller's `mesh` / nodes-array references, which
+        // persistWorktreeSetupState reuses across subsequent calls.
+        for (const entry of mesh.nodes) foldMeshNodeIdentityToCanonical(entry);
         this.inlineMeshCache.set(meshId, mesh);
+        this.invalidateAggregateMeshStatus(meshId);
     }
 
     private removeInlineMeshNode(meshId: string, mesh: any, nodeId: string): boolean {
         if (!mesh || !Array.isArray(mesh.nodes)) return false;
-        const idx = mesh.nodes.findIndex((entry: any) => entry?.id === nodeId || entry?.nodeId === nodeId);
+        const idx = mesh.nodes.findIndex((entry: any) => meshNodeIdMatches(entry, nodeId));
         if (idx === -1) return false;
+        const canonicalNodeId = readInlineMeshNodeId(mesh.nodes[idx]) || nodeId;
         mesh.nodes.splice(idx, 1);
         mesh.updatedAt = new Date().toISOString();
         this.inlineMeshCache.set(meshId, mesh);
+        // Tombstone the removed node so the dashboard's stale inlineMesh echo does
+        // not MERGE it back on the next command (see removedInlineMeshNodeIds).
+        this.tombstoneRemovedInlineMeshNode(meshId, canonicalNodeId);
+        if (canonicalNodeId !== nodeId) this.tombstoneRemovedInlineMeshNode(meshId, nodeId);
+        this.invalidateAggregateMeshStatus(meshId);
         return true;
     }
 
-    private normalizeMeshSessionCleanupMode(value: unknown): RepoMeshSessionCleanupMode {
+    /**
+     * WORKTREE-BOOTSTRAP-COORD-STATE: mark a worktree node's bootstrap as reaching a
+     * terminal state (complete / failed) in THIS daemon's mesh view.
+     *
+     * Root cause this fixes: clone_mesh_node forwards the clone+bootstrap to the
+     * source node's daemon (the worktree's machine). persistWorktreeSetupState
+     * therefore flips worktreeBootstrap.status to 'complete' on the WORKER daemon's
+     * mesh object — never on the coordinator's. The coordinator only ever holds the
+     * 'running' state it stamped from the forwarded clone reply. The claim path's
+     * bootstrap gate (mesh-event-forwarding agent:ready / mesh-queue-assignment)
+     * reads the coordinator's mesh via getMeshWithCache, sees status==='running'
+     * forever, and DEFERS every claim — so the worktree_bootstrap_complete re-fire
+     * (triggerMeshQueue) loops against a gate that never opens: claim never lands,
+     * the idle session is re-registered each tick, and auto-launch keeps spawning
+     * fresh sessions (runaway worktree-session multiplication).
+     *
+     * Called from the worktree_bootstrap_complete/_failed event handler BEFORE the
+     * queue re-fire so the gate sees the terminal state and the deferred claim can
+     * finally land. Updates the inline cache (clone worktree nodes are inline-only)
+     * and, when the node also exists in local config, persists there too; both paths
+     * invalidate the aggregate status cache. Best-effort and idempotent.
+     */
+    public markWorktreeBootstrapTerminalState(meshId: string, nodeId: string, status: 'complete' | 'failed', opts?: { workspace?: string }): void {
+        if (!meshId || !nodeId) return;
+        const terminalBootstrap = (prev?: Record<string, unknown>): Record<string, unknown> => ({
+            ...(prev && typeof prev === 'object' ? prev : {}),
+            status,
+            completedAt: (prev as any)?.completedAt ?? new Date().toISOString(),
+        });
+        const stamp = (mesh: any): boolean => {
+            if (!mesh || !Array.isArray(mesh.nodes)) return false;
+            const node = mesh.nodes.find((entry: any) => meshNodeIdMatches(entry, nodeId));
+            if (!node) return false;
+            const prev = (node.worktreeBootstrap && typeof node.worktreeBootstrap === 'object')
+                ? node.worktreeBootstrap as Record<string, unknown>
+                : {};
+            if (prev.status === status) return false;
+            node.worktreeBootstrap = terminalBootstrap(prev);
+            return true;
+        };
+        let changed = false;
+        // Inline cache (the authoritative view for inline-only clone worktree nodes).
+        try {
+            const cached = this.getCachedInlineMesh(meshId);
+            if (cached && stamp(cached)) {
+                cached.updatedAt = new Date().toISOString();
+                this.inlineMeshCache.set(meshId, cached);
+                changed = true;
+            } else if (!cached || !(Array.isArray(cached.nodes) && cached.nodes.some((entry: any) => meshNodeIdMatches(entry, nodeId)))) {
+                // Fix (3) HYDRATE-ON-MISS: the terminal bootstrap event arrived for a node this
+                // coordinator's inline view does NOT hold — the clone reply that would have seeded
+                // the worktree node never reached this daemon (or the inline mesh for this id is
+                // empty). With no node entry the claim gate has nothing to open, so the deferred
+                // claim (mesh-event-forwarding agent:ready / mesh-queue-assignment) strands forever
+                // and the coordinator relaunch/stop-loops. Instead of returning early, upsert a
+                // minimal worktree node carrying the terminal bootstrap status from the event
+                // payload so the gate — which reads this same inline view — sees a non-'running'
+                // state and the registered idle session can finally claim. Identity is canonicalized
+                // by updateInlineMeshNode (id/nodeId folded via the shared 3-form normalizer), so the
+                // remote-clone node-id form resolves the same way every claim-path consumer matches.
+                const shell = (cached && typeof cached === 'object')
+                    ? cached
+                    : { id: meshId, nodes: [] as any[], updatedAt: new Date().toISOString() };
+                if (!Array.isArray(shell.nodes)) shell.nodes = [];
+                const hydratedNode: any = {
+                    id: nodeId,
+                    nodeId,
+                    isLocalWorktree: true,
+                    ...(opts?.workspace ? { workspace: opts.workspace } : {}),
+                    worktreeBootstrap: terminalBootstrap(),
+                };
+                this.updateInlineMeshNode(meshId, shell, hydratedNode);
+                changed = true;
+            }
+        } catch { /* best-effort */ }
+        if (changed) this.invalidateAggregateMeshStatus(meshId);
+        // Local config (a worktree node registered via addNode also lives here).
+        // Done in a detached dynamic-import chain so the method stays sync; both the
+        // stamp and the persist are best-effort, and the inline-cache stamp above is
+        // what the coordinator's claim gate reads.
+        void import('../config/mesh-config.js')
+            .then(({ getMesh, updateNode }) => {
+                const local = getMesh(meshId);
+                if (local && stamp(local)) {
+                    const node = local.nodes.find((entry: any) => meshNodeIdMatches(entry, nodeId));
+                    if (node) updateNode(meshId, node.id, { worktreeBootstrap: node.worktreeBootstrap } as any);
+                    this.invalidateAggregateMeshStatus(meshId);
+                }
+            })
+            .catch(() => { /* persistence is best-effort */ });
+    }
+
+    private tombstoneRemovedInlineMeshNode(meshId: string, nodeId: string): void {
+        if (!nodeId) return;
+        let set = this.removedInlineMeshNodeIds.get(meshId);
+        if (!set) {
+            set = new Set<string>();
+            this.removedInlineMeshNodeIds.set(meshId, set);
+        }
+        set.add(nodeId);
+    }
+
+    /** Filter an incoming inline mesh against this mesh's tombstones before it is
+     *  reconciled into the cache. A tombstoned node is dropped only while its
+     *  workspace is still absent from disk; if the workspace is back (genuine
+     *  re-registration), the tombstone is cleared and the node merges normally. */
+    private applyInlineMeshNodeTombstones(meshId: string, incoming: any): any {
+        const tombstones = this.removedInlineMeshNodeIds.get(meshId);
+        if (!tombstones?.size || !incoming || typeof incoming !== 'object' || !Array.isArray(incoming.nodes)) {
+            return incoming;
+        }
+        let dropped = false;
+        const nodes = incoming.nodes.filter((node: any) => {
+            const nodeId = readInlineMeshNodeId(node);
+            if (!nodeId || !tombstones.has(nodeId)) return true;
+            const workspace = readStringValue(node?.workspace);
+            // Genuine re-registration: same nodeId, workspace back on disk →
+            // clear the tombstone and let the node merge normally.
+            if (workspace && fs.existsSync(workspace)) {
+                tombstones.delete(nodeId);
+                return true;
+            }
+            dropped = true;
+            return false;
+        });
+        if (tombstones.size === 0) this.removedInlineMeshNodeIds.delete(meshId);
+        if (!dropped) return incoming;
+        return { ...incoming, nodes };
+    }
+
+    normalizeMeshSessionCleanupMode(value: unknown): RepoMeshSessionCleanupMode {
         return value === 'stop'
             || value === 'delete_stopped'
             || value === 'stop_and_delete'
@@ -838,445 +676,77 @@ export class DaemonCommandRouter {
             : 'preserve';
     }
 
-    private sessionMatchesMeshNode(record: any, node: any, nodeId: string, sessionIds?: Set<string>): boolean {
-        const sessionId = typeof record?.sessionId === 'string' ? record.sessionId : '';
-        if (!sessionId) return false;
-        if (sessionIds?.size) return sessionIds.has(sessionId);
-        const workspace = typeof node?.workspace === 'string' ? node.workspace : '';
-        if (workspace && record?.workspace === workspace) return true;
-        if (record?.meta?.meshNodeId === nodeId) return true;
-        return false;
+    // ─── Worktree / mesh-session cleanup ────────────────────────────────
+    // Implementation lives in ./router-worktree-cleanup.ts (behavior-preserving
+    // code move). Kept here as thin delegators: cleanupMeshSessions /
+    // cleanupLocalWorktreeNode / precheckLocalWorktreeRemovable are bound into
+    // MedFamilyContext; bestEffortRemoveWorktreeDir is overridden on the instance
+    // by a unit test, so callers reach these via `self.` for correct dispatch.
+
+    sessionMatchesMeshNode(record: any, node: any, nodeId: string, sessionIds?: Set<string>): boolean {
+        return sessionMatchesMeshNode(this, record, node, nodeId, sessionIds);
+    }
+
+    async bestEffortRemoveWorktreeDir(dir: string): Promise<{ removed: boolean; residue: boolean; error?: string }> {
+        return bestEffortRemoveWorktreeDir(this, dir);
     }
 
-    private async cleanupLocalWorktreeNode(args: {
+    async precheckLocalWorktreeRemovable(args: {
         mesh: any;
         node: any;
         nodeId: string;
-    }): Promise<{ success: true; skipped?: boolean; removedPath?: string; repoRoot?: string; reason?: string; fallback?: string; forced?: boolean; convergence?: Record<string, unknown> } | { success: false; code: string; error: string; recoveryHint: string; convergence?: Record<string, unknown> }> {
-        const workspace = typeof args.node?.workspace === 'string' ? args.node.workspace.trim() : '';
-        if (!workspace) {
-            return {
-                success: false,
-                code: 'mesh_worktree_cleanup_missing_workspace',
-                error: `Worktree node '${args.nodeId}' is missing workspace metadata`,
-                recoveryHint: 'Inspect the mesh node record before removing it, or remove stale metadata manually only after confirming no managed worktree remains.',
-            };
-        }
-
-        const worktreeExists = fs.existsSync(workspace);
-        const sourceNode = args.node?.clonedFromNodeId
-            ? args.mesh?.nodes?.find((n: any) => n.id === args.node.clonedFromNodeId || n.nodeId === args.node.clonedFromNodeId)
-            : args.mesh?.nodes?.find((n: any) => !n.isLocalWorktree);
-        const repoRoot = typeof sourceNode?.repoRoot === 'string' && sourceNode.repoRoot.trim()
-            ? sourceNode.repoRoot.trim()
-            : typeof sourceNode?.workspace === 'string' && sourceNode.workspace.trim()
-                ? sourceNode.workspace.trim()
-                : '';
-
-        if (!worktreeExists) {
-            return { success: true, skipped: true, removedPath: workspace, repoRoot: repoRoot || undefined, reason: 'worktree_path_missing' };
-        }
-        if (!repoRoot || !fs.existsSync(repoRoot)) {
-            return {
-                success: false,
-                code: 'mesh_worktree_cleanup_missing_source_repo',
-                error: `Refusing to remove worktree '${workspace}' because the source repo root is unavailable`,
-                recoveryHint: 'Run mesh_remove_node from the machine that owns the source repo, or verify the source node metadata before retrying.',
-            };
-        }
-        if (typeof args.node?.worktreeBranch !== 'string' || !args.node.worktreeBranch.trim()) {
-            return {
-                success: false,
-                code: 'mesh_worktree_cleanup_missing_branch',
-                error: `Refusing to remove worktree '${workspace}' because worktreeBranch metadata is missing`,
-                recoveryHint: 'Confirm this is an ADHDev-managed worktree before removing it manually; managed worktree nodes include worktreeBranch metadata.',
-            };
-        }
-
-        const { resolveWorktreePath, listWorktrees, removeWorktree } = await import('../git/git-worktree.js');
-        const normalizePath = (value: string) => {
-            const resolved = pathResolve(value);
-            try { return fs.realpathSync(resolved); } catch { return resolved; }
-        };
-        const expectedPath = normalizePath(resolveWorktreePath(repoRoot, String(args.mesh?.name || args.mesh?.id || 'mesh'), args.node.worktreeBranch));
-        const actualPath = normalizePath(workspace);
-        if (actualPath !== expectedPath) {
-            return {
-                success: false,
-                code: 'mesh_worktree_cleanup_unexpected_path',
-                error: `Refusing to remove worktree '${workspace}' because it is not at the expected managed path '${expectedPath}'`,
-                recoveryHint: 'Use git worktree list/status to inspect the path. Retry only after confirming the mesh node metadata points to an ADHDev-managed worktree.',
-            };
-        }
-
-        const entries = await listWorktrees(repoRoot);
-        const managedEntry = entries.find(entry => normalizePath(entry.path) === actualPath);
-        if (!managedEntry) {
-            return {
-                success: false,
-                code: 'mesh_worktree_cleanup_not_registered',
-                error: `Refusing to remove '${workspace}' because it is not registered in git worktree list for '${repoRoot}'`,
-                recoveryHint: 'Inspect git worktree list --porcelain from the source repo. If the path was already removed, prune git worktrees before retrying.',
-            };
-        }
-        if (managedEntry.branch && managedEntry.branch !== args.node.worktreeBranch) {
-            return {
-                success: false,
-                code: 'mesh_worktree_cleanup_branch_mismatch',
-                error: `Refusing to remove '${workspace}' because git reports branch '${managedEntry.branch}', expected '${args.node.worktreeBranch}'`,
-                recoveryHint: 'Inspect the worktree branch and mesh metadata before retrying cleanup.',
-            };
-        }
-
-        const forceFallbackConvergence = await this.getWorktreeForceCleanupConvergence({
-            repoRoot,
-            workspace,
-            node: args.node,
-        });
+        force?: boolean;
+    }): Promise<{ ok: true } | { ok: false; code: string; error: string; recoveryHint: string }> {
+        return precheckLocalWorktreeRemovable(this, args);
+    }
 
-        try {
-            const result = await removeWorktree(repoRoot, workspace, {
-                requireClean: true,
-                allowSubmoduleForceFallback: forceFallbackConvergence.allow,
-            });
-            return {
-                success: true,
-                removedPath: result.removedPath,
-                repoRoot,
-                ...(result.fallback ? {
-                    fallback: result.fallback,
-                    forced: result.forced,
-                    reason: result.reason,
-                    convergence: forceFallbackConvergence,
-                } : {}),
-            };
-        } catch (e: any) {
-            const message = String(e?.message || e || 'worktree cleanup failed');
-            const dirty = message.includes('dirty worktree') || message.includes('local changes');
-            const submoduleForceBlocked = /working trees containing submodules cannot be moved or removed/i.test(message) && !forceFallbackConvergence.allow;
-            return {
-                success: false,
-                code: dirty
-                    ? 'mesh_worktree_cleanup_dirty'
-                    : submoduleForceBlocked
-                        ? 'mesh_worktree_cleanup_force_fallback_blocked'
-                        : 'mesh_worktree_cleanup_failed',
-                error: submoduleForceBlocked
-                    ? `${message}; refusing --force fallback because convergence could not be verified: ${forceFallbackConvergence.error || 'unknown convergence state'}`
-                    : message,
-                recoveryHint: dirty
-                    ? 'Commit, stash, or intentionally discard the worktree changes before retrying mesh_remove_node. The mesh registry entry is preserved until cleanup is safe.'
-                    : submoduleForceBlocked
-                        ? 'Verify the worktree branch is merged/contained in the source default branch (for example origin/main) or mark the node with a safe branchConvergence final state before retrying. The mesh registry entry is preserved.'
-                        : 'Inspect git worktree status/list from the source repo and retry after resolving the reported cleanup failure.',
-                ...(submoduleForceBlocked ? { convergence: forceFallbackConvergence } : {}),
-            };
-        }
+    async cleanupLocalWorktreeNode(args: {
+        mesh: any;
+        node: any;
+        nodeId: string;
+        force?: boolean;
+    }): Promise<{ 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; branchRefDeleted?: boolean; branchRefReason?: string; branchRefForced?: boolean; branchRefWarning?: string } | { success: false; code: string; error: string; recoveryHint: string; convergence?: Record<string, unknown> }> {
+        return cleanupLocalWorktreeNode(this, args);
     }
 
-    private async getWorktreeForceCleanupConvergence(args: {
+    async getWorktreeForceCleanupConvergence(args: {
         repoRoot: string;
         workspace: string;
         node: any;
     }): Promise<{ allow: boolean; status?: string; source?: string; ref?: string; error?: string }> {
-        const metadataStatus = typeof args.node?.branchConvergence?.status === 'string'
-            ? args.node.branchConvergence.status
-            : '';
-        if (metadataStatus === 'merged_to_main' || metadataStatus === 'cleanup_candidate') {
-            return { allow: true, status: metadataStatus, source: 'node_branch_convergence' };
-        }
-
-        const { execFile } = await import('node:child_process');
-        const { promisify } = await import('node:util');
-        const execFileAsync = promisify(execFile);
-        const runGit = async (gitArgs: string[], cwd: string): Promise<string> => {
-            const { stdout } = await execFileAsync('git', gitArgs, {
-                cwd,
-                encoding: 'utf8',
-                timeout: 30_000,
-                maxBuffer: 4 * 1024 * 1024,
-                windowsHide: true,
-            });
-            return String(stdout || '').trim();
-        };
-
-        let head = '';
-        try {
-            head = await runGit(['rev-parse', 'HEAD'], args.workspace);
-        } catch (e: any) {
-            return { allow: false, error: `could not resolve worktree HEAD: ${e?.message || e}` };
-        }
-        if (!head) return { allow: false, error: 'worktree HEAD is empty' };
-
-        const candidateRefs: string[] = [];
-        try {
-            const defaultBranch = await runGit(['branch', '--show-current'], args.repoRoot);
-            if (defaultBranch) {
-                candidateRefs.push(defaultBranch, `origin/${defaultBranch}`);
-            }
-        } catch { /* fall through to common refs */ }
-        candidateRefs.push('origin/main', 'origin/master', 'main', 'master');
-
-        const seen = new Set<string>();
-        const checkedRefs: string[] = [];
-        for (const ref of candidateRefs) {
-            if (!ref || seen.has(ref)) continue;
-            seen.add(ref);
-            let commit = '';
-            try {
-                commit = await runGit(['rev-parse', '--verify', `${ref}^{commit}`], args.repoRoot);
-            } catch {
-                continue;
-            }
-            checkedRefs.push(ref);
-            try {
-                await runGit(['merge-base', '--is-ancestor', head, commit], args.repoRoot);
-                return { allow: true, status: 'merged_to_default_ref', source: 'git_merge_base', ref };
-            } catch {
-                // Not contained in this candidate ref; keep checking other safe refs.
-            }
-        }
-
-        return {
-            allow: false,
-            status: metadataStatus || undefined,
-            error: checkedRefs.length
-                ? `worktree HEAD is not contained in checked refs: ${checkedRefs.join(', ')}`
-                : 'no default/main refs were available for convergence verification',
-        };
+        return getWorktreeForceCleanupConvergence(this, args);
     }
 
-    private isCompletedHostedSession(record: any): boolean {
-        return record?.lifecycle === 'stopped' || record?.lifecycle === 'failed' || record?.lifecycle === 'interrupted';
+    isCompletedHostedSession(record: any): boolean {
+        return isCompletedHostedSession(this, record);
     }
 
-    private async recordIntentionalMeshSessionStop(args: {
+    async recordIntentionalMeshSessionStop(args: {
         meshId: string;
         nodeId: string;
         node: any;
         sessionId: string;
         mode: RepoMeshSessionCleanupMode;
-        source: 'mesh_cleanup_sessions' | 'mesh_remove_node';
+        source: 'mesh_cleanup_sessions' | 'mesh_remove_node' | 'magi_session_cleanup';
         action: 'stop_session' | 'delete_session_force';
     }): Promise<void> {
-        try {
-            const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
-            appendLedgerEntry(args.meshId, {
-                kind: 'session_stopped',
-                nodeId: args.nodeId,
-                sessionId: args.sessionId,
-                payload: {
-                    intentional: true,
-                    reason: 'operator_cleanup',
-                    intentionalStopReason: 'operator_cleanup',
-                    source: args.source,
-                    cleanupMode: args.mode,
-                    action: args.action,
-                    workspace: typeof args.node?.workspace === 'string' ? args.node.workspace : undefined,
-                },
-            });
-        } catch (e: any) {
-            LOG.warn('MeshCleanup', `Failed to record intentional cleanup stop for ${args.sessionId}: ${e?.message || e}`);
-        }
+        return recordIntentionalMeshSessionStop(this, args);
     }
 
-    private async cleanupMeshSessions(args: {
+    async cleanupMeshSessions(args: {
         meshId: string;
         nodeId: string;
         node: any;
         mode: RepoMeshSessionCleanupMode;
         sessionIds?: string[];
         dryRun?: boolean;
-        source?: 'mesh_cleanup_sessions' | 'mesh_remove_node';
+        source?: 'mesh_cleanup_sessions' | 'mesh_remove_node' | 'magi_session_cleanup';
+        requireAutoLaunchedForTaskIds?: Record<string, string>;
+        reclaimOrphans?: boolean;
+        liveMeshNodeIds?: string[];
     }): Promise<{ success: boolean; [key: string]: unknown }> {
-        if (args.mode === 'preserve') {
-            return { success: true, mode: 'preserve', matchedCount: 0, stoppedSessionIds: [], deletedSessionIds: [], skippedSessionIds: [] };
-        }
-        if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-
-        const requestedSessionIds = Array.isArray(args.sessionIds)
-            ? new Set(args.sessionIds.map(id => typeof id === 'string' ? id.trim() : '').filter(Boolean))
-            : undefined;
-        const sessions = await this.deps.sessionHostControl.listSessions();
-        const matched = sessions.filter(record => this.sessionMatchesMeshNode(record, args.node, args.nodeId, requestedSessionIds));
-        const hasExplicitSessionIds = !!requestedSessionIds?.size;
-        const stoppedSessionIds: string[] = [];
-        const deletedSessionIds: string[] = [];
-        const skippedSessionIds: string[] = [];
-        const skippedLiveSessionIds: string[] = [];
-        const deleteUnsupportedSessionIds: string[] = [];
-        const recordsRemainSessionIds: string[] = [];
-        const errors: Array<{ sessionId: string; error: string }> = [];
-        const cleanupSource = args.source || 'mesh_cleanup_sessions';
-        const markedIntentionalStopSessionIds = new Set<string>();
-        const markIntentionalStop = async (sessionId: string, action: 'stop_session' | 'delete_session_force') => {
-            if (args.dryRun || markedIntentionalStopSessionIds.has(sessionId)) return;
-            markedIntentionalStopSessionIds.add(sessionId);
-            await this.recordIntentionalMeshSessionStop({
-                meshId: args.meshId,
-                nodeId: args.nodeId,
-                node: args.node,
-                sessionId,
-                mode: args.mode,
-                source: cleanupSource,
-                action,
-            });
-        };
-        const matchedBySurfaceKind = {
-            live_runtime: 0,
-            recovery_snapshot: 0,
-            inactive_record: 0,
-        };
-
-        for (const record of matched) {
-            const surfaceKind = getSessionHostSurfaceKind(record);
-            matchedBySurfaceKind[surfaceKind] += 1;
-        }
-
-        for (const record of matched) {
-            const sessionId = String(record.sessionId);
-            const completed = this.isCompletedHostedSession(record);
-            const surfaceKind = getSessionHostSurfaceKind(record);
-            const liveRuntime = surfaceKind === 'live_runtime';
-            if (!hasExplicitSessionIds && liveRuntime) {
-                skippedSessionIds.push(sessionId);
-                skippedLiveSessionIds.push(sessionId);
-                continue;
-            }
-            try {
-                if (args.mode === 'stop') {
-                    if (!completed) {
-                        if (!args.dryRun) {
-                            await markIntentionalStop(sessionId, 'stop_session');
-                            await this.deps.sessionHostControl.stopSession(sessionId);
-                        }
-                        stoppedSessionIds.push(sessionId);
-                    } else {
-                        skippedSessionIds.push(sessionId);
-                    }
-                    continue;
-                }
-
-                if (args.mode === 'delete_stopped') {
-                    if (completed) {
-                        if (!args.dryRun) await this.deps.sessionHostControl.deleteSession(sessionId, { force: false });
-                        deletedSessionIds.push(sessionId);
-                    } else {
-                        skippedSessionIds.push(sessionId);
-                    }
-                    continue;
-                }
-
-                if (args.mode === 'stop_and_delete') {
-                    if (!completed) await markIntentionalStop(sessionId, 'delete_session_force');
-                    if (!args.dryRun) await this.deps.sessionHostControl.deleteSession(sessionId, { force: true });
-                    deletedSessionIds.push(sessionId);
-                    continue;
-                }
-            } catch (e: any) {
-                const message = e?.message || String(e);
-                if (message.includes('Unsupported session host request: delete_session')
-                    && (args.mode === 'delete_stopped' || args.mode === 'stop_and_delete')) {
-                    deleteUnsupportedSessionIds.push(sessionId);
-                    recordsRemainSessionIds.push(sessionId);
-                    if (args.mode === 'stop_and_delete' && !completed) {
-                        try {
-                            await markIntentionalStop(sessionId, 'stop_session');
-                            await this.deps.sessionHostControl.stopSession(sessionId);
-                            stoppedSessionIds.push(sessionId);
-                        } catch (stopError: any) {
-                            errors.push({ sessionId, error: stopError?.message || String(stopError) });
-                            continue;
-                        }
-                    }
-                    skippedSessionIds.push(sessionId);
-                    continue;
-                }
-                errors.push({ sessionId, error: message });
-            }
-        }
-
-        const deleteUnsupported = deleteUnsupportedSessionIds.length > 0;
-        return {
-            success: errors.length === 0,
-            mode: args.mode,
-            dryRun: args.dryRun === true,
-            matchedCount: matched.length,
-            matchedBySurfaceKind,
-            stoppedSessionIds,
-            deletedSessionIds,
-            skippedSessionIds,
-            skippedLiveSessionIds,
-            ...(deleteUnsupported ? {
-                deleteUnsupported: true,
-                effectiveCleanup: args.mode === 'stop_and_delete'
-                    ? 'stopped_only_records_remain'
-                    : 'delete_unsupported_records_remain',
-                deleteUnsupportedSessionIds,
-                recordsRemainSessionIds,
-            } : {}),
-            ...(errors.length ? { errors } : {}),
-        };
-    }
-
-    private async traceSessionHostAction<T>(
-        action: string,
-        args: any,
-        run: () => Promise<T>,
-        summarizeResult?: (result: T) => Record<string, unknown>,
-    ): Promise<T> {
-        const interactionId = typeof args?._interactionId === 'string' ? args._interactionId : undefined;
-        const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : undefined;
-        const requestedPayload: Record<string, unknown> = { action };
-        if (sessionId) requestedPayload.sessionId = sessionId;
-        if (typeof args?.clientId === 'string') requestedPayload.clientId = args.clientId;
-        if (typeof args?.signal === 'string') requestedPayload.signal = args.signal;
-        if (typeof args?.providerType === 'string') requestedPayload.providerType = args.providerType;
-        if (typeof args?.workspace === 'string') requestedPayload.workspace = args.workspace;
-        if (typeof args?.dryRun === 'boolean') requestedPayload.dryRun = args.dryRun;
-
-        recordDebugTrace({
-            interactionId,
-            category: 'session_host',
-            stage: 'action_requested',
-            level: 'info',
-            sessionId,
-            payload: requestedPayload,
-        });
-
-        try {
-            const result = await run();
-            recordDebugTrace({
-                interactionId,
-                category: 'session_host',
-                stage: 'action_result',
-                level: 'info',
-                sessionId,
-                payload: {
-                    ...requestedPayload,
-                    success: true,
-                    ...(summarizeResult ? summarizeResult(result) : {}),
-                },
-            });
-            return result;
-        } catch (error: any) {
-            recordDebugTrace({
-                interactionId,
-                category: 'session_host',
-                stage: 'action_failed',
-                level: 'error',
-                sessionId,
-                payload: {
-                    ...requestedPayload,
-                    error: error?.message || String(error),
-                    failureKind: getWriteConflictOwnerClientId(error) ? 'write_conflict' : 'request_failed',
-                    conflictOwnerClientId: getWriteConflictOwnerClientId(error),
-                },
-            });
-            throw error;
-        }
+        return cleanupMeshSessions(this, args);
     }
-
     /**
      * Unified command routing.
      * Returns result for all commands:
@@ -1347,1631 +817,114 @@ export class DaemonCommandRouter {
         }
     }
 
-    // ─── Daemon-level command core ───────────────────
-
-    /**
-     * Daemon-level command execution (IDE start/stop/restart, CLI, detect, logs).
-     * Returns null if not handled at this level → caller delegates to CommandHandler.
-     */
-    private async executeDaemonCommand(cmd: string, args: any): Promise<CommandRouterResult | null> {
-        switch (cmd) {
-            // ─── CLI / ACP commands ───
-            case 'mesh_forward_event': {
-                return handleMeshForwardEvent({ instanceManager: this.deps.instanceManager } as any, args as Record<string, unknown>);
-            }
-
-            case 'get_pending_mesh_events': {
-                const events = drainPendingMeshCoordinatorEvents();
-                return { success: true, events };
-            }
-
-            case 'launch_cli':
-            case 'stop_cli':
-            case 'set_cli_view_mode':
-            case 'agent_command': {
-                return this.deps.cliManager.handleCliCommand(cmd, args);
-            }
-
-            // ─── Logs ───
-            case 'get_logs': {
-                const count = parseInt(args?.count) || parseInt(args?.lines) || 100;
-                const minLevel = args?.minLevel || 'info';
-                const sinceTs = args?.since || 0;
-
-                try {
-                    // Priority 1: ring buffer (fast and structured)
-                    let logs = getRecentLogs(count, minLevel);
-                    if (sinceTs > 0) {
-                        logs = logs.filter((l: any) => l.ts > sinceTs);
-                    }
-                    if (logs.length > 0) {
-                        return { success: true, logs, totalBuffered: logs.length };
-                    }
-                    // Incremental polling must not fall back to unfiltered file text: the file
-                    // format is not timestamp-filterable, and returning its tail makes the UI
-                    // replace structured logs with old raw fallback lines when nothing new exists.
-                    if (sinceTs > 0) {
-                        return { success: true, logs: [], totalBuffered: 0 };
-                    }
-                    // Priority 2: file fallback
-                    if (fs.existsSync(LOG_PATH)) {
-                        const content = fs.readFileSync(LOG_PATH, 'utf-8');
-                        const allLines = content.split('\n');
-                        const recent = allLines.slice(-count).join('\n');
-                        return { success: true, logs: recent, totalLines: allLines.length };
-                    }
-                    return { success: true, logs: [], totalBuffered: 0 };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'get_debug_trace': {
-                const count = parseInt(args?.count) || parseInt(args?.limit) || 100;
-                const sinceTs = Number(args?.since) || 0;
-                const interactionId = typeof args?.interactionId === 'string' ? args.interactionId : undefined;
-                const category = typeof args?.category === 'string' ? args.category : undefined;
-                const trace = getRecentDebugTrace({ interactionId, category, limit: count })
-                    .filter((entry) => !sinceTs || entry.ts > sinceTs);
-                return { success: true, trace, count: trace.length };
-            }
-
-            case 'session_host_get_diagnostics': {
-                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-                const diagnostics = await this.traceSessionHostAction('session_host_get_diagnostics', args, () => this.deps.sessionHostControl!.getDiagnostics({
-                    includeSessions: args?.includeSessions !== false,
-                    limit: Number(args?.limit) || undefined,
-                }), (result) => ({
-                    includeSessions: args?.includeSessions !== false,
-                    limit: Number(args?.limit) || undefined,
-                    ...summarizeSessionHostDiagnostics(result),
-                }));
-                return { success: true, diagnostics };
-            }
-
-            case 'session_host_list_sessions': {
-                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-                const sessions = await this.traceSessionHostAction('session_host_list_sessions', args, () => this.deps.sessionHostControl!.listSessions(), (records) => summarizeSessionHostRecords(records));
-                return { success: true, sessions };
-            }
-
-            case 'session_host_stop_session': {
-                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
-                if (!sessionId) return { success: false, error: 'sessionId required' };
-                const record = await this.traceSessionHostAction('session_host_stop_session', args, () => this.deps.sessionHostControl!.stopSession(sessionId), (result) => summarizeSessionHostRecord(result));
-                return { success: true, record };
-            }
-
-            case 'session_host_resume_session': {
-                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
-                if (!sessionId) return { success: false, error: 'sessionId required' };
-                const record = await this.traceSessionHostAction('session_host_resume_session', args, async () => {
-                    const nextRecord = await this.deps.sessionHostControl!.resumeSession(sessionId);
-                    const hosted = toHostedCliRuntimeDescriptor(nextRecord);
-                    if (hosted) {
-                        await this.deps.cliManager.restoreHostedSessions([hosted]);
-                    }
-                    return nextRecord;
-                }, (result) => ({
-                    ...summarizeSessionHostRecord(result),
-                    restoredHostedSession: !!toHostedCliRuntimeDescriptor(result),
-                }));
-                return { success: true, record };
-            }
-
-            case 'session_host_restart_session': {
-                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
-                if (!sessionId) return { success: false, error: 'sessionId required' };
-                const record = await this.traceSessionHostAction('session_host_restart_session', args, async () => {
-                    const nextRecord = await this.deps.sessionHostControl!.restartSession(sessionId);
-                    const hosted = toHostedCliRuntimeDescriptor(nextRecord);
-                    if (hosted) {
-                        await this.deps.cliManager.restoreHostedSessions([hosted]);
-                    }
-                    return nextRecord;
-                }, (result) => ({
-                    ...summarizeSessionHostRecord(result),
-                    restoredHostedSession: !!toHostedCliRuntimeDescriptor(result),
-                }));
-                return { success: true, record };
-            }
-
-            case 'session_host_send_signal': {
-                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
-                const signal = typeof args?.signal === 'string' ? args.signal : '';
-                if (!sessionId) return { success: false, error: 'sessionId required' };
-                if (!signal) return { success: false, error: 'signal required' };
-                const record = await this.traceSessionHostAction('session_host_send_signal', args, () => this.deps.sessionHostControl!.sendSignal(sessionId, signal), (result) => summarizeSessionHostRecord(result));
-                return { success: true, record };
-            }
 
-            case 'session_host_force_detach_client': {
-                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
-                const clientId = typeof args?.clientId === 'string' ? args.clientId : '';
-                if (!sessionId) return { success: false, error: 'sessionId required' };
-                if (!clientId) return { success: false, error: 'clientId required' };
-                const record = await this.traceSessionHostAction('session_host_force_detach_client', args, () => this.deps.sessionHostControl!.forceDetachClient(sessionId, clientId), (result) => summarizeSessionHostRecord(result));
-                return { success: true, record };
-            }
+    // ─── Refinery job orchestration ─────────────────────────────────────
+    // Implementation lives in ./router-refine.ts (behavior-preserving code move).
+    // Only the externally-referenced entry points remain here as thin delegators.
 
-            case 'session_host_prune_duplicate_sessions': {
-                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-                const result = await this.traceSessionHostAction('session_host_prune_duplicate_sessions', args, () => this.deps.sessionHostControl!.pruneDuplicateSessions({
-                    providerType: typeof args?.providerType === 'string' ? args.providerType : undefined,
-                    workspace: typeof args?.workspace === 'string' ? args.workspace : undefined,
-                    dryRun: args?.dryRun === true,
-                }), (value) => summarizeSessionHostPruneResult(value));
-                return { success: true, result };
-            }
-
-            case 'session_host_acquire_write': {
-                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
-                const clientId = typeof args?.clientId === 'string' ? args.clientId : '';
-                const ownerType = args?.ownerType === 'agent' ? 'agent' : 'user';
-                if (!sessionId) return { success: false, error: 'sessionId required' };
-                if (!clientId) return { success: false, error: 'clientId required' };
-                const record = await this.traceSessionHostAction('session_host_acquire_write', args, () => this.deps.sessionHostControl!.acquireWrite({
-                    sessionId,
-                    clientId,
-                    ownerType,
-                    force: args?.force !== false,
-                }), (result) => ({
-                    ...summarizeSessionHostRecord(result),
-                    ownerType,
-                }));
-                return { success: true, record };
-            }
-
-            case 'session_host_release_write': {
-                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
-                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
-                const clientId = typeof args?.clientId === 'string' ? args.clientId : '';
-                if (!sessionId) return { success: false, error: 'sessionId required' };
-                if (!clientId) return { success: false, error: 'clientId required' };
-                const record = await this.traceSessionHostAction('session_host_release_write', args, () => this.deps.sessionHostControl!.releaseWrite({
-                    sessionId,
-                    clientId,
-                }), (result) => summarizeSessionHostRecord(result));
-                return { success: true, record };
-            }
-
-            case 'list_saved_sessions': {
-                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 = this.deps.providerLoader.resolve?.(providerType) || this.deps.providerLoader.getMeta(providerType);
-                const { sessions: historySessions, hasMore, source } = listProviderHistorySessions(providerType, {
-                    canonicalHistory: providerMeta?.canonicalHistory,
-                    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 ───
-            case 'restart_session': {
-                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 = this.deps.cdpManagers.has(targetType) ||
-                    this.deps.providerLoader.getMeta(targetType)?.category === 'ide';
-
-                if (isIde) {
-                    // IDE restart: stop (with process kill) → launch
-                    await this.stopIde(targetType, true);
-                    const launchResult = await this.executeDaemonCommand('launch_ide', { ideType: targetType, enableCdp: true, workspace: args?.workspace });
-                    return { success: true, restarted: true, ideType: targetType, launch: launchResult };
-                }
-
-                // CLI/ACP restart: delegate to CliManager
-                return this.deps.cliManager.handleCliCommand(cmd, args);
-            }
-
-            // ─── IDE stop ───
-            case 'stop_ide': {
-                const ideType = args?.ideType;
-                if (!ideType) throw new Error('ideType required');
-                const killProcess = args?.killProcess !== false; // default true
-                await this.stopIde(ideType, killProcess);
-                try {
-                    const results = await detectIDEs(this.deps.providerLoader);
-                    this.deps.detectedIdes.value = results;
-                    this.deps.providerLoader.setIdeDetectionResults(results, true);
-                } catch { /* ignore detection refresh errors */ }
-                return { success: true, ideType, stopped: true, processKilled: killProcess };
-            }
-
-            // ─── IDE restart ───
-            case 'restart_ide': {
-                const ideType = args?.ideType;
-                if (!ideType) throw new Error('ideType required');
-                await this.stopIde(ideType, true); // always kill process on restart
-                const launchResult = await this.executeDaemonCommand('launch_ide', { ideType, enableCdp: true, workspace: args?.workspace });
-                return { success: true, ideType, restarted: true, launch: launchResult };
-            }
-
-            // ─── IDE launch + CDP connect ───
-            case 'launch_ide': {
-                const ideKey = args?.ideId || args?.ideType;
-                const resolvedWorkspace = resolveIdeLaunchWorkspace(
-                    {
-                        workspace: args?.workspace,
-                        workspaceId: args?.workspaceId,
-                        useDefaultWorkspace: args?.useDefaultWorkspace,
-                    },
-                    loadConfig(),
-                );
-                const launchArgs = {
-                    ideId: ideKey,
-                    workspace: resolvedWorkspace,
-                    newWindow: args?.newWindow,
-                };
-                LOG.info('LaunchIDE', `target=${ideKey || 'auto'}`);
-                const result = await launchWithCdp(launchArgs);
-
-                if (result.success && result.port && result.ideId && !this.deps.cdpManagers.has(result.ideId)) {
-                    const logFn = this.deps.getCdpLogFn
-                        ? this.deps.getCdpLogFn(result.ideId)
-                        : LOG.forComponent(`CDP:${result.ideId}`).asLogFn();
-                    const provider = this.deps.providerLoader.getMeta(result.ideId);
-                    const manager = new DaemonCdpManager(result.port, logFn, undefined, provider?.targetFilter);
-                    const connected = await manager.connect();
-                    if (connected) {
-                        // Register active extension providers for this IDE in CDP manager
-                        registerExtensionProviders(this.deps.providerLoader, manager, result.ideId);
-                        this.deps.cdpManagers.set(result.ideId, manager);
-                        LOG.info('CDP', `Connected: ${result.ideId} (port ${result.port})`);
-                        LOG.info('CDP', `${this.deps.cdpManagers.size} IDE(s) connected`);
-
-                        // Notify consumer (e.g. setupIdeInstance)
-                        this.deps.onCdpManagerCreated?.(result.ideId, manager);
-                    }
-                }
-                this.deps.onIdeConnected?.();
-                try {
-                    const results = await detectIDEs(this.deps.providerLoader);
-                    this.deps.detectedIdes.value = results;
-                    this.deps.providerLoader.setIdeDetectionResults(results, true);
-                } catch { /* ignore detection refresh errors */ }
-                if (result.success && resolvedWorkspace) {
-                    try {
-                        const next = appendRecentActivity(loadState(), {
-                            kind: 'ide',
-                            providerType: result.ideId || ideKey,
-                            providerName: result.ideId || ideKey,
-                            workspace: resolvedWorkspace,
-                            title: result.ideId || ideKey,
-                        });
-                        saveState(next);
-                    } catch { /* ignore activity persist errors */ }
-                } else if (result.success && (result.ideId || ideKey)) {
-                    try {
-                        saveState(appendRecentActivity(loadState(), {
-                            kind: 'ide',
-                            providerType: result.ideId || ideKey,
-                            providerName: result.ideId || ideKey,
-                            title: result.ideId || ideKey,
-                        }));
-                    } catch { /* ignore activity persist errors */ }
-                }
-                return { ...result };
-            }
-
-            // ─── Detect providers ───
-            case 'detect_provider': {
-                const providerType = typeof args?.providerType === 'string' ? args.providerType.trim() : '';
-                if (!providerType) return { success: false, error: 'providerType is required' };
-                const normalizedType = this.deps.providerLoader.resolveAlias(providerType);
-                const provider = this.deps.providerLoader.getByAlias(providerType);
-                if (!provider) return { success: false, error: `Provider not found: ${providerType}` };
-                if (provider.category !== 'cli' && provider.category !== 'acp') {
-                    return { success: false, error: `Provider detection is only supported for CLI/ACP providers: ${providerType}` };
-                }
-                if (!this.deps.providerLoader.isMachineProviderEnabled(normalizedType)) {
-                    return { success: false, error: `Provider is disabled on this machine: ${providerType}` };
-                }
-                const detected = await detectCLI(normalizedType, this.deps.providerLoader, { includeVersion: false });
-                this.deps.providerLoader.setCliDetectionResults([{
-                    id: normalizedType,
-                    installed: !!detected,
-                    path: detected?.path,
-                }], false);
-                this.deps.onStatusChange?.();
-                return {
-                    success: true,
-                    providerType: normalizedType,
-                    detected: !!detected,
-                    path: detected?.path || null,
-                };
-            }
-
-            // ─── Detect IDEs ───
-            case 'detect_ides': {
-                const results = await detectIDEs(this.deps.providerLoader);
-                this.deps.detectedIdes.value = results;
-                this.deps.providerLoader.setIdeDetectionResults(results, true);
-                return { success: true, detectedInfo: results };
-            }
-
-            // ─── Set User Name ───
-            case 'set_user_name': {
-                const name = args?.userName;
-                if (!name || typeof name !== 'string') throw new Error('userName required');
-                updateConfig({ userName: name });
-                return { success: true, userName: name };
-            }
-
-            case 'get_status_metadata': {
-                const snapshot = buildStatusSnapshot({
-                    allStates: this.deps.instanceManager.collectAllStates(),
-                    cdpManagers: this.deps.cdpManagers,
-                    providerLoader: this.deps.providerLoader,
-                    detectedIdes: this.deps.detectedIdes.value,
-                    instanceId: this.deps.statusInstanceId || loadConfig().machineId || 'daemon',
-                    version: this.deps.statusVersion || 'unknown',
-                    profile: 'metadata',
-                });
-                return { success: true, status: snapshot };
-            }
-
-            case 'get_machine_runtime_stats': {
-                return {
-                    success: true,
-                    machine: buildMachineInfo('full'),
-                    timestamp: Date.now(),
-                };
-            }
-
-            case 'mark_session_seen': {
-                const sessionId = args?.sessionId;
-                if (!sessionId || typeof sessionId !== 'string') {
-                    return { success: false, error: 'sessionId is required' };
-                }
-                const currentState = loadState();
-                const prevSeenAt = currentState.sessionReads?.[sessionId] || 0;
-                const sessionEntries = buildSessionEntries(
-                    this.deps.instanceManager.collectAllStates(),
-                    this.deps.cdpManagers,
-                );
-                const targetSession = sessionEntries.find((entry) => entry.id === sessionId);
-                const requestedCompletionMarker = typeof args?.completionMarker === 'string'
-                    ? args.completionMarker.trim()
-                    : '';
-                const completionMarker = requestedCompletionMarker || (targetSession ? getSessionCompletionMarker(targetSession) : '');
-                const requestedProviderSessionId = typeof args?.providerSessionId === 'string'
-                    ? args.providerSessionId.trim()
-                    : '';
-                const providerSessionId = requestedProviderSessionId || targetSession?.providerSessionId;
-                const next = markSessionSeen(
-                    currentState,
-                    sessionId,
-                    typeof args?.seenAt === 'number' ? args.seenAt : Date.now(),
-                    completionMarker,
-                    providerSessionId,
-                );
-                if (READ_DEBUG_ENABLED) {
-                    LOG.info('RecentRead', `mark_session_seen sessionId=${sessionId} seenAt=${String(args?.seenAt || '')} prevSeenAt=${String(prevSeenAt)} nextSeenAt=${String(next.sessionReads?.[sessionId] || 0)} marker=${completionMarker || '-'}`);
-                }
-                saveState(next);
-                this.deps.onStatusChange?.();
-                return {
-                    success: true,
-                    sessionId,
-                    seenAt: next.sessionReads?.[sessionId] || Date.now(),
-                    completionMarker,
-                };
-            }
-
-            case 'delete_notification': {
-                const sessionId = args?.sessionId;
-                const notificationId = typeof args?.notificationId === 'string' ? args.notificationId.trim() : '';
-                if (!sessionId || typeof sessionId !== 'string') {
-                    return { success: false, error: 'sessionId is required' };
-                }
-                if (!notificationId) {
-                    return { success: false, error: 'notificationId is required' };
-                }
-                const sessionEntries = buildSessionEntries(
-                    this.deps.instanceManager.collectAllStates(),
-                    this.deps.cdpManagers,
-                );
-                const targetSession = sessionEntries.find((entry) => entry.id === sessionId);
-                const next = dismissSessionNotification(
-                    loadState(),
-                    sessionId,
-                    notificationId,
-                    targetSession?.providerSessionId,
-                );
-                saveState(next);
-                this.deps.onStatusChange?.();
-                return {
-                    success: true,
-                    sessionId,
-                    notificationId,
-                };
-            }
-
-            case 'mark_notification_unread': {
-                const sessionId = args?.sessionId;
-                const notificationId = typeof args?.notificationId === 'string' ? args.notificationId.trim() : '';
-                if (!sessionId || typeof sessionId !== 'string') {
-                    return { success: false, error: 'sessionId is required' };
-                }
-                if (!notificationId) {
-                    return { success: false, error: 'notificationId is required' };
-                }
-                const sessionEntries = buildSessionEntries(
-                    this.deps.instanceManager.collectAllStates(),
-                    this.deps.cdpManagers,
-                );
-                const targetSession = sessionEntries.find((entry) => entry.id === sessionId);
-                const next = markSessionNotificationUnread(
-                    loadState(),
-                    sessionId,
-                    notificationId,
-                    targetSession?.providerSessionId,
-                );
-                saveState(next);
-                this.deps.onStatusChange?.();
-                return {
-                    success: true,
-                    sessionId,
-                    notificationId,
-                };
-            }
-
-            // ─── Daemon Self-Upgrade ───
-            case 'daemon_upgrade': {
-                LOG.info('Upgrade', 'Remote upgrade requested from dashboard');
-                try {
-                    // Detect package name for upgrade
-                    const isStandalone = this.deps.packageName === '@adhdev/daemon-standalone'
-                        || process.argv[1]?.includes('daemon-standalone');
-                    const pkgName = isStandalone ? '@adhdev/daemon-standalone' : 'adhdev';
-                    const npmSurface = resolveCurrentGlobalInstallSurface({ packageName: pkgName });
-                    const channel = resolveUpgradeChannel(args);
-                    const npmTag = CHANNEL_NPM_TAG[channel];
-
-                    // Check channel-pinned dist-tag and resolve it to a concrete install version.
-                    const latest = String(execNpmCommandSync(['view', `${pkgName}@${npmTag}`, 'version'], { encoding: 'utf-8', timeout: 10000 }, npmSurface)).trim();
-                    LOG.info('Upgrade', `Latest ${pkgName}@${npmTag}: v${latest}`);
-                    updateConfig({ updateChannel: channel, serverUrl: CHANNEL_SERVER_URL[channel] } as any);
-                    let currentInstalled: string | null = null;
-                    try {
-                        const currentJson = String(execNpmCommandSync(['ls', '-g', pkgName, '--depth=0', '--json'], {
-                            encoding: 'utf-8',
-                            timeout: 10000,
-                            stdio: ['pipe', 'pipe', 'pipe'],
-                        }, npmSurface)).trim();
-                        const parsed = JSON.parse(currentJson);
-                        currentInstalled = parsed?.dependencies?.[pkgName]?.version || null;
-                    } catch {
-                        // ignore ls failures; upgrade can still proceed
-                    }
-
-                    const runningVersion = typeof this.deps.statusVersion === 'string'
-                        ? this.deps.statusVersion.trim().replace(/^v/, '')
-                        : null;
-                    if (currentInstalled === latest && runningVersion === latest) {
-                        LOG.info('Upgrade', `Already on ${channel} channel version v${latest}; skipping install`);
-                        return { success: true, upgraded: false, alreadyLatest: true, version: latest, channel, npmTag };
-                    }
-                    if (currentInstalled === latest && runningVersion && runningVersion !== latest) {
-                        LOG.info('Upgrade', `Installed package is v${latest}, but running daemon is v${runningVersion}; scheduling restart`);
-                    }
-
-                    spawnDetachedDaemonUpgradeHelper({
-                        packageName: pkgName,
-                        targetVersion: latest,
-                        parentPid: process.pid,
-                        restartArgv: process.argv.slice(1),
-                        cwd: process.cwd(),
-                        sessionHostAppName: process.env.ADHDEV_SESSION_HOST_NAME || 'adhdev',
-                    });
-                    LOG.info('Upgrade', `Scheduled detached ${channel} upgrade to v${latest}`);
-
-                    // Exit after the command response has been sent so the helper can replace the package cleanly.
-                    setTimeout(() => {
-                        LOG.info('Upgrade', 'Exiting daemon so detached upgrader can continue...');
-                        process.exit(0);
-                    }, 3000);
-
-                    return { success: true, upgraded: true, version: latest, restarting: true, channel, npmTag };
-                } catch (e: any) {
-                    LOG.error('Upgrade', `Failed: ${e.message}`);
-                    return { success: false, error: e.message };
-                }
-            }
-
-            // ─── Machine Settings ───
-            case 'set_machine_nickname': {
-                const nickname = args?.nickname;
-                updateConfig({ machineNickname: nickname || null });
-                return { success: true };
-            }
-
-            // ─── Mesh CRUD (local meshes.json) ───
-            case 'list_meshes': {
-                try {
-                    const { listMeshes } = await import('../config/mesh-config.js');
-                    return { success: true, meshes: listMeshes() };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'get_mesh': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-                try {
-                    const { getMesh } = await import('../config/mesh-config.js');
-                    const mesh = getMesh(meshId);
-                    if (mesh) return { success: true, mesh };
-                } catch { /* fall through to inline cache */ }
-                // Fallback: check in-memory cache for cloud-originating meshes
-                const cached = this.inlineMeshCache.get(meshId);
-                if (cached) return { success: true, mesh: cached };
-                return { success: false, error: 'Mesh not found' };
-            }
-
-            case 'create_mesh': {
-                const name = typeof args?.name === 'string' ? args.name.trim() : '';
-                const repoIdentity = typeof args?.repoIdentity === 'string' ? args.repoIdentity.trim() : '';
-                const repoRemoteUrl = typeof args?.repoRemoteUrl === 'string' ? args.repoRemoteUrl.trim() : undefined;
-                const defaultBranch = typeof args?.defaultBranch === 'string' ? args.defaultBranch.trim() : undefined;
-                if (!name) return { success: false, error: 'name required' };
-                try {
-                    const { createMesh } = await import('../config/mesh-config.js');
-                    const mesh = createMesh({ name, repoIdentity, repoRemoteUrl, defaultBranch, policy: args?.policy });
-                    return { success: true, mesh };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'update_mesh': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-                try {
-                    const { updateMesh } = await import('../config/mesh-config.js');
-                    const patch: Record<string, unknown> = {};
-                    if (typeof args?.name === 'string') patch.name = args.name;
-                    if (typeof args?.defaultBranch === 'string') patch.defaultBranch = args.defaultBranch;
-                    if (args?.policy && typeof args.policy === 'object' && !Array.isArray(args.policy)) patch.policy = args.policy;
-                    if (args?.coordinator && typeof args.coordinator === 'object' && !Array.isArray(args.coordinator)) patch.coordinator = args.coordinator;
-                    if (!Object.keys(patch).length) return { success: false, error: 'No updates provided' };
-                    const mesh = updateMesh(meshId, patch as any);
-                    if (!mesh) return { success: false, error: 'Mesh not found' };
-                    this.inlineMeshCache.set(meshId, mesh);
-                    return { success: true, mesh };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'delete_mesh': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-                try {
-                    const { deleteMesh } = await import('../config/mesh-config.js');
-                    const deleted = deleteMesh(meshId);
-                    return { success: true, deleted };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'get_mesh_ledger': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-                try {
-                    const { readLedgerEntries, getLedgerSummary } = await import('../mesh/mesh-ledger.js');
-                    const tail = typeof args?.tail === 'number' ? args.tail : 20;
-                    const since = typeof args?.since === 'string' ? args.since : undefined;
-                    const kind = Array.isArray(args?.kind) ? args.kind.filter((k: any) => typeof k === 'string') : undefined;
-                    const entries = readLedgerEntries(meshId, { tail, since, kind });
-                    const summary = getLedgerSummary(meshId);
-                    return { success: true, entries, summary };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'get_mesh_ledger_slice': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-                try {
-                    const { readLedgerSlice } = await import('../mesh/mesh-ledger.js');
-                    const kind = Array.isArray(args?.kind) ? args.kind.filter((k: any) => typeof k === 'string') : undefined;
-                    const slice = readLedgerSlice(meshId, {
-                        afterId: typeof args?.afterId === 'string' ? args.afterId : undefined,
-                        since: typeof args?.since === 'string' ? args.since : undefined,
-                        kind,
-                        limit: typeof args?.limit === 'number' ? args.limit : undefined,
-                    });
-                    return { success: true, slice };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'import_mesh_ledger_slice': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-                try {
-                    const { appendRemoteLedgerEntries, getLedgerSummary } = await import('../mesh/mesh-ledger.js');
-                    const entries = Array.isArray(args?.entries)
-                        ? args.entries as any[]
-                        : Array.isArray(args?.slice?.entries)
-                            ? args.slice.entries as any[]
-                            : [];
-                    const result = appendRemoteLedgerEntries(meshId, entries as any);
-                    return { success: true, result, summary: getLedgerSummary(meshId) };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'get_mesh_queue': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-                try {
-                    const { getMeshQueueStats, getQueue } = 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 queue = getQueue(meshId, { status: status as any });
-                    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 };
-                }
-            }
-
-            case 'cancel_mesh_queue_task': {
-                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' };
-                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 };
-                }
-            }
-
-            case 'requeue_mesh_queue_task': {
-                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' };
-                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 };
-                }
-            }
-
-            case 'add_mesh_node': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                const workspace = typeof args?.workspace === 'string' ? args.workspace.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-                if (!workspace) return { success: false, error: 'workspace required' };
-                try {
-                    const { addNode } = await import('../config/mesh-config.js');
-                    const providerPriority = Array.isArray(args?.providerPriority)
-                        ? args.providerPriority.map((type: any) => typeof type === 'string' ? type.trim() : '').filter(Boolean)
-                        : [];
-                    const readOnly = args?.readOnly === true;
-                    const policy = {
-                        ...(readOnly ? { readOnly: true } : {}),
-                        ...(providerPriority.length ? { providerPriority } : {}),
-                    };
-                    const node = addNode(meshId, { workspace, ...(policy ? { policy } : {}) });
-                    if (!node) return { success: false, error: 'Mesh not found' };
-                    return { success: true, node };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'update_mesh_node': {
-                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' };
-                try {
-                    const { updateNode } = await import('../config/mesh-config.js');
-                    const policy = args?.policy && typeof args.policy === 'object' && !Array.isArray(args.policy)
-                        ? { ...(args.policy as Record<string, unknown>) }
-                        : {};
-                    if (Array.isArray(args?.providerPriority)) {
-                        const providerPriority = args.providerPriority
-                            .map((type: any) => typeof type === 'string' ? type.trim() : '')
-                            .filter(Boolean);
-                        delete (policy as any).provider_priority;
-                        if (providerPriority.length) {
-                            (policy as any).providerPriority = providerPriority;
-                        } else {
-                            delete (policy as any).providerPriority;
-                        }
-                    }
-                    const node = updateNode(meshId, nodeId, { policy: policy as any });
-                    if (!node) return { success: false, error: 'Mesh node not found' };
-                    return { success: true, node };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'cleanup_mesh_sessions': {
-                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' };
-                try {
-                    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
-                    const mesh = meshRecord?.mesh;
-                    if (!mesh) return { success: false, error: 'Mesh not found' };
-                    const node = mesh?.nodes?.find((n: any) => n.id === nodeId || n.nodeId === nodeId);
-                    if (!node) return { success: false, error: `Node '${nodeId}' not found in mesh` };
-                    const mode = this.normalizeMeshSessionCleanupMode(args?.mode ?? mesh?.policy?.sessionCleanupOnNodeRemove);
-                    const sessionIds = Array.isArray(args?.sessionIds)
-                        ? args.sessionIds.map((id: any) => typeof id === 'string' ? id.trim() : '').filter(Boolean)
-                        : undefined;
-                    const result = await this.cleanupMeshSessions({
-                        meshId,
-                        nodeId,
-                        node,
-                        mode,
-                        sessionIds,
-                        dryRun: args?.dryRun === true,
-                        source: 'mesh_cleanup_sessions',
-                    });
-                    return result;
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'refine_mesh_node': {
-                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' };
-                try {
-                    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
-                    const mesh = meshRecord?.mesh;
-                    const node = mesh?.nodes?.find((n: any) => n.id === nodeId || n.nodeId === nodeId);
-                    if (!node) return { success: false, error: `Node '${nodeId}' not found in mesh` };
-
-                    if (!node.isLocalWorktree || !node.workspace) {
-                        return { success: false, error: `Refinery requires a local worktree node` };
-                    }
-
-                    const sourceNode = node.clonedFromNodeId
-                        ? mesh?.nodes.find((n: any) => n.id === node.clonedFromNodeId || n.nodeId === node.clonedFromNodeId)
-                        : mesh?.nodes.find((n: any) => !n.isLocalWorktree);
-                    const repoRoot = sourceNode?.repoRoot || sourceNode?.workspace;
-                    if (!repoRoot) return { success: false, error: 'Source node repoRoot not found' };
-
-                    const { execFile } = await import('node:child_process');
-                    const { promisify } = await import('node:util');
-                    const execFileAsync = promisify(execFile);
-
-                    const { stdout: branchStdout } = await execFileAsync('git', ['branch', '--show-current'], { cwd: node.workspace, encoding: 'utf8' });
-                    const branch = branchStdout.trim();
-                    if (!branch) return { success: false, error: 'Could not determine branch of the worktree node' };
-
-                    const { stdout: baseBranchStdout } = await execFileAsync('git', ['branch', '--show-current'], { cwd: repoRoot, encoding: 'utf8' });
-                    const baseBranch = baseBranchStdout.trim();
-
-                    const validationSummary = await runMeshRefineValidationGate(mesh, node.workspace);
-                    if (validationSummary.status === 'failed') {
-                        return {
-                            success: false,
-                            code: 'validation_failed',
-                            convergenceStatus: 'blocked_review',
-                            error: 'Refinery validation gate failed; merge/refine was not attempted.',
-                            branch,
-                            into: baseBranch,
-                            validationSummary,
-                            finalBranchConvergenceState: {
-                                branch,
-                                baseBranch,
-                                merged: false,
-                                removed: false,
-                                validation: 'failed',
-                                status: 'blocked_review',
-                            },
-                        };
-                    }
-                    if (validationSummary.status === 'skipped') {
-                        return {
-                            success: false,
-                            code: 'validation_unavailable',
-                            convergenceStatus: 'blocked_review',
-                            error: 'Refinery validation gate is required but no allowlisted validation command was available; merge/refine was not attempted.',
-                            branch,
-                            into: baseBranch,
-                            validationSummary,
-                            finalBranchConvergenceState: {
-                                branch,
-                                baseBranch,
-                                merged: false,
-                                removed: false,
-                                validation: 'unavailable',
-                                status: 'blocked_review',
-                            },
-                        };
-                    }
-
-                    try {
-                        await execFileAsync('git', ['merge', '--no-ff', branch, '-m', `Auto-merge branch '${branch}' via Refinery`], { cwd: repoRoot, encoding: 'utf8' });
-                    } catch (e: any) {
-                        return {
-                            success: false,
-                            error: `Merge failed (conflicts?): ${e.message}`,
-                            validationSummary,
-                            finalBranchConvergenceState: {
-                                branch,
-                                baseBranch,
-                                merged: false,
-                                removed: false,
-                                validation: 'passed',
-                                status: 'not_mergeable',
-                            },
-                        };
-                    }
-
-                    const removeResult = await this.execute('remove_mesh_node', {
-                        meshId,
-                        nodeId,
-                        sessionCleanupMode: 'kill',
-                        inlineMesh: args?.inlineMesh,
-                    });
-
-                    try {
-                        const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
-                        appendLedgerEntry(meshId, {
-                            kind: 'node_removed',
-                            nodeId,
-                            payload: { refined: true, mergedBranch: branch, into: baseBranch, validationSummary },
-                        });
-                    } catch {}
-
-                    return {
-                        success: true,
-                        merged: true,
-                        branch,
-                        into: baseBranch,
-                        removeResult,
-                        validationSummary,
-                        finalBranchConvergenceState: {
-                            branch: baseBranch,
-                            mergedBranch: branch,
-                            baseBranch,
-                            merged: true,
-                            removed: removeResult?.success !== false,
-                            validation: 'passed',
-                            status: removeResult?.success === false ? 'merged_cleanup_failed' : 'merged',
-                        },
-                    };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'remove_mesh_node': {
-                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' };
-                try {
-                    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
-                    const mesh = meshRecord?.mesh;
-                    const node = mesh?.nodes?.find((n: any) => n.id === nodeId || n.nodeId === nodeId);
-
-                    const sessionCleanupMode = this.normalizeMeshSessionCleanupMode(
-                        args?.sessionCleanupMode ?? args?.session_cleanup_mode ?? mesh?.policy?.sessionCleanupOnNodeRemove,
-                    );
-                    let sessionCleanup: Record<string, unknown> | undefined;
-                    if (node && sessionCleanupMode !== 'preserve') {
-                        sessionCleanup = await this.cleanupMeshSessions({ meshId, nodeId, node, mode: sessionCleanupMode, source: 'mesh_remove_node' });
-                        if (sessionCleanup.success === false) return { success: false, removed: false, sessionCleanup };
-                    }
-
-                    let worktreeCleanup: Record<string, unknown> | undefined;
-                    if (node?.isLocalWorktree) {
-                        const cleanupResult = await this.cleanupLocalWorktreeNode({ mesh, node, nodeId });
-                        if (cleanupResult.success === false) {
-                            return {
-                                success: false,
-                                removed: false,
-                                code: cleanupResult.code,
-                                error: cleanupResult.error,
-                                recoveryHint: cleanupResult.recoveryHint,
-                                ...(sessionCleanup ? { sessionCleanup } : {}),
-                                worktreeCleanup: cleanupResult,
-                            };
-                        }
-                        worktreeCleanup = cleanupResult;
-                    }
-
-                    let removed = false;
-                    if (meshRecord?.inline) {
-                        removed = this.removeInlineMeshNode(meshId, mesh, nodeId);
-                    } else {
-                        const { removeNode } = await import('../config/mesh-config.js');
-                        removed = removeNode(meshId, nodeId);
-                    }
-
-                    // Record in task ledger
-                    if (removed) {
-                        try {
-                            const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
-                            appendLedgerEntry(meshId, {
-                                kind: 'node_removed',
-                                nodeId,
-                                payload: {
-                                    worktree: !!node?.isLocalWorktree,
-                                    sessionCleanupMode,
-                                    workspace: typeof node?.workspace === 'string' ? node.workspace : undefined,
-                                    daemonId: typeof node?.daemonId === 'string' ? node.daemonId : undefined,
-                                    worktreeBranch: typeof node?.worktreeBranch === 'string' ? node.worktreeBranch : undefined,
-                                    worktreeCleanupFallback: typeof worktreeCleanup?.fallback === 'string' ? worktreeCleanup.fallback : undefined,
-                                    forced: worktreeCleanup?.forced === true ? true : undefined,
-                                    forceFallbackReason: typeof worktreeCleanup?.reason === 'string' ? worktreeCleanup.reason : undefined,
-                                },
-                            });
-                        } catch { /* ledger append is best-effort */ }
-                    }
-
-                    return { success: true, removed, ...(sessionCleanup ? { sessionCleanup } : {}), ...(worktreeCleanup ? { worktreeCleanup } : {}) };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-
-            case 'clone_mesh_node': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                const sourceNodeId = typeof args?.sourceNodeId === 'string' ? args.sourceNodeId.trim() : '';
-                const branch = typeof args?.branch === 'string' ? args.branch.trim() : '';
-                const baseBranch = typeof args?.baseBranch === 'string' ? args.baseBranch.trim() : undefined;
-                if (!meshId) return { success: false, error: 'meshId required' };
-                if (!sourceNodeId) return { success: false, error: 'sourceNodeId required' };
-                if (!branch) return { success: false, error: 'branch required' };
-
-                try {
-                    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
-                    const mesh = meshRecord?.mesh;
-                    if (!mesh) return { success: false, error: 'Mesh not found' };
-
-                    const sourceNode = mesh.nodes?.find((n: any) => n.id === sourceNodeId || n.nodeId === sourceNodeId);
-                    if (!sourceNode) return { success: false, error: `Source node '${sourceNodeId}' not found in mesh` };
-
-                    const repoRoot = sourceNode.repoRoot || sourceNode.workspace;
-                    const { createWorktree } = await import('../git/git-worktree.js');
-                    const result = await createWorktree({
-                        repoRoot,
-                        branch,
-                        baseBranch,
-                        meshName: mesh.name,
-                    });
-
-                    let node: any;
-                    if (meshRecord.inline) {
-                        const { randomUUID } = await import('crypto');
-                        node = {
-                            id: `node_${randomUUID().replace(/-/g, '')}`,
-                            workspace: result.worktreePath,
-                            repoRoot: result.worktreePath,
-                            daemonId: sourceNode.daemonId,
-                            machineId: sourceNode.machineId ?? (sourceNode as any).machine_id,
-                            userOverrides: { ...(sourceNode.userOverrides || {}) },
-                            policy: { ...(sourceNode.policy || {}) },
-                            isLocalWorktree: true,
-                            worktreeBranch: result.branch,
-                            clonedFromNodeId: sourceNodeId,
-                        };
-                        this.updateInlineMeshNode(meshId, mesh, node);
-                    } else {
-                        const { addNode } = await import('../config/mesh-config.js');
-                        node = addNode(meshId, {
-                            workspace: result.worktreePath,
-                            repoRoot: result.worktreePath,
-                            daemonId: sourceNode.daemonId,
-                            machineId: sourceNode.machineId ?? (sourceNode as any).machine_id,
-                            userOverrides: { ...(sourceNode.userOverrides || {}) },
-                            isLocalWorktree: true,
-                            worktreeBranch: result.branch,
-                            clonedFromNodeId: sourceNodeId,
-                            policy: { ...(sourceNode.policy || {}) },
-                        });
-                        if (!node) return { success: false, error: 'Failed to register worktree node' };
-                    }
+    async resumePendingRefineJobsOnStartup(): Promise<void> {
+        return resumePendingRefineJobsOnStartup(this);
+    }
 
-                    // Initialize submodules if policy allows (default: true)
-                    const initSubmodules = (sourceNode.policy as any)?.initSubmodulesOnClone !== false;
-                    if (initSubmodules) {
-                        try {
-                            const { runGit } = await import('../git/git-executor.js');
-                            await runGit(
-                                { workspace: result.worktreePath, repoRoot: result.worktreePath, isGitRepo: true },
-                                ['submodule', 'update', '--init', '--recursive'],
-                                { timeoutMs: 120000 },
-                            );
-                        } catch (subErr: any) {
-                            // Submodule init is best-effort; don't fail the clone
-                            console.warn('[mesh] Submodule init failed for worktree:', subErr.message);
-                        }
-                    }
+    private async batchRefineMeshNodes(meshId: string, requestedNodeIds: string[] | undefined, args: any): Promise<CommandRouterResult> {
+        return batchRefineMeshNodes(this, meshId, requestedNodeIds, args);
+    }
 
-                    // Record in task ledger
-                    try {
-                        const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
-                        appendLedgerEntry(meshId, {
-                            kind: 'node_cloned',
-                            nodeId: node.id,
-                            payload: { sourceNodeId, branch: result.branch, worktreePath: result.worktreePath, submodulesInitialized: initSubmodules },
-                        });
-                    } catch { /* ledger append is best-effort */ }
-
-                    return {
-                        success: true,
-                        node,
-                        worktreePath: result.worktreePath,
-                        branch: result.branch,
-                    };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
-            case 'trigger_mesh_queue': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-                try {
-                    const { triggerMeshQueue } = await import('../mesh/mesh-events.js');
-                    if (meshId) {
-                        triggerMeshQueue(this.deps as any, meshId);
-                    }
-                    return { success: true };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
+    private async startMeshRefineBatchJob(meshId: string, requestedNodeIds: string[] | undefined, args: any): Promise<CommandRouterResult> {
+        return startMeshRefineBatchJob(this, meshId, requestedNodeIds, args);
+    }
 
-            // ─── Mesh Coordinator Launch ───
-            case 'launch_mesh_coordinator': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                let cliType = typeof args?.cliType === 'string' ? args.cliType.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-
-                try {
-                    const { buildCoordinatorSystemPrompt } = await import('../mesh/coordinator-prompt.js');
-
-                    // Support inline mesh data from cloud (bypasses local meshes.json lookup)
-                    let mesh: any;
-                    if (args?.inlineMesh && typeof args.inlineMesh === 'object') {
-                        mesh = args.inlineMesh;
-                        // Cache cloud mesh so the MCP server can retrieve it via get_mesh
-                        this.inlineMeshCache.set(meshId, mesh);
-                    } else {
-                        const { getMesh } = await import('../config/mesh-config.js');
-                        mesh = getMesh(meshId);
-                    }
-                    if (!mesh) return { success: false, error: 'Mesh not found' };
-                    if (!Array.isArray(mesh.nodes) || mesh.nodes.length === 0) return { success: false, error: 'No nodes in mesh' };
-
-                    const requestedCoordinatorNodeId = typeof args?.coordinatorNodeId === 'string'
-                        ? args.coordinatorNodeId.trim()
-                        : '';
-                    const preferredCoordinatorNodeId = requestedCoordinatorNodeId
-                        || (typeof mesh.coordinator?.preferredNodeId === 'string' ? mesh.coordinator.preferredNodeId.trim() : '');
-                    const coordinatorNode = preferredCoordinatorNodeId
-                        ? mesh.nodes.find((node: any) => node?.id === preferredCoordinatorNodeId || node?.nodeId === preferredCoordinatorNodeId)
-                        : mesh.nodes[0];
-                    if (!coordinatorNode) {
-                        return {
-                            success: false,
-                            code: 'mesh_coordinator_node_not_found',
-                            error: `Coordinator node ${preferredCoordinatorNodeId} was not found in mesh`,
-                            meshId,
-                            cliType,
-                        };
-                    }
-                    const workspace = typeof coordinatorNode.workspace === 'string' ? coordinatorNode.workspace.trim() : '';
-                    if (!workspace) return { success: false, error: 'Coordinator node workspace required', meshId, cliType };
-                    if (!cliType) {
-                        const resolved = await resolveProviderTypeFromPriority({
-                            nodeId: String(coordinatorNode.id || coordinatorNode.nodeId || preferredCoordinatorNodeId || 'coordinator'),
-                            providerPriority: readProviderPriorityFromPolicy(coordinatorNode.policy),
-                            providerLoader: this.deps.providerLoader,
-                            onStatusChange: this.deps.onStatusChange,
-                        });
-                        if (!resolved.providerType) {
-                            return {
-                                success: false,
-                                code: 'mesh_coordinator_provider_priority_unusable',
-                                error: resolved.error || 'No usable provider found from node providerPriority',
-                                meshId,
-                                cliType,
-                                workspace,
-                            };
-                        }
-                        cliType = resolved.providerType;
-                    }
-                    const providerMeta = this.deps.providerLoader.resolve?.(cliType) || this.deps.providerLoader.getMeta(cliType);
-                    const coordinatorSetup = resolveMeshCoordinatorSetup({
-                        provider: providerMeta,
-                        cliType,
-                        meshId,
-                        workspace,
-                    });
-
-                    if (coordinatorSetup.kind === 'unsupported') {
-                        return {
-                            success: false,
-                            code: 'mesh_coordinator_unsupported',
-                            error: coordinatorSetup.reason,
-                            meshId,
-                            cliType,
-                            workspace,
-                        };
-                    }
+    private async startMeshRefineJob(meshId: string, nodeId: string, args: any): Promise<CommandRouterResult> {
+        return startMeshRefineJob(this, meshId, nodeId, args);
+    }
 
-                    if (coordinatorSetup.kind === 'manual') {
-                        return {
-                            success: false,
-                            code: 'mesh_coordinator_manual_mcp_setup_required',
-                            error: coordinatorSetup.instructions,
-                            meshId,
-                            cliType,
-                            workspace,
-                            meshCoordinatorSetup: coordinatorSetup,
-                        };
-                    }
+    // ─── Daemon-level command core ───────────────────
 
-                    // ─── CLI-command MCP registration (Codex, Gemini CLI) ───────────
-                    if (coordinatorSetup.kind === 'cli_command') {
-                        // Build coordinator prompt first — fail closed on errors.
-                        let cliCmdSystemPrompt = '';
-                        try {
-                            cliCmdSystemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType });
-                        } catch (error: any) {
-                            const message = error?.message || String(error);
-                            LOG.error('MeshCoordinator', `Failed to build coordinator prompt: ${message}`);
-                            return {
-                                success: false,
-                                code: 'mesh_coordinator_prompt_failed',
-                                error: `Failed to build Repo Mesh coordinator prompt: ${message}`,
-                                meshId, cliType, workspace,
-                            };
-                        }
-
-                        // Run the provider's MCP registration command.
-                        try {
-                            const { execFileSync: execCmdSync } = await import('node:child_process');
-                            const cmdParts = coordinatorSetup.command.trim().split(/\s+/);
-                            const [regCmd, ...regArgs] = cmdParts;
-                            LOG.info('MeshCoordinator', `Running MCP registration: ${coordinatorSetup.command}`);
-                            execCmdSync(regCmd, regArgs, { stdio: 'pipe', timeout: 15_000 });
-                        } catch (error: any) {
-                            // Non-fatal — server may already be registered (providers return exit 1 on duplicate).
-                            LOG.warn('MeshCoordinator', `MCP registration command failed (may be pre-registered): ${error?.message || error}`);
-                        }
-
-                        // Inject system prompt using provider-native methods.
-                        // Codex: -c 'instructions="..."' CLI config override
-                        // Gemini: write GEMINI.md to workspace (auto-loaded as context)
-                        const cliCmdArgs: string[] = [];
-                        const cliCmdEnv: Record<string, string> = {};
-                        if (cliCmdSystemPrompt) {
-                            if (cliType === 'codex-cli') {
-                                // Codex reads `developer_instructions` from config.toml as system instructions.
-                                // The -c flag overrides a config key for this session only.
-                                cliCmdArgs.push('-c', `developer_instructions=${JSON.stringify(cliCmdSystemPrompt)}`);
-                            } else if (cliType === 'gemini-cli') {
-                                // Gemini CLI auto-loads GEMINI.md from CWD as project context.
-                                // Write a temporary GEMINI.md to the workspace before launch.
-                                try {
-                                    const { writeFileSync: wfs, existsSync: efs, readFileSync: rfs } = await import('node:fs');
-                                    const geminiMdPath = `${workspace}/GEMINI.md`;
-                                    const marker = '<!-- adhdev-mesh-coordinator-prompt -->';
-                                    const markerEnd = '<!-- /adhdev-mesh-coordinator-prompt -->';
-                                    const block = `${marker}\n${cliCmdSystemPrompt}\n${markerEnd}`;
-                                    if (efs(geminiMdPath)) {
-                                        const existing = rfs(geminiMdPath, 'utf-8');
-                                        // Replace existing block or append
-                                        const replaced = existing.replace(
-                                            new RegExp(`${marker}[\\s\\S]*?${markerEnd}`, 'g'),
-                                            block,
-                                        );
-                                        wfs(geminiMdPath, replaced.includes(marker) ? replaced : `${existing}\n\n${block}`);
-                                    } else {
-                                        wfs(geminiMdPath, block);
-                                    }
-                                    LOG.info('MeshCoordinator', `Wrote coordinator prompt to ${workspace}/GEMINI.md`);
-                                } catch (e: any) {
-                                    LOG.warn('MeshCoordinator', `Could not write GEMINI.md: ${e?.message || e}`);
-                                }
-                            }
-                        }
-
-                        const cliCmdLaunch: any = await this.deps.cliManager.handleCliCommand('launch_cli', {
-                            cliType,
-                            dir: workspace,
-                            cliArgs: cliCmdArgs.length > 0 ? cliCmdArgs : undefined,
-                            env: Object.keys(cliCmdEnv).length > 0 ? cliCmdEnv : undefined,
-                            settings: { meshCoordinatorFor: meshId },
+    /**
+     * Daemon-level command execution (IDE start/stop/restart, CLI, detect, logs).
+     * Returns null if not handled at this level → caller delegates to CommandHandler.
+     */
+    private async executeDaemonCommand(cmd: string, args: any): Promise<CommandRouterResult | null> {
+        // [Z] Remote mesh worker session-scoped command forward.
+        //
+        // Session-scoped commands issued from the dashboard (the controlbar Model/Mode
+        // selectors → invoke_provider_script, and modal approval → resolve_action, plus the
+        // direct set_mode/change_model/set_thought_level mutations) target a session by
+        // targetSessionId. agent_command (send_chat / clear_history / stop) is included for the
+        // same reason: a command naming a session must reach THAT session, never a different
+        // local one. When that session is a mesh worker hosted on a REMOTE daemon, this
+        // coordinator never holds its live instance, so the CommandHandler delegation would
+        // fail with "Live session not found" — or, for agent_command, findAdapter would have
+        // fuzzy-injected the message into the coordinator's own CLI session (TASKECHO). Forward
+        // to the owning worker daemon — the same daemon that already executes send_chat for that
+        // session — so the command acts on the real worker. _meshDirectDispatch prevents
+        // re-forwarding once the call lands on the owning daemon (it then handles the session
+        // locally). A locally-hosted worker (or any session this coordinator owns) resolves to
+        // undefined below and falls through to normal local handling — no regression.
+        if (MESH_FORWARDABLE_SESSION_COMMANDS.has(cmd) && this.deps.dispatchMeshCommand && !args?._meshDirectDispatch) {
+            const targetSessionId = readStringValue(args?.targetSessionId, args?.sessionId, args?.instanceId);
+            if (targetSessionId) {
+                const localInstance = this.deps.instanceManager?.getInstance(targetSessionId);
+                const localRegistry = this.deps.sessionRegistry?.get?.(targetSessionId);
+                if (!localInstance && !localRegistry) {
+                    // CANCEL-STOP-RELAY: pass the authoritative owning nodeId (when the caller
+                    // shipped one in meshContext, e.g. mesh_queue_cancel's assignedNodeId) as the
+                    // deterministic owner-resolution fallback. The session-id cache scan stays the
+                    // primary path; the hint only kicks in when that scan misses (worktree-clone
+                    // worker session not yet in / form-mismatched against the cached snapshot).
+                    const meshContext = readObjectRecord(args?.meshContext);
+                    const ownerNodeIdHint = readStringValue(meshContext.nodeId);
+                    const ownerDaemonId = this.resolveRemoteMeshSessionOwnerDaemonId(targetSessionId, ownerNodeIdHint);
+                    if (ownerDaemonId) {
+                        LOG.info('Mesh', `[Mesh] Forwarding session-scoped '${cmd}' for remote worker session ${targetSessionId.split('_')[0]} → daemon ${ownerDaemonId.slice(0, 12)}`);
+                        const forwarded = await this.deps.dispatchMeshCommand(ownerDaemonId, cmd, {
+                            ...(typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}),
+                            _meshDirectDispatch: true,
                         });
-
-                        if (!cliCmdLaunch?.success) {
-                            return { success: false, error: cliCmdLaunch?.error || 'Failed to launch CLI session' };
-                        }
-
-                        LOG.info('MeshCoordinator', `Launched ${cliType} coordinator (cli_command) for mesh ${meshId}`);
-                        try {
-                            const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
-                            appendLedgerEntry(meshId, {
-                                kind: 'coordinator_started',
-                                sessionId: cliCmdLaunch.sessionId || cliCmdLaunch.id,
-                                providerType: cliType,
-                                payload: { workspace },
-                            });
-                        } catch { /* best-effort */ }
-
-                        return {
-                            success: true,
-                            meshId,
-                            cliType,
-                            workspace,
-                            sessionId: cliCmdLaunch.sessionId || cliCmdLaunch.id,
-                            mcpRegistered: true,
-                        };
-                    }
-
-                    const configFormat = coordinatorSetup.configFormat as MeshCoordinatorConfigFormat;
-                    if (configFormat !== 'claude_mcp_json' && configFormat !== 'hermes_config_yaml') {
-                        return {
-                            success: false,
-                            code: 'mesh_coordinator_unsupported',
-                            error: `Unsupported auto-import MCP config format: ${String(coordinatorSetup.configFormat)}`,
-                            meshId,
-                            cliType,
-                            workspace,
-                        };
-                    }
-
-                    // Build the coordinator prompt before mutating workspace config or launching.
-                    // Prompt generation failures are configuration/data-shape errors; fail closed so
-                    // broken mesh state is visible instead of silently launching with weaker rules.
-                    let systemPrompt = '';
-                    try {
-                        systemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType });
-                    } catch (error: any) {
-                        const message = error?.message || String(error);
-                        LOG.error('MeshCoordinator', `Failed to build coordinator prompt: ${message}`);
-                        return {
-                            success: false,
-                            code: 'mesh_coordinator_prompt_failed',
-                            error: `Failed to build Repo Mesh coordinator prompt: ${message}`,
-                            meshId,
-                            cliType,
-                            workspace,
-                        };
-                    }
-
-                    // 1. Write provider-declared MCP config for CLIs that auto-import it.
-                    const { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } = await import('fs');
-                    const { dirname } = await import('path');
-                    const mcpConfigPath = coordinatorSetup.configPath;
-                    const hermesManualFallback = cliType === 'hermes-cli' && configFormat === 'hermes_config_yaml'
-                        ? createHermesManualMeshCoordinatorSetup(meshId, workspace)
-                        : null;
-                    let hermesBaseConfig: { config: Record<string, any>; sourceHome: string; sourceConfigPath: string } | null = null;
-                    if (hermesManualFallback) {
-                        try {
-                            hermesBaseConfig = loadHermesCoordinatorBaseConfig(mcpConfigPath);
-                        } catch (error: any) {
-                            const message = `Failed to parse Hermes base config for automatic coordinator setup: ${error?.message || error}`;
-                            LOG.error('MeshCoordinator', message);
-                            return { success: false, code: 'mesh_coordinator_config_parse_failed', error: message, meshId, cliType, workspace };
-                        }
-                    }
-                    const returnManualFallback = (message: string) => ({
-                        success: false,
-                        code: 'mesh_coordinator_manual_mcp_setup_required',
-                        error: message,
-                        meshId,
-                        cliType,
-                        workspace,
-                        meshCoordinatorSetup: hermesManualFallback,
-                    });
-
-                    // Merge ADHDev mesh server into existing config.
-                    // Pass full mesh data as env var so the MCP server can bootstrap
-                    // without depending on meshes.json or a running daemon.
-                    const mcpServerEntry: Record<string, any> = {
-                        command: coordinatorSetup.mcpServer.command,
-                        args: coordinatorSetup.mcpServer.args,
-                    };
-                    if (args?.inlineMesh) {
-                        const modeArgIndex = coordinatorSetup.mcpServer.args.findIndex((value: string) => value === '--mode');
-                        const mcpTransport = modeArgIndex >= 0 ? coordinatorSetup.mcpServer.args[modeArgIndex + 1] : 'ipc';
-                        mcpServerEntry.env = {
-                            ADHDEV_INLINE_MESH: JSON.stringify(mesh),
-                            ADHDEV_MCP_TRANSPORT: mcpTransport === 'local' ? 'local' : 'ipc',
-                        };
-                    }
-
-                    try {
-                        mkdirSync(dirname(mcpConfigPath), { recursive: true });
-                    } catch (error: any) {
-                        const message = `Could not prepare MCP config path for automatic setup: ${error?.message || error}`;
-                        LOG.error('MeshCoordinator', message);
-                        if (hermesManualFallback) return returnManualFallback(message);
-                        return { success: false, code: 'mesh_coordinator_config_write_failed', error: message, meshId, cliType, workspace };
-                    }
-
-                    // Backup existing MCP config if present.
-                    const hadExistingMcpConfig = existsSync(mcpConfigPath);
-                    let existingMcpConfig: Record<string, any> = hermesBaseConfig?.config || {};
-                    if (hermesBaseConfig) {
-                        copyHermesCoordinatorCredentialFiles(hermesBaseConfig.sourceHome, dirname(mcpConfigPath));
-                    }
-                    if (hadExistingMcpConfig) {
-                        try {
-                            const parsedExistingMcpConfig = parseMeshCoordinatorMcpConfig(readFileSync(mcpConfigPath, 'utf-8'), configFormat);
-                            const existingCoordinatorConfig = hermesManualFallback
-                                ? stripHermesCoordinatorTempModelProviderOverrides(parsedExistingMcpConfig)
-                                : parsedExistingMcpConfig;
-                            existingMcpConfig = { ...existingMcpConfig, ...existingCoordinatorConfig };
-                            copyFileSync(mcpConfigPath, mcpConfigPath + '.backup');
-                        } catch (error: any) {
-                            LOG.error('MeshCoordinator', `Failed to parse existing MCP config ${mcpConfigPath}: ${error?.message || error}`);
-                            return {
-                                success: false,
-                                code: 'mesh_coordinator_config_parse_failed',
-                                error: `Failed to parse existing MCP config at ${mcpConfigPath}`,
-                            };
-                        }
-                    }
-
-                    const mcpServersKey = getMcpServersKey(configFormat);
-                    const existingServers = existingMcpConfig[mcpServersKey];
-                    const mcpConfig = {
-                        ...existingMcpConfig,
-                        [mcpServersKey]: {
-                            ...(existingServers && typeof existingServers === 'object' && !Array.isArray(existingServers) ? existingServers : {}),
-                            [coordinatorSetup.serverName]: mcpServerEntry,
-                        },
-                    };
-                    try {
-                        writeFileSync(mcpConfigPath, serializeMeshCoordinatorMcpConfig(mcpConfig, configFormat), 'utf-8');
-                    } catch (error: any) {
-                        const message = `Could not write MCP config for automatic setup: ${error?.message || error}`;
-                        LOG.error('MeshCoordinator', message);
-                        if (hermesManualFallback) return returnManualFallback(message);
-                        return { success: false, code: 'mesh_coordinator_config_write_failed', error: message, meshId, cliType, workspace };
+                        return (forwarded ?? { success: false, error: 'no response from remote worker daemon' }) as CommandRouterResult;
                     }
-                    LOG.info('MeshCoordinator', `Wrote ${mcpConfigPath} with ${coordinatorSetup.serverName} server`);
-
-                    const cliArgs: string[] = [];
-                    const launchEnv: Record<string, string> = {};
-                    if (configFormat === 'hermes_config_yaml') {
-                        launchEnv.HERMES_HOME = dirname(mcpConfigPath);
-                        launchEnv.HERMES_IGNORE_USER_CONFIG = '';
-                    }
-                    if (systemPrompt) {
-                        if (configFormat === 'hermes_config_yaml') {
-                            launchEnv.HERMES_EPHEMERAL_SYSTEM_PROMPT = systemPrompt;
-                        } else {
-                            cliArgs.push('--append-system-prompt', systemPrompt);
-                        }
-                    }
-                    if (cliType === 'claude-cli') {
-                        cliArgs.push('--mcp-config', coordinatorSetup.configPath);
-                    }
-
-                    // 3. Launch CLI session via existing cliManager.
-                    // Provider-specific prompt injection remains fail-closed: Claude gets
-                    // explicit CLI args, while Hermes reads HERMES_EPHEMERAL_SYSTEM_PROMPT.
-                    const launchResult: any = await this.deps.cliManager.handleCliCommand('launch_cli', {
-                        cliType,
-                        dir: workspace,
-                        cliArgs: cliArgs.length > 0 ? cliArgs : undefined,
-                        env: Object.keys(launchEnv).length > 0 ? launchEnv : undefined,
-                        settings: {
-                            meshCoordinatorFor: meshId
-                        }
-                    });
-
-                    if (!launchResult?.success) {
-                        return { success: false, error: launchResult?.error || 'Failed to launch CLI session' };
-                    }
-
-                    LOG.info('MeshCoordinator', `Launched ${cliType} coordinator for mesh ${meshId} in ${workspace}`);
-
-                    // Record coordinator launch in task ledger
-                    try {
-                        const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
-                        appendLedgerEntry(meshId, {
-                            kind: 'coordinator_started',
-                            sessionId: launchResult.sessionId || launchResult.id,
-                            providerType: cliType,
-                            payload: { workspace },
-                        });
-                    } catch { /* ledger append is best-effort */ }
-
-                    return {
-                        success: true,
-                        meshId,
-                        cliType,
-                        workspace,
-                        sessionId: launchResult.sessionId || launchResult.id,
-                        mcpConfigWritten: true,
-                    };
-                } catch (e: any) {
-                    LOG.error('MeshCoordinator', `Failed: ${e.message}`);
-                    return { success: false, error: e.message };
                 }
             }
+        }
 
-            case 'mesh_status': {
-                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                if (!meshId) return { success: false, error: 'meshId required' };
-                try {
-                    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
-                    const mesh = meshRecord?.mesh;
-                    if (!mesh) return { success: false, error: 'Mesh not found' };
-
-                    const { getMeshQueueStats, getQueue } = await import('../mesh/mesh-work-queue.js');
-                    const queue = getQueue(meshId);
-                    const queueSummary = getMeshQueueStats(meshId);
-
-                    const { readLedgerEntries, getLedgerSummary } = await import('../mesh/mesh-ledger.js');
-                    const ledgerEntries = readLedgerEntries(meshId, { tail: 20 });
-                    const ledgerSummary = getLedgerSummary(meshId);
-
-                    const nodeStatuses = [];
-                    for (const node of mesh.nodes || []) {
-                        const status: Record<string, unknown> = {
-                            nodeId: node.id || node.nodeId,
-                            machineLabel: node.machineLabel || node.id || node.nodeId,
-                            workspace: node.workspace,
-                            repoRoot: node.repoRoot,
-                            isLocalWorktree: node.isLocalWorktree,
-                            worktreeBranch: node.worktreeBranch,
-                            daemonId: node.daemonId,
-                            machineId: node.machineId,
-                            health: 'unknown',
-                            providers: node.providers || [],
-                            activeSessions: [],
-                        };
-                        if (node.workspace && typeof node.workspace === 'string') {
-                            if (!fs.existsSync(node.workspace as string) && applyCachedInlineMeshNodeStatus(status, node)) {
-                                nodeStatuses.push(status);
-                                continue;
-                            }
-                            try {
-                                const gitStatus = await getGitRepoStatus(node.workspace as string, { timeoutMs: 10_000 });
-                                status.git = gitStatus;
-                                if (gitStatus.isGitRepo) {
-                                    const dirty = (gitStatus.staged + gitStatus.modified + gitStatus.untracked + gitStatus.deleted + gitStatus.renamed) > 0;
-                                    status.health = gitStatus.branch ? (dirty ? 'dirty' : 'online') : 'degraded';
-                                } else {
-                                    status.health = 'degraded';
-                                    if (gitStatus.error && !status.error) status.error = gitStatus.error;
-                                }
-                            } catch {
-                                if (!applyCachedInlineMeshNodeStatus(status, node)) {
-                                    status.health = 'degraded';
-                                }
-                            }
-                        } else {
-                            applyCachedInlineMeshNodeStatus(status, node);
-                        }
-                        nodeStatuses.push(status);
-                    }
+        // RF-ROUTER LOW family: low-coupling commands (session-host control, spec
+        // provider-dev, refine/change-impact config) are handled by the registry
+        // before the switch. A hit returns the same CommandRouterResult the inlined
+        // case used to; a miss falls through to the switch unchanged.
+        const lowFamilyHandler = lowFamilyRegistry.get(cmd);
+        if (lowFamilyHandler) {
+            return await lowFamilyHandler({
+                deps: this.deps,
+                getMeshForCommand: this.getMeshForCommand.bind(this),
+            }, args);
+        }
 
-                    return {
-                        success: true,
-                        meshId: mesh.id,
-                        meshName: mesh.name,
-                        repoIdentity: mesh.repoIdentity,
-                        defaultBranch: mesh.defaultBranch,
-                        nodes: nodeStatuses,
-                        queue: { tasks: queue, summary: queueSummary },
-                        ledger: { entries: ledgerEntries, summary: ledgerSummary },
-                    };
-                } catch (e: any) {
-                    return { success: false, error: e.message };
-                }
-            }
+        // RF-ROUTER MED family: medium-coupling commands (CLI/ACP agent, IDE
+        // lifecycle, mesh CRUD, mesh queue, mesh host pairing, fast-forward /
+        // refine convergence) are handled by the registry after the LOW family and
+        // before the switch. Unlike LOW handlers, MED handlers need router-private
+        // collaborators, so the context carries bound methods + the inline-mesh /
+        // git-probe caches + the launchIde helper (which breaks the original
+        // launch_ide ↔ restart_* self-recursion). A hit returns the same
+        // CommandRouterResult the inlined case used to; a miss falls through.
+        const medFamilyHandler = medFamilyRegistry.get(cmd);
+        if (medFamilyHandler) {
+            return await medFamilyHandler(this.buildMedFamilyContext(), args);
+        }
 
-            default:
-                break;
+        // RF-ROUTER HIGH family: high-coupling commands (mesh coordinator-event
+        // relay + interactive prompt, mesh coordinator launch, mesh aggregate
+        // status + review inbox) are handled by the registry after the LOW and
+        // MED families and before the (now empty) switch. HIGH handlers reach the
+        // most router-owned state — the aggregate-status memory cache and the
+        // running-refine-job table — so the context carries those plus bound
+        // read/write helpers and the router's own `execute` (the
+        // get_mesh_review_inbox mesh_status re-entry). A hit returns the same
+        // CommandRouterResult the inlined case used to; a miss falls through to
+        // CommandHandler delegation.
+        const highFamilyHandler = highFamilyRegistry.get(cmd);
+        if (highFamilyHandler) {
+            return await highFamilyHandler(this.buildHighFamilyContext(), args);
         }
 
         return null; // Not handled at this level → delegate to CommandHandler
@@ -3022,7 +975,7 @@ export class DaemonCommandRouter {
 
         // 3. Kill OS process if requested
         if (killProcess) {
-            const running = isIdeRunning(ideType);
+            const running = await isIdeRunning(ideType);
             if (running) {
                 LOG.info('StopIDE', `Killing IDE process: ${ideType}`);
                 const killed = await killIdeProcess(ideType);