@adhdev/daemon-core 0.9.82-rc.467 → 0.9.82-rc.469

package/src/mesh/mesh-remote-event-pull.ts

@@ -0,0 +1,279 @@
+// ---------------------------------------------------------------------------
+// mesh-remote-event-pull — cloud P2P remote-node pull helpers for the reconcile loop
+// ---------------------------------------------------------------------------
+// Extracted from mesh-reconcile-loop.ts (A-3 god-module decomposition, pure move,
+// no behavior change). These helpers implement the reconcile loop's cloud-only
+// PHASE that pulls pending coordinator events + worker status from REMOTE worker
+// node daemons over P2P (get_pending_mesh_events / read_chat / get_status_metadata)
+// and the payload-unwrapping utilities that tolerate the varied transport envelope
+// shapes a local commandHandler vs. a remote dispatchMeshCommand returns.
+//
+// mesh-completion-synthesis.ts (the PHASE-4 synth) consumes several of these
+// (unwrapReadChatPayload, readChatPayloadStatus, reprobeWorkerStatus,
+// realTerminalEmitPendingForTask, collectLiveNodesWithSessions); the reconcile
+// loop itself consumes pullRemoteNodeQueues.
+// ---------------------------------------------------------------------------
+
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+import type { LocalMeshEntry } from '../repo-mesh-types.js';
+import { getPendingMeshCoordinatorEvents, serializeV2EnvelopeToWire } from './mesh-events-pending.js';
+import type { PendingMeshCoordinatorEvent } from './mesh-events-pending.js';
+import { handleMeshForwardEvent } from './mesh-events-coordinator.js';
+import { readNonEmptyString } from './mesh-events-utils.js';
+import { daemonIdsEquivalent } from '@adhdev/mesh-shared';
+import { daemonIdListIncludes } from './mesh-reconcile-identity.js';
+
+// 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).
+//
+// Scoping: the remote handler (get_pending_mesh_events) drains its queue filtered
+// by coordinatorDaemonId — returning events targeted at that id OR unscoped, and
+// leaving events targeted at a *different* coordinator. A remote worker stamps the
+// coordinator id in one of SEVERAL forms (the canonical status id `standalone_`/
+// `daemon_<machineId>` stamped by the MCP layer, the bare machineId stamped by the
+// local queue path, OR — most commonly for remote launches — the coordinator mesh
+// node's config-form `daemonId`, which resolveCoordinatorDaemonId prefers and which
+// is NOT canonicalised). `candidateDaemonIds` is the already-expanded self-identity
+// set (resolveCoordinatorSelfIds: runtime drain ids ∪ this daemon's mesh-config node/
+// host id forms), so we pull ONCE PER candidate id and a completion stamped with any
+// of them is recovered. The remote drain is atomic (drained=1), so issuing multiple
+// pulls cannot double-deliver — the first pull that matches consumes the event; the
+// rest see nothing. When no ids resolve we fall back to a single unscoped pull.
+export async function pullRemoteNodeQueues(
+    components: DaemonComponents,
+    mesh: LocalMeshEntry,
+    localDaemonId: string | undefined,
+    candidateDaemonIds: string[],
+): Promise<void> {
+    const dispatchMeshCommand = components.dispatchMeshCommand;
+    if (!dispatchMeshCommand) return;
+    const meshId = mesh.id;
+
+    // One args object per candidate coordinator-id form, or a single unscoped pull
+    // when none resolve.
+    const pulls: Array<Record<string, unknown>> = candidateDaemonIds.length > 0
+        ? candidateDaemonIds.map(id => ({ meshId, coordinatorDaemonId: id }))
+        : [{ meshId }];
+
+    // Parallelize across nodes: a single connected-but-slow node must not serially
+    // block the other nodes for the rest of the tick. Each node callback is fully
+    // self-contained (local/candidate skip, peer-connected pre-check, per-candidate
+    // pulls, extract→re-inject) and best-effort — allSettled swallows per-node errors.
+    await Promise.allSettled(mesh.nodes.map(async (node) => {
+        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 PHASE 2). "This daemon" is matched
+        // against the full self-identity set (candidateDaemonIds), not just the bare
+        // localDaemonId — a self node can be registered under the config-form daemonId
+        // (`daemon_<machineId>`) which would NOT equal bare localDaemonId, and pulling
+        // from ourselves over P2P is both wasteful and a self-dispatch hazard.
+        if (!nodeDaemonId) return;
+        if (daemonIdsEquivalent(nodeDaemonId, localDaemonId)) return;
+        if (daemonIdListIncludes(candidateDaemonIds, nodeDaemonId)) return;
+
+        // Peer-connected pre-check (EVENT-DELIVERY-DELAY fix(a)): a degraded peer whose
+        // DataChannel is not open would sink this pull into peer.connectQueue and stall
+        // until CONNECT_TIMEOUT_MS (90s), formerly freezing the whole serial loop and
+        // delaying completion-event recovery from healthy nodes. Skip such a node THIS
+        // tick and retry next tick — LOSSLESS: an unconnected peer has not drained
+        // anything (drained=0 preserved), so its events are recovered whole on the next
+        // successful tick. Skip = delay, never loss.
+        //   • snapshot present and state !== 'connected' → skip (continue next tick).
+        //   • snapshot null/undefined (getter unwired, e.g. standalone) → DO NOT skip;
+        //     fall through to the legacy path so this stays regression-free.
+        const peerSnapshot = components.getMeshPeerConnectionStatus?.(nodeDaemonId);
+        if (peerSnapshot && String(peerSnapshot.state) !== 'connected') return;
+
+        for (const pendingEventArgs of pulls) {
+            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.
+                break; // node unreachable — don't bother with the other id form this tick.
+            }
+            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 */ }
+            }
+        }
+    }));
+}
+
+// Pull the read_chat payload out of whatever envelope the transport returned.
+// A local commandHandler.handle() returns the CommandResult directly; a remote
+// dispatchMeshCommand returns it possibly wrapped in { payload } / { result }.
+export function unwrapReadChatPayload(raw: unknown): Record<string, unknown> | null {
+    let cursor: unknown = raw;
+    for (let depth = 0; depth < 4 && cursor && typeof cursor === 'object'; depth++) {
+        const record = cursor as Record<string, unknown>;
+        if (Array.isArray(record.messages)) return record;
+        if (record.payload && typeof record.payload === 'object') { cursor = record.payload; continue; }
+        if (record.result && typeof record.result === 'object') { cursor = record.result; continue; }
+        if (record.data && typeof record.data === 'object') { cursor = record.data; continue; }
+        break;
+    }
+    return cursor && typeof cursor === 'object' ? cursor as Record<string, unknown> : null;
+}
+
+export function readChatPayloadStatus(payload: Record<string, unknown> | null): string {
+    return readNonEmptyString(payload?.status).toLowerCase();
+}
+
+// R4e fix (3): peek the pending-events queue for a REAL (worker-emitted) terminal completion
+// already queued for a task — used to yield the in-flight synth to the worker's own emit. Broad
+// peek (no daemon-id scoping) matched precisely by taskId, so a worker stamp in any daemon-id form
+// is still recognized. Best-effort: a peek failure returns false (proceed to synth — never block
+// delivery). A prior SYNTH's still-queued pending event also names this taskId, but a synth always
+// writes its terminal ledger atomically, so hasTerminalLedgerAfterDispatch downstream already
+// no-ops that case — this guard is specifically for an as-yet-unledgered worker emit in flight.
+export function realTerminalEmitPendingForTask(meshId: string, taskId: string): boolean {
+    let pending: readonly PendingMeshCoordinatorEvent[];
+    try {
+        pending = getPendingMeshCoordinatorEvents(meshId);
+    } catch {
+        return false;
+    }
+    return pending.some(e =>
+        readNonEmptyString(e.metadataEvent?.taskId) === taskId
+        && (e.event === 'agent:generating_completed' || e.event === 'agent:stopped'));
+}
+
+// R4e fix (2): one fresh read_chat status read for the worker session, via the same local/remote
+// transport PHASE 4 uses. Returns the lowercased status, or null when the read is inconclusive
+// (transport error, success:false, no payload) — callers treat null as "no new evidence, proceed".
+export async function reprobeWorkerStatus(
+    components: DaemonComponents,
+    args: { isLocalNode: boolean; nodeDaemonId: string; readArgs: Record<string, unknown> },
+): Promise<string | null> {
+    try {
+        if (args.isLocalNode) {
+            const r = await components.commandHandler.handle('read_chat', args.readArgs);
+            if (r && (r as { success?: boolean }).success === false) return null;
+            return readChatPayloadStatus(unwrapReadChatPayload(r));
+        }
+        if (components.dispatchMeshCommand) {
+            const r = await components.dispatchMeshCommand(args.nodeDaemonId, 'read_chat', args.readArgs);
+            const p = unwrapReadChatPayload(r);
+            if (p && (p as { success?: boolean }).success === false) return null;
+            return readChatPayloadStatus(p);
+        }
+    } catch {
+        return null;
+    }
+    return null;
+}
+
+// Probe each node for its live session list (get_status_metadata) and return mesh.nodes
+// decorated with a `sessions` array — the shape buildMeshActiveWork / sessionStatusFromNodes
+// consume to decide whether a dispatched session is still present. Best-effort: an unreachable
+// node yields an empty session list rather than throwing.
+export async function collectLiveNodesWithSessions(
+    components: DaemonComponents,
+    mesh: LocalMeshEntry,
+    selfIds: string[],
+    localDaemonId: string | undefined,
+): Promise<any[]> {
+    const dispatchMeshCommand = components.dispatchMeshCommand;
+    return Promise.all(mesh.nodes.map(async (node) => {
+        const nodeDaemonId = readNonEmptyString(node.daemonId);
+        const isLocalNode = !nodeDaemonId
+            || daemonIdListIncludes(selfIds, nodeDaemonId)
+            || daemonIdsEquivalent(nodeDaemonId, localDaemonId);
+        // Peer-connected pre-check (EVENT-DELIVERY-DELAY fix(a)): mirror pullRemoteNodeQueues.
+        // Without this the 90s connect-deadline block re-enters via this Promise.all —
+        // a degraded remote's get_status_metadata sinks into peer.connectQueue and stalls
+        // the whole prune probe. Only call the remote when the peer is 'connected'; an
+        // unconnected peer is left undecorated (empty session list), same as unreachable.
+        // Getter unwired (null/undefined) → do NOT skip, fall through (regression-free).
+        if (!isLocalNode) {
+            const peerSnapshot = components.getMeshPeerConnectionStatus?.(nodeDaemonId);
+            if (peerSnapshot && String(peerSnapshot.state) !== 'connected') return node;
+        }
+        let statusResult: unknown;
+        try {
+            if (isLocalNode) {
+                statusResult = await components.commandHandler.handle('get_status_metadata', {});
+            } else if (dispatchMeshCommand) {
+                statusResult = await dispatchMeshCommand(nodeDaemonId, 'get_status_metadata', {});
+            } else {
+                return node; // remote node, no P2P transport — leave undecorated
+            }
+        } catch {
+            return node; // unreachable — leave undecorated (empty session list)
+        }
+        const sessions = extractStatusMetadataSessions(statusResult);
+        return sessions.length > 0 ? { ...node, sessions } : node;
+    }));
+}
+
+// Pull the live session list out of a get_status_metadata result, tolerating the same
+// envelope shapes unwrapReadChatPayload handles (direct CommandResult or { payload }/{ result }).
+export function extractStatusMetadataSessions(raw: unknown): any[] {
+    let cursor: unknown = raw;
+    for (let depth = 0; depth < 4 && cursor && typeof cursor === 'object'; depth++) {
+        const record = cursor as Record<string, unknown>;
+        const status = record.status && typeof record.status === 'object' ? record.status as Record<string, unknown> : undefined;
+        if (status && Array.isArray(status.sessions)) return status.sessions;
+        if (Array.isArray(record.sessions)) return record.sessions;
+        if (record.payload && typeof record.payload === 'object') { cursor = record.payload; continue; }
+        if (record.result && typeof record.result === 'object') { cursor = record.result; continue; }
+        if (record.data && typeof record.data === 'object') { cursor = record.data; continue; }
+        break;
+    }
+    return [];
+}
+
+export 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).
+export 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),
+        // Preserve the originating coordinator session id across the relay. It is normally
+        // carried inside metadataEvent.meshCoordinatorSessionId (spread below), but pass the
+        // top-level field through explicitly too so the handleMeshForwardEvent whitelist
+        // recovers it regardless of which carrier the producing daemon used.
+        ...(readNonEmptyString(event?.targetCoordinatorSessionId)
+            ? { targetCoordinatorSessionId: readNonEmptyString(event.targetCoordinatorSessionId) }
+            : {}),
+        ...metadata,
+        // NOTIF-MISS (FIX 3): surface the dispatch task id at the TOP LEVEL so the relay's
+        // received-stage trace (and buildRelayMetadataEvent) recovers it regardless of which
+        // carrier the producing daemon used. The metadata spread above may carry the id only as
+        // `meshActiveTaskId` (a worker provider event), leaving top-level `taskId` unset and the
+        // received stage rendering `task=-`. Resolve both carriers into an explicit `taskId` so
+        // dedup stays task-scoped end-to-end. Only set when a non-empty id exists (no clobber to
+        // undefined when neither is present).
+        ...((): Record<string, unknown> => {
+            const tid = readNonEmptyString(metadata.taskId) || readNonEmptyString(metadata.meshActiveTaskId);
+            return tid ? { taskId: tid } : {};
+        })(),
+        // T4 (B3b): carry the v2 envelope (protocolVersion/eventId/scope/dispatchedBy/
+        // intendedFor) across the P2P relay boundary at the TOP LEVEL. These live on the
+        // pending event itself, not inside metadataEvent, so without this the remote pull
+        // re-queue would re-stamp a fresh eventId — breaking cross-machine idempotency and
+        // downgrading the relayed completion to v1 broadcast routing. Spread LAST so the
+        // authoritative envelope always wins over any stale key the metadata spread carried.
+        ...serializeV2EnvelopeToWire(event as PendingMeshCoordinatorEvent),
+    };
+}

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

@@ -1,9 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync } from 'fs';
 import { dirname, join } from 'path';
 import { LOG } from '../logging/logger.js';
 import { loadBetterSqlite3 } from '../system/load-better-sqlite3.js';
+import { getConfigDir } from '../config/config.js';
 import { getLedgerDir } from './mesh-ledger.js';
-import { nodeSatisfiesRequiredTags, isTaskReadonly, taskDependenciesSatisfied } from './mesh-work-queue.js';
+import { nodeSatisfiesRequiredTags, isTaskReadonly, taskDependenciesSatisfied, meshTaskNotBeforeReady, meshTaskPriorityRank } from './mesh-work-queue.js';
 import { meshNodeIdMatches, daemonIdsEquivalent, expandDaemonIdForms, sessionIdsEquivalent } from '@adhdev/mesh-shared';
 import type { MeshTaskStatus, MeshWorkQueueEntry } from './mesh-work-queue.js';
 import type BetterSqlite3 from 'better-sqlite3';
@@ -39,10 +40,43 @@ function legacyQueuePath(meshId: string): string {
 }
 
 let loggedMigrationFailure = false;
+let loggedStrayCleanup = false;
+
+/**
+ * MESH-COMPLEXITY-AUDIT Part 8-1: one-shot hygiene for a stray root mesh-runtime.db.
+ *
+ * The store lives at `~/.adhdev/mesh-ledger/mesh-runtime.db` (getLedgerDir()). An older
+ * build path could create a 0-byte `mesh-runtime.db` directly under `~/.adhdev/` — a
+ * dead file that is never opened or read (the canonical path is the only one used) but
+ * lingers. Remove it if and only if it is provably that stray: (a) exists, (b) is NOT the
+ * canonical store path, and (c) is empty (0 bytes). The size gate is the safety belt — we
+ * never unlink a non-empty file, so a real DB that somehow landed here is left untouched
+ * and surfaces as data rather than being silently deleted. Best-effort: any error is
+ * swallowed (with one diagnostic warn), never blocking store init.
+ */
+function cleanupStrayRootRuntimeDb(canonicalPath: string): void {
+    try {
+        const strayPath = join(getConfigDir(), 'mesh-runtime.db');
+        if (strayPath === canonicalPath) return; // canonical dir IS the config dir — never touch
+        if (!existsSync(strayPath)) return;
+        if (statSync(strayPath).size !== 0) return; // non-empty → not the known 0-byte stray; leave it
+        unlinkSync(strayPath);
+        if (!loggedStrayCleanup) {
+            loggedStrayCleanup = true;
+            LOG.info('MeshRuntimeStore', `Removed stray 0-byte root mesh-runtime.db at ${strayPath}`);
+        }
+    } catch (err: any) {
+        if (!loggedStrayCleanup) {
+            loggedStrayCleanup = true;
+            LOG.warn('MeshRuntimeStore', `Stray root mesh-runtime.db cleanup failed (ignored): ${err?.message || err}`);
+        }
+    }
+}
 
 function meshRuntimeStorePath(): string {
     const dir = getLedgerDir();
     const nextPath = join(dir, 'mesh-runtime.db');
+    cleanupStrayRootRuntimeDb(nextPath);
     if (existsSync(nextPath)) return nextPath;
 
     const legacyPath = join(dir, 'beads.db');
@@ -236,20 +270,9 @@ export class MeshRuntimeStore {
             CREATE INDEX IF NOT EXISTS idx_mesh_session_delivery_task
                 ON mesh_session_delivery(mesh_id, task_id);
 
-            CREATE TABLE IF NOT EXISTS mesh_completion_conflicts (
-                id TEXT PRIMARY KEY,
-                mesh_id TEXT NOT NULL,
-                fingerprint TEXT NOT NULL,
-                conflicting_task_id TEXT,
-                conflicting_session_id TEXT,
-                original_task_id TEXT,
-                original_session_id TEXT,
-                event TEXT NOT NULL,
-                created_at TEXT NOT NULL
-            );
-
-            CREATE INDEX IF NOT EXISTS idx_mesh_completion_conflicts_mesh
-                ON mesh_completion_conflicts(mesh_id, created_at);
+            -- MESH-COMPLEXITY-AUDIT Part 8-2: mesh_completion_conflicts removed
+            -- (write-only fingerprint-collision diagnostic, no production reader,
+            -- no no-loss role). Dropped in migrateMeshIsolationColumns step 6.
 
             CREATE TABLE IF NOT EXISTS mesh_tool_call_log (
                 id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -459,6 +482,27 @@ export class MeshRuntimeStore {
                     ON mesh_pending_events(mesh_id, event_id)
                     WHERE event_id IS NOT NULL
             `);
+
+            // 5. MESH-COMPLEXITY-AUDIT Part 8-1: drop the legacy mesh_direct_delivered_events
+            //    table. It backed the retired R3 "direct-delivered" dedup marker
+            //    (markMeshCoordinatorEventDirectDelivered / wasDirectDeliveredToCoordinator,
+            //    removed when spontaneous PTY direct-inject was retired — see the NOTE in
+            //    mesh-events-pending.ts). No live code CREATEs, reads, or writes it anymore,
+            //    so this is a pure runtime-residue cleanup with no behavior change: a store
+            //    that never had the table just no-ops (IF EXISTS), an old install carrying
+            //    the dormant table has it removed once. Idempotent — DROP TABLE IF EXISTS is
+            //    a no-op on every subsequent boot.
+            this.db.exec(`DROP TABLE IF EXISTS mesh_direct_delivered_events`);
+
+            // 6. MESH-COMPLEXITY-AUDIT Part 8-2: drop the mesh_completion_conflicts
+            //    diagnostic table. It recorded which task lost a completion-fingerprint
+            //    dedup collision but had NO production reader (getRecentCompletionConflicts
+            //    was test-only) and played NO part in the no-loss delivery contract — the
+            //    dedup DECISION is the fingerprint match in mesh-event-forwarding.ts and is
+            //    unchanged. Pure runtime-residue cleanup with no behavior change: a fresh
+            //    store never creates it; an old install drops the dormant table once.
+            //    Idempotent — DROP TABLE IF EXISTS is a no-op on every subsequent boot.
+            this.db.exec(`DROP TABLE IF EXISTS mesh_completion_conflicts`);
         } catch (err: any) {
             // Best-effort: a failed isolation migration must not brick the store. The
             // CREATE-TABLE definitions above already carry the new schema for fresh DBs;
@@ -867,31 +911,35 @@ export class MeshRuntimeStore {
             // targetMatches() JS gate above re-validates each fetched row.
             const nodeIdForms = expandDaemonIdForms(nodeId);
             const nodePinnedPlaceholders = nodeIdForms.map(() => '?').join(', ');
-            // Priority: session-targeted > node-targeted (no session) > unconstrained
-            const rows = [
-                ...(
-                this.db.prepare(`
+            // Priority: session-targeted > node-targeted (no session) > unconstrained.
+            // G6: WITHIN each targeting tier, a higher task-level priority is pulled first;
+            // created_at ASC (from the SQL ORDER BY) is the intra-priority tie-break. The
+            // tier ordering is preserved (a high-priority unconstrained task never jumps
+            // ahead of a session/node-pinned task) so targeting stays the outer key and
+            // priority is the inner key. Sort is stable, so equal-priority rows keep FIFO.
+            const parseTier = (query: string, ...params: unknown[]): MeshWorkQueueEntry[] => {
+                const tierRows = this.db.prepare(query).all(...params) as Array<{ payload: string }>;
+                return tierRows
+                    .map(row => JSON.parse(row.payload) as MeshWorkQueueEntry)
+                    .sort((a, b) => meshTaskPriorityRank(b.priority) - meshTaskPriorityRank(a.priority));
+            };
+            const candidates = [
+                ...parseTier(`
                     SELECT payload FROM mesh_queue
                     WHERE mesh_id = ? AND status = 'pending' AND target_session_id = ?
                     ORDER BY created_at ASC
-                `).all(meshId, sessionId) as Array<{ payload: string }>
-                ),
-                ...(
-                this.db.prepare(`
+                `, meshId, sessionId),
+                ...parseTier(`
                     SELECT payload FROM mesh_queue
                     WHERE mesh_id = ? AND status = 'pending' AND target_node_id IN (${nodePinnedPlaceholders}) AND target_session_id IS NULL
                     ORDER BY created_at ASC
-                `).all(meshId, ...nodeIdForms) as Array<{ payload: string }>
-                ),
-                ...(
-                this.db.prepare(`
+                `, meshId, ...nodeIdForms),
+                ...parseTier(`
                     SELECT payload FROM mesh_queue
                     WHERE mesh_id = ? AND status = 'pending' AND target_node_id IS NULL AND target_session_id IS NULL
                     ORDER BY created_at ASC
-                `).all(meshId) as Array<{ payload: string }>
-                ),
+                `, meshId),
             ];
-            const candidates = rows.map(row => JSON.parse(row.payload) as MeshWorkQueueEntry);
 
             // M1: a task with unmet dependencies (or a system blockedReason) is not claimable.
             // Resolve dependency statuses in one query over the union of referenced ids.
@@ -919,6 +967,13 @@ export class MeshRuntimeStore {
                 return !nodeBusy;
             };
 
+            // G7: delayed execution. A task with a notBefore in the future is held pending
+            // (skipped as a claim candidate) until the wall clock passes it. Fail-open on an
+            // unparseable timestamp (meshTaskNotBeforeReady) so a bad value never strands work.
+            const claimNowMs = Date.now();
+            const notBeforeReady = (candidate: MeshWorkQueueEntry): boolean =>
+                meshTaskNotBeforeReady(candidate, claimNowMs);
+
             // WTDISPATCH-FANOUT: a `convergence` task lands its work onto base (merge →
             // push → cleanup against the real checkout). It must NEVER be claimed by a
             // co-located worktree-clone session — N sibling worktree sessions on one daemon
@@ -961,6 +1016,7 @@ export class MeshRuntimeStore {
             const entry = candidates.find(candidate =>
                 nodeSatisfiesRequiredTags(candidate.requiredTags, capabilityTags)
                 && dependenciesSatisfied(candidate)
+                && notBeforeReady(candidate)
                 && convergenceAllows(candidate)
                 && targetMatches(candidate)
                 && nodeConflictAllows(candidate));
@@ -1433,58 +1489,11 @@ export class MeshRuntimeStore {
 
     // ── Completion Conflict Diagnostics ──────────────────────────────────────
 
-    recordCompletionConflict(entry: {
-        id: string;
-        meshId: string;
-        fingerprint: string;
-        conflictingTaskId?: string;
-        conflictingSessionId?: string;
-        originalTaskId?: string;
-        originalSessionId?: string;
-        event: string;
-        createdAt: string;
-    }): void {
-        this.db.prepare(`
-            INSERT OR IGNORE INTO mesh_completion_conflicts
-                (id, mesh_id, fingerprint, conflicting_task_id, conflicting_session_id,
-                 original_task_id, original_session_id, event, created_at)
-            VALUES (@id, @meshId, @fingerprint, @conflictingTaskId, @conflictingSessionId,
-                    @originalTaskId, @originalSessionId, @event, @createdAt)
-        `).run({
-            id: entry.id,
-            meshId: entry.meshId,
-            fingerprint: entry.fingerprint,
-            conflictingTaskId: entry.conflictingTaskId ?? null,
-            conflictingSessionId: entry.conflictingSessionId ?? null,
-            originalTaskId: entry.originalTaskId ?? null,
-            originalSessionId: entry.originalSessionId ?? null,
-            event: entry.event,
-            createdAt: entry.createdAt,
-        });
-        this.maybeCheckpointWal();
-    }
-
-    getRecentCompletionConflicts(meshId: string, limitMs: number = 60 * 60 * 1000): Array<{
-        id: string; meshId: string; fingerprint: string; conflictingTaskId: string | null;
-        conflictingSessionId: string | null; originalTaskId: string | null;
-        originalSessionId: string | null; event: string; createdAt: string;
-    }> {
-        const cutoff = new Date(Date.now() - limitMs).toISOString();
-        const rows = this.db.prepare(
-            'SELECT * FROM mesh_completion_conflicts WHERE mesh_id = ? AND created_at >= ? ORDER BY created_at DESC LIMIT 50'
-        ).all(meshId, cutoff) as Array<Record<string, unknown>>;
-        return rows.map(r => ({
-            id: r.id as string,
-            meshId: r.mesh_id as string,
-            fingerprint: r.fingerprint as string,
-            conflictingTaskId: r.conflicting_task_id as string | null,
-            conflictingSessionId: r.conflicting_session_id as string | null,
-            originalTaskId: r.original_task_id as string | null,
-            originalSessionId: r.original_session_id as string | null,
-            event: r.event as string,
-            createdAt: r.created_at as string,
-        }));
-    }
+    // MESH-COMPLEXITY-AUDIT Part 8-2: recordCompletionConflict /
+    // getRecentCompletionConflicts (and their mesh_completion_conflicts table)
+    // were removed. They were a write-only diagnostic of fingerprint-dedup
+    // collisions with no production reader and no part in the no-loss delivery
+    // contract; the table is dropped in migrateMeshIsolationColumns (step 6).
 
     /**
      * Record a mesh tool call and check whether this mesh+tool combination is

package/src/mesh/mesh-work-queue.ts

@@ -16,9 +16,66 @@ export type MeshActiveTaskStatus = Extract<MeshTaskStatus, 'pending' | 'assigned
 export type MeshHistoricalTaskStatus = Extract<MeshTaskStatus, 'completed' | 'failed' | 'cancelled'>;
 export type MeshTaskMode = 'code_change' | 'validation' | 'live_debug_readonly' | 'launch_app' | 'convergence';
 
+/** G6: task-level scheduling priority. Ranks which task a node pulls first (created_at tie-break). */
+export type MeshTaskPriority = 'low' | 'normal' | 'high';
+
 export const ACTIVE_MESH_QUEUE_STATUSES: MeshActiveTaskStatus[] = ['pending', 'assigned'];
 export const HISTORICAL_MESH_QUEUE_STATUSES: MeshHistoricalTaskStatus[] = ['completed', 'failed', 'cancelled'];
 export const MESH_TASK_MODES: MeshTaskMode[] = ['code_change', 'validation', 'live_debug_readonly', 'launch_app', 'convergence'];
+export const MESH_TASK_PRIORITIES: MeshTaskPriority[] = ['low', 'normal', 'high'];
+
+/**
+ * G6: numeric rank of a task priority (higher = pulled first). Absent/unknown → 'normal' (1).
+ * Shared by the claim-candidate ordering and any surface that must sort by task priority.
+ */
+export function meshTaskPriorityRank(priority: unknown): number {
+    switch (priority) {
+        case 'high': return 2;
+        case 'low': return 0;
+        default: return 1; // 'normal' and any absent/unknown value
+    }
+}
+
+/** G6: coerce an arbitrary input to a valid MeshTaskPriority, or undefined when not one of the three. */
+export function normalizeMeshTaskPriority(value: unknown): MeshTaskPriority | undefined {
+    return value === 'low' || value === 'normal' || value === 'high' ? value : undefined;
+}
+
+/**
+ * G7: resolve a not_before input to a stored ISO string (or undefined when absent/invalid).
+ * Accepts an ISO/date string, an absolute epoch-ms number, or a small relative-ms offset from
+ * `nowMs`. Disambiguation for numbers: a value below {@link NOT_BEFORE_RELATIVE_THRESHOLD_MS}
+ * (~1 year in ms) is treated as a relative offset added to now; a larger value is an absolute
+ * epoch-ms timestamp. A past/negative result is normalized to now (immediately claimable).
+ */
+export const NOT_BEFORE_RELATIVE_THRESHOLD_MS = 365 * 24 * 60 * 60 * 1000;
+export function resolveNotBefore(value: unknown, nowMs: number = Date.now()): string | undefined {
+    if (value === undefined || value === null) return undefined;
+    let absMs: number;
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        absMs = value < NOT_BEFORE_RELATIVE_THRESHOLD_MS ? nowMs + value : value;
+    } else if (typeof value === 'string' && value.trim()) {
+        const parsed = Date.parse(value.trim());
+        if (Number.isNaN(parsed)) return undefined;
+        absMs = parsed;
+    } else {
+        return undefined;
+    }
+    if (absMs <= nowMs) return new Date(nowMs).toISOString();
+    return new Date(absMs).toISOString();
+}
+
+/** G7: is a task claimable now, or is it still held back by its notBefore gate? */
+export function meshTaskNotBeforeReady(
+    task: { notBefore?: string } | null | undefined,
+    nowMs: number = Date.now(),
+): boolean {
+    const nb = task?.notBefore;
+    if (!nb) return true;
+    const parsed = Date.parse(nb);
+    if (Number.isNaN(parsed)) return true; // unparseable → do not block (fail-open)
+    return parsed <= nowMs;
+}
 
 /**
  * QUEUE-NODE-SERIALIZATION: single source of truth for "is this task read-only?".
@@ -488,6 +545,22 @@ export interface MeshWorkQueueEntry {
     targetSessionId?: string;
     /** If specified, a node must expose all tags before it can claim the task. */
     requiredTags?: string[];
+    /**
+     * G6 (task-level scheduling priority): 'low' | 'normal' | 'high'. Orders the
+     * claim candidate list so a high-priority task is pulled ahead of an older
+     * normal/low task within the same claim tier (created_at is the tie-break).
+     * Absent → treated as 'normal'. This is the TASK-level priority, distinct from
+     * the NODE-level schedulingPriority (resolveNodeSchedulingPriority), which ranks
+     * which node a task goes to, not which task a node pulls first.
+     */
+    priority?: MeshTaskPriority;
+    /**
+     * G7 (delayed execution): ISO timestamp before which the task is NOT claimable.
+     * The claim gate holds the task pending while now < notBefore; once the wall
+     * clock passes it the task becomes a normal claim candidate. A pure time gate —
+     * cron/webhook triggers are out of scope. Absent → immediately claimable.
+     */
+    notBefore?: string;
     /**
      * M1: ids of tasks that must reach 'completed' before this task is claimable.
      * Forward references (ids not yet enqueued) are allowed for batch flows and
@@ -777,6 +850,12 @@ export function enqueueTask(
         requiredTags?: string[];
         /** M1: tasks that must complete before this one is claimable. */
         dependsOn?: string[];
+        /** G6: task-level scheduling priority ('low' | 'normal' | 'high'). Absent → 'normal'. */
+        priority?: MeshTaskPriority | string;
+        /** G7: hold the task pending until this time. ISO string, absolute epoch-ms, or relative-ms offset from now. */
+        notBefore?: string | number;
+        /** P3: max automatic requeue attempts before the task auto-fails. Absent → policy default (1). */
+        maxRetries?: number;
         /** M1/M3: mission this task belongs to. */
         missionId?: string;
         /** MAGI: consensus group id shared by every replica of a mesh_magi_review fan-out. */
@@ -797,6 +876,11 @@ export function enqueueTask(
     }
     const id = typeof opts?.id === 'string' && opts.id.trim() ? opts.id.trim() : randomUUID();
     const dependsOn = normalizeDependsOn(opts?.dependsOn);
+    const priority = normalizeMeshTaskPriority(opts?.priority);
+    const notBefore = resolveNotBefore(opts?.notBefore);
+    const maxRetries = typeof opts?.maxRetries === 'number' && Number.isFinite(opts.maxRetries) && opts.maxRetries >= 0
+        ? Math.floor(opts.maxRetries)
+        : undefined;
     return withQueueLock(meshId, () => {
         if (MeshRuntimeStore.getInstance().findQueueEntryById(meshId, id)) {
             throw new Error(`duplicate_task_id: task '${id}' already exists in mesh '${meshId}'`);
@@ -825,6 +909,12 @@ export function enqueueTask(
             targetSessionId: opts?.targetSessionId,
             requiredTags: resolvedRequiredTags,
             ...(dependsOn.length > 0 ? { dependsOn } : {}),
+            // G6: only persist a non-default priority so legacy/normal rows stay minimal.
+            ...(priority && priority !== 'normal' ? { priority } : {}),
+            // G7: hold-until gate (stored ISO). Omitted when absent/immediate.
+            ...(notBefore ? { notBefore } : {}),
+            // P3: explicit retry cap. Omitted → requeue path falls back to policy default.
+            ...(maxRetries !== undefined ? { maxRetries } : {}),
             ...(typeof opts?.missionId === 'string' && opts.missionId.trim() ? { missionId: opts.missionId.trim() } : {}),
             ...(typeof opts?.consensusGroupId === 'string' && opts.consensusGroupId.trim() ? { consensusGroupId: opts.consensusGroupId.trim() } : {}),
             ...(typeof opts?.model === 'string' && opts.model.trim() ? { model: opts.model.trim() } : {}),