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

package/src/mesh/contracts.ts

@@ -0,0 +1,329 @@
+/**
+ * Mesh contract v2 — first-class identity, scopes, and protocol version.
+ *
+ * Replaces the implicit conventions that grew across mesh-events.ts,
+ * mesh-work-queue.ts, mesh-ledger.ts, and mesh-tools.ts where the same
+ * concept (a coordinator, a session, a task status) appeared in different
+ * shapes per file. The audit found:
+ *
+ *   - PendingMeshCoordinatorEvent had no targetCoordinatorDaemonId. All
+ *     events were broadcast to every coordinator that drained them. Two
+ *     coordinators sharing a mesh would each receive every event,
+ *     leading to duplicate completion handling and missed targeting.
+ *   - drainPendingMeshCoordinatorEvents accepted only meshId. The caller's
+ *     coordinator identity was never available, so per-coordinator
+ *     routing was impossible by construction.
+ *   - Session identifier keys diverged across stores: targetSessionId /
+ *     assignedSessionId / instanceId / runtimeSessionId / providerSessionId.
+ *     resolveEventSessionId() tried four fallbacks per call.
+ *   - No protocol version on the JSONL ledger or BeadsDB. Schema
+ *     evolutions had no guard rail.
+ *   - mesh_reconcile_ledger existed as a routine recovery tool, not as
+ *     an incident-response escape hatch. That itself signals the routing
+ *     layer cannot be trusted.
+ *
+ * This module introduces the types; the actual wiring lands in B2 (data
+ * model + 3-way transactional store), B3 (MCP layer enforcement), and B4
+ * (frontend consumption). B1 is intentionally non-breaking — it adds the
+ * types and leaves runtime behaviour unchanged.
+ */
+
+/** Provider type identifier (e.g. 'claude-cli', 'codex-cli', 'roo-code').
+ *  Free-form string; no shared enum exists in daemon-core yet. */
+type ProviderType = string;
+
+// ─── Protocol version ────────────────────────────────────────────────────
+
+export const MESH_PROTOCOL_VERSION_V1 = '1.0' as const;
+export const MESH_PROTOCOL_VERSION_V2 = '2.0' as const;
+
+export type MeshProtocolVersion =
+  | typeof MESH_PROTOCOL_VERSION_V1
+  | typeof MESH_PROTOCOL_VERSION_V2;
+
+export const SUPPORTED_MESH_PROTOCOL_VERSIONS: readonly MeshProtocolVersion[] = [
+  MESH_PROTOCOL_VERSION_V1,
+  MESH_PROTOCOL_VERSION_V2,
+] as const;
+
+export function isSupportedMeshProtocolVersion(value: unknown): value is MeshProtocolVersion {
+  return typeof value === 'string'
+    && (SUPPORTED_MESH_PROTOCOL_VERSIONS as readonly string[]).includes(value);
+}
+
+// ─── Coordinator identity ────────────────────────────────────────────────
+
+/**
+ * Identity of a mesh coordinator. Required (non-optional) on every dispatch
+ * and drain operation in v2 — opaque/missing identity is the audit's
+ * smoking gun for routing failures and is structurally banned by the v2
+ * types.
+ *
+ * - daemonId: the machineId of the daemon hosting the coordinator. Stable
+ *   across coordinator restarts on the same machine.
+ * - coordinatorRunId: a UUID generated when the coordinator process starts.
+ *   Stable for the coordinator's lifetime, fresh on restart. Required so
+ *   two coordinators on the same daemon (one CLI, one MCP) can be told
+ *   apart without conflating their drains.
+ * - sessionId: optional CLI coordinator session identifier (instanceId).
+ *   Present when the coordinator is itself a CLI session, absent for
+ *   pure MCP coordinators.
+ */
+export interface CoordinatorIdentity {
+  readonly daemonId: string;
+  readonly coordinatorRunId: string;
+  readonly sessionId?: string;
+}
+
+export function coordinatorIdentityEquals(a: CoordinatorIdentity, b: CoordinatorIdentity): boolean {
+  return a.daemonId === b.daemonId
+      && a.coordinatorRunId === b.coordinatorRunId
+      && (a.sessionId ?? '') === (b.sessionId ?? '');
+}
+
+export function coordinatorIdentityKey(identity: CoordinatorIdentity): string {
+  // Stable string form for map keys and ledger payloads. Avoids the
+  // {a:b, c:d} JSON.stringify ordering trap by enforcing field order.
+  return `${identity.daemonId}|${identity.coordinatorRunId}|${identity.sessionId ?? ''}`;
+}
+
+// ─── Session handle ──────────────────────────────────────────────────────
+
+/**
+ * Unified mesh session identifier. v1 referred to "the session" with five
+ * different field names depending on which store you were reading; v2
+ * collapses them into one explicit handle that carries every disambiguator
+ * a consumer might need.
+ *
+ * - nodeId: the mesh node this session belongs to (FK into mesh node table).
+ * - sessionId: provider-instance identifier (the runtime session id).
+ * - providerType: which provider category/type the session runs (e.g.
+ *   'claude-cli', 'codex-cli', 'roo-code').
+ * - coordinatorDaemonId: which coordinator dispatched the work that
+ *   spawned this session. Used for completion event routing.
+ * - assignedAt: ms epoch when the session was bound to its current task.
+ */
+export interface MeshSessionHandle {
+  readonly nodeId: string;
+  readonly sessionId: string;
+  readonly providerType: ProviderType;
+  readonly coordinatorDaemonId: string;
+  readonly assignedAt: number;
+}
+
+export function meshSessionHandleKey(handle: MeshSessionHandle): string {
+  return `${handle.nodeId}|${handle.sessionId}`;
+}
+
+// ─── Task status (canonical enum) ────────────────────────────────────────
+
+/**
+ * Single canonical task status enum. v1 had at least three overlapping
+ * sets (queue / ledger / direct-dispatch). v2 consumers import from here.
+ */
+export const MESH_TASK_STATUSES = [
+  'pending',
+  'assigned',
+  'in_progress',
+  'completed',
+  'failed',
+  'cancelled',
+] as const;
+export type MeshTaskStatus = typeof MESH_TASK_STATUSES[number];
+
+export function isMeshTaskStatus(value: unknown): value is MeshTaskStatus {
+  return typeof value === 'string'
+    && (MESH_TASK_STATUSES as readonly string[]).includes(value);
+}
+
+// ─── Event scope ─────────────────────────────────────────────────────────
+
+/**
+ * Explicit scope for pending coordinator events. v1 had no scope: every
+ * event was broadcast to every drainer. v2 forces producers to declare
+ * intent.
+ *
+ * - 'unicast': delivered to exactly one coordinator (intendedFor). Other
+ *   coordinators' drains skip it.
+ * - 'broadcast': delivered to every coordinator on the mesh. Used for
+ *   system-wide signals (e.g. mesh-wide policy changes). The v1 default
+ *   becomes explicit here so audit tools can flag unintended broadcasts.
+ * - 'system': delivered to the daemon-level handler, not coordinators.
+ *   Reserved for infrastructure events that no coordinator should see
+ *   (e.g. ledger reconciliation outcomes).
+ */
+export const MESH_EVENT_SCOPES = ['unicast', 'broadcast', 'system'] as const;
+export type MeshEventScope = typeof MESH_EVENT_SCOPES[number];
+
+export function isMeshEventScope(value: unknown): value is MeshEventScope {
+  return typeof value === 'string'
+    && (MESH_EVENT_SCOPES as readonly string[]).includes(value);
+}
+
+// ─── Pending coordinator event v2 ────────────────────────────────────────
+
+/**
+ * v2 shape of a pending coordinator event. Strict supersets of the v1
+ * shape — every v1 field is preserved so existing readers do not break;
+ * v2 fields (scope, dispatchedBy, intendedFor, protocolVersion) are
+ * additive and consulted by v2-aware drainers only.
+ *
+ * Mixed v1/v2 events coexist during the rollout window. B2 fully cuts
+ * over once every coordinator drain is v2-aware.
+ */
+export interface PendingMeshCoordinatorEventV2 {
+  // v1 fields (preserved exactly)
+  readonly event: string;
+  readonly meshId: string;
+  readonly nodeLabel: string;
+  readonly nodeId?: string;
+  readonly workspace?: string;
+  readonly metadataEvent: Record<string, unknown>;
+  readonly coordinatorMessage?: string;
+  readonly queuedAt: number;
+
+  // v2 additions
+  readonly protocolVersion: MeshProtocolVersion;
+  readonly scope: MeshEventScope;
+  readonly dispatchedBy: CoordinatorIdentity;
+  /**
+   * Required when scope === 'unicast', forbidden otherwise. Drainers MUST
+   * skip unicast events whose intendedFor does not equal their own identity.
+   */
+  readonly intendedFor?: CoordinatorIdentity;
+}
+
+// ─── Ledger entry v2 ─────────────────────────────────────────────────────
+
+/**
+ * v2 ledger entry additions. The originatingCoordinator field is the
+ * source of truth that lets completion events route back to the
+ * coordinator that dispatched the task. v1's "worker settings carried it
+ * if it happened to be set" approach is replaced.
+ */
+export interface MeshLedgerOriginatingCoordinatorV2 {
+  readonly originatingCoordinator: CoordinatorIdentity;
+  readonly protocolVersion: MeshProtocolVersion;
+}
+
+// ─── Validation primitives ───────────────────────────────────────────────
+
+export class MeshContractViolationError extends Error {
+  readonly violationPath: string;
+  readonly protocolVersion: MeshProtocolVersion;
+  constructor(
+    protocolVersion: MeshProtocolVersion,
+    violationPath: string,
+    detail: string,
+  ) {
+    super(`mesh contract ${protocolVersion} violation at ${violationPath}: ${detail}`);
+    this.name = 'MeshContractViolationError';
+    this.violationPath = violationPath;
+    this.protocolVersion = protocolVersion;
+  }
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+export function assertCoordinatorIdentity(raw: unknown, path: string): CoordinatorIdentity {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, path, 'must be an object');
+  }
+  const obj = raw as Record<string, unknown>;
+  if (!isNonEmptyString(obj.daemonId)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.daemonId`, 'must be a non-empty string');
+  }
+  if (!isNonEmptyString(obj.coordinatorRunId)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.coordinatorRunId`, 'must be a non-empty string');
+  }
+  const sessionId = obj.sessionId;
+  if (sessionId !== undefined && !isNonEmptyString(sessionId)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.sessionId`, 'must be a non-empty string when provided');
+  }
+  return sessionId !== undefined
+    ? { daemonId: obj.daemonId, coordinatorRunId: obj.coordinatorRunId, sessionId }
+    : { daemonId: obj.daemonId, coordinatorRunId: obj.coordinatorRunId };
+}
+
+export function assertPendingMeshCoordinatorEventV2(raw: unknown, path = '$'): PendingMeshCoordinatorEventV2 {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, path, 'must be an object');
+  }
+  const obj = raw as Record<string, unknown>;
+  if (!isSupportedMeshProtocolVersion(obj.protocolVersion)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.protocolVersion`, `must be one of ${SUPPORTED_MESH_PROTOCOL_VERSIONS.join(', ')}`);
+  }
+  if (!isMeshEventScope(obj.scope)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.scope`, `must be one of ${MESH_EVENT_SCOPES.join(', ')}`);
+  }
+  if (!isNonEmptyString(obj.event)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.event`, 'must be a non-empty string');
+  }
+  if (!isNonEmptyString(obj.meshId)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.meshId`, 'must be a non-empty string');
+  }
+  const dispatchedBy = assertCoordinatorIdentity(obj.dispatchedBy, `${path}.dispatchedBy`);
+
+  if (obj.scope === 'unicast') {
+    if (!obj.intendedFor) {
+      throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.intendedFor`, 'unicast scope requires intendedFor');
+    }
+  } else if (obj.intendedFor !== undefined) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.intendedFor`, 'only unicast scope may set intendedFor');
+  }
+  const intendedFor = obj.intendedFor
+    ? assertCoordinatorIdentity(obj.intendedFor, `${path}.intendedFor`)
+    : undefined;
+
+  const metadata = obj.metadataEvent && typeof obj.metadataEvent === 'object' && !Array.isArray(obj.metadataEvent)
+    ? (obj.metadataEvent as Record<string, unknown>)
+    : null;
+  if (!metadata) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.metadataEvent`, 'must be an object');
+  }
+  const queuedAt = typeof obj.queuedAt === 'number' && Number.isFinite(obj.queuedAt) ? obj.queuedAt : null;
+  if (queuedAt === null) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.queuedAt`, 'must be a finite number');
+  }
+
+  return {
+    event: obj.event,
+    meshId: obj.meshId,
+    nodeLabel: isNonEmptyString(obj.nodeLabel) ? obj.nodeLabel : '',
+    nodeId: typeof obj.nodeId === 'string' ? obj.nodeId : undefined,
+    workspace: typeof obj.workspace === 'string' ? obj.workspace : undefined,
+    metadataEvent: metadata,
+    coordinatorMessage: typeof obj.coordinatorMessage === 'string' ? obj.coordinatorMessage : undefined,
+    queuedAt,
+    protocolVersion: obj.protocolVersion,
+    scope: obj.scope,
+    dispatchedBy,
+    ...(intendedFor ? { intendedFor } : {}),
+  };
+}
+
+// ─── Routing helper ──────────────────────────────────────────────────────
+
+/**
+ * Decide whether a v2 pending event should be delivered to the given drainer.
+ * Centralised so every drain implementation uses the same rule.
+ *
+ *   - 'broadcast': always delivered.
+ *   - 'system': never delivered to coordinators (system handler only).
+ *   - 'unicast': delivered iff intendedFor matches drainer identity.
+ *
+ * v1 events (no scope / no protocolVersion) are treated as broadcast for
+ * backward compatibility during rollout; B3 tightens this so v1 events
+ * are quarantined to a dedicated drain endpoint instead.
+ */
+export function shouldDeliverPendingEventToCoordinator(
+  event: PendingMeshCoordinatorEventV2,
+  drainer: CoordinatorIdentity,
+): boolean {
+  if (event.scope === 'system') return false;
+  if (event.scope === 'broadcast') return true;
+  if (!event.intendedFor) return false;
+  return coordinatorIdentityEquals(event.intendedFor, drainer);
+}

package/src/mesh/coordinator-prompt.ts

@@ -209,21 +209,16 @@ function buildRulesSection(coordinatorCliType?: string): string {
 
     return `## Rules
 
-- **Minimize coordinator context.** The coordinator's job is routing, not implementing. Do not read source files, run commands, or analyze code directly — delegate all of that to node agents. Your context should stay lean.
-- **Delegate analysis too.** If you need to understand a bug or explore the codebase, send that investigation as a task to the queue or a node. Do not do it yourself.
-- **Respect explicit provider requests.** If the user names an agent/provider, pass the matching provider type to \`mesh_launch_session\`: Hermes → \`hermes-cli\`, Claude Code/Claude → \`claude-cli\`, Codex → \`codex-cli\`, Gemini → \`gemini-cli\`, Antigravity → \`antigravity-cli\`. Never substitute \`claude-cli\` just because the coordinator itself is Claude Code.
-- **Front-load new task messages.** When calling \`mesh_enqueue_task\` or \`mesh_send_task\` for a new task, include everything the agent needs: what files to touch, what the problem is, what the fix should look like. The agent won't ask follow-up questions.
-- **Avoid context-wasting restarts.** For follow-up, retry, commit/push, preview, or cleanup work on the same issue, prefer the existing idle session and send only the delta from its last verified state. Start a fresh chat/session only for genuinely independent work, explicit provider/user request, unsafe transcript contamination, or required branch/worktree isolation.
-- **Don't inspect code.** Treat delegated agent summaries as self-reports, not verification. Verify side effects via \`mesh_git_status\` (including related repo freshness when configured), not by reading source files.
-- **Don't over-parallelize.** Start with 1-2 concurrent tasks. Scale up if they succeed. Never launch a duplicate session or second worker solely because \`mesh_read_chat\` has no final assistant message while the delegated session is still showing tool/terminal activity.
-- **Handle failures with context.** If a task fails, check \`mesh_task_history\` first to see if this task was attempted before and how it failed. Read the chat to understand why, then decide: retry on the same node, reassign to a different node, or escalate to the user.
-- **Check history before starting.** At the beginning of a coordination session, call \`mesh_task_history\` to understand what was previously delegated and its outcomes. This prevents duplicate work and informs recovery decisions.
-- **Keep the user informed.** Report progress after each delegation round — one or two sentences, not a narration.
-- **Respect node capabilities.** Don't send build tasks to read-only nodes. Don't push from nodes that aren't allowed to.
-- **Never fabricate tool results.** Always call the actual tool; never pretend you did.
-- **Clean up worktree nodes.** After a worktree task completes and its changes are merged or checkpointed, call \`mesh_remove_node\` to free resources.
-- **Do not strand completed branches.** A checkpointed or clean feature/worktree branch is not done by itself. Merge/refine it to the mesh default branch, fast-forward obvious clean behind-only branches with \`mesh_fast_forward_node\`, or explicitly report one of \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\` with the next action.
-- **Keep Refinery validation project-configurable.** \`mesh_refine_node\` must execute validation from repo mesh/refine config (for example \`.adhdev/refine.{json,yaml,yml}\`, \`.adhdev/repo-mesh-refine.*\`, or \`repo-mesh.refine.*\`). Heuristics are suggestions/scaffolding only, not the execution path.
-- **Treat submodule main reachability as publish-needed.** A \`submodule_reachability_failed\` refine result means the root gitlink points at a submodule commit that is not reachable from the configured submodule remote main branch. Do not treat feature-branch reachability as complete, retry validation blindly, or start code review first. Classify it as \`blocked_review\`, request user approval to push/publish the submodule commit to submodule main, then rerun \`mesh_refine_node\`, unless the mesh or repo refine config explicitly enabled \`allowAutoPublishSubmoduleMainCommits\` and Refinery reports exact path/commit/remote/branch evidence with post-publish verification.
-- **Name worktree branches meaningfully.** Use descriptive names like \`feat/auth-refactor\` or \`fix/build-123\`.${coordinatorNote}`;
+- **Route, don't implement.** Delegate all code reading, analysis, and execution to node agents. Never read source files or run commands in the coordinator — keep context lean.
+- **Front-load task messages.** Include everything the agent needs (files, problem, expected fix) in \`mesh_enqueue_task\` / \`mesh_send_task\`. Append a structured result request at the end: ask the worker to conclude with a JSON block containing \`status\`, \`changedFiles\`, \`gitStatus\`, \`validationResults\`, \`errors\`, \`nextAction\`. The daemon parses this automatically; you can read it from \`mesh_task_history\`.
+- **Reuse idle sessions.** For follow-up, retry, commit/push, or cleanup on the same issue, send only the delta to the existing idle session. Start fresh only for independent work, provider mismatch, transcript contamination, or required worktree isolation.
+- **Respect explicit provider requests.** Map: Hermes → \`hermes-cli\`, Claude/Claude Code → \`claude-cli\`, Codex → \`codex-cli\`, Gemini → \`gemini-cli\`, Antigravity → \`antigravity-cli\`. Never substitute the coordinator's own runtime.
+- **Verify via git, not source.** Use \`mesh_git_status\` to confirm side effects. Treat agent summaries as self-reports, not verification.
+- **Limit parallelism.** Start with 1–2 tasks; scale only on success. Never duplicate a session because \`mesh_read_chat\` shows no final message while tool/terminal activity is ongoing.
+- **Check history first.** Call \`mesh_task_history\` at session start to avoid duplicate work and inform recovery. On failure, read task history before retrying.
+- **Converge branches.** After worktree tasks: refine/fast-forward, or classify as \`pushed_feature_branch_needs_merge\` / \`blocked_review\` / \`cleanup_candidate\` / \`not_mergeable\`. Clean up with \`mesh_remove_node\`.
+- **Refinery is config-driven.** \`mesh_refine_node\` must run validation from \`.adhdev/refine.{json,yaml,yml}\` or \`repo-mesh.refine.*\`. Heuristics are scaffolding only.
+- **Submodule reachability = publish-needed.** \`submodule_reachability_failed\` → classify as \`blocked_review\`, request user approval to push to submodule main, then rerun \`mesh_refine_node\`.
+- **Never fabricate tool results.** Always call the actual tool.
+- **Keep the user informed.** One or two sentences after each delegation round.${coordinatorNote}`;
 }

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

@@ -1,5 +1,5 @@
 import type { MeshLedgerEntry } from './mesh-ledger.js';
-import type { MeshWorkQueueEntry } from './mesh-work-queue.js';
+import type { MeshWorkQueueEntry, DirectDispatchRecord } from './mesh-work-queue.js';
 
 export type MeshActiveWorkSource = 'queue' | 'direct';
 export type MeshActiveWorkStatus = 'pending' | 'assigned' | 'generating' | 'idle' | 'failed' | 'awaiting_approval';
@@ -69,6 +69,12 @@ export interface BuildMeshActiveWorkOptions {
     meshId: string;
     queue?: MeshWorkQueueEntry[];
     ledgerEntries?: MeshLedgerEntry[];
+    /**
+     * Active direct dispatches from BeadsDB. When provided, these are used instead of
+     * scanning ledger entries for direct dispatches — eliminates the O(n_ledger) scan.
+     * Falls back to ledger scanning when not provided.
+     */
+    directDispatches?: DirectDispatchRecord[];
     nodes?: any[];
     now?: number;
     /** Include terminal direct rows (idle/failed) for handoff/recent-work surfaces. Defaults false. */
@@ -218,66 +224,163 @@ export function buildMeshActiveWork(opts: BuildMeshActiveWorkOptions): { activeW
         });
     }
 
-    const ledgerEntries = (opts.ledgerEntries || []).slice().sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
-    const terminals = ledgerEntries.filter(entry => TERMINAL_LEDGER_KINDS.has(entry.kind) || entry.kind === 'task_approval_needed');
-    for (const dispatch of ledgerEntries.filter(isDirectDispatch)) {
-        const taskId = directDispatchTaskId(dispatch);
-        const terminal = terminals
-            .filter(entry => new Date(entry.timestamp).getTime() >= new Date(dispatch.timestamp).getTime())
-            .find(entry => terminalMatchesDispatch(entry, dispatch, taskId));
-        const terminalStatus = terminal ? statusFromTerminal(terminal) : undefined;
-        const live = sessionStatusFromNodes(opts.nodes, dispatch.nodeId, dispatch.sessionId);
-        const status = terminalStatus || live.status || 'assigned';
-        const terminalRow = Boolean(terminal && terminal.kind !== 'task_approval_needed');
-        // dispatchedToIdleSession is recorded by mesh_send_task when the target session was idle
-        // at dispatch time. Combined with status === 'idle', it confirms no runtime transition.
-        const dispatchedToIdleSession = dispatch.payload?.dispatchedToIdleSession === true;
-        // Flag stale when no terminal event AND either:
-        // - session is now idle (dispatch not acknowledged), OR
-        // - no live status reported (node/session absent from live mesh), OR
-        // - payload flagged idle-at-dispatch AND session is still not generating (redundant guard for clarity).
-        const isNoTransition = !terminalStatus && !live.status;
-        const isIdleUnacknowledged = status === 'idle';
-        const ledgerOnlyStaleReason = !terminalRow && (isIdleUnacknowledged || isNoTransition || (dispatchedToIdleSession && isIdleUnacknowledged))
-            ? 'direct task dispatch has no provider acknowledgement, transcript append, or active runtime transition'
-            : undefined;
-        const message = readString(dispatch.payload?.message) || readString(dispatch.payload?.summary) || '';
-        const { title, summary } = summarizeMessage(message);
-        // A dispatch is a fresh unacknowledged failure when the node and session both still exist
-        // in the live mesh but the session never transitioned to generating. This is distinct from
-        // historical/orphaned stale entries where the node or session is gone from the live mesh.
-        // fresh-unacknowledged: ledgerOnlyStaleReason is set (session didn't ack) AND no live.staleReason (node/session is present)
-        const isFreshUnacknowledged = Boolean(ledgerOnlyStaleReason && !live.staleReason);
-        const record: MeshActiveWorkRecord = {
-            taskId,
-            source: 'direct',
-            status,
-            nodeId: dispatch.nodeId,
-            sessionId: dispatch.sessionId,
-            providerType: dispatch.providerType || readString(dispatch.payload?.providerType),
-            taskTitle: readString(dispatch.payload?.taskTitle) || title,
-            taskSummary: readString(dispatch.payload?.taskSummary) || summary,
-            message,
-            taskMode: readString(dispatch.payload?.taskMode),
-            createdAt: dispatch.timestamp,
-            updatedAt: terminal?.timestamp || dispatch.timestamp,
-            dispatchedAt: dispatch.timestamp,
-            elapsedMs: elapsedSince(dispatch.timestamp, now),
-            terminal: terminalRow,
-            terminalKind: terminal?.kind,
-            terminalAt: terminal?.timestamp,
-            staleReason: live.staleReason || ledgerOnlyStaleReason,
-            ...(isFreshUnacknowledged ? { staleDispatchUnacknowledged: true } : {}),
-        };
-        if (terminalRow) {
-            terminalDirectWork.push(record);
-            if (opts.includeTerminalDirect !== true) continue;
+    // When BeadsDB direct dispatches are provided, use them for LOCAL dispatches (O(1) indexed).
+    // ALSO scan ledger for remote dispatches (P2P) whose taskIds are not in BeadsDB — these
+    // are never written to the local BeadsDB since they're dispatched from a remote daemon.
+    if (opts.directDispatches !== undefined) {
+        const dbTaskIds = new Set(opts.directDispatches.map(d => d.taskId));
+        for (const dispatch of opts.directDispatches) {
+            const live = sessionStatusFromNodes(opts.nodes, dispatch.nodeId ?? undefined, dispatch.sessionId ?? undefined);
+            const dbStatus = dispatch.status; // 'dispatched' | 'acked' | 'completed' | 'failed' | 'stale'
+            const isTerminal = dbStatus === 'completed' || dbStatus === 'failed' || dbStatus === 'stale';
+            const status: MeshActiveWorkStatus = isTerminal
+                ? (dbStatus === 'completed' ? 'idle' : 'failed')
+                : live.status || (dbStatus === 'acked' ? 'generating' : 'assigned');
+            const isNoTransition = !isTerminal && !live.status;
+            const isIdleUnacknowledged = status === 'idle' && !isTerminal;
+            const ledgerOnlyStaleReason = !isTerminal && (isIdleUnacknowledged || isNoTransition || (dispatch.dispatchedToIdleSession && isIdleUnacknowledged))
+                ? 'direct task dispatch has no provider acknowledgement, transcript append, or active runtime transition'
+                : undefined;
+            const isFreshUnacknowledged = Boolean(ledgerOnlyStaleReason && !live.staleReason);
+            const { title, summary } = summarizeMessage(dispatch.message || '');
+            const record: MeshActiveWorkRecord = {
+                taskId: dispatch.taskId,
+                source: 'direct',
+                status,
+                nodeId: dispatch.nodeId ?? undefined,
+                sessionId: dispatch.sessionId ?? undefined,
+                providerType: dispatch.providerType ?? undefined,
+                taskTitle: title,
+                taskSummary: summary,
+                message: dispatch.message,
+                taskMode: dispatch.taskMode ?? undefined,
+                createdAt: dispatch.dispatchedAt,
+                updatedAt: dispatch.updatedAt,
+                dispatchedAt: dispatch.dispatchedAt,
+                elapsedMs: elapsedSince(dispatch.dispatchedAt, now),
+                terminal: isTerminal,
+                terminalKind: isTerminal ? (dbStatus === 'completed' ? 'task_completed' : 'task_failed') : undefined,
+                terminalAt: isTerminal ? dispatch.updatedAt : undefined,
+                staleReason: live.staleReason || ledgerOnlyStaleReason,
+                ...(isFreshUnacknowledged ? { staleDispatchUnacknowledged: true } : {}),
+            };
+            if (isTerminal) {
+                terminalDirectWork.push(record);
+                if (opts.includeTerminalDirect !== true) continue;
+            }
+            if ((live.staleReason || ledgerOnlyStaleReason) && !isTerminal) {
+                staleDirectWork.push(record);
+                continue;
+            }
+            records.push(record);
+        }
+        // Also scan ledger for remote dispatches (via p2p_direct) whose taskIds are NOT in BeadsDB.
+        // Remote daemons write their own local BeadsDB; this coordinator's BeadsDB only has local dispatches.
+        const ledgerEntries = (opts.ledgerEntries || []).slice().sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+        const terminals = ledgerEntries.filter(entry => TERMINAL_LEDGER_KINDS.has(entry.kind) || entry.kind === 'task_approval_needed');
+        for (const dispatch of ledgerEntries.filter(isDirectDispatch)) {
+            const taskId = directDispatchTaskId(dispatch);
+            if (dbTaskIds.has(taskId)) continue; // already covered by BeadsDB path above
+            const terminal = terminals
+                .filter(entry => new Date(entry.timestamp).getTime() >= new Date(dispatch.timestamp).getTime())
+                .find(entry => terminalMatchesDispatch(entry, dispatch, taskId));
+            const terminalStatus = terminal ? statusFromTerminal(terminal) : undefined;
+            const live = sessionStatusFromNodes(opts.nodes, dispatch.nodeId, dispatch.sessionId);
+            const status = terminalStatus || live.status || 'assigned';
+            const terminalRow = Boolean(terminal && terminal.kind !== 'task_approval_needed');
+            const dispatchedToIdleSession = dispatch.payload?.dispatchedToIdleSession === true;
+            const isNoTransition = !terminalStatus && !live.status;
+            const isIdleUnacknowledged = status === 'idle';
+            const ledgerOnlyStaleReason = !terminalRow && (isIdleUnacknowledged || isNoTransition || (dispatchedToIdleSession && isIdleUnacknowledged))
+                ? 'direct task dispatch has no provider acknowledgement, transcript append, or active runtime transition'
+                : undefined;
+            const message = readString(dispatch.payload?.message) || readString(dispatch.payload?.summary) || '';
+            const { title, summary } = summarizeMessage(message);
+            const isFreshUnacknowledged = Boolean(ledgerOnlyStaleReason && !live.staleReason);
+            const record: MeshActiveWorkRecord = {
+                taskId,
+                source: 'direct',
+                status,
+                nodeId: dispatch.nodeId,
+                sessionId: dispatch.sessionId,
+                providerType: dispatch.providerType || readString(dispatch.payload?.providerType),
+                taskTitle: readString(dispatch.payload?.taskTitle) || title,
+                taskSummary: readString(dispatch.payload?.taskSummary) || summary,
+                message,
+                taskMode: readString(dispatch.payload?.taskMode),
+                createdAt: dispatch.timestamp,
+                updatedAt: terminal?.timestamp || dispatch.timestamp,
+                dispatchedAt: dispatch.timestamp,
+                elapsedMs: elapsedSince(dispatch.timestamp, now),
+                terminal: terminalRow,
+                terminalKind: terminal?.kind,
+                terminalAt: terminal?.timestamp,
+                staleReason: live.staleReason || ledgerOnlyStaleReason,
+                ...(isFreshUnacknowledged ? { staleDispatchUnacknowledged: true } : {}),
+            };
+            if (terminalRow) {
+                terminalDirectWork.push(record);
+                if (opts.includeTerminalDirect !== true) continue;
+            }
+            if ((live.staleReason || ledgerOnlyStaleReason) && !terminalRow) {
+                staleDirectWork.push(record);
+                continue;
+            }
+            records.push(record);
         }
-        if ((live.staleReason || ledgerOnlyStaleReason) && !terminalRow) {
-            staleDirectWork.push(record);
-            continue;
+    } else {
+        // Full ledger scan: no BeadsDB direct dispatches available (standalone mode or empty).
+        const ledgerEntries = (opts.ledgerEntries || []).slice().sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+        const terminals = ledgerEntries.filter(entry => TERMINAL_LEDGER_KINDS.has(entry.kind) || entry.kind === 'task_approval_needed');
+        for (const dispatch of ledgerEntries.filter(isDirectDispatch)) {
+            const taskId = directDispatchTaskId(dispatch);
+            const terminal = terminals
+                .filter(entry => new Date(entry.timestamp).getTime() >= new Date(dispatch.timestamp).getTime())
+                .find(entry => terminalMatchesDispatch(entry, dispatch, taskId));
+            const terminalStatus = terminal ? statusFromTerminal(terminal) : undefined;
+            const live = sessionStatusFromNodes(opts.nodes, dispatch.nodeId, dispatch.sessionId);
+            const status = terminalStatus || live.status || 'assigned';
+            const terminalRow = Boolean(terminal && terminal.kind !== 'task_approval_needed');
+            const dispatchedToIdleSession = dispatch.payload?.dispatchedToIdleSession === true;
+            const isNoTransition = !terminalStatus && !live.status;
+            const isIdleUnacknowledged = status === 'idle';
+            const ledgerOnlyStaleReason = !terminalRow && (isIdleUnacknowledged || isNoTransition || (dispatchedToIdleSession && isIdleUnacknowledged))
+                ? 'direct task dispatch has no provider acknowledgement, transcript append, or active runtime transition'
+                : undefined;
+            const message = readString(dispatch.payload?.message) || readString(dispatch.payload?.summary) || '';
+            const { title, summary } = summarizeMessage(message);
+            const isFreshUnacknowledged = Boolean(ledgerOnlyStaleReason && !live.staleReason);
+            const record: MeshActiveWorkRecord = {
+                taskId,
+                source: 'direct',
+                status,
+                nodeId: dispatch.nodeId,
+                sessionId: dispatch.sessionId,
+                providerType: dispatch.providerType || readString(dispatch.payload?.providerType),
+                taskTitle: readString(dispatch.payload?.taskTitle) || title,
+                taskSummary: readString(dispatch.payload?.taskSummary) || summary,
+                message,
+                taskMode: readString(dispatch.payload?.taskMode),
+                createdAt: dispatch.timestamp,
+                updatedAt: terminal?.timestamp || dispatch.timestamp,
+                dispatchedAt: dispatch.timestamp,
+                elapsedMs: elapsedSince(dispatch.timestamp, now),
+                terminal: terminalRow,
+                terminalKind: terminal?.kind,
+                terminalAt: terminal?.timestamp,
+                staleReason: live.staleReason || ledgerOnlyStaleReason,
+                ...(isFreshUnacknowledged ? { staleDispatchUnacknowledged: true } : {}),
+            };
+            if (terminalRow) {
+                terminalDirectWork.push(record);
+                if (opts.includeTerminalDirect !== true) continue;
+            }
+            if ((live.staleReason || ledgerOnlyStaleReason) && !terminalRow) {
+                staleDirectWork.push(record);
+                continue;
+            }
+            records.push(record);
         }
-        records.push(record);
     }
 
     records.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());