@adhdev/daemon-core 0.9.82-rc.136 → 0.9.82-rc.138

package/src/commands/router.ts

@@ -1434,10 +1434,18 @@ function buildSubmodulePublishRequiredNextStep(entries: MeshRefineSubmoduleReach
 
 function resolveRefineryAutoPublishSubmoduleMainCommits(mesh: any, workspace: string): { enabled: boolean; source?: string } {
     if (mesh?.policy?.allowAutoPublishSubmoduleMainCommits === true) {
+        process.stderr.write(
+            `[adhdev-mesh] WARNING: allowAutoPublishSubmoduleMainCommits is ENABLED via mesh.policy. `
+            + `Refinery may push unreachable submodule commits to submodule origin/main without additional user approval.\n`,
+        );
         return { enabled: true, source: 'mesh.policy.allowAutoPublishSubmoduleMainCommits' };
     }
     const loaded = loadMeshRefineConfig(mesh, workspace);
     if (loaded.config?.allowAutoPublishSubmoduleMainCommits === true) {
+        process.stderr.write(
+            `[adhdev-mesh] WARNING: allowAutoPublishSubmoduleMainCommits is ENABLED via ${loaded.path || loaded.source}. `
+            + `Refinery may push unreachable submodule commits to submodule origin/main without additional user approval.\n`,
+        );
         return { enabled: true, source: loaded.path || loaded.source };
     }
     return { enabled: false };
@@ -3637,7 +3645,13 @@ export class DaemonCommandRouter {
 
             case 'get_pending_mesh_events': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                const events = drainPendingMeshCoordinatorEvents(meshId || undefined);
+                // (B3) Respect coordinatorDaemonId when the caller declares it
+                // so unicast events route to the right coordinator instead of
+                // being silently consumed by the first drainer.
+                const coordinatorDaemonId = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
+                    ? args.coordinatorDaemonId.trim()
+                    : undefined;
+                const events = drainPendingMeshCoordinatorEvents(meshId || undefined, coordinatorDaemonId);
                 return { success: true, events };
             }
 
@@ -5879,7 +5893,13 @@ export class DaemonCommandRouter {
                         nodeStatuses.push(status);
                     }
 
-                    const pendingCoordinatorEvents = drainPendingMeshCoordinatorEvents(meshId);
+                    // (B3) Pass coordinatorDaemonId when the caller declares
+                    // it so v1.5 unicast routing (targetCoordinatorDaemonId)
+                    // delivers events to the right coordinator.
+                    const callerCoordinatorDaemonId = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
+                        ? args.coordinatorDaemonId.trim()
+                        : undefined;
+                    const pendingCoordinatorEvents = drainPendingMeshCoordinatorEvents(meshId, callerCoordinatorDaemonId);
                     const previewFreshness = (() => {
                         const localRepoRoot = nodeStatuses
                             .map((node: any) => readStringValue(node?.git?.repoRoot, node?.repoRoot, node?.workspace))

package/src/config/chat-history.ts

@@ -1375,19 +1375,42 @@ function normalizeProviderNativeHistoryRecords(agentType: string, historySession
     if (!Array.isArray(records)) return [];
     const normalizedSessionId = normalizeSavedHistorySessionId(historySessionId);
     return records
-        .map((record: any) => sanitizeHistoryMessage(agentType, {
-            ts: typeof record?.ts === 'string' ? record.ts : new Date(Number(record?.receivedAt) || Date.now()).toISOString(),
-            receivedAt: Number(record?.receivedAt) || Date.parse(record?.ts || '') || Date.now(),
-            role: record?.role,
-            content: String(record?.content || ''),
-            kind: record?.kind || (record?.role === 'system' ? 'session_start' : 'standard'),
-            senderName: record?.senderName,
-            agent: agentType,
-            instanceId: record?.instanceId,
-            historySessionId: normalizeSavedHistorySessionId(record?.historySessionId || normalizedSessionId),
-            sessionTitle: record?.sessionTitle,
-            workspace: record?.workspace,
-        } as HistoryMessage))
+        .map((record: any) => {
+            const base: HistoryMessage = {
+                ts: typeof record?.ts === 'string' ? record.ts : new Date(Number(record?.receivedAt) || Date.now()).toISOString(),
+                receivedAt: Number(record?.receivedAt) || Date.parse(record?.ts || '') || Date.now(),
+                role: record?.role,
+                content: String(record?.content || ''),
+                kind: record?.kind || (record?.role === 'system' ? 'session_start' : 'standard'),
+                senderName: record?.senderName,
+                agent: agentType,
+                instanceId: record?.instanceId,
+                historySessionId: normalizeSavedHistorySessionId(record?.historySessionId || normalizedSessionId),
+                sessionTitle: record?.sessionTitle,
+                workspace: record?.workspace,
+            } as HistoryMessage;
+            // (A2.3 v2 identity passthrough) — if the producer (native_history.js)
+            // emitted v2 stable identity, keep it across the sanitize layer so
+            // downstream (chat-commands.ts normalizeNativeHistoryMessages) sees
+            // the producer's contract output instead of recomputing from index
+            // and content hash. v1 producers without these fields are unaffected.
+            if (typeof record?.providerUnitKey === 'string' && record.providerUnitKey) {
+                (base as any).providerUnitKey = record.providerUnitKey;
+            }
+            if (typeof record?.bubbleId === 'string' && record.bubbleId) {
+                (base as any).bubbleId = record.bubbleId;
+            }
+            if (typeof record?.sequence === 'number' && Number.isFinite(record.sequence)) {
+                (base as any).sequence = record.sequence;
+            }
+            if (typeof record?._turnKey === 'string' && record._turnKey) {
+                (base as any)._turnKey = record._turnKey;
+            }
+            if (typeof record?.bubbleState === 'string' && record.bubbleState) {
+                (base as any).bubbleState = record.bubbleState;
+            }
+            return sanitizeHistoryMessage(agentType, base);
+        })
         .filter(Boolean) as HistoryMessage[];
 }
 
@@ -1397,6 +1420,7 @@ function callProviderNativeHistoryRead(
     scripts: ProviderNativeHistoryScripts | undefined,
     historySessionId: string | undefined,
     workspace?: string,
+    excludeInProgressTurn?: boolean,
 ): ProviderNativeHistoryReadResult | null {
     const fn = getProviderNativeHistoryScript(scripts, canonicalHistory, 'readSession');
     if (!fn) return null;
@@ -1408,7 +1432,8 @@ function callProviderNativeHistoryRead(
         workspace,
         format: canonicalHistory?.format,
         watchPath: canonicalHistory?.watchPath,
-        args: { sessionId: normalizedSessionId, historySessionId: normalizedSessionId, workspace },
+        excludeInProgressTurn: excludeInProgressTurn === true,
+        args: { sessionId: normalizedSessionId, historySessionId: normalizedSessionId, workspace, excludeInProgressTurn: excludeInProgressTurn === true },
     });
     if (!result || typeof result !== 'object') return null;
     const records = normalizeProviderNativeHistoryRecords(agentType, normalizedSessionId, (result as any).messages || (result as any).records);
@@ -1430,11 +1455,12 @@ function buildNativeHistoryReadResult(
     scripts: ProviderNativeHistoryScripts | undefined,
     historySessionId: string | undefined,
     workspace?: string,
+    excludeInProgressTurn?: boolean,
 ): ProviderNativeHistoryReadResult | null {
     const normalizedSessionId = normalizeSavedHistorySessionId(historySessionId || '');
     const normalizedWorkspace = typeof workspace === 'string' ? workspace.trim() : '';
     if (!canonicalHistory || (!normalizedSessionId && !normalizedWorkspace) || !isNativeSourceCanonicalHistory(canonicalHistory)) return null;
-    return callProviderNativeHistoryRead(agentType, canonicalHistory, scripts, normalizedSessionId, workspace);
+    return callProviderNativeHistoryRead(agentType, canonicalHistory, scripts, normalizedSessionId, workspace, excludeInProgressTurn);
 }
 
 function materializeNativeHistoryToMirror(
@@ -1490,6 +1516,7 @@ export function readProviderChatHistory(
         excludeRecentCount?: number;
         historyBehavior?: ProviderHistoryBehavior;
         scripts?: ProviderNativeHistoryScripts;
+        excludeInProgressTurn?: boolean;
     } = {},
 ): {
     messages: HistoryMessage[];
@@ -1503,7 +1530,7 @@ export function readProviderChatHistory(
     unavailableReason?: string;
 } {
     if (isNativeSourceCanonicalHistory(options.canonicalHistory) && (options.historySessionId || options.workspace)) {
-        const nativeResult = buildNativeHistoryReadResult(agentType, options.canonicalHistory, options.scripts, options.historySessionId, options.workspace);
+        const nativeResult = buildNativeHistoryReadResult(agentType, options.canonicalHistory, options.scripts, options.historySessionId, options.workspace, options.excludeInProgressTurn);
         if (!nativeResult) return { messages: [], hasMore: false, source: 'native-unavailable' };
         return {
             ...pageHistoryRecords(agentType, nativeResult.records, options.offset || 0, options.limit || 30, options.excludeRecentCount || 0, options.historyBehavior),

package/src/git/git-worktree.ts

@@ -116,8 +116,11 @@ export async function createWorktree(opts: WorktreeCreateOptions): Promise<Workt
         });
     } catch (error: any) {
         const stderr = typeof error.stderr === 'string' ? error.stderr : '';
-        // Clean error messages for common failures
         if (/already exists/i.test(stderr)) {
+            // Distinguish directory-collision (TOCTOU race) from branch-already-exists
+            if (existsSync(targetDir)) {
+                throw new Error(`Worktree target directory was created concurrently: ${targetDir}`);
+            }
             throw new Error(`Branch '${branch}' already exists or is checked out in another worktree`);
         }
         throw new Error(`git worktree add failed: ${stderr.trim() || error.message}`);
@@ -170,6 +173,10 @@ export async function removeWorktree(repoRoot: string, worktreePath: string, opt
         const stdout = typeof error.stdout === 'string' ? error.stdout : '';
         const detail = `${stderr}\n${stdout}\n${error.message || ''}`;
         if (opts.allowSubmoduleForceFallback && SUBMODULE_WORKTREE_REMOVE_RE.test(detail)) {
+            process.stderr.write(
+                `[adhdev-mesh] WARNING: git worktree remove --force fallback for submodule worktree '${worktreePath}'. `
+                + `Any uncommitted changes inside submodules will be lost.\n`,
+            );
             try {
                 await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], {
                     cwd: repoRoot,

package/src/index.ts

@@ -115,6 +115,7 @@ export type {
   RepoMeshLedgerEntryStatus,
   RepoMeshLedgerSummaryStatus,
   RepoMeshLedgerStatus,
+  MeshAsyncJobLifecycle,
 } from './repo-mesh-types.js';
 export { DEFAULT_MESH_POLICY } from './repo-mesh-types.js';
 
@@ -195,8 +196,8 @@ export { buildMeshLedgerReconciliationEvidence, buildMeshLedgerReplicaEvidence }
 export type { MeshLedgerReconciliationEvidence, MeshLedgerReplicaEvidence, MeshLedgerReplicaStatus } from './mesh/mesh-ledger-reconciliation.js';
 
 // ── Mesh Work Queue (GUPP) ──
-export { enqueueTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest } from './mesh/mesh-work-queue.js';
-export type { MeshWorkQueueEntry, MeshTaskStatus, MeshTaskMode, MeshWorkQueueStats, MeshQueueMutationOptions, MeshTaskModeValidationResult } from './mesh/mesh-work-queue.js';
+export { enqueueTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches } from './mesh/mesh-work-queue.js';
+export type { MeshWorkQueueEntry, MeshTaskStatus, MeshTaskMode, MeshWorkQueueStats, MeshQueueMutationOptions, MeshTaskModeValidationResult, DirectDispatchRecord } from './mesh/mesh-work-queue.js';
 export { buildCompactStaleDirectWorkSummary, buildMeshActiveWork, buildMeshActiveWorkSummary } from './mesh/mesh-active-work.js';
 export type { MeshActiveWorkRecord, MeshActiveWorkStatus, MeshActiveWorkSummary, MeshActiveWorkSource, MeshStaleDirectWorkSummary } from './mesh/mesh-active-work.js';
 export { buildMeshAsyncRefineJobs } from './mesh/mesh-refine-status.js';

package/src/mesh/beads-db.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, statSync } from 'fs';
 import { dirname, join } from 'path';
 import { createRequire } from 'module';
 import { getLedgerDir } from './mesh-ledger.js';
@@ -28,12 +28,18 @@ function legacyQueuePath(meshId: string): string {
 export class BeadsDB {
     private static instance: BeadsDB | undefined;
     private readonly db: DatabaseHandle;
+    private readonly dbPath: string;
     private readonly migratedMeshIds = new Set<string>();
+    private fingerprintSweepCounter = 0;
+    private walWriteCounter = 0;
+    private static readonly WAL_CHECK_INTERVAL = 500;
+    private static readonly WAL_MAX_BYTES = 50 * 1024 * 1024; // 50 MB
 
     private constructor(dbPath: string) {
         const dir = dirname(dbPath);
         if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
+        this.dbPath = dbPath;
         this.db = new (loadDatabaseCtor())(dbPath);
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('synchronous = NORMAL');
@@ -81,9 +87,72 @@ export class BeadsDB {
                 ON mesh_queue(mesh_id, status, created_at);
             CREATE INDEX IF NOT EXISTS idx_mesh_queue_assignment
                 ON mesh_queue(mesh_id, assigned_node_id, assigned_session_id, status);
+
+            CREATE TABLE IF NOT EXISTS mesh_completion_fingerprints (
+                fingerprint TEXT PRIMARY KEY,
+                expires_at INTEGER NOT NULL
+            );
+
+            CREATE TABLE IF NOT EXISTS mesh_direct_dispatches (
+                task_id TEXT PRIMARY KEY,
+                mesh_id TEXT NOT NULL,
+                node_id TEXT,
+                session_id TEXT,
+                provider_type TEXT,
+                message TEXT NOT NULL,
+                task_mode TEXT,
+                via TEXT NOT NULL,
+                status TEXT NOT NULL DEFAULT 'dispatched',
+                dispatched_to_idle_session INTEGER NOT NULL DEFAULT 0,
+                dispatched_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+            );
+
+            CREATE INDEX IF NOT EXISTS idx_direct_dispatches_mesh_session
+                ON mesh_direct_dispatches(mesh_id, session_id, status);
         `);
     }
 
+    hasCompletionFingerprint(fingerprint: string): boolean {
+        const now = Date.now();
+        const row = this.db
+            .prepare('SELECT 1 FROM mesh_completion_fingerprints WHERE fingerprint = ? AND expires_at > ?')
+            .get(fingerprint, now) as { 1: number } | undefined;
+        // Sweep expired fingerprints every 100 reads so stale rows don't accumulate
+        // even during read-heavy (non-write) periods when recordFingerprintSeen is idle.
+        if (++this.fingerprintSweepCounter >= 100) {
+            this.fingerprintSweepCounter = 0;
+            this.sweepExpiredFingerprints();
+        }
+        return row !== undefined;
+    }
+
+    recordCompletionFingerprint(fingerprint: string, ttlMs: number): void {
+        const expiresAt = Date.now() + ttlMs;
+        this.db.prepare('INSERT OR REPLACE INTO mesh_completion_fingerprints (fingerprint, expires_at) VALUES (?, ?)')
+            .run(fingerprint, expiresAt);
+        this.maybeCheckpointWal();
+    }
+
+    sweepExpiredFingerprints(): void {
+        this.db.prepare('DELETE FROM mesh_completion_fingerprints WHERE expires_at <= ?').run(Date.now());
+    }
+
+    private maybeCheckpointWal(): void {
+        if (++this.walWriteCounter < BeadsDB.WAL_CHECK_INTERVAL) return;
+        this.walWriteCounter = 0;
+        try {
+            const walPath = `${this.dbPath}-wal`;
+            if (!existsSync(walPath)) return;
+            const size = statSync(walPath).size;
+            if (size < BeadsDB.WAL_MAX_BYTES) return;
+            process.stderr.write(
+                `[adhdev-mesh] WAL file ${Math.round(size / 1024 / 1024)}MB exceeds threshold; forcing checkpoint\n`,
+            );
+            this.db.pragma('wal_checkpoint(TRUNCATE)');
+        } catch { /* best-effort */ }
+    }
+
     private ensureLegacyQueueMigrated(meshId: string): void {
         if (this.migratedMeshIds.has(meshId)) return;
         this.migratedMeshIds.add(meshId);
@@ -136,7 +205,8 @@ export class BeadsDB {
         const rows = this.db
             .prepare('SELECT id, status, updated_at FROM mesh_queue WHERE mesh_id = ? ORDER BY id ASC')
             .all(meshId) as Array<{ id: string; status: string; updated_at: string }>;
-        return rows.map(row => `${row.id}:${row.status}:${row.updated_at}`).join('|');
+        // Tab as field delimiter (UUIDs and ISO timestamps never contain tabs).
+        return rows.map(row => `${row.id}\t${row.status}\t${row.updated_at}`).join('\n');
     }
 
     replaceQueue(meshId: string, queue: MeshWorkQueueEntry[]): void {
@@ -152,6 +222,7 @@ export class BeadsDB {
         `);
         deleteStmt.run(meshId);
         for (const entry of queue) insert.run(this.toRow(entry));
+        this.maybeCheckpointWal();
     }
 
     deleteQueue(meshId: string): void {
@@ -159,6 +230,134 @@ export class BeadsDB {
         this.migratedMeshIds.delete(meshId);
     }
 
+    insertQueueEntry(entry: MeshWorkQueueEntry): void {
+        this.db.prepare(`
+            INSERT INTO mesh_queue (
+                id, mesh_id, status, target_node_id, target_session_id,
+                assigned_node_id, assigned_session_id, created_at, updated_at, payload
+            ) VALUES (
+                @id, @meshId, @status, @targetNodeId, @targetSessionId,
+                @assignedNodeId, @assignedSessionId, @createdAt, @updatedAt, @payload
+            )
+        `).run(this.toRow(entry));
+        this.maybeCheckpointWal();
+    }
+
+    updateQueueEntry(entry: MeshWorkQueueEntry): void {
+        const now = new Date().toISOString();
+        entry.updatedAt = now;
+        this.db.prepare(`
+            UPDATE mesh_queue SET
+                status = @status,
+                target_node_id = @targetNodeId,
+                target_session_id = @targetSessionId,
+                assigned_node_id = @assignedNodeId,
+                assigned_session_id = @assignedSessionId,
+                updated_at = @updatedAt,
+                payload = @payload
+            WHERE id = @id AND mesh_id = @meshId
+        `).run(this.toRow(entry));
+        this.maybeCheckpointWal();
+    }
+
+    findQueueEntryById(meshId: string, id: string): MeshWorkQueueEntry | null {
+        this.ensureLegacyQueueMigrated(meshId);
+        const row = this.db.prepare(
+            'SELECT payload FROM mesh_queue WHERE id = ? AND mesh_id = ?'
+        ).get(id, meshId) as { payload: string } | undefined;
+        return row ? JSON.parse(row.payload) as MeshWorkQueueEntry : null;
+    }
+
+    hasActiveAssignment(meshId: string, sessionId: string, nodeId: string): boolean {
+        this.ensureLegacyQueueMigrated(meshId);
+        const row = this.db.prepare(`
+            SELECT 1 FROM mesh_queue
+            WHERE mesh_id = ? AND status = 'assigned'
+              AND (assigned_session_id = ? OR assigned_node_id = ?)
+            LIMIT 1
+        `).get(meshId, sessionId, nodeId);
+        return row !== undefined;
+    }
+
+    // O(1) claim: transaction ensures only one session claims a pending task
+    claimNextQueueTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null {
+        return this.transaction(() => {
+            this.ensureLegacyQueueMigrated(meshId);
+            if (this.hasActiveAssignment(meshId, sessionId, nodeId)) return null;
+
+            // Priority: session-targeted > node-targeted (no session) > unconstrained
+            const row = (
+                this.db.prepare(`
+                    SELECT payload FROM mesh_queue
+                    WHERE mesh_id = ? AND status = 'pending' AND target_session_id = ?
+                    ORDER BY created_at ASC LIMIT 1
+                `).get(meshId, sessionId) as { payload: string } | undefined
+            ) || (
+                this.db.prepare(`
+                    SELECT payload FROM mesh_queue
+                    WHERE mesh_id = ? AND status = 'pending' AND target_node_id = ? AND target_session_id IS NULL
+                    ORDER BY created_at ASC LIMIT 1
+                `).get(meshId, nodeId) as { payload: string } | undefined
+            ) || (
+                this.db.prepare(`
+                    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 LIMIT 1
+                `).get(meshId) as { payload: string } | undefined
+            );
+            if (!row) return null;
+
+            const entry = JSON.parse(row.payload) as MeshWorkQueueEntry;
+            const now = new Date().toISOString();
+            entry.status = 'assigned';
+            entry.assignedNodeId = nodeId;
+            entry.assignedSessionId = sessionId;
+            entry.dispatchTimestamp = now;
+            entry.updatedAt = now;
+
+            this.db.prepare(`
+                UPDATE mesh_queue SET
+                    status = 'assigned', assigned_node_id = ?, assigned_session_id = ?,
+                    updated_at = ?, payload = ?
+                WHERE id = ? AND mesh_id = ?
+            `).run(nodeId, sessionId, now, JSON.stringify(entry), entry.id, meshId);
+
+            this.maybeCheckpointWal();
+            return entry;
+        });
+    }
+
+    getQueueStatsByStatus(meshId: string): { status: string; count: number }[] {
+        this.ensureLegacyQueueMigrated(meshId);
+        return this.db.prepare(
+            `SELECT status, COUNT(*) as count FROM mesh_queue WHERE mesh_id = ? GROUP BY status`
+        ).all(meshId) as { status: string; count: number }[];
+    }
+
+    getActiveAssignmentDetails(meshId: string): Array<{ id: string; nodeId?: string; sessionId?: string; message: string }> {
+        this.ensureLegacyQueueMigrated(meshId);
+        const rows = this.db.prepare(`
+            SELECT assigned_node_id, assigned_session_id, payload
+            FROM mesh_queue WHERE mesh_id = ? AND status = 'assigned'
+        `).all(meshId) as Array<{ assigned_node_id: string | null; assigned_session_id: string | null; payload: string }>;
+        return rows.map(r => {
+            let id = '', message = '';
+            try { const e = JSON.parse(r.payload) as MeshWorkQueueEntry; id = e.id; message = e.message; } catch { /* ignore */ }
+            return { id, nodeId: r.assigned_node_id ?? undefined, sessionId: r.assigned_session_id ?? undefined, message };
+        });
+    }
+
+    findAssignedBySession(meshId: string, sessionId: string, occurredAtIso?: string): MeshWorkQueueEntry | null {
+        this.ensureLegacyQueueMigrated(meshId);
+        // Use updated_at (≈ dispatchTimestamp when status='assigned') for the occurredAt filter.
+        const sql = occurredAtIso
+            ? `SELECT payload FROM mesh_queue WHERE mesh_id = ? AND assigned_session_id = ? AND status = 'assigned' AND updated_at <= ? ORDER BY updated_at DESC LIMIT 1`
+            : `SELECT payload FROM mesh_queue WHERE mesh_id = ? AND assigned_session_id = ? AND status = 'assigned' ORDER BY updated_at DESC LIMIT 1`;
+        const args: string[] = occurredAtIso ? [meshId, sessionId, occurredAtIso] : [meshId, sessionId];
+        const row = this.db.prepare(sql).get(...args as [string, string, string?]) as { payload: string } | undefined;
+        return row ? JSON.parse(row.payload) as MeshWorkQueueEntry : null;
+    }
+
     private toRow(entry: MeshWorkQueueEntry): Record<string, unknown> {
         return {
             id: entry.id,
@@ -173,4 +372,108 @@ export class BeadsDB {
             payload: JSON.stringify(entry),
         };
     }
+
+    // ── Direct Dispatch Tracking ─────────────────────────────────────────────
+
+    insertDirectDispatch(entry: {
+        taskId: string;
+        meshId: string;
+        nodeId?: string;
+        sessionId?: string;
+        providerType?: string;
+        message: string;
+        taskMode?: string;
+        via: string;
+        dispatchedToIdleSession?: boolean;
+        dispatchedAt: string;
+    }): void {
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            INSERT OR REPLACE INTO mesh_direct_dispatches
+                (task_id, mesh_id, node_id, session_id, provider_type, message, task_mode, via,
+                 status, dispatched_to_idle_session, dispatched_at, updated_at)
+            VALUES
+                (@taskId, @meshId, @nodeId, @sessionId, @providerType, @message, @taskMode, @via,
+                 'dispatched', @dispatchedToIdle, @dispatchedAt, @updatedAt)
+        `).run({
+            taskId: entry.taskId,
+            meshId: entry.meshId,
+            nodeId: entry.nodeId ?? null,
+            sessionId: entry.sessionId ?? null,
+            providerType: entry.providerType ?? null,
+            message: entry.message,
+            taskMode: entry.taskMode ?? null,
+            via: entry.via,
+            dispatchedToIdle: entry.dispatchedToIdleSession ? 1 : 0,
+            dispatchedAt: entry.dispatchedAt,
+            updatedAt: now,
+        });
+    }
+
+    getActiveDirectDispatches(meshId: string): Array<{
+        taskId: string;
+        meshId: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        message: string;
+        taskMode: string | null;
+        via: string;
+        status: string;
+        dispatchedToIdleSession: boolean;
+        dispatchedAt: string;
+        updatedAt: string;
+    }> {
+        const rows = this.db.prepare(`
+            SELECT task_id, mesh_id, node_id, session_id, provider_type, message, task_mode, via,
+                   status, dispatched_to_idle_session, dispatched_at, updated_at
+            FROM mesh_direct_dispatches
+            WHERE mesh_id = ? AND status NOT IN ('completed', 'failed', 'stale')
+            ORDER BY dispatched_at ASC
+        `).all(meshId) as Array<Record<string, unknown>>;
+        return rows.map(r => ({
+            taskId: r.task_id as string,
+            meshId: r.mesh_id as string,
+            nodeId: r.node_id as string | null,
+            sessionId: r.session_id as string | null,
+            providerType: r.provider_type as string | null,
+            message: r.message as string,
+            taskMode: r.task_mode as string | null,
+            via: r.via as string,
+            status: r.status as string,
+            dispatchedToIdleSession: (r.dispatched_to_idle_session as number) === 1,
+            dispatchedAt: r.dispatched_at as string,
+            updatedAt: r.updated_at as string,
+        }));
+    }
+
+    updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void {
+        if (!sessionId) return; // never update rows without a session binding
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE mesh_direct_dispatches
+            SET status = @status, updated_at = @updatedAt
+            WHERE mesh_id = @meshId AND session_id = @sessionId
+              AND session_id IS NOT NULL
+              AND status NOT IN ('completed', 'failed')
+        `).run({ status, meshId, sessionId, updatedAt: now });
+    }
+
+    cleanupTerminalDirectDispatches(olderThanMs: number): void {
+        const cutoff = new Date(Date.now() - olderThanMs).toISOString();
+        this.db.prepare(`
+            DELETE FROM mesh_direct_dispatches
+            WHERE status IN ('completed', 'failed', 'stale') AND updated_at < ?
+        `).run(cutoff);
+    }
+
+    markStaleDirectDispatches(meshId: string, olderThanMs: number): void {
+        const cutoff = new Date(Date.now() - olderThanMs).toISOString();
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE mesh_direct_dispatches
+            SET status = 'stale', updated_at = ?
+            WHERE mesh_id = ? AND status = 'dispatched' AND dispatched_at < ?
+        `).run(now, meshId, cutoff);
+    }
 }