@adhdev/daemon-core 0.9.82-rc.461 → 0.9.82-rc.463

package/src/commands/router.ts

@@ -22,7 +22,7 @@ import { DaemonCliManager } from './cli-manager.js';
 import type { ProviderLoader } from '../providers/provider-loader.js';
 import type { ProviderInstanceManager } from '../providers/provider-instance-manager.js';
 import { killIdeProcess, isIdeRunning } from '../launch.js';
-import { normalizeMeshNodeId, meshNodeIdMatches, daemonIdsEquivalent } from '@adhdev/mesh-shared';
+import { normalizeMeshNodeId, meshNodeIdMatches } from '@adhdev/mesh-shared';
 import { SessionRegistry } from '../sessions/registry.js';
 import { LOG } from '../logging/logger.js';
 import { logCommand } from '../logging/command-log.js';
@@ -42,27 +42,16 @@ import { execFileSync } from 'node:child_process';
 
 // ─── Extracted-module imports (symbols the dispatch class consumes) ───
 import {
-    applyInlineMeshBranchConvergence,
-    buildInlineMeshTransitGitStatus,
-    buildLivePeerGitConnection,
-    collectMeshNodeHostedSessionIds,
-    deriveMeshNodeHealthFromGit,
     foldMeshNodeIdentityToCanonical,
     inlineMeshCarriesTransientNodeTruth,
-    isDeadLocalWorktreeNode,
     MESH_DIRECT_PROBE_REUSE_MS,
     MeshGitProbeCache,
     normalizeInlineMeshNodeIdentity,
-    readBooleanValue,
-    readCachedInlineMeshActiveSessions,
     readInlineMeshNodeId,
-    readMeshNodeDaemonId,
     readObjectRecord,
     readStringValue,
     reconcileInlineMeshCache,
     sanitizeInlineMesh,
-    shouldRefreshStalePendingAggregate,
-    summarizeInlineMeshBranchConvergence,
 } from '../mesh/mesh-node-identity.js';
 import {
     alignRefinerySubmodulesAfterMerge,
@@ -105,6 +94,14 @@ import {
     recordIntentionalMeshSessionStop,
     sessionMatchesMeshNode,
 } from './router-worktree-cleanup.js';
+// ─── Aggregate mesh-status cache (bodies extracted from this file) ───
+import {
+    getCachedAggregateMeshStatus,
+    hydrateCachedAggregateMeshStatusFromInline,
+    rememberAggregateMeshStatus,
+} from './router-aggregate-status.js';
+// ─── Remote mesh-session owner resolution (bodies extracted from this file) ───
+import { resolveRemoteMeshSessionOwnerDaemonId } from './router-mesh-session-owner.js';
 
 // ─── Barrel re-exports: node-identity / git-freshness, refine gates, coordinator config ───
 // These modules were split out of router.ts. Re-export their public surface so the
@@ -299,8 +296,9 @@ export class DaemonCommandRouter {
      *  on disk) clears the tombstone and merges normally, preserving clone
      *  worktree visibility and legitimate node re-creation. */
     private removedInlineMeshNodeIds = new Map<string, Set<string>>();
-    /** Coordinator-owned whole-mesh aggregate status snapshots. Browser callers read this by default. */
-    private aggregateMeshStatusCache = new Map<string, { builtAt: number; snapshot: any; queueRevision: string }>();
+    /** Coordinator-owned whole-mesh aggregate status snapshots. Browser callers read this by default.
+     *  Public (not private) so the extracted ./router-aggregate-status.ts orchestration can reach it via `self`. */
+    aggregateMeshStatusCache = new Map<string, { builtAt: number; snapshot: any; queueRevision: string }>();
     /** Shared per-peer git_status probe dedup + recently-probed reuse gate.
      *  Spans separate mesh_status/get_mesh calls so the dashboard auto-retry
      *  loop cannot storm a slow peer with back-to-back refreshUpstream probes. */
@@ -323,108 +321,14 @@ export class DaemonCommandRouter {
         this.deps = deps;
     }
 
-    private cloneJsonValue<T>(value: T): T {
-        if (typeof structuredClone === 'function') return structuredClone(value);
-        return JSON.parse(JSON.stringify(value)) as T;
-    }
+    // ─── Aggregate mesh-status cache ────────────────────────────────────
+    // Implementation lives in ./router-aggregate-status.ts (behavior-preserving
+    // code move). Kept here as thin delegators: getCachedAggregateMeshStatus /
+    // rememberAggregateMeshStatus are bound into HighFamilyContext, so callers
+    // reach these via `self.` for correct instance dispatch.
 
     private hydrateCachedAggregateMeshStatusFromInline(snapshot: any, mesh: any, options?: { requireDirectPeerTruth?: boolean }): any {
-        if (!mesh || typeof mesh !== 'object' || !Array.isArray(mesh.nodes) || !Array.isArray(snapshot?.nodes)) return snapshot;
-        const inlineNodesById = new Map<string, any>();
-        for (const node of mesh.nodes) {
-            const nodeId = readInlineMeshNodeId(node);
-            if (nodeId) inlineNodesById.set(nodeId, node);
-        }
-        if (!inlineNodesById.size) return snapshot;
-
-        let changed = false;
-        const unavailableNodeIds = new Set<string>();
-        const sourceOfTruth = readObjectRecord(snapshot.sourceOfTruth);
-        const directPeerTruth = readObjectRecord(sourceOfTruth.directPeerTruth);
-        // Dead local worktree nodes (isLocalWorktree, workspace deleted from disk)
-        // carry no live truth and must never gate the aggregate as unavailable.
-        // A cached snapshot built before the worktree was removed can still list
-        // such a node in unavailableNodeIds, which would wedge the graph in a
-        // permanent direct_peer_truth_unavailable; drop them here so the held
-        // standing-state truth for the surviving nodes satisfies the aggregate.
-        const deadNodeIds = new Set<string>();
-        for (const node of mesh.nodes) {
-            if (!isDeadLocalWorktreeNode(node)) continue;
-            const deadId = readInlineMeshNodeId(node);
-            if (deadId) deadNodeIds.add(deadId);
-        }
-        let droppedDeadUnavailable = false;
-        for (const entry of Array.isArray(directPeerTruth.unavailableNodeIds) ? directPeerTruth.unavailableNodeIds : []) {
-            const nodeId = readStringValue(entry);
-            if (!nodeId) continue;
-            if (deadNodeIds.has(nodeId)) {
-                droppedDeadUnavailable = true;
-                continue;
-            }
-            unavailableNodeIds.add(nodeId);
-        }
-        // Force a rewrite when a dead worktree was filtered out of a previously
-        // built unavailable set, even if no live git was re-hydrated this pass —
-        // otherwise the early-return below would hand back the stale snapshot that
-        // still says direct_peer_truth_unavailable.
-        if (droppedDeadUnavailable) changed = true;
-
-        const nodes = snapshot.nodes.map((statusNode: any) => {
-            const nodeId = normalizeMeshNodeId(statusNode);
-            const inlineNode = nodeId ? inlineNodesById.get(nodeId) : undefined;
-            if (!inlineNode) return statusNode;
-            const liveGit = buildInlineMeshTransitGitStatus(inlineNode);
-            if (!liveGit) return statusNode;
-            const nextStatus = { ...statusNode };
-            nextStatus.git = liveGit;
-            nextStatus.health = deriveMeshNodeHealthFromGit(liveGit);
-            applyInlineMeshBranchConvergence(mesh, inlineNode, nextStatus);
-            nextStatus.launchReady = readBooleanValue(nextStatus.launchReady) ?? true;
-            const connection = readObjectRecord(nextStatus.connection);
-            const connectionState = readStringValue(connection.state);
-            const connectionReported = readBooleanValue(connection.reported) ?? false;
-            if (!connectionReported || connectionState === 'unknown') {
-                nextStatus.connection = buildLivePeerGitConnection(connection);
-            }
-            delete nextStatus.gitProbePending;
-            const error = readStringValue(nextStatus.error);
-            if (error && /pending_git|git probe|live peer git snapshot|no peer git snapshot/i.test(error)) delete nextStatus.error;
-            if (!readStringValue(nextStatus.machineStatus)) nextStatus.machineStatus = 'online';
-            if (nodeId) unavailableNodeIds.delete(nodeId);
-            changed = true;
-            return nextStatus;
-        });
-
-        const aggregateDirectTruthSatisfied = sourceOfTruth.coordinatorOwnsLiveTruth === true
-            || directPeerTruth.satisfied === true;
-        if (!changed && !(options?.requireDirectPeerTruth && unavailableNodeIds.size > 0 && !aggregateDirectTruthSatisfied)) return snapshot;
-        const nextSourceOfTruth = {
-            ...sourceOfTruth,
-            ...(Object.keys(directPeerTruth).length ? {
-                directPeerTruth: {
-                    ...directPeerTruth,
-                    satisfied: options?.requireDirectPeerTruth === true
-                        ? aggregateDirectTruthSatisfied || unavailableNodeIds.size === 0
-                        : directPeerTruth.satisfied,
-                    unavailableNodeIds: [...unavailableNodeIds],
-                },
-                ...(options?.requireDirectPeerTruth === true ? {
-                    coordinatorOwnsLiveTruth: aggregateDirectTruthSatisfied || unavailableNodeIds.size === 0,
-                    currentStatus: aggregateDirectTruthSatisfied || unavailableNodeIds.size === 0 ? 'live_git_and_session_probes' : 'direct_peer_truth_unavailable',
-                } : {}),
-            } : {}),
-        };
-        return {
-            ...snapshot,
-            ...(options?.requireDirectPeerTruth === true && unavailableNodeIds.size > 0 && !aggregateDirectTruthSatisfied ? {
-                success: false,
-                code: 'mesh_direct_peer_truth_unavailable',
-                error: 'Selected coordinator could not confirm direct mesh truth for every remote node yet.',
-            } : {}),
-            sourceOfTruth: nextSourceOfTruth,
-            branchConvergenceSummary: summarizeInlineMeshBranchConvergence(nodes),
-            nodes,
-        };
+        return hydrateCachedAggregateMeshStatusFromInline(this, snapshot, mesh, options);
     }
 
     private getCachedAggregateMeshStatus(
@@ -432,63 +336,11 @@ export class DaemonCommandRouter {
         mesh?: any,
         options?: { requireDirectPeerTruth?: boolean; allowStalePending?: boolean },
     ): any | null {
-        const cached = this.aggregateMeshStatusCache.get(meshId);
-        if (!cached?.snapshot || cached.snapshot.success !== true || !Array.isArray(cached.snapshot.nodes)) return null;
-        // Genuine invalidation still forces truth: a queue mutation bumps the
-        // revision, so a stale-revision snapshot is never served (even under the
-        // SWR allowStalePending path below).
-        if (cached.queueRevision !== getMeshQueueRevision(meshId)) return null;
-        let snapshot = this.cloneJsonValue(cached.snapshot);
-        snapshot = this.hydrateCachedAggregateMeshStatusFromInline(snapshot, mesh, options);
-        // SWR: allowStalePending lets the interactive detail-open serve a snapshot
-        // that still has pending peer-git nodes (would otherwise miss here) so the
-        // graph paints instantly; the caller fires a background freshen. The
-        // queueRevision guard above is NOT relaxed — only the pending-git freshness
-        // gate is, so a genuine queue/identity mutation still forces a live rebuild.
-        if (!options?.allowStalePending && shouldRefreshStalePendingAggregate(snapshot, options)) return null;
-        const ageMs = Math.max(0, Date.now() - cached.builtAt);
-        const sourceOfTruth = snapshot.sourceOfTruth && typeof snapshot.sourceOfTruth === 'object'
-            ? snapshot.sourceOfTruth
-            : {};
-        snapshot.sourceOfTruth = {
-            ...sourceOfTruth,
-            aggregateSnapshot: {
-                ...(sourceOfTruth.aggregateSnapshot && typeof sourceOfTruth.aggregateSnapshot === 'object'
-                    ? sourceOfTruth.aggregateSnapshot
-                    : {}),
-                owner: 'coordinator_daemon_memory',
-                cached: true,
-                source: 'memory',
-                refreshReason: 'memory_cache_hit',
-                ageMs,
-                cachedAt: new Date(cached.builtAt).toISOString(),
-                returnedAt: new Date().toISOString(),
-            },
-        };
-        return snapshot;
+        return getCachedAggregateMeshStatus(this, meshId, mesh, options);
     }
 
     private rememberAggregateMeshStatus(meshId: string, snapshot: any, refreshReason: string): any {
-        if (!snapshot || typeof snapshot !== 'object' || snapshot.success !== true || !Array.isArray(snapshot.nodes)) return snapshot;
-        const builtAt = Date.now();
-        const next = this.cloneJsonValue(snapshot);
-        const sourceOfTruth = next.sourceOfTruth && typeof next.sourceOfTruth === 'object'
-            ? next.sourceOfTruth
-            : {};
-        next.sourceOfTruth = {
-            ...sourceOfTruth,
-            aggregateSnapshot: {
-                owner: 'coordinator_daemon_memory',
-                cached: false,
-                source: 'live_refresh',
-                refreshReason,
-                ageMs: 0,
-                cachedAt: new Date(builtAt).toISOString(),
-                returnedAt: new Date(builtAt).toISOString(),
-            },
-        };
-        this.aggregateMeshStatusCache.set(meshId, { builtAt, snapshot: this.cloneJsonValue(next), queueRevision: getMeshQueueRevision(meshId) });
-        return next;
+        return rememberAggregateMeshStatus(this, meshId, snapshot, refreshReason);
     }
 
     public getCachedInlineMeshNodes(): any[] {
@@ -501,94 +353,14 @@ export class DaemonCommandRouter {
         return nodes;
     }
 
-    /**
-     * Resolve the REMOTE worker daemonId that owns a given session, when the session
-     * belongs to a mesh node hosted on a DIFFERENT daemon than this coordinator.
-     *
-     * The coordinator does not host remote-worker session instances in its own
-     * instanceManager/sessionRegistry — only their cached mesh-node metadata. A
-     * dashboard-issued session-scoped command (invoke_provider_script / resolve_action /
-     * set_mode / …) lands on the coordinator with a targetSessionId the coordinator can't
-     * find locally, and without forwarding it dies as "Live session not found". send_chat
-     * happens to survive (its target resolves to the worker by another route), but the
-     * controlbar commands do not — so the controlbar buttons appear to do nothing.
-     *
-     * Mirror the existing node-level remote-forward pattern (fast_forward_mesh_node etc.):
-     * scan the candidate mesh nodes for the one hosting the targetSessionId, and return its
-     * daemonId when that daemonId is a remote daemon (i.e. not this coordinator's own
-     * statusInstanceId). Returns undefined for a locally-hosted session (no forward — execute
-     * locally as before) or when ownership can't be resolved.
-     *
-     * The candidate set spans BOTH the cached inline-mesh nodes and the live aggregate
-     * mesh-status snapshots. The inline cache reliably carries only each node's single primary
-     * session (cachedStatus.activeSession), so a worker hosting more than one session exposes its
-     * non-primary sessions only on the aggregate snapshot nodes (status.activeSessions /
-     * activeSessionDetails, built from live session records). collectMeshNodeHostedSessionIds does
-     * the wider plural-shape scan so a controlbar/modal command targeting a non-primary remote
-     * session still resolves its owner — the singular readCachedInlineMeshActiveSessions semantics
-     * other consumers depend on stay untouched.
-     *
-     * CANCEL-STOP-RELAY: the session-id cache scan above only matches when the coordinator's
-     * cached status snapshot already lists the worker's session id in a recognized active-sessions
-     * shape. A worktree-clone worker session whose id form/timing differs from the cached snapshot
-     * (or is simply not yet reflected) misses the scan, so a stop that carries the authoritative
-     * owning nodeId (mesh_queue_cancel knows assignedNodeId) used to silently fail to forward.
-     * `ownerNodeIdHint` adds a deterministic fallback: when the session-id scan misses, resolve the
-     * owner daemonId by matching the node by id (meshNodeIdMatches — same form-tolerant compare the
-     * rest of the router uses, no new raw compare). The same self-loopback guard applies to both
-     * paths, so a coordinator-hosted node is still never force-forwarded to a remote form of itself.
-     */
-    public resolveRemoteMeshSessionOwnerDaemonId(sessionId: string, ownerNodeIdHint?: string): string | undefined {
-        const trimmed = typeof sessionId === 'string' ? sessionId.trim() : '';
-        const nodeHint = typeof ownerNodeIdHint === 'string' ? ownerNodeIdHint.trim() : '';
-        if (!trimmed && !nodeHint) return undefined;
-        const selfDaemonId = this.deps.statusInstanceId;
-        const candidates = this.collectMeshSessionOwnerCandidateNodes();
-        if (trimmed) {
-            for (const node of candidates) {
-                if (!collectMeshNodeHostedSessionIds(node).has(trimmed)) continue;
-                const nodeDaemonId = readMeshNodeDaemonId(readObjectRecord(node));
-                // A matching node with no readable daemonId can't be attributed — keep scanning
-                // the remaining candidates (e.g. the same session on an aggregate node that does
-                // carry the daemonId) rather than bailing on the whole resolution.
-                if (!nodeDaemonId) continue;
-                // Only forward to a genuinely remote daemon. When the owning node is this
-                // coordinator itself (locally hosted worker), fall through to local handling.
-                // id-form robust: the node daemonId and selfDaemonId may be stored in different
-                // forms of the same machine — a strict `===` would miss the self-match and forward
-                // a local session to a remote form of THIS daemon (loopback).
-                if (selfDaemonId && daemonIdsEquivalent(nodeDaemonId, selfDaemonId)) return undefined;
-                return nodeDaemonId;
-            }
-        }
-        // Deterministic fallback: the session-id scan missed (cache lag / id-form mismatch on a
-        // worktree-clone worker), but the caller knows the authoritative owning nodeId. Resolve the
-        // owner daemonId straight off that node — never the fuzzy session cache.
-        if (nodeHint) {
-            for (const node of candidates) {
-                if (!meshNodeIdMatches(node, nodeHint)) continue;
-                const nodeDaemonId = readMeshNodeDaemonId(readObjectRecord(node));
-                if (!nodeDaemonId) continue;
-                if (selfDaemonId && daemonIdsEquivalent(nodeDaemonId, selfDaemonId)) return undefined;
-                return nodeDaemonId;
-            }
-        }
-        return undefined;
-    }
+    // ─── Remote mesh-session owner resolution ───────────────────────────
+    // Implementation lives in ./router-mesh-session-owner.ts (behavior-preserving
+    // code move). resolveRemoteMeshSessionOwnerDaemonId stays public (the [Z]
+    // session-scoped forward in executeDaemonCommand and a unit test call it), so
+    // it's kept here as a thin delegator.
 
-    /**
-     * Candidate nodes for remote-session owner resolution: the cached inline-mesh nodes (which
-     * carry each node's primary session) plus the nodes from every cached aggregate mesh-status
-     * snapshot (which carry each node's full live session list). getCachedInlineMeshNodes()
-     * returns a fresh array, so appending the aggregate nodes never mutates cached state.
-     */
-    private collectMeshSessionOwnerCandidateNodes(): any[] {
-        const nodes: any[] = this.getCachedInlineMeshNodes();
-        for (const cached of this.aggregateMeshStatusCache.values()) {
-            const snapshotNodes = cached?.snapshot?.nodes;
-            if (Array.isArray(snapshotNodes)) nodes.push(...snapshotNodes);
-        }
-        return nodes;
+    public resolveRemoteMeshSessionOwnerDaemonId(sessionId: string, ownerNodeIdHint?: string): string | undefined {
+        return resolveRemoteMeshSessionOwnerDaemonId(this, sessionId, ownerNodeIdHint);
     }
 
     public getCachedInlineMesh(meshId: string, inlineMesh?: unknown): any | undefined {

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

@@ -134,8 +134,68 @@ function normalizeCoordinatorDaemonIds(
 //      SAME machine as the drainer (a coordinatorRunId change from a restart
 //      orphaned it): it is delivered to the current coordinator on that daemon.
 
-/** Observability counters for the accept-and-warn rollout. Read by tests and (later,
- *  B4) surfaced in mesh_status. Process-lifetime totals — never reset in production. */
+/**
+ * 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,
@@ -152,6 +212,14 @@ const meshV2DrainCounters = {
     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). */
@@ -271,23 +339,49 @@ function routeV2EventsForDrainer(
     },
 ): 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 → broadcast during rollout (existing policy).
+            // 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. (T6 enforce
-        // mode is where this becomes a quarantine.)
+        // 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`,

package/src/mesh/mesh-events.ts

@@ -13,6 +13,8 @@ export {
     clearPendingMeshCoordinatorEvents,
     serializeV2EnvelopeToWire,
     readV2EnvelopeFromWire,
+    getMeshV2DrainCounters,
+    isMeshProtocolV2EnforceEnabled,
 } from './mesh-events-pending.js';
 
 export {
@@ -24,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-reconcile-loop.ts

@@ -258,6 +258,59 @@ const inFlightAckedHoldState = new Map<string, AckedHoldState>();
 // A restart resets this set, so the first touch of each mesh reloads from disk.
 const rehydratedHoldMeshes = new Set<string>();
 
+// ─── T6 (B3c): PHASE-4 synthesis + acked-hold fast-track demoted to last-resort ──
+//
+// Under mesh-protocol-v2 enforce, the completion contract is explicit: a worker's
+// terminal emit is a v2 unicast event drained straight to the coordinator. The
+// PHASE-4 transcript-synthesis backstop and the acked-hold fast-track exist to
+// paper over a LOST emit — they should NEVER fire once v2 delivery is healthy. So
+// their firing is now a demoted last-resort signal: every fire bumps a counter, and
+// under enforce a fire additionally emits a WARN naming it a v2-contract violation
+// (a real emit was expected but never arrived). Target = 0 fires in steady state.
+//
+// The code is NOT removed — it stays as the correctness net for a genuinely lost
+// emit (rollout plan §B3c: "코드 삭제는 하지 않고 관측 후 다음 사이클에 판단"). Process-
+// lifetime totals; read by tests + surfaced in mesh_status.
+const meshV2BackstopCounters = {
+    /** PHASE-4 transcript synthesis actually reconciled a missing completion. */
+    phase4SynthesisFired: 0,
+    /** Acked-hold transcript fast-track promoted a synth ahead of the death deadline. */
+    ackedHoldFastTrackFired: 0,
+    /** Acked-hold death-deadline backstop released a held synth (the 8-min net). */
+    ackedHoldDeathDeadlineFired: 0,
+};
+
+/** Test/observability accessor for the v2 last-resort backstop counters (snapshot). */
+export function getMeshV2BackstopCounters(): Readonly<typeof meshV2BackstopCounters> {
+    return { ...meshV2BackstopCounters };
+}
+
+/** Test helper: zero the backstop counters so a case starts from a clean slate. */
+export function __resetMeshV2BackstopCountersForTests(): void {
+    for (const k of Object.keys(meshV2BackstopCounters) as Array<keyof typeof meshV2BackstopCounters>) {
+        meshV2BackstopCounters[k] = 0;
+    }
+}
+
+/** Enforce switch mirror (see isMeshProtocolV2EnforceEnabled in mesh-events-pending);
+ *  re-read here (not imported) to keep the reconcile loop free of a cross-file coupling
+ *  and to read env at fire time. Same truthy vocabulary. */
+function meshProtocolV2EnforceOn(): boolean {
+    const raw = process.env.MESH_PROTOCOL_V2_ENFORCE;
+    if (typeof raw !== 'string') return false;
+    const v = raw.trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'on' || v === 'yes';
+}
+
+/** Bump a backstop counter and, under enforce, WARN that a last-resort net fired —
+ *  which under a healthy v2 contract should not happen (the real emit was lost). */
+function recordBackstopFire(kind: keyof typeof meshV2BackstopCounters, detail: string): void {
+    meshV2BackstopCounters[kind]++;
+    if (meshProtocolV2EnforceOn()) {
+        LOG.warn('MeshReconcileV2', `v2 ENFORCE last-resort backstop fired (${kind}): ${detail}. Under a healthy v2 completion contract this should be 0 — a worker's real terminal emit was lost/late.`);
+    }
+}
+
 function inFlightSynthKey(meshId: string, taskId: string): string {
     return `${meshId}::${taskId}`;
 }
@@ -2011,6 +2064,12 @@ async function reconcileUnterminatedDirectDispatches(
 
         const synthKey = inFlightSynthKey(mesh.id, taskId);
         const isAcked = dispatch.status === 'acked';
+        // T6: which last-resort backstop (if any) drove this synth. Set when the
+        // acked-hold fast-track / death-deadline promotes the synth; the counter is
+        // bumped only if the synth actually COMMITS (result.reconciled), so a
+        // deferred/re-probed-away synth is not miscounted. A never-acked dispatch
+        // that reaches the commit is a plain PHASE-4 transcript synthesis.
+        let backstopKind: keyof ReturnType<typeof getMeshV2BackstopCounters> | undefined;
 
         // R4f: read the worker session. A FAILED read (transport error / success:false / no payload)
         // is no longer silently swallowed for an acked task — it is the liveness side of the
@@ -2130,6 +2189,7 @@ async function reconcileUnterminatedDirectDispatches(
                 const idleHeldMs = nowMs - idleSinceMs;
                 if (idleHeldMs >= fastTrackGraceMs) {
                     fastTrackReady = true;
+                    backstopKind = 'ackedHoldFastTrackFired';
                     LOG.info('MeshReconcile', `Acked-hold transcript fast-track: task ${taskId} on node ${nodeId} (mesh ${mesh.id}) read idle WITH a final assistant message for ${Math.round(idleHeldMs / 1000)}s continuous (grace ${Math.round(fastTrackGraceMs / 1000)}s) — promoting the synth ahead of the ${Math.round(deathDeadlineMs / 1000)}s death backstop; the worker's real emit was lost/late and a later one no-ops idempotently.`);
                 }
             } else if (holdState?.transcriptIdleSinceMs !== undefined) {
@@ -2144,6 +2204,7 @@ async function reconcileUnterminatedDirectDispatches(
                 continue;
             }
             if (!fastTrackReady) {
+                backstopKind = 'ackedHoldDeathDeadlineFired';
                 LOG.warn('MeshReconcile', `Acked-hold death deadline reached: task ${taskId} on node ${nodeId} (mesh ${mesh.id}) still idle ${Math.round(sinceAckMs / 1000)}s after the ack (deadline ${Math.round(deathDeadlineMs / 1000)}s) — synthesizing the missing completion as a notification-loss net (a real emit, if it ever lands, no-ops idempotently).`);
             }
         }
@@ -2221,6 +2282,11 @@ async function reconcileUnterminatedDirectDispatches(
                 source: 'daemon_reconcile_transcript_completion',
             });
             if (result.reconciled) {
+                // T6: this synth actually committed → count the last-resort backstop fire.
+                // An acked hold routes to the fast-track / death-deadline kind captured
+                // above; a never-acked dispatch is a plain PHASE-4 transcript synthesis.
+                // Under enforce, recordBackstopFire additionally WARNs (target = 0 fires).
+                recordBackstopFire(backstopKind ?? 'phase4SynthesisFired', `task ${taskId} on node ${nodeId} (mesh ${mesh.id}), kind=${result.kind}`);
                 LOG.info('MeshReconcile', `Synthesized missing completion (${result.kind}) for task ${taskId} on node ${nodeId} (mesh ${mesh.id})`);
             }
         } catch (e: any) {

package/src/providers/approval-utils.ts

@@ -16,7 +16,7 @@ const DEFAULT_APPROVAL_POSITIVE_HINTS = [
     'always allow',
 ];
 
-function normalizeApprovalLabel(value: string): string {
+export function normalizeApprovalLabel(value: string): string {
     return String(value || '')
         .toLowerCase()
         .replace(/^[\s\[(<{]*\d+(?:\s*[.)\]}>:-]|\s)+/, '')