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

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

@@ -138,15 +138,16 @@ function normalizeCoordinatorDaemonIds(
  * 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.
+ * routing is the only delivery path (there is no v1 broadcast fallback). On by
+ * default; set MESH_PROTOCOL_V2_ENFORCE=0/false/off/no to disable and restore 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.
+ * Per the rollout plan (§1 decision 4): enforce is `MESH_PROTOCOL_V2_ENFORCE` (env).
+ * Now that every node emits v2 (§배포 게이트 1 / risk §4), the code default is ON —
+ * a manual env injection is no longer required to get enforce behaviour. Rollback to
+ * accept mode is a pure-env step: set `MESH_PROTOCOL_V2_ENFORCE=0` (or `false`/`off`/
+ * `no`) — 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
@@ -159,9 +160,9 @@ function normalizeCoordinatorDaemonIds(
  */
 export function isMeshProtocolV2EnforceEnabled(): boolean {
     const raw = readNonEmptyString(process.env.MESH_PROTOCOL_V2_ENFORCE);
-    if (!raw) return false;
+    if (!raw) return true;                      // unset/blank = default ON
     const v = raw.trim().toLowerCase();
-    return v === '1' || v === 'true' || v === 'on' || v === 'yes';
+    return !(v === '0' || v === 'false' || v === 'off' || v === 'no');  // only explicit off = false
 }
 
 /**

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

@@ -294,12 +294,13 @@ export function __resetMeshV2BackstopCountersForTests(): void {
 
 /** 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. */
+ *  and to read env at fire time. On by default; set MESH_PROTOCOL_V2_ENFORCE=0/false/
+ *  off/no to disable. Same vocabulary as the source of truth. */
 function meshProtocolV2EnforceOn(): boolean {
     const raw = process.env.MESH_PROTOCOL_V2_ENFORCE;
-    if (typeof raw !== 'string') return false;
+    if (typeof raw !== 'string' || !raw.trim()) return true;   // unset/blank = default ON
     const v = raw.trim().toLowerCase();
-    return v === '1' || v === 'true' || v === 'on' || v === 'yes';
+    return !(v === '0' || v === 'false' || v === 'off' || v === 'no');
 }
 
 /** Bump a backstop counter and, under enforce, WARN that a last-resort net fired —

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

@@ -1517,6 +1517,22 @@ export class CliProviderInstance implements ProviderInstance {
         return probe;
     }
 
+    /**
+     * The spawned CLI's env overrides (e.g. the mesh coordinator points hermes
+     * at a per-coordinator HERMES_HOME so its state.db lives in a tmpdir instead
+     * of ~/.hermes). The native-history executor expands `${HERMES_HOME:-~/.hermes}`
+     * from this map, so the completion gate MUST pass it through — otherwise the
+     * gate reads ~/.hermes, finds no coordinator-session transcript, and
+     * false-fires missing_final_assistant on every coordinator turn.
+     */
+    private spawnedEnvOverrides(): Record<string, string> | undefined {
+        const meta = typeof (this.adapter as any)?.getRuntimeMetadata === 'function'
+            ? (this.adapter as any).getRuntimeMetadata()
+            : undefined;
+        const env = meta && typeof meta === 'object' ? (meta as Record<string, unknown>).spawnedEnv : undefined;
+        return env && typeof env === 'object' ? env as Record<string, string> : undefined;
+    }
+
     private readExternalCompletionMessages(): unknown[] | null {
         const adapterOwnsMessagesElsewhere = (this.adapter as any)?.chatMessagesOwnedExternally === true;
         if (!adapterOwnsMessagesElsewhere) return null;
@@ -1535,6 +1551,7 @@ export class CliProviderInstance implements ProviderInstance {
             historyBehavior: this.provider.historyBehavior,
             scripts: this.provider.scripts as any,
             sessionStartedAtMs: this.startedAt,
+            envOverrides: this.spawnedEnvOverrides(),
             forceRefresh: true,
         });
         if (restoredHistory.source !== 'provider-native') {

package/src/providers/native-history/hermes-cli-transcript.ts

@@ -69,7 +69,59 @@ function openDb(): any | null {
     }
 }
 
+/**
+ * Expand an anchor session id to every session id in its logical cluster.
+ *
+ * hermes ≥0.14 splits a SINGLE logical turn across several `sessions` rows
+ * linked by `parent_session_id` (a 0-message intermediate row is common), and
+ * the turn's final assistant message lands in a DIFFERENT row than the one the
+ * daemon pins. A bidirectional walk — up the parent chain to the cluster root,
+ * then down through every descendant — returns the complete set from ANY anchor
+ * (root, middle, or leaf), mirroring the declarative executor's
+ * `session_cluster_query`. Falls back to the anchor alone if the schema has no
+ * `parent_session_id` column (older hermes) or the walk fails.
+ */
+function resolveClusterSessionIds(db: any, anchorId: string): string[] {
+    if (!anchorId) return [];
+    try {
+        const rows: any[] = db.prepare(
+            `WITH RECURSIVE
+               up(id) AS (
+                 SELECT id FROM sessions WHERE id = ?
+                 UNION
+                 SELECT s.parent_session_id FROM sessions s JOIN up ON s.id = up.id
+                   WHERE s.parent_session_id IS NOT NULL
+               ),
+               cluster(id) AS (
+                 SELECT id FROM up
+                 UNION
+                 SELECT s.id FROM sessions s JOIN cluster ON s.parent_session_id = cluster.id
+               )
+             SELECT id FROM cluster`,
+        ).all(anchorId);
+        const ids = new Set<string>([anchorId]);
+        for (const r of rows) {
+            if (r && r.id != null && String(r.id)) ids.add(String(r.id));
+        }
+        return Array.from(ids);
+    } catch {
+        // No parent_session_id column (older hermes) or a walk failure — the
+        // single anchor is still a valid (degenerate) cluster.
+        return [anchorId];
+    }
+}
+
 function loadMessagesForSession(db: any, sessionId: string): NativeHistoryMessage[] {
+    // Read the WHOLE sub-session cluster, not just the pinned anchor. hermes
+    // ≥0.14 writes a turn's final assistant into a descendant sub-session row,
+    // so an anchor-only read misses it → read_chat shows zero assistant bubbles
+    // and the completion gate false-fires missing_final_assistant. Gather every
+    // cluster member (parent-chain walk) and merge; the SQL `ORDER BY timestamp`
+    // re-interleaves bubbles from different sub-sessions into true chronological
+    // order so the final assistant lands last.
+    const clusterIds = resolveClusterSessionIds(db, sessionId);
+    if (clusterIds.length === 0) return [];
+    const placeholders = clusterIds.map(() => '?').join(', ');
     // Assistant turns whose finish_reason='tool_calls' persist an EMPTY
     // `content` — their payload lives in the `tool_calls` column. Filtering on
     // `content != ''` alone drops those rows, so a turn whose terminal message
@@ -79,10 +131,10 @@ function loadMessagesForSession(db: any, sessionId: string): NativeHistoryMessag
     const rows: any[] = db.prepare(
         `SELECT id, role, COALESCE(NULLIF(content, ''), tool_calls) AS content, timestamp
          FROM messages
-         WHERE session_id = ?
+         WHERE session_id IN (${placeholders})
            AND ((content IS NOT NULL AND content != '') OR (tool_calls IS NOT NULL AND tool_calls != ''))
          ORDER BY timestamp ASC, id ASC`,
-    ).all(sessionId);
+    ).all(...clusterIds);
     const out: NativeHistoryMessage[] = [];
     for (const r of rows) {
         const role = normalizeHermesRole(r.role);

package/src/providers/spec/native-history-executor.ts

@@ -279,12 +279,53 @@ function executeSqlite(src: NativeHistorySqliteSource, input: NativeHistoryInput
         // this schema-agnostic and only rescues the mis-bound-id case: a genuine
         // discovered pin (codex/claude use jsonl sources and never reach here;
         // any real sqlite pin has rows) still short-circuits on its own rows.
-        const resolveMessagesFor = (sessionId: string): any[] | null => {
-            if (!sessionId) return null;
-            let rows: any[];
-            try { rows = db.prepare(src.message_query).all(sessionId); }
-            catch { return null; }
-            return rows && rows.length > 0 ? rows : null;
+        // Expand an anchor session id to every session id in its logical
+        // cluster. When the spec declares `session_cluster_query` the anchor is
+        // run through it (bound `?`) and each returned row's FIRST column is a
+        // cluster member id — typically a WITH RECURSIVE walk up to the cluster
+        // root and back down through all descendants, so passing a root, middle,
+        // or leaf anchor all resolve the same complete set. The anchor is always
+        // included even if the query omits it (defensive) so a spec with no
+        // cluster query, or a query that returns nothing, still reads the anchor
+        // itself. Absent query → just the anchor (single-session behaviour).
+        const resolveClusterIds = (anchorId: string): string[] => {
+            const ids = new Set<string>();
+            if (anchorId) ids.add(anchorId);
+            if (src.session_cluster_query && anchorId) {
+                try {
+                    const rows: any[] = db.prepare(src.session_cluster_query).all(anchorId);
+                    for (const row of rows) {
+                        const idRaw = Object.values(row)[0];
+                        if (idRaw != null && String(idRaw)) ids.add(String(idRaw));
+                    }
+                } catch { /* fall back to anchor-only on a malformed cluster query */ }
+            }
+            return Array.from(ids);
+        };
+
+        // Read messages for an anchor's WHOLE cluster, merged and re-sorted by
+        // their mapped timestamp so bubbles from different sub-sessions interleave
+        // in true chronological order (the turn's final assistant — written into a
+        // descendant sub-session in the split-turn case — lands last). No per-session
+        // short-circuit: an anchor whose OWN row has zero messages (hermes writes a
+        // 0-message intermediate `sessions` row) still yields the cluster's rows,
+        // and the whole cluster is scanned rather than stopping at the first
+        // non-empty session. Returns null only when the ENTIRE cluster is empty,
+        // preserving the pin-validation contract below (a pin that resolves no rows
+        // anywhere is a mis-bound id and falls through to newest-session recovery).
+        const resolveMessagesFor = (anchorId: string): any[] | null => {
+            if (!anchorId) return null;
+            const clusterIds = resolveClusterIds(anchorId);
+            const merged: any[] = [];
+            for (const id of clusterIds) {
+                let rows: any[];
+                try { rows = db.prepare(src.message_query).all(id); }
+                catch { continue; }
+                if (rows && rows.length > 0) merged.push(...rows);
+            }
+            if (merged.length === 0) return null;
+            if (clusterIds.length > 1) sortRowsByMappedTimestamp(merged, src.message_map);
+            return merged;
         };
 
         const resolveNewestSessionId = (): string => {
@@ -362,6 +403,32 @@ function executeSqlite(src: NativeHistorySqliteSource, input: NativeHistoryInput
     }
 }
 
+/**
+ * Stable-sort merged cluster rows by their mapped timestamp so bubbles read
+ * from different sub-sessions interleave in true chronological order. Uses the
+ * same `message_map.timestamp_ms` jsonpath + `parseTimestamp` heuristic the
+ * projection uses, so the sort key agrees with the receivedAt each row will be
+ * given. Rows with no resolvable timestamp keep their pre-sort relative order
+ * (stable), and equal timestamps preserve insertion order — both matter because
+ * a turn's terminal bubbles can share a sub-second timestamp.
+ */
+function sortRowsByMappedTimestamp(rows: any[], map: NativeHistoryMessageMap): void {
+    if (!map.timestamp_ms) return;
+    const keyed = rows.map((row, index) => {
+        const parsed = parseTimestamp(jsonPathGet(row, map.timestamp_ms as string));
+        return { row, index, ts: parsed == null ? Number.NaN : parsed };
+    });
+    keyed.sort((a, b) => {
+        const aHas = !Number.isNaN(a.ts);
+        const bHas = !Number.isNaN(b.ts);
+        if (aHas && bHas && a.ts !== b.ts) return a.ts - b.ts;
+        // Missing-timestamp rows and ties fall back to original insertion order
+        // so the sort stays stable.
+        return a.index - b.index;
+    });
+    for (let i = 0; i < keyed.length; i += 1) rows[i] = keyed[i].row;
+}
+
 // ────────────────────────────────────────────────────────────────────────────
 // Path expansion + globbing
 // ────────────────────────────────────────────────────────────────────────────

package/src/providers/spec/types.ts

@@ -103,6 +103,28 @@ export interface NativeHistorySqliteSource {
     path: string;
     session_query: string;
     message_query: string;
+    /**
+     * Optional sub-session cluster expansion. Some agents (hermes ≥0.14) split
+     * a SINGLE logical turn across several `sessions` rows linked by a parent
+     * pointer, and the turn's final assistant message lands in a DIFFERENT row
+     * than the one `session_query` / the daemon's pin resolves. Reading only
+     * the anchor session then surfaces zero (or stale) assistant bubbles even
+     * though the answer is physically present in a sibling/descendant row —
+     * `read_chat` returns no final assistant and the completion gate false-fires
+     * `missing_final_assistant`.
+     *
+     * When present, the executor treats the resolved session id as an ANCHOR
+     * and runs this query (bound `?` = anchor id) to expand it to every session
+     * id in the same logical cluster (typically a `WITH RECURSIVE` walk over the
+     * parent pointer, up to the root and back down through all descendants).
+     * `message_query` is then run once per cluster id and the rows merged and
+     * re-sorted by their mapped timestamp, so the turn's final assistant — in
+     * whichever sub-session it was written — is always included. Each returned
+     * row's first column is a cluster session id.
+     *
+     * Absent → single-session behaviour is unchanged (anchor session only).
+     */
+    session_cluster_query?: string;
     message_map: NativeHistoryMessageMap;
 }