@adhdev/daemon-core 1.0.28-rc.6 → 1.0.28-rc.8

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

@@ -293,6 +293,30 @@ function warnDispatchWarmupGetterMissingOnce(daemonId: string): void {
     LOG.warn('MeshQueue', `Mesh peer connection getter unavailable for ${String(daemonId).slice(0, 12)}; remote task-dispatch warmup deadline degraded to the combined connect+response window. Avoids a cold-open false-timeout but loses warm/cold precision — wire getMeshPeerConnectionStatus on this daemon.`);
 }
 
+// LEDGER-TASK-TRACEABILITY (A/D): the routing rationale captured at claim/dispatch
+// time so mesh_task_history / the dashboard can answer "why THIS node/provider/model".
+// All fields optional — the event-driven / idle drains don't compute a fitness score,
+// so they omit the extras and only `source` is always present.
+export interface MeshTaskRoutingDecision {
+    // How the task reached this dispatch: a normal queue claim, the auto-launch drain
+    // that spawned a fresh worker, or a coordinator direct dispatch (mesh_send_task).
+    source: 'queue' | 'autoLaunch' | 'direct';
+    // The task→slot fitness score of the selected node (scoreSlotForTask), when the
+    // 'fitness' scheduling strategy ranked candidates. Absent for first_eligible etc.
+    fitnessScore?: number;
+    // Candidate nodes considered but skipped before this one won, with the reason.
+    skippedCandidates?: Array<{ nodeId: string; reason: string }>;
+    // Required-tag gating result for the selected node.
+    requiredTagsResult?: { required: string[]; satisfied: boolean; missing: string[] };
+    // The resolved execution profile (D): provider actually launched, and the
+    // model/thinking/difficulty axes that shaped it, plus the human-readable reason.
+    resolvedProviderType?: string;
+    resolvedModel?: string;
+    resolvedThinkingLevel?: string;
+    resolvedDifficulty?: string;
+    reason?: string;
+}
+
 interface DeliverTaskContext {
     meshId: string;
     nodeId: string;
@@ -302,6 +326,8 @@ interface DeliverTaskContext {
     transport: 'remote' | 'local';
     sourceCoordinatorSessionId?: string;
     sourceCoordinatorDaemonId?: string;
+    // LEDGER-TASK-TRACEABILITY (A): routing rationale to record on task_dispatched.
+    routingDecision?: MeshTaskRoutingDecision;
 }
 
 // Readiness barrier for the LOCAL auto-launch path. A just-spawned CLI session is
@@ -346,6 +372,51 @@ async function waitForLocalSessionReady(components: DaemonComponents, sessionId:
 // (response budget governs from t0), so a normal dispatch sees no added latency. The
 // LOCAL transport (in-process cliManager) has no channel to warm up and keeps the
 // flat Bug B hang guard.
+/**
+ * LEDGER-TASK-TRACEABILITY (A/D): append a task_dispatched entry from an already-built
+ * dispatch context. Reads the execution profile off the claimed task (model/thinking/
+ * difficulty/coordinator session were stamped at enqueue/claim) and folds in the caller's
+ * routing rationale. Hot-path-safe: no detection, no scoring — everything is precomputed.
+ * taskId is promoted to the base field (B) so the row joins the lifecycle by kind+taskId.
+ */
+function recordTaskDispatchedLedger(ctx: DeliverTaskContext, deliveryId: string): void {
+    const task = ctx.task;
+    const routing = ctx.routingDecision;
+    const routingDecision: Record<string, unknown> = {
+        source: routing?.source ?? 'queue',
+        selectedNodeId: ctx.nodeId,
+        ...(localCoordinatorDaemonId() ? { daemonId: localCoordinatorDaemonId() } : {}),
+        transport: ctx.transport,
+        // D: resolved execution profile — prefer the caller's resolved values, fall back
+        // to what the claimed task row carries (queue/idle drains carry it on the task).
+        resolvedProviderType: routing?.resolvedProviderType ?? ctx.providerType,
+        ...(routing?.resolvedModel ?? task.model ? { resolvedModel: routing?.resolvedModel ?? task.model } : {}),
+        ...(routing?.resolvedThinkingLevel ?? task.thinkingLevel ? { resolvedThinkingLevel: routing?.resolvedThinkingLevel ?? task.thinkingLevel } : {}),
+        ...(routing?.resolvedDifficulty ?? task.difficulty ? { resolvedDifficulty: routing?.resolvedDifficulty ?? task.difficulty } : {}),
+        ...(typeof routing?.fitnessScore === 'number' ? { fitnessScore: routing.fitnessScore } : {}),
+        ...(routing?.skippedCandidates?.length ? { skippedCandidates: routing.skippedCandidates } : {}),
+        ...(routing?.requiredTagsResult ? { requiredTagsResult: routing.requiredTagsResult } : {}),
+        ...(routing?.reason ? { reason: routing.reason } : {}),
+    };
+    appendLedgerEntry(ctx.meshId, {
+        kind: 'task_dispatched',
+        nodeId: ctx.nodeId,
+        sessionId: ctx.sessionId,
+        providerType: ctx.providerType,
+        taskId: task.id,
+        payload: {
+            taskId: task.id,
+            ...(task.missionId ? { missionId: task.missionId } : {}),
+            deliveryId,
+            transport: ctx.transport,
+            ...(ctx.sourceCoordinatorSessionId ? { coordinatorSessionId: ctx.sourceCoordinatorSessionId } : {}),
+            ...(ctx.sourceCoordinatorDaemonId ? { coordinatorDaemonId: ctx.sourceCoordinatorDaemonId } : {}),
+            ...(Array.isArray(task.requiredTags) && task.requiredTags.length ? { requiredTags: task.requiredTags } : {}),
+            routingDecision,
+        },
+    });
+}
+
 function deliverTaskToSession(
     dispatchThunk: () => Promise<unknown>,
     ctx: DeliverTaskContext,
@@ -364,6 +435,15 @@ function deliverTaskToSession(
         ...(ctx.sourceCoordinatorDaemonId ? { sourceCoordinatorDaemonId: ctx.sourceCoordinatorDaemonId } : {}),
     });
 
+    // LEDGER-TASK-TRACEABILITY (A): record the dispatch — the single funnel every
+    // queue-claim dispatch (local + remote) flows through — so mesh_task_history and the
+    // dashboard can show "which device/daemon/provider/model, via what path, and why".
+    // All routing values are ALREADY computed by the caller (no re-serialization on the
+    // hot path); the delivery id links this to the delivered/failed transitions below.
+    try {
+        recordTaskDispatchedLedger(ctx, delivery.id);
+    } catch { /* ledger write is best-effort — dispatch proceeds regardless */ }
+
     // Invoke the transport synchronously (preserves the prior fire-and-forget timing,
     // and lets a synchronous throw fall into the same failure path as a rejection).
     let dispatchPromise: Promise<unknown>;
@@ -466,7 +546,12 @@ export function tryAssignQueueTask(
     meshId: string,
     nodeId: string,
     sessionId: string,
-    providerType: string
+    providerType: string,
+    // LEDGER-TASK-TRACEABILITY (A): routing rationale computed by the auto-launch drain
+    // (fitness score, skipped candidates, resolved model/thinking). Threaded to the
+    // task_dispatched ledger entry. Other claim paths (event/idle drain) omit it and the
+    // entry records source:'queue' with just the resolved provider from the claimed row.
+    routingDecision?: MeshTaskRoutingDecision,
 ): boolean {
     const mesh = getMeshWithCache(components, meshId);
     // Match with the shared 3-form normalizer (id / nodeId / node_id), not raw
@@ -652,6 +737,29 @@ export function tryAssignQueueTask(
 
     LOG.info('MeshQueue', `Node ${nodeId} (${sessionId}) pulled task ${task.id}`);
 
+    // LEDGER-TASK-TRACEABILITY (C): the task just transitioned pending→assigned. Record
+    // the claim (distinct from the later task_dispatched, which fires when the message is
+    // handed to the transport in deliverTaskToSession). This is the single funnel every
+    // claim path (event/idle drain, auto-launch, remote reclaim) flows through, so one
+    // append here covers them all. Best-effort — a ledger write must never fail a claim.
+    try {
+        appendLedgerEntry(meshId, {
+            kind: 'task_claimed',
+            nodeId,
+            sessionId,
+            providerType,
+            taskId: task.id,
+            payload: {
+                taskId: task.id,
+                ...(task.missionId ? { missionId: task.missionId } : {}),
+                nodeId,
+                sessionId,
+                providerType,
+                claimedAt: new Date().toISOString(),
+            },
+        });
+    } catch { /* best-effort — claim proceeds regardless */ }
+
     // FALSE-BLOCKER-CLONE-QUEUE (stale-event clear): the task just claimed and will dispatch,
     // so any actionable blocker previously paged for it (e.g. a 'target_node_id_unmatched'
     // emitted during the clone/bootstrap propagation window before the node became
@@ -726,6 +834,7 @@ export function tryAssignQueueTask(
                     transport: 'remote',
                     ...(sourceCoordinatorSessionId ? { sourceCoordinatorSessionId } : {}),
                     ...(localDaemonIdForDispatch ? { sourceCoordinatorDaemonId: localDaemonIdForDispatch } : {}),
+                    ...(routingDecision ? { routingDecision } : {}),
                 },
                 // Warmup-aware deadline: this dispatch can be the FIRST command to a
                 // peer whose mesh DataChannel is still opening — charge the cold-open
@@ -815,6 +924,7 @@ export function tryAssignQueueTask(
             transport: 'local',
             ...(readNonEmptyString(task.sourceCoordinatorSessionId) ? { sourceCoordinatorSessionId: readNonEmptyString(task.sourceCoordinatorSessionId) } : {}),
             ...(localCoordinatorDaemonId() ? { sourceCoordinatorDaemonId: localCoordinatorDaemonId() } : {}),
+            ...(routingDecision ? { routingDecision } : {}),
         },
     );
 
@@ -1832,6 +1942,11 @@ function recordAutoLaunchEvent(meshId: string, args: {
     sessionId?: string;
     reason?: string;
     error?: string;
+    // LEDGER-TASK-TRACEABILITY (D): the resolved execution profile the auto-launch
+    // resolved for this worker, so session_auto_launch records what model/thinking the
+    // spawned worker actually launched with (not just the provider).
+    model?: string;
+    thinkingLevel?: string;
 }) {
     // Suppress consecutive identical `skipped` entries for the same task (4s reconcile
     // re-trigger noise). Non-skip phases and changed reasons always record and reset
@@ -1853,11 +1968,16 @@ function recordAutoLaunchEvent(meshId: string, args: {
             nodeId: args.nodeId,
             sessionId: args.sessionId,
             providerType: args.providerType,
+            // (B) promote taskId so this entry joins the task lifecycle timeline.
+            ...(args.taskId ? { taskId: args.taskId } : {}),
             payload: {
                 phase: args.phase,
                 taskId: args.taskId,
                 reason: args.reason,
                 error: args.error,
+                // (D) resolved execution profile for the spawned worker.
+                ...(args.model ? { resolvedModel: args.model } : {}),
+                ...(args.thinkingLevel ? { resolvedThinkingLevel: args.thinkingLevel } : {}),
             },
         });
     } catch (e: any) {
@@ -1872,6 +1992,9 @@ function markAutoLaunch(meshId: string, taskId: string, args: {
     providerType?: string;
     sessionId?: string;
     error?: string;
+    // LEDGER-TASK-TRACEABILITY (D): resolved execution profile for started/completed.
+    model?: string;
+    thinkingLevel?: string;
 }) {
     recordTaskAutoLaunch(meshId, taskId, {
         status: args.status,
@@ -1888,6 +2011,8 @@ function markAutoLaunch(meshId: string, taskId: string, args: {
         sessionId: args.sessionId,
         reason: args.reason,
         error: args.error,
+        ...(args.model ? { model: args.model } : {}),
+        ...(args.thinkingLevel ? { thinkingLevel: args.thinkingLevel } : {}),
     });
     // Fix (1): actively notify the coordinator of a non-self-resolving skip; re-arm the
     // notification on any non-skip transition (started/completed) so a later genuine skip
@@ -2278,6 +2403,20 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                 { bumpCursor: true, task: { difficulty: (task as any).difficulty, requiredTags: task.requiredTags } },
             ).map((c: RankableNode) => c.node);
 
+        // LEDGER-TASK-TRACEABILITY (A): accumulate the candidate nodes that were
+        // considered but skipped before the winning node, so task_dispatched can record
+        // WHY the other nodes lost (cooldown, dirty, cap, provider mismatch, …). Bounded
+        // so a large fleet can't bloat the entry. markSkip mirrors markAutoLaunch's skip
+        // side effect AND appends to this list in one call.
+        const skippedCandidates: Array<{ nodeId: string; reason: string }> = [];
+        const SKIPPED_CANDIDATES_MAX = 12;
+        const markSkip = (nodeIdForSkip: string, reason: string, extra?: { providerType?: string }) => {
+            markAutoLaunch(meshId, task.id, { status: 'skipped', reason, nodeId: nodeIdForSkip, ...(extra || {}) });
+            if (nodeIdForSkip && skippedCandidates.length < SKIPPED_CANDIDATES_MAX) {
+                skippedCandidates.push({ nodeId: nodeIdForSkip, reason });
+            }
+        };
+
         for (const node of orderedCandidateNodes) {
             const nodeId = readMeshNodeId(node);
             if (!nodeId) continue;
@@ -2286,19 +2425,19 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
             const cooldownUntil = autoLaunchCooldownUntil.get(launchKey) || 0;
             if (cooldownUntil > 0 && now >= cooldownUntil) autoLaunchCooldownUntil.delete(launchKey);
             if (autoLaunchInProgress.has(launchKey)) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'auto_launch_in_progress', nodeId });
+                markSkip(nodeId, 'auto_launch_in_progress');
                 continue;
             }
             if (now < cooldownUntil) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'auto_launch_cooldown', nodeId });
+                markSkip(nodeId, 'auto_launch_cooldown');
                 continue;
             }
             if (isDirtyNode(node)) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'dirty_workspace', nodeId });
+                markSkip(nodeId, 'dirty_workspace');
                 continue;
             }
             if (!isLaunchableNode(node)) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_not_launch_ready', nodeId });
+                markSkip(nodeId, 'node_not_launch_ready');
                 continue;
             }
             // FRESHNESS gate (distinct from the health gate above): a clean-tree node that
@@ -2310,7 +2449,7 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
             // place. Telemetry-absent nodes pass (never block on missing data). The 4s
             // reconcile retries once the node's auto-ff repair path catches it up.
             if (!isMeshNodeFreshEnoughToLaunch(node, freshnessGate)) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_stale_behind_upstream', nodeId });
+                markSkip(nodeId, 'node_stale_behind_upstream');
                 continue;
             }
             const launchTarget = resolveAutoLaunchTarget(components, node);
@@ -2318,7 +2457,7 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                 // Remote node we can't reach (no transport / no coordinator daemonId).
                 // Set a cooldown so the 4s reconcile loop doesn't re-attempt this node
                 // every tick; the de-dup'd skip ledger keeps it diagnosable without flood.
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: launchTarget.reason || 'auto_launch_unavailable', nodeId });
+                markSkip(nodeId, launchTarget.reason || 'auto_launch_unavailable');
                 autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS); sweepExpiredCooldowns();
                 continue;
             }
@@ -2333,19 +2472,19 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
             // reason so the coordinator is not paged; the 4s reconcile retries, and once the
             // existing session goes terminal this gate clears and a legitimate launch proceeds.
             if (nodeHasLiveSessionPendingClaim(components, meshId, nodeId, task, node)) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_has_live_session_pending_claim', nodeId });
+                markSkip(nodeId, 'node_has_live_session_pending_claim');
                 continue;
             }
             // Write tasks keep the one-active-per-node invariant (worktree isolation);
             // read-only diagnoses may auto-launch onto a node that already has an active
             // assignment. Classified by the shared isTaskReadonly predicate.
             if (!isTaskReadonly(task) && nodeHasActiveAssignment(meshId, nodeId)) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_has_active_assignment', nodeId });
+                markSkip(nodeId, 'node_has_active_assignment');
                 continue;
             }
             const maxConcurrentSessions = Number(node?.policy?.maxConcurrentSessions);
             if (Number.isFinite(maxConcurrentSessions) && maxConcurrentSessions >= 0 && liveSessionCountForNode(components, meshId, nodeId) >= maxConcurrentSessions) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'max_concurrent_sessions_reached', nodeId });
+                markSkip(nodeId, 'max_concurrent_sessions_reached');
                 continue;
             }
 
@@ -2353,7 +2492,7 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
             try {
                 const resolved = await resolveUsableProvider(components, nodeId, node, task.requiredTags, { difficulty: (task as any).difficulty, requiredTags: task.requiredTags });
                 if (!resolved.providerType) {
-                    markAutoLaunch(meshId, task.id, { status: 'skipped', reason: resolved.reason || 'provider_unusable', nodeId });
+                    markSkip(nodeId, resolved.reason || 'provider_unusable');
                     continue;
                 }
                 // Slot-derived model/thinking: an explicit task.model/thinkingLevel
@@ -2388,7 +2527,7 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                     providerCap !== undefined
                     && activeProviderAssignedCount(meshId, nodeId, resolved.providerType) >= providerCap
                 ) {
-                    markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'max_provider_parallel_reached', nodeId, providerType: resolved.providerType });
+                    markSkip(nodeId, 'max_provider_parallel_reached', { providerType: resolved.providerType });
                     continue;
                 }
 
@@ -2424,7 +2563,7 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                         meshCoordinatorDaemonId: launchTarget.coordinatorDaemonId,
                         meshCoordinatorNodeId: nodeId,
                     };
-                    markAutoLaunch(meshId, task.id, { status: 'started', nodeId, providerType: resolved.providerType });
+                    markAutoLaunch(meshId, task.id, { status: 'started', nodeId, providerType: resolved.providerType, ...(effectiveModel ? { model: effectiveModel } : {}), ...(effectiveThinkingLevel ? { thinkingLevel: effectiveThinkingLevel } : {}) });
                     let launchResult: any;
                     try {
                         // OFFLINE-NODE-BLOCKING: no peer-connected pre-check before this remote
@@ -2464,12 +2603,12 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                     // which (forwarded back here) drives the claim via the normal event path / PHASE 1
                     // reconcile. Set a cooldown so the 4s loop doesn't re-launch before that lands.
                     const remoteSessionId = readNonEmptyString(payload.sessionId) || readNonEmptyString(payload.id) || readNonEmptyString(payload.runtimeSessionId);
-                    markAutoLaunch(meshId, task.id, { status: 'completed', nodeId, providerType: resolved.providerType, sessionId: remoteSessionId || undefined });
+                    markAutoLaunch(meshId, task.id, { status: 'completed', nodeId, providerType: resolved.providerType, sessionId: remoteSessionId || undefined, ...(effectiveModel ? { model: effectiveModel } : {}), ...(effectiveThinkingLevel ? { thinkingLevel: effectiveThinkingLevel } : {}) });
                     autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS); sweepExpiredCooldowns();
                     return true;
                 }
 
-                markAutoLaunch(meshId, task.id, { status: 'started', nodeId, providerType: resolved.providerType });
+                markAutoLaunch(meshId, task.id, { status: 'started', nodeId, providerType: resolved.providerType, ...(effectiveModel ? { model: effectiveModel } : {}), ...(effectiveThinkingLevel ? { thinkingLevel: effectiveThinkingLevel } : {}) });
                 const launchResult: any = await components.cliManager.handleCliCommand('launch_cli', {
                     cliType: resolved.providerType,
                     dir: node.workspace,
@@ -2492,7 +2631,7 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                     autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS); sweepExpiredCooldowns();
                     return false;
                 }
-                markAutoLaunch(meshId, task.id, { status: 'completed', nodeId, providerType: resolved.providerType, sessionId });
+                markAutoLaunch(meshId, task.id, { status: 'completed', nodeId, providerType: resolved.providerType, sessionId, ...(effectiveModel ? { model: effectiveModel } : {}), ...(effectiveThinkingLevel ? { thinkingLevel: effectiveThinkingLevel } : {}) });
                 // Readiness barrier: a freshly-spawned local CLI session is NOT yet
                 // interactive — its PTY prints the input prompt (and the adapter flips
                 // isReady()) only ~2-6s after launch. Dispatching the task immediately
@@ -2503,7 +2642,27 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                 // first message lands cleanly. The adapter's queue-until-ready path is the
                 // backstop if readiness is reported late; this just avoids the churn.
                 await waitForLocalSessionReady(components, sessionId);
-                tryAssignQueueTask(components, meshId, nodeId, sessionId, resolved.providerType);
+                // LEDGER-TASK-TRACEABILITY (A/D): the auto-launch drain has all the routing
+                // rationale in scope (resolved provider/model/thinking, skipped candidates,
+                // fitness score). Fold it into the task_dispatched entry the claim writes.
+                // All values are already computed above — no extra work on the dispatch path.
+                const requiredTags = Array.isArray(task.requiredTags) ? task.requiredTags.filter((t): t is string => !!t) : [];
+                const routingDecision: MeshTaskRoutingDecision = {
+                    source: 'autoLaunch',
+                    fitnessScore: nodeFitnessForTask(node, { difficulty: (task as any).difficulty, requiredTags: task.requiredTags }),
+                    ...(skippedCandidates.length ? { skippedCandidates } : {}),
+                    requiredTagsResult: {
+                        required: requiredTags,
+                        satisfied: !requiredTags.length || nodeSatisfiesRequiredTags(requiredTags, buildMeshNodeCapabilityTags(node, resolved.providerType)),
+                        missing: requiredTags.filter(t => !buildMeshNodeCapabilityTags(node, resolved.providerType).includes(t)),
+                    },
+                    resolvedProviderType: resolved.providerType,
+                    ...(effectiveModel ? { resolvedModel: effectiveModel } : {}),
+                    ...(effectiveThinkingLevel ? { resolvedThinkingLevel: effectiveThinkingLevel } : {}),
+                    ...((task as any).difficulty ? { resolvedDifficulty: String((task as any).difficulty) } : {}),
+                    ...(resolved.reason ? { reason: resolved.reason } : {}),
+                };
+                tryAssignQueueTask(components, meshId, nodeId, sessionId, resolved.providerType, routingDecision);
                 return true;
             } catch (e: any) {
                 markAutoLaunch(meshId, task.id, { status: 'failed', error: e?.message || String(e), nodeId });

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

@@ -323,6 +323,10 @@ export class MeshRuntimeStore {
                 node_id TEXT,
                 session_id TEXT,
                 provider_type TEXT,
+                -- LEDGER-TASK-TRACEABILITY (B): the task a lifecycle entry pertains to,
+                -- promoted from payload.taskId so kind+task_id joins are index-backed
+                -- (legacy DBs get this column via migrateMeshIsolationColumns' ALTER).
+                task_id TEXT,
                 payload TEXT NOT NULL DEFAULT '{}'
             );
 
@@ -546,6 +550,23 @@ export class MeshRuntimeStore {
             //    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`);
+
+            // 7. LEDGER-TASK-TRACEABILITY (B): mesh_event_ledger.task_id. A pre-existing
+            //    DB has the ledger table (CREATE IF NOT EXISTS is a no-op) without this
+            //    column, so add it. Nullable — legacy rows read back with task_id NULL and
+            //    fall back to payload.taskId at the read layer (ledgerEntryTaskId), so no
+            //    backfill is needed. Idempotent: the column check short-circuits once present.
+            const ledgerCols = this.tableColumns('mesh_event_ledger');
+            if (!ledgerCols.has('task_id')) {
+                this.db.exec(`ALTER TABLE mesh_event_ledger ADD COLUMN task_id TEXT`);
+            }
+            // kind+task_id join index (task lifecycle timeline). Created unconditionally —
+            // IF NOT EXISTS is a no-op once present; the column is guaranteed above.
+            this.db.exec(`
+                CREATE INDEX IF NOT EXISTS idx_mesh_event_ledger_task
+                    ON mesh_event_ledger(mesh_id, task_id, timestamp)
+                    WHERE task_id IS NOT NULL
+            `);
         } 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;
@@ -1821,6 +1842,7 @@ export class MeshRuntimeStore {
         nodeId?: string | null;
         sessionId?: string | null;
         providerType?: string | null;
+        taskId?: string | null;
         payload?: unknown;
     }): void {
         // Ledger `kind` is a mandatory schema invariant (mesh_event_ledger.kind is
@@ -1837,8 +1859,8 @@ export class MeshRuntimeStore {
         }
         this.db.prepare(
             `INSERT OR IGNORE INTO mesh_event_ledger
-             (id, mesh_id, timestamp, kind, node_id, session_id, provider_type, payload)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+             (id, mesh_id, timestamp, kind, node_id, session_id, provider_type, task_id, payload)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
         ).run(
             entry.id,
             entry.meshId,
@@ -1847,6 +1869,7 @@ export class MeshRuntimeStore {
             entry.nodeId ?? null,
             entry.sessionId ?? null,
             entry.providerType ?? null,
+            entry.taskId ?? null,
             JSON.stringify(entry.payload ?? {}),
         );
         this.maybeCheckpointWal();
@@ -1857,7 +1880,7 @@ export class MeshRuntimeStore {
         since?: string;
         kind?: string;
         limit?: number;
-    }): Array<{ id: string; meshId: string; timestamp: string; kind: string; nodeId: string | null; sessionId: string | null; providerType: string | null; payload: unknown }> {
+    }): Array<{ id: string; meshId: string; timestamp: string; kind: string; nodeId: string | null; sessionId: string | null; providerType: string | null; taskId: string | null; payload: unknown }> {
         const limit = opts?.tail ?? opts?.limit ?? 200;
         let query: string;
         const params: unknown[] = [meshId];
@@ -1883,6 +1906,7 @@ export class MeshRuntimeStore {
             nodeId: r.node_id as string | null,
             sessionId: r.session_id as string | null,
             providerType: r.provider_type as string | null,
+            taskId: (r.task_id as string | null) ?? null,
             payload: (() => { try { return JSON.parse(r.payload as string); } catch { return {}; } })(),
         }));
     }
@@ -1897,7 +1921,7 @@ export class MeshRuntimeStore {
         since?: string;
         kinds?: string[];
         tail?: number;
-    }): Array<{ id: string; meshId: string; timestamp: string; kind: string; nodeId: string | null; sessionId: string | null; providerType: string | null; payload: unknown }> {
+    }): Array<{ id: string; meshId: string; timestamp: string; kind: string; nodeId: string | null; sessionId: string | null; providerType: string | null; taskId: string | null; payload: unknown }> {
         const params: unknown[] = [meshId];
         let whereClause = 'mesh_id = ?';
         if (opts?.since) {
@@ -1929,6 +1953,7 @@ export class MeshRuntimeStore {
             nodeId: r.node_id as string | null,
             sessionId: r.session_id as string | null,
             providerType: r.provider_type as string | null,
+            taskId: (r.task_id as string | null) ?? null,
             payload: (() => { try { return JSON.parse(r.payload as string); } catch { return {}; } })(),
         }));
     }
@@ -1967,13 +1992,13 @@ export class MeshRuntimeStore {
 
     importLedgerEntries(entries: Array<{
         id: string; meshId: string; timestamp: string; kind: string;
-        nodeId?: string | null; sessionId?: string | null; providerType?: string | null; payload?: unknown;
+        nodeId?: string | null; sessionId?: string | null; providerType?: string | null; taskId?: string | null; payload?: unknown;
     }>): number {
         let imported = 0;
         const stmt = this.db.prepare(
             `INSERT OR IGNORE INTO mesh_event_ledger
-             (id, mesh_id, timestamp, kind, node_id, session_id, provider_type, payload)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+             (id, mesh_id, timestamp, kind, node_id, session_id, provider_type, task_id, payload)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
         );
         this.db.transaction(() => {
             for (const e of entries) {
@@ -1984,7 +2009,7 @@ export class MeshRuntimeStore {
                 if (!e.kind || !String(e.kind).trim()) continue;
                 const result = stmt.run(
                     e.id, e.meshId, e.timestamp, e.kind,
-                    e.nodeId ?? null, e.sessionId ?? null, e.providerType ?? null,
+                    e.nodeId ?? null, e.sessionId ?? null, e.providerType ?? null, e.taskId ?? null,
                     JSON.stringify(e.payload ?? {}),
                 );
                 if (result.changes > 0) imported++;

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

@@ -1150,6 +1150,10 @@ export function recordDirectDispatchTask(
                 status: 'delivered',
             });
         } catch { /* best-effort — the assigned row is already recorded */ }
+        // NOTE (LEDGER-TASK-TRACEABILITY A): the direct-dispatch (mesh_send_task) path
+        // appends its own task_dispatched ledger entry at the MCP layer (mesh-tools-session.ts
+        // via buildDirectTaskPayload → routingDecision source:'direct') BEFORE calling this.
+        // Do NOT append task_dispatched here — it would double-record the same dispatch.
         return entry;
     });
 }

package/src/providers/cli-provider-instance.ts

@@ -785,16 +785,21 @@ export class CliProviderInstance implements ProviderInstance {
             }))
             : mergedMessages;
 
-        // Dashboard-tail repair (native-source providers, e.g. antigravity): the
-        // assistant answer lives only in native-history, so the PTY-parsed
-        // statusMessages end on the user prompt / auto-approve system lines and the
-        // snapshot's preview / lastMessageRole / completionMarker never see the
-        // answer — the session looks stuck on the user turn. We already cached the
-        // real final assistant summary at completion time (lastCompletionSummary),
-        // so append it as the trailing assistant bubble when the current tail has no
-        // assistant message at/after it. Purely additive to the status view; no
-        // per-tick native read, no effect on providers whose PTY carries the
-        // assistant (they surface it themselves and the guard below is a no-op).
+        // purpose: 'display-tail' (zero-read) — Dashboard-tail repair (native-source
+        // providers, e.g. antigravity): the assistant answer lives only in native-history,
+        // so the PTY-parsed statusMessages end on the user prompt / auto-approve system
+        // lines and the snapshot's preview / lastMessageRole / completionMarker never see
+        // the answer — the session looks stuck on the user turn. We already cached the
+        // real final assistant summary at completion time (lastCompletionSummary), so
+        // append it as the trailing assistant bubble when the current tail has no
+        // assistant message at/after it. Purely additive to the status view; no per-tick
+        // native read, no effect on providers whose PTY carries the assistant (they
+        // surface it themselves and the guard below is a no-op).
+        //
+        // authority-ok: this is a DISPLAY-ONLY tail repair, never a completion/stall/
+        // redrive verdict — it reads the pre-cached summary (zero native read) and only
+        // paints the status view. It keys off the adapter's runtime chatMessagesOwnedExternally
+        // capability (not a class predicate); a completion decision is never taken here.
         const adapterOwnsMessagesElsewhereForTail = (this.adapter as any)?.chatMessagesOwnedExternally === true;
         if (adapterOwnsMessagesElsewhereForTail && this.lastCompletionSummary) {
             const summary = this.lastCompletionSummary;
@@ -1580,6 +1585,11 @@ export class CliProviderInstance implements ProviderInstance {
     private readExternalCompletionMessages(): unknown[] | null {
         const adapterOwnsMessagesElsewhere = (this.adapter as any)?.chatMessagesOwnedExternally === true;
         if (!adapterOwnsMessagesElsewhere) return null;
+        // authority-ok: native READ resolution, not a completion/stall/redrive verdict.
+        // This gate only decides whether an on-disk native transcript EXISTS to read for
+        // this session; the completion decision is made by callers over the returned
+        // messages (completionFinalAssistantEvidence / completionFinalSummary), which
+        // route class through resolveTranscriptAuthorityProfile.
         if (!isNativeSourceCanonicalHistory(this.provider.nativeHistory)) return null;
 
         // Resolve a CONCRETE native-history handle for this session's OWN
@@ -2613,6 +2623,11 @@ export class CliProviderInstance implements ProviderInstance {
      * (≥180s of PTY stasis), never on the routine 5s tick.
      */
     private sampleNativeTranscriptProgress(): { msgCount: number; sourceMtimeMs: number } | null {
+        // authority-ok: native fingerprint SAMPLING, not a stall verdict. This only
+        // decides whether a native source exists to sample a progress fingerprint from;
+        // the caller (checkMeshWorkerStall) makes the stall/no-progress decision over the
+        // returned fingerprint. Non-native-source classes have nothing to sample here and
+        // fall back to the unchanged lastOutputAt-only judgment.
         if (!isNativeSourceCanonicalHistory(this.provider?.nativeHistory)) return null;
         // readExternalCompletionMessages resolves this session's OWN native-source
         // conversation (providerSessionId / persisted pin / floor claim) and, as a
@@ -3900,7 +3915,31 @@ export class CliProviderInstance implements ProviderInstance {
             fcEvidenceSource = evidence.source;
             fcFinalSummary = extractFinalSummaryFromMessages(evidence.messages as any);
         } catch { /* best-effort */ }
-        const missingEvidence = (resolveTranscriptAuthorityProfile(this.provider).timing === 'floor' || fcEvidenceSource === 'external-native') && !fcFinalSummary;
+        // SPEC-DRIVEN completion timing (mission f2f6da1b / AGY-BOOT-PHANTOM): the
+        // startup-grace synth must enumerate the SAME transcript-authority timing
+        // classes the genuine finalization gate does (getCompletedFinalizationBlock,
+        // the external-native branch ~line 2120), not just 'floor' + external-native.
+        // The 'hold' class (antigravity — holdCompletionForTranscript) was missing:
+        // at boot its native history is often not yet written, so fcEvidenceSource is
+        // 'unavailable' (neither 'floor' nor 'external-native'), which left
+        // missingEvidence=false and fired a WEAK phantom completion the moment the FSM
+        // collapsed to idle — a completion for a turn whose authoritative transcript
+        // had not landed.
+        const synthTiming = resolveTranscriptAuthorityProfile(this.provider).timing;
+        const missingEvidence = (synthTiming === 'floor' || synthTiming === 'hold' || fcEvidenceSource === 'external-native') && !fcFinalSummary;
+        // HOLD class (antigravity): idle holds for the native transcript to land. The
+        // finalization gate never emits a completion for a hold provider without the
+        // transcript (it returns holdForTranscript / null at ~line 2120), so the synth
+        // must not either — even WITH mesh context. Suppress the synth and leave the
+        // task UNMARKED so a later idle poll re-runs this path once the transcript's
+        // final assistant lands (then fcFinalSummary is present → missingEvidence=false
+        // → a genuine, summary-bearing emit). This is the HOLD-and-retry equivalent of
+        // the finalization gate's non-terminal missing_final_assistant hold; it is what
+        // stops the boot-time phantom weak completion for a mesh worker.
+        if (missingEvidence && synthTiming === 'hold') {
+            LOG.info('CLI', `[${this.type}] ${reason} held: hold-class transcript not yet landed (source=${fcEvidenceSource})`);
+            return false;
+        }
         // Mirror the short-generating idle path's suppression: a provider that
         // requires a final assistant (or external-native history) with NO confirmed
         // summary and NO mesh context emits nothing — the session is idle with no
@@ -5119,6 +5158,9 @@ export class CliProviderInstance implements ProviderInstance {
         const limit = options.full ? Number.MAX_SAFE_INTEGER : STATUS_HYDRATION_TAIL_LIMIT;
         const windowTag = options.full ? 'full' : `tail:${STATUS_HYDRATION_TAIL_LIMIT}`;
 
+        // authority-ok: history-hydration READ routing, not a completion verdict. Selects
+        // the on-disk native transcript vs the materialized-mirror read path; no
+        // completion/stall/redrive decision is taken here.
         if (isNativeSourceCanonicalHistory(canonicalHistory)) {
             const cacheKey = [this.type, this.providerSessionId, this.workingDir, windowTag].join('\0');
             const now = Date.now();
@@ -5188,6 +5230,8 @@ export class CliProviderInstance implements ProviderInstance {
         // transcript so seedSessionHistory can prime dedup state. Pass full so the
         // hydration read is unbounded here (and only here).
         this.syncCanonicalSavedHistoryIfNeeded({ full: true });
+        // authority-ok: history-restore READ routing, not a completion verdict — picks the
+        // native transcript read vs the legacy chat-history read for seeding dedup state.
         const restoredHistory = isNativeSourceCanonicalHistory(this.provider.nativeHistory)
             ? readProviderChatHistory(this.type, {
                 canonicalHistory: this.provider.nativeHistory,