@adhdev/daemon-core 0.9.82-rc.273 → 0.9.82-rc.275

package/src/mesh/mesh-events-pending.ts

@@ -4,7 +4,7 @@ import { randomUUID } from 'crypto';
 import { LOG } from '../logging/logger.js';
 import { getLedgerDir, readLedgerEntries } from './mesh-ledger.js';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
-import { buildMeshSystemMessage, canonicalDaemonId, readNonEmptyString, readRecord, resolveEventSessionId } from './mesh-events-utils.js';
+import { buildMeshSystemMessage, readNonEmptyString, readRecord, resolveEventSessionId } from './mesh-events-utils.js';
 
 // ---------------------------------------------------------------------------
 // MCP coordinator pending-event queue — FILE-BASED PERSISTENCE
@@ -83,46 +83,11 @@ export function buildPendingEventFingerprint(event: PendingMeshCoordinatorEvent)
     ].join('::');
 }
 
-// R3: TTL for the direct-delivered marker. A coordinator polls get_pending_mesh_events
-// well within this window after a terminal event; after it expires the marker is swept and
-// a late/duplicate drain would (harmlessly) re-surface — but by then the event is long gone
-// from the queue too. 10 minutes mirrors the completion-fingerprint TTL.
-const DIRECT_DELIVERED_TTL_MS = 10 * 60 * 1000;
-
-/**
- * R3: record that an event was direct-injected into a live coordinator on `coordinatorDaemonId`.
- * That coordinator's own drain (get_pending_mesh_events with the same coordinatorDaemonId) will
- * skip the queued copy, so it receives the event exactly once instead of twice (PTY + poll).
- * Other consumers (unscoped drainers, other daemons) are unaffected — they did not get the inject.
- */
-export function markMeshCoordinatorEventDirectDelivered(
-    coordinatorDaemonId: string,
-    event: PendingMeshCoordinatorEvent,
-): void {
-    // Canonicalize so the raw machineId used at inject time and the prefixed instanceId the
-    // coordinator drains with resolve to the same key.
-    const canonical = canonicalDaemonId(coordinatorDaemonId);
-    if (!canonical) return;
-    const fingerprint = buildPendingEventFingerprint(event);
-    if (!fingerprint.trim()) return;
-    try {
-        const store = MeshRuntimeStore.getInstance();
-        store.recordDirectDelivered(canonical, fingerprint, DIRECT_DELIVERED_TTL_MS);
-        store.sweepExpiredDirectDelivered();
-    } catch { /* best-effort — a duplicate is preferable to a crash */ }
-}
-
-function wasDirectDeliveredToCoordinator(coordinatorDaemonId: string, event: PendingMeshCoordinatorEvent): boolean {
-    const canonical = canonicalDaemonId(coordinatorDaemonId);
-    if (!canonical) return false;
-    const fingerprint = buildPendingEventFingerprint(event);
-    if (!fingerprint.trim()) return false;
-    try {
-        return MeshRuntimeStore.getInstance().wasDirectDelivered(canonical, fingerprint);
-    } catch {
-        return false;
-    }
-}
+// NOTE: the former R3 "direct-delivered" marker (markMeshCoordinatorEventDirectDelivered /
+// wasDirectDeliveredToCoordinator) was removed when spontaneous PTY direct-inject was retired.
+// Delivery is now queue-drain-only: an event is consumed by exactly one drainer via the atomic
+// SQLite drained=1 marking, so there is no PTY-vs-poll double-delivery left to dedup against.
+// The dormant mesh_direct_delivered_events table / store helpers remain (harmless) but unused.
 
 export function hasPendingCoordinatorEventDuplicate(event: PendingMeshCoordinatorEvent): boolean {
     const fingerprint = buildPendingEventFingerprint(event);
@@ -314,10 +279,77 @@ function atomicDrainFile(path: string): string | null {
     }
 }
 
-/** Drain and return all pending coordinator events for meshId, removing them from disk. */
-export function drainPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string): PendingMeshCoordinatorEvent[] {
+// Selectively drain a JSONL pending-events file: atomically claim it (rename), then
+// consume only the lines whose parsed event matches `predicate` and rewrite the
+// remaining (kept) lines back to the original path. Unparseable lines are kept
+// untouched. Returns the consumed events. The rename makes claiming exclusive —
+// only one concurrent caller wins, so there is no double-consume of the same lines.
+function selectiveDrainFile(
+    path: string,
+    predicate: (event: PendingMeshCoordinatorEvent) => boolean,
+): PendingMeshCoordinatorEvent[] {
+    const tmpPath = `${path}.draining`;
+    try {
+        renameSync(path, tmpPath);
+    } catch {
+        return []; // another drain claimed it, or the file doesn't exist
+    }
+    let content: string;
+    try {
+        content = readFileSync(tmpPath, 'utf-8');
+    } catch {
+        try { unlinkSync(tmpPath); } catch { /* best-effort */ }
+        return [];
+    }
+
+    const consumed: PendingMeshCoordinatorEvent[] = [];
+    const keptLines: string[] = [];
+    for (const line of content.split('\n')) {
+        if (!line) continue;
+        let parsed: PendingMeshCoordinatorEvent | undefined;
+        try { parsed = JSON.parse(line) as PendingMeshCoordinatorEvent; } catch { parsed = undefined; }
+        if (parsed && predicate(parsed)) {
+            consumed.push(parsed);
+        } else {
+            keptLines.push(line); // non-matching or unparseable → leave queued
+        }
+    }
+
+    try {
+        if (keptLines.length > 0) {
+            writeFileSync(path, keptLines.join('\n') + '\n', 'utf-8');
+        }
+        unlinkSync(tmpPath);
+    } catch {
+        // If the rewrite/cleanup fails, restore the claimed file so no events are
+        // lost — the next drain retries the whole file.
+        try { if (existsSync(tmpPath) && !existsSync(path)) renameSync(tmpPath, path); } catch { /* best-effort */ }
+        return [];
+    }
+    return consumed;
+}
+
+/**
+ * Drain and return pending coordinator events for meshId, removing the drained
+ * ones from both the SQLite inbox and the JSONL legacy file.
+ *
+ * When `opts.onlyEvents` is supplied, ONLY events whose name is in that set are
+ * drained; every other event stays queued (undrained in SQLite, rewritten back to
+ * the JSONL file). The reconcile loop uses this to force-drain terminal/force-inject
+ * events into a *generating* coordinator while leaving non-force progress events for
+ * the coordinator's next idle transition. The atomic SQLite drained=1 marking and the
+ * atomic JSONL rename keep force-drain and a concurrent full drain from double-consuming.
+ */
+export function drainPendingMeshCoordinatorEvents(
+    meshId?: string,
+    coordinatorDaemonId?: string,
+    opts?: { onlyEvents?: ReadonlySet<string> },
+): PendingMeshCoordinatorEvent[] {
     if (!meshId) return [];
 
+    const onlyEvents = opts?.onlyEvents;
+    const matchesFilter = (eventName: string): boolean => !onlyEvents || onlyEvents.has(eventName);
+
     // Dual-write means SQLite and JSONL hold the same events. Both stores must be
     // emptied in one drain call — draining only one leaves the other to re-deliver
     // the same events on the next call. Merge with fingerprint dedup.
@@ -336,7 +368,7 @@ export function drainPendingMeshCoordinatorEvents(meshId?: string, coordinatorDa
     try {
         const store = MeshRuntimeStore.getInstance();
         if (store.pendingEventCount(meshId) > 0) {
-            for (const row of store.drainPendingEvents(meshId, coordinatorDaemonId)) {
+            for (const row of store.drainPendingEvents(meshId, coordinatorDaemonId, onlyEvents ? { onlyEvents } : undefined)) {
                 const event = row.payload as PendingMeshCoordinatorEvent;
                 if (event) pushUnique(event);
             }
@@ -350,26 +382,34 @@ export function drainPendingMeshCoordinatorEvents(meshId?: string, coordinatorDa
         ? [getPendingEventsPath(meshId, coordinatorDaemonId), getPendingEventsPath(meshId)]
         : [getPendingEventsPath(meshId)];
     for (const path of paths) {
+        const isSharedFile = coordinatorDaemonId && path === getPendingEventsPath(meshId);
+        // Targeting predicate for the shared (unscoped) file: only this coordinator's
+        // events (or legacy untargeted ones) are eligible.
+        const targets = (e: PendingMeshCoordinatorEvent): boolean =>
+            !isSharedFile || !e.targetCoordinatorDaemonId || e.targetCoordinatorDaemonId === coordinatorDaemonId;
+
+        if (onlyEvents) {
+            // Selective JSONL drain: consume only matching events, rewrite the rest back.
+            for (const event of selectiveDrainFile(path, e => targets(e) && matchesFilter(e.event))) {
+                pushUnique(event);
+            }
+            continue;
+        }
         const content = atomicDrainFile(path);
         if (!content) continue;
         const parsed = content.split('\n').filter(Boolean).flatMap(line => {
             try { return [JSON.parse(line) as PendingMeshCoordinatorEvent]; } catch { return []; }
         });
         // If reading the shared file, filter to events that target this coordinator or are unscoped.
-        const filtered = (coordinatorDaemonId && path === getPendingEventsPath(meshId))
-            ? parsed.filter(e => !e.targetCoordinatorDaemonId || e.targetCoordinatorDaemonId === coordinatorDaemonId)
-            : parsed;
+        const filtered = isSharedFile ? parsed.filter(targets) : parsed;
         for (const event of filtered) pushUnique(event);
     }
     if (merged.length === 0) return [];
-    // R3: when this drain is scoped to a coordinator daemon, exclude events that were already
-    // direct-injected into that coordinator's live CLI session. Unscoped drains (no daemon id)
-    // keep everything — they belong to consumers that never received the direct inject.
-    const deliverable = coordinatorDaemonId
-        ? merged.filter(event => !wasDirectDeliveredToCoordinator(coordinatorDaemonId, event))
-        : merged;
-    if (deliverable.length === 0) return [];
-    return reconcilePendingMeshCoordinatorEvents(meshId, deliverable);
+    // (Former R3 direct-delivered dedup removed.) Spontaneous PTY direct-inject no
+    // longer exists — delivery is now queue-drain-only (reconcile loop or MCP pull),
+    // so an event is consumed by exactly one drainer via the atomic SQLite drained=1
+    // marking. There is no PTY-vs-poll double path left to dedup against.
+    return reconcilePendingMeshCoordinatorEvents(meshId, merged);
 }
 
 /** Peek at pending coordinator events without draining (non-destructive). */
@@ -404,13 +444,9 @@ export function getPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaem
         pushUnique(event);
     }
 
-    // R3: hide events already direct-delivered to this coordinator from its status peek, so
-    // mesh_status doesn't report a "pending" event the coordinator has in fact already received.
-    const deliverable = coordinatorDaemonId
-        ? merged.filter(event => !wasDirectDeliveredToCoordinator(coordinatorDaemonId, event))
-        : merged;
-
-    return reconcilePendingMeshCoordinatorEvents(meshId, deliverable);
+    // (Former R3 direct-delivered filter removed — no PTY direct-inject path exists
+    // anymore, so a peeked pending event has genuinely not yet been consumed.)
+    return reconcilePendingMeshCoordinatorEvents(meshId, merged);
 }
 
 /**

package/src/mesh/mesh-events.ts

@@ -11,13 +11,17 @@ export {
     drainPendingMeshCoordinatorEvents,
     getPendingMeshCoordinatorEvents,
     clearPendingMeshCoordinatorEvents,
-    markMeshCoordinatorEventDirectDelivered,
 } from './mesh-events-pending.js';
 
 export {
     reconcileDirectDispatchCompletionFromTranscript,
 } from './mesh-events-stale.js';
 
+export {
+    setupMeshReconcileLoop,
+    runMeshReconcileTick,
+} from './mesh-reconcile-loop.js';
+
 export type { MeshQueueTriggerResult } from './mesh-events-coordinator.js';
 export {
     tryAssignQueueTask,

package/src/mesh/mesh-reconcile-loop.ts

@@ -0,0 +1,276 @@
+// ---------------------------------------------------------------------------
+// mesh-reconcile-loop — periodic queue → live coordinator reconciliation
+// ---------------------------------------------------------------------------
+// Single-model replacement for the old event-based "spontaneous forward" paths
+// (remote P2P mesh_forward_event dispatch + live-CLI PTY fire-and-forget inject).
+// Those pushed events at the moment a worker transitioned state, and silently
+// dropped on the network (P2P) or when the coordinator was generating.
+//
+// The reliable backbone has always been the pending-events queue (SQLite +
+// JSONL): every mesh coordinator event is persisted there before anything else
+// (see injectMeshSystemMessage). What was missing was an *active* drainer that
+// runs on a schedule rather than only when the coordinator (an LLM) happens to
+// call a mesh tool.
+//
+// This loop is that drainer. On a fixed interval it:
+//   1. Finds live CLI coordinator sessions on THIS daemon (meshCoordinatorFor
+//      stamp). For each mesh, drains the local queue scoped to this daemon and
+//      injects pending events into the coordinator. When a coordinator is idle it
+//      receives every queued event. When ONLY generating coordinators exist (the
+//      common case while the coordinator is blocked awaiting a worker result), the
+//      loop force-drains ONLY the force-inject events (completion / approval / stop /
+//      refine·bootstrap terminal) and force-writes them into the generating PTY —
+//      the same busy-bypass send-guard escape the live-CLI inject used to use.
+//      Non-force progress events stay queued for the next idle tick (injecting them
+//      mid-generation would be noise). This is what makes a coordinator parked in
+//      `generating` while awaiting a worker's completion actually receive it.
+//   2. In cloud mode (dispatchMeshCommand present), pulls each remote worker
+//      node daemon's queue over P2P (get_pending_mesh_events) and re-injects via
+//      handleMeshForwardEvent — the same pull the MCP drainCoordinatorPendingEvents
+//      already does, now driven by the daemon timer instead of an LLM tool call.
+//
+// IMPORTANT — limits of this loop:
+//   - It only delivers to *live CLI coordinator instances* on this daemon. A
+//     pure stdio MCP coordinator (an LLM with no live CLI session to inject
+//     into) has no inject target here; that case stays pull-driven — the LLM
+//     drains the queue when it calls mesh_status / mesh_read_chat. We do NOT try
+//     to "wake" an LLM from the daemon; that is structurally impossible over a
+//     stdio request/response transport. See docs/refactoring/2026-06-15-mesh-event-to-queue-polling.md §4.7.
+//   - Queue persistence (queuePendingMeshCoordinatorEvent) and the SQLite
+//     drained=1 idempotency are the trust backbone and are untouched by this loop.
+// ---------------------------------------------------------------------------
+
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+import { loadConfig } from '../config/config.js';
+import { listMeshes } from '../config/mesh-config.js';
+import { LOG } from '../logging/logger.js';
+import { drainPendingMeshCoordinatorEvents } from './mesh-events-pending.js';
+import type { PendingMeshCoordinatorEvent } from './mesh-events-pending.js';
+import { MeshRuntimeStore } from './mesh-runtime-store.js';
+import { handleMeshForwardEvent, shouldForceInjectMeshEvent, MESH_FORCE_INJECT_EVENTS } from './mesh-events-coordinator.js';
+import { readNonEmptyString } from './mesh-events-utils.js';
+
+// Default reconcile cadence. approval/completion notifications to a live CLI
+// coordinator land within at most one interval. Overridable via env for tuning.
+const DEFAULT_RECONCILE_INTERVAL_MS = 4_000;
+
+function resolveReconcileIntervalMs(): number {
+    const raw = readNonEmptyString(process.env.MESH_RECONCILE_INTERVAL_MS);
+    if (raw) {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed >= 1_000 && parsed <= 60_000) return parsed;
+    }
+    return DEFAULT_RECONCILE_INTERVAL_MS;
+}
+
+interface LiveCoordinator {
+    meshId: string;
+    instance: ReturnType<DaemonComponents['instanceManager']['getInstance']>;
+    idle: boolean;
+}
+
+// Find live CLI coordinator instances on THIS daemon, keyed by mesh.
+function findLiveCoordinators(components: DaemonComponents): LiveCoordinator[] {
+    const out: LiveCoordinator[] = [];
+    for (const inst of components.instanceManager.getByCategory('cli')) {
+        const state = inst.getState();
+        const settings = state.settings && typeof state.settings === 'object'
+            ? state.settings as Record<string, unknown>
+            : {};
+        const meshId = readNonEmptyString(settings.meshCoordinatorFor);
+        if (!meshId) continue;
+        const status = readNonEmptyString(state.status).toLowerCase();
+        out.push({ meshId, instance: inst, idle: status === 'idle' });
+    }
+    return out;
+}
+
+// Inject a drained pending event into a live coordinator session. Force-inject
+// events carry force:true so they bypass the busy send-guard and land in the PTY
+// even while the coordinator is generating (see shouldForceInjectMeshEvent).
+function injectPendingIntoCoordinator(
+    coordinator: LiveCoordinator['instance'],
+    pending: PendingMeshCoordinatorEvent,
+): void {
+    if (!coordinator || !pending.coordinatorMessage) return;
+    const force = shouldForceInjectMeshEvent(pending.event);
+    coordinator.onEvent('send_message', {
+        input: { text: pending.coordinatorMessage, textFallback: pending.coordinatorMessage },
+        ...(force ? { force: true } : {}),
+    });
+}
+
+// One reconcile tick across every mesh that has a live CLI coordinator here.
+export async function runMeshReconcileTick(components: DaemonComponents): Promise<void> {
+    const coordinators = findLiveCoordinators(components);
+    if (coordinators.length === 0) {
+        // No live CLI coordinator on this daemon — nothing to inject into.
+        // (MCP-only LLM coordinators drain the queue via their own tool calls.)
+        return;
+    }
+
+    // Group coordinators by mesh; multiple coordinator instances for one mesh is
+    // unusual but supported (each gets the same drained events).
+    const byMesh = new Map<string, LiveCoordinator[]>();
+    for (const c of coordinators) {
+        const list = byMesh.get(c.meshId);
+        if (list) list.push(c);
+        else byMesh.set(c.meshId, [c]);
+    }
+
+    const localDaemonId = readNonEmptyString(loadConfig().machineId) || undefined;
+    const dispatchMeshCommand = components.dispatchMeshCommand;
+    const store = (() => {
+        try { return MeshRuntimeStore.getInstance(); } catch { return undefined; }
+    })();
+
+    for (const [meshId, meshCoordinators] of byMesh) {
+        // (a) Cloud-only: pull remote worker node daemons' queues over P2P and
+        //     re-inject locally. This is the same cross-daemon pull the MCP
+        //     drainCoordinatorPendingEvents performs, lifted to the daemon timer.
+        //     On standalone (no dispatchMeshCommand) this whole block is skipped,
+        //     keeping cloud/standalone identical for the local case.
+        if (dispatchMeshCommand) {
+            try {
+                await pullRemoteNodeQueues(components, meshId, localDaemonId);
+            } catch (e: any) {
+                LOG.warn('MeshReconcile', `Remote node pull failed for mesh ${meshId}: ${e?.message || e}`);
+            }
+        }
+
+        // (b) Drain the local queue scoped to this coordinator daemon and inject.
+        //     - If an idle coordinator exists, FULL-drain and deliver every event to it
+        //       (it can receive non-force progress events without deadlocking).
+        //     - If only GENERATING coordinators exist, force-drain ONLY the force-inject
+        //       events (completion/approval/stop/refine·bootstrap terminal) and force-inject
+        //       them so a coordinator parked in `generating` while awaiting that very event
+        //       is not deadlocked. Non-force progress events stay queued for the next idle
+        //       tick — injecting them would be noise mid-generation. Both drains mark the
+        //       consumed rows drained=1 atomically, so the pull path can't re-deliver.
+        const idleCoordinators = meshCoordinators.filter(c => c.idle);
+        const generatingCoordinators = meshCoordinators.filter(c => !c.idle);
+        const targetCoordinators = idleCoordinators.length > 0 ? idleCoordinators : generatingCoordinators;
+        const forceOnly = idleCoordinators.length === 0;
+
+        // O(1) guard: skip the drain entirely when the queue is empty.
+        if (store) {
+            try {
+                if (store.pendingEventCount(meshId) === 0) continue;
+            } catch { /* fall through to drain */ }
+        }
+
+        let pendingEvents: PendingMeshCoordinatorEvent[] = [];
+        try {
+            pendingEvents = drainPendingMeshCoordinatorEvents(
+                meshId,
+                localDaemonId,
+                forceOnly ? { onlyEvents: MESH_FORCE_INJECT_EVENTS } : undefined,
+            );
+        } catch (e: any) {
+            LOG.warn('MeshReconcile', `Drain failed for mesh ${meshId}: ${e?.message || e}`);
+            continue;
+        }
+        if (pendingEvents.length === 0) continue;
+
+        const mode = forceOnly ? 'force-drain → generating' : 'inject → idle';
+        LOG.info('MeshReconcile', `Reconcile ${mode}: ${pendingEvents.length} pending event(s) → ${targetCoordinators.length} coordinator(s) for mesh ${meshId}`);
+        for (const pending of pendingEvents) {
+            for (const c of targetCoordinators) {
+                injectPendingIntoCoordinator(c.instance, pending);
+            }
+        }
+    }
+}
+
+// Cloud-only: poll each remote worker node daemon for pending coordinator events
+// and re-inject them locally via handleMeshForwardEvent (which re-queues +
+// surfaces to the live coordinator on the next tick / immediately if idle).
+async function pullRemoteNodeQueues(
+    components: DaemonComponents,
+    meshId: string,
+    localDaemonId: string | undefined,
+): Promise<void> {
+    const dispatchMeshCommand = components.dispatchMeshCommand;
+    if (!dispatchMeshCommand) return;
+    const mesh = listMeshes().find(m => m.id === meshId);
+    if (!mesh) return;
+
+    const pendingEventArgs: Record<string, unknown> = {
+        meshId,
+        ...(localDaemonId ? { coordinatorDaemonId: localDaemonId } : {}),
+    };
+
+    for (const node of mesh.nodes) {
+        const nodeDaemonId = readNonEmptyString(node.daemonId);
+        // Skip nodes without a daemon, and nodes on THIS daemon (their events are
+        // already in the local queue drained in step (b)).
+        if (!nodeDaemonId) continue;
+        if (localDaemonId && nodeDaemonId === localDaemonId) continue;
+
+        let events: unknown;
+        try {
+            events = await dispatchMeshCommand(nodeDaemonId, 'get_pending_mesh_events', pendingEventArgs);
+        } catch {
+            // Remote pull is best-effort; the node may be offline. Retry next tick.
+            continue;
+        }
+        const list = extractPendingEvents(events).filter(e => readNonEmptyString(e?.meshId) === meshId);
+        for (const event of list) {
+            const payload = buildForwardPayloadFromPending(event);
+            if (!payload.event || !payload.meshId) continue;
+            try {
+                handleMeshForwardEvent(components, payload);
+            } catch { /* best-effort re-inject */ }
+        }
+    }
+}
+
+function extractPendingEvents(raw: unknown): any[] {
+    if (Array.isArray(raw)) return raw;
+    if (raw && typeof raw === 'object') {
+        const events = (raw as Record<string, unknown>).events;
+        if (Array.isArray(events)) return events;
+    }
+    return [];
+}
+
+// Flatten a queued PendingMeshCoordinatorEvent into the flat payload shape
+// handleMeshForwardEvent expects (mirrors the MCP buildMeshForwardPayloadFromPendingEvent).
+function buildForwardPayloadFromPending(event: any): Record<string, unknown> {
+    const metadata = event?.metadataEvent && typeof event.metadataEvent === 'object'
+        ? event.metadataEvent as Record<string, unknown>
+        : {};
+    return {
+        event: readNonEmptyString(event?.event),
+        meshId: readNonEmptyString(event?.meshId),
+        nodeId: readNonEmptyString(event?.nodeId) || readNonEmptyString(metadata.meshNodeId),
+        workspace: readNonEmptyString(event?.workspace) || readNonEmptyString(metadata.workspace),
+        ...metadata,
+    };
+}
+
+interface ReconcileLoopHandle {
+    stop(): void;
+}
+
+// Start the periodic reconcile loop. Returns a handle with stop() for shutdown.
+export function setupMeshReconcileLoop(components: DaemonComponents): ReconcileLoopHandle {
+    const intervalMs = resolveReconcileIntervalMs();
+    let running = false;
+    const timer = setInterval(() => {
+        if (running) return; // never overlap ticks
+        running = true;
+        void runMeshReconcileTick(components)
+            .catch((e: any) => LOG.warn('MeshReconcile', `Reconcile tick error: ${e?.message || e}`))
+            .finally(() => { running = false; });
+    }, intervalMs);
+    // Don't keep the process alive solely for this timer.
+    if (typeof timer.unref === 'function') timer.unref();
+    LOG.info('MeshReconcile', `Mesh reconcile loop started (interval ${intervalMs}ms)`);
+    return {
+        stop() {
+            clearInterval(timer);
+            LOG.info('MeshReconcile', 'Mesh reconcile loop stopped');
+        },
+    };
+}

package/src/mesh/mesh-runtime-store.ts

@@ -1241,16 +1241,41 @@ export class MeshRuntimeStore {
         return result.changes > 0;
     }
 
-    drainPendingEvents(meshId: string, coordinatorDaemonId?: string | null): Array<{ id: string; event: string; payload: unknown }> {
+    /**
+     * Drain undrained pending events for a mesh, atomically marking them drained.
+     * When `opts.onlyEvents` is supplied, ONLY rows whose `event` is in that set are
+     * drained — the rest stay queued (drained=0) for a later drain. This is how the
+     * reconcile loop force-drains terminal/force-inject events into a *generating*
+     * coordinator while leaving non-force progress events for the coordinator's next
+     * idle transition. Filtering happens inside the same transaction as the
+     * drained=1 marking, so force-drain + a concurrent full drain can never both
+     * consume the same row.
+     */
+    drainPendingEvents(
+        meshId: string,
+        coordinatorDaemonId?: string | null,
+        opts?: { onlyEvents?: ReadonlySet<string> },
+    ): Array<{ id: string; event: string; payload: unknown }> {
         return this.transaction(() => {
-            const whereClause = coordinatorDaemonId
-                ? `WHERE mesh_id = ? AND drained = 0 AND (coordinator_daemon_id IS NULL OR coordinator_daemon_id = ?)`
-                : `WHERE mesh_id = ? AND drained = 0`;
-            const params: unknown[] = coordinatorDaemonId
-                ? [meshId, coordinatorDaemonId]
-                : [meshId];
+            const onlyEvents = opts?.onlyEvents;
+            // An explicit-but-empty filter means "drain nothing" (no event name can match).
+            if (onlyEvents && onlyEvents.size === 0) return [];
+            const eventList = onlyEvents ? [...onlyEvents] : [];
+            // Filter by event name IN-SQL when onlyEvents is set so the LIMIT applies to
+            // matching rows — a long run of non-force events ahead in the queue must not
+            // crowd a force event out of the 100-row window.
+            const clauses = ['mesh_id = ?', 'drained = 0'];
+            const params: unknown[] = [meshId];
+            if (coordinatorDaemonId) {
+                clauses.push('(coordinator_daemon_id IS NULL OR coordinator_daemon_id = ?)');
+                params.push(coordinatorDaemonId);
+            }
+            if (eventList.length > 0) {
+                clauses.push(`event IN (${eventList.map(() => '?').join(',')})`);
+                params.push(...eventList);
+            }
             const rows = this.db.prepare(
-                `SELECT id, event, payload FROM mesh_pending_events ${whereClause} ORDER BY queued_at ASC LIMIT 100`
+                `SELECT id, event, payload FROM mesh_pending_events WHERE ${clauses.join(' AND ')} ORDER BY queued_at ASC LIMIT 100`
             ).all(...params) as Array<{ id: string; event: string; payload: string }>;
             if (rows.length === 0) return [];
             const ids = rows.map(r => r.id);