@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

package/src/mesh/mesh-refine-status.ts

@@ -0,0 +1,231 @@
+import type { MeshLedgerEntry } from './mesh-ledger.js';
+import type { PendingMeshCoordinatorEvent } from './mesh-events.js';
+import type { MeshAsyncJobLifecycle } from '../repo-mesh-types.js';
+
+export type MeshAsyncRefineJobStatus = 'accepted' | 'running' | 'completed' | 'failed';
+
+export interface MeshAsyncRefineJobSummary extends MeshAsyncJobLifecycle {
+    jobId: string;
+    interactionId?: string;
+    status: MeshAsyncRefineJobStatus;
+    meshId?: string;
+    nodeId?: string;
+    targetNodeId?: string;
+    targetDaemonId?: string;
+    workspace?: string;
+    branch?: string;
+    into?: string;
+    retryOfJobId?: string;
+    lastEvent?: string;
+    lastLedgerKind?: string;
+    lastUpdatedAt?: string;
+    instruction: string;
+}
+
+function readString(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value as Record<string, unknown>
+        : undefined;
+}
+
+function eventStatus(event: string | undefined, fallback?: string): MeshAsyncRefineJobStatus | undefined {
+    if (event === 'refine:accepted') return 'accepted';
+    if (event === 'refine:completed') return 'completed';
+    if (event === 'refine:failed') return 'failed';
+    if (fallback === 'completed' || fallback === 'failed' || fallback === 'accepted') return fallback;
+    return undefined;
+}
+
+function ledgerStatus(kind: string, fallback?: string): MeshAsyncRefineJobStatus {
+    if (kind === 'task_completed') return 'completed';
+    if (kind === 'task_failed') return 'failed';
+    if (fallback === 'accepted') return 'accepted';
+    return 'running';
+}
+
+function instructionForStatus(status: MeshAsyncRefineJobStatus): string {
+    if (status === 'accepted') return 'Refine job is accepted; wait for asyncRefineJobs or pendingCoordinatorEvents to report running/completed/failed.';
+    if (status === 'running') return 'Refine job is running; do not poll the ledger repeatedly. Watch asyncRefineJobs or pendingCoordinatorEvents for the terminal result.';
+    if (status === 'completed') return 'Refine job completed; inspect branch convergence and cleanup evidence before reporting final merge state.';
+    return 'Refine job failed; inspect result/finalBranchConvergenceState in mesh_task_history, fix the blocker, then rerun mesh_refine_node when ready.';
+}
+
+function mergeJob(
+    jobs: Map<string, MeshAsyncRefineJobSummary>,
+    patch: Partial<MeshAsyncRefineJobSummary> & { jobId?: string },
+): void {
+    const jobId = readString(patch.jobId);
+    if (!jobId) return;
+    const previous = jobs.get(jobId);
+    const status = patch.status || previous?.status || 'running';
+    const definedPatch = Object.fromEntries(
+        Object.entries(patch).filter(([, value]) => value !== undefined),
+    ) as Partial<MeshAsyncRefineJobSummary>;
+    jobs.set(jobId, {
+        ...previous,
+        ...definedPatch,
+        jobId,
+        status,
+        instruction: instructionForStatus(status),
+    });
+}
+
+export function buildMeshAsyncRefineJobs(args: {
+    meshId?: string;
+    ledgerEntries?: MeshLedgerEntry[];
+    pendingEvents?: PendingMeshCoordinatorEvent[];
+}): MeshAsyncRefineJobSummary[] {
+    const jobs = new Map<string, MeshAsyncRefineJobSummary>();
+
+    for (const entry of args.ledgerEntries || []) {
+        const payload = readRecord(entry.payload);
+        if (payload?.source !== 'refine_mesh_node_async_job') continue;
+        const refineJob = readRecord(payload.refineJob);
+        const result = readRecord(payload.result);
+        const finalState = readRecord(payload.finalBranchConvergenceState) || readRecord(result?.finalBranchConvergenceState);
+        const jobId = readString(refineJob?.jobId);
+        if (!jobId) continue;
+        const status = ledgerStatus(entry.kind, readString(refineJob?.status));
+        mergeJob(jobs, {
+            jobId,
+            interactionId: readString(refineJob?.interactionId),
+            status,
+            meshId: readString(refineJob?.meshId) || args.meshId,
+            nodeId: readString(refineJob?.nodeId) || entry.nodeId,
+            targetNodeId: readString(refineJob?.nodeId) || entry.nodeId,
+            targetDaemonId: readString(refineJob?.targetDaemonId),
+            workspace: readString(refineJob?.workspace),
+            branch: readString(result?.branch) || readString(finalState?.branch),
+            into: readString(result?.into) || readString(finalState?.baseBranch),
+            startedAt: readString(refineJob?.startedAt),
+            completedAt: readString(refineJob?.completedAt),
+            retryOfJobId: readString(refineJob?.retryOfJobId) || readString(payload.retryOfJobId),
+            lastLedgerKind: entry.kind,
+            lastUpdatedAt: entry.timestamp,
+        });
+    }
+
+    for (const event of args.pendingEvents || []) {
+        const metadata = readRecord(event.metadataEvent);
+        if (metadata?.source !== 'refine_mesh_node_async_job') continue;
+        const result = readRecord(metadata.result);
+        const finalState = readRecord(result?.finalBranchConvergenceState);
+        const jobId = readString(metadata.jobId);
+        if (!jobId) continue;
+        const status = eventStatus(event.event, readString(metadata.status));
+        mergeJob(jobs, {
+            jobId,
+            interactionId: readString(metadata.interactionId),
+            ...(status ? { status } : {}),
+            meshId: readString(metadata.meshId) || event.meshId || args.meshId,
+            nodeId: readString(metadata.nodeId) || event.nodeId,
+            targetNodeId: readString(metadata.nodeId) || event.nodeId,
+            targetDaemonId: readString(metadata.targetDaemonId),
+            workspace: readString(metadata.workspace) || event.workspace,
+            branch: readString(result?.branch) || readString(finalState?.branch),
+            into: readString(result?.into) || readString(finalState?.baseBranch),
+            startedAt: readString(metadata.startedAt),
+            completedAt: readString(metadata.completedAt),
+            retryOfJobId: readString(metadata.retryOfJobId),
+            lastEvent: event.event,
+            lastUpdatedAt: new Date(event.queuedAt).toISOString(),
+        });
+    }
+
+    return Array.from(jobs.values()).sort((a, b) => {
+        const aTime = new Date(a.lastUpdatedAt || a.startedAt || '').getTime();
+        const bTime = new Date(b.lastUpdatedAt || b.startedAt || '').getTime();
+        return (Number.isFinite(bTime) ? bTime : 0) - (Number.isFinite(aTime) ? aTime : 0);
+    });
+}
+
+const TERMINAL_REFINE_STATUSES = new Set<MeshAsyncRefineJobStatus>(['completed', 'failed']);
+
+/** Terminal refine jobs older than this (relative to the newest job in the set) are
+ * "stale" — already-resolved historical refinery rejections/successes that should not
+ * keep inflating the status counts in mesh_status. 6h covers a long working session
+ * while still folding multi-day-old residue. */
+export const STALE_TERMINAL_REFINE_WINDOW_MS = 6 * 60 * 60 * 1000;
+
+/** Cap on how many recent terminal jobs are counted even if all fall inside the freshness
+ * window — prevents a burst of refines from dominating the summary. */
+export const RECENT_TERMINAL_REFINE_CAP = 8;
+
+export interface MeshAsyncRefineJobsSummary {
+    /** Count of jobs reflected in `byStatus` (active jobs + recent terminal jobs). */
+    total: number;
+    byStatus: Record<string, number>;
+    /** Terminal jobs dropped from the counts because they are stale residue. */
+    staleTerminal: number;
+    /** Non-terminal (accepted/running) jobs still in flight. */
+    activeJobs: MeshAsyncRefineJobSummary[];
+}
+
+function jobActivityTime(job: MeshAsyncRefineJobSummary): number {
+    const raw = job.lastUpdatedAt || job.completedAt || job.startedAt || '';
+    const t = new Date(raw).getTime();
+    return Number.isFinite(t) ? t : 0;
+}
+
+/**
+ * Build a compact summary of refine jobs that folds stale terminal jobs.
+ *
+ * The full job list (from `buildMeshAsyncRefineJobs`) is derived from a recent ledger
+ * window and deduped by jobId, but it still includes every terminal (completed/failed)
+ * job that happens to fall in that window — including multi-day-old refinery rejections
+ * that have long since been resolved. Those stale terminals inflate `byStatus.failed`
+ * and read as "current breakage" when they are historical noise.
+ *
+ * Active (accepted/running) jobs are always counted. Terminal jobs are counted only when
+ * they are recent: within `STALE_TERMINAL_REFINE_WINDOW_MS` of the newest job's activity
+ * time AND among the `RECENT_TERMINAL_REFINE_CAP` most-recent terminals. Everything else
+ * is folded into `staleTerminal` and excluded from `byStatus`.
+ *
+ * Freshness is measured relative to the newest job in the set (not wall-clock), so the
+ * result is deterministic for a given input — important for tests and for stale-clock
+ * environments.
+ */
+export function summarizeMeshAsyncRefineJobs(
+    jobs: MeshAsyncRefineJobSummary[],
+): MeshAsyncRefineJobsSummary {
+    const activeJobs: MeshAsyncRefineJobSummary[] = [];
+    const terminalJobs: MeshAsyncRefineJobSummary[] = [];
+    for (const job of jobs) {
+        if (TERMINAL_REFINE_STATUSES.has(job.status)) terminalJobs.push(job);
+        else activeJobs.push(job);
+    }
+
+    // Newest activity across ALL jobs anchors the freshness window.
+    let newest = 0;
+    for (const job of jobs) newest = Math.max(newest, jobActivityTime(job));
+    const cutoff = newest - STALE_TERMINAL_REFINE_WINDOW_MS;
+
+    const terminalByRecency = [...terminalJobs].sort(
+        (a, b) => jobActivityTime(b) - jobActivityTime(a),
+    );
+    const freshTerminal = terminalByRecency
+        .filter(job => jobActivityTime(job) >= cutoff)
+        .slice(0, RECENT_TERMINAL_REFINE_CAP);
+    const freshTerminalIds = new Set(freshTerminal.map(job => job.jobId));
+
+    const byStatus: Record<string, number> = {};
+    for (const job of activeJobs) {
+        byStatus[job.status] = (byStatus[job.status] ?? 0) + 1;
+    }
+    for (const job of freshTerminal) {
+        byStatus[job.status] = (byStatus[job.status] ?? 0) + 1;
+    }
+
+    const staleTerminal = terminalJobs.length - freshTerminalIds.size;
+
+    return {
+        total: activeJobs.length + freshTerminal.length,
+        byStatus,
+        staleTerminal,
+        activeJobs,
+    };
+}

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

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