@adhdev/daemon-core 0.9.82-rc.460 → 0.9.82-rc.462

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

@@ -5,13 +5,19 @@ import { LOG } from '../logging/logger.js';
 import { getLedgerDir, readLedgerEntries, appendLedgerEntry } from './mesh-ledger.js';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
 import { buildMeshSystemMessage, readNonEmptyString, readRecord, resolveEventSessionId, readMeshCompletionSummary, isWeakCompletionMetadata } from './mesh-events-utils.js';
-import { expandDaemonIdForms } from '@adhdev/mesh-shared';
+import { daemonIdsEquivalent, expandDaemonIdForms } from '@adhdev/mesh-shared';
 import {
+    assertPendingMeshCoordinatorEventV2,
     buildPendingEventEmitStamp,
+    coordinatorIdentityEquals,
     coordinatorIdentityFromEmitFields,
+    coordinatorIdentityKey,
+    isMeshEventScope,
     MESH_PROTOCOL_VERSION_V2,
+    shouldDeliverPendingEventToCoordinator,
     type CoordinatorIdentity,
     type MeshEventScope,
+    type PendingMeshCoordinatorEventV2,
 } from './contracts.js';
 
 // ---------------------------------------------------------------------------
@@ -108,6 +114,351 @@ function normalizeCoordinatorDaemonIds(
     return expandDaemonIdForms(coordinatorDaemonId);
 }
 
+// ─── B3a: drain-side v2 routing (accept-and-warn) ────────────────────────────
+//
+// Stage-1 of the v2 receive path. The drain scope is still primarily gated by the
+// SQLite/JSONL `coordinator_daemon_id` filter (v1 mechanism, untouched here), so
+// this layer runs on top of an already daemon-scoped candidate set and adds:
+//
+//   1. v2 unicast routing — an event whose intendedFor addresses a DIFFERENT
+//      coordinator on THIS daemon (a sibling CLI/MCP session) is skipped, so a
+//      completion doesn't cross-surface. Broadcast/system-as-broadcast pass.
+//   2. eventId idempotency — a v2 event whose eventId was already drained is
+//      skipped (durable, via MeshRuntimeStore.hasDrainedEventId) plus a per-drain
+//      batch guard against same-batch duplicates.
+//   3. accept-and-warn — a v2 event that FAILS validation, or has NO version, is
+//      NOT dropped: it passes through (no v1 regression) with a one-shot WARN and
+//      a counter bump. Hard rejection is T6 (enforce mode), not here.
+//   4. re-attribution fallback — a unicast event whose intendedFor does not match
+//      the drainer by identity is NOT dropped when its intendedFor.daemonId is the
+//      SAME machine as the drainer (a coordinatorRunId change from a restart
+//      orphaned it): it is delivered to the current coordinator on that daemon.
+
+/**
+ * T6 (B3c) enforce switch. When ON, the drain path stops passing an unversioned
+ * (v1) or a validation-failing v2 event through to the coordinator — it QUARANTINES
+ * it instead (excluded from the delivered batch + WARN + counter), and unicast
+ * routing is the only delivery path (there is no v1 broadcast fallback). Off (the
+ * default) preserves the accept-and-warn rollout behaviour exactly.
+ *
+ * Per the rollout plan (§1 decision 4): enforce is `MESH_PROTOCOL_V2_ENFORCE` (env)
+ * — its activation is a deliberate operational step taken ONLY after daemonBuilds
+ * confirms every node emits v2 (§배포 게이트 1 / risk §4). So the code default is
+ * OFF; flipping the env back to accept mode is a pure-env rollback (no code change,
+ * no data migration — the schema is additive). Read at call time so a test /
+ * operator can toggle it without a restart.
+ *
+ * Quarantine (not drop) keeps the loss-free invariant. The DESTRUCTIVE drain has
+ * already consumed the event from its store by the time routing runs, so "held
+ * back" here means: excluded from the delivered batch AND mirrored into the mesh
+ * ledger as a recoverable `event_held` entry (the same recovery channel the
+ * pending-trim path uses). It is observable via the counters + the ledger, so an
+ * operator can requeue it after fixing the producer. The non-destructive PEEK path
+ * (countMetrics=false) merely omits the event from the returned list — it never
+ * consumed it and must not ledger-record on every status poll.
+ */
+export function isMeshProtocolV2EnforceEnabled(): boolean {
+    const raw = readNonEmptyString(process.env.MESH_PROTOCOL_V2_ENFORCE);
+    if (!raw) return false;
+    const v = raw.trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'on' || v === 'yes';
+}
+
+/**
+ * Record a v2-enforce-quarantined event into the mesh ledger as recoverable, so a
+ * destructively-drained event held back by enforce is auditable and requeue-able
+ * (loss-free invariant). Mirrors the pending-trim `event_held` shape. Best-effort:
+ * a ledger write failure must not break the drain. Called ONLY on the destructive
+ * drain path (the peek path never consumed the event, so nothing to recover).
+ */
+function ledgerRecordQuarantinedEvent(event: PendingMeshCoordinatorEvent, reason: string): void {
+    try {
+        const finalSummary = readMeshCompletionSummary(event.metadataEvent || {});
+        appendLedgerEntry(event.meshId, {
+            kind: 'event_held',
+            ...(event.nodeId ? { nodeId: event.nodeId } : {}),
+            payload: {
+                event: event.event,
+                reason,
+                recoverable: true,
+                nodeLabel: event.nodeLabel,
+                ...(event.workspace ? { workspace: event.workspace } : {}),
+                targetCoordinatorDaemonId: event.targetCoordinatorDaemonId ?? null,
+                ...(readNonEmptyString(event.eventId) ? { eventId: event.eventId } : {}),
+                queuedAt: event.queuedAt,
+                ...(finalSummary ? { finalSummary } : {}),
+            },
+        });
+    } catch (e: any) {
+        LOG.warn('MeshEventsV2', `Failed to ledger-record v2-quarantined ${event.event} for mesh ${event.meshId}: ${e?.message || e}`);
+    }
+}
+
+/** Observability counters for the v2 drain path. Read by tests and surfaced in
+ *  mesh_status (B4/T6). Process-lifetime totals — never reset in production. */
+const meshV2DrainCounters = {
+    /** v2 events that passed validation and unicast/broadcast routing → delivered. */
+    v2Delivered: 0,
+    /** v2 unicast events skipped because intendedFor addressed another coordinator. */
+    v2RoutedAway: 0,
+    /** v2 events skipped because their eventId was already drained (idempotency). */
+    v2DedupSkipped: 0,
+    /** v2 events that failed assertPendingMeshCoordinatorEventV2 but were PASSED
+     *  THROUGH (accept mode). Non-zero here is the rollout signal that a producer
+     *  emits a malformed envelope. */
+    v2ValidationFailedAccepted: 0,
+    /** unicast events re-attributed to the drainer via daemon-core match (a
+     *  coordinatorRunId change orphaned them). */
+    v2ReattributedToDrainer: 0,
+    /** v1 (unversioned) events passed through as broadcast (rollout baseline). */
+    v1BroadcastAccepted: 0,
+    /** T6 enforce: v2 events that FAILED validation and were QUARANTINED (held back
+     *  from delivery, not dropped). Non-zero here means a producer is still emitting a
+     *  malformed envelope after enforce was turned on. */
+    v2ValidationFailedQuarantined: 0,
+    /** T6 enforce: v1 (unversioned) events QUARANTINED because no v2 envelope could be
+     *  derived at emit time. Non-zero here means a producer path still emits v1 after
+     *  enforce — it should reach 0 once every node is on a v2-stamping build. */
+    v1UnversionedQuarantined: 0,
+};
+
+/** Test/observability accessor for the v2 drain counters (snapshot copy). */
+export function getMeshV2DrainCounters(): Readonly<typeof meshV2DrainCounters> {
+    return { ...meshV2DrainCounters };
+}
+
+/** Test helper: zero the v2 drain counters so a test starts from a clean slate. */
+export function __resetMeshV2DrainCountersForTests(): void {
+    for (const k of Object.keys(meshV2DrainCounters) as Array<keyof typeof meshV2DrainCounters>) {
+        meshV2DrainCounters[k] = 0;
+    }
+}
+
+// One-shot WARN dedup: an accept-mode warning is logged once per (meshId, eventId)
+// so a re-polled malformed event doesn't spam the log every 4s reconcile tick.
+const warnedV2Violations = new Set<string>();
+function warnV2Once(key: string, message: string): void {
+    if (warnedV2Violations.has(key)) return;
+    warnedV2Violations.add(key);
+    // Bound the set so a long-lived daemon churning many distinct eventIds can't leak.
+    if (warnedV2Violations.size > 2000) {
+        const first = warnedV2Violations.values().next().value;
+        if (first !== undefined) warnedV2Violations.delete(first);
+    }
+    LOG.warn('MeshEventsV2', message);
+}
+
+/** Test helper: clear the one-shot WARN dedup set. */
+export function __resetMeshV2WarnDedupForTests(): void {
+    warnedV2Violations.clear();
+}
+
+/**
+ * Resolve the drainer's CoordinatorIdentity for v2 routing from the daemon-id
+ * argument the (untouchable) reconcile-loop already passes. The daemon ids are the
+ * dual/expanded self-identity forms from resolveCoordinatorDaemonIds; the FIRST is
+ * the primary. coordinatorRunId is not threaded through the drain call yet, so it
+ * falls back to the daemonId exactly as the emit side does
+ * (coordinatorIdentityFromEmitFields) — this keeps drain-side identity CONSISTENT
+ * with how v1→v2 events were stamped, and unicast equality then reduces to the
+ * daemon-core match, which is the correct rollout-window granularity. A caller that
+ * knows the full identity (with a real coordinatorRunId) may pass it explicitly to
+ * override. Returns undefined when no daemon id is known (→ v2 routing is a no-op,
+ * everything passes as-is).
+ */
+function resolveDrainerIdentity(
+    daemonIds: ReadonlyArray<string>,
+    explicit?: CoordinatorIdentity,
+): CoordinatorIdentity | undefined {
+    if (explicit) return explicit;
+    return coordinatorIdentityFromEmitFields({ daemonId: daemonIds[0] });
+}
+
+/** A v2 event carries a '2.0' protocolVersion. Everything else is a v1 event. */
+function isV2Event(event: PendingMeshCoordinatorEvent): boolean {
+    return event.protocolVersion === MESH_PROTOCOL_VERSION_V2;
+}
+
+/**
+ * True when an identity's coordinatorRunId is merely its own daemonId form (the
+ * B2a fallback in coordinatorIdentityFromEmitFields — no real coordinatorRunId was
+ * threaded through the emit/drain site yet). For such an identity the runId carries
+ * NO information beyond the daemon, so two different daemon-id FORMS of the same
+ * machine (mach_ vs daemon_mach_) must not be treated as different coordinators.
+ */
+function runIdIsDaemonFormFallback(identity: CoordinatorIdentity): boolean {
+    return daemonIdsEquivalent(identity.coordinatorRunId, identity.daemonId);
+}
+
+/**
+ * Delivery equality for the rollout window. When BOTH sides carry only a
+ * daemon-form-fallback runId (no real coordinatorRunId wired yet), a match reduces
+ * to same-machine — so a completion stamped `daemon_mach_X` is delivered to a
+ * coordinator that knows itself as bare `mach_X` (the canon-identity heterogeneous-
+ * form case). The session is compared ONLY when BOTH sides carry one: a session-less
+ * drainer is a daemon-level drain (what the reconcile loop passes) that accepts any
+ * session's events on that machine — targetCoordinatorSessionId is a PHASE-2 inject
+ * key, not a drain-scoping key (see the v1 field comment). When only the drainer AND
+ * the event both name a session do we require them to match, so a session-specific
+ * coordinator does not receive a sibling session's unicast event.
+ *
+ * When EITHER side has a real (non-daemon-form) runId, fall back to strict
+ * coordinatorIdentityEquals so two genuinely distinct coordinators on the same
+ * daemon (different real runIds) stay separated.
+ */
+function identityDeliversTo(intendedFor: CoordinatorIdentity, drainer: CoordinatorIdentity): boolean {
+    if (runIdIsDaemonFormFallback(intendedFor) && runIdIsDaemonFormFallback(drainer)) {
+        if (!daemonIdsEquivalent(intendedFor.daemonId, drainer.daemonId)) return false;
+        // Session filter applies only when the drainer itself is session-specific.
+        if (intendedFor.sessionId && drainer.sessionId) {
+            return intendedFor.sessionId === drainer.sessionId;
+        }
+        return true;
+    }
+    return coordinatorIdentityEquals(intendedFor, drainer);
+}
+
+/**
+ * Apply v2 receive-side routing + idempotency to a merged, already daemon-scoped
+ * candidate list (accept-and-warn — never drops on validation failure).
+ *
+ * - `drainer` undefined → routing is skipped, list returned unchanged (safety).
+ * - Marks each surviving v2 event's eventId in `batchSeen` so a same-batch dup is
+ *   skipped; a caller that persists drains uses `alreadyDrained` for the durable
+ *   check (getPending peek passes a no-op so a peek never dedups against itself).
+ */
+function routeV2EventsForDrainer(
+    events: PendingMeshCoordinatorEvent[],
+    drainer: CoordinatorIdentity | undefined,
+    ctx: {
+        alreadyDrained: (eventId: string) => boolean;
+        batchSeen: Set<string>;
+        /** false for a non-destructive peek so the frequent status-poll path does
+         *  not inflate the delivery counters (only the real drain counts). */
+        countMetrics: boolean;
+    },
+): PendingMeshCoordinatorEvent[] {
+    if (!drainer) return events;
+    // Read the enforce flag ONCE per drain so the whole batch is classified under a
+    // single, consistent policy (a mid-batch env flip cannot split one drain).
+    const enforce = isMeshProtocolV2EnforceEnabled();
+    const bump = (k: keyof typeof meshV2DrainCounters) => { if (ctx.countMetrics) meshV2DrainCounters[k]++; };
+    const kept: PendingMeshCoordinatorEvent[] = [];
+    for (const event of events) {
+        if (!isV2Event(event)) {
+            // v1 / unversioned event. ACCEPT MODE: broadcast during rollout (existing
+            // policy). ENFORCE MODE: quarantine — an unversioned event has no scope, so
+            // there is no safe unicast target; hold it back (not delivered) and mirror
+            // it to the ledger as recoverable, with a one-shot WARN + counter.
+            if (enforce) {
+                bump('v1UnversionedQuarantined');
+                if (ctx.countMetrics) ledgerRecordQuarantinedEvent(event, 'v2_enforce_unversioned_quarantined');
+                warnV2Once(
+                    `${event.meshId}::${event.eventId ?? event.event}::v1-quarantined`,
+                    `v2 ENFORCE: unversioned ${event.event} on mesh ${event.meshId} QUARANTINED (no v2 envelope — held back, not delivered; ledger-recorded recoverable). A producer path still emits v1.`,
+                );
+                continue;
+            }
+            bump('v1BroadcastAccepted');
+            kept.push(event);
+            continue;
+        }
+
+        // Validate the v2 envelope. ACCEPT MODE: a validation failure does NOT drop
+        // the event — it passes through with a one-shot WARN + counter. ENFORCE MODE:
+        // a validation failure is QUARANTINED (held back, not delivered) — the malformed
+        // envelope carries no trustworthy scope/target, so delivering it risks a
+        // cross-surface. It is ledger-recorded recoverable on the destructive path.
+        let validated: PendingMeshCoordinatorEventV2;
+        try {
+            validated = assertPendingMeshCoordinatorEventV2(event);
+        } catch (e: any) {
+            if (enforce) {
+                bump('v2ValidationFailedQuarantined');
+                if (ctx.countMetrics) ledgerRecordQuarantinedEvent(event, 'v2_enforce_validation_failed_quarantined');
+                warnV2Once(
+                    `${event.meshId}::${event.eventId ?? event.event}::invalid-quarantined`,
+                    `v2 ENFORCE: envelope validation failed for ${event.event} on mesh ${event.meshId} — QUARANTINED (held back, not delivered; ledger-recorded recoverable): ${e?.message || e}`,
+                );
+                continue;
+            }
+            bump('v2ValidationFailedAccepted');
+            warnV2Once(
+                `${event.meshId}::${event.eventId ?? event.event}::invalid`,
+                `v2 envelope validation failed for ${event.event} on mesh ${event.meshId} — PASSED THROUGH (accept mode): ${e?.message || e}`,
+            );
+            kept.push(event);
+            continue;
+        }
+
+        // eventId idempotency: skip if already drained (durable) or already seen in
+        // this same batch (guards the SQLite+JSONL dual-store merge duplicate).
+        const eventId = validated.eventId;
+        if (ctx.batchSeen.has(eventId) || ctx.alreadyDrained(eventId)) {
+            bump('v2DedupSkipped');
+            continue;
+        }
+
+        // Broadcast → any coordinator; system → daemon handler only (never a
+        // coordinator). Delegates to the contract helper for those two scopes.
+        if (validated.scope !== 'unicast') {
+            if (shouldDeliverPendingEventToCoordinator(validated, drainer)) {
+                ctx.batchSeen.add(eventId);
+                bump('v2Delivered');
+                kept.push(event);
+            } else {
+                // system scope → not for any coordinator.
+                bump('v2RoutedAway');
+            }
+            continue;
+        }
+
+        // Unicast: deliver iff intendedFor addresses THIS drainer. identityDeliversTo
+        // treats a daemon-form-fallback runId (no real coordinatorRunId wired yet) as
+        // form-agnostic so a `daemon_mach_X`-addressed event reaches a bare-`mach_X`
+        // drainer (heterogeneous-form same coordinator), while keeping two REAL
+        // distinct runIds on one daemon separated.
+        if (validated.intendedFor && identityDeliversTo(validated.intendedFor, drainer)) {
+            ctx.batchSeen.add(eventId);
+            bump('v2Delivered');
+            kept.push(event);
+            continue;
+        }
+
+        // Not delivered by identity. Apply the re-attribution fallback (plan risk
+        // §4): if intendedFor addresses the SAME MACHINE as the drainer AND the
+        // mismatch is a genuine coordinatorRunId change (a restart minted a fresh
+        // runId), deliver it to the current coordinator rather than orphaning it.
+        //
+        // Guard: when BOTH sides carry only a daemon-form-fallback runId, a mismatch
+        // that survived identityDeliversTo is a SESSION mismatch (a sibling
+        // coordinator on the same daemon) — that is a legitimate route-away, NOT an
+        // orphaned event, so re-attribution must not fire. Re-attribution requires a
+        // REAL runId difference, which means at least one side carries a real runId.
+        const realRunIdMismatch = !runIdIsDaemonFormFallback(validated.intendedFor!)
+            || !runIdIsDaemonFormFallback(drainer);
+        if (
+            validated.intendedFor
+            && realRunIdMismatch
+            && daemonIdsEquivalent(validated.intendedFor.daemonId, drainer.daemonId)
+        ) {
+            ctx.batchSeen.add(eventId);
+            bump('v2ReattributedToDrainer');
+            warnV2Once(
+                `${event.meshId}::${eventId}::reattributed`,
+                `v2 unicast ${event.event} on mesh ${event.meshId} re-attributed to current coordinator ${coordinatorIdentityKey(drainer)} (originating coordinatorRunId no longer live)`,
+            );
+            kept.push(event);
+            continue;
+        }
+
+        // Addressed to a genuinely different coordinator (different machine, or
+        // system scope) → not for this drainer. Skipped (left for its own drainer).
+        bump('v2RoutedAway');
+    }
+    return kept;
+}
+
 export function readRefineJobId(event: { metadataEvent?: Record<string, unknown> } | Record<string, unknown>): string {
     const metadata = readRecord((event as any).metadataEvent) || event as Record<string, unknown>;
     const result = readRecord(metadata.result);
@@ -422,6 +773,74 @@ export function stampPendingEventV2(
     };
 }
 
+// ─── v2 envelope: remote (P2P) boundary preservation (B3b/T4) ─────────────
+//
+// The remote pull round-trip (mesh-reconcile-loop pullRemoteNodeQueues →
+// get_pending_mesh_events → buildForwardPayloadFromPending → handleMeshForwardEvent
+// → queuePendingMeshCoordinatorEvent) flattens a queued PendingMeshCoordinatorEvent
+// into a flat wire payload and rebuilds it on the receiving daemon. The v2 envelope
+// fields (protocolVersion / eventId / scope / dispatchedBy / intendedFor) live at the
+// TOP LEVEL of the event, not inside metadataEvent, so the flatten/rebuild whitelist
+// dropped them: the re-queue then re-stamped a FRESH eventId, breaking cross-machine
+// idempotency and downgrading the relayed completion to v1 (broadcast) routing.
+//
+// These two helpers are the single serialization/deserialization pair for that
+// boundary. serializeV2EnvelopeToWire copies the present v2 fields onto the flat
+// payload; readV2EnvelopeFromWire validates and restores them for the re-queue. The
+// eventId is carried verbatim so stampPendingEventV2's already-stamped short-circuit
+// preserves it (no new UUID). Kept pure + exported so the round-trip is unit-testable.
+
+/** Read a CoordinatorIdentity off an untrusted wire object, or undefined if malformed. */
+function readCoordinatorIdentityFromWire(raw: unknown): CoordinatorIdentity | undefined {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+    const obj = raw as Record<string, unknown>;
+    const daemonId = readNonEmptyString(obj.daemonId);
+    const coordinatorRunId = readNonEmptyString(obj.coordinatorRunId);
+    if (!daemonId || !coordinatorRunId) return undefined;
+    const sessionId = readNonEmptyString(obj.sessionId);
+    return { daemonId, coordinatorRunId, ...(sessionId ? { sessionId } : {}) };
+}
+
+/**
+ * Copy the v2 envelope fields that are present on `event` onto a flat wire
+ * payload. Only sets a field when it is present, so a v1 event contributes
+ * nothing (the payload stays v1-shaped and version-skew safe).
+ */
+export function serializeV2EnvelopeToWire(event: PendingMeshCoordinatorEvent): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    if (event.protocolVersion) out.protocolVersion = event.protocolVersion;
+    if (readNonEmptyString(event.eventId)) out.eventId = event.eventId;
+    if (event.scope) out.scope = event.scope;
+    if (event.dispatchedBy) out.dispatchedBy = event.dispatchedBy;
+    if (event.intendedFor) out.intendedFor = event.intendedFor;
+    return out;
+}
+
+/**
+ * Restore the v2 envelope fields from a flat wire payload for a re-queue. Only
+ * returns fields that survive validation; a payload missing/malforming a field
+ * yields a partial (or empty) object so the re-queue path stays v1-safe. The
+ * eventId is returned verbatim — its preservation is the idempotency guarantee.
+ */
+export function readV2EnvelopeFromWire(payload: Record<string, unknown>): Partial<Pick<
+    PendingMeshCoordinatorEvent,
+    'protocolVersion' | 'eventId' | 'scope' | 'dispatchedBy' | 'intendedFor'
+>> {
+    const out: Partial<Pick<
+        PendingMeshCoordinatorEvent,
+        'protocolVersion' | 'eventId' | 'scope' | 'dispatchedBy' | 'intendedFor'
+    >> = {};
+    if (payload.protocolVersion === MESH_PROTOCOL_VERSION_V2) out.protocolVersion = MESH_PROTOCOL_VERSION_V2;
+    const eventId = readNonEmptyString(payload.eventId);
+    if (eventId) out.eventId = eventId;
+    if (isMeshEventScope(payload.scope)) out.scope = payload.scope;
+    const dispatchedBy = readCoordinatorIdentityFromWire(payload.dispatchedBy);
+    if (dispatchedBy) out.dispatchedBy = dispatchedBy;
+    const intendedFor = readCoordinatorIdentityFromWire(payload.intendedFor);
+    if (intendedFor) out.intendedFor = intendedFor;
+    return out;
+}
+
 export function queuePendingMeshCoordinatorEvent(
     rawEvent: PendingMeshCoordinatorEvent,
     hint?: PendingEventEmitHint,
@@ -569,7 +988,7 @@ function selectiveDrainFile(
 export function drainPendingMeshCoordinatorEvents(
     meshId?: string,
     coordinatorDaemonId?: string | ReadonlyArray<string>,
-    opts?: { onlyEvents?: ReadonlySet<string> },
+    opts?: { onlyEvents?: ReadonlySet<string>; drainerIdentity?: CoordinatorIdentity },
 ): PendingMeshCoordinatorEvent[] {
     if (!meshId) return [];
 
@@ -580,6 +999,18 @@ export function drainPendingMeshCoordinatorEvents(
     const daemonIds = normalizeCoordinatorDaemonIds(coordinatorDaemonId);
     const primaryDaemonId = daemonIds[0];
 
+    // B3a: the drainer's v2 identity, for unicast routing + eventId dedup. Derived
+    // from the daemon ids the (untouchable) reconcile-loop already passes, so no
+    // caller change is required; a caller may still pass the full identity.
+    const drainer = resolveDrainerIdentity(daemonIds, opts?.drainerIdentity);
+    // Snapshot the ALREADY-drained v2 eventIds BEFORE the SQLite drain marks this
+    // batch drained=1 — the re-delivery dedup baseline. Reading it after would
+    // self-match the batch's own rows.
+    let priorDrainedEventIds = new Set<string>();
+    try {
+        priorDrainedEventIds = MeshRuntimeStore.getInstance().drainedEventIdsForMesh(meshId);
+    } catch { /* store unavailable — no durable baseline; batch guard still applies */ }
+
     const onlyEvents = opts?.onlyEvents;
     const matchesFilter = (eventName: string): boolean => !onlyEvents || onlyEvents.has(eventName);
 
@@ -648,7 +1079,17 @@ export function drainPendingMeshCoordinatorEvents(
     // longer exists — delivery is now queue-drain-only (reconcile loop or MCP pull),
     // so an event is consumed by exactly one drainer via the atomic SQLite drained=1
     // marking. There is no PTY-vs-poll double path left to dedup against.
-    return reconcilePendingMeshCoordinatorEvents(meshId, merged);
+    //
+    // B3a: v2 receive-side routing (accept-and-warn) — unicast targeting, eventId
+    // idempotency, malformed-envelope pass-through-with-warn. v1 events broadcast.
+    // Runs AFTER the merge/reconcile so a single eventId dedup batch covers both
+    // stores. Non-destructive to v1 behaviour when no drainer identity is known.
+    const routed = routeV2EventsForDrainer(merged, drainer, {
+        alreadyDrained: (eventId) => priorDrainedEventIds.has(eventId),
+        batchSeen: new Set<string>(),
+        countMetrics: true,
+    });
+    return reconcilePendingMeshCoordinatorEvents(meshId, routed);
 }
 
 /**
@@ -703,9 +1144,21 @@ export function retractPendingDispatchBlockedEvent(
 }
 
 /** Peek at pending coordinator events without draining (non-destructive). */
-export function getPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string | ReadonlyArray<string>): readonly PendingMeshCoordinatorEvent[] {
+export function getPendingMeshCoordinatorEvents(
+    meshId?: string,
+    coordinatorDaemonId?: string | ReadonlyArray<string>,
+    opts?: { drainerIdentity?: CoordinatorIdentity },
+): readonly PendingMeshCoordinatorEvent[] {
     if (!meshId) return [];
     const daemonIds = normalizeCoordinatorDaemonIds(coordinatorDaemonId);
+    // B3a: same v2 routing the destructive drain applies, so a peek (mesh_status
+    // count, reconcile pre-check) sees the SAME set the drain would deliver — a
+    // unicast event for another coordinator is not counted for this one.
+    const drainer = resolveDrainerIdentity(daemonIds, opts?.drainerIdentity);
+    let priorDrainedEventIds = new Set<string>();
+    try {
+        priorDrainedEventIds = MeshRuntimeStore.getInstance().drainedEventIdsForMesh(meshId);
+    } catch { /* store unavailable — batch guard still applies */ }
 
     // Merge SQLite (primary) + JSONL (legacy) with fingerprint dedup.
     const merged: PendingMeshCoordinatorEvent[] = [];
@@ -737,7 +1190,14 @@ export function getPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaem
 
     // (Former R3 direct-delivered filter removed — no PTY direct-inject path exists
     // anymore, so a peeked pending event has genuinely not yet been consumed.)
-    return reconcilePendingMeshCoordinatorEvents(meshId, merged);
+    // B3a: apply the SAME v2 routing the drain applies (non-destructive: no counter
+    // inflation on the frequent status-poll path).
+    const routed = routeV2EventsForDrainer(merged, drainer, {
+        alreadyDrained: (eventId) => priorDrainedEventIds.has(eventId),
+        batchSeen: new Set<string>(),
+        countMetrics: false,
+    });
+    return reconcilePendingMeshCoordinatorEvents(meshId, routed);
 }
 
 /**

package/src/mesh/mesh-events.ts

@@ -11,6 +11,10 @@ export {
     drainPendingMeshCoordinatorEvents,
     getPendingMeshCoordinatorEvents,
     clearPendingMeshCoordinatorEvents,
+    serializeV2EnvelopeToWire,
+    readV2EnvelopeFromWire,
+    getMeshV2DrainCounters,
+    isMeshProtocolV2EnforceEnabled,
 } from './mesh-events-pending.js';
 
 export {
@@ -22,6 +26,7 @@ export {
     runMeshReconcileTick,
     resolveCoordinatorDrainDeliverability,
     shouldHoldPendingDrainForBusyLocalCoordinator,
+    getMeshV2BackstopCounters,
 } from './mesh-reconcile-loop.js';
 
 export type { MeshQueueTriggerResult } from './mesh-events-coordinator.js';

package/src/mesh/mesh-node-identity.ts

@@ -319,9 +319,21 @@ export function recordInlineMeshDirectGitTruth(
     node: any,
     git: Record<string, unknown>,
     source: 'selected_coordinator_local_git' | 'selected_coordinator_mesh_p2p_git',
-): { reporterPlatform: string | null; reporterArch: string | null; reporterMachineNickname: string | null } {
+): {
+    reporterPlatform: string | null;
+    reporterArch: string | null;
+    reporterMachineNickname: string | null;
+    reporterProviderVersions: Record<string, string> | null;
+    reporterDaemonBuildVersion: string | null;
+} {
     if (!node || typeof node !== 'object' || Array.isArray(node)) {
-        return { reporterPlatform: null, reporterArch: null, reporterMachineNickname: null };
+        return {
+            reporterPlatform: null,
+            reporterArch: null,
+            reporterMachineNickname: null,
+            reporterProviderVersions: null,
+            reporterDaemonBuildVersion: null,
+        };
     }
     const checkedAt = readNumberValue(git.lastCheckedAt) ?? Date.now();
     const updatedAt = new Date(checkedAt).toISOString();
@@ -366,7 +378,38 @@ export function recordInlineMeshDirectGitTruth(
     // overwrite an existing nickname with an empty value.
     const reporterMachineNickname = readStringValue(git.reporterMachineNickname) ?? null;
     if (reporterMachineNickname) node.machineNickname = reporterMachineNickname;
-    return { reporterPlatform, reporterArch, reporterMachineNickname };
+    // T7: self-heal provider versions + daemon build version from the same git_status
+    // envelope. These are best-effort observability (never routing), so the raw
+    // reported map is stamped onto dedicated node fields and overwritten by the next
+    // report — never merged with a stale value the way an operator override would be.
+    const reporterProviderVersions = readProviderVersionsRecord(git.reporterProviderVersions);
+    if (reporterProviderVersions) node.reportedProviderVersions = reporterProviderVersions;
+    const reporterDaemonBuildVersion = readStringValue(git.reporterDaemonBuildVersion) ?? null;
+    if (reporterDaemonBuildVersion) node.reportedDaemonBuildVersion = reporterDaemonBuildVersion;
+    return {
+        reporterPlatform,
+        reporterArch,
+        reporterMachineNickname,
+        reporterProviderVersions,
+        reporterDaemonBuildVersion,
+    };
+}
+
+/**
+ * Coerce an unknown git-envelope `reporterProviderVersions` field into a clean
+ * `{ providerId: version }` record: only string→non-empty-string entries survive.
+ * Returns null when nothing usable is present so callers can skip the stamp.
+ */
+function readProviderVersionsRecord(value: unknown): Record<string, string> | null {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    const out: Record<string, string> = {};
+    for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+        if (typeof key !== 'string' || !key.trim()) continue;
+        const version = typeof raw === 'string' ? raw.trim() : '';
+        if (!version) continue;
+        out[key] = version;
+    }
+    return Object.keys(out).length > 0 ? out : null;
 }
 
 /**
@@ -403,7 +446,13 @@ export function persistNodeReporterPlatform(
     meshSource: 'inline_cache' | 'inline_bootstrap' | 'local_config',
     mesh: any,
     nodeId: string | undefined,
-    reporter: { reporterPlatform: string | null; reporterArch: string | null; reporterMachineNickname?: string | null },
+    reporter: {
+        reporterPlatform: string | null;
+        reporterArch: string | null;
+        reporterMachineNickname?: string | null;
+        reporterProviderVersions?: Record<string, string> | null;
+        reporterDaemonBuildVersion?: string | null;
+    },
 ): void {
     if (meshSource !== 'local_config') return;
     const meshId = readStringValue(mesh?.id);
@@ -411,9 +460,25 @@ export function persistNodeReporterPlatform(
     const reportedPlatform = reporter.reporterPlatform ?? undefined;
     const reportedArch = reporter.reporterArch ?? undefined;
     const reportedMachineNickname = reporter.reporterMachineNickname ?? undefined;
-    if (!reportedPlatform && !reportedArch && !reportedMachineNickname) return;
+    const reportedProviderVersions = reporter.reporterProviderVersions ?? undefined;
+    const reportedDaemonBuildVersion = reporter.reporterDaemonBuildVersion ?? undefined;
+    if (
+        !reportedPlatform &&
+        !reportedArch &&
+        !reportedMachineNickname &&
+        !reportedProviderVersions &&
+        !reportedDaemonBuildVersion
+    ) {
+        return;
+    }
     void import('../config/mesh-config.js')
-        .then(({ updateNode }) => updateNode(meshId, nodeId, { reportedPlatform, reportedArch, reportedMachineNickname }))
+        .then(({ updateNode }) => updateNode(meshId, nodeId, {
+            reportedPlatform,
+            reportedArch,
+            reportedMachineNickname,
+            reportedProviderVersions,
+            reportedDaemonBuildVersion,
+        }))
         .catch(() => { /* best-effort self-heal; never block status assembly */ });
 }
 
@@ -1428,6 +1493,12 @@ async function probeRemoteMeshGitStatus(args: {
     if (reporterPlatform) git.reporterPlatform = reporterPlatform;
     if (reporterArch) git.reporterArch = reporterArch;
     if (reporterMachineNickname) git.reporterMachineNickname = reporterMachineNickname;
+    // T7: propagate the member's self-reported provider versions + build version on
+    // the same reporter* channel so a remote node's providerVersions self-heal too.
+    const reporterProviderVersions = readProviderVersionsRecord(remoteResult?.reporterProviderVersions);
+    if (reporterProviderVersions) git.reporterProviderVersions = reporterProviderVersions;
+    const reporterDaemonBuildVersion = readStringValue(remoteResult?.reporterDaemonBuildVersion);
+    if (reporterDaemonBuildVersion) git.reporterDaemonBuildVersion = reporterDaemonBuildVersion;
     return git;
 }