@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

package/src/mesh/mesh-events.ts

@@ -1,1039 +1,47 @@
-import { appendFileSync, existsSync, readFileSync, unlinkSync } from 'fs';
-import { join } from 'path';
-import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
-import { loadConfig } from '../config/config.js';
-import { getMesh, getMeshByRepo } from '../config/mesh-config.js';
-import { detectCLI } from '../detection/cli-detector.js';
-import { LOG } from '../logging/logger.js';
-import { appendLedgerEntry, buildTaskCompletionEvidence, getLedgerDir, getSessionRecoveryContext, isIntentionalCleanupStopEntry, readLedgerEntries } from './mesh-ledger.js';
-import type { MeshLedgerKind, SessionRecoveryContext } from './mesh-ledger.js';
-import { claimNextTask, updateSessionTaskStatus, enqueueTask, updateTaskStatus, getQueue, recordTaskAutoLaunch } from './mesh-work-queue.js';
-
-// ---------------------------------------------------------------------------
-// Remote Node Idle Session Tracking
-// ---------------------------------------------------------------------------
-// Tracks remote sessions that emitted 'agent:ready' so triggerMeshQueue
-// can assign tasks to them. Each entry carries an expiresAt timestamp;
-// entries are swept on insertion to prevent unbounded growth.
-// ---------------------------------------------------------------------------
-interface RemoteIdleSession {
-    nodeId: string;
-    sessionId: string;
-    providerType: string;
-    expiresAt: number;
-}
-const REMOTE_IDLE_SESSION_TTL_MS = 5 * 60 * 1000; // 5 minutes
-const remoteIdleSessions = new Map<string, RemoteIdleSession>(); // key: `${nodeId}:${sessionId}`
-
-function sweepExpiredRemoteIdleSessions(): void {
-    const now = Date.now();
-    for (const [key, session] of remoteIdleSessions) {
-        if (session.expiresAt <= now) remoteIdleSessions.delete(key);
-    }
-}
-
 // ---------------------------------------------------------------------------
-// MCP coordinator pending-event queue — FILE-BASED PERSISTENCE
+// mesh-events — entry point
 // ---------------------------------------------------------------------------
-// When a mesh event fires but no CLI coordinator session is registered (e.g.
-// the coordinator is Claude Code running via MCP), we persist the event to a
-// per-mesh JSONL file so it survives daemon restarts. The 50-entry hard cap
-// is removed; the file is drained atomically on each get_pending_mesh_events
-// call and limited to 100 KB to prevent runaway growth.
-//
-// File: <ledgerDir>/<meshId>.pending-events.jsonl
+// Public API re-exported from sub-modules for backward compatibility.
+// New code should import directly from the relevant sub-module.
 // ---------------------------------------------------------------------------
 
-export interface PendingMeshCoordinatorEvent {
-    event: string;
-    meshId: string;
-    nodeLabel: string;
-    nodeId?: string;
-    workspace?: string;
-    metadataEvent: Record<string, unknown>;
-    queuedAt: number;
-}
-
-function getPendingEventsPath(meshId: string): string {
-    const safe = meshId.replace(/[^a-zA-Z0-9_-]/g, '_');
-    return join(getLedgerDir(), `${safe}.pending-events.jsonl`);
-}
-
-export function queuePendingMeshCoordinatorEvent(event: PendingMeshCoordinatorEvent): boolean {
-    try {
-        appendFileSync(getPendingEventsPath(event.meshId), JSON.stringify(event) + '\n', 'utf-8');
-        return true;
-    } catch (e: any) {
-        LOG.warn('MeshEvents', `Failed to persist pending coordinator event: ${e?.message || e}`);
-        return false;
-    }
-}
-
-/** Drain and return all pending coordinator events for meshId, removing them from disk. */
-export function drainPendingMeshCoordinatorEvents(meshId?: string): PendingMeshCoordinatorEvent[] {
-    if (!meshId) return [];
-    const path = getPendingEventsPath(meshId);
-    if (!existsSync(path)) return [];
-    try {
-        const raw = readFileSync(path, 'utf-8');
-        try { unlinkSync(path); } catch { /* concurrent drain already removed it */ }
-        return raw.split('\n').filter(Boolean).flatMap(line => {
-            try { return [JSON.parse(line) as PendingMeshCoordinatorEvent]; } catch { return []; }
-        });
-    } catch { return []; }
-}
-
-/** Peek at pending coordinator events without draining (non-destructive). */
-export function getPendingMeshCoordinatorEvents(meshId?: string): readonly PendingMeshCoordinatorEvent[] {
-    if (!meshId) return [];
-    const path = getPendingEventsPath(meshId);
-    if (!existsSync(path)) return [];
-    try {
-        const raw = readFileSync(path, 'utf-8');
-        return raw.split('\n').filter(Boolean).flatMap(line => {
-            try { return [JSON.parse(line) as PendingMeshCoordinatorEvent]; } catch { return []; }
-        });
-    } catch { return []; }
-}
-
-/** Explicitly clear all pending coordinator events for a mesh. */
-export function clearPendingMeshCoordinatorEvents(meshId?: string): void {
-    if (!meshId) return;
-    const path = getPendingEventsPath(meshId);
-    if (existsSync(path)) try { unlinkSync(path); } catch { /* already removed */ }
-}
-
-function readNonEmptyString(value: unknown): string {
-    return typeof value === 'string' && value.trim() ? value.trim() : '';
-}
-
-function resolveEventSessionId(event: Record<string, unknown>, fallback?: unknown): string {
-    return readNonEmptyString(event.targetSessionId)
-        || readNonEmptyString(event.sessionId)
-        || readNonEmptyString(event.instanceId)
-        || readNonEmptyString(fallback);
-}
-
-const MESH_COORDINATOR_EVENTS = new Set([
-    'agent:generating_started',
-    'agent:generating_completed',
-    'agent:waiting_approval',
-    'agent:stopped',
-    'agent:ready',
-    'monitor:long_generating',
-]);
-
-const EVENT_TO_LEDGER_KIND: Record<string, MeshLedgerKind> = {
-    'agent:generating_completed': 'task_completed',
-    'agent:waiting_approval': 'task_approval_needed',
-    'agent:stopped': 'task_failed',
-    'monitor:long_generating': 'task_stalled',
-};
-
-function isMeshCoordinatorEvent(eventName: unknown): eventName is string {
-    return typeof eventName === 'string' && MESH_COORDINATOR_EVENTS.has(eventName);
-}
-
-function formatCompletionMetadata(event: Record<string, unknown>): string {
-    const parts = [
-        readNonEmptyString(event.targetSessionId) ? `session_id=${readNonEmptyString(event.targetSessionId)}` : '',
-        readNonEmptyString(event.providerType) ? `provider=${readNonEmptyString(event.providerType)}` : '',
-        readNonEmptyString(event.providerSessionId) ? `provider_session_id=${readNonEmptyString(event.providerSessionId)}` : '',
-    ].filter(Boolean);
-    return parts.length > 0 ? ` (${parts.join('; ')})` : '';
-}
-
-function getMeshWithCache(components: DaemonComponents, meshId: string): any | undefined {
-    const localMesh = getMesh(meshId);
-    if (localMesh) return localMesh;
-    return components.router?.getCachedInlineMesh(meshId);
-}
-
-const INTENTIONAL_CLEANUP_STOP_SUPPRESSION_MS = 30 * 60 * 1000;
-
-function isIntentionalCleanupStopMetadata(event: Record<string, unknown>): boolean {
-    return event.intentional === true
-        || event.intentionalStop === true
-        || event.operatorCleanup === true
-        || event.reason === 'operator_cleanup'
-        || event.stopReason === 'operator_cleanup'
-        || event.cleanupReason === 'operator_cleanup'
-        || event.source === 'mesh_cleanup_sessions'
-        || event.source === 'mesh_remove_node';
-}
-
-function hasRecentIntentionalCleanupStop(meshId: string, sessionId?: string, nodeId?: string): boolean {
-    if (!sessionId && !nodeId) return false;
-    const cutoff = Date.now() - INTENTIONAL_CLEANUP_STOP_SUPPRESSION_MS;
-    const entries = readLedgerEntries(meshId);
-    for (let i = entries.length - 1; i >= 0; i--) {
-        const entry = entries[i];
-        const timestamp = new Date(entry.timestamp).getTime();
-        if (!Number.isNaN(timestamp) && timestamp < cutoff) break;
-        if (!isIntentionalCleanupStopEntry(entry)) continue;
-        if (sessionId && entry.sessionId === sessionId) return true;
-        if (!sessionId && nodeId && entry.nodeId === nodeId) return true;
-    }
-    return false;
-}
-
-function shouldSuppressIntentionalCleanupStop(args: {
-    event: string;
-    meshId: string;
-    metadataEvent: Record<string, unknown>;
-    sessionId?: string;
-    nodeId?: string;
-}): boolean {
-    if (args.event !== 'agent:stopped' && args.event !== 'monitor:long_generating') return false;
-    if (isIntentionalCleanupStopMetadata(args.metadataEvent)) return true;
-    return hasRecentIntentionalCleanupStop(args.meshId, args.sessionId, args.nodeId);
-}
-
-const RECENT_COMPLETION_FINGERPRINT_TTL_MS = 10 * 60 * 1000;
-const recentCompletionFingerprints = new Map<string, number>();
-
-function readEventTimestamp(value: unknown): number | null {
-    if (typeof value === 'number' && Number.isFinite(value)) return value;
-    if (typeof value === 'string' && value.trim()) {
-        const numeric = Number(value);
-        if (Number.isFinite(numeric)) return numeric;
-        const parsed = Date.parse(value);
-        if (Number.isFinite(parsed)) return parsed;
-    }
-    return null;
-}
-
-function buildMeshCompletionFingerprint(args: {
-    meshId: string;
-    event: string;
-    sessionId: string;
-    providerType?: string;
-    providerSessionId?: string;
-    timestamp?: number | null;
-    finalSummary?: string;
-}): string {
-    const timestampPart = Number.isFinite(args.timestamp)
-        ? String(args.timestamp)
-        : readNonEmptyString(args.finalSummary).slice(0, 200);
-    return [
-        args.meshId,
-        args.event,
-        args.sessionId,
-        args.providerType || '',
-        args.providerSessionId || '',
-        timestampPart,
-    ].join('::');
-}
-
-function isDuplicateMeshCompletionEvent(args: {
-    meshId: string;
-    event: string;
-    sessionId: string;
-    providerType?: string;
-    providerSessionId?: string;
-    timestamp?: number | null;
-    finalSummary?: string;
-}): boolean {
-    const fingerprint = buildMeshCompletionFingerprint(args);
-    if (!fingerprint) return false;
-    const now = Date.now();
-    for (const [key, seenAt] of recentCompletionFingerprints.entries()) {
-        if (now - seenAt > RECENT_COMPLETION_FINGERPRINT_TTL_MS) recentCompletionFingerprints.delete(key);
-    }
-    if (recentCompletionFingerprints.has(fingerprint)) return true;
-    recentCompletionFingerprints.set(fingerprint, now);
-    return false;
-}
-
-
-export function tryAssignQueueTask(
-    components: DaemonComponents,
-    meshId: string,
-    nodeId: string,
-    sessionId: string,
-    providerType: string
-): boolean {
-    const task = claimNextTask(meshId, nodeId, sessionId);
-    if (!task) {
-        return false;
-    }
-
-    LOG.info('MeshQueue', `Node ${nodeId} (${sessionId}) pulled task ${task.id}`);
-
-    // Check if the node is remote
-    const mesh = getMeshWithCache(components, meshId);
-    const node = mesh?.nodes.find((n: any) => n.id === nodeId);
-    
-    // If the node is explicitly remote and we have a dispatch mechanism, route via P2P
-    if (node?.daemonId && components.dispatchMeshCommand) {
-        const isLocalNode = components.cliManager.adapters.has(sessionId);
-        if (!isLocalNode) {
-            components.dispatchMeshCommand(node.daemonId, 'agent_command', {
-                targetSessionId: sessionId,
-                cliType: providerType,
-                action: 'send_chat',
-                message: task.message,
-            }).catch((e: any) => {
-                LOG.error('MeshQueue', `Failed to dispatch task via P2P to remote node ${nodeId}: ${e?.message}`);
-                // Revert to pending so the task can be retried rather than permanently failing
-                updateTaskStatus(meshId, task.id, 'pending');
-                try {
-                    appendLedgerEntry(meshId, {
-                        kind: 'dispatch_failed' as any,
-                        nodeId,
-                        sessionId,
-                        payload: { taskId: task.id, error: e?.message, retryable: true },
-                    });
-                } catch { /* ledger write is best-effort */ }
-            });
-            return true;
-        }
-    }
-
-    // Local routing
-    components.cliManager.handleCliCommand('agent_command', {
-        targetSessionId: sessionId,
-        cliType: providerType,
-        action: 'send_chat',
-        message: task.message,
-    }).catch((e: any) => {
-        LOG.error('MeshQueue', `Failed to dispatch task locally to node ${nodeId}: ${e?.message}`);
-        updateTaskStatus(meshId, task.id, 'failed');
-    });
-
-    return true;
-}
-
-const autoLaunchInProgress = new Set<string>();
-const autoLaunchCooldownUntil = new Map<string, number>();
-const AUTO_LAUNCH_COOLDOWN_MS = 5_000;
-
-function normalizeProviderPriority(policy: unknown): string[] {
-    const raw = policy && typeof policy === 'object' && !Array.isArray(policy)
-        ? (policy as Record<string, unknown>).providerPriority
-        : undefined;
-    if (!Array.isArray(raw)) return [];
-    const seen = new Set<string>();
-    return raw
-        .map(type => typeof type === 'string' ? type.trim() : '')
-        .filter(Boolean)
-        .filter(type => {
-            if (seen.has(type)) return false;
-            seen.add(type);
-            return true;
-        });
-}
-
-function isTerminalSessionStatus(status: string): boolean {
-    return ['stopped', 'failed', 'terminated', 'exited', 'closed'].includes(status);
-}
-
-function isIdleSessionState(state: any): boolean {
-    const status = readNonEmptyString(state?.status).toLowerCase();
-    if (isTerminalSessionStatus(status)) return false;
-    return status === 'idle' || state?.activeChat?.status === 'waiting_input';
-}
-
-function isDirtyNode(node: any): boolean {
-    return node?.health === 'dirty' || node?.git?.dirty === true;
-}
-
-function isLaunchableNode(node: any): boolean {
-    if (!node || node.status === 'disabled' || node.status === 'removed') return false;
-    const health = readNonEmptyString(node.health).toLowerCase();
-    if (!health) return true;
-    return health === 'online' || health === 'unknown';
-}
-
-function localAutoLaunchSkipReason(node: any): string | null {
-    const daemonId = readNonEmptyString(node?.daemonId);
-    const machineId = readNonEmptyString(node?.machineId);
-    const appConfig = loadConfig();
-    const localMachineId = readNonEmptyString(appConfig.machineId) || readNonEmptyString(appConfig.registeredMachineId);
-    const cloudDaemonId = localMachineId ? `daemon_${localMachineId}` : '';
-    const standaloneDaemonId = localMachineId ? `standalone_${localMachineId}` : '';
-
-    const daemonMatchesLocal = !daemonId || daemonId === cloudDaemonId || daemonId === standaloneDaemonId;
-    const machineMatchesLocal = !machineId || (localMachineId && machineId === localMachineId);
-
-    // ADHDev-managed local worktrees are explicitly safe to launch locally, but
-    // still must not be auto-launched if their metadata points at another
-    // daemon/machine. Remote nodes require an explicit coordinator launch path.
-    if (node?.isLocalWorktree === true) {
-        return daemonMatchesLocal && machineMatchesLocal ? null : 'remote_auto_launch_unsupported';
-    }
-
-    // Legacy/local workspace nodes may not have daemon/machine metadata. If
-    // metadata is present, require it to identify this daemon/machine before
-    // using the local cliManager.launch_cli path.
-    if (daemonId || machineId) {
-        return daemonMatchesLocal && machineMatchesLocal ? null : 'remote_auto_launch_unsupported';
-    }
-
-    return null;
-}
-
-function activeAssignedCount(meshId: string): number {
-    return getQueue(meshId, { status: ['assigned'] as any }).length;
-}
-
-function nodeHasActiveAssignment(meshId: string, nodeId: string): boolean {
-    return getQueue(meshId, { status: ['assigned'] as any }).some(task => task.assignedNodeId === nodeId);
-}
-
-function liveSessionCountForNode(components: DaemonComponents, meshId: string, nodeId: string): number {
-    return components.instanceManager.getByCategory('cli').filter((inst: any) => {
-        const state = inst.getState();
-        const settings = state.settings as Record<string, unknown> || {};
-        if (readNonEmptyString(settings.meshNodeFor) !== meshId) return false;
-        const instNodeId = readNonEmptyString(settings.meshNodeId) || readNonEmptyString(settings.nodeId);
-        if (instNodeId !== nodeId) return false;
-        const status = readNonEmptyString(state.status).toLowerCase();
-        return !isTerminalSessionStatus(status);
-    }).length;
-}
-
-function recordAutoLaunchEvent(meshId: string, args: {
-    phase: 'skipped' | 'started' | 'failed' | 'completed';
-    taskId: string;
-    nodeId?: string;
-    providerType?: string;
-    sessionId?: string;
-    reason?: string;
-    error?: string;
-}) {
-    try {
-        appendLedgerEntry(meshId, {
-            kind: 'session_auto_launch',
-            nodeId: args.nodeId,
-            sessionId: args.sessionId,
-            providerType: args.providerType,
-            payload: {
-                phase: args.phase,
-                taskId: args.taskId,
-                reason: args.reason,
-                error: args.error,
-            },
-        });
-    } catch (e: any) {
-        LOG.warn('MeshQueue', `Failed to record auto-launch ledger event: ${e?.message || e}`);
-    }
-}
-
-function markAutoLaunch(meshId: string, taskId: string, args: {
-    status: 'skipped' | 'started' | 'failed' | 'completed';
-    reason?: string;
-    nodeId?: string;
-    providerType?: string;
-    sessionId?: string;
-    error?: string;
-}) {
-    recordTaskAutoLaunch(meshId, taskId, {
-        status: args.status,
-        reason: args.reason || args.error,
-        nodeId: args.nodeId,
-        providerType: args.providerType,
-        sessionId: args.sessionId,
-    });
-    recordAutoLaunchEvent(meshId, {
-        phase: args.status,
-        taskId,
-        nodeId: args.nodeId,
-        providerType: args.providerType,
-        sessionId: args.sessionId,
-        reason: args.reason,
-        error: args.error,
-    });
-}
-
-async function resolveUsableProvider(components: DaemonComponents, nodeId: string, node: any): Promise<{ providerType?: string; reason?: string }> {
-    const providerPriority = normalizeProviderPriority(node?.policy);
-    if (!providerPriority.length) return { reason: 'missing_provider_priority' };
-    const providerLoader = components.providerLoader;
-    if (!providerLoader) return { reason: 'provider_loader_unavailable' };
-
-    const failed: string[] = [];
-    for (const requestedType of providerPriority) {
-        const normalizedType = typeof providerLoader.resolveAlias === 'function'
-            ? providerLoader.resolveAlias(requestedType)
-            : requestedType;
-        if (typeof providerLoader.isMachineProviderEnabled === 'function' && !providerLoader.isMachineProviderEnabled(normalizedType)) {
-            failed.push(`${requestedType}: disabled`);
-            continue;
-        }
-        let detected: any;
-        try {
-            detected = await detectCLI(normalizedType, providerLoader, { includeVersion: false });
-        } catch (e: any) {
-            failed.push(`${requestedType}: detect failed: ${e?.message || e}`);
-            continue;
-        }
-        if (typeof providerLoader.setCliDetectionResults === 'function') {
-            providerLoader.setCliDetectionResults([{
-                id: normalizedType,
-                installed: !!detected,
-                path: detected?.path,
-            }], false);
-        }
-        (components as any).onStatusChange?.();
-        if (detected) return { providerType: normalizedType };
-        failed.push(`${requestedType}: not detected`);
-    }
-    return { reason: `provider_priority_unusable: ${failed.join('; ') || nodeId}` };
-}
-
-async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, meshId: string, mesh: any): Promise<boolean> {
-    const queue = getQueue(meshId);
-    const pending = queue.filter(task => task.status === 'pending');
-    if (!pending.length) return false;
-
-    const maxParallelTasks = Math.max(1, Math.floor(Number(mesh?.policy?.maxParallelTasks) || 2));
-    for (const task of pending) {
-        if (activeAssignedCount(meshId) >= maxParallelTasks) {
-            markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'max_parallel_tasks_reached' });
-            return false;
-        }
-        if (task.targetSessionId) {
-            markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'target_session_constraint' });
-            continue;
-        }
-
-        const candidateNodes = Array.isArray(mesh?.nodes)
-            ? mesh.nodes.filter((node: any) => task.targetNodeId ? node?.id === task.targetNodeId : true)
-            : [];
-        if (!candidateNodes.length) {
-            markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'no_matching_node', nodeId: task.targetNodeId });
-            continue;
-        }
-
-        for (const node of candidateNodes) {
-            const nodeId = readNonEmptyString(node?.id);
-            if (!nodeId) continue;
-            const launchKey = `${meshId}:${nodeId}`;
-            const cooldownUntil = autoLaunchCooldownUntil.get(launchKey) || 0;
-            if (autoLaunchInProgress.has(launchKey)) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'auto_launch_in_progress', nodeId });
-                continue;
-            }
-            if (Date.now() < cooldownUntil) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'auto_launch_cooldown', nodeId });
-                continue;
-            }
-            if (isDirtyNode(node)) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'dirty_workspace', nodeId });
-                continue;
-            }
-            if (!isLaunchableNode(node)) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_not_launch_ready', nodeId });
-                continue;
-            }
-            const localSkipReason = localAutoLaunchSkipReason(node);
-            if (localSkipReason) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: localSkipReason, nodeId });
-                continue;
-            }
-            if (nodeHasActiveAssignment(meshId, nodeId)) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_has_active_assignment', nodeId });
-                continue;
-            }
-            const maxConcurrentSessions = Number(node?.policy?.maxConcurrentSessions);
-            if (Number.isFinite(maxConcurrentSessions) && maxConcurrentSessions >= 0 && liveSessionCountForNode(components, meshId, nodeId) >= maxConcurrentSessions) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'max_concurrent_sessions_reached', nodeId });
-                continue;
-            }
-
-            autoLaunchInProgress.add(launchKey);
-            try {
-                const resolved = await resolveUsableProvider(components, nodeId, node);
-                if (!resolved.providerType) {
-                    markAutoLaunch(meshId, task.id, { status: 'skipped', reason: resolved.reason || 'provider_unusable', nodeId });
-                    continue;
-                }
-
-                markAutoLaunch(meshId, task.id, { status: 'started', nodeId, providerType: resolved.providerType });
-                const launchResult: any = await components.cliManager.handleCliCommand('launch_cli', {
-                    cliType: resolved.providerType,
-                    dir: node.workspace,
-                    settings: {
-                        meshNodeFor: meshId,
-                        meshNodeId: nodeId,
-                        spawnedSessionVisibility: mesh?.policy?.spawnedSessionVisibility || 'hidden',
-                        launchedByCoordinator: true,
-                        autoLaunchedForQueueTaskId: task.id,
-                    },
-                });
-                if (!launchResult?.success) {
-                    const reason = launchResult?.error || 'launch_cli_failed';
-                    markAutoLaunch(meshId, task.id, { status: 'failed', reason, nodeId, providerType: resolved.providerType });
-                    autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS);
-                    return false;
-                }
-                const sessionId = readNonEmptyString(launchResult.sessionId) || readNonEmptyString(launchResult.id) || readNonEmptyString(launchResult.runtimeSessionId);
-                if (!sessionId) {
-                    markAutoLaunch(meshId, task.id, { status: 'failed', reason: 'launch_missing_session_id', nodeId, providerType: resolved.providerType });
-                    autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS);
-                    return false;
-                }
-                markAutoLaunch(meshId, task.id, { status: 'completed', nodeId, providerType: resolved.providerType, sessionId });
-                tryAssignQueueTask(components, meshId, nodeId, sessionId, resolved.providerType);
-                return true;
-            } catch (e: any) {
-                markAutoLaunch(meshId, task.id, { status: 'failed', error: e?.message || String(e), nodeId });
-                autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS);
-                return false;
-            } finally {
-                autoLaunchInProgress.delete(launchKey);
-            }
-        }
-    }
-    return false;
-}
-
-/**
- * Triggers a queue check for all nodes in the mesh.
- * Called when a new task is enqueued, in case nodes are already idle.
- */
-export async function triggerMeshQueue(components: DaemonComponents, meshId: string): Promise<void> {
-    const mesh = getMeshWithCache(components, meshId);
-    if (!mesh) return;
-
-    // Find all CLI instances that belong to this mesh and are idle
-    const cliInstances = components.instanceManager.getByCategory('cli');
-    for (const inst of cliInstances) {
-        const state = inst.getState();
-        const settings = state.settings as Record<string, unknown> || {};
-        
-        const instMeshId = readNonEmptyString(settings.meshNodeFor);
-        if (instMeshId !== meshId) continue;
-
-        const nodeId = readNonEmptyString(settings.meshNodeId) || readNonEmptyString(settings.nodeId);
-        if (!nodeId) continue;
-
-        // Only genuinely idle live sessions can pull work. Restored/stopped
-        // records are kept for transcript/recovery visibility, but assigning
-        // queue items to them strands tasks in assigned/pending without chat.
-        if (!isIdleSessionState(state)) continue;
-
-        const sessionId = state.instanceId;
-        const providerType = state.type || readNonEmptyString(settings.providerType);
-        
-        if (providerType) {
-            // Try to assign a task to this idle node
-            tryAssignQueueTask(components, meshId, nodeId, sessionId, providerType);
-        }
-    }
-
-    // Also check known idle remote sessions
-    for (const [key, idle] of remoteIdleSessions.entries()) {
-        // Find if this node is in the same mesh
-        const node = mesh.nodes.find((n: any) => n.id === idle.nodeId);
-        if (node) {
-            const assigned = tryAssignQueueTask(components, meshId, idle.nodeId, idle.sessionId, idle.providerType);
-            if (assigned) {
-                remoteIdleSessions.delete(key);
-            }
-        }
-    }
-
-    await maybeAutoLaunchOneQueueSession(components, meshId, mesh);
-}
-
-function buildMeshSystemMessage(args: {
-    event: string;
-    nodeLabel: string;
-    metadataEvent: Record<string, unknown>;
-    recoveryContext?: SessionRecoveryContext | null;
-}): string {
-    const metadata = formatCompletionMetadata(args.metadataEvent);
-    if (args.event === 'agent:generating_completed') {
-        return `[System] ${args.nodeLabel} has completed its task and is now idle${metadata}. This completion came from the agent status event path; use mesh_read_chat once to review its final progress, but do not poll repeatedly.`;
-    }
-    if (args.event === 'agent:waiting_approval') {
-        return `[System] ${args.nodeLabel} is waiting for approval to proceed${metadata}. You may use mesh_read_chat and mesh_approve to handle it.`;
-    }
-    if (args.event === 'agent:stopped') {
-        const rc = args.recoveryContext;
-        if (rc && rc.consecutiveNodeFailures > 0) {
-            const parts = [
-                `[System] ${args.nodeLabel} has stopped unexpectedly${metadata}.`,
-                `\n\n**Recovery Context:**`,
-                `- Consecutive failures on this node: ${rc.consecutiveNodeFailures}`,
-                rc.taskAttemptCount > 0 ? `- This task has been attempted ${rc.taskAttemptCount} time(s)` : '',
-                `- Recommendation: ${rc.advice}`,
-            ];
-            if (rc.retryRecommended && rc.lastTaskMessage) {
-                parts.push(
-                    `\n\n**Original task to retry:**`,
-                    `> ${rc.lastTaskMessage.length > 300 ? rc.lastTaskMessage.slice(0, 300) + '...' : rc.lastTaskMessage}`,
-                    `\nTo retry: call \`mesh_launch_session\` for this node, then \`mesh_send_task\` with the original task.`,
-                );
-            } else if (!rc.retryRecommended) {
-                parts.push(
-                    `\nDo NOT retry on this node. Consider reassigning to a different node or asking the user for guidance.`,
-                );
-            }
-            return parts.filter(Boolean).join('\n');
-        }
-        return `[System] ${args.nodeLabel} has stopped${metadata}. Use mesh_read_chat once if you need to inspect its last output.`;
-    }
-    if (args.event === 'monitor:long_generating') {
-        return `[System] ${args.nodeLabel} has been generating for a long time${metadata}. Use mesh_read_chat once for a status check, but do not poll repeatedly.`;
-    }
-    return '';
-}
-
-function injectMeshSystemMessage(components: DaemonComponents, args: {
-    meshId: string;
-    sourceInstanceId?: string;
-    nodeId?: string;
-    nodeLabel: string;
-    event: string;
-    metadataEvent: Record<string, unknown>;
-}) {
-    const eventSessionId = resolveEventSessionId(args.metadataEvent, args.sourceInstanceId);
-    const eventNodeId = readNonEmptyString(args.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId);
-    const intentionalCleanupStop = shouldSuppressIntentionalCleanupStop({
-        event: args.event,
-        meshId: args.meshId,
-        metadataEvent: args.metadataEvent,
-        sessionId: eventSessionId || undefined,
-        nodeId: eventNodeId || undefined,
-    });
-    if (intentionalCleanupStop) {
-        if (eventSessionId && eventNodeId) {
-            remoteIdleSessions.delete(`${eventNodeId}:${eventSessionId}`);
-        }
-        LOG.info('MeshEvents', `Suppressed ${args.event} for intentionally cleanup-stopped session ${eventSessionId || '(unknown session)'}`);
-        return { success: true, forwarded: 0, suppressed: true, intentionalCleanupStop: true };
-    }
-
-    const eventTimestamp = readEventTimestamp(args.metadataEvent.timestamp);
-    if (args.event === 'agent:generating_completed' && eventSessionId) {
-        const duplicateCompletion = isDuplicateMeshCompletionEvent({
-            meshId: args.meshId,
-            event: args.event,
-            sessionId: eventSessionId,
-            providerType: readNonEmptyString(args.metadataEvent.providerType) || undefined,
-            providerSessionId: readNonEmptyString(args.metadataEvent.providerSessionId) || undefined,
-            timestamp: eventTimestamp,
-            finalSummary: readNonEmptyString(args.metadataEvent.finalSummary) || undefined,
-        });
-        if (duplicateCompletion) {
-            LOG.info('MeshEvents', `Suppressed duplicate completion for mesh ${args.meshId} session ${eventSessionId}`);
-            return { success: true, forwarded: 0, suppressed: true, duplicateCompletion: true };
-        }
-    }
-
-    // ── Task Queue & Ledger ──
-    let completedTaskForLedger: { id?: string } | null = null;
-    if (args.event === 'agent:generating_completed') {
-        const sessionId = resolveEventSessionId(args.metadataEvent, args.sourceInstanceId);
-        const nodeId = readNonEmptyString(args.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId);
-        const providerType = readNonEmptyString(args.metadataEvent.providerType);
-        
-        if (sessionId) {
-            const completedTask = updateSessionTaskStatus(args.meshId, sessionId, 'completed', {
-                occurredAt: eventTimestamp !== null ? new Date(eventTimestamp).toISOString() : undefined,
-            });
-            completedTaskForLedger = completedTask ? { id: completedTask.id } : null;
-            if (nodeId && providerType) {
-                // Queue state is already updated above; setImmediate avoids the
-                // 500 ms artificial delay while still deferring past this call frame.
-                setImmediate(() => {
-                    tryAssignQueueTask(components, args.meshId, nodeId, sessionId, providerType);
-                });
-            }
-        }
-    } else if (args.event === 'agent:ready') {
-        const sessionId = resolveEventSessionId(args.metadataEvent, args.sourceInstanceId);
-        const nodeId = readNonEmptyString(args.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId);
-        const providerType = readNonEmptyString(args.metadataEvent.providerType);
-        const completedTask = sessionId
-            ? updateSessionTaskStatus(args.meshId, sessionId, 'completed')
-            : null;
-        if (completedTask) {
-            completedTaskForLedger = { id: completedTask.id };
-            try {
-                appendLedgerEntry(args.meshId, {
-                    kind: 'task_completed',
-                    nodeId: nodeId || undefined,
-                    sessionId,
-                    providerType: providerType || undefined,
-                    payload: {
-                        event: args.event,
-                        nodeLabel: args.nodeLabel,
-                        taskId: completedTask.id,
-                        completedViaReady: true,
-                        providerSessionId: readNonEmptyString(args.metadataEvent.providerSessionId) || undefined,
-                        finalSummary: readNonEmptyString(args.metadataEvent.finalSummary) || undefined,
-                        evidence: buildTaskCompletionEvidence({
-                            event: 'agent:ready',
-                            nodeId,
-                            sessionId,
-                            providerType: providerType || undefined,
-                            providerSessionId: readNonEmptyString(args.metadataEvent.providerSessionId) || undefined,
-                            finalSummary: readNonEmptyString(args.metadataEvent.finalSummary) || undefined,
-                        }),
-                    },
-                });
-            } catch (e: any) {
-                LOG.warn('MeshLedger', `Failed to record task_completed from ready: ${e?.message || e}`);
-            }
-        }
-        
-        if (sessionId && nodeId && providerType) {
-            sweepExpiredRemoteIdleSessions();
-            remoteIdleSessions.set(`${nodeId}:${sessionId}`, {
-                nodeId, sessionId, providerType,
-                expiresAt: Date.now() + REMOTE_IDLE_SESSION_TTL_MS,
-            });
-            setImmediate(() => {
-                const assigned = tryAssignQueueTask(components, args.meshId, nodeId, sessionId, providerType);
-                if (assigned) remoteIdleSessions.delete(`${nodeId}:${sessionId}`);
-            });
-        }
-    } else if (args.event === 'agent:generating_started') {
-        const sessionId = resolveEventSessionId(args.metadataEvent, args.sourceInstanceId);
-        const nodeId = readNonEmptyString(args.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId);
-        if (sessionId && nodeId) {
-            remoteIdleSessions.delete(`${nodeId}:${sessionId}`);
-        }
-    } else if (args.event === 'agent:stopped') {
-        const sessionId = resolveEventSessionId(args.metadataEvent, args.sourceInstanceId);
-        const nodeId = readNonEmptyString(args.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId);
-        if (sessionId && nodeId) {
-            remoteIdleSessions.delete(`${nodeId}:${sessionId}`);
-        }
-        if (sessionId) {
-            updateSessionTaskStatus(args.meshId, sessionId, 'failed');
-        }
-    }
-
-    const ledgerKind = EVENT_TO_LEDGER_KIND[args.event];
-    if (ledgerKind) {
-        try {
-            const ledgerNodeId = readNonEmptyString(args.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId) || undefined;
-            const ledgerSessionId = resolveEventSessionId(args.metadataEvent, args.sourceInstanceId) || undefined;
-            const ledgerProviderType = readNonEmptyString(args.metadataEvent.providerType) || undefined;
-            const completionEvidence = ledgerKind === 'task_completed' && ledgerNodeId && ledgerSessionId
-                ? buildTaskCompletionEvidence({
-                    event: 'agent:generating_completed',
-                    nodeId: ledgerNodeId,
-                    sessionId: ledgerSessionId,
-                    providerType: ledgerProviderType,
-                    providerSessionId: readNonEmptyString(args.metadataEvent.providerSessionId) || undefined,
-                    finalSummary: readNonEmptyString(args.metadataEvent.finalSummary) || undefined,
-                })
-                : undefined;
-            appendLedgerEntry(args.meshId, {
-                kind: ledgerKind,
-                nodeId: ledgerNodeId,
-                sessionId: ledgerSessionId,
-                providerType: ledgerProviderType,
-                payload: {
-                    event: args.event,
-                    nodeLabel: args.nodeLabel,
-                    taskId: completedTaskForLedger?.id || undefined,
-                    providerSessionId: readNonEmptyString(args.metadataEvent.providerSessionId) || undefined,
-                    finalSummary: readNonEmptyString(args.metadataEvent.finalSummary) || undefined,
-                    evidence: completionEvidence,
-                },
-            });
-        } catch (e: any) {
-            LOG.warn('MeshLedger', `Failed to record ${ledgerKind}: ${e?.message || e}`);
-        }
-    }
-
-    // ── Recovery Context: enrich agent:stopped with retry intelligence ──
-    let recoveryContext: SessionRecoveryContext | null = null;
-    if (args.event === 'agent:stopped') {
-        try {
-            // Resolve maxTaskRetries from mesh policy
-            const mesh = getMesh(args.meshId);
-            const maxRetries = mesh?.policy?.maxTaskRetries ?? 1;
-
-            recoveryContext = getSessionRecoveryContext(args.meshId, {
-                sessionId: resolveEventSessionId(args.metadataEvent, args.sourceInstanceId) || undefined,
-                nodeId: readNonEmptyString(args.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId) || undefined,
-                maxRetries,
-            });
-            recoveryContext.failedProviderType = readNonEmptyString(args.metadataEvent.providerType) || null;
-
-            // Record recovery_attempted if retry is recommended
-            if (recoveryContext.retryRecommended && recoveryContext.consecutiveNodeFailures > 0) {
-                appendLedgerEntry(args.meshId, {
-                    kind: 'recovery_attempted',
-                    nodeId: recoveryContext.failedNodeId || undefined,
-                    sessionId: recoveryContext.failedSessionId || undefined,
-                    providerType: recoveryContext.failedProviderType || undefined,
-                    payload: {
-                        consecutiveFailures: recoveryContext.consecutiveNodeFailures,
-                        taskAttemptCount: recoveryContext.taskAttemptCount,
-                        retryRecommended: recoveryContext.retryRecommended,
-                        advice: recoveryContext.advice,
-                    },
-                });
-
-                // Auto-Recovery (Phase 5): Automatically re-enqueue the task and re-launch the session
-                if (recoveryContext.lastTaskMessage && recoveryContext.failedNodeId && recoveryContext.failedProviderType) {
-                    const autoNodeId = recoveryContext.failedNodeId;
-                    try {
-                        const task = enqueueTask(args.meshId, recoveryContext.lastTaskMessage, {
-                            targetNodeId: autoNodeId
-                        });
-                        LOG.info('MeshRecovery', `Auto-requeued failed task: ${task.id} for node ${autoNodeId}`);
-
-                        const node = mesh?.nodes.find(n => n.id === autoNodeId);
-                        if (node) {
-                            components.cliManager.handleCliCommand('launch_cli', {
-                                cliType: recoveryContext.failedProviderType,
-                                dir: node.workspace,
-                                settings: {
-                                    meshNodeFor: args.meshId,
-                                    meshNodeId: node.id,
-                                    spawnedSessionVisibility: mesh?.policy?.spawnedSessionVisibility || 'hidden',
-                                    launchedByCoordinator: true,
-                                }
-                            }).catch((e: any) => LOG.error('MeshRecovery', `Failed to auto-relaunch session for ${node.id}: ${e?.message}`));
-                        }
-                    } catch (e: any) {
-                        LOG.warn('MeshRecovery', `Failed to execute auto-recovery: ${e?.message}`);
-                    }
-                }
-            }
-
-            LOG.info('MeshRecovery', `Recovery context for ${args.nodeLabel}: ${recoveryContext.advice}`);
-        } catch (e: any) {
-            LOG.warn('MeshRecovery', `Failed to build recovery context: ${e?.message || e}`);
-        }
-    }
-
-    const coordinatorInstances = components.instanceManager.getByCategory('cli').filter((inst) => {
-        const instState = inst.getState();
-        if (instState.settings?.meshCoordinatorFor !== args.meshId) return false;
-        if (args.sourceInstanceId && instState.instanceId === args.sourceInstanceId) return false;
-        return true;
-    });
-
-    if (coordinatorInstances.length === 0) {
-        // No CLI coordinator session found — buffer for MCP-based coordinators.
-        if (queuePendingMeshCoordinatorEvent({
-                event: args.event,
-                meshId: args.meshId,
-                nodeLabel: args.nodeLabel,
-                nodeId: args.nodeId || undefined,
-                workspace: readNonEmptyString(args.metadataEvent.workspace),
-                metadataEvent: {
-                    ...args.metadataEvent,
-                    ...(recoveryContext ? { recoveryContext } : {}),
-                },
-                queuedAt: Date.now(),
-            })) {
-            LOG.info('MeshEvents', `Queued ${args.event} for MCP coordinator (mesh ${args.meshId})`);
-        }
-        return { success: true, forwarded: 0 };
-    }
-
-    const messageText = buildMeshSystemMessage({
-        event: args.event,
-        nodeLabel: args.nodeLabel,
-        metadataEvent: args.metadataEvent,
-        recoveryContext,
-    });
-    if (!messageText) return { success: false, error: 'unsupported mesh event' };
-
-    for (const coord of coordinatorInstances) {
-        const coordState = coord.getState();
-        LOG.info('MeshEvents', `Forwarding mesh event to coordinator ${coordState.instanceId}`);
-        coord.onEvent('send_message', { input: { text: messageText, textFallback: messageText } });
-    }
-    return { success: true, forwarded: coordinatorInstances.length };
-}
-
-export function handleMeshForwardEvent(components: DaemonComponents, payload: Record<string, unknown>) {
-    const eventName = readNonEmptyString(payload.event);
-    if (!isMeshCoordinatorEvent(eventName)) {
-        return { success: false, error: 'unsupported mesh event' };
-    }
-    const meshId = readNonEmptyString(payload.meshId);
-    if (!meshId) return { success: false, error: 'meshId required' };
-
-    const nodeId = readNonEmptyString(payload.nodeId);
-    const workspace = readNonEmptyString(payload.workspace);
-    const nodeLabel = nodeId ? `Node '${nodeId}'` : workspace ? `Agent at ${workspace}` : 'Remote agent';
-    return injectMeshSystemMessage(components, {
-        meshId,
-        nodeId,
-        nodeLabel,
-        event: eventName,
-        metadataEvent: {
-            targetSessionId: readNonEmptyString(payload.targetSessionId) || readNonEmptyString(payload.sessionId) || readNonEmptyString(payload.instanceId),
-            providerType: readNonEmptyString(payload.providerType),
-            providerSessionId: readNonEmptyString(payload.providerSessionId),
-            finalSummary: readNonEmptyString(payload.finalSummary) || readNonEmptyString(payload.summary),
-            ...(payload.timestamp !== undefined ? { timestamp: payload.timestamp } : {}),
-            intentional: payload.intentional === true,
-            intentionalStop: payload.intentionalStop === true,
-            operatorCleanup: payload.operatorCleanup === true,
-            reason: readNonEmptyString(payload.reason),
-            stopReason: readNonEmptyString(payload.stopReason),
-            cleanupReason: readNonEmptyString(payload.cleanupReason),
-            source: readNonEmptyString(payload.source),
-        },
-    });
-}
-
-export function setupMeshEventForwarding(components: DaemonComponents) {
-    components.instanceManager.onEvent((event) => {
-        // We only care about lightweight Repo Mesh coordinator control/status hints.
-        if (!isMeshCoordinatorEvent(event.event)) return;
-
-        const instanceId = readNonEmptyString(event.instanceId);
-        if (!instanceId) return;
-
-        // Try to find the workspace and mesh metadata of the sub-agent.
-        const sourceInstance = components.instanceManager.getInstance(instanceId);
-        if (!sourceInstance || sourceInstance.category !== 'cli') return;
-        const state = sourceInstance.getState();
-        const workspace = readNonEmptyString(state.workspace);
-        if (!workspace) return;
-        const settings = state.settings && typeof state.settings === 'object' ? state.settings as Record<string, unknown> : {};
-
-        // Coordinator sessions must never inject events into themselves.
-        // A coordinator instance carries meshCoordinatorFor but not meshNodeFor/launchedByCoordinator.
-        if (readNonEmptyString(settings.meshCoordinatorFor)) return;
-
-        const meshIdFromRuntime = readNonEmptyString(settings.meshNodeFor);
-
-        // Only forward events for sessions that were explicitly launched as mesh-node delegates
-        // (meshNodeFor set by mesh_launch_session) or that carry the launchedByCoordinator flag.
-        // Do NOT fall back to workspace-based mesh lookup: that would pick up coordinator sessions
-        // and any other CLI session that happens to share the same workspace, causing spurious
-        // system-message injection into the coordinator's own conversation.
-        const isMeshDelegate = Boolean(meshIdFromRuntime || settings.launchedByCoordinator);
-        if (!isMeshDelegate) return;
-
-        const mesh = meshIdFromRuntime ? getMeshWithCache(components, meshIdFromRuntime) : getMeshByRepo(workspace);
-        const meshId = meshIdFromRuntime || readNonEmptyString(mesh?.id);
-        if (!meshId) return;
-
-        // Determine node label. Inline/cloud meshes may be unavailable here, so preserve runtime node id.
-        const targetNode = mesh?.nodes?.find((n: any) => n.workspace === workspace);
-        const runtimeNodeId = readNonEmptyString(settings.meshNodeId);
-        const resolvedNodeId = targetNode?.id || runtimeNodeId;
-        const nodeLabel = targetNode
-            ? `Node '${targetNode.id}'`
-            : runtimeNodeId
-                ? `Node '${runtimeNodeId}'`
-                : `Agent at ${workspace}`;
-
-        injectMeshSystemMessage(components, {
-            meshId,
-            sourceInstanceId: instanceId,
-            nodeId: resolvedNodeId,
-            nodeLabel,
-            event: event.event,
-            metadataEvent: event,
-        });
-    });
-}
+export type {
+    PendingMeshCoordinatorEvent,
+    MeshHeldEventRequeueFilter,
+    MeshHeldEventRequeueResult,
+} from './mesh-events-pending.js';
+export {
+    queuePendingMeshCoordinatorEvent,
+    drainPendingMeshCoordinatorEvents,
+    getPendingMeshCoordinatorEvents,
+    clearPendingMeshCoordinatorEvents,
+    requeueHeldMeshCoordinatorEvents,
+    serializeV2EnvelopeToWire,
+    readV2EnvelopeFromWire,
+    getMeshV2DrainCounters,
+    isMeshProtocolV2EnforceEnabled,
+} from './mesh-events-pending.js';
+
+export {
+    reconcileDirectDispatchCompletionFromTranscript,
+} from './mesh-events-stale.js';
+
+export {
+    setupMeshReconcileLoop,
+    runMeshReconcileTick,
+    resolveCoordinatorDrainDeliverability,
+    shouldHoldPendingDrainForBusyLocalCoordinator,
+    getMeshV2BackstopCounters,
+} from './mesh-reconcile-loop.js';
+
+export type { MeshQueueTriggerResult } from './mesh-events-coordinator.js';
+export {
+    tryAssignQueueTask,
+    isSessionActivelyGenerating,
+    triggerMeshQueue,
+    handleMeshForwardEvent,
+    setupMeshEventForwarding,
+    isMeshCoordinatorEvent,
+    __resetIdleAutoFastForwardForTests,
+    __resetMeshWorkspaceCacheForTests,
+} from './mesh-events-coordinator.js';