@adhdev/daemon-core 0.9.82-rc.20 → 0.9.82-rc.201

package/src/commands/router.ts

@@ -38,14 +38,38 @@ import { createInteractionId, getRecentDebugTrace, recordDebugTrace } from '../l
 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 { registerMeshCoordinator, getCoordinatorForSession } from '../mesh/coordinator-registry.js';
+import { handleMeshForwardEvent, drainPendingMeshCoordinatorEvents, getPendingMeshCoordinatorEvents, queuePendingMeshCoordinatorEvent } from '../mesh/mesh-events.js';
+import { buildMeshHostRequiredFailure, normalizeMeshDaemonRole, resolveMeshHostStatus } from '../mesh/mesh-host-ownership.js';
+import { fastForwardMeshNode } from '../mesh/mesh-fast-forward.js';
+import { buildPreviewFreshness } from '../mesh/preview-freshness.js';
+import { buildMeshAsyncRefineJobs } from '../mesh/mesh-refine-status.js';
+import {
+    MESH_REFINE_CONFIG_LOCATIONS,
+    MESH_REFINE_CONFIG_SCHEMA,
+    loadMeshRefineConfig,
+    resolveMeshRefineValidationPlan,
+    suggestMeshRefineConfig,
+    validateMeshRefineConfig,
+    type MeshRefineValidationCommandPlan,
+} from '../mesh/refine-config.js';
+import {
+    MESH_WORKTREE_BOOTSTRAP_CONFIG_LOCATIONS,
+    MESH_WORKTREE_BOOTSTRAP_CONFIG_SCHEMA,
+    loadMeshWorktreeBootstrapConfig,
+    runMeshWorktreeBootstrap,
+    type WorktreeBootstrapState,
+} from '../mesh/worktree-bootstrap-config.js';
 import { buildMachineInfo, buildStatusSnapshot } from '../status/snapshot.js';
 import { getSessionCompletionMarker } from '../status/snapshot.js';
 import { execNpmCommandSync, resolveCurrentGlobalInstallSurface, spawnDetachedDaemonUpgradeHelper } from './upgrade-helper.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 { homedir, hostname as osHostname } from 'os';
+import { basename as pathBasename, join as pathJoin, resolve as pathResolve } from 'path';
 import * as fs from 'fs';
+import { execFileSync } from 'node:child_process';
+import { normalizeInteractivePromptResponse } from '../providers/types/interactive-prompt.js';
 
 type ReleaseChannel = 'stable' | 'preview';
 const CHANNEL_NPM_TAG: Record<ReleaseChannel, 'latest' | 'next'> = { stable: 'latest', preview: 'next' };
@@ -114,14 +138,95 @@ function readBooleanValue(...values: unknown[]): boolean | undefined {
     return undefined;
 }
 
-function readGitSubmodules(value: unknown): GitSubmoduleStatus[] | undefined {
+function summarizeRepoMeshDebugGit(git: unknown): Record<string, unknown> | null {
+    const record = readObjectRecord(git);
+    if (!Object.keys(record).length) return null;
+    const submodules = Array.isArray(record.submodules)
+        ? record.submodules.map((entry: any) => ({
+            path: readStringValue(entry?.path) ?? null,
+            commit: readStringValue(entry?.commit)?.slice(0, 12) ?? null,
+            dirty: readBooleanValue(entry?.dirty) ?? false,
+            outOfSync: readBooleanValue(entry?.outOfSync, entry?.out_of_sync) ?? false,
+        }))
+        : [];
+    return {
+        isGitRepo: readBooleanValue(record.isGitRepo),
+        workspace: readStringValue(record.workspace) ?? null,
+        repoRoot: readStringValue(record.repoRoot, record.repo_root) ?? null,
+        branch: readStringValue(record.branch) ?? null,
+        upstream: readStringValue(record.upstream) ?? null,
+        upstreamStatus: readStringValue(record.upstreamStatus, record.upstream_status) ?? null,
+        headCommit: readStringValue(record.headCommit, record.head_commit)?.slice(0, 12) ?? null,
+        ahead: readNumberValue(record.ahead) ?? null,
+        behind: readNumberValue(record.behind) ?? null,
+        dirtyCounts: {
+            staged: readNumberValue(record.staged) ?? 0,
+            modified: readNumberValue(record.modified) ?? 0,
+            untracked: readNumberValue(record.untracked) ?? 0,
+            deleted: readNumberValue(record.deleted) ?? 0,
+            renamed: readNumberValue(record.renamed) ?? 0,
+        },
+        lastCheckedAt: readNumberValue(record.lastCheckedAt, record.last_checked_at) ?? null,
+        submoduleCount: submodules.length,
+        submodules,
+    };
+}
+
+function summarizeRepoMeshStatusDebug(status: any): Record<string, unknown> {
+    const nodes = Array.isArray(status?.nodes) ? status.nodes : [];
+    return {
+        success: status?.success,
+        meshId: readStringValue(status?.meshId, status?.mesh_id) ?? null,
+        refreshedAt: readStringValue(status?.refreshedAt, status?.refreshed_at) ?? null,
+        sourceOfTruth: status?.sourceOfTruth ?? null,
+        branchConvergenceSummary: status?.branchConvergenceSummary ?? status?.branch_convergence_summary ?? null,
+        nodeCount: nodes.length,
+        nodes: nodes.map((node: any) => ({
+            nodeId: readStringValue(node?.nodeId, node?.id) ?? null,
+            daemonId: readStringValue(node?.daemonId, node?.daemon_id) ?? null,
+            workspace: readStringValue(node?.workspace, node?.git?.workspace) ?? null,
+            health: readStringValue(node?.health) ?? null,
+            machineStatus: readStringValue(node?.machineStatus, node?.machine_status) ?? null,
+            connection: node?.connection && typeof node.connection === 'object' ? {
+                state: readStringValue(node.connection.state) ?? null,
+                transport: readStringValue(node.connection.transport) ?? null,
+                source: readStringValue(node.connection.source) ?? null,
+                reported: readBooleanValue(node.connection.reported) ?? null,
+            } : null,
+            gitProbePending: node?.gitProbePending === true,
+            launchReady: node?.launchReady === true,
+            git: summarizeRepoMeshDebugGit(node?.git),
+            branchConvergence: node?.branchConvergence ?? node?.branch_convergence ?? null,
+        })),
+    };
+}
+
+function logRepoMeshStatusDebug(event: string, fields: Record<string, unknown>): void {
+    try {
+        LOG.info('MeshStatusDebug', `[RepoMeshStatusDebug] ${JSON.stringify({ event, ...fields })}`);
+    } catch {
+        LOG.info('MeshStatusDebug', `[RepoMeshStatusDebug] ${event}`);
+    }
+}
+
+function joinRepoPath(root: string | undefined, relativePath: string | undefined): string | undefined {
+    const normalizedRoot = typeof root === 'string' ? root.trim().replace(/[\\/]+$/, '') : '';
+    const normalizedPath = typeof relativePath === 'string' ? relativePath.trim() : '';
+    if (!normalizedPath) return undefined;
+    if (/^(?:[A-Za-z]:[\\/]|\/)/.test(normalizedPath)) return normalizedPath;
+    if (!normalizedRoot) return undefined;
+    return `${normalizedRoot}/${normalizedPath.replace(/^[\\/]+/, '')}`;
+}
+
+function readGitSubmodules(value: unknown, parentRepoRoot?: string): 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);
+            const repoPath = readStringValue(submodule.repoPath, submodule.repo_root)
+                ?? joinRepoPath(parentRepoRoot, path);
             if (!path || !commit || !repoPath) return null;
             return {
                 path,
@@ -137,60 +242,146 @@ function readGitSubmodules(value: unknown): GitSubmoduleStatus[] | undefined {
     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 } : {}),
-            };
-        }
+function buildMeshNodeDisplayLabel(node: Record<string, unknown>, nodeId: string, providerPriority: string[]): string {
+    const explicit = readStringValue(node.machineLabel, node.machine_label, node.machineNickname, node.machine_nickname, node.alias);
+    if (explicit) return explicit;
+    const workspace = readStringValue(node.workspace, node.repoRoot, node.repo_root);
+    const workspaceName = workspace ? pathBasename(workspace) : undefined;
+    const host = readStringValue(node.machineName, node.machine_name, node.hostname, node.host, node.daemonId, node.daemon_id, node.machineId, node.machine_id);
+    const provider = providerPriority[0] || (Array.isArray(node.providers) ? readStringValue(...node.providers) : undefined);
+    const parts = [workspaceName, host, provider].filter(Boolean);
+    if (parts.length > 0) return parts.join(' · ');
+    return nodeId || 'unidentified mesh node';
+}
+
+function normalizeMeshHostname(value: unknown): string | undefined {
+    const hostname = readStringValue(value);
+    if (!hostname) return undefined;
+    return hostname.toLowerCase().replace(/\.$/, '');
+}
+
+function readMeshNodeMachineId(node: Record<string, unknown>): string | undefined {
+    return readStringValue(
+        node.machineId,
+        node.machine_id,
+        readObjectRecord(node.machine)?.id,
+        readObjectRecord(node.machine)?.machineId,
+        readObjectRecord(node.lastProbe)?.machineId,
+        readObjectRecord(node.last_probe)?.machine_id,
+        readObjectRecord(readObjectRecord(node.lastProbe)?.machine)?.id,
+        readObjectRecord(readObjectRecord(node.lastProbe)?.machine)?.machineId,
+        readObjectRecord(readObjectRecord(node.last_probe)?.machine)?.id,
+        readObjectRecord(readObjectRecord(node.last_probe)?.machine)?.machine_id,
+    );
+}
+
+function readMeshNodeDaemonId(node: Record<string, unknown>): string | undefined {
+    return readStringValue(
+        node.daemonId,
+        node.daemon_id,
+        readObjectRecord(node.machine)?.daemonId,
+        readObjectRecord(node.machine)?.daemon_id,
+        readObjectRecord(node.lastProbe)?.daemonId,
+        readObjectRecord(node.last_probe)?.daemon_id,
+        readObjectRecord(readObjectRecord(node.lastProbe)?.machine)?.daemonId,
+        readObjectRecord(readObjectRecord(node.lastProbe)?.machine)?.daemon_id,
+        readObjectRecord(readObjectRecord(node.last_probe)?.machine)?.daemonId,
+        readObjectRecord(readObjectRecord(node.last_probe)?.machine)?.daemon_id,
+    );
+}
+
+function readMeshNodeHostname(node: Record<string, unknown>): string | undefined {
+    return readStringValue(
+        node.hostname,
+        node.host,
+        node.machineHostname,
+        node.machine_hostname,
+        readObjectRecord(node.machine)?.hostname,
+        readObjectRecord(node.machine)?.host,
+        readObjectRecord(node.lastProbe)?.hostname,
+        readObjectRecord(node.last_probe)?.hostname,
+        readObjectRecord(readObjectRecord(node.lastProbe)?.machine)?.hostname,
+        readObjectRecord(readObjectRecord(node.last_probe)?.machine)?.hostname,
+    );
+}
+
+function readMeshNodeDisplayMachineName(node: Record<string, unknown>): string | undefined {
+    return readStringValue(
+        node.machineName,
+        node.machine_name,
+        node.machineLabel,
+        node.machine_label,
+        node.machineNickname,
+        node.machine_nickname,
+        node.alias,
+        readObjectRecord(node.machine)?.name,
+        readObjectRecord(node.machine)?.displayName,
+        readObjectRecord(node.machine)?.display_name,
+        readObjectRecord(node.lastProbe)?.machineName,
+        readObjectRecord(node.last_probe)?.machine_name,
+        readObjectRecord(readObjectRecord(node.lastProbe)?.machine)?.name,
+        readObjectRecord(readObjectRecord(node.last_probe)?.machine)?.name,
+        readMeshNodeHostname(node),
+    );
+}
+
+function compactMeshIdentityEvidence(value: string | undefined): string | undefined {
+    if (!value) return undefined;
+    return value.length > 24 ? `${value.slice(0, 12)}…${value.slice(-8)}` : value;
+}
+
+function buildMeshNodeMachineIdentity(node: Record<string, unknown>, opts: {
+    localMachineId?: string;
+    localDaemonId?: string;
+    coordinatorHostname?: string;
+    isSelfNode?: boolean;
+}): Record<string, unknown> {
+    const machineId = readMeshNodeMachineId(node);
+    const daemonId = readMeshNodeDaemonId(node);
+    const hostname = readMeshNodeHostname(node);
+    const machineName = readMeshNodeDisplayMachineName(node);
+    const coordinatorHostname = readStringValue(opts.coordinatorHostname);
+    const machineIdMatches = Boolean(opts.localMachineId && machineId && opts.localMachineId === machineId);
+    const daemonIdMatches = Boolean(opts.localDaemonId && daemonId && opts.localDaemonId === daemonId);
+    const hostnameMatches = Boolean(
+        normalizeMeshHostname(hostname)
+        && normalizeMeshHostname(coordinatorHostname)
+        && normalizeMeshHostname(hostname) === normalizeMeshHostname(coordinatorHostname),
+    );
+    const sameMachine = opts.isSelfNode === true || machineIdMatches || daemonIdMatches || hostnameMatches;
+    const evidence: string[] = [];
+    for (const [label, value] of [['machineName', machineName], ['hostname', hostname], ['machineId', machineId], ['daemonId', daemonId]] as const) {
+        const compact = compactMeshIdentityEvidence(value);
+        if (compact) evidence.push(`${label}:${compact}`);
     }
+    const locality = sameMachine ? 'same_machine' : (evidence.length > 0 ? 'remote_known' : 'remote_or_unknown');
+    const localityReason = sameMachine
+        ? (machineIdMatches ? 'matched coordinator machine id'
+            : daemonIdMatches ? 'matched coordinator daemon id'
+                : hostnameMatches ? 'matched coordinator hostname'
+                    : 'selected coordinator node')
+        : evidence.length > 0
+            ? `known remote/other machine identity; no local coordinator match (${evidence.join(', ')})`
+            : 'no useful machine identity evidence available';
+    return {
+        daemonId,
+        machineId,
+        hostname,
+        machineName,
+        displayName: machineName || hostname || daemonId || machineId,
+        coordinatorHostname,
+        sameMachine,
+        locality,
+        localityReason,
+        identityEvidence: evidence,
+    };
+}
 
-    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
-                    : {};
+function normalizeInlineMeshGitStatus(
+    status: Record<string, unknown>,
+    node: any,
+    options?: { lastCheckedAt?: number },
+): Record<string, unknown> | undefined {
     const isGitRepo = readBooleanValue(status.isGitRepo);
     if (!Object.keys(status).length || isGitRepo === undefined) return undefined;
     const conflictFiles = Array.isArray(status.conflictFiles)
@@ -198,15 +389,20 @@ function buildCachedInlineMeshGitStatus(node: any): Record<string, unknown> | un
         : [];
     const conflictCount = readNumberValue(status.conflicts) ?? conflictFiles.length;
     const hasConflicts = readBooleanValue(status.hasConflicts) ?? conflictCount > 0;
-    const submodules = readGitSubmodules(status.submodules);
+    const repoRoot = readStringValue(status.repoRoot, status.repo_root, node?.repoRoot, node?.repo_root, status.workspace, node?.workspace) || undefined;
+    const submodules = readGitSubmodules(status.submodules, repoRoot);
     return {
         workspace: readStringValue(status.workspace, node?.workspace) || '',
-        repoRoot: readStringValue(status.repoRoot, node?.repoRoot, node?.workspace) || null,
+        repoRoot: repoRoot ?? null,
         isGitRepo,
         branch: readStringValue(status.branch) ?? null,
         headCommit: readStringValue(status.headCommit) ?? null,
         headMessage: readStringValue(status.headMessage) ?? null,
         upstream: readStringValue(status.upstream) ?? null,
+        upstreamStatus: readStringValue(status.upstreamStatus, status.upstream_status)
+            ?? (readStringValue(status.upstream) ? 'unchecked' : 'no_upstream'),
+        upstreamFetchedAt: readNumberValue(status.upstreamFetchedAt, status.upstream_fetched_at),
+        upstreamFetchError: readStringValue(status.upstreamFetchError, status.upstream_fetch_error),
         ahead: readNumberValue(status.ahead) ?? 0,
         behind: readNumberValue(status.behind) ?? 0,
         staged: readNumberValue(status.staged) ?? 0,
@@ -217,14 +413,247 @@ function buildCachedInlineMeshGitStatus(node: any): Record<string, unknown> | un
         hasConflicts,
         conflictFiles,
         stashCount: readNumberValue(status.stashCount) ?? 0,
-        lastCheckedAt: Date.now(),
+        lastCheckedAt: options?.lastCheckedAt ?? readNumberValue(status.lastCheckedAt) ?? Date.now(),
         ...(submodules ? { submodules } : {}),
     };
 }
 
+function scoreInlineMeshGitStatus(git: Record<string, unknown> | undefined): number {
+    if (!git) return Number.NEGATIVE_INFINITY;
+    let score = 0;
+    if (readBooleanValue(git.isGitRepo) === true) score += 50;
+    if (readBooleanValue(git.isGitRepo) === false) score -= 10;
+    if (readStringValue(git.branch)) score += 20;
+    if (readStringValue(git.headCommit)) score += 20;
+    if (readStringValue(git.upstream)) score += 10;
+    if (readStringValue(git.upstreamStatus)) score += 5;
+    if (readNumberValue(git.ahead) !== undefined) score += 2;
+    if (readNumberValue(git.behind) !== undefined) score += 2;
+    if (Array.isArray(git.submodules) && git.submodules.length > 0) score += 4 + git.submodules.length;
+    if (readStringValue(git.error)) score -= 20;
+    return score;
+}
+
+function buildInlineMeshTransitGitStatus(node: any): Record<string, unknown> | undefined {
+    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 candidates = [directStatus, nestedStatus, probeDirectStatus, probeNestedStatus];
+    let best: { git: Record<string, unknown>; score: number } | null = null;
+    for (const status of candidates) {
+        const normalized = normalizeInlineMeshGitStatus(status, node, { lastCheckedAt: Date.now() });
+        if (!normalized) continue;
+        const score = scoreInlineMeshGitStatus(normalized);
+        if (!best || score > best.score) best = { git: normalized, score };
+    }
+    return best?.git;
+}
+
+function shouldRefreshStalePendingAggregate(snapshot: any, options?: { requireDirectPeerTruth?: boolean }): boolean {
+    if (options?.requireDirectPeerTruth !== true || !Array.isArray(snapshot?.nodes)) return false;
+    return snapshot.nodes.some((node: any) => {
+        if (node?.gitProbePending !== true) return false;
+        const git = readObjectRecord(node?.git);
+        return !readBooleanValue(git.isGitRepo) && !readStringValue(git.branch, git.headCommit, git.upstream);
+    });
+}
+
+function buildLivePeerGitConnection(connection: Record<string, unknown>, timestamp = new Date().toISOString()): Record<string, unknown> {
+    const source = readStringValue(connection.source);
+    const transport = readStringValue(connection.transport);
+    return {
+        ...connection,
+        perspective: readStringValue(connection.perspective) ?? 'selected_coordinator',
+        source: source && source !== 'not_reported' ? source : 'mesh_peer_status',
+        state: 'connected',
+        transport: transport && transport !== 'unknown' ? transport : 'direct',
+        reported: true,
+        reason: 'Live peer git snapshot reported by the selected coordinator.',
+        lastStateChangeAt: readStringValue(connection.lastStateChangeAt) ?? timestamp,
+    };
+}
+
+function recordInlineMeshDirectGitTruth(
+    node: any,
+    git: Record<string, unknown>,
+    source: 'selected_coordinator_local_git' | 'selected_coordinator_mesh_p2p_git',
+): void {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) return;
+    const checkedAt = readNumberValue(git.lastCheckedAt) ?? Date.now();
+    const updatedAt = new Date(checkedAt).toISOString();
+    const nextGit: Record<string, unknown> = {
+        ...git,
+        lastCheckedAt: checkedAt,
+    };
+    node.lastGit = {
+        source,
+        checkedAt,
+        status: nextGit,
+    };
+    node.last_git = node.lastGit;
+    node.machineStatus = 'online';
+    node.updatedAt = updatedAt;
+    node.lastSeenAt = updatedAt;
+    const repoRoot = readStringValue(nextGit.repoRoot);
+    if (repoRoot && !readStringValue(node.repoRoot)) node.repoRoot = repoRoot;
+}
+
+function buildCachedInlineMeshGitStatus(node: any): Record<string, unknown> | undefined {
+    const liveGit = buildInlineMeshTransitGitStatus(node);
+    if (liveGit) return liveGit;
+
+    const cachedStatus = readObjectRecord(node?.cachedStatus);
+    const cachedGit = readObjectRecord(cachedStatus.git);
+    if (!Object.keys(cachedGit).length) return undefined;
+    return normalizeInlineMeshGitStatus(cachedGit, node);
+}
+
+function shouldDiscardCachedInlineMeshStatus(node: any): boolean {
+    const cachedStatus = readObjectRecord(node?.cachedStatus);
+    if (!Object.keys(cachedStatus).length) return false;
+    const cachedGit = readObjectRecord(cachedStatus.git);
+    const workspaceError = readStringValue(cachedStatus.error, node?.error);
+    if (workspaceError && /workspace must be an existing directory/i.test(workspaceError)) return true;
+    const isGitRepo = readBooleanValue(cachedGit.isGitRepo);
+    const branch = readStringValue(cachedGit.branch);
+    const headCommit = readStringValue(cachedGit.headCommit);
+    return isGitRepo === false && !branch && !headCommit;
+}
+
+function stripInlineMeshTransientNodeState(node: any): any {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) return node;
+    const {
+        cachedStatus,
+        lastGit: _lastGit,
+        last_git: _lastGitLegacy,
+        lastProbe: _lastProbe,
+        last_probe: _lastProbeLegacy,
+        error: _error,
+        health: _health,
+        machineStatus: _machineStatus,
+        lastSeenAt: _lastSeenAt,
+        last_seen_at: _lastSeenAtLegacy,
+        updatedAt: _updatedAt,
+        updated_at: _updatedAtLegacy,
+        activeSession: _activeSession,
+        active_session: _activeSessionLegacy,
+        activeSessionId: _activeSessionId,
+        active_session_id: _activeSessionIdLegacy,
+        sessionId: _sessionId,
+        session_id: _sessionIdLegacy,
+        providerType: _providerType,
+        provider_type: _providerTypeLegacy,
+        ...rest
+    } = node as Record<string, unknown>;
+    if (cachedStatus && !shouldDiscardCachedInlineMeshStatus(node)) {
+        return { ...rest, cachedStatus };
+    }
+    return rest;
+}
+
+function hasInlineMeshTransientNodeState(node: any): boolean {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) return false;
+    return 'cachedStatus' in node
+        || 'lastGit' in node
+        || 'last_git' in node
+        || 'lastProbe' in node
+        || 'last_probe' in node
+        || 'error' in node
+        || 'health' in node
+        || 'machineStatus' in node
+        || 'lastSeenAt' in node
+        || 'last_seen_at' in node
+        || 'updatedAt' in node
+        || 'updated_at' in node
+        || 'activeSession' in node
+        || 'active_session' in node
+        || 'activeSessionId' in node
+        || 'active_session_id' in node
+        || 'sessionId' in node
+        || 'session_id' in node
+        || 'providerType' in node
+        || 'provider_type' in node;
+}
+
+function inlineMeshCarriesTransientNodeTruth(inlineMesh: any): boolean {
+    if (!inlineMesh || typeof inlineMesh !== 'object' || Array.isArray(inlineMesh)) return false;
+    if (!Array.isArray(inlineMesh.nodes) || inlineMesh.nodes.length === 0) return false;
+    return inlineMesh.nodes.some((node: any) => hasInlineMeshTransientNodeState(node));
+}
+
+function readInlineMeshNodeId(node: any): string {
+    return readStringValue(node?.id, node?.nodeId) || '';
+}
+
+function sanitizeInlineMesh(inlineMesh: any): any {
+    if (!inlineMesh || typeof inlineMesh !== 'object' || Array.isArray(inlineMesh)) return inlineMesh;
+    if (!Array.isArray(inlineMesh.nodes)) return inlineMesh;
+    let changed = false;
+    const nodes = inlineMesh.nodes.map((node: any) => {
+        if (!hasInlineMeshTransientNodeState(node)) return node;
+        changed = true;
+        return stripInlineMeshTransientNodeState(node);
+    });
+    if (!changed) return inlineMesh;
+    return {
+        ...inlineMesh,
+        nodes,
+    };
+}
+
+function reconcileInlineMeshCache(cached: any, incoming: any): any {
+    if (!cached || typeof cached !== 'object' || Array.isArray(cached)) return incoming;
+    if (!incoming || typeof incoming !== 'object' || Array.isArray(incoming)) return cached;
+    const cachedNodes = Array.isArray(cached.nodes) ? cached.nodes : [];
+    const incomingNodes = Array.isArray(incoming.nodes) ? incoming.nodes : [];
+    if (!cachedNodes.length || !incomingNodes.length) return { ...cached, ...incoming };
+
+    const cachedUpdatedAt = Date.parse(readStringValue(cached.updatedAt, cached.updated_at) || '');
+    const incomingUpdatedAt = Date.parse(readStringValue(incoming.updatedAt, incoming.updated_at) || '');
+    const preserveCachedMembership = Number.isFinite(cachedUpdatedAt)
+        && (!Number.isFinite(incomingUpdatedAt) || cachedUpdatedAt > incomingUpdatedAt);
+
+    const cachedById = new Map<string, any>();
+    for (const node of cachedNodes) {
+        const nodeId = readInlineMeshNodeId(node);
+        if (nodeId) cachedById.set(nodeId, node);
+    }
+
+    const nodes = incomingNodes.map((incomingNode: any) => {
+        const nodeId = readInlineMeshNodeId(incomingNode);
+        const cachedNode = nodeId ? cachedById.get(nodeId) : undefined;
+        if (!cachedNode && preserveCachedMembership) return null;
+        if (!cachedNode) return incomingNode;
+        if (hasInlineMeshTransientNodeState(incomingNode)) {
+            return { ...cachedNode, ...incomingNode };
+        }
+        return { ...stripInlineMeshTransientNodeState(cachedNode), ...incomingNode };
+    }).filter(Boolean);
+
+    return {
+        ...cached,
+        ...incoming,
+        nodes,
+    };
+}
+
 function hasGitWorktreeChanges(git: Record<string, unknown> | null | undefined): boolean {
-    if (!git) return false;
-    return Number(git.staged || 0) + Number(git.modified || 0) + Number(git.untracked || 0) + Number(git.deleted || 0) + Number(git.renamed || 0) > 0;
+    return countGitWorktreeChanges(git) > 0;
+}
+
+function countGitWorktreeChanges(git: Record<string, unknown> | null | undefined): number {
+    if (!git) return 0;
+    return Number(git.staged || 0)
+        + Number(git.modified || 0)
+        + Number(git.untracked || 0)
+        + Number(git.deleted || 0)
+        + Number(git.renamed || 0);
 }
 
 function getGitSubmoduleDriftState(git: Record<string, unknown> | null | undefined): { dirty: boolean; outOfSync: boolean } {
@@ -249,6 +678,167 @@ function deriveMeshNodeHealthFromGit(git: Record<string, unknown> | null | undef
     return 'online';
 }
 
+function readMeshNodeLabel(status: Record<string, unknown>, node: any): string {
+    return readStringValue(status.nodeId, node?.id, node?.nodeId) ?? 'unknown';
+}
+
+function buildInlineMeshBranchConvergence(args: {
+    mesh: any;
+    node: any;
+    status: Record<string, unknown>;
+}): Record<string, unknown> {
+    const git = readObjectRecord(args.status.git);
+    const nodeLabel = readMeshNodeLabel(args.status, args.node);
+    const defaultBranch = readStringValue(args.mesh?.defaultBranch) ?? 'main';
+    const branch = readStringValue(git.branch, args.node?.worktreeBranch) ?? null;
+    const upstream = readStringValue(git.upstream) ?? null;
+    const upstreamStatus = readStringValue(git.upstreamStatus, git.upstream_status)
+        ?? (upstream ? 'unchecked' : 'no_upstream');
+    const ahead = readNumberValue(git.ahead) ?? 0;
+    const behind = readNumberValue(git.behind) ?? 0;
+    const uncommittedChanges = countGitWorktreeChanges(git);
+    const hasConflicts = readBooleanValue(git.hasConflicts)
+        ?? (Array.isArray(git.conflictFiles) && git.conflictFiles.length > 0);
+    const base = {
+        defaultBranch,
+        branch,
+        upstream,
+        upstreamStatus,
+        ahead,
+        behind,
+        isWorktree: args.node?.isLocalWorktree === true || args.status.isLocalWorktree === true,
+        isDefaultBranch: branch === defaultBranch,
+    };
+
+    if (readBooleanValue(git.isGitRepo) !== true) {
+        return {
+            ...base,
+            status: 'blocked_review',
+            needsConvergence: true,
+            reason: 'git_status_unavailable',
+            nextStep: `Resolve git status for node '${nodeLabel}' before marking the task complete.`,
+        };
+    }
+
+    if (!branch) {
+        return {
+            ...base,
+            status: 'blocked_review',
+            needsConvergence: true,
+            reason: 'branch_unknown',
+            nextStep: `Inspect node '${nodeLabel}' git branch before deciding whether it is merged to ${defaultBranch}.`,
+        };
+    }
+
+    if (hasConflicts || uncommittedChanges > 0) {
+        return {
+            ...base,
+            status: 'not_mergeable',
+            needsConvergence: true,
+            reason: hasConflicts ? 'conflicts_present' : 'dirty_workspace',
+            nextStep: `Commit, checkpoint, or resolve node '${nodeLabel}' before any main convergence step.`,
+        };
+    }
+
+    if (branch === defaultBranch) {
+        if (upstream && upstreamStatus !== 'fresh') {
+            return {
+                ...base,
+                status: 'blocked_review',
+                needsConvergence: true,
+                reason: 'default_branch_upstream_unverified',
+                nextStep: `Refresh ${defaultBranch}'s upstream refs or resolve the fetch failure before declaring convergence complete for node '${nodeLabel}'.`,
+            };
+        }
+        if (ahead > 0 || behind > 0) {
+            return {
+                ...base,
+                status: 'blocked_review',
+                needsConvergence: true,
+                reason: 'default_branch_not_even_with_upstream',
+                nextStep: `Bring ${defaultBranch} even with its upstream before declaring convergence complete.`,
+            };
+        }
+        return {
+            ...base,
+            status: 'merged_to_main',
+            needsConvergence: false,
+            reason: 'clean_default_branch',
+            nextStep: null,
+        };
+    }
+
+    if (args.node?.isLocalWorktree === true || args.status.isLocalWorktree === true) {
+        return {
+            ...base,
+            status: 'cleanup_candidate',
+            needsConvergence: true,
+            reason: 'clean_non_default_worktree_branch',
+            nextStep: `Run mesh_refine_node(node_id: "${nodeLabel}") or explicitly classify this worktree as blocked_review/not_mergeable before ending the task.`,
+        };
+    }
+
+    if (upstream && upstreamStatus !== 'fresh') {
+        return {
+            ...base,
+            status: 'blocked_review',
+            needsConvergence: true,
+            reason: 'feature_branch_upstream_unverified',
+            nextStep: `Refresh branch '${branch}' upstream refs or resolve the fetch failure before deciding whether it is ready to merge into ${defaultBranch}.`,
+        };
+    }
+
+    if (!upstream || ahead > 0 || behind > 0) {
+        return {
+            ...base,
+            status: 'blocked_review',
+            needsConvergence: true,
+            reason: !upstream ? 'feature_branch_missing_upstream' : 'feature_branch_not_even_with_upstream',
+            nextStep: `Push or reconcile branch '${branch}', then merge it into ${defaultBranch} or mark it not_mergeable with a reason.`,
+        };
+    }
+
+    return {
+        ...base,
+        status: 'pushed_feature_branch_needs_merge',
+        needsConvergence: true,
+        reason: 'clean_non_default_branch',
+        nextStep: `Review and merge branch '${branch}' into ${defaultBranch}; do not report the task as fully complete while it remains off main.`,
+    };
+}
+
+function applyInlineMeshBranchConvergence(mesh: any, node: any, status: Record<string, unknown>): void {
+    const git = readObjectRecord(status.git);
+    if (Object.keys(git).length === 0 && !status.gitProbePending) return;
+    const uncommittedChanges = countGitWorktreeChanges(git);
+    status.isDirty = uncommittedChanges > 0;
+    status.uncommittedChanges = uncommittedChanges;
+    status.branchConvergence = buildInlineMeshBranchConvergence({ mesh, node, status });
+}
+
+function summarizeInlineMeshBranchConvergence(nodes: Array<Record<string, unknown>>): Record<string, unknown> {
+    const followUps = nodes
+        .filter(node => readObjectRecord(node.branchConvergence).needsConvergence === true)
+        .map(node => {
+            const convergence = readObjectRecord(node.branchConvergence);
+            return {
+                nodeId: node.nodeId,
+                workspace: node.workspace,
+                branch: convergence.branch,
+                status: convergence.status,
+                reason: convergence.reason,
+                nextStep: convergence.nextStep,
+            };
+        });
+
+    return {
+        needsFollowUp: followUps.length > 0,
+        unresolvedCount: followUps.length,
+        requiredFinalStates: ['merged_to_main', 'pushed_feature_branch_needs_merge', 'blocked_review', 'cleanup_candidate', 'not_mergeable'],
+        followUps,
+    };
+}
+
 function readCachedInlineMeshActiveSessions(node: any): string[] {
     const cachedStatus = readObjectRecord(node?.cachedStatus);
     const activeSession = readObjectRecord(cachedStatus.activeSession);
@@ -259,7 +849,7 @@ function readCachedInlineMeshActiveSessions(node: any): string[] {
     return sessionId ? [sessionId] : [];
 }
 
-function readCachedInlineMeshActiveSessionDetails(node: any): Array<Record<string, unknown>> {
+export function readCachedInlineMeshActiveSessionDetails(node: any): Array<Record<string, unknown>> {
     const cachedStatus = readObjectRecord(node?.cachedStatus);
     const activeSession = readObjectRecord(cachedStatus.activeSession);
     const fallbackSession = Object.keys(activeSession).length
@@ -287,9 +877,14 @@ function readCachedInlineMeshActiveSessionDetails(node: any): Array<Record<strin
             node?.provider_type,
         ),
         state: readStringValue(fallbackSession.status, fallbackSession.state, fallbackSession.lifecycle),
+        chatStatus: readStringValue(fallbackSession.chatStatus, fallbackSession.chat_status),
         lifecycle: readStringValue(fallbackSession.lifecycle),
         title: readStringValue(fallbackSession.title, fallbackSession.displayName, fallbackSession.display_name) ?? null,
         workspace: readStringValue(fallbackSession.workspace, node?.workspace) ?? null,
+        role: readStringValue(fallbackSession.role) ?? null,
+        isSelfCoordinator: fallbackSession.isSelfCoordinator === true || fallbackSession.is_self_coordinator === true,
+        createdAt: readStringValue(fallbackSession.createdAt, fallbackSession.created_at) ?? null,
+        startedAt: readStringValue(fallbackSession.startedAt, fallbackSession.started_at) ?? null,
         lastActivityAt: readStringValue(fallbackSession.lastActivityAt, fallbackSession.last_activity_at) ?? null,
         recoveryState: readStringValue(fallbackSession.recoveryState, fallbackSession.recovery_state) ?? null,
         isCached: true,
@@ -313,21 +908,217 @@ function toIsoTimestamp(value: unknown): string | null {
     return stringValue || null;
 }
 
+function synthesizeMeshNodeFreshnessFromConnection(status: Record<string, unknown>): void {
+    const connection = readObjectRecord(status.connection);
+    const connectionFreshAt = toIsoTimestamp(connection.lastCommandAt ?? connection.lastConnectedAt ?? connection.lastStateChangeAt);
+    const git = readObjectRecord(status.git);
+    const gitCheckedAt = toIsoTimestamp(git.lastCheckedAt);
+    if (!status.lastSeenAt && connectionFreshAt) status.lastSeenAt = connectionFreshAt;
+    if (!status.updatedAt && (gitCheckedAt || connectionFreshAt)) {
+        status.updatedAt = gitCheckedAt ?? connectionFreshAt;
+    }
+}
+
+function finalizeMeshNodeStatus(args: {
+    status: Record<string, unknown>;
+    node: any;
+    daemonId?: string;
+    isSelfNode: boolean;
+}): void {
+    const { status, node, daemonId, isSelfNode } = args;
+    if (!readStringValue(status.machineStatus)) {
+        const cachedStatus = readObjectRecord(node?.cachedStatus);
+        const machineStatus = readStringValue(cachedStatus.machineStatus, cachedStatus.machine_status, node?.machineStatus);
+        if (machineStatus) status.machineStatus = machineStatus;
+    }
+    synthesizeMeshNodeFreshnessFromConnection(status);
+    const bootstrap = readObjectRecord(node?.worktreeBootstrap);
+    if (node?.isLocalWorktree && readStringValue(bootstrap.status)) {
+        status.worktreeBootstrap = bootstrap;
+        if (bootstrap.status === 'failed' && bootstrap.required !== false) {
+            status.launchReady = false;
+            status.launchBlockedReason = 'worktree_bootstrap_failed';
+            status.launchBlockedMessage = readStringValue(bootstrap.error)
+                || 'Required worktree bootstrap failed; resolve it before launching an agent into this node.';
+            return;
+        }
+        if (bootstrap.status === 'running' && bootstrap.required !== false) {
+            status.launchReady = false;
+            status.launchBlockedReason = 'worktree_bootstrap_running';
+            status.launchBlockedMessage = 'Required worktree bootstrap is still running; wait for it to finish before launching an agent into this node.';
+            return;
+        }
+    }
+    const connectionState = readStringValue(readObjectRecord(status.connection).state);
+    status.launchReady = !!daemonId && (
+        readStringValue(status.machineStatus) === 'online'
+        || connectionState === 'connected'
+        || isSelfNode
+    );
+}
+
+async function probeRemoteMeshGitStatus(args: {
+    dispatchMeshCommand?: (daemonId: string, cmd: string, args: Record<string, unknown>) => Promise<unknown>;
+    daemonId: string;
+    workspace: string;
+    timeoutMs: number;
+}): Promise<Record<string, unknown> | null> {
+    if (!args.dispatchMeshCommand) return null;
+    const remoteResult = await Promise.race([
+        args.dispatchMeshCommand(args.daemonId, 'git_status', { workspace: args.workspace, refreshUpstream: true }),
+        new Promise<never>((_, reject) => setTimeout(() => reject(new Error('timeout')), args.timeoutMs)),
+    ]) as any;
+    const remoteGit = remoteResult?.status ?? remoteResult?.git ?? remoteResult;
+    return remoteGit && typeof remoteGit === 'object' && typeof remoteGit.isGitRepo === 'boolean'
+        ? remoteGit as Record<string, unknown>
+        : null;
+}
+
+async function hydrateInlineMeshDirectTruth(args: {
+    mesh: any;
+    meshSource: 'inline_cache' | 'inline_bootstrap' | 'local_config';
+    dispatchMeshCommand?: (daemonId: string, cmd: string, args: Record<string, unknown>) => Promise<unknown>;
+    statusInstanceId?: string;
+    localMachineId?: string;
+}): Promise<{
+    directEvidenceCount: number;
+    localConfirmedCount: number;
+    peerAttemptedCount: number;
+    peerConfirmedCount: number;
+    unavailableNodeIds: string[];
+}> {
+    const nodes = Array.isArray(args.mesh?.nodes) ? args.mesh.nodes : [];
+    if (!nodes.length) {
+        return {
+            directEvidenceCount: 0,
+            localConfirmedCount: 0,
+            peerAttemptedCount: 0,
+            peerConfirmedCount: 0,
+            unavailableNodeIds: [],
+        };
+    }
+
+    const selectedCoordinatorNodeId = readStringValue(
+        args.mesh?.coordinator?.preferredNodeId,
+        nodes[0]?.id,
+        nodes[0]?.nodeId,
+    );
+
+    let localConfirmedCount = 0;
+    let peerAttemptedCount = 0;
+    let peerConfirmedCount = 0;
+    const unavailableNodeIds: string[] = [];
+
+    for (const [nodeIndex, node] of nodes.entries()) {
+        const nodeId = readStringValue(node?.id, node?.nodeId) || `node_${nodeIndex}`;
+        const workspace = readStringValue(node?.workspace);
+        const daemonId = readStringValue(node?.daemonId);
+        const isSelfNode = Boolean(
+            nodeId && selectedCoordinatorNodeId && nodeId === selectedCoordinatorNodeId,
+        ) || Boolean(
+            daemonId && (daemonId === args.localMachineId || daemonId === args.statusInstanceId),
+        ) || Boolean(args.meshSource !== 'local_config' && nodeIndex === 0);
+
+        if (!workspace) {
+            if (!isSelfNode && daemonId) unavailableNodeIds.push(nodeId);
+            continue;
+        }
+
+        if (fs.existsSync(workspace)) {
+            try {
+                const localGit = await getGitRepoStatus(workspace, { timeoutMs: 10_000, refreshUpstream: true });
+                if (localGit?.isGitRepo) {
+                    recordInlineMeshDirectGitTruth(node, localGit as unknown as Record<string, unknown>, 'selected_coordinator_local_git');
+                    localConfirmedCount += 1;
+                    continue;
+                }
+            } catch {
+                // Fall through to remote classification.
+            }
+        }
+
+        if (!daemonId || !args.dispatchMeshCommand) {
+            if (!isSelfNode) unavailableNodeIds.push(nodeId);
+            continue;
+        }
+
+        peerAttemptedCount += 1;
+        try {
+            const remoteGit = await probeRemoteMeshGitStatus({
+                dispatchMeshCommand: args.dispatchMeshCommand,
+                daemonId,
+                workspace,
+                timeoutMs: 8_000,
+            });
+            if (remoteGit) {
+                recordInlineMeshDirectGitTruth(node, remoteGit, 'selected_coordinator_mesh_p2p_git');
+                peerConfirmedCount += 1;
+                continue;
+            }
+        } catch {
+            // Strict direct-only path: do not fall back to persisted cloud truth here.
+        }
+
+        unavailableNodeIds.push(nodeId);
+    }
+
+    return {
+        directEvidenceCount: localConfirmedCount + peerConfirmedCount,
+        localConfirmedCount,
+        peerAttemptedCount,
+        peerConfirmedCount,
+        unavailableNodeIds,
+    };
+}
+
 function summarizeMeshSessionRecord(record: any): Record<string, unknown> {
+    const meta = readObjectRecord(record?.meta);
+    const isSelfCoordinator = Boolean(readStringValue(meta.meshCoordinatorFor));
+    const chatStatus = readStringValue(record?.chatStatus, record?.activeChat?.status, meta.chatStatus, meta.sessionStatus);
+    const state = readLiveMeshSessionState(record);
+    const statusNote = isSelfCoordinator && (!chatStatus || chatStatus === 'idle' || state === 'idle')
+        ? 'Coordinator self status is sampled from the session host and may read idle while the coordinator is generating this response.'
+        : null;
     return {
         sessionId: readStringValue(record?.sessionId) || 'unknown',
         providerType: readStringValue(record?.providerType),
-        state: readLiveMeshSessionState(record),
+        state,
+        chatStatus,
         lifecycle: readStringValue(record?.lifecycle),
         surfaceKind: getSessionHostSurfaceKind(record as any),
-        recoveryState: readStringValue(record?.meta?.runtimeRecoveryState) ?? null,
+        recoveryState: readStringValue(meta.runtimeRecoveryState) ?? null,
         workspace: readStringValue(record?.workspace) ?? null,
         title: readStringValue(record?.displayName, record?.workspaceLabel) ?? null,
+        role: isSelfCoordinator ? 'coordinator' : readStringValue(meta.meshRole, meta.role) ?? null,
+        isSelfCoordinator,
+        statusNote,
+        createdAt: toIsoTimestamp(record?.createdAt ?? record?.created_at),
+        startedAt: toIsoTimestamp(record?.startedAt ?? record?.started_at ?? record?.spawnedAtMs ?? record?.spawned_at_ms),
         lastActivityAt: toIsoTimestamp(record?.updatedAt ?? record?.lastActivityAt ?? record?.last_activity_at),
         isCached: false,
     };
 }
 
+function liveSessionRecordMatchesMeshNode(record: any, meshId: string, nodeId: string, nodeWorkspace = '', nodeIsMissingLocalWorktree = false): boolean {
+    const recordNodeId = readStringValue(record?.meta?.meshNodeId);
+    if (!recordNodeId || recordNodeId !== nodeId) return false;
+    if (nodeIsMissingLocalWorktree) return false;
+    const recordWorkspace = readStringValue(record?.workspace);
+    if (nodeWorkspace && recordWorkspace && recordWorkspace !== nodeWorkspace) return false;
+    const recordMeshId = readStringValue(record?.meta?.meshNodeFor);
+    return !recordMeshId || recordMeshId === meshId;
+}
+
+function liveSessionRecordMatchesMeshWorkspace(record: any, meshId: string, workspace: string): boolean {
+    const recordWorkspace = readStringValue(record?.workspace);
+    if (!recordWorkspace || !workspace || recordWorkspace !== workspace) return false;
+
+    const recordMeshId = readStringValue(record?.meta?.meshNodeFor);
+    if (recordMeshId) return recordMeshId === meshId;
+
+    return record?.meta?.launchedByCoordinator === true || !!readStringValue(record?.meta?.meshNodeId);
+}
+
 function readLiveMeshNodeWorkspace(args: {
     meshId: string;
     nodeId: string;
@@ -335,7 +1126,7 @@ function readLiveMeshNodeWorkspace(args: {
     allowCoordinatorSession?: boolean;
 }): string {
     const directNodeWorkspace = args.liveSessionRecords.find((record) => (
-        readStringValue(record?.meta?.meshNodeId) === args.nodeId
+        liveSessionRecordMatchesMeshNode(record, args.meshId, args.nodeId)
         && readStringValue(record?.workspace)
     ));
     if (directNodeWorkspace) {
@@ -362,11 +1153,16 @@ function collectLiveMeshSessionRecords(args: {
     liveSessionRecords: any[];
     allowCoordinatorSession?: boolean;
 }): any[] {
+    const nodeWorkspace = readStringValue(args.node?.workspace);
+    const nodeIsMissingLocalWorktree = args.node?.isLocalWorktree === true
+        && !!nodeWorkspace
+        && !fs.existsSync(nodeWorkspace);
     const matches = args.liveSessionRecords.filter((record) => {
-        if (readStringValue(record?.meta?.meshNodeId) === args.nodeId) return true;
-        const recordWorkspace = readStringValue(record?.workspace);
-        const nodeWorkspace = readStringValue(args.node?.workspace);
-        return !!recordWorkspace && !!nodeWorkspace && recordWorkspace === nodeWorkspace;
+        const recordNodeId = readStringValue(record?.meta?.meshNodeId);
+        if (recordNodeId && recordNodeId !== args.nodeId) return false;
+        if (liveSessionRecordMatchesMeshNode(record, args.meshId, args.nodeId, nodeWorkspace || '', nodeIsMissingLocalWorktree)) return true;
+        if (nodeIsMissingLocalWorktree) return false;
+        return !!nodeWorkspace && liveSessionRecordMatchesMeshWorkspace(record, args.meshId, nodeWorkspace);
     });
 
     if (args.allowCoordinatorSession) {
@@ -381,11 +1177,62 @@ function collectLiveMeshSessionRecords(args: {
     return matches;
 }
 
-function applyCachedInlineMeshNodeStatus(status: Record<string, unknown>, node: any): boolean {
+function buildHistoricalMeshSessions(args: {
+    meshId: string;
+    nodes: any[];
+    liveSessionRecords: any[];
+}): { count: number; sessions: Record<string, unknown>[]; instruction: string } | undefined {
+    const liveNodeIds = new Set<string>();
+    const liveWorkspaces = new Set<string>();
+    const missingLocalWorktreeNodeIds = new Set<string>();
+    for (const node of args.nodes || []) {
+        const nodeId = readStringValue(node?.id, node?.nodeId);
+        const workspace = readStringValue(node?.workspace);
+        if (nodeId) liveNodeIds.add(nodeId);
+        if (workspace) liveWorkspaces.add(workspace);
+        if (nodeId && node?.isLocalWorktree === true && workspace && !fs.existsSync(workspace)) {
+            missingLocalWorktreeNodeIds.add(nodeId);
+        }
+    }
+
+    const sessions: Record<string, unknown>[] = [];
+    for (const record of args.liveSessionRecords || []) {
+        const meta = readObjectRecord(record?.meta);
+        const recordMeshId = readStringValue(meta.meshNodeFor, meta.meshCoordinatorFor);
+        if (recordMeshId !== args.meshId) continue;
+        const recordNodeId = readStringValue(meta.meshNodeId);
+        const workspace = readStringValue(record?.workspace);
+        const removedNode = !!recordNodeId && (!liveNodeIds.has(recordNodeId) || missingLocalWorktreeNodeIds.has(recordNodeId));
+        const orphanedWorkspace = !!workspace && !liveWorkspaces.has(workspace) && meta.meshCoordinatorFor !== args.meshId;
+        if (!removedNode && !orphanedWorkspace) continue;
+        sessions.push({
+            ...summarizeMeshSessionRecord(record),
+            classification: removedNode ? 'removedNode' : 'orphanedSession',
+            historical: true,
+            meshNodeId: recordNodeId || null,
+            reason: removedNode
+                ? 'Session is tagged to a mesh node that is no longer in live membership.'
+                : 'Session workspace is no longer attached to a live mesh node.',
+        });
+    }
+    if (sessions.length === 0) return undefined;
+    return {
+        count: sessions.length,
+        sessions: sessions.slice(0, 5),
+        instruction: 'These sessions are separated from normal node activeSessions because their mesh node/workspace is no longer live. Use mesh_cleanup_sessions only if cleanup is intended.',
+    };
+}
+
+function applyCachedInlineMeshNodeStatus(
+    status: Record<string, unknown>,
+    node: any,
+    options?: { skipGit?: boolean; skipError?: boolean; skipHealth?: boolean },
+): 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 liveGit = buildInlineMeshTransitGitStatus(node);
+    const git = options?.skipGit ? undefined : (liveGit ?? buildCachedInlineMeshGitStatus(node));
+    const error = options?.skipError ? undefined : (liveGit ? undefined : readStringValue(cachedStatus.error, node?.error));
+    const health = options?.skipHealth ? undefined : (liveGit ? undefined : readStringValue(cachedStatus.health, node?.health));
     const machineStatus = readStringValue(cachedStatus.machineStatus, node?.machineStatus);
     const lastSeenAt = toIsoTimestamp(cachedStatus.lastSeenAt ?? cachedStatus.last_seen_at ?? node?.lastSeenAt ?? node?.last_seen_at);
     const updatedAt = toIsoTimestamp(cachedStatus.updatedAt ?? cachedStatus.updated_at ?? node?.updatedAt ?? node?.updated_at);
@@ -442,29 +1289,140 @@ async function resolveProviderTypeFromPriority(args: {
 }
 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 MeshRefineValidationCommand = MeshRefineValidationCommandPlan;
 
 type MeshRefineValidationSummary = {
     status: MeshRefineValidationStatus;
     required: true;
     commandsRun: Array<Record<string, unknown>>;
+    bootstrapCommandsRun: Array<Record<string, unknown>>;
     rejectedCommands: Array<Record<string, unknown>>;
     skippedReason?: string;
+    failureKind?: string;
+    failureCode?: string;
     timeoutMs: number;
     outputLimitBytes: number;
+    configSource?: string;
+    configSourceType?: string;
+    suggestions?: unknown[];
+    suggestedConfig?: unknown;
+};
+
+type MeshRefineStageStatus = 'passed' | 'failed' | 'skipped';
+
+type MeshRefinePatchEquivalenceSummary = {
+    status: MeshRefineStageStatus;
+    equivalent: boolean;
+    baseHead: string;
+    branchHead: string;
+    mergeBase?: string;
+    mergedTree?: string;
+    expectedPatchId?: string;
+    actualPatchId?: string;
+    durationMs: number;
+    error?: string;
+    stdout?: string;
+    stderr?: string;
+    actionableHint?: MeshRefineSubmoduleConflictHint;
+};
+
+type MeshRefineSubmoduleConflictHint = {
+    kind: 'submodule_conflict';
+    message: string;
+    conflicts: Array<{
+        path: string;
+        baseCommit?: string;
+        branchCommit?: string;
+    }>;
+    nextSteps: string[];
+};
+
+type MeshRefineSubmoduleAlignmentSummary = {
+    status: 'passed' | 'failed' | 'skipped';
+    changedGitlinkPaths: string[];
+    outOfSyncPaths: string[];
+    updatedPaths: string[];
+    verifiedPaths: string[];
+    durationMs: number;
+    reason?: string;
+    command?: string;
+    error?: string;
+    stdout?: string;
+    stderr?: string;
+};
+
+type MeshRefineSubmoduleReachabilityEntry = {
+    path: string;
+    commit: string;
+    reachable: boolean;
+    publishRequired?: boolean;
+    autoPublishAllowed?: boolean;
+    autoPublishAttempted?: boolean;
+    autoPublishSucceeded?: boolean;
+    autoPublishVerified?: boolean;
+    autoPublishRefspec?: string;
+    autoPublishSkippedReason?: string;
+    importedFromWorktree?: boolean;
+    checkedLocal?: boolean;
+    localReachable?: boolean;
+    remote?: string;
+    remoteUrl?: string;
+    remoteReachable?: boolean;
+    remoteMainBranch?: string;
+    remoteMainReachable?: boolean;
+    fetchedFromOrigin?: boolean;
+    error?: string;
+    publishStdout?: string;
+    publishStderr?: string;
 };
 
+type MeshRefineSubmoduleReachabilitySummary = {
+    status: MeshRefineStageStatus;
+    checked: number;
+    unreachable: MeshRefineSubmoduleReachabilityEntry[];
+    entries: MeshRefineSubmoduleReachabilityEntry[];
+    durationMs: number;
+    autoPublishAllowed?: boolean;
+    autoPublishPolicySource?: string;
+    error?: string;
+};
+
+type MeshRefineAsyncJobStatus = 'accepted' | 'completed' | 'failed';
+
+type MeshRefineJobHandle = {
+    success: true;
+    async: true;
+    status: MeshRefineAsyncJobStatus;
+    jobId: string;
+    interactionId: string;
+    meshId: string;
+    nodeId: string;
+    targetNodeId: string;
+    targetDaemonId?: string;
+    workspace?: string;
+    startedAt: string;
+    completedAt?: string;
+    duplicate?: boolean;
+    retryOfJobId?: string;
+    eventDelivery: {
+        pendingEvents: true;
+        ledger: true;
+    };
+    evidence: {
+        pendingEventsCommand: 'get_pending_mesh_events';
+        ledgerCommand: 'get_mesh_ledger_slice';
+        taskHistoryKind: 'task_dispatched' | 'task_completed' | 'task_failed';
+    };
+};
+
+type MeshRefineTerminalJob = MeshRefineJobHandle & { result?: Record<string, unknown> };
+
 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;
+const REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES = 4 * 1024 * 1024;
 
 function truncateValidationOutput(value: unknown): string {
     const text = typeof value === 'string' ? value : value == null ? '' : String(value);
@@ -472,171 +1430,492 @@ function truncateValidationOutput(value: unknown): string {
     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 recordMeshRefineStage(
+    stages: Array<Record<string, unknown>>,
+    stage: string,
+    status: MeshRefineStageStatus,
+    startedAt: number,
+    details?: Record<string, unknown>,
+): void {
+    stages.push({
+        stage,
+        status,
+        durationMs: Date.now() - startedAt,
+        ...(details || {}),
+    });
 }
 
-function scriptMatchesValidationCategory(scriptName: string, category: string): boolean {
-    return scriptName === category || scriptName.startsWith(`${category}:`);
+function buildSubmodulePublishRequiredNextStep(entries: MeshRefineSubmoduleReachabilityEntry[]): string {
+    const refs = entries
+        .map(entry => `${entry.path}@${entry.commit}`)
+        .join(', ');
+    return `Ask the user for explicit approval to push/publish the unreachable submodule commit(s) (${refs}) to the configured submodule remote main branch, then rerun mesh_refine_node. Do not merge the root branch until every submodule gitlink commit is reachable from submodule origin/main.`;
 }
 
-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' } };
+function resolveRefineryAutoPublishSubmoduleMainCommits(mesh: any, workspace: string): { enabled: boolean; source?: string } {
+    if (mesh?.policy?.allowAutoPublishSubmoduleMainCommits === true) {
+        process.stderr.write(
+            `[adhdev-mesh] WARNING: allowAutoPublishSubmoduleMainCommits is ENABLED via mesh.policy. `
+            + `Refinery may push unreachable submodule commits to submodule origin/main without additional user approval.\n`,
+        );
+        return { enabled: true, source: 'mesh.policy.allowAutoPublishSubmoduleMainCommits' };
     }
-
-    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' } };
+    const loaded = loadMeshRefineConfig(mesh, workspace);
+    if (loaded.config?.allowAutoPublishSubmoduleMainCommits === true) {
+        process.stderr.write(
+            `[adhdev-mesh] WARNING: allowAutoPublishSubmoduleMainCommits is ENABLED via ${loaded.path || loaded.source}. `
+            + `Refinery may push unreachable submodule commits to submodule origin/main without additional user approval.\n`,
+        );
+        return { enabled: true, source: loaded.path || loaded.source };
     }
+    return { enabled: false };
+}
 
-    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' } };
+async function computeGitPatchId(cwd: string, fromRef: string, toRef: string): Promise<string> {
+    const { execFileSync } = await import('node:child_process');
+    const diff = execFileSync('git', ['diff', '--patch', '--full-index', fromRef, toRef], {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+    });
+    if (!diff.trim()) return '';
+    const patchId = execFileSync('git', ['patch-id', '--stable'], {
+        cwd,
+        input: diff,
+        encoding: 'utf8',
+        maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+    }).trim();
+    return patchId.split(/\s+/)[0] || '';
+}
+
+async function runMeshRefinePatchEquivalenceGate(
+    repoRoot: string,
+    baseHead: string,
+    branchHead: string,
+): Promise<MeshRefinePatchEquivalenceSummary> {
+    const startedAt = Date.now();
+    try {
+        const { execFileSync } = await import('node:child_process');
+        const git = (args: string[]) => execFileSync('git', args, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+        });
+        const mergeBase = git(['merge-base', baseHead, branchHead]).trim();
+        const mergeTreeStdout = git(['merge-tree', '--write-tree', baseHead, branchHead]);
+        const mergedTree = mergeTreeStdout.trim().split(/\s+/)[0] || '';
+        if (!mergeBase || !mergedTree) {
+            return {
+                status: 'failed',
+                equivalent: false,
+                baseHead,
+                branchHead,
+                mergeBase: mergeBase || undefined,
+                mergedTree: mergedTree || undefined,
+                durationMs: Date.now() - startedAt,
+                error: 'patch equivalence preflight could not resolve merge-base or synthetic merge tree',
+                stdout: truncateValidationOutput(mergeTreeStdout),
+            };
+        }
+        const expectedPatchId = await computeGitPatchId(repoRoot, mergeBase, branchHead);
+        const actualPatchId = await computeGitPatchId(repoRoot, baseHead, mergedTree);
+        const equivalent = expectedPatchId === actualPatchId;
+        return {
+            status: equivalent ? 'passed' : 'failed',
+            equivalent,
+            baseHead,
+            branchHead,
+            mergeBase,
+            mergedTree,
+            expectedPatchId,
+            actualPatchId,
+            durationMs: Date.now() - startedAt,
+        };
+    } catch (e: any) {
+        return {
+            status: 'failed',
+            equivalent: false,
+            baseHead,
+            branchHead,
+            durationMs: Date.now() - startedAt,
+            error: e?.message || String(e),
+            stdout: truncateValidationOutput(e?.stdout),
+            stderr: truncateValidationOutput(e?.stderr),
+            actionableHint: buildPatchEquivalenceSubmoduleConflictHint(
+                repoRoot,
+                baseHead,
+                branchHead,
+                `${e?.message || ''}\n${e?.stdout || ''}\n${e?.stderr || ''}`,
+            ),
+        };
     }
+}
 
+function buildPatchEquivalenceSubmoduleConflictHint(
+    repoRoot: string,
+    baseHead: string,
+    branchHead: string,
+    output: string,
+): MeshRefineSubmoduleConflictHint | undefined {
+    if (!/(submodule|160000)/i.test(output) || !/(conflict|failed to merge)/i.test(output)) return undefined;
+    const conflicts = readChangedGitlinkPaths(repoRoot, baseHead, branchHead)
+        .map(path => ({
+            path,
+            baseCommit: readTreeObject(repoRoot, baseHead, path),
+            branchCommit: readTreeObject(repoRoot, branchHead, path),
+        }));
+    if (conflicts.length === 0) return undefined;
     return {
-        command: {
-            command,
-            args,
-            displayCommand: [command, ...args].join(' '),
-            category,
-            source,
-        },
+        kind: 'submodule_conflict',
+        message: 'Refinery could not synthesize a safe merge tree because the branch and base point the same submodule path at different commits.',
+        conflicts,
+        nextSteps: [
+            'Inspect the listed submodule path in both base and branch: baseCommit is the commit currently recorded by the base workspace, branchCommit is the commit recorded by the worktree branch.',
+            'Resolve the submodule first by checking out or creating the intended submodule commit, then commit the chosen gitlink in the root branch.',
+            'Ensure the chosen submodule commit is reachable from the configured submodule remote main branch, then rerun mesh_refine_node.',
+        ],
     };
 }
 
-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,
-            });
+function readChangedGitlinkPaths(repoRoot: string, fromRef: string, toRef: string): string[] {
+    try {
+        const output = execFileSync('git', ['diff', '--raw', '--no-abbrev', fromRef, toRef], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+        });
+        const paths = new Set<string>();
+        for (const line of output.split('\n')) {
+            if (!line.trim()) continue;
+            const metaAndPath = line.split('\t');
+            const meta = metaAndPath[0] || '';
+            const path = metaAndPath[metaAndPath.length - 1]?.trim();
+            if (!path) continue;
+            const parts = meta.split(/\s+/);
+            if (parts[0]?.includes('160000') || parts[1]?.includes('160000')) {
+                paths.add(path);
+            }
         }
+        return [...paths].sort();
+    } catch {
+        return [];
     }
-    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 readTreeObject(repoRoot: string, ref: string, path: string): string | undefined {
+    try {
+        const output = execFileSync('git', ['ls-tree', ref, '--', path], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            maxBuffer: 1024 * 1024,
+        }).trim();
+        const match = output.match(/\bcommit\s+([0-9a-f]{40})\b/i);
+        return match?.[1];
+    } catch {
+        return undefined;
+    }
 }
 
-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;
+async function alignRefinerySubmodulesAfterMerge(
+    repoRoot: string,
+    previousBaseHead: string,
+    currentHead: string,
+    options: { submoduleIgnorePaths?: string[] } = {},
+): Promise<MeshRefineSubmoduleAlignmentSummary> {
+    const startedAt = Date.now();
+    const changedGitlinkPaths = readChangedGitlinkPaths(repoRoot, previousBaseHead, currentHead)
+        .filter(path => !(options.submoduleIgnorePaths || []).includes(path));
+    const preStatus = await getGitRepoStatus(repoRoot, {
+        includeSubmodules: true,
+        submoduleIgnorePaths: options.submoduleIgnorePaths,
+        timeoutMs: 15_000,
+    });
+    const outOfSyncPaths = (preStatus.submodules || [])
+        .filter(submodule => submodule.dirty || submodule.outOfSync || !!submodule.error)
+        .map(submodule => submodule.path);
+    const updatePaths = [...new Set([...changedGitlinkPaths, ...outOfSyncPaths])].sort();
+
+    if (updatePaths.length === 0) {
+        return {
+            status: 'skipped',
+            changedGitlinkPaths,
+            outOfSyncPaths,
+            updatedPaths: [],
+            verifiedPaths: [],
+            durationMs: Date.now() - startedAt,
+            reason: 'no_changed_or_out_of_sync_submodules',
+        };
+    }
+
+    const commandArgs = ['submodule', 'update', '--init', '--recursive', '--', ...updatePaths];
+    try {
+        const { execFile } = await import('node:child_process');
+        const { promisify } = await import('node:util');
+        const execFileAsync = promisify(execFile);
+        const result = await execFileAsync('git', commandArgs, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+            timeout: 60_000,
+        });
+        const postStatus = await getGitRepoStatus(repoRoot, {
+            includeSubmodules: true,
+            submoduleIgnorePaths: options.submoduleIgnorePaths,
+            timeoutMs: 15_000,
+        });
+        const remaining = (postStatus.submodules || [])
+            .filter(submodule => updatePaths.includes(submodule.path) && (submodule.dirty || submodule.outOfSync || !!submodule.error));
+        return {
+            status: remaining.length === 0 ? 'passed' : 'failed',
+            changedGitlinkPaths,
+            outOfSyncPaths,
+            updatedPaths: updatePaths,
+            verifiedPaths: updatePaths.filter(path => !remaining.some(submodule => submodule.path === path)),
+            durationMs: Date.now() - startedAt,
+            command: `git ${commandArgs.join(' ')}`,
+            stdout: truncateValidationOutput(result.stdout),
+            stderr: truncateValidationOutput(result.stderr),
+            ...(remaining.length > 0 ? { error: `Submodule checkout remained out of sync after update: ${remaining.map(entry => entry.path).join(', ')}` } : {}),
+        };
+    } catch (e: any) {
+        return {
+            status: 'failed',
+            changedGitlinkPaths,
+            outOfSyncPaths,
+            updatedPaths: updatePaths,
+            verifiedPaths: [],
+            durationMs: Date.now() - startedAt,
+            command: `git ${commandArgs.join(' ')}`,
+            error: e?.message || String(e),
+            stdout: truncateValidationOutput(e?.stdout),
+            stderr: truncateValidationOutput(e?.stderr),
+        };
+    }
+}
+
+async function runMeshRefineSubmoduleReachabilityGate(
+    repoRoot: string,
+    mergedTree: string,
+    options: { allowAutoPublishSubmoduleMainCommits?: boolean; autoPublishPolicySource?: string; worktreeRoot?: string } = {},
+): Promise<MeshRefineSubmoduleReachabilitySummary> {
+    const startedAt = Date.now();
+    const entries: MeshRefineSubmoduleReachabilityEntry[] = [];
+    try {
+        const { execFile } = await import('node:child_process');
+        const { promisify } = await import('node:util');
+        const execFileAsync = promisify(execFile);
+        const runGit = async (cwd: string, args: string[]): Promise<string> => {
+            const { stdout } = await execFileAsync('git', args, {
+                cwd,
+                encoding: 'utf8',
+                timeout: 30_000,
+                maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+                windowsHide: true,
+            });
+            return String(stdout || '');
+        };
+        const verifyRemoteMainContainsCommit = async (submodulePath: string, commit: string, branch = 'main'): Promise<void> => {
+            await runGit(submodulePath, ['-c', 'protocol.file.allow=always', 'fetch', 'origin', `refs/heads/${branch}:refs/remotes/origin/${branch}`]);
+            await runGit(submodulePath, ['merge-base', '--is-ancestor', commit, `refs/remotes/origin/${branch}`]);
+        };
+        const publishCommitToRemoteMain = async (submodulePath: string, commit: string, branch = 'main'): Promise<{ stdout: string; stderr: string; refspec: string }> => {
+            const refspec = `${commit}:refs/heads/${branch}`;
+            const { stdout, stderr } = await execFileAsync('git', ['push', 'origin', refspec], {
+                cwd: submodulePath,
+                encoding: 'utf8',
+                timeout: 30_000,
+                maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+                windowsHide: true,
+            });
+            return { stdout: String(stdout || ''), stderr: String(stderr || ''), refspec };
+        };
+        const importCommitFromWorktreeSubmodule = async (submodulePath: string, worktreeSubmodulePath: string, commit: string): Promise<boolean> => {
+            if (!fs.existsSync(worktreeSubmodulePath)) return false;
+            try {
+                await runGit(worktreeSubmodulePath, ['cat-file', '-e', `${commit}^{commit}`]);
+            } catch {
+                return false;
+            }
+            await runGit(submodulePath, ['-c', 'protocol.file.allow=always', 'fetch', worktreeSubmodulePath, commit]);
+            await runGit(submodulePath, ['cat-file', '-e', `${commit}^{commit}`]);
+            return true;
+        };
+
+        const treeOutput = await runGit(repoRoot, ['ls-tree', '-r', '-z', mergedTree]);
+        const gitlinks = treeOutput
+            .split('\0')
+            .filter(Boolean)
+            .map(record => {
+                const match = /^160000\s+commit\s+([0-9a-f]{40})\t(.+)$/.exec(record);
+                return match ? { commit: match[1], path: match[2] } : null;
+            })
+            .filter((entry): entry is { commit: string; path: string } => !!entry);
+
+        for (const gitlink of gitlinks) {
+            const submodulePath = pathResolve(repoRoot, gitlink.path);
+            const entry: MeshRefineSubmoduleReachabilityEntry = {
+                path: gitlink.path,
+                commit: gitlink.commit,
+                reachable: false,
+            };
+            try {
+                if (!fs.existsSync(submodulePath)) {
+                    entry.error = `Submodule checkout missing at ${gitlink.path}`;
+                    entry.publishRequired = true;
+                    if (options.allowAutoPublishSubmoduleMainCommits === true) {
+                        entry.autoPublishAllowed = true;
+                        entry.autoPublishAttempted = false;
+                        entry.autoPublishSkippedReason = `submodule checkout missing at ${gitlink.path}; cannot perform non-force push to origin/main`;
+                    }
+                    entries.push(entry);
+                    continue;
+                }
+
+                entry.checkedLocal = true;
+                try {
+                    await runGit(submodulePath, ['cat-file', '-e', `${gitlink.commit}^{commit}`]);
+                    entry.localReachable = true;
+                } catch {
+                    entry.localReachable = false;
+                    if (options.allowAutoPublishSubmoduleMainCommits === true && options.worktreeRoot) {
+                        try {
+                            const imported = await importCommitFromWorktreeSubmodule(
+                                submodulePath,
+                                pathResolve(options.worktreeRoot, gitlink.path),
+                                gitlink.commit,
+                            );
+                            if (imported) {
+                                entry.localReachable = true;
+                                entry.importedFromWorktree = true;
+                            }
+                        } catch (importError: any) {
+                            entry.autoPublishSkippedReason = `candidate commit was not present in the source checkout and could not be imported from worktree submodule: ${truncateValidationOutput(importError?.stderr || importError?.message || String(importError))}`;
+                        }
+                    }
+                    // Probe the submodule remote before allowing cleanup/completion.
+                }
+
+                try {
+                    entry.remote = 'origin';
+                    let remoteUrl = '';
+                    try {
+                        remoteUrl = (await runGit(submodulePath, ['remote', 'get-url', 'origin'])).trim();
+                        if (!remoteUrl) throw new Error('origin remote has no URL');
+                        entry.remoteUrl = remoteUrl;
+                    } catch {
+                        entry.error = 'Submodule remote reachability check failed: no configured origin remote';
+                        entry.publishRequired = true;
+                        if (options.allowAutoPublishSubmoduleMainCommits === true) {
+                            entry.autoPublishAllowed = true;
+                            entry.autoPublishAttempted = false;
+                            entry.autoPublishSkippedReason = 'submodule origin remote is not configured; cannot perform non-force push to origin/main';
+                        }
+                        entries.push(entry);
+                        continue;
+                    }
+                    entry.remoteMainBranch = 'main';
+                    try {
+                        await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, 'main');
+                        entry.fetchedFromOrigin = true;
+                        entry.remoteReachable = true;
+                        entry.remoteMainReachable = true;
+                        entry.reachable = true;
+                    } catch (e: any) {
+                        entry.remoteReachable = false;
+                        entry.remoteMainReachable = false;
+                        entry.publishRequired = true;
+                        const details = truncateValidationOutput(e?.stderr || e?.message || String(e));
+                        entry.error = `Submodule remote main reachability check failed for origin/main: ${details}`;
+                        if (options.allowAutoPublishSubmoduleMainCommits === true && entry.localReachable === true) {
+                            entry.autoPublishAllowed = true;
+                            entry.autoPublishAttempted = true;
+                            try {
+                                const publish = await publishCommitToRemoteMain(submodulePath, gitlink.commit, 'main');
+                                entry.autoPublishRefspec = publish.refspec;
+                                entry.publishStdout = truncateValidationOutput(publish.stdout);
+                                entry.publishStderr = truncateValidationOutput(publish.stderr);
+                                entry.autoPublishSucceeded = true;
+                                await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, 'main');
+                                entry.fetchedFromOrigin = true;
+                                entry.remoteReachable = true;
+                                entry.remoteMainReachable = true;
+                                entry.autoPublishVerified = true;
+                                entry.publishRequired = false;
+                                entry.reachable = true;
+                                entry.error = undefined;
+                            } catch (publishError: any) {
+                                entry.autoPublishSucceeded = false;
+                                entry.autoPublishVerified = false;
+                                const publishDetails = truncateValidationOutput(publishError?.stderr || publishError?.message || String(publishError));
+                                entry.error = `Submodule auto-publish to origin/main failed or could not be verified: ${publishDetails}`;
+                            }
+                        } else if (options.allowAutoPublishSubmoduleMainCommits === true) {
+                            entry.autoPublishAllowed = true;
+                            entry.autoPublishAttempted = false;
+                            entry.autoPublishSkippedReason = entry.autoPublishSkippedReason
+                                || 'candidate commit is not reachable in the source checkout or worktree submodule, so Refinery cannot push it to origin/main';
+                        }
+                    }
+                } catch (e: any) {
+                    entry.remoteReachable = false;
+                    entry.remoteMainReachable = false;
+                    entry.publishRequired = true;
+                    const details = truncateValidationOutput(e?.stderr || e?.message || String(e));
+                    entry.error = `Submodule remote main reachability check failed for origin/main: ${details}`;
+                }
+            } catch (e: any) {
+                entry.error = truncateValidationOutput(e?.message || String(e));
+                entry.publishRequired = true;
+            }
+            entries.push(entry);
         }
+
+        const unreachable = entries.filter(entry => !entry.reachable);
+        return {
+            status: unreachable.length ? 'failed' : 'passed',
+            checked: entries.length,
+            unreachable: unreachable.map(entry => ({ ...entry, publishRequired: entry.publishRequired !== false })),
+            entries: entries.map(entry => entry.reachable ? entry : { ...entry, publishRequired: entry.publishRequired !== false }),
+            durationMs: Date.now() - startedAt,
+            autoPublishAllowed: options.allowAutoPublishSubmoduleMainCommits === true,
+            autoPublishPolicySource: options.autoPublishPolicySource,
+        };
+    } catch (e: any) {
+        const unreachable = entries.filter(entry => !entry.reachable).map(entry => ({ ...entry, publishRequired: true }));
+        return {
+            status: 'failed',
+            checked: entries.length,
+            unreachable,
+            entries: entries.map(entry => entry.reachable ? entry : { ...entry, publishRequired: true }),
+            durationMs: Date.now() - startedAt,
+            autoPublishAllowed: options.allowAutoPublishSubmoduleMainCommits === true,
+            autoPublishPolicySource: options.autoPublishPolicySource,
+            error: truncateValidationOutput(e?.message || String(e)),
+        };
     }
+}
 
+function buildMeshRefineValidationPlan(mesh: any, workspace: string): Record<string, unknown> {
+    const plan = resolveMeshRefineValidationPlan(mesh, workspace);
+    const mapCommand = (command: MeshRefineValidationCommandPlan) => ({
+        displayCommand: command.displayCommand,
+        category: command.category,
+        source: command.source,
+        cwd: command.cwd,
+        timeoutMs: command.timeoutMs,
+    });
     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',
+        source: plan.source,
+        sourceType: plan.sourceType,
+        bootstrapCommands: plan.bootstrapCommands.map(mapCommand),
+        commands: plan.commands.map(mapCommand),
+        unavailableReason: plan.unavailableReason,
+        rejectedCommands: plan.rejectedCommands,
+        suggestions: plan.suggestions,
+        suggestedConfig: plan.suggestedConfig,
+        note: plan.sourceType === 'unavailable'
+            ? 'No validation command will be executed until a repo mesh/refine config is provided. Heuristics are suggestions only.'
+            : 'Validation commands are resolved from repo mesh/refine config; heuristics are suggestions only.',
     };
 }
 
@@ -644,60 +1923,119 @@ async function runMeshRefineValidationGate(mesh: any, workspace: string): Promis
     const { execFile } = await import('node:child_process');
     const { promisify } = await import('node:util');
     const execFileAsync = promisify(execFile);
-    const selection = selectMeshRefineValidationCommands(mesh, workspace);
+    const selection = resolveMeshRefineValidationPlan(mesh, workspace);
     const summary: MeshRefineValidationSummary = {
         status: 'skipped',
         required: true,
         commandsRun: [],
+        bootstrapCommandsRun: [],
         rejectedCommands: selection.rejectedCommands,
         skippedReason: undefined,
         timeoutMs: REFINE_VALIDATION_TIMEOUT_MS,
         outputLimitBytes: REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
+        configSource: selection.source,
+        configSourceType: selection.sourceType,
+        suggestions: selection.suggestions,
+        suggestedConfig: selection.suggestedConfig,
     };
 
     if (!selection.commands.length) {
-        summary.skippedReason = 'validation_unavailable: no allowlisted projectContext, mesh policy, or package.json build/test/typecheck/lint command was available';
+        summary.skippedReason = selection.unavailableReason || 'validation_unavailable: repo mesh/refine config did not provide executable validation.commands';
         return summary;
     }
 
-    for (const candidate of selection.commands) {
+    const commandRecord = (candidate: MeshRefineValidationCommand, cwd: string, startedAt: number, result: any, passed: boolean, extras: Record<string, unknown> = {}) => ({
+        command: candidate.command,
+        args: candidate.args,
+        displayCommand: candidate.displayCommand,
+        category: candidate.category,
+        source: candidate.source,
+        cwd,
+        passed,
+        durationMs: Date.now() - startedAt,
+        stdout: truncateValidationOutput(result?.stdout),
+        stderr: truncateValidationOutput(result?.stderr || result?.message),
+        ...extras,
+    });
+    const isPackageManagerValidation = (candidate: MeshRefineValidationCommand): boolean => {
+        const command = pathBasename(candidate.command).replace(/\.(?:cmd|exe)$/i, '');
+        return ['npm', 'pnpm', 'yarn', 'bun'].includes(command)
+            && candidate.args.some(arg => arg === 'run' || arg === 'test' || arg === 'exec');
+    };
+    const dependenciesLikelyMissing = (cwd: string): boolean => {
+        if (!fs.existsSync(pathJoin(cwd, 'package.json'))) return false;
+        if (fs.existsSync(pathJoin(cwd, 'node_modules'))) return false;
+        return ['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lockb', 'bun.lock']
+            .some(lock => fs.existsSync(pathJoin(cwd, lock)));
+    };
+
+    for (const candidate of selection.bootstrapCommands) {
         const startedAt = Date.now();
+        const cwd = candidate.cwd ? pathResolve(workspace, candidate.cwd) : workspace;
+        const timeout = candidate.timeoutMs || REFINE_VALIDATION_TIMEOUT_MS;
         try {
             const result = await execFileAsync(candidate.command, candidate.args, {
-                cwd: workspace,
+                cwd,
                 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),
+                timeout,
+                maxBuffer: candidate.outputLimitBytes || REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
+                env: { ...process.env, CI: process.env.CI || '1', ...(candidate.env || {}) },
             });
+            summary.bootstrapCommandsRun.push(commandRecord(candidate, cwd, startedAt, result, true, { exitCode: 0 }));
         } catch (error: any) {
-            summary.commandsRun.push({
-                command: candidate.command,
-                args: candidate.args,
-                displayCommand: candidate.displayCommand,
-                category: candidate.category,
-                source: candidate.source,
-                passed: false,
+            summary.bootstrapCommandsRun.push(commandRecord(candidate, cwd, startedAt, error, 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),
+                failureKind: 'dependency_bootstrap_failed',
+            }));
+            summary.status = 'failed';
+            summary.failureKind = 'dependency_bootstrap_failed';
+            summary.failureCode = 'dependency_bootstrap_failed';
+            return summary;
+        }
+    }
+
+    for (const candidate of selection.commands) {
+        const startedAt = Date.now();
+        const cwd = candidate.cwd ? pathResolve(workspace, candidate.cwd) : workspace;
+        const timeout = candidate.timeoutMs || REFINE_VALIDATION_TIMEOUT_MS;
+        if (selection.bootstrapCommands.length === 0 && isPackageManagerValidation(candidate) && dependenciesLikelyMissing(cwd)) {
+            summary.commandsRun.push(commandRecord(candidate, cwd, startedAt, {
+                stderr: 'Dependencies appear to be missing: package.json and a lockfile are present, but node_modules is absent. Configure validation.bootstrapCommands in repo mesh/refine config if Refinery should install/bootstrap before validation.',
+            }, false, {
+                exitCode: null,
+                skipped: true,
+                failureKind: 'missing_dependencies',
+            }));
+            summary.status = 'failed';
+            summary.failureKind = 'missing_dependencies';
+            summary.failureCode = 'missing_dependencies';
+            return summary;
+        }
+        try {
+            const result = await execFileAsync(candidate.command, candidate.args, {
+                cwd,
+                encoding: 'utf8',
+                timeout,
+                maxBuffer: candidate.outputLimitBytes || REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
+                env: { ...process.env, CI: process.env.CI || '1', ...(candidate.env || {}) },
             });
+            summary.commandsRun.push(commandRecord(candidate, cwd, startedAt, result, true, { exitCode: 0 }));
+        } catch (error: any) {
+            const stderr = truncateValidationOutput(error?.stderr || error?.message);
+            const missingDependencyFailure = /Cannot find module|MODULE_NOT_FOUND|node_modules|command not found|not found/i.test(stderr);
+            summary.commandsRun.push(commandRecord(candidate, cwd, startedAt, error, 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 || '')),
+                ...(missingDependencyFailure ? { failureKind: 'missing_dependencies' } : {}),
+            }));
             summary.status = 'failed';
+            if (missingDependencyFailure) {
+                summary.failureKind = 'missing_dependencies';
+                summary.failureCode = 'missing_dependencies';
+            }
             return summary;
         }
     }
@@ -810,12 +2148,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) */
@@ -829,6 +2169,8 @@ export interface CommandRouterDeps {
     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 {
@@ -931,12 +2273,56 @@ function summarizeSessionHostDiagnostics(result: unknown): Record<string, unknow
     };
 }
 
-function summarizeSessionHostPruneResult(result: unknown): Record<string, unknown> {
-    const value = result && typeof result === 'object' ? result as Record<string, any> : {};
+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,
+    };
+}
+
+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();
+}
+
+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) => node?.id === requestedNodeId || node?.nodeId === 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;
     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: source?.userOverrides && typeof source.userOverrides === 'object' && !Array.isArray(source.userOverrides) ? source.userOverrides : {},
+        policy: source?.policy && typeof source.policy === 'object' && !Array.isArray(source.policy) ? source.policy : {},
+        role: 'member',
     };
 }
 
@@ -946,11 +2332,160 @@ export class DaemonCommandRouter {
      *  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>();
+    /** Coordinator-owned whole-mesh aggregate status snapshots. Browser callers read this by default. */
+    private aggregateMeshStatusCache = new Map<string, { builtAt: number; snapshot: any; queueRevision: string }>();
+    /** In-memory async Refinery jobs keyed by meshId:nodeId to reject/return duplicate in-flight requests. */
+    private runningRefineJobs = new Map<string, MeshRefineJobHandle>();
+    /** Terminal async Refinery jobs preserve a clear answer after the worktree node has been removed. */
+    private terminalRefineJobs = new Map<string, MeshRefineTerminalJob>();
 
     constructor(deps: CommandRouterDeps) {
         this.deps = deps;
     }
 
+    private cloneJsonValue<T>(value: T): T {
+        if (typeof structuredClone === 'function') return structuredClone(value);
+        return JSON.parse(JSON.stringify(value)) as T;
+    }
+
+    private hydrateCachedAggregateMeshStatusFromInline(snapshot: any, mesh: any, options?: { requireDirectPeerTruth?: boolean }): any {
+        if (!mesh || typeof mesh !== 'object' || !Array.isArray(mesh.nodes) || !Array.isArray(snapshot?.nodes)) return snapshot;
+        const inlineNodesById = new Map<string, any>();
+        for (const node of mesh.nodes) {
+            const nodeId = readInlineMeshNodeId(node);
+            if (nodeId) inlineNodesById.set(nodeId, node);
+        }
+        if (!inlineNodesById.size) return snapshot;
+
+        let changed = false;
+        const unavailableNodeIds = new Set<string>();
+        const sourceOfTruth = readObjectRecord(snapshot.sourceOfTruth);
+        const directPeerTruth = readObjectRecord(sourceOfTruth.directPeerTruth);
+        for (const entry of Array.isArray(directPeerTruth.unavailableNodeIds) ? directPeerTruth.unavailableNodeIds : []) {
+            const nodeId = readStringValue(entry);
+            if (nodeId) unavailableNodeIds.add(nodeId);
+        }
+
+        const nodes = snapshot.nodes.map((statusNode: any) => {
+            const nodeId = readStringValue(statusNode?.nodeId, statusNode?.id);
+            const inlineNode = nodeId ? inlineNodesById.get(nodeId) : undefined;
+            if (!inlineNode) return statusNode;
+            const liveGit = buildInlineMeshTransitGitStatus(inlineNode);
+            if (!liveGit) return statusNode;
+            const nextStatus = { ...statusNode };
+            nextStatus.git = liveGit;
+            nextStatus.health = deriveMeshNodeHealthFromGit(liveGit);
+            applyInlineMeshBranchConvergence(mesh, inlineNode, nextStatus);
+            nextStatus.launchReady = readBooleanValue(nextStatus.launchReady) ?? true;
+            const connection = readObjectRecord(nextStatus.connection);
+            const connectionState = readStringValue(connection.state);
+            const connectionReported = readBooleanValue(connection.reported) ?? false;
+            if (!connectionReported || connectionState === 'unknown') {
+                nextStatus.connection = buildLivePeerGitConnection(connection);
+            }
+            delete nextStatus.gitProbePending;
+            const error = readStringValue(nextStatus.error);
+            if (error && /pending_git|git probe|live peer git snapshot|no peer git snapshot/i.test(error)) delete nextStatus.error;
+            if (!readStringValue(nextStatus.machineStatus)) nextStatus.machineStatus = 'online';
+            if (nodeId) unavailableNodeIds.delete(nodeId);
+            changed = true;
+            return nextStatus;
+        });
+
+        const aggregateDirectTruthSatisfied = sourceOfTruth.coordinatorOwnsLiveTruth === true
+            || directPeerTruth.satisfied === true;
+        if (!changed && !(options?.requireDirectPeerTruth && unavailableNodeIds.size > 0 && !aggregateDirectTruthSatisfied)) return snapshot;
+        const nextSourceOfTruth = {
+            ...sourceOfTruth,
+            ...(Object.keys(directPeerTruth).length ? {
+                directPeerTruth: {
+                    ...directPeerTruth,
+                    satisfied: options?.requireDirectPeerTruth === true
+                        ? aggregateDirectTruthSatisfied || unavailableNodeIds.size === 0
+                        : directPeerTruth.satisfied,
+                    unavailableNodeIds: [...unavailableNodeIds],
+                },
+                ...(options?.requireDirectPeerTruth === true ? {
+                    coordinatorOwnsLiveTruth: aggregateDirectTruthSatisfied || unavailableNodeIds.size === 0,
+                    currentStatus: aggregateDirectTruthSatisfied || unavailableNodeIds.size === 0 ? 'live_git_and_session_probes' : 'direct_peer_truth_unavailable',
+                } : {}),
+            } : {}),
+        };
+        return {
+            ...snapshot,
+            ...(options?.requireDirectPeerTruth === true && unavailableNodeIds.size > 0 && !aggregateDirectTruthSatisfied ? {
+                success: false,
+                code: 'mesh_direct_peer_truth_unavailable',
+                error: 'Selected coordinator could not confirm direct mesh truth for every remote node yet.',
+            } : {}),
+            sourceOfTruth: nextSourceOfTruth,
+            branchConvergenceSummary: summarizeInlineMeshBranchConvergence(nodes),
+            nodes,
+        };
+    }
+
+    private getCachedAggregateMeshStatus(meshId: string, mesh?: any, options?: { requireDirectPeerTruth?: boolean }): any | null {
+        const cached = this.aggregateMeshStatusCache.get(meshId);
+        if (!cached?.snapshot || cached.snapshot.success !== true || !Array.isArray(cached.snapshot.nodes)) return null;
+        if (cached.queueRevision !== getMeshQueueRevision(meshId)) return null;
+        let snapshot = this.cloneJsonValue(cached.snapshot);
+        snapshot = this.hydrateCachedAggregateMeshStatusFromInline(snapshot, mesh, options);
+        if (shouldRefreshStalePendingAggregate(snapshot, options)) return null;
+        const ageMs = Math.max(0, Date.now() - cached.builtAt);
+        const sourceOfTruth = snapshot.sourceOfTruth && typeof snapshot.sourceOfTruth === 'object'
+            ? snapshot.sourceOfTruth
+            : {};
+        snapshot.sourceOfTruth = {
+            ...sourceOfTruth,
+            aggregateSnapshot: {
+                ...(sourceOfTruth.aggregateSnapshot && typeof sourceOfTruth.aggregateSnapshot === 'object'
+                    ? sourceOfTruth.aggregateSnapshot
+                    : {}),
+                owner: 'coordinator_daemon_memory',
+                cached: true,
+                source: 'memory',
+                refreshReason: 'memory_cache_hit',
+                ageMs,
+                cachedAt: new Date(cached.builtAt).toISOString(),
+                returnedAt: new Date().toISOString(),
+            },
+        };
+        return snapshot;
+    }
+
+    private rememberAggregateMeshStatus(meshId: string, snapshot: any, refreshReason: string): any {
+        if (!snapshot || typeof snapshot !== 'object' || snapshot.success !== true || !Array.isArray(snapshot.nodes)) return snapshot;
+        const builtAt = Date.now();
+        const next = this.cloneJsonValue(snapshot);
+        const sourceOfTruth = next.sourceOfTruth && typeof next.sourceOfTruth === 'object'
+            ? next.sourceOfTruth
+            : {};
+        next.sourceOfTruth = {
+            ...sourceOfTruth,
+            aggregateSnapshot: {
+                owner: 'coordinator_daemon_memory',
+                cached: false,
+                source: 'live_refresh',
+                refreshReason,
+                ageMs: 0,
+                cachedAt: new Date(builtAt).toISOString(),
+                returnedAt: new Date(builtAt).toISOString(),
+            },
+        };
+        this.aggregateMeshStatusCache.set(meshId, { builtAt, snapshot: this.cloneJsonValue(next), queueRevision: getMeshQueueRevision(meshId) });
+        return next;
+    }
+
+    public getCachedInlineMeshNodes(): any[] {
+        const nodes: any[] = [];
+        for (const mesh of this.inlineMeshCache.values()) {
+            if (Array.isArray(mesh?.nodes)) {
+                nodes.push(...mesh.nodes);
+            }
+        }
+        return nodes;
+    }
+
     public getCachedInlineMesh(meshId: string, inlineMesh?: unknown): any | undefined {
         if (inlineMesh && typeof inlineMesh === 'object') {
             return this.warmInlineMeshCache(meshId, inlineMesh);
@@ -960,10 +2495,15 @@ export class DaemonCommandRouter {
 
     private warmInlineMeshCache(meshId: string, inlineMesh?: unknown): any | undefined {
         if (!inlineMesh || typeof inlineMesh !== 'object') return undefined;
+        const sanitizedInlineMesh = sanitizeInlineMesh(inlineMesh as any);
         const cached = this.inlineMeshCache.get(meshId);
-        if (cached) return cached;
-        this.inlineMeshCache.set(meshId, inlineMesh as any);
-        return inlineMesh as any;
+        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;
     }
 
     private async getMeshForCommand(
@@ -974,9 +2514,18 @@ export class DaemonCommandRouter {
         const preferInline = options?.preferInline === true;
         if (preferInline) {
             const cached = this.getCachedInlineMesh(meshId);
-            if (cached) return { mesh: cached, inline: true, source: 'inline_cache' };
-            const warmedInline = this.warmInlineMeshCache(meshId, inlineMesh);
-            if (warmedInline) return { mesh: warmedInline, inline: true, source: 'inline_bootstrap' };
+            if (cached) {
+                if (inlineMeshCarriesTransientNodeTruth(inlineMesh)) {
+                    const merged = reconcileInlineMeshCache(cached, inlineMesh as any);
+                    this.inlineMeshCache.set(meshId, sanitizeInlineMesh(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');
@@ -989,6 +2538,23 @@ export class DaemonCommandRouter {
         return warmedInline ? { mesh: warmedInline, inline: true, source: 'inline_bootstrap' } : null;
     }
 
+    private invalidateAggregateMeshStatus(meshId: string): void {
+        this.aggregateMeshStatusCache.delete(meshId);
+        this.deps.onMeshStateChange?.(meshId);
+    }
+
+
+    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);
@@ -996,6 +2562,7 @@ export class DaemonCommandRouter {
         else mesh.nodes.push(node);
         mesh.updatedAt = new Date().toISOString();
         this.inlineMeshCache.set(meshId, mesh);
+        this.invalidateAggregateMeshStatus(meshId);
     }
 
     private removeInlineMeshNode(meshId: string, mesh: any, nodeId: string): boolean {
@@ -1005,6 +2572,7 @@ export class DaemonCommandRouter {
         mesh.nodes.splice(idx, 1);
         mesh.updatedAt = new Date().toISOString();
         this.inlineMeshCache.set(meshId, mesh);
+        this.invalidateAggregateMeshStatus(meshId);
         return true;
     }
 
@@ -1534,6 +3102,567 @@ export class DaemonCommandRouter {
         }
     }
 
+
+    private buildRefineJobKey(meshId: string, nodeId: string): string {
+        return `${meshId}:${nodeId}`;
+    }
+
+    private buildRefineJobHandle(args: {
+        meshId: string;
+        nodeId: string;
+        node?: any;
+        status?: MeshRefineAsyncJobStatus;
+        startedAt?: string;
+        completedAt?: string;
+        jobId?: string;
+        interactionId?: string;
+        retryOfJobId?: string;
+    }): MeshRefineJobHandle {
+        return {
+            success: true,
+            async: true,
+            status: args.status || 'accepted',
+            jobId: args.jobId || `refine_${createInteractionId()}`,
+            interactionId: args.interactionId || createInteractionId(),
+            meshId: args.meshId,
+            nodeId: args.nodeId,
+            targetNodeId: args.nodeId,
+            targetDaemonId: readStringValue(args.node?.daemonId),
+            workspace: readStringValue(args.node?.workspace),
+            startedAt: args.startedAt || new Date().toISOString(),
+            ...(args.completedAt ? { completedAt: args.completedAt } : {}),
+            ...(args.retryOfJobId ? { retryOfJobId: args.retryOfJobId } : {}),
+            eventDelivery: { pendingEvents: true, ledger: true },
+            evidence: {
+                pendingEventsCommand: 'get_pending_mesh_events',
+                ledgerCommand: 'get_mesh_ledger_slice',
+                taskHistoryKind: args.status === 'completed' ? 'task_completed' : args.status === 'failed' ? 'task_failed' : 'task_dispatched',
+            },
+        };
+    }
+
+    private queueRefineJobEvent(event: 'refine:accepted' | 'refine:completed' | 'refine:failed', handle: MeshRefineJobHandle, result?: Record<string, unknown>): void {
+        const metadataEvent = {
+            source: 'refine_mesh_node_async_job',
+            jobId: handle.jobId,
+            interactionId: handle.interactionId,
+            meshId: handle.meshId,
+            nodeId: handle.targetNodeId,
+            targetDaemonId: handle.targetDaemonId,
+            workspace: handle.workspace,
+            status: handle.status,
+            startedAt: handle.startedAt,
+            completedAt: handle.completedAt,
+            retryOfJobId: handle.retryOfJobId,
+            ...(result ? { result } : {}),
+        };
+        const eventPayload = {
+            event,
+            meshId: handle.meshId,
+            nodeLabel: handle.targetNodeId,
+            nodeId: handle.targetNodeId,
+            workspace: handle.workspace,
+            metadataEvent,
+            queuedAt: Date.now(),
+        };
+        if (typeof this.deps.instanceManager?.getByCategory === 'function') {
+            const forwarded = handleMeshForwardEvent(
+                { instanceManager: this.deps.instanceManager } as any,
+                {
+                    event,
+                    meshId: handle.meshId,
+                    nodeId: handle.targetNodeId,
+                    workspace: handle.workspace,
+                    jobId: handle.jobId,
+                    interactionId: handle.interactionId,
+                    status: handle.status,
+                    targetDaemonId: handle.targetDaemonId,
+                    startedAt: handle.startedAt,
+                    completedAt: handle.completedAt,
+                    retryOfJobId: handle.retryOfJobId,
+                    ...(result ? { result } : {}),
+                },
+            );
+            if (forwarded?.success === true) return;
+            LOG.warn('Mesh', `[Refinery] Failed to forward async refine event ${event}: ${forwarded?.error || 'unknown error'}`);
+        }
+        queuePendingMeshCoordinatorEvent(eventPayload);
+    }
+
+    private async appendRefineJobLedger(kind: 'task_dispatched' | 'task_completed' | 'task_failed', handle: MeshRefineJobHandle, result?: Record<string, unknown>): Promise<void> {
+        try {
+            const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+            appendLedgerEntry(handle.meshId, {
+                kind,
+                nodeId: handle.targetNodeId,
+                payload: {
+                    source: 'refine_mesh_node_async_job',
+                    refineJob: {
+                        jobId: handle.jobId,
+                        interactionId: handle.interactionId,
+                        status: handle.status,
+                        meshId: handle.meshId,
+                        nodeId: handle.targetNodeId,
+                        targetDaemonId: handle.targetDaemonId,
+                        workspace: handle.workspace,
+                        startedAt: handle.startedAt,
+                        completedAt: handle.completedAt,
+                        retryOfJobId: handle.retryOfJobId,
+                    },
+                    async: true,
+                    retryOfJobId: handle.retryOfJobId,
+                    ...(result ? {
+                        success: result.success === true,
+                        result,
+                        finalBranchConvergenceState: result.finalBranchConvergenceState,
+                    } : {}),
+                },
+            });
+        } catch (e: any) {
+            LOG.warn('Mesh', `[Refinery] Failed to append async refine ledger entry: ${e?.message || e}`);
+        }
+    }
+
+    private async executeMeshRefineNodeSynchronously(meshId: string, nodeId: string, args: any): Promise<CommandRouterResult> {
+        const refineStages: Array<Record<string, unknown>> = [];
+        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`, refineStages };
+
+            if (!node.isLocalWorktree || !node.workspace) {
+                return { success: false, error: `Refinery requires a local worktree node`, refineStages };
+            }
+
+            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', refineStages };
+
+            const { execFile } = await import('node:child_process');
+            const { promisify } = await import('node:util');
+            const execFileAsync = promisify(execFile);
+
+            const resolveStarted = Date.now();
+            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', refineStages };
+
+            const { stdout: baseBranchStdout } = await execFileAsync('git', ['branch', '--show-current'], { cwd: repoRoot, encoding: 'utf8' });
+            const baseBranch = baseBranchStdout.trim();
+            const { stdout: baseHeadStdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repoRoot, encoding: 'utf8' });
+            const { stdout: branchHeadStdout } = await execFileAsync('git', ['rev-parse', branch], { cwd: node.workspace, encoding: 'utf8' });
+            const baseHead = baseHeadStdout.trim();
+            const branchHead = branchHeadStdout.trim();
+            recordMeshRefineStage(refineStages, 'resolve_refs', 'passed', resolveStarted, { branch, baseBranch, baseHead, branchHead });
+
+            const validationStarted = Date.now();
+            const validationSummary = await runMeshRefineValidationGate(mesh, node.workspace);
+            recordMeshRefineStage(
+                refineStages,
+                'validation',
+                validationSummary.status === 'passed' ? 'passed' : validationSummary.status === 'failed' ? 'failed' : 'skipped',
+                validationStarted,
+                { validationStatus: validationSummary.status, commandsRun: validationSummary.commandsRun.length },
+            );
+            if (validationSummary.status === 'failed') {
+                return {
+                    success: false,
+                    code: validationSummary.failureCode || 'validation_failed',
+                    convergenceStatus: 'blocked_review',
+                    error: validationSummary.failureCode === 'missing_dependencies'
+                        ? 'Refinery validation dependencies are missing; merge/refine was not attempted. Configure validation.bootstrapCommands if Refinery should bootstrap dependencies before validation.'
+                        : validationSummary.failureCode === 'dependency_bootstrap_failed'
+                            ? 'Refinery dependency/bootstrap command failed; merge/refine was not attempted.'
+                            : 'Refinery validation gate failed; merge/refine was not attempted.',
+                    branch,
+                    into: baseBranch,
+                    validationSummary,
+                    refineStages,
+                    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,
+                    refineStages,
+                    finalBranchConvergenceState: {
+                branch,
+                baseBranch,
+                merged: false,
+                removed: false,
+                validation: 'unavailable',
+                status: 'blocked_review',
+                    },
+                };
+            }
+
+            const patchEquivalenceStarted = Date.now();
+            const patchEquivalence = await runMeshRefinePatchEquivalenceGate(repoRoot, baseHead, branchHead);
+            recordMeshRefineStage(refineStages, 'patch_equivalence', patchEquivalence.status, patchEquivalenceStarted, {
+                equivalent: patchEquivalence.equivalent,
+                expectedPatchId: patchEquivalence.expectedPatchId,
+                actualPatchId: patchEquivalence.actualPatchId,
+                error: patchEquivalence.error,
+                actionableHint: patchEquivalence.actionableHint,
+            });
+            if (!patchEquivalence.equivalent) {
+                return {
+                    success: false,
+                    code: 'patch_equivalence_failed',
+                    convergenceStatus: 'blocked_review',
+                    error: 'Refinery patch-equivalence preflight failed; merge/refine was not attempted.',
+                    branch,
+                    into: baseBranch,
+                    validationSummary,
+                    patchEquivalence,
+                    refineStages,
+                    finalBranchConvergenceState: {
+                branch,
+                baseBranch,
+                merged: false,
+                removed: false,
+                validation: 'passed',
+                patchEquivalence: 'failed',
+                status: 'blocked_review',
+                    },
+                };
+            }
+
+            const submoduleReachabilityStarted = Date.now();
+            const autoPublishSubmoduleMainCommits = resolveRefineryAutoPublishSubmoduleMainCommits(mesh, node.workspace);
+            const submoduleReachability = await runMeshRefineSubmoduleReachabilityGate(repoRoot, patchEquivalence.mergedTree || branchHead, {
+                allowAutoPublishSubmoduleMainCommits: autoPublishSubmoduleMainCommits.enabled,
+                autoPublishPolicySource: autoPublishSubmoduleMainCommits.source,
+                worktreeRoot: node.workspace,
+            });
+            recordMeshRefineStage(refineStages, 'submodule_reachability', submoduleReachability.status, submoduleReachabilityStarted, {
+                checked: submoduleReachability.checked,
+                autoPublishAllowed: submoduleReachability.autoPublishAllowed,
+                autoPublishPolicySource: submoduleReachability.autoPublishPolicySource,
+                autoPublished: submoduleReachability.entries
+                    .filter(entry => entry.autoPublishAttempted)
+                    .map(entry => ({
+                        path: entry.path,
+                        commit: entry.commit,
+                        remote: entry.remote,
+                        remoteUrl: entry.remoteUrl,
+                        remoteMainBranch: entry.remoteMainBranch,
+                        refspec: entry.autoPublishRefspec,
+                        succeeded: entry.autoPublishSucceeded,
+                        verified: entry.autoPublishVerified,
+                        remoteMainReachable: entry.remoteMainReachable,
+                        error: entry.error,
+                    })),
+                autoPublishSkipped: submoduleReachability.entries
+                    .filter(entry => entry.autoPublishAllowed === true && entry.autoPublishAttempted !== true)
+                    .map(entry => ({
+                        path: entry.path,
+                        commit: entry.commit,
+                        remote: entry.remote,
+                        remoteUrl: entry.remoteUrl,
+                        remoteMainBranch: entry.remoteMainBranch,
+                        reason: entry.autoPublishSkippedReason || entry.error || 'auto-publish was allowed but no publish attempt was possible',
+                    })),
+                unreachable: submoduleReachability.unreachable.map(entry => ({
+                    path: entry.path,
+                    commit: entry.commit,
+                    publishRequired: entry.publishRequired === true,
+                    autoPublishAllowed: entry.autoPublishAllowed,
+                    autoPublishAttempted: entry.autoPublishAttempted,
+                    autoPublishSucceeded: entry.autoPublishSucceeded,
+                        autoPublishVerified: entry.autoPublishVerified,
+                        autoPublishRefspec: entry.autoPublishRefspec,
+                        autoPublishSkippedReason: entry.autoPublishSkippedReason,
+                        remote: entry.remote,
+                    remoteUrl: entry.remoteUrl,
+                    remoteReachable: entry.remoteReachable,
+                    remoteMainBranch: entry.remoteMainBranch,
+                    remoteMainReachable: entry.remoteMainReachable,
+                    error: entry.error,
+                })),
+                error: submoduleReachability.error,
+            });
+            if (submoduleReachability.status === 'failed') {
+                const nextStep = buildSubmodulePublishRequiredNextStep(submoduleReachability.unreachable);
+                return {
+                    success: false,
+                    code: 'submodule_reachability_failed',
+                    convergenceStatus: 'blocked_review',
+                    publishRequired: true,
+                    blockedReason: 'submodule_publish_required',
+                    error: 'Refinery submodule reachability preflight failed because one or more submodule gitlink commits are not reachable from their configured remote main branch; merge/refine cleanup was not attempted.',
+                    nextStep,
+                    nextSteps: [
+                        'Ask the user for explicit approval before pushing or publishing any submodule commit.',
+                        'Push/publish each unreachable submodule commit to the configured submodule remote main branch shown in the evidence.',
+                        'Rerun mesh_refine_node after remote reachability is confirmed.',
+                        'Do not merge the root branch until every submodule gitlink commit is reachable from submodule origin/main.',
+                    ],
+                    unreachableSubmoduleCommits: submoduleReachability.unreachable.map(entry => ({
+                        path: entry.path,
+                        commit: entry.commit,
+                        remote: entry.remote,
+                        remoteUrl: entry.remoteUrl,
+                        remoteReachable: entry.remoteReachable,
+                        remoteMainBranch: entry.remoteMainBranch,
+                        remoteMainReachable: entry.remoteMainReachable,
+                        autoPublishAllowed: entry.autoPublishAllowed,
+                        autoPublishAttempted: entry.autoPublishAttempted,
+                        autoPublishSucceeded: entry.autoPublishSucceeded,
+                        autoPublishVerified: entry.autoPublishVerified,
+                        autoPublishRefspec: entry.autoPublishRefspec,
+                        autoPublishSkippedReason: entry.autoPublishSkippedReason,
+                        error: entry.error,
+                    })),
+                    branch,
+                    into: baseBranch,
+                    validationSummary,
+                    patchEquivalence,
+                    submoduleReachability,
+                    refineStages,
+                    finalBranchConvergenceState: {
+                branch,
+                baseBranch,
+                merged: false,
+                removed: false,
+                validation: 'passed',
+                patchEquivalence: 'passed',
+                submoduleReachability: 'failed',
+                status: 'blocked_review',
+                reason: 'submodule_publish_required',
+                nextStep,
+                    },
+                };
+            }
+
+            let mergeResult: Record<string, unknown> | undefined;
+            const mergeStarted = Date.now();
+            try {
+                const result = await execFileAsync('git', ['merge', '--no-ff', branch, '-m', `Auto-merge branch '${branch}' via Refinery`], { cwd: repoRoot, encoding: 'utf8' });
+                mergeResult = {
+                    stdout: truncateValidationOutput(result.stdout),
+                    stderr: truncateValidationOutput(result.stderr),
+                    durationMs: Date.now() - mergeStarted,
+                };
+                recordMeshRefineStage(refineStages, 'merge', 'passed', mergeStarted, mergeResult);
+            } catch (e: any) {
+                recordMeshRefineStage(refineStages, 'merge', 'failed', mergeStarted, {
+                    error: e?.message || String(e),
+                    stdout: truncateValidationOutput(e?.stdout),
+                    stderr: truncateValidationOutput(e?.stderr),
+                });
+                return {
+                    success: false,
+                    error: `Merge failed (conflicts?): ${e.message}`,
+                    validationSummary,
+                    patchEquivalence,
+                    refineStages,
+                    finalBranchConvergenceState: {
+                branch,
+                baseBranch,
+                merged: false,
+                removed: false,
+                validation: 'passed',
+                patchEquivalence: 'passed',
+                status: 'not_mergeable',
+                    },
+                };
+            }
+
+            const submoduleAlignmentStarted = Date.now();
+            const submoduleAlignment = await alignRefinerySubmodulesAfterMerge(repoRoot, baseHead, 'HEAD', {
+                submoduleIgnorePaths: Array.isArray(sourceNode?.policy?.submoduleIgnorePaths)
+                    ? sourceNode.policy.submoduleIgnorePaths.filter((value: unknown): value is string => typeof value === 'string')
+                    : undefined,
+            });
+            if (submoduleAlignment.status !== 'skipped') {
+                recordMeshRefineStage(refineStages, 'submodule_alignment', submoduleAlignment.status, submoduleAlignmentStarted, {
+                    changedGitlinkPaths: submoduleAlignment.changedGitlinkPaths,
+                    outOfSyncPaths: submoduleAlignment.outOfSyncPaths,
+                    updatedPaths: submoduleAlignment.updatedPaths,
+                    verifiedPaths: submoduleAlignment.verifiedPaths,
+                    command: submoduleAlignment.command,
+                    error: submoduleAlignment.error,
+                });
+            }
+            if (submoduleAlignment.status === 'failed') {
+                return {
+                    success: false,
+                    code: 'post_merge_submodule_alignment_failed',
+                    error: 'Refinery merge completed but post-merge submodule checkout alignment failed; run the reported git submodule update command and re-check base workspace status.',
+                    merged: true,
+                    branch,
+                    into: baseBranch,
+                    validationSummary,
+                    patchEquivalence,
+                    submoduleReachability,
+                    submoduleAlignment,
+                    mergeResult,
+                    refineStages,
+                    finalBranchConvergenceState: {
+                branch: baseBranch,
+                mergedBranch: branch,
+                baseBranch,
+                merged: true,
+                removed: false,
+                validation: 'passed',
+                patchEquivalence: 'passed',
+                submoduleReachability: 'passed',
+                submoduleAlignment: 'failed',
+                status: 'post_merge_alignment_failed',
+                nextStep: submoduleAlignment.command || 'Run git submodule update --init --recursive for the reported path(s), then re-check base workspace status.',
+                    },
+                };
+            }
+
+            const cleanupStarted = Date.now();
+            const removeResult = await this.execute('remove_mesh_node', {
+                meshId,
+                nodeId,
+                sessionCleanupMode: 'preserve',
+                inlineMesh: args?.inlineMesh,
+            });
+            recordMeshRefineStage(refineStages, 'cleanup', removeResult?.success === false ? 'failed' : 'passed', cleanupStarted, {
+                removed: removeResult?.removed,
+                code: removeResult?.code,
+                error: removeResult?.error,
+            });
+
+            let ledgerError: string | undefined;
+            const ledgerStarted = Date.now();
+            try {
+                const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+                appendLedgerEntry(meshId, {
+                    kind: 'node_removed',
+                    nodeId,
+                    payload: { refined: true, mergedBranch: branch, into: baseBranch, validationSummary, patchEquivalence, submoduleReachability, submoduleAlignment },
+                });
+                recordMeshRefineStage(refineStages, 'ledger', 'passed', ledgerStarted);
+            } catch (e: any) {
+                ledgerError = e?.message || String(e);
+                recordMeshRefineStage(refineStages, 'ledger', 'failed', ledgerStarted, { error: ledgerError });
+            }
+
+            const finalBranchConvergenceState = {
+                branch: baseBranch,
+                mergedBranch: branch,
+                baseBranch,
+                merged: true,
+                removed: removeResult?.success !== false,
+                validation: 'passed',
+                patchEquivalence: 'passed',
+                submoduleAlignment: submoduleAlignment.status,
+                status: removeResult?.success === false ? 'merged_cleanup_failed' : 'merged',
+            };
+
+            if (removeResult?.success === false) {
+                return {
+                    success: false,
+                    code: 'cleanup_failed',
+                    error: 'Refinery merge completed but worktree cleanup failed; manual cleanup/retry is required.',
+                    merged: true,
+                    branch,
+                    into: baseBranch,
+                    removeResult,
+                    validationSummary,
+                    patchEquivalence,
+                    submoduleReachability,
+                    submoduleAlignment,
+                    mergeResult,
+                    refineStages,
+                    ...(ledgerError ? { ledgerError } : {}),
+                    finalBranchConvergenceState,
+                };
+            }
+
+            return {
+                success: true,
+                merged: true,
+                branch,
+                into: baseBranch,
+                removeResult,
+                validationSummary,
+                patchEquivalence,
+                submoduleReachability,
+                submoduleAlignment,
+                mergeResult,
+                refineStages,
+                ...(ledgerError ? { ledgerError } : {}),
+                finalBranchConvergenceState,
+            };
+        } catch (e: any) {
+            return { success: false, error: e.message, refineStages };
+        }
+    }
+
+    private async finishMeshRefineJob(handle: MeshRefineJobHandle, args: any): Promise<void> {
+        const key = this.buildRefineJobKey(handle.meshId, handle.targetNodeId);
+        let result: Record<string, unknown>;
+        try {
+            result = await this.executeMeshRefineNodeSynchronously(handle.meshId, handle.targetNodeId, args) as Record<string, unknown>;
+        } catch (e: any) {
+            result = { success: false, error: e?.message || String(e) };
+        }
+        const completedAt = new Date().toISOString();
+        const terminalHandle = this.buildRefineJobHandle({
+            meshId: handle.meshId,
+            nodeId: handle.targetNodeId,
+            status: result.success === true ? 'completed' : 'failed',
+            startedAt: handle.startedAt,
+            completedAt,
+            jobId: handle.jobId,
+            interactionId: handle.interactionId,
+            retryOfJobId: handle.retryOfJobId,
+            node: { daemonId: handle.targetDaemonId, workspace: handle.workspace },
+        });
+        const terminal: MeshRefineTerminalJob = { ...terminalHandle, result };
+        this.terminalRefineJobs.set(key, terminal);
+        this.runningRefineJobs.delete(key);
+        this.invalidateAggregateMeshStatus(handle.meshId);
+        await this.appendRefineJobLedger(result.success === true ? 'task_completed' : 'task_failed', terminalHandle, result);
+        this.queueRefineJobEvent(result.success === true ? 'refine:completed' : 'refine:failed', terminalHandle, result);
+    }
+
+    private async startMeshRefineJob(meshId: string, nodeId: string, args: any): Promise<CommandRouterResult> {
+        const key = this.buildRefineJobKey(meshId, nodeId);
+        const running = this.runningRefineJobs.get(key);
+        if (running) return { ...running, duplicate: true };
+        const terminal = this.terminalRefineJobs.get(key);
+
+        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 handle = this.buildRefineJobHandle({ meshId, nodeId, node, retryOfJobId: terminal?.jobId });
+        this.runningRefineJobs.set(key, handle);
+        await this.appendRefineJobLedger('task_dispatched', handle);
+        this.queueRefineJobEvent('refine:accepted', handle);
+
+        setImmediate(() => {
+            void this.finishMeshRefineJob(handle, args);
+        });
+
+        return handle;
+    }
+
     // ─── Daemon-level command core ───────────────────
 
     /**
@@ -1548,13 +3677,35 @@ export class DaemonCommandRouter {
             }
 
             case 'get_pending_mesh_events': {
-                const events = drainPendingMeshCoordinatorEvents();
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                // (B3) Respect coordinatorDaemonId when the caller declares it
+                // so unicast events route to the right coordinator instead of
+                // being silently consumed by the first drainer.
+                const coordinatorDaemonId = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
+                    ? args.coordinatorDaemonId.trim()
+                    : undefined;
+                const events = drainPendingMeshCoordinatorEvents(meshId || undefined, coordinatorDaemonId);
                 return { success: true, events };
             }
 
+            case 'interactive_prompt_response': {
+                const sessionId = typeof args?.targetSessionId === 'string' && args.targetSessionId.trim()
+                    ? args.targetSessionId.trim()
+                    : typeof args?.sessionId === 'string' && args.sessionId.trim()
+                        ? args.sessionId.trim()
+                        : '';
+                if (!sessionId) return { success: false, error: 'targetSessionId required' };
+                const response = normalizeInteractivePromptResponse(args?.response ?? args);
+                const instance = this.deps.instanceManager.getInstance(sessionId);
+                if (!instance) return { success: false, error: `No running instance for session ${sessionId}` };
+                this.deps.instanceManager.sendEvent(sessionId, 'interactive_prompt_response', response);
+                return { success: true };
+            }
+
             case 'launch_cli':
             case 'stop_cli':
             case 'set_cli_view_mode':
+            case 'record_provider_pty':
             case 'agent_command': {
                 return this.deps.cliManager.handleCliCommand(cmd, args);
             }
@@ -1750,7 +3901,7 @@ export class DaemonCommandRouter {
                         : '';
                 const providerMeta = this.deps.providerLoader.resolve?.(providerType) || this.deps.providerLoader.getMeta(providerType);
                 const { sessions: historySessions, hasMore, source } = listProviderHistorySessions(providerType, {
-                    canonicalHistory: providerMeta?.canonicalHistory,
+                    canonicalHistory: providerMeta?.nativeHistory,
                     offset,
                     limit,
                     historyBehavior: providerMeta?.historyBehavior,
@@ -1972,6 +4123,151 @@ export class DaemonCommandRouter {
                 };
             }
 
+            // Session-info popup data. Aggregates whatever the daemon knows
+            // about a single live session into one envelope so the dashboard
+            // doesn't need to stitch together status + coordinator registry +
+            // session registry on the client. Includes the actual system
+            // prompt that was injected at launch when the session is a mesh
+            // coordinator — that's the "what prompt did the agent see?"
+            // question the info-icon dialog is meant to answer.
+            case 'get_session_info': {
+                const sessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim()
+                    : typeof args?.sessionId === 'string' ? args.sessionId.trim() : '';
+                if (!sessionId) return { success: false, error: 'targetSessionId required' };
+                // Fetch both lookups up front. We used to bail with "Session not
+                // found" when sessionRegistry forgot the SID (auto-cleanup,
+                // daemon restart with the session not yet restored, etc), which
+                // hid the coordinator-side metadata even though the
+                // coordinator-registry still has it. Now we return whichever
+                // side we have. The dashboard renders "no coordinator-specific
+                // prompt" only when *neither* side knows the session.
+                const target = this.deps.sessionRegistry.get(sessionId);
+                const coord = getCoordinatorForSession(sessionId);
+                if (!target && !coord) return { success: false, error: 'Session not found', sessionId };
+                const adapter = target
+                    ? this.deps.cliManager.findAdapter(target.providerType, { instanceKey: sessionId })?.adapter
+                    : undefined;
+                const runtimeMeta = (adapter && typeof (adapter as any).getRuntimeMetadata === 'function')
+                    ? (adapter as any).getRuntimeMetadata()
+                    : undefined;
+                const providerType = target?.providerType || coord?.cliType || '';
+                const providerMetaForSession = providerType
+                    ? this.deps.providerLoader.resolve?.(providerType) || this.deps.providerLoader.getMeta(providerType)
+                    : undefined;
+                return {
+                    success: true,
+                    session: {
+                        sessionId,
+                        providerType,
+                        providerName: providerMetaForSession?.name,
+                        transport: target?.transport,
+                        workspace: (target as any)?.workspace || coord?.workspace,
+                        spawnedAtMs: (target as any)?.spawnedAtMs || coord?.startedAt,
+                        providerSessionId: (target as any)?.providerSessionId,
+                        runtimeMetadata: runtimeMeta,
+                    },
+                    coordinator: coord ? {
+                        meshId: coord.meshId,
+                        startedAt: coord.startedAt,
+                        cliType: coord.cliType,
+                        systemPrompt: coord.systemPrompt,
+                        extraSystemPrompt: coord.extraSystemPrompt,
+                        injection: coord.injection,
+                        mcpConfigPath: coord.mcpConfigPath,
+                    } : null,
+                };
+            }
+
+            case 'get_spec_debug': {
+                const sessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim()
+                    : typeof args?.sessionId === 'string' ? args.sessionId.trim() : '';
+                if (!sessionId) return { success: false, error: 'targetSessionId required' };
+                const target = this.deps.sessionRegistry.get(sessionId);
+                if (!target) return { success: false, error: 'Session not found', sessionId };
+                const adapterObj = this.deps.cliManager.findAdapter(target.providerType, { instanceKey: sessionId })?.adapter;
+                const snapshot = adapterObj
+                    ? (typeof (adapterObj as any).getDebugSnapshot === 'function'
+                        ? (adapterObj as any).getDebugSnapshot()
+                        : typeof (adapterObj as any).getDebugState === 'function'
+                            ? (adapterObj as any).getDebugState()
+                            : null)
+                    : null;
+                return {
+                    success: true,
+                    sessionId,
+                    providerType: target.providerType,
+                    isSpecProvider: snapshot !== null,
+                    snapshot,
+                };
+            }
+
+            // ── User-level coordinator-prompt files (~/.adhdev/coordinator-prompts/).
+            //    These live on this daemon's filesystem and never sync to the
+            //    cloud / other daemons — they're per-machine config. The
+            //    Settings page in the dashboard reads/writes via these two
+            //    commands instead of going through fs from the browser.
+            case 'list_coordinator_prompts': {
+                const fs = await import('node:fs');
+                const path = await import('node:path');
+                const os = await import('node:os');
+                const dir = path.join(os.homedir(), '.adhdev', 'coordinator-prompts');
+                const entries: Record<string, { override: string; append: string }> = {};
+                try {
+                    if (fs.existsSync(dir)) {
+                        for (const name of fs.readdirSync(dir)) {
+                            // Bucket files into <key>.{md|append.md}; ignore others
+                            // so a stray README or .DS_Store doesn't show up.
+                            const matchOverride = name.match(/^([a-zA-Z0-9_.-]+)\.md$/);
+                            const matchAppend = name.match(/^([a-zA-Z0-9_.-]+)\.append\.md$/);
+                            // append-pattern wins when both match (file is `.append.md`).
+                            const m = matchAppend || matchOverride;
+                            if (!m) continue;
+                            const isAppend = !!matchAppend;
+                            const key = m[1];
+                            const full = path.join(dir, name);
+                            let content = '';
+                            try { content = fs.readFileSync(full, 'utf8'); } catch { /* skip */ }
+                            if (!entries[key]) entries[key] = { override: '', append: '' };
+                            if (isAppend) entries[key].append = content;
+                            else entries[key].override = content;
+                        }
+                    }
+                } catch (error: any) {
+                    return { success: false, error: error?.message || String(error) };
+                }
+                return { success: true, dir, entries };
+            }
+
+            case 'write_coordinator_prompt': {
+                const fs = await import('node:fs');
+                const path = await import('node:path');
+                const os = await import('node:os');
+                const key = typeof args?.key === 'string' ? args.key.trim() : '';
+                const kind = args?.kind === 'append' ? 'append' : 'override';
+                const content = typeof args?.content === 'string' ? args.content : '';
+                // Whitelist key chars so a malicious caller can't write
+                // ../../etc/passwd. Same charset readUserPromptFile accepts.
+                if (!key || !/^[a-zA-Z0-9_.-]+$/.test(key)) {
+                    return { success: false, error: 'key must match [a-zA-Z0-9_.-]+' };
+                }
+                const dir = path.join(os.homedir(), '.adhdev', 'coordinator-prompts');
+                const filename = kind === 'append' ? `${key}.append.md` : `${key}.md`;
+                const full = path.join(dir, filename);
+                try {
+                    fs.mkdirSync(dir, { recursive: true });
+                    if (content.trim()) {
+                        fs.writeFileSync(full, content, { encoding: 'utf8', mode: 0o600 });
+                    } else if (fs.existsSync(full)) {
+                        // Empty content = "reset to default" — delete the file
+                        // so the daemon's readUserPromptFile path falls through.
+                        fs.unlinkSync(full);
+                    }
+                    return { success: true, path: full, kind, key };
+                } catch (error: any) {
+                    return { success: false, error: error?.message || String(error) };
+                }
+            }
+
             case 'mark_session_seen': {
                 const sessionId = args?.sessionId;
                 if (!sessionId || typeof sessionId !== 'string') {
@@ -2150,46 +4446,305 @@ export class DaemonCommandRouter {
                 }
             }
 
-            case 'get_mesh': {
+            case 'get_mesh': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+                if (!meshRecord?.mesh) return { success: false, error: 'Mesh not found' };
+
+                const requireDirectPeerTruth = args?.requireDirectPeerTruth === true;
+                const directTruth = await hydrateInlineMeshDirectTruth({
+                    mesh: meshRecord.mesh,
+                    meshSource: meshRecord.source,
+                    dispatchMeshCommand: this.deps.dispatchMeshCommand,
+                    statusInstanceId: this.deps.statusInstanceId,
+                    localMachineId: loadConfig().machineId || '',
+                });
+                const directTruthSatisfied = meshRecord.source !== 'inline_bootstrap' || directTruth.directEvidenceCount > 0;
+                const sourceOfTruth = {
+                    membership: meshRecord.source === 'inline_cache'
+                        ? 'coordinator_inline_mesh_cache'
+                        : meshRecord.source === 'local_config'
+                            ? 'local_mesh_config'
+                            : 'inline_bootstrap_snapshot',
+                    coordinatorOwnsLiveTruth: directTruthSatisfied,
+                    directPeerTruth: {
+                        required: requireDirectPeerTruth,
+                        satisfied: directTruthSatisfied,
+                        directEvidenceCount: directTruth.directEvidenceCount,
+                        localConfirmedCount: directTruth.localConfirmedCount,
+                        peerAttemptedCount: directTruth.peerAttemptedCount,
+                        peerConfirmedCount: directTruth.peerConfirmedCount,
+                        unavailableNodeIds: directTruth.unavailableNodeIds,
+                    },
+                };
+                if (requireDirectPeerTruth && !directTruthSatisfied) {
+                    return {
+                        success: false,
+                        code: 'mesh_direct_peer_truth_unavailable',
+                        error: 'Selected coordinator could not confirm direct mesh truth yet. Bootstrap inventory stays unavailable until direct get_mesh probes succeed.',
+                        sourceOfTruth,
+                    };
+                }
+                return { success: true, mesh: meshRecord.mesh, sourceOfTruth };
+            }
+
+            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 meshHost = args?.meshHost && typeof args.meshHost === 'object' && !Array.isArray(args.meshHost)
+                        ? args.meshHost
+                        : undefined;
+                    const mesh = createMesh({ name, repoIdentity, repoRemoteUrl, defaultBranch, policy: args?.policy, meshHost });
+                    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 (args?.meshHost && typeof args.meshHost === 'object' && !Array.isArray(args.meshHost)) patch.meshHost = args.meshHost;
+                    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);
+                    this.invalidateAggregateMeshStatus(meshId);
+                    return { success: true, mesh };
+                } catch (e: any) {
+                    return { success: false, error: e.message };
+                }
+            }
+
+            case 'get_mesh_host_pairing': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+                const mesh = meshRecord?.mesh;
+                if (!mesh) return { success: false, error: 'Mesh not found' };
+                const meshHost = resolveMeshHostStatus(mesh);
+                const pairingStatus = meshHost.pairing?.status || 'not_configured';
+                return {
+                    success: true,
+                    code: pairingStatus === 'not_configured' ? 'mesh_host_pairing_not_configured' : 'mesh_host_pairing_pending',
+                    meshId,
+                    hostAddress: meshHost.hostAddress,
+                    meshHost,
+                    manualPairing: {
+                        status: pairingStatus,
+                        joinImplemented: true,
+                        protocol: 'standalone_command_direct_v1',
+                        description: 'Standalone manual pairing can save address/token metadata, apply a host join over direct standalone command HTTP or injected mesh command dispatch, and check persisted status. P2P signaling remains outside this slice.',
+                    },
+                };
+            }
+
+            case 'configure_mesh_host_pairing': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const hostAddress = typeof args?.hostAddress === 'string' ? args.hostAddress.trim() : '';
+                const token = typeof args?.token === 'string' ? args.token.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                if (!hostAddress || !token) return { success: false, error: 'hostAddress and token required' };
+                try {
+                    const { configureMeshHostPairing } = await import('../config/mesh-config.js');
+                    const configured = configureMeshHostPairing(meshId, { hostAddress, token });
+                    if (!configured) return { success: false, error: 'Mesh not found' };
+                    this.inlineMeshCache.set(meshId, configured.mesh);
+                    const meshHost = resolveMeshHostStatus(configured.mesh);
+                    return {
+                        success: true,
+                        code: 'mesh_host_pairing_pending',
+                        meshId,
+                        hostAddress: configured.hostAddress,
+                        meshHost,
+                        manualPairing: {
+                            status: meshHost.pairing?.status || 'pairing',
+                            joinImplemented: true,
+                            protocol: 'standalone_command_direct_v1',
+                            description: 'Manual Mesh Host pairing config was saved locally. Use join_mesh_host_pairing to apply it to the host. Raw token was not persisted.',
+                        },
+                    };
+                } catch (e: any) {
+                    return { success: false, code: 'mesh_host_pairing_invalid', meshId, hostAddress, error: e.message };
+                }
+            }
+
+            case 'create_mesh_host_pairing_token': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                try {
+                    const { createMeshHostPairingToken } = await import('../config/mesh-config.js');
+                    const created = createMeshHostPairingToken(meshId, {
+                        token: typeof args?.token === 'string' ? args.token : undefined,
+                        expiresAt: typeof args?.expiresAt === 'string' ? args.expiresAt : undefined,
+                    });
+                    if (!created) return { success: false, error: 'Mesh not found' };
+                    this.inlineMeshCache.set(meshId, created.mesh);
+                    this.invalidateAggregateMeshStatus(meshId);
+                    return {
+                        success: true,
+                        code: 'mesh_host_pairing_token_created',
+                        meshId,
+                        token: created.token,
+                        tokenId: created.tokenId,
+                        expiresAt: created.expiresAt,
+                        meshHost: resolveMeshHostStatus(created.mesh),
+                        warning: 'Raw token is returned once and is not persisted; share it with member daemons over a trusted channel.',
+                    };
+                } catch (e: any) {
+                    return { success: false, code: 'mesh_host_pairing_token_invalid', meshId, error: e.message };
+                }
+            }
+
+            case 'apply_mesh_host_join': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const token = typeof args?.token === 'string' ? args.token.trim() : '';
+                const memberNode = args?.memberNode && typeof args.memberNode === 'object' && !Array.isArray(args.memberNode)
+                    ? args.memberNode
+                    : null;
                 if (!meshId) return { success: false, error: 'meshId required' };
-                const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
-                if (meshRecord?.mesh) return { success: true, mesh: meshRecord.mesh };
-                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' };
+                if (!token || !memberNode) return { success: false, error: 'token and memberNode required' };
                 try {
-                    const { createMesh } = await import('../config/mesh-config.js');
-                    const mesh = createMesh({ name, repoIdentity, repoRemoteUrl, defaultBranch, policy: args?.policy });
-                    return { success: true, mesh };
+                    const { applyMeshHostJoinRequest } = await import('../config/mesh-config.js');
+                    const applied = applyMeshHostJoinRequest(meshId, {
+                        token,
+                        memberNode: memberNode as any,
+                        memberMeshId: typeof args?.memberMeshId === 'string' ? args.memberMeshId : undefined,
+                    });
+                    if (!applied) return { success: false, error: 'Mesh not found' };
+                    if (!applied.accepted) {
+                        return {
+                            success: false,
+                            code: 'mesh_host_join_rejected',
+                            meshId,
+                            tokenId: applied.tokenId,
+                            meshHost: applied.meshHost ? resolveMeshHostStatus({ meshHost: applied.meshHost }) : undefined,
+                            error: applied.reason,
+                        };
+                    }
+                    this.inlineMeshCache.set(meshId, applied.mesh);
+                    this.invalidateAggregateMeshStatus(meshId);
+                    try {
+                        const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+                        appendLedgerEntry(meshId, {
+                            kind: 'node_joined',
+                            nodeId: applied.node.id,
+                            payload: { role: 'member', tokenId: applied.tokenId, workspace: applied.node.workspace },
+                        });
+                    } catch { /* ledger append is best-effort */ }
+                    return {
+                        success: true,
+                        code: 'mesh_host_join_accepted',
+                        meshId,
+                        node: applied.node,
+                        tokenId: applied.tokenId,
+                        meshHost: resolveMeshHostStatus(applied.mesh),
+                    };
                 } catch (e: any) {
-                    return { success: false, error: e.message };
+                    return { success: false, code: 'mesh_host_join_failed', meshId, error: e.message };
                 }
             }
 
-            case 'update_mesh': {
+            case 'join_mesh_host_pairing': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const token = typeof args?.token === 'string' ? args.token.trim() : '';
                 if (!meshId) return { success: false, error: 'meshId required' };
+                if (!token) return { success: false, error: 'token required because raw pairing tokens are not persisted' };
+                const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+                const mesh = meshRecord?.mesh;
+                if (!mesh) return { success: false, error: 'Mesh not found' };
+                const meshHost = resolveMeshHostStatus(mesh);
+                if (meshHost.role !== 'member') {
+                    return { success: false, code: 'mesh_host_join_not_member', meshId, meshHost, error: 'join_mesh_host_pairing must run from a member daemon configured with a Mesh Host address/token.' };
+                }
                 try {
-                    const { 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 };
+                    const { tokenIdForManualPairing, markMeshHostPairingJoined } = await import('../config/mesh-config.js');
+                    const tokenId = tokenIdForManualPairing(token);
+                    if (meshHost.pairing?.tokenId && meshHost.pairing.tokenId !== tokenId) {
+                        return { success: false, code: 'mesh_host_join_rejected', meshId, tokenId, meshHost, error: 'invalid pairing token' };
+                    }
+                    const memberNode = buildMemberJoinNode(mesh, args, this.deps.statusInstanceId);
+                    if (!memberNode) return { success: false, error: 'member node metadata unavailable' };
+                    const hostMeshId = typeof args?.hostMeshId === 'string' && args.hostMeshId.trim() ? args.hostMeshId.trim() : meshId;
+                    const hostDaemonId = typeof args?.hostDaemonId === 'string' && args.hostDaemonId.trim()
+                        ? args.hostDaemonId.trim()
+                        : meshHost.hostDaemonId;
+                    let hostResult: any;
+                    let transport: string;
+                    if (hostDaemonId && this.deps.dispatchMeshCommand) {
+                        transport = 'mesh_command_dispatch';
+                        hostResult = await this.deps.dispatchMeshCommand(hostDaemonId, 'apply_mesh_host_join', {
+                            meshId: hostMeshId,
+                            token,
+                            memberMeshId: meshId,
+                            memberNode,
+                        });
+                    } else if (meshHost.hostAddress) {
+                        transport = 'standalone_http_command';
+                        const commandUrl = normalizeStandaloneHostCommandUrl(meshHost.hostAddress);
+                        const response = await fetch(commandUrl, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({ type: 'apply_mesh_host_join', payload: { meshId: hostMeshId, token, memberMeshId: meshId, memberNode } }),
+                        });
+                        hostResult = await response.json().catch(() => ({ success: false, error: `Host returned HTTP ${response.status}` }));
+                        if (!response.ok && hostResult?.success !== false) hostResult = { success: false, error: `Host returned HTTP ${response.status}` };
+                    } else {
+                        return {
+                            success: false,
+                            code: 'mesh_host_join_transport_unavailable',
+                            meshId,
+                            meshHost,
+                            error: 'No hostDaemonId dispatch path or hostAddress HTTP command path is available. P2P signaling join is not implemented in this slice.',
+                        };
+                    }
+                    if (!hostResult?.success) {
+                        return { success: false, code: hostResult?.code || 'mesh_host_join_rejected', meshId, meshHost, transport, error: hostResult?.error || 'Mesh Host rejected join request', hostResult };
+                    }
+                    const joined = meshRecord.inline
+                        ? null
+                        : markMeshHostPairingJoined(meshId, {
+                            tokenId: hostResult.tokenId || tokenId,
+                            hostDaemonId: hostResult.meshHost?.hostDaemonId || hostDaemonId,
+                            hostNodeId: hostResult.meshHost?.hostNodeId,
+                            joinedAt: hostResult.meshHost?.pairing?.joinedAt,
+                        });
+                    if (joined) {
+                        this.inlineMeshCache.set(meshId, joined.mesh);
+                        this.invalidateAggregateMeshStatus(meshId);
+                    }
+                    return {
+                        success: true,
+                        code: 'mesh_host_join_applied',
+                        meshId,
+                        hostMeshId,
+                        transport,
+                        node: hostResult.node,
+                        tokenId: hostResult.tokenId || tokenId,
+                        meshHost: joined ? resolveMeshHostStatus(joined.mesh) : { ...meshHost, pairing: { ...(meshHost.pairing || {}), status: 'paired', tokenId: hostResult.tokenId || tokenId } },
+                        hostResult,
+                        manualPairing: {
+                            status: 'paired',
+                            joinImplemented: true,
+                            protocol: 'standalone_command_direct_v1',
+                            description: 'Mesh Host accepted the join and local member pairing status was marked paired. P2P runtime signaling remains outside this slice.',
+                        },
+                    };
                 } catch (e: any) {
-                    return { success: false, error: e.message };
+                    return { success: false, code: 'mesh_host_join_failed', meshId, meshHost, error: e.message };
                 }
             }
 
@@ -2286,6 +4841,8 @@ export class DaemonCommandRouter {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 const taskId = typeof args?.taskId === 'string' ? args.taskId.trim() : '';
                 if (!meshId || !taskId) return { success: false, error: 'meshId and taskId required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'queue cancellation');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const { cancelTask } = await import('../mesh/mesh-work-queue.js');
                     const reason = typeof args?.reason === 'string' ? args.reason : undefined;
@@ -2301,6 +4858,8 @@ export class DaemonCommandRouter {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 const taskId = typeof args?.taskId === 'string' ? args.taskId.trim() : '';
                 if (!meshId || !taskId) return { success: false, error: 'meshId and taskId required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'queue requeue');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const { requeueTask } = await import('../mesh/mesh-work-queue.js');
                     const task = requeueTask(meshId, taskId, {
@@ -2322,6 +4881,8 @@ export class DaemonCommandRouter {
                 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' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'node addition');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const { addNode } = await import('../config/mesh-config.js');
                     const providerPriority = Array.isArray(args?.providerPriority)
@@ -2332,8 +4893,26 @@ export class DaemonCommandRouter {
                         ...(readOnly ? { readOnly: true } : {}),
                         ...(providerPriority.length ? { providerPriority } : {}),
                     };
-                    const node = addNode(meshId, { workspace, ...(policy ? { policy } : {}) });
+                    const role = normalizeMeshDaemonRole(args?.role);
+                    const daemonId = typeof args?.daemonId === 'string' && args.daemonId.trim() ? args.daemonId.trim() : undefined;
+                    const machineId = typeof args?.machineId === 'string' && args.machineId.trim() ? args.machineId.trim() : undefined;
+                    const repoRoot = typeof args?.repoRoot === 'string' && args.repoRoot.trim() ? args.repoRoot.trim() : undefined;
+                    const node = addNode(meshId, {
+                        workspace,
+                        ...(repoRoot ? { repoRoot } : {}),
+                        ...(daemonId ? { daemonId } : {}),
+                        ...(machineId ? { machineId } : {}),
+                        ...(policy ? { policy } : {}),
+                        ...(role ? { role } : {}),
+                    });
                     if (!node) return { success: false, error: 'Mesh not found' };
+                    // mesh_status hands back a coordinator-memory aggregate
+                    // snapshot keyed on (meshId, queueRevision). Adding a
+                    // node touches neither, so without an explicit cache
+                    // bust the dashboard graph keeps rendering the pre-add
+                    // node list (empty for a fresh mesh) even after the
+                    // user clicks Refresh.
+                    this.invalidateAggregateMeshStatus(meshId);
                     return { success: true, node };
                 } catch (e: any) {
                     return { success: false, error: e.message };
@@ -2344,6 +4923,8 @@ export class DaemonCommandRouter {
                 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' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'node update');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const { updateNode } = await import('../config/mesh-config.js');
                     const policy = args?.policy && typeof args.policy === 'object' && !Array.isArray(args.policy)
@@ -2360,8 +4941,20 @@ export class DaemonCommandRouter {
                             delete (policy as any).providerPriority;
                         }
                     }
-                    const node = updateNode(meshId, nodeId, { policy: policy as any });
+                    const patch: Record<string, unknown> = { policy: policy as any };
+                    if (typeof args?.systemPrompt === 'string') {
+                        const trimmed = (args.systemPrompt as string).trim();
+                        patch.systemPrompt = trimmed || undefined;
+                    } else if (args?.systemPrompt === null) {
+                        patch.systemPrompt = undefined;
+                    }
+                    const node = updateNode(meshId, nodeId, patch as any);
                     if (!node) return { success: false, error: 'Mesh node not found' };
+                    // Provider priority / systemPrompt changes don't touch
+                    // the queue revision, so without a manual bust the
+                    // cached aggregate keeps surfacing pre-update values
+                    // (priority chip, coordinator prompt preview, etc.).
+                    this.invalidateAggregateMeshStatus(meshId);
                     return { success: true, node };
                 } catch (e: any) {
                     return { success: false, error: e.message };
@@ -2372,6 +4965,8 @@ export class DaemonCommandRouter {
                 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' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'node removal');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
                     const mesh = meshRecord?.mesh;
@@ -2397,131 +4992,97 @@ export class DaemonCommandRouter {
                 }
             }
 
-            case 'refine_mesh_node': {
+            case 'get_mesh_refine_config_schema': {
+                return {
+                    success: true,
+                    schema: MESH_REFINE_CONFIG_SCHEMA,
+                    locations: MESH_REFINE_CONFIG_LOCATIONS,
+                    worktreeBootstrap: {
+                        schema: MESH_WORKTREE_BOOTSTRAP_CONFIG_SCHEMA,
+                        locations: MESH_WORKTREE_BOOTSTRAP_CONFIG_LOCATIONS,
+                        sourceOfTruth: 'repo worktree bootstrap config',
+                        runBehavior: 'When present and enabled, clone_mesh_node runs commands after submodule initialization and records status on the worktree node.',
+                    },
+                    sourceOfTruth: 'repo mesh/refine config',
+                    heuristicRole: 'suggestions_only_not_execution_path',
+                };
+            }
+
+            case 'validate_mesh_refine_config': {
+                const workspace = typeof args?.workspace === 'string' ? args.workspace : process.cwd();
+                const mesh = args?.inlineMesh || {};
+                const loaded = args?.config !== undefined
+                    ? { config: args.config, source: 'inline', sourceType: 'mesh_policy' as const }
+                    : loadMeshRefineConfig(mesh, workspace);
+                const validation = loaded.config
+                    ? validateMeshRefineConfig(loaded.config, loaded.source)
+                    : { valid: false, errors: [((loaded as { error?: string }).error) || 'repo mesh/refine config unavailable'], commands: [], rejectedCommands: [] };
+                return { success: validation.valid, ...loaded, ...validation };
+            }
+
+            case 'suggest_mesh_refine_config': {
+                const workspace = typeof args?.workspace === 'string' ? args.workspace : process.cwd();
+                const mesh = args?.inlineMesh || {};
+                return {
+                    success: true,
+                    ...suggestMeshRefineConfig(mesh, workspace),
+                    note: 'Suggestions are heuristic scaffold only; Refinery will not execute them until saved into repo mesh/refine config.',
+                };
+            }
+
+            case 'plan_mesh_refine_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?.workspace) return { success: false, error: `Node '${nodeId}' workspace not found` };
+                return {
+                    success: true,
+                    dryRun: true,
+                    nodeId,
+                    workspace: node.workspace,
+                    validationPlan: buildMeshRefineValidationPlan(mesh, node.workspace),
+                    mergeWillRun: false,
+                    cleanupWillRun: false,
+                };
+            }
+
+            case 'fast_forward_mesh_node': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
+                let workspace = typeof args?.workspace === 'string' ? args.workspace.trim() : '';
+                let submoduleIgnorePaths = Array.isArray(args?.submoduleIgnorePaths)
+                    ? args.submoduleIgnorePaths.filter((value: unknown): value is string => typeof value === 'string')
+                    : undefined;
+                if (!workspace && meshId && nodeId) {
                     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',
-                            },
-                        };
+                    workspace = typeof node?.workspace === 'string' ? node.workspace.trim() : '';
+                    if (!submoduleIgnorePaths && Array.isArray(node?.policy?.submoduleIgnorePaths)) {
+                        submoduleIgnorePaths = node.policy.submoduleIgnorePaths.filter((value: unknown): value is string => typeof value === 'string');
                     }
-
-                    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 };
                 }
+                const result = await (fastForwardMeshNode({
+                    meshId: meshId || undefined,
+                    nodeId: nodeId || undefined,
+                    workspace,
+                    branch: typeof args?.branch === 'string' ? args.branch : undefined,
+                    execute: args?.execute === true,
+                    dryRun: args?.dryRun === true,
+                    updateSubmodules: args?.updateSubmodules === true,
+                    submoduleIgnorePaths,
+                }) as Promise<unknown>);
+                return result as CommandRouterResult;
+            }
+
+            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' };
+                return this.startMeshRefineJob(meshId, nodeId, args);
             }
 
             case 'remove_mesh_node': {
@@ -2562,9 +5123,15 @@ export class DaemonCommandRouter {
                     let removed = false;
                     if (meshRecord?.inline) {
                         removed = this.removeInlineMeshNode(meshId, mesh, nodeId);
+                        // Inline meshes share the same aggregate snapshot cache as
+                        // local-config meshes; without this bust the removed node
+                        // keeps showing up in the dashboard graph until the cache
+                        // ages out on its own.
+                        if (removed) this.invalidateAggregateMeshStatus(meshId);
                     } else {
                         const { removeNode } = await import('../config/mesh-config.js');
                         removed = removeNode(meshId, nodeId);
+                        if (removed) this.invalidateAggregateMeshStatus(meshId);
                     }
 
                     // Record in task ledger
@@ -2602,6 +5169,8 @@ export class DaemonCommandRouter {
                 if (!meshId) return { success: false, error: 'meshId required' };
                 if (!sourceNodeId) return { success: false, error: 'sourceNodeId required' };
                 if (!branch) return { success: false, error: 'branch required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'worktree clone');
+                if (ownerFailure) return ownerFailure;
 
                 try {
                     const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
@@ -2650,39 +5219,124 @@ export class DaemonCommandRouter {
                             policy: { ...(sourceNode.policy || {}) },
                         });
                         if (!node) return { success: false, error: 'Failed to register worktree node' };
+                        this.invalidateAggregateMeshStatus(meshId);
                     }
 
-                    // Initialize submodules if policy allows (default: true)
-                    const initSubmodules = (sourceNode.policy as any)?.initSubmodulesOnClone !== false;
-                    if (initSubmodules) {
+                    const persistWorktreeSetupState = async (bootstrapState: WorktreeBootstrapState): Promise<void> => {
+                        node.worktreeBootstrap = bootstrapState;
+                        if (meshRecord.inline) {
+                            this.updateInlineMeshNode(meshId, mesh, node);
+                            return;
+                        }
                         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);
+                            const { updateNode } = await import('../config/mesh-config.js');
+                            updateNode(meshId, node.id, { worktreeBootstrap: bootstrapState });
+                            this.invalidateAggregateMeshStatus(meshId);
+                        } catch { /* bootstrap status persistence is best-effort */ }
+                    };
+
+                    const appendCloneLedger = async (initSubmodules: boolean, bootstrapState: WorktreeBootstrapState): Promise<void> => {
+                        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,
+                                    worktreeBootstrap: {
+                                        status: bootstrapState.status,
+                                        required: bootstrapState.required,
+                                        configSource: bootstrapState.configSource,
+                                        configSourceType: bootstrapState.configSourceType,
+                                        lastCommand: bootstrapState.lastCommand,
+                                        exitCode: bootstrapState.exitCode,
+                                    },
+                                },
+                            });
+                        } catch { /* ledger append is best-effort */ }
+                    };
+
+                    const initSubmodules = (sourceNode.policy as any)?.initSubmodulesOnClone !== false;
+                    const loadedBootstrap = loadMeshWorktreeBootstrapConfig(mesh, result.worktreePath);
+                    const runningBootstrapState: WorktreeBootstrapState = {
+                        status: 'running',
+                        required: loadedBootstrap.config?.required !== false,
+                        configSource: loadedBootstrap.path || loadedBootstrap.source,
+                        configSourceType: loadedBootstrap.sourceType,
+                        startedAt: new Date().toISOString(),
+                    };
+                    await persistWorktreeSetupState(runningBootstrapState);
+
+                    const finishWorktreeSetup = async (): Promise<{ submodulesInitialized: boolean; bootstrapState: WorktreeBootstrapState }> => {
+                        let submodulesInitialized = 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 },
+                                );
+                                submodulesInitialized = true;
+                            } catch (subErr: any) {
+                                // Submodule init is best-effort; don't fail the clone
+                                console.warn('[mesh] Submodule init failed for worktree:', subErr.message);
+                            }
                         }
-                    }
+                        const bootstrapState: WorktreeBootstrapState = await runMeshWorktreeBootstrap(mesh, result.worktreePath);
+                        await persistWorktreeSetupState(bootstrapState);
+                        await appendCloneLedger(submodulesInitialized, bootstrapState);
+                        return { submodulesInitialized, bootstrapState };
+                    };
 
-                    // 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 },
+                    const requestedSetupWaitMs = Number(args?.setupWaitMs ?? args?.bootstrapWaitMs ?? 8000);
+                    const setupWaitMs = Number.isFinite(requestedSetupWaitMs)
+                        ? Math.min(Math.max(requestedSetupWaitMs, 0), 14000)
+                        : 8000;
+                    const setupPromise = finishWorktreeSetup();
+                    const setupResult = await Promise.race([
+                        setupPromise.then((value) => ({ completed: true as const, value })),
+                        new Promise<{ completed: false }>((resolve) => setTimeout(() => resolve({ completed: false }), setupWaitMs)),
+                    ]);
+
+                    if (!setupResult.completed) {
+                        setupPromise.catch((error: any) => {
+                            const failedState: WorktreeBootstrapState = {
+                                ...runningBootstrapState,
+                                status: 'failed',
+                                completedAt: new Date().toISOString(),
+                                error: error?.message || String(error),
+                            };
+                            void persistWorktreeSetupState(failedState);
+                            void appendCloneLedger(false, failedState);
                         });
-                    } catch { /* ledger append is best-effort */ }
+                        return {
+                            success: true,
+                            async: true,
+                            status: 'accepted',
+                            node,
+                            worktreePath: result.worktreePath,
+                            branch: result.branch,
+                            worktreeBootstrap: runningBootstrapState,
+                            worktreeSetup: {
+                                status: 'running',
+                                setupWaitMs,
+                                message: 'Worktree node is registered; submodule/bootstrap setup is continuing in the background.',
+                            },
+                        };
+                    }
 
+                    const { submodulesInitialized, bootstrapState } = setupResult.value;
                     return {
                         success: true,
                         node,
                         worktreePath: result.worktreePath,
                         branch: result.branch,
+                        submodulesInitialized,
+                        worktreeBootstrap: bootstrapState,
                     };
                 } catch (e: any) {
                     return { success: false, error: e.message };
@@ -2691,12 +5345,12 @@ export class DaemonCommandRouter {
             case 'trigger_mesh_queue': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 if (!meshId) return { success: false, error: 'meshId required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'queue trigger');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const { triggerMeshQueue } = await import('../mesh/mesh-events.js');
-                    if (meshId) {
-                        triggerMeshQueue(this.deps as any, meshId);
-                    }
-                    return { success: true };
+                    const trigger = await triggerMeshQueue(this.deps as any, meshId);
+                    return { success: true, trigger };
                 } catch (e: any) {
                     return { success: false, error: e.message };
                 }
@@ -2706,6 +5360,19 @@ export class DaemonCommandRouter {
             case 'launch_mesh_coordinator': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 let cliType = typeof args?.cliType === 'string' ? args.cliType.trim() : '';
+                // Optional per-launch system-prompt addition. Dashboard or API
+                // callers (e.g. when spawning a mesh-node-specific coordinator)
+                // can pass extra context that gets appended to the rendered
+                // default prompt under the "## Additional Context" section.
+                // Going through buildCoordinatorSystemPrompt's userInstruction
+                // means user-level override files (~/.adhdev/coordinator-prompts)
+                // and this per-launch addition compose cleanly: an override
+                // wins outright, but if there's no override, the default
+                // prompt + the optional append.md file + this extra context
+                // all stack in declared order.
+                const extraSystemPrompt = typeof args?.extraSystemPrompt === 'string'
+                    ? args.extraSystemPrompt.trim()
+                    : '';
                 if (!meshId) return { success: false, error: 'meshId required' };
 
                 try {
@@ -2722,6 +5389,15 @@ export class DaemonCommandRouter {
                         mesh = getMesh(meshId);
                     }
                     if (!mesh) return { success: false, error: 'Mesh not found' };
+                    const meshHost = resolveMeshHostStatus(mesh);
+                    if (!meshHost.canOwnCoordinator) {
+                        return {
+                            success: false,
+                            ...buildMeshHostRequiredFailure(mesh, 'coordinator launch'),
+                            meshId,
+                            cliType,
+                        };
+                    }
                     if (!Array.isArray(mesh.nodes) || mesh.nodes.length === 0) return { success: false, error: 'No nodes in mesh' };
 
                     const requestedCoordinatorNodeId = typeof args?.coordinatorNodeId === 'string'
@@ -2807,7 +5483,7 @@ export class DaemonCommandRouter {
                         // Build coordinator prompt first — fail closed on errors.
                         let cliCmdSystemPrompt = '';
                         try {
-                            cliCmdSystemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType });
+                            cliCmdSystemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType, userInstruction: extraSystemPrompt || undefined });
                         } catch (error: any) {
                             const message = error?.message || String(error);
                             LOG.error('MeshCoordinator', `Failed to build coordinator prompt: ${message}`);
@@ -2819,55 +5495,126 @@ export class DaemonCommandRouter {
                             };
                         }
 
-                        // Run the provider's MCP registration command.
+                        // Run the provider's MCP registration command under a
+                        // PTY. Some providers (agy, future bubbletea CLIs)
+                        // refuse to run without /dev/tty, so pipe-only
+                        // execFileSync silently no-ops the registration and
+                        // the coordinator ends up without any mcp tools. With
+                        // a real PTY the registration goes through and the
+                        // exit code tells us whether it actually persisted.
+                        let mcpRegistrationOk = false;
+                        let mcpRegistrationFailure: {
+                            command: string;
+                            output: string;
+                            exitCode: number | null;
+                            signal: number | null;
+                            timedOut: boolean;
+                        } | null = null;
                         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 });
+                            const { buildMeshCoordinatorRegistrationPlan, execUnderPty } = await import('./mesh-coordinator.js');
+                            const registrationPlan = buildMeshCoordinatorRegistrationPlan(
+                                cliType,
+                                coordinatorSetup.serverName,
+                                coordinatorSetup.command,
+                            );
+                            for (const step of registrationPlan) {
+                                const renderedCommand = [step.command, ...step.args].join(' ');
+                                LOG.info('MeshCoordinator', `Running MCP ${step.label} (pty): ${renderedCommand}`);
+                                const ptyResult = await execUnderPty(step.command, step.args, { cwd: workspace, timeoutMs: 20_000 });
+                                if (ptyResult.exitCode === 0 && !ptyResult.timedOut) {
+                                    if (step.required) mcpRegistrationOk = true;
+                                    continue;
+                                }
+                                LOG.warn('MeshCoordinator', `MCP ${step.label} failed exit=${ptyResult.exitCode} signal=${ptyResult.signal} timedOut=${ptyResult.timedOut} — output:\n${ptyResult.output.slice(-2000)}`);
+                                if (step.required) {
+                                    mcpRegistrationFailure = {
+                                        command: renderedCommand,
+                                        output: ptyResult.output.slice(-2000),
+                                        exitCode: ptyResult.exitCode,
+                                        signal: ptyResult.signal,
+                                        timedOut: ptyResult.timedOut,
+                                    };
+                                    break;
+                                }
+                            }
                         } 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}`);
+                            LOG.warn('MeshCoordinator', `MCP registration command failed: ${error?.message || error}`);
+                            mcpRegistrationFailure = {
+                                command: coordinatorSetup.command,
+                                output: error?.message || String(error),
+                                exitCode: null,
+                                signal: null,
+                                timedOut: false,
+                            };
                         }
 
-                        // 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.
+                        if (!mcpRegistrationOk) {
+                            return {
+                                success: false,
+                                code: 'mesh_coordinator_mcp_registration_failed',
+                                error: `Could not register ${coordinatorSetup.serverName}; coordinator session was not launched`,
+                                meshId,
+                                cliType,
+                                workspace,
+                                registration: mcpRegistrationFailure,
+                            };
+                        }
+
+                        // Codex gives repo-local .mcp.json precedence over its
+                        // global `codex mcp add` registration. Refresh an
+                        // existing ADHDev entry so a stale workspace command
+                        // cannot shadow the registration we just verified.
+                        if (cliType === 'codex-cli') {
+                            const repoMcpConfigPath = pathJoin(workspace, '.mcp.json');
+                            if (fs.existsSync(repoMcpConfigPath)) {
                                 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);
+                                    const repoMcpConfig = parseMeshCoordinatorMcpConfig(
+                                        fs.readFileSync(repoMcpConfigPath, 'utf-8'),
+                                        'claude_mcp_json',
+                                    );
+                                    const existingServers = repoMcpConfig.mcpServers;
+                                    if (
+                                        existingServers
+                                        && typeof existingServers === 'object'
+                                        && !Array.isArray(existingServers)
+                                        && existingServers[coordinatorSetup.serverName]
+                                    ) {
+                                        fs.writeFileSync(repoMcpConfigPath, serializeMeshCoordinatorMcpConfig({
+                                            ...repoMcpConfig,
+                                            mcpServers: {
+                                                ...existingServers,
+                                                [coordinatorSetup.serverName]: coordinatorSetup.mcpServer,
+                                            },
+                                        }, 'claude_mcp_json'), 'utf-8');
+                                        LOG.info('MeshCoordinator', `Refreshed repo-local ${repoMcpConfigPath} entry for ${coordinatorSetup.serverName}`);
                                     }
-                                    LOG.info('MeshCoordinator', `Wrote coordinator prompt to ${workspace}/GEMINI.md`);
-                                } catch (e: any) {
-                                    LOG.warn('MeshCoordinator', `Could not write GEMINI.md: ${e?.message || e}`);
+                                } catch (error: any) {
+                                    return {
+                                        success: false,
+                                        code: 'mesh_coordinator_config_write_failed',
+                                        error: `Could not refresh repo-local MCP config: ${error?.message || error}`,
+                                        meshId,
+                                        cliType,
+                                        workspace,
+                                    };
                                 }
                             }
                         }
 
+                        // Inject system prompt declaratively from provider.v1.json.
+                        const cliCmdArgs: string[] = [];
+                        const cliCmdEnv: Record<string, string> = {};
+                        let cliCmdContextFilePath: string | undefined;
+                        if (cliCmdSystemPrompt) {
+                            const { applyMeshCoordinatorSystemPromptInjection } = await import('./mesh-coordinator.js');
+                            const effect = applyMeshCoordinatorSystemPromptInjection(
+                                cliCmdSystemPrompt,
+                                providerMeta?.meshCoordinator?.systemPromptInjection,
+                                { cliArgs: cliCmdArgs, launchEnv: cliCmdEnv, workspace, cliType },
+                            );
+                            cliCmdContextFilePath = effect.contextFilePath;
+                        }
+
                         const cliCmdLaunch: any = await this.deps.cliManager.handleCliCommand('launch_cli', {
                             cliType,
                             dir: workspace,
@@ -2876,16 +5623,52 @@ export class DaemonCommandRouter {
                             settings: { meshCoordinatorFor: meshId },
                         });
 
+                        // R48 inject-then-remove. Spawn was just kicked off above; agy and
+                        // gemini-cli read AGENTS.md / GEMINI.md exactly once at startup and
+                        // cache it for the rest of the session, so we can safely strip
+                        // the wrapper from disk shortly after launch. That keeps any
+                        // worker session launched into the same workspace later from
+                        // picking up our wrapper block.
+                        if (cliCmdLaunch?.success && cliCmdContextFilePath) {
+                            const stripPath = cliCmdContextFilePath;
+                            setTimeout(() => {
+                                void import('./mesh-coordinator.js').then(({ stripCoordinatorWrapperFile }) => {
+                                    stripCoordinatorWrapperFile(stripPath);
+                                    LOG.info('MeshCoordinator', `Stripped wrapper from ${stripPath} after launch settle (cli_command)`);
+                                }).catch(() => { /* best-effort */ });
+                            }, 5000);
+                        }
+
                         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}`);
+                        const cliCmdSessionId = cliCmdLaunch.sessionId || cliCmdLaunch.id;
+                        if (cliCmdSessionId) {
+                            const cliCmdInjectionDecl = providerMeta?.meshCoordinator?.systemPromptInjection;
+                            registerMeshCoordinator({
+                                meshId,
+                                sessionId: cliCmdSessionId,
+                                workspace,
+                                startedAt: Date.now(),
+                                cliType,
+                                systemPrompt: cliCmdSystemPrompt || undefined,
+                                extraSystemPrompt: extraSystemPrompt || undefined,
+                                injection: cliCmdInjectionDecl ? {
+                                    mode: cliCmdInjectionDecl.mode,
+                                    target: 'flag' in cliCmdInjectionDecl ? cliCmdInjectionDecl.flag
+                                        : 'name' in cliCmdInjectionDecl ? cliCmdInjectionDecl.name
+                                        : 'path' in cliCmdInjectionDecl ? cliCmdInjectionDecl.path
+                                        : undefined,
+                                } : undefined,
+                            });
+                        }
                         try {
                             const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
                             appendLedgerEntry(meshId, {
                                 kind: 'coordinator_started',
-                                sessionId: cliCmdLaunch.sessionId || cliCmdLaunch.id,
+                                sessionId: cliCmdSessionId,
                                 providerType: cliType,
                                 payload: { workspace },
                             });
@@ -2896,8 +5679,8 @@ export class DaemonCommandRouter {
                             meshId,
                             cliType,
                             workspace,
-                            sessionId: cliCmdLaunch.sessionId || cliCmdLaunch.id,
-                            mcpRegistered: true,
+                            sessionId: cliCmdSessionId,
+                            mcpRegistered: mcpRegistrationOk,
                         };
                     }
 
@@ -2918,7 +5701,7 @@ export class DaemonCommandRouter {
                     // broken mesh state is visible instead of silently launching with weaker rules.
                     let systemPrompt = '';
                     try {
-                        systemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType });
+                        systemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType, userInstruction: extraSystemPrompt || undefined });
                     } catch (error: any) {
                         const message = error?.message || String(error);
                         LOG.error('MeshCoordinator', `Failed to build coordinator prompt: ${message}`);
@@ -3033,12 +5816,15 @@ export class DaemonCommandRouter {
                         launchEnv.HERMES_HOME = dirname(mcpConfigPath);
                         launchEnv.HERMES_IGNORE_USER_CONFIG = '';
                     }
+                    let autoImportContextFilePath: string | undefined;
                     if (systemPrompt) {
-                        if (configFormat === 'hermes_config_yaml') {
-                            launchEnv.HERMES_EPHEMERAL_SYSTEM_PROMPT = systemPrompt;
-                        } else {
-                            cliArgs.push('--append-system-prompt', systemPrompt);
-                        }
+                        const { applyMeshCoordinatorSystemPromptInjection } = await import('./mesh-coordinator.js');
+                        const effect = applyMeshCoordinatorSystemPromptInjection(
+                            systemPrompt,
+                            providerMeta?.meshCoordinator?.systemPromptInjection,
+                            { cliArgs, launchEnv, workspace, cliType },
+                        );
+                        autoImportContextFilePath = effect.contextFilePath;
                     }
                     if (cliType === 'claude-cli') {
                         cliArgs.push('--mcp-config', coordinatorSetup.configPath);
@@ -3057,18 +5843,53 @@ export class DaemonCommandRouter {
                         }
                     });
 
+                    // R48 inject-then-remove. See the cli_command branch for context;
+                    // same idea: strip the wrapper from disk ~5s after launch so the
+                    // user's AGENTS.md / GEMINI.md is untouched the moment any
+                    // worker session opens up in the same workspace.
+                    if (launchResult?.success && autoImportContextFilePath) {
+                        const stripPath = autoImportContextFilePath;
+                        setTimeout(() => {
+                            void import('./mesh-coordinator.js').then(({ stripCoordinatorWrapperFile }) => {
+                                stripCoordinatorWrapperFile(stripPath);
+                                LOG.info('MeshCoordinator', `Stripped wrapper from ${stripPath} after launch settle (auto_import)`);
+                            }).catch(() => { /* best-effort */ });
+                        }, 5000);
+                    }
+
                     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}`);
+                    const launchSessionId = launchResult.sessionId || launchResult.id;
+                    if (launchSessionId) {
+                        const autoImportInjectionDecl = providerMeta?.meshCoordinator?.systemPromptInjection;
+                        registerMeshCoordinator({
+                            meshId,
+                            sessionId: launchSessionId,
+                            workspace,
+                            startedAt: Date.now(),
+                            cliType,
+                            systemPrompt: systemPrompt || undefined,
+                            extraSystemPrompt: extraSystemPrompt || undefined,
+                            mcpConfigPath,
+                            injection: autoImportInjectionDecl ? {
+                                mode: autoImportInjectionDecl.mode,
+                                target: 'flag' in autoImportInjectionDecl ? autoImportInjectionDecl.flag
+                                    : 'name' in autoImportInjectionDecl ? autoImportInjectionDecl.name
+                                    : 'path' in autoImportInjectionDecl ? autoImportInjectionDecl.path
+                                    : undefined,
+                            } : undefined,
+                        });
+                    }
 
                     // 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,
+                            sessionId: launchSessionId,
                             providerType: cliType,
                             payload: { workspace },
                         });
@@ -3079,7 +5900,7 @@ export class DaemonCommandRouter {
                         meshId,
                         cliType,
                         workspace,
-                        sessionId: launchResult.sessionId || launchResult.id,
+                        sessionId: launchSessionId,
                         mcpConfigWritten: true,
                     };
                 } catch (e: any) {
@@ -3095,6 +5916,36 @@ export class DaemonCommandRouter {
                     const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
                     const mesh = meshRecord?.mesh;
                     if (!mesh) return { success: false, error: 'Mesh not found' };
+                    const meshHost = resolveMeshHostStatus(mesh);
+
+                    const refreshRequested = args?.refresh === true || args?.forceRefresh === true;
+                    // See (B3) below: scope the peek to this daemon when the
+                    // caller doesn't tell us, otherwise scoped events look
+                    // missing and we falsely return a stale cache.
+                    const peekScope = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
+                        ? args.coordinatorDaemonId.trim()
+                        : (this.deps.statusInstanceId || undefined);
+                    const pendingCoordinatorEventCount = getPendingMeshCoordinatorEvents(meshId, peekScope).length;
+                    const hadAggregateCache = this.aggregateMeshStatusCache.has(meshId);
+                    if (!refreshRequested && pendingCoordinatorEventCount === 0) {
+                        const cachedStatus = this.getCachedAggregateMeshStatus(meshId, mesh, { requireDirectPeerTruth: args?.requireDirectPeerTruth === true });
+                        if (cachedStatus) {
+                            logRepoMeshStatusDebug('return_cached', {
+                                meshId,
+                                command: 'mesh_status',
+                                refreshRequested,
+                                summary: summarizeRepoMeshStatusDebug(cachedStatus),
+                            });
+                            return cachedStatus;
+                        }
+                    }
+                    const refreshReason = refreshRequested
+                        ? 'explicit_refresh'
+                        : pendingCoordinatorEventCount > 0
+                            ? 'pending_coordinator_events'
+                        : hadAggregateCache
+                            ? 'stale_pending_cache_refresh'
+                            : 'cold_cache_miss';
 
                     const { getMeshQueueStats, getQueue } = await import('../mesh/mesh-work-queue.js');
                     const queue = getQueue(meshId);
@@ -3102,6 +5953,7 @@ export class DaemonCommandRouter {
 
                     const { readLedgerEntries, getLedgerSummary } = await import('../mesh/mesh-ledger.js');
                     const ledgerEntries = readLedgerEntries(meshId, { tail: 20 });
+                    const asyncRefineLedgerEntries = readLedgerEntries(meshId, { tail: 100 });
                     const ledgerSummary = getLedgerSummary(meshId);
                     const sessionHostRecords = this.deps.sessionHostControl?.listSessions
                         ? await this.deps.sessionHostControl.listSessions().catch(() => [])
@@ -3109,6 +5961,74 @@ export class DaemonCommandRouter {
                     const liveMeshSessions = partitionSessionHostRecords(Array.isArray(sessionHostRecords) ? sessionHostRecords : []).liveRuntimes;
 
                     const localMachineId = loadConfig().machineId || '';
+                    const requireDirectPeerTruth = args?.requireDirectPeerTruth === true;
+                    const directTruth = requireDirectPeerTruth
+                        ? await hydrateInlineMeshDirectTruth({
+                            mesh,
+                            meshSource: meshRecord.source,
+                            dispatchMeshCommand: this.deps.dispatchMeshCommand,
+                            statusInstanceId: this.deps.statusInstanceId,
+                            localMachineId,
+                        })
+                        : {
+                            directEvidenceCount: 0,
+                            localConfirmedCount: 0,
+                            peerAttemptedCount: 0,
+                            peerConfirmedCount: 0,
+                            unavailableNodeIds: [] as string[],
+                        };
+                    // Default/cached loads may not attempt a remote peer probe yet; do not surface that as
+                    // a direct mesh truth failure until an explicit probe attempt actually fails.
+                    const passivePeerTruthNotAttempted = requireDirectPeerTruth
+                        && !refreshRequested
+                        && directTruth.directEvidenceCount > 0
+                        && directTruth.peerAttemptedCount === 0;
+                    const effectiveDirectTruth = passivePeerTruthNotAttempted
+                        ? { ...directTruth, unavailableNodeIds: [] as string[] }
+                        : directTruth;
+                    const unavailableDirectTruthNodeIds = new Set(effectiveDirectTruth.unavailableNodeIds);
+                    const unavailableNodesAreOnlyRemovedWorktrees = unavailableDirectTruthNodeIds.size > 0
+                        && Array.isArray(mesh.nodes)
+                        && mesh.nodes
+                            .filter((node: any) => unavailableDirectTruthNodeIds.has(String(node.id || node.nodeId || '')))
+                            .every((node: any) => node?.isLocalWorktree === true);
+                    const directTruthSatisfied = !requireDirectPeerTruth
+                        || (effectiveDirectTruth.directEvidenceCount > 0 && (effectiveDirectTruth.unavailableNodeIds.length === 0 || unavailableNodesAreOnlyRemovedWorktrees));
+                    if (requireDirectPeerTruth && !directTruthSatisfied) {
+                        const failureResult = {
+                            success: false,
+                            code: 'mesh_direct_peer_truth_unavailable',
+                            error: 'Selected coordinator could not confirm direct mesh truth yet. Bootstrap inventory stays unavailable until direct mesh_status probes succeed.',
+                            sourceOfTruth: {
+                                membership: meshRecord.source === 'inline_cache'
+                                    ? 'coordinator_inline_mesh_cache'
+                                    : meshRecord.source === 'local_config'
+                                        ? 'local_mesh_config'
+                                        : 'inline_bootstrap_snapshot',
+                                coordinatorOwnsLiveTruth: false,
+                                currentStatus: 'direct_peer_truth_unavailable',
+                                directPeerTruth: {
+                                    required: true,
+                                    satisfied: false,
+                                    directEvidenceCount: directTruth.directEvidenceCount,
+                                    localConfirmedCount: directTruth.localConfirmedCount,
+                                    peerAttemptedCount: directTruth.peerAttemptedCount,
+                                    peerConfirmedCount: directTruth.peerConfirmedCount,
+                                    unavailableNodeIds: directTruth.unavailableNodeIds,
+                                },
+                            },
+                        };
+                        logRepoMeshStatusDebug('direct_truth_unavailable', {
+                            meshId,
+                            command: 'mesh_status',
+                            refreshRequested,
+                            meshSource: meshRecord.source,
+                            directTruth,
+                        });
+                        return failureResult;
+                    }
+                    const directTruthUnavailableNodeIds = new Set(effectiveDirectTruth.unavailableNodeIds);
+                    const coordinatorHostname = osHostname();
                     const selectedCoordinatorNodeId = readStringValue(
                         mesh.coordinator?.preferredNodeId,
                         (mesh.nodes?.[0] as any)?.id,
@@ -3122,21 +6042,42 @@ export class DaemonCommandRouter {
                     for (const [nodeIndex, node] of (mesh.nodes || []).entries()) {
                         const nodeId = String(node.id || node.nodeId || '');
                         const daemonId = readStringValue(node.daemonId);
+                        const nodeMachineId = readMeshNodeMachineId(node as Record<string, unknown>);
+                        const nodeHostname = readMeshNodeHostname(node as Record<string, unknown>);
                         const providerPriority = readProviderPriorityFromPolicy(node.policy);
+                        const configuredCoordinatorNode = Boolean(
+                            nodeId && selectedCoordinatorNodeId && nodeId === selectedCoordinatorNodeId,
+                        );
+                        const sparseConfiguredCoordinatorNode = configuredCoordinatorNode
+                            && !daemonId
+                            && !nodeMachineId
+                            && !nodeHostname;
                         const isSelfNode = Boolean(
                             nodeId && inlineCoordinatorNodeId && nodeId === inlineCoordinatorNodeId,
                         ) || Boolean(
                             daemonId && (daemonId === localMachineId || daemonId === this.deps.statusInstanceId),
-                        ) || Boolean(meshRecord?.inline && nodeIndex === 0);
+                        ) || Boolean(meshRecord?.inline && nodeIndex === 0)
+                            || sparseConfiguredCoordinatorNode;
+                        const machineIdentity = buildMeshNodeMachineIdentity(node as Record<string, unknown>, {
+                            localMachineId,
+                            localDaemonId: this.deps.statusInstanceId,
+                            coordinatorHostname,
+                            isSelfNode,
+                        });
                         const status: Record<string, unknown> = {
                             nodeId,
-                            machineLabel: node.machineLabel || node.id || node.nodeId,
+                            machineLabel: buildMeshNodeDisplayLabel(node as Record<string, unknown>, nodeId, providerPriority),
+                            labelSource: readStringValue(node.machineLabel, node.machine_label, node.machineNickname, node.machine_nickname, node.alias)
+                                ? 'explicit_metadata'
+                                : 'workspace_host_provider_context',
                             workspace: node.workspace,
                             repoRoot: node.repoRoot,
                             isLocalWorktree: node.isLocalWorktree,
                             worktreeBranch: node.worktreeBranch,
+                            role: normalizeMeshDaemonRole(node.role) || (meshHost.hostNodeId && nodeId === meshHost.hostNodeId ? 'host' : undefined),
                             daemonId,
-                            machineId: node.machineId,
+                            machineId: nodeMachineId || node.machineId,
+                            machine: machineIdentity,
                             machineStatus: node.machineStatus,
                             health: 'unknown',
                             providers: node.providers || [],
@@ -3203,52 +6144,224 @@ export class DaemonCommandRouter {
                             }
                         }
                         if (workspace) {
-                            if (!fs.existsSync(workspace) && applyCachedInlineMeshNodeStatus(status, node)) {
-                                status.launchReady = !!daemonId && (readStringValue(status.machineStatus) === 'online' || isSelfNode);
-                                nodeStatuses.push(status);
-                                continue;
-                            }
-                            try {
-                                const gitStatus = await getGitRepoStatus(workspace, { timeoutMs: 10_000, refreshUpstream: true });
-                                status.git = gitStatus;
-                                if (gitStatus.isGitRepo) {
-                                    status.health = deriveMeshNodeHealthFromGit(gitStatus as unknown as Record<string, unknown>);
-                                } else {
-                                    status.health = 'degraded';
-                                    if (gitStatus.error && !status.error) status.error = gitStatus.error;
+                            if (!fs.existsSync(workspace)) {
+                                // Workspace not local — prefer direct live inline truth, then attempt a P2P git probe.
+                                const inlineTransitGit = buildInlineMeshTransitGitStatus(node);
+                                let remoteProbeApplied = false;
+                                if (inlineTransitGit) {
+                                    status.git = inlineTransitGit;
+                                    status.health = inlineTransitGit.isGitRepo
+                                        ? deriveMeshNodeHealthFromGit(inlineTransitGit as unknown as Record<string, unknown>)
+                                        : 'degraded';
+                                    const connection = readObjectRecord(status.connection);
+                                    const connectionState = readStringValue(connection.state);
+                                    const connectionReported = readBooleanValue(connection.reported) ?? false;
+                                    if (!connectionReported || connectionState === 'unknown') {
+                                        status.connection = buildLivePeerGitConnection(connection, refreshedAt);
+                                    }
+                                    remoteProbeApplied = true;
+                                } else if (!isSelfNode && daemonId && this.deps.dispatchMeshCommand && !directTruthUnavailableNodeIds.has(nodeId)) {
+                                    try {
+                                        const remoteGit = await probeRemoteMeshGitStatus({
+                                            dispatchMeshCommand: this.deps.dispatchMeshCommand,
+                                            daemonId,
+                                            workspace,
+                                            timeoutMs: 8000,
+                                        });
+                                        if (remoteGit) {
+                                            status.git = remoteGit;
+                                            status.health = remoteGit.isGitRepo
+                                                ? deriveMeshNodeHealthFromGit(remoteGit as unknown as Record<string, unknown>)
+                                                : 'degraded';
+                                            const connection = readObjectRecord(status.connection);
+                                            const connectionState = readStringValue(connection.state);
+                                            const connectionReported = readBooleanValue(connection.reported) ?? false;
+                                            if (!connectionReported || connectionState === 'unknown') {
+                                                status.connection = buildLivePeerGitConnection(connection, refreshedAt);
+                                            }
+                                            recordInlineMeshDirectGitTruth(node, remoteGit, 'selected_coordinator_mesh_p2p_git');
+                                            remoteProbeApplied = true;
+                                        }
+                                    } catch {
+                                        const refreshedConnection = this.deps.getMeshPeerConnectionStatus?.(daemonId);
+                                        const refreshedConnectionState = readStringValue(refreshedConnection?.state);
+                                        if (refreshedConnection && refreshedConnectionState === 'connected') {
+                                            status.connection = refreshedConnection;
+                                            try {
+                                                const remoteGit = await probeRemoteMeshGitStatus({
+                                                    dispatchMeshCommand: this.deps.dispatchMeshCommand,
+                                                    daemonId,
+                                                    workspace,
+                                                    timeoutMs: 12000,
+                                                });
+                                                if (remoteGit) {
+                                                    status.git = remoteGit;
+                                                    status.health = remoteGit.isGitRepo
+                                                        ? deriveMeshNodeHealthFromGit(remoteGit as unknown as Record<string, unknown>)
+                                                        : 'degraded';
+                                                    const connection = readObjectRecord(status.connection);
+                                                    const connectionState = readStringValue(connection.state);
+                                                    const connectionReported = readBooleanValue(connection.reported) ?? false;
+                                                    if (!connectionReported || connectionState === 'unknown') {
+                                                        status.connection = buildLivePeerGitConnection(connection, refreshedAt);
+                                                    }
+                                                    recordInlineMeshDirectGitTruth(node, remoteGit, 'selected_coordinator_mesh_p2p_git');
+                                                    remoteProbeApplied = true;
+                                                }
+                                            } catch {
+                                                // Probe timed out again or P2P unavailable — fall back to cached status
+                                            }
+                                        }
+                                    }
+                                }
+                                if (!remoteProbeApplied) {
+                                    const connectionState = readStringValue((status.connection as any)?.state);
+                                    const pendingPeerGitProbe = !inlineTransitGit
+                                        && !isSelfNode
+                                        && !!daemonId
+                                        && (
+                                            readStringValue(status.machineStatus) === 'online'
+                                            || readStringValue(status.health) === 'online'
+                                            || connectionState === 'connecting'
+                                            || connectionState === 'connected'
+                                            || connectionState === 'unknown'
+                                        );
+                                    if (pendingPeerGitProbe) {
+                                        status.gitProbePending = true;
+                                        status.health = 'unknown';
+                                    }
+                                    if (applyCachedInlineMeshNodeStatus(
+                                        status,
+                                        node,
+                                        pendingPeerGitProbe ? { skipGit: true, skipError: true, skipHealth: true } : undefined,
+                                    )) {
+                                        applyInlineMeshBranchConvergence(mesh, node, status);
+                                        finalizeMeshNodeStatus({ status, node, daemonId, isSelfNode });
+                                        nodeStatuses.push(status);
+                                        continue;
+                                    }
+                                    if (meshRecord?.source === 'inline_cache' && !isSelfNode) {
+                                        applyInlineMeshBranchConvergence(mesh, node, status);
+                                        finalizeMeshNodeStatus({ status, node, daemonId, isSelfNode });
+                                        nodeStatuses.push(status);
+                                        continue;
+                                    }
                                 }
-                            } catch {
-                                if (!applyCachedInlineMeshNodeStatus(status, node)) {
-                                    status.health = 'degraded';
+                            } else {
+                                try {
+                                    const gitStatus = await getGitRepoStatus(workspace, { timeoutMs: 10_000, refreshUpstream: true });
+                                    status.git = gitStatus;
+                                    recordInlineMeshDirectGitTruth(node, gitStatus as unknown as Record<string, unknown>, 'selected_coordinator_local_git');
+                                    if (gitStatus.isGitRepo) {
+                                        status.health = deriveMeshNodeHealthFromGit(gitStatus as unknown as Record<string, unknown>);
+                                    } 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);
                         }
-                        status.launchReady = !!daemonId && (readStringValue(status.machineStatus) === 'online' || isSelfNode);
+                        applyInlineMeshBranchConvergence(mesh, node, status);
+                        finalizeMeshNodeStatus({ status, node, daemonId, isSelfNode });
                         nodeStatuses.push(status);
                     }
 
-                    return {
+                    // (B3) Resolve the coordinator daemon scope for the drain.
+                    // Emit-time always tags events with the worker's
+                    // targetCoordinatorDaemonId and writes them to the
+                    // scoped pending-events file. If the caller (MCP tool,
+                    // dashboard, etc.) doesn't tell us which coordinator
+                    // they're running under, fall back to *this daemon's*
+                    // ID — the caller reached us over our IPC/WS, so they
+                    // are by definition under this daemon. Falling back to
+                    // undefined would silently miss every scoped event.
+                    const callerCoordinatorDaemonId = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
+                        ? args.coordinatorDaemonId.trim()
+                        : (this.deps.statusInstanceId || undefined);
+                    const pendingCoordinatorEvents = drainPendingMeshCoordinatorEvents(meshId, callerCoordinatorDaemonId);
+                    const previewFreshness = (() => {
+                        const localRepoRoot = nodeStatuses
+                            .map((node: any) => readStringValue(node?.git?.repoRoot, node?.repoRoot, node?.workspace))
+                            .find((candidate: string | undefined) => !!candidate && fs.existsSync(candidate));
+                        return localRepoRoot ? buildPreviewFreshness(localRepoRoot) : undefined;
+                    })();
+                    const asyncRefineJobs = buildMeshAsyncRefineJobs({
+                        meshId,
+                        ledgerEntries: asyncRefineLedgerEntries,
+                        pendingEvents: pendingCoordinatorEvents,
+                    });
+                    const historicalSessions = buildHistoricalMeshSessions({
+                        meshId,
+                        nodes: mesh.nodes || [],
+                        liveSessionRecords: liveMeshSessions,
+                    });
+                    const statusResult = {
                         success: true,
                         meshId: mesh.id,
                         meshName: mesh.name,
                         repoIdentity: mesh.repoIdentity,
                         defaultBranch: mesh.defaultBranch,
-                        refreshedAt: new Date().toISOString(),
+                        refreshedAt,
+                        meshHost,
                         sourceOfTruth: {
                             membership: meshRecord?.source === 'inline_cache'
                                 ? 'coordinator_inline_mesh_cache'
                                 : meshRecord?.source === 'local_config'
                                     ? 'local_mesh_config'
                                     : 'inline_bootstrap_snapshot',
-                            coordinatorOwnsLiveTruth: meshRecord?.source !== 'inline_bootstrap',
-                            historicalEvidenceOnly: ['recoveryHints', 'ledger.summary', 'queue.summary'],
+                            coordinatorOwnsLiveTruth: directTruthSatisfied,
+                            meshHost: {
+                                owner: 'mesh_host_daemon',
+                                localRole: meshHost.role,
+                                hostDaemonId: meshHost.hostDaemonId,
+                                hostNodeId: meshHost.hostNodeId,
+                                hostAddress: meshHost.hostAddress,
+                            },
+                            ...(requireDirectPeerTruth ? {
+                                currentStatus: directTruthSatisfied ? 'live_git_and_session_probes' : 'direct_peer_truth_unavailable',
+                                directPeerTruth: {
+                                    required: true,
+                                    satisfied: directTruthSatisfied,
+                                    directEvidenceCount: effectiveDirectTruth.directEvidenceCount,
+                                    localConfirmedCount: effectiveDirectTruth.localConfirmedCount,
+                                    peerAttemptedCount: effectiveDirectTruth.peerAttemptedCount,
+                                    peerConfirmedCount: effectiveDirectTruth.peerConfirmedCount,
+                                    unavailableNodeIds: effectiveDirectTruth.unavailableNodeIds,
+                                    partialNodeFailures: effectiveDirectTruth.unavailableNodeIds,
+                                },
+                            } : {}),
+                            historicalEvidenceOnly: ['recoveryHints', 'ledger.summary', 'queue.summary', 'historicalSessions'],
                         },
+                        branchConvergenceSummary: summarizeInlineMeshBranchConvergence(nodeStatuses),
+                        ...(previewFreshness ? { previewFreshness, deployFreshness: previewFreshness } : {}),
                         nodes: nodeStatuses,
                         queue: { tasks: queue, summary: queueSummary },
                         ledger: { entries: ledgerEntries, summary: ledgerSummary },
+                        ...(asyncRefineJobs.length > 0 ? { asyncRefineJobs } : {}),
+                        ...(historicalSessions ? { historicalSessions } : {}),
+                        ...(pendingCoordinatorEvents.length > 0 ? { pendingCoordinatorEvents } : {}),
                     };
+                    const { pendingCoordinatorEvents: _pendingCoordinatorEvents, ...cacheableStatusResult } = statusResult as any;
+                    const rememberedStatus = this.rememberAggregateMeshStatus(meshId, cacheableStatusResult, refreshReason);
+                    const returnedStatus = pendingCoordinatorEvents.length > 0
+                        ? { ...rememberedStatus, pendingCoordinatorEvents }
+                        : rememberedStatus;
+                    logRepoMeshStatusDebug('return_live', {
+                        meshId,
+                        command: 'mesh_status',
+                        refreshRequested,
+                        refreshReason,
+                        meshSource: meshRecord.source,
+                        directTruth,
+                        summary: summarizeRepoMeshStatusDebug(returnedStatus),
+                    });
+                    return returnedStatus;
                 } catch (e: any) {
                     return { success: false, error: e.message };
                 }
@@ -3306,7 +6419,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);