@adhdev/daemon-core 0.9.82-rc.353 → 0.9.82-rc.355

package/src/mesh/mesh-event-trace.ts

@@ -0,0 +1,67 @@
+/**
+ * EVTTRACE — observation-only lifecycle tracing for mesh completion events.
+ *
+ * Pure logging. This module adds NO decision logic: every call site is a bare log
+ * statement inserted ALONGSIDE (never replacing) the existing control flow. Its only
+ * job is to make a single completion event greppable across its whole lifecycle by a
+ * stable correlation key, and to mark — with one uniform anchor — every point where
+ * such an event is rejected / held / skipped / deduped.
+ *
+ * grep anchors:
+ *   [EvtTrace] [stage:<name>]   — lifecycle progressed a step (INFO)
+ *   [EvtTrace] [drop:<reason>]  — event did NOT advance here, with the reason (WARN)
+ *
+ * Follow one completion: grep the daemon log for its `task=<id>` (or `sess=<id>`)
+ * across the [stage:*] lines; the line with [drop:*] is where it died.
+ *
+ * Dependency-light on purpose (only the logger) so both providers/ and mesh/ can
+ * import it without any cycle risk.
+ */
+import { LOG } from '../logging/logger.js';
+
+const CAT = 'EvtTrace';
+
+function s(v: unknown): string {
+    return typeof v === 'string' && v.trim() ? v.trim() : '';
+}
+
+export interface MeshEventTraceCtx {
+    /** Primary correlation anchor — the mesh task id (meshActiveTaskId / metadataEvent.taskId). */
+    taskId?: unknown;
+    /** Optional per-event id when the producer assigns one. */
+    eventId?: unknown;
+    /** Worker session id — the fallback anchor when no task is attached. */
+    sessionId?: unknown;
+    nodeId?: unknown;
+    meshId?: unknown;
+    event?: unknown;
+}
+
+/**
+ * Stable, greppable correlation key. `task=` and `sess=` are ALWAYS rendered (as `-`
+ * when absent) so the key shape is uniform across stages and a single grep alternation
+ * (`task=<id>\|sess=<id>`) follows the event end-to-end.
+ */
+export function meshEventTraceKey(ctx: MeshEventTraceCtx): string {
+    const segs = [`task=${s(ctx.taskId) || '-'}`];
+    const eventId = s(ctx.eventId);
+    if (eventId) segs.push(`evt=${eventId}`);
+    segs.push(`sess=${s(ctx.sessionId) || '-'}`);
+    const nodeId = s(ctx.nodeId);
+    if (nodeId) segs.push(`node=${nodeId}`);
+    const meshId = s(ctx.meshId);
+    if (meshId) segs.push(`mesh=${meshId}`);
+    const event = s(ctx.event);
+    if (event) segs.push(`event=${event}`);
+    return segs.join(' ');
+}
+
+/** Lifecycle progress (INFO). One line per stage the event clears. */
+export function traceMeshEventStage(stage: string, ctx: MeshEventTraceCtx, detail?: string): void {
+    LOG.info(CAT, `[stage:${stage}] ${meshEventTraceKey(ctx)}${detail ? ` — ${detail}` : ''}`);
+}
+
+/** Event did not advance — rejected / held / skipped / deduped (WARN). */
+export function traceMeshEventDrop(reason: string, ctx: MeshEventTraceCtx, detail?: string): void {
+    LOG.warn(CAT, `[drop:${reason}] ${meshEventTraceKey(ctx)}${detail ? ` — ${detail}` : ''}`);
+}

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

@@ -1,7 +1,7 @@
 import { existsSync } from 'fs';
 import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
 import { loadConfig } from '../config/config.js';
-import { getMesh, getMeshByRepo } from '../config/mesh-config.js';
+import { getMesh, getMeshByRepo, listMeshes } from '../config/mesh-config.js';
 import { detectCLI } from '../detection/cli-detector.js';
 import { LOG } from '../logging/logger.js';
 import { appendLedgerEntry, buildTaskCompletionEvidence, getSessionRecoveryContext, isIntentionalCleanupStopEntry, readLedgerEntries } from './mesh-ledger.js';
@@ -15,6 +15,7 @@ import { queuePendingMeshCoordinatorEvent, drainPendingMeshCoordinatorEvents } f
 import type { PendingMeshCoordinatorEvent } from './mesh-events-pending.js';
 import { resolveWorkerDelegateRouting, recordUnroutableDelegateEvent, isUnroutableDelegateRejection } from './mesh-routing.js';
 import { enqueueUnresolvedDelegateForward, peekUnresolvedDelegateForwards, ackUnresolvedDelegateForward } from './mesh-unresolved-forward-outbox.js';
+import { traceMeshEventStage, traceMeshEventDrop } from './mesh-event-trace.js';
 import { getLastDisplayMessage } from '../status/snapshot.js';
 import { resolveDelegatedWorkerAutoApprove, resolveProviderMaxParallel, resolveNodeSchedulingPriority, normalizeMeshSchedulingStrategy } from '../repo-mesh-types.js';
 import type { RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
@@ -70,6 +71,25 @@ function getCachedMeshByWorkspace(workspace: string): any {
     return mesh;
 }
 
+// Deterministic meshId recovery for a forwarded worker event that carries no meshId.
+// An unresolved-mesh worker (forwardUnresolvedDelegateEvent) cannot resolve its own
+// meshId locally, so it pushes the event with nodeId + workspace only and relies on
+// the coordinator — which hosts the mesh — to recover the id. Workspace recovery
+// (getCachedMeshByWorkspace → getMeshByRepo) is the fast path but can miss (a worktree
+// clone whose repoIdentity differs, or a transient cache state), which left the retry
+// permanently rejected with "meshId required". The node-id IS a stable, coordinator-side
+// fact: scan the hosted meshes for the one whose node matches the forwarded nodeId
+// (3-form normalizer). This is timing-independent and never depends on repo lookup.
+function recoverMeshIdByNodeId(nodeId: string): string {
+    if (!nodeId) return '';
+    for (const mesh of listMeshes()) {
+        if (Array.isArray(mesh.nodes) && mesh.nodes.some((n: any) => meshNodeIdMatches(n, nodeId))) {
+            return readNonEmptyString(mesh.id);
+        }
+    }
+    return '';
+}
+
 export function __resetIdleAutoFastForwardForTests(): void {
     idleAutoFastForwardLastAttempt.clear();
 }
@@ -1540,6 +1560,16 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
     const eventSessionId = resolveEventSessionId(args.metadataEvent, args.sourceInstanceId);
     const eventNodeId = readNonEmptyString(args.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId);
 
+    // EVTTRACE correlation context for this event's coordinator-side lifecycle (queue /
+    // dedup / suppress). Observation only — never read by any decision below.
+    const traceCtx = {
+        taskId: args.metadataEvent.taskId,
+        sessionId: eventSessionId,
+        nodeId: eventNodeId,
+        meshId: args.meshId,
+        event: args.event,
+    };
+
     const sourceSession = args.sourceInstanceId
         ? components.instanceManager.getInstance(args.sourceInstanceId)
         : undefined;
@@ -1626,6 +1656,7 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
             } catch { /* best-effort */ }
         }
         LOG.info('MeshEvents', `Suppressed ${args.event} for intentionally cleanup-stopped session ${eventSessionId || '(unknown session)'}`);
+        traceMeshEventDrop('intentional_cleanup_stop', traceCtx);
         return { success: true, forwarded: 0, suppressed: true, intentionalCleanupStop: true };
     }
 
@@ -1647,6 +1678,7 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
         }
         if (reconciledCompletion?.source === 'no_progress_terminal_ledger_suppression') {
             LOG.info('MeshEvents', `Suppressed no-progress monitor because terminal ledger evidence already exists for session ${eventSessionId || '(unknown session)'}`);
+            traceMeshEventDrop('no_progress_terminal_ledger_suppression', traceCtx, `terminalKind=${reconciledCompletion.terminalLedgerKind}`);
             return {
                 success: true,
                 forwarded: 0,
@@ -1659,6 +1691,7 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
 
     if (isDuplicateRefineTerminalEvent(args.meshId, args.event, args.metadataEvent)) {
         LOG.info('MeshEvents', `Suppressed duplicate ${args.event} for refine job ${readRefineJobId({ metadataEvent: args.metadataEvent })}`);
+        traceMeshEventDrop('duplicate_refine_terminal', traceCtx);
         return { success: true, forwarded: 0, suppressed: true, duplicateRefineTerminalEvent: true };
     }
 
@@ -1674,6 +1707,7 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
         });
         if (duplicateApproval) {
             LOG.info('MeshEvents', `Suppressed duplicate approval event for mesh ${args.meshId} session ${eventSessionId}`);
+            traceMeshEventDrop('duplicate_approval', traceCtx);
             return { success: true, forwarded: 0, suppressed: true, duplicateApproval: true };
         }
     }
@@ -1706,6 +1740,7 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
                     || args.metadataEvent.source === 'no_progress_reconciliation'
                 ) {
                     LOG.info('MeshEvents', `Suppressed duplicate completion with existing terminal ledger evidence for mesh ${args.meshId} session ${eventSessionId}`);
+                    traceMeshEventDrop('duplicate_completion_terminal_ledger', traceCtx);
                     return { success: true, forwarded: 0, suppressed: true, duplicateCompletion: true, terminalLedgerEvidence: true };
                 }
             }
@@ -1724,6 +1759,7 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
         });
         if (duplicateCompletion) {
             LOG.info('MeshEvents', `Suppressed duplicate completion for mesh ${args.meshId} session ${eventSessionId}`);
+            traceMeshEventDrop('duplicate_completion', traceCtx);
             return { success: true, forwarded: 0, suppressed: true, duplicateCompletion: true };
         }
     }
@@ -1742,6 +1778,7 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
         });
         if (duplicateStopped) {
             LOG.info('MeshEvents', `Suppressed duplicate stopped event for mesh ${args.meshId} session ${eventSessionId}`);
+            traceMeshEventDrop('duplicate_stopped', traceCtx);
             return { success: true, forwarded: 0, suppressed: true, duplicateStopped: true };
         }
     }
@@ -1762,7 +1799,9 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
         // genuine evidence, is marked terminal as before.
         const leaveDirectDispatchActive = !task && opts?.tentativeIfDirect === true;
         if (!leaveDirectDispatchActive) {
-            updateDirectDispatchStatus(args.meshId, sessionId, outcome);
+            // CANON-B: flip the exact dispatch row the completion echoed its taskId for; the
+            // session_id fallback (no echoed taskId) still covers legacy/relayed workers.
+            updateDirectDispatchStatus(args.meshId, sessionId, outcome, eventTaskId);
         }
         markSessionDeliveriesTerminal(args.meshId, sessionId, outcome);
         setImmediate(() => cleanupTerminalDirectDispatches());
@@ -1779,7 +1818,10 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
         const providerType = readNonEmptyString(args.metadataEvent.providerType);
 
         if (sessionId) {
-            directDispatchTaskIdForLedger = resolveActiveDirectDispatchTaskId(args.meshId, sessionId);
+            // CANON-B: trust the taskId the completion echoed; only fall back to the
+            // most-recent-by-session heuristic when the worker carried none.
+            directDispatchTaskIdForLedger = readNonEmptyString(args.metadataEvent.taskId)
+                || resolveActiveDirectDispatchTaskId(args.meshId, sessionId);
             // A false-idle completion of a direct dispatch is recorded but kept tentative (the
             // dispatch row stays active for the reconcile fallback); a genuine completion is terminal.
             const isFalseIdle = isFalseIdleCompletion(args.metadataEvent);
@@ -1867,12 +1909,21 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
             } catch { /* best-effort */ }
         }
         if (sessionId) {
-            updateDirectDispatchStatus(args.meshId, sessionId, 'acked');
-            const activeDeliveries = ((): { id: string }[] => {
+            // CANON-B: a generating_started that echoes its taskId acks exactly the dispatch
+            // and the delivery for THAT task — not every in-flight dispatch/delivery on the
+            // session. A session that already holds a freshly-dispatched (still 'dispatched')
+            // sibling must keep that row 'dispatched' so its own confirm can match it; acking
+            // by session would mark it 'acked' prematurely and hide a genuine non-delivery.
+            const startedTaskId = readNonEmptyString(args.metadataEvent.taskId) || undefined;
+            updateDirectDispatchStatus(args.meshId, sessionId, 'acked', startedTaskId);
+            const activeDeliveries = ((): { id: string; taskId: string | null }[] => {
                 try { return MeshRuntimeStore.getInstance().getActiveSessionDeliveries(args.meshId, sessionId); }
                 catch { return []; }
             })();
-            for (const d of activeDeliveries) {
+            const deliveriesToAck = startedTaskId
+                ? activeDeliveries.filter(d => d.taskId === startedTaskId)
+                : activeDeliveries;
+            for (const d of deliveriesToAck) {
                 updateSessionDeliveryStatus(d.id, 'acked');
             }
         }
@@ -1885,7 +1936,9 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
             } catch { /* best-effort */ }
         }
         if (sessionId) {
-            directDispatchTaskIdForLedger = resolveActiveDirectDispatchTaskId(args.meshId, sessionId);
+            // CANON-B: prefer the echoed taskId; session heuristic is the fallback.
+            directDispatchTaskIdForLedger = readNonEmptyString(args.metadataEvent.taskId)
+                || resolveActiveDirectDispatchTaskId(args.meshId, sessionId);
             completedTaskForLedger = markSessionTerminal(sessionId, 'failed');
         }
     }
@@ -2081,6 +2134,11 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
     };
     if (queuePendingMeshCoordinatorEvent(pendingEvent)) {
         LOG.info('MeshEvents', `Queued ${args.event} for coordinator (mesh ${args.meshId}${workerCoordinatorDaemonId ? `, coordinator daemon ${workerCoordinatorDaemonId}` : ''}${workerCoordinatorSessionId ? `, coordinator session ${workerCoordinatorSessionId}` : ''})`);
+        // EVTTRACE: event persisted to the coordinator pending queue (awaiting reconcile drain).
+        traceMeshEventStage('queued', traceCtx, workerCoordinatorDaemonId ? `coordinatorDaemon=${workerCoordinatorDaemonId}` : 'broadcast');
+    } else {
+        // EVTTRACE: queue rejected the event (dedup at queue time / persistence guard).
+        traceMeshEventDrop('queue_dedup', traceCtx);
     }
     return { success: true, forwarded: 0 };
 }
@@ -2094,12 +2152,37 @@ export function handleMeshForwardEvent(components: DaemonComponents, payload: Re
     const workspace = readNonEmptyString(payload.workspace);
 
     // The fallback worker-forward path (forwardUnresolvedDelegateEvent) cannot resolve a
-    // mesh id locally on the remote worker, so it forwards the event with workspace only.
-    // The coordinator hosting the mesh CAN resolve it: recover the mesh id by workspace
-    // when the payload doesn't carry one.
+    // mesh id locally on the remote worker, so it forwards the event with nodeId +
+    // workspace only. The coordinator hosting the mesh CAN resolve it. Two recovery
+    // paths, in order:
+    //   1) workspace → mesh (fast path; cached repoIdentity lookup), then
+    //   2) nodeId → mesh (deterministic backstop; scans hosted meshes for the node).
+    // Workspace recovery alone was unreliable — a worktree clone whose repoIdentity
+    // differs, or a transient cache miss, left the reconcile retry permanently rejected
+    // ("meshId required") so the worker's completion never surfaced to the coordinator.
+    // The nodeId is a stable coordinator-side fact and resolves timing-independently.
     const meshId = readNonEmptyString(payload.meshId)
-        || (workspace ? readNonEmptyString(getCachedMeshByWorkspace(workspace)?.id) : '');
-    if (!meshId) return { success: false, error: 'meshId required' };
+        || (workspace ? readNonEmptyString(getCachedMeshByWorkspace(workspace)?.id) : '')
+        || recoverMeshIdByNodeId(nodeId);
+    if (!meshId) {
+        // EVTTRACE: forwarded event rejected at receive — no meshId could be resolved
+        // (no payload.meshId, no workspace→mesh, no nodeId→mesh). Observation only.
+        traceMeshEventDrop('meshId_required', {
+            taskId: payload.taskId,
+            sessionId: readNonEmptyString(payload.targetSessionId) || readNonEmptyString(payload.sessionId),
+            nodeId,
+            event: eventName,
+        }, workspace ? `workspace=${workspace} unresolved` : 'no workspace/nodeId');
+        return { success: false, error: 'meshId required' };
+    }
+    // EVTTRACE: forwarded event accepted at receive (meshId resolved).
+    traceMeshEventStage('received', {
+        taskId: payload.taskId,
+        sessionId: readNonEmptyString(payload.targetSessionId) || readNonEmptyString(payload.sessionId),
+        nodeId,
+        meshId,
+        event: eventName,
+    });
     const nodeLabel = nodeId ? `Node '${nodeId}'` : workspace ? `Agent at ${workspace}` : 'Remote agent';
     const relayModalMessage = readNonEmptyString(payload.modalMessage);
     const relayModalButtons = Array.isArray(payload.modalButtons)
@@ -2235,13 +2318,24 @@ function forwardUnresolvedDelegateEvent(
     //    push below (degrades to the old at-most-once behaviour rather than dropping
     //    the chance entirely).
     const persisted = enqueueUnresolvedDelegateForward(coordinatorDaemonId, eventName, payload);
+    // EVTTRACE: unresolved-mesh worker persisted its completion to the outbox (no meshId
+    // available locally; coordinator will recover it on receive).
+    const fwdTraceCtx = {
+        taskId: (payload as Record<string, unknown>).taskId,
+        sessionId: readNonEmptyString(payload.targetSessionId) || readNonEmptyString(payload.sessionId),
+        nodeId: readNonEmptyString(routing.nodeId) || readNonEmptyString(event.meshNodeId),
+        event: eventName,
+    };
+    traceMeshEventStage('outbox_enqueue', fwdTraceCtx, `coordinatorDaemon=${coordinatorDaemonId} meshId=absent`);
 
     // 2) Best-effort immediate push for low latency. On success, ack the outbox row so
     //    the retry loop won't re-send it. On failure, leave it queued — PHASE 0 retries.
+    traceMeshEventStage('forward_send', fwdTraceCtx, 'immediate push');
     Promise.resolve(components.dispatchMeshCommand(coordinatorDaemonId, 'mesh_forward_event', payload))
         .then((result: any) => {
             if (result && result.success === false) {
                 LOG.warn('MeshEvents', `Immediate forward of ${eventName} to coordinator ${coordinatorDaemonId} rejected (${readNonEmptyString(result.error) || 'no reason'}) — left queued for retry`);
+                traceMeshEventDrop('immediate_forward_rejected', fwdTraceCtx, readNonEmptyString(result.error) || 'no reason');
                 return;
             }
             // Acked. Mark the durable copy delivered so the retry loop skips it.
@@ -2368,6 +2462,17 @@ export function setupMeshEventForwarding(components: DaemonComponents) {
             // silently. Leave a fail-loud diagnostic so the missing completion is traceable.
             // Benign non-delegate rejections (not_cli / no_workspace / etc.) are no-ops inside
             // recordUnroutableDelegateEvent.
+            // EVTTRACE: a delegate event that could not be routed AND could not be
+            // fallback-forwarded (no coordinator anchor). Only mesh_unresolved is a real
+            // drop; the benign non-delegate rejections are ordinary non-mesh traffic.
+            if (isUnroutableDelegateRejection(routing)) {
+                traceMeshEventDrop('unroutable', {
+                    taskId: (event as Record<string, unknown>).meshActiveTaskId ?? (event as Record<string, unknown>).taskId,
+                    sessionId: routing.sessionId,
+                    nodeId: routing.nodeId,
+                    event: event.event,
+                }, 'no coordinator anchor / mesh_unresolved');
+            }
             recordUnroutableDelegateEvent(routing, event.event);
             return;
         }

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

@@ -88,6 +88,25 @@ function hasPendingRefineTerminalEventDuplicate(event: PendingMeshCoordinatorEve
     );
 }
 
+// CANON-B / DUPNOTIF: terminal completion events that the coordinator surfaces as a
+// notification. The native completion path (handleMeshCoordinatorEvent) and the transcript
+// reconciliation fallback (reconcileDirectDispatchCompletionFromTranscript) BOTH queue one of
+// these for the same finished task — with DIFFERENT timestamps — so a timestamp-bearing
+// fingerprint lets both surface and the coordinator notifies twice. When the event carries a
+// taskId we anchor the fingerprint on the taskId (dropping the timestamp), collapsing the two
+// paths into a single surface. A weakness marker keeps a tentative false-idle completion
+// distinct from the genuine completion that supersedes it, so the genuine one is never
+// swallowed by the earlier weak one.
+const TERMINAL_COMPLETION_EVENTS = new Set(['agent:generating_completed', 'agent:stopped']);
+
+function isWeakCompletionMetadata(metadata: Record<string, unknown>): boolean {
+    const evidenceLevel = readNonEmptyString(metadata.evidenceLevel);
+    if (evidenceLevel === 'insufficient' || evidenceLevel === 'weak') return true;
+    if (metadata.reviewRecommended === true) return true;
+    const diag = readRecord(metadata.completionDiagnostic);
+    return diag?.finalAssistantPresent === false || diag?.blockReason === 'missing_final_assistant';
+}
+
 export function buildPendingEventFingerprint(event: PendingMeshCoordinatorEvent): string {
     const metadata = readRecord(event.metadataEvent) || {};
     // Bootstrap events are node-scoped: dedup by meshId+event+nodeId only.
@@ -96,6 +115,20 @@ export function buildPendingEventFingerprint(event: PendingMeshCoordinatorEvent)
     if (event.event === 'worktree_bootstrap_complete' || event.event === 'worktree_bootstrap_failed') {
         return [event.meshId, event.event, event.nodeId || ''].join('::');
     }
+    // DUPNOTIF: a terminal completion carrying a taskId is deduped by taskId (+ weakness),
+    // NOT by timestamp — the native and transcript-reconciliation paths timestamp the same
+    // completion differently, and only taskId is stable across both.
+    if (TERMINAL_COMPLETION_EVENTS.has(event.event)) {
+        const terminalTaskId = readNonEmptyString(metadata.taskId) || readNonEmptyString(readRecord(metadata.payload)?.taskId);
+        if (terminalTaskId) {
+            return [
+                event.meshId,
+                event.event,
+                terminalTaskId,
+                isWeakCompletionMetadata(metadata) ? 'weak' : 'genuine',
+            ].join('::');
+        }
+    }
     const sessionId = resolveEventSessionId(metadata);
     const providerSessionId = readNonEmptyString(metadata.providerSessionId);
     const taskId = readNonEmptyString(metadata.taskId) || readNonEmptyString(readRecord(metadata.payload)?.taskId);

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

@@ -223,7 +223,9 @@ export function reconcileDirectDispatchCompletionFromTranscript(args: {
             evidence,
         },
     });
-    updateDirectDispatchStatus(args.meshId, args.sessionId, kind === 'task_completed' ? 'completed' : 'failed');
+    // CANON-B: this reconcile path always knows the exact taskId — flip that dispatch row, not
+    // whichever sibling the session_id happens to match.
+    updateDirectDispatchStatus(args.meshId, args.sessionId, kind === 'task_completed' ? 'completed' : 'failed', args.taskId);
     markSessionDeliveriesTerminal(args.meshId, args.sessionId, kind === 'task_completed' ? 'completed' : 'failed');
     setImmediate(() => cleanupTerminalDirectDispatches());
     queuePendingMeshCoordinatorEvent({

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

@@ -56,6 +56,7 @@ import {
     expireStaleUnresolvedDelegateForwards,
 } from './mesh-unresolved-forward-outbox.js';
 import { readNonEmptyString, readMeshCompletionSummary } from './mesh-events-utils.js';
+import { traceMeshEventStage, traceMeshEventDrop } from './mesh-event-trace.js';
 import { expandDaemonIdForms } from '@adhdev/mesh-shared';
 import { getActiveDirectDispatches, getQueue, reclaimStrandedAssignedTask } from './mesh-work-queue.js';
 import { readLedgerEntries } from './mesh-ledger.js';
@@ -230,6 +231,15 @@ function injectPendingIntoCoordinator(
 ): void {
     if (!coordinator || !pending.coordinatorMessage) return;
     const force = shouldForceInjectMeshEvent(pending.event);
+    // EVTTRACE: event surfaced to the coordinator (injected into its live CLI session).
+    // This is the terminal happy-path stage. Observation only.
+    traceMeshEventStage('surfaced', {
+        taskId: pending.metadataEvent?.taskId,
+        sessionId: pending.metadataEvent?.targetSessionId ?? pending.targetCoordinatorSessionId,
+        nodeId: pending.nodeId,
+        meshId: pending.meshId,
+        event: pending.event,
+    }, force ? 'force-inject' : 'inject');
     coordinator.onEvent('send_message', {
         input: { text: pending.coordinatorMessage, textFallback: pending.coordinatorMessage },
         ...(force ? { force: true } : {}),
@@ -357,6 +367,16 @@ function recoverStrandedAssignedDispatches(meshId: string, store: MeshRuntimeSto
             LOG.warn('MeshReconcile', `Reclaimed stranded assigned task ${row.id} on mesh ${meshId} `
                 + `(node=${row.assignedNodeId ?? '?'} session=${row.assignedSessionId ?? '?'}, dispatched `
                 + `${Math.round((nowMs - dispatchedAtMs) / 1000)}s ago, never confirmed delivered → ${reclaimed.status})`);
+            // EVTTRACE: the dispatch for this task was stranded (assigned, never confirmed
+            // delivered) and reclaimed (CANON-B) — its expected completion event never
+            // arrived. Observation only; the reclaim decision above is unchanged.
+            traceMeshEventDrop('assigned_stranded_reclaim', {
+                taskId: row.id,
+                sessionId: row.assignedSessionId,
+                nodeId: row.assignedNodeId,
+                meshId,
+                event: 'agent:generating_completed',
+            }, `unconfirmed ${Math.round((nowMs - dispatchedAtMs) / 1000)}s → ${reclaimed.status}`);
         }
     }
 }
@@ -652,6 +672,15 @@ function holdOrExpireStrictUnmatchedEvent(
         try {
             queuePendingMeshCoordinatorEvent(pending); // preserves queuedAt → true age retained
             LOG.info('MeshReconcile', `Strict route hold: coordinator session ${wantSession} not live on mesh ${meshId} — re-queued (${pending.event})`);
+            // EVTTRACE: event held (re-queued) — its originating coordinator session is not
+            // currently deliverable. Held, not dropped; surfaces later or expires past TTL.
+            traceMeshEventDrop('strict_route_hold', {
+                taskId: pending.metadataEvent?.taskId,
+                sessionId: pending.metadataEvent?.targetSessionId ?? wantSession,
+                nodeId: pending.nodeId,
+                meshId,
+                event: pending.event,
+            }, `coordinatorSession=${wantSession} not live`);
         } catch (e: any) {
             LOG.warn('MeshReconcile', `Strict route re-queue failed for ${pending.event} on mesh ${meshId}: ${e?.message || e}`);
         }
@@ -675,6 +704,14 @@ function holdOrExpireStrictUnmatchedEvent(
             },
         });
         LOG.warn('MeshReconcile', `Strict route expire: coordinator session ${wantSession} never returned for mesh ${meshId} — recorded to ledger (recoverable), dropped (${pending.event})`);
+        // EVTTRACE: event expired past the strict-route TTL — dropped (recoverable, ledgered).
+        traceMeshEventDrop('strict_route_expired', {
+            taskId: pending.metadataEvent?.taskId,
+            sessionId: pending.metadataEvent?.targetSessionId ?? wantSession,
+            nodeId: pending.nodeId,
+            meshId,
+            event: pending.event,
+        }, `coordinatorSession=${wantSession} never returned`);
     } catch (e: any) {
         LOG.warn('MeshReconcile', `Failed to ledger-expire strict-unmatched ${pending.event} for mesh ${meshId}: ${e?.message || e}`);
     }
@@ -698,16 +735,26 @@ async function retryUnresolvedDelegateForwards(components: DaemonComponents): Pr
     if (entries.length === 0) return;
 
     for (const entry of entries) {
+        // EVTTRACE correlation context for this outbox entry's retry.
+        const entryTraceCtx = {
+            taskId: (entry.payload as Record<string, unknown>).taskId,
+            sessionId: readNonEmptyString(entry.payload.targetSessionId) || readNonEmptyString(entry.payload.sessionId),
+            nodeId: readNonEmptyString(entry.payload.nodeId),
+            event: readNonEmptyString(entry.payload.event),
+        };
         let result: any;
         try {
+            traceMeshEventStage('forward_send', entryTraceCtx, `retry → ${entry.coordinatorDaemonId}`);
             result = await dispatchMeshCommand(entry.coordinatorDaemonId, 'mesh_forward_event', entry.payload);
         } catch (e: any) {
             // Coordinator unreachable — keep the entry queued and try again next tick.
             LOG.warn('MeshReconcile', `Retry forward to coordinator ${entry.coordinatorDaemonId} failed: ${e?.message || e} — left queued`);
+            traceMeshEventDrop('retry_forward_failed', entryTraceCtx, e?.message || String(e));
             continue;
         }
         if (result && result.success === false) {
             LOG.warn('MeshReconcile', `Retry forward to coordinator ${entry.coordinatorDaemonId} rejected (${readNonEmptyString(result.error) || 'no reason'}) — left queued`);
+            traceMeshEventDrop('retry_forward_rejected', entryTraceCtx, readNonEmptyString(result.error) || 'no reason');
             continue;
         }
         // Acked — mark the durable copy delivered.

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

@@ -887,9 +887,25 @@ export class MeshRuntimeStore {
         }));
     }
 
-    updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void {
-        if (!sessionId) return; // never update rows without a session binding
+    // CANON-B (dispatch identity): mesh_direct_dispatches is keyed by task_id (PK), but a
+    // single session can host several sequential direct dispatches (re-dispatch / nudge), so
+    // matching a status flip by session_id alone hits EVERY non-terminal row for that session
+    // — flipping a sibling task's row and stranding the one whose event actually fired (the
+    // assigned-stranded watchdog then requeues a task that is really still generating). When
+    // the firing event carries a taskId, target the single PK row; the session_id match is the
+    // legacy fallback only for events that arrive without a taskId.
+    updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale', taskId?: string): void {
         const now = new Date().toISOString();
+        if (taskId) {
+            this.db.prepare(`
+                UPDATE mesh_direct_dispatches
+                SET status = @status, updated_at = @updatedAt
+                WHERE mesh_id = @meshId AND task_id = @taskId
+                  AND status NOT IN ('completed', 'failed')
+            `).run({ status, meshId, taskId, updatedAt: now });
+            return;
+        }
+        if (!sessionId) return; // never update rows without a session binding
         this.db.prepare(`
             UPDATE mesh_direct_dispatches
             SET status = @status, updated_at = @updatedAt

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

@@ -1140,9 +1140,16 @@ export function updateDirectDispatchStatus(
     meshId: string,
     sessionId: string,
     status: 'acked' | 'completed' | 'failed' | 'stale',
+    taskId?: string,
 ): void {
     try {
-        MeshRuntimeStore.getInstance().updateDirectDispatchStatus(meshId, sessionId, status);
+        // CANON-B: prefer the exact task_id row; fall back to the session_id match only when
+        // the firing event carried no taskId (a legacy/relayed event). Warn on the fallback so
+        // the residual PK-substitute path is observable when it strands a sibling dispatch.
+        if (!taskId) {
+            LOG.warn('MeshQueue', `updateDirectDispatchStatus(${status}) for mesh ${meshId} session ${sessionId} has no taskId — falling back to session_id match (may flip a sibling dispatch row)`);
+        }
+        MeshRuntimeStore.getInstance().updateDirectDispatchStatus(meshId, sessionId, status, taskId);
     } catch { /* best-effort */ }
 }
 

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

@@ -51,6 +51,7 @@ import { normalizeContent, flattenContent, normalizeInputEnvelope } from './cont
 import { assertProviderSupportsDeclaredInput, getEffectiveMessageInputSupport } from './provider-input-support.js';
 import type { ProviderInstance, ProviderState, AcpProviderState, ProviderErrorReason, ProviderEvent, InstanceContext, SessionModalState } from './provider-instance.js';
 import { StatusMonitor } from './status-monitor.js';
+import { ManualAttendanceTracker } from './manual-attendance.js';
 import { buildLegacyModelModeSummaryMetadata } from './summary-metadata.js';
 import { workingDirBasename } from './working-dir.js';
 import {
@@ -845,7 +846,12 @@ export class AcpProviderInstance implements ProviderInstance {
                 }
 
                 // ─── Auto-approve: skip user confirmation ───
-                if (this.settings.autoApprove !== false) {
+                // Held while a human is actively attending this session (manual
+                // attendance) so they can decide the permission themselves; falls
+                // through to the waiting_approval manual path below. A background
+                // worker is never attended, so its delegated auto-approve fires
+                // as before.
+                if (this.settings.autoApprove !== false && !this.manualAttendance.isAttended()) {
                     const toolTitle = tc.title || tc.toolCallId || 'tool call';
                     this.log.info(`[${this.type}] Auto-approving: ${toolTitle}`);
                     this.appendSystemMessage(`Auto-approved: ${toolTitle}`);
@@ -1128,6 +1134,17 @@ export class AcpProviderInstance implements ProviderInstance {
 
     private permissionResolvers: ((approved: boolean) => void)[] = [];
 
+    // Provider-common manual-attendance signal: while a human is actively driving
+    // this session from the dashboard, auto-approve holds so they can decide on
+    // the permission request themselves. Background workers are never attended →
+    // delegated auto-approve is unaffected.
+    private readonly manualAttendance = new ManualAttendanceTracker();
+
+    /** @see ProviderInstance.noteManualInteraction */
+    noteManualInteraction(now = Date.now()): void {
+        this.manualAttendance.note(now);
+    }
+
     async resolvePermission(approved: boolean): Promise<void> {
         const resolver = this.permissionResolvers.shift();
         if (resolver) {