granttap-mcp 0.8.84 → 0.8.86

package/apps/bridge/src/machine-load/mcp/scan-cost.ts

@@ -23,3 +23,13 @@ export function timedProviderScan<T extends { sessions: unknown[] }>(
   });
   return result;
 }
+
+/** Includes elapsed time across cooperative yields; selected capability is never usage. */
+export async function timedProviderScanAsync<T extends { sessions: unknown[] }>(
+  agent: string, scan: () => Promise<T>,
+): Promise<T> {
+  const startedAt = Date.now();
+  const result = await scan();
+  samples.set(agent, { durationMs: Date.now() - startedAt, sessions: result.sessions.length });
+  return result;
+}

package/apps/bridge/src/mesh/catalog/README.md

@@ -17,6 +17,16 @@ negative probes nor old repository identities persist across refreshes.
 Behavior tests: `tests/agentic/codex-workspace-binding.test.ts` and
 `tests/project/project-mesh-core.test.ts`.
 
+## Background Graph admission
+
+`inspectRepositoryAsync` provides the same repository facts without blocking
+relay callbacks. Native Git subprocesses are limited to two across the process.
+Concurrent inspections of the same path share their in-flight result; a later
+inspection verifies the checkout again. Missing Git facts remain unknown.
+
+Tests for asynchronous inspection live in `tests/`; Graph admission also has
+`runtime/graph/tests/responsiveness/checkout-inspection.test.ts`.
+
 ## License
 
 GrantTap Commercial Source License. See [LICENSE](../../../../../LICENSE).

package/apps/bridge/src/mesh/catalog/index.ts

@@ -19,6 +19,7 @@ import { readIntegrationMap } from "../observed/integration-map";
 import type { MeshStore } from "../store";
 import { queueProjectBindingSync } from "../../engine/runtime/engine-projects";
 import { isCursorTaskCloneId } from "../../sessions/cursor/catalog";
+export { inspectRepositoryAsync } from "./repository-inspection";
 
 export type RepositoryFacts = {
   root: string;

package/apps/bridge/src/mesh/catalog/repository-inspection.ts

@@ -0,0 +1,49 @@
+import { execFile } from "node:child_process";
+import { canonicalRepositoryIdentity, sanitizedRepositoryRemote } from "../identity";
+import type { RepositoryFacts } from ".";
+
+let running = 0;
+const waiting: Array<() => void> = [];
+const pending = new Map<string, Promise<RepositoryFacts>>();
+
+/** Native read-only Git work stays bounded without blocking relay callbacks. */
+function git(cwd: string, args: string[]): Promise<string | undefined> {
+  return new Promise(resolve => {
+    const run = () => {
+      running++;
+      const done = (error: Error | null, stdout = "") => {
+        running--;
+        waiting.shift()?.();
+        resolve(error ? undefined : stdout.trim() || undefined);
+      };
+      try {
+        execFile("git", ["-C", cwd, ...args], {
+          encoding: "utf8", timeout: 2_000, maxBuffer: 1024 * 1024, windowsHide: true,
+        }, done);
+      } catch { done(new Error("Repository command could not start")); }
+    };
+    if (running < 2) run(); else waiting.push(run);
+  });
+}
+
+async function inspect(cwd: string): Promise<RepositoryFacts> {
+  const worktree = await git(cwd, ["rev-parse", "--show-toplevel"]);
+  const root = worktree ?? cwd;
+  const [rawRemote, revision, branch] = await Promise.all([
+    git(root, ["remote", "get-url", "origin"]),
+    git(root, ["rev-parse", "HEAD"]),
+    git(root, ["symbolic-ref", "--quiet", "--short", "HEAD"]),
+  ]);
+  return { root, worktree, revision, branch,
+    baseRemote: rawRemote ? sanitizedRepositoryRemote(rawRemote) : undefined,
+    canonicalRepositoryId: canonicalRepositoryIdentity(rawRemote, root) };
+}
+
+/** Share only in-flight observations; a later refresh verifies the checkout again. */
+export function inspectRepositoryAsync(cwd: string): Promise<RepositoryFacts> {
+  const active = pending.get(cwd);
+  if (active) return active;
+  const next = inspect(cwd).finally(() => { pending.delete(cwd); });
+  pending.set(cwd, next);
+  return next;
+}

package/apps/bridge/src/mesh/runtime/graph/binding-sync.ts

@@ -1,7 +1,7 @@
 import { realpathSync } from "node:fs";
 import type { MeshSnapshot, ProjectRepositoryGraph } from "../../../../../../packages/protocol/schema";
 import { queueProjectBindingSync } from "../../../engine/runtime/engine-projects";
-import { inspectRepository } from "../../catalog";
+import { inspectRepositoryAsync, type RepositoryFacts } from "../../catalog";
 import { computerId } from "../../identity/computer";
 import { matchesLocalCheckout } from "./checkout-identity";
 
@@ -18,18 +18,18 @@ export async function refreshLocalGraphBindings(
   snapshot: MeshSnapshot,
   dependencies: {
     endpoint: () => string;
-    inspect: typeof inspectRepository;
+    inspect: (cwd: string) => RepositoryFacts | Promise<RepositoryFacts>;
     sync: typeof queueProjectBindingSync;
-  } = { endpoint: computerId, inspect: inspectRepository, sync: queueProjectBindingSync },
+  } = { endpoint: computerId, inspect: inspectRepositoryAsync, sync: queueProjectBindingSync },
 ): Promise<ProjectRepositoryGraph[]> {
   const localEndpoint = dependencies.endpoint();
   const candidates = (snapshot.bindings ?? []).filter((binding) =>
     binding.endpointId === localEndpoint && binding.available && binding.localPathHint);
   const failures: ProjectRepositoryGraph[] = [];
-  const checkouts = candidates.flatMap((binding) => {
-    const facts = readCheckout(dependencies.inspect, binding.localPathHint!);
+  const checkouts = (await Promise.all(candidates.map(async binding => {
+    const facts = await readCheckout(dependencies.inspect, binding.localPathHint!);
     return facts ? [{ binding, facts, real: realpathSync(facts.root) }] : [];
-  });
+  }))).flat();
   await Promise.all(checkouts.map(async ({ binding, facts, real }) => {
     const pathIdentity = matchesLocalCheckout(binding.repositoryId, facts.root);
     if (facts.canonicalRepositoryId !== binding.repositoryId && !pathIdentity) {
@@ -58,9 +58,9 @@ export async function refreshLocalGraphBindings(
 }
 
 /** A Git checkout rooted exactly at the bound path, or nothing a Graph can be built from. */
-function readCheckout(inspect: typeof inspectRepository, path: string) {
+async function readCheckout(inspect: (cwd: string) => RepositoryFacts | Promise<RepositoryFacts>, path: string) {
   try {
-    const facts = inspect(path);
+    const facts = await inspect(path);
     if (!facts.worktree || realpathSync(facts.root) !== realpathSync(path)) return undefined;
     return facts;
   } catch {

package/apps/bridge/src/monitor/capability-publication/README.md

@@ -0,0 +1,13 @@
+# Usage publication
+
+Public entry: `index.ts`. Complete capability totals are computed from the live
+catalog and full discovered history. This work has one independent in-flight
+publication per relay client. A slow history read or encrypted fan-out does not
+hold the current chat catalog. Successful reports retain their existing cadence;
+failures retry on a later catalog publication. Closing the monitor prevents
+further queued reads and sends. Counts and unknown usage semantics are unchanged.
+Concurrent catalog and Usage requests share one in-flight history read. The
+history cache's lifetime begins when that read completes.
+
+Behavior tests live in `tests/`.
+Licensed under the GrantTap Commercial Source License in the repository root.

package/apps/bridge/src/monitor/capability-publication/index.ts

@@ -0,0 +1,33 @@
+import { setImmediate } from "node:timers/promises";
+import type { RelayClient } from "../../../../../packages/core/relay-client";
+import type { SessionInfo, SessionsStatus } from "../../../../../packages/protocol/schema";
+import { scanCapabilityUsage, scopeCapabilityUsageToRoom } from "../../sessions";
+
+type Publication = { running: boolean; closed: boolean; lastPublishedAt: number };
+const publications = new WeakMap<RelayClient, Publication>();
+
+/** A slow usage fan-out never occupies the current chat catalog's publication slot. */
+export function publishMonitorCapabilities(client: RelayClient, status: SessionsStatus,
+  history: () => Promise<SessionInfo[]>): void {
+  const state = publications.get(client) ?? { running: false, closed: false, lastPublishedAt: 0 };
+  publications.set(client, state);
+  if (state.running || state.closed || Date.now() - state.lastPublishedAt < 30_000) return;
+  state.running = true;
+  const work = (async () => {
+    await setImmediate();
+    if (state.closed || !client.isConnected) return;
+    const older = await history();
+    if (state.closed || !client.isConnected) return;
+    const usage = scanCapabilityUsage([...status.sessions, ...older]);
+    await client.send(scopeCapabilityUsageToRoom(usage, client.room), "phone",
+      { ttlMs: 90_000, reliable: false });
+    state.lastPublishedAt = Date.now();
+  })();
+  void work.catch(() => {}).finally(() => { state.running = false; });
+}
+
+export function stopMonitorCapabilities(client: RelayClient): void {
+  const state = publications.get(client);
+  if (state) state.closed = true;
+  publications.delete(client);
+}

package/apps/bridge/src/monitor/support/runtime.ts

@@ -23,7 +23,7 @@ import { publishedCatalog, rememberPublishedCatalog, resumePublishedChats,
   publishCatalogHeads, stopCatalogHeads } from "../../session-catalog";
 import { createMachineLoadPublisher } from "../../machine-load";
 import { startMachineLoadLoop } from "../../machine-load/host/loop";
-import { scanCapabilityUsage, scanSessionHistory, scanSessions, scopeCapabilityUsageToRoom, TOKEN_WINDOW_HOURS } from "../../sessions";
+import { scanSessionHistoryCooperatively, scanSessionsCooperatively, TOKEN_WINDOW_HOURS } from "../../sessions";
 import { boundedCatalogHistory, INTERVAL_MS, publishSessionEvents } from "../handlers/catalog";
 import { sweepAttachments } from "../handlers/receipts";
 import { handleMonitorMessage } from "../handlers/inbound";
@@ -32,6 +32,7 @@ import { decorateTaskOriginCatalog } from '../../task-origins';
 const HISTORY_INTERVAL_MS = 60_000;
 const resumedHeads = new WeakSet<RelayClient>();
 import { publishMonitorMeshes, stopMonitorMeshes } from "../mesh-publication";
+import { publishMonitorCapabilities, stopMonitorCapabilities } from "../capability-publication";
 
 export type SessionMonitor = {
   publish: () => Promise<void>;
@@ -71,23 +72,23 @@ function decorateSessions(
   });
 }
 
-function monitorSnapshot(input: {
+async function monitorSnapshot(input: {
   includeHistory: boolean;
   forceHistory: boolean;
   subscriptions: Set<string>;
-  history: (force?: boolean) => SessionsStatus["sessions"];
-}): SessionsStatus {
+  history: (force?: boolean) => Promise<SessionsStatus["sessions"]>;
+}): Promise<SessionsStatus> {
   const { includeHistory, forceHistory, subscriptions, history } = input;
   sweepAttachments();
   if (loadRuntimeConfig().meshEnabled) localMeshStore().flush();
-  const { sessions, tokensRecent } = scanSessions();
+  const { sessions, tokensRecent } = await scanSessionsCooperatively();
   const runtime = loadRuntimeConfig();
   return {
     type: "sessions.status",
     machine: computerDisplayName(),
     sessions: decorateSessions(sessions, subscriptions),
     history: includeHistory
-      ? decorateSessions(boundedCatalogHistory(history(forceHistory), subscriptions), subscriptions)
+      ? decorateSessions(boundedCatalogHistory(await history(forceHistory), subscriptions), subscriptions)
       : undefined,
     tokensRecent,
     tokenWindowHours: TOKEN_WINDOW_HOURS,
@@ -113,21 +114,24 @@ async function publishMonitorTick(input: {
   client: RelayClient;
   leadership: ReturnType<typeof monitorLeadership>;
   subscriptions: Set<string>;
-  history: (force?: boolean) => SessionsStatus["sessions"];
-  clocks: { lastHistoryPublishedAt: number; lastCapabilityPublishedAt: number };
+  history: (force?: boolean) => Promise<SessionsStatus["sessions"]>;
+  clocks: { lastHistoryPublishedAt: number };
   loadLoop: { updateStatus: (status: SessionsStatus) => void };
   forceHistory: boolean;
-}): Promise<{ lastHistoryPublishedAt: number; lastCapabilityPublishedAt: number }> {
+  active: () => boolean;
+}): Promise<{ lastHistoryPublishedAt: number }> {
   const { client, leadership, subscriptions, history, clocks, loadLoop, forceHistory } = input;
-  let { lastHistoryPublishedAt, lastCapabilityPublishedAt } = clocks;
-  if (!client.isConnected) return { lastHistoryPublishedAt, lastCapabilityPublishedAt };
+  let { lastHistoryPublishedAt } = clocks;
+  if (!client.isConnected) return { lastHistoryPublishedAt };
   await publishHeartbeat(client).catch(() => {});
-  if (!leadership.acquire()) return { lastHistoryPublishedAt, lastCapabilityPublishedAt };
+  if (!input.active()) return { lastHistoryPublishedAt };
+  if (!leadership.acquire()) return { lastHistoryPublishedAt };
   await client.send(approvalsStatus(), "phone", { ttlMs: INTERVAL_MS * 3, reliable: false });
   const initial = lastHistoryPublishedAt === 0;
   const includeHistory = forceHistory || (!initial && Date.now() - lastHistoryPublishedAt >= HISTORY_INTERVAL_MS);
-  const status = decorateTaskOriginCatalog(
-    monitorSnapshot({ includeHistory, forceHistory, subscriptions, history }), client.room);
+  const snapshot = await monitorSnapshot({ includeHistory, forceHistory, subscriptions, history });
+  if (!input.active()) return { lastHistoryPublishedAt };
+  const status = decorateTaskOriginCatalog(snapshot, client.room);
   rememberPublishedCatalog(client, status);
   await client.send(status, "phone", { ttlMs: INTERVAL_MS * 24, reliable: false });
   if (initial && !resumedHeads.has(client)) {
@@ -143,15 +147,8 @@ async function publishMonitorTick(input: {
   void refreshMcpLoad(status.sessions).catch(() => {});
   publishCatalogHeads(client, status, subscriptions, publishSessionEvents);
   if (loadRuntimeConfig().meshEnabled) publishMonitorMeshes(client, status);
-  if (Date.now() - lastCapabilityPublishedAt >= 30_000) {
-    const usage = scanCapabilityUsage([
-      ...status.sessions,
-      ...history(false),
-    ]);
-    await client.send(scopeCapabilityUsageToRoom(usage, client.room), "phone", { ttlMs: 90_000, reliable: false });
-    lastCapabilityPublishedAt = Date.now();
-  }
-  return { lastHistoryPublishedAt, lastCapabilityPublishedAt };
+  publishMonitorCapabilities(client, status, () => history(false));
+  return { lastHistoryPublishedAt };
 }
 
 /**
@@ -165,8 +162,9 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
   primeSessionKeys(client);
   publishedCatalog(client);
   let historyCache: { generatedAt: number; sessions: SessionsStatus["sessions"] } | undefined;
+  let historyRead: Promise<SessionsStatus["sessions"]> | undefined;
   let lastHistoryPublishedAt = 0;
-  let lastCapabilityPublishedAt = 0;
+  let closed = false;
   const publishMachineLoad = createMachineLoadPublisher({
     log: (line) => process.stderr.write(`[monitor] ${line}\n`),
   });
@@ -185,20 +183,26 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
     },
   });
 
-  const history = (force = false): SessionsStatus["sessions"] => {
-    if (force || !historyCache || Date.now() - historyCache.generatedAt > 60_000) {
-      historyCache = { generatedAt: Date.now(), sessions: scanSessionHistory() };
+  const history = (force = false): Promise<SessionsStatus["sessions"]> => {
+    if (historyRead) return historyRead;
+    if (!force && historyCache && Date.now() - historyCache.generatedAt <= 60_000) {
+      return Promise.resolve(historyCache.sessions);
     }
-    return historyCache.sessions;
+    historyRead = scanSessionHistoryCooperatively().then(sessions => {
+      historyCache = { generatedAt: Date.now(), sessions };
+      return sessions;
+    }).finally(() => { historyRead = undefined; });
+    return historyRead;
   };
 
   const publish = singleFlightPublisher(async (forceHistory: boolean): Promise<void> => {
+    if (closed) return;
     const next = await publishMonitorTick({
       client, leadership, subscriptions, history, loadLoop, forceHistory,
-      clocks: { lastHistoryPublishedAt, lastCapabilityPublishedAt },
+      active: () => !closed,
+      clocks: { lastHistoryPublishedAt },
     });
     lastHistoryPublishedAt = next.lastHistoryPublishedAt;
-    lastCapabilityPublishedAt = next.lastCapabilityPublishedAt;
   });
 
   const off = client.onMessage(async (payload: Payload, peerPublicKey) => {
@@ -213,6 +217,8 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
     return handleMonitorMessage(client, payload, { leadership, subscriptions, publish, peerPublicKey });
   });
 
+  const offConnected = client.onConnected?.(() => publish().catch(() => {}));
+
   const stopCatalog = startPublishLoop({
     connected: () => client.isConnected,
     intervalMs: INTERVAL_MS,
@@ -233,8 +239,11 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
     publish: () => publish(false),
     isLeader: () => leadership.acquire(),
     close: () => {
+      closed = true;
+      offConnected?.();
       stopCatalog();
       stopCatalogHeads(client);
+      stopMonitorCapabilities(client);
       stopMonitorMeshes(client);
       stopHeartbeat();
       loadLoop.stop();

package/apps/bridge/src/session-catalog/README.md

@@ -18,8 +18,16 @@ Tests live in `tests/`. This runtime module uses the repository GrantTap Commerc
 
 Engine binding recovery waits for the first connected catalog publication before projecting repository graphs. A cold Engine cannot hold the initial relay handshake behind restored Mesh analysis.
 
-Codex discovery shares repeated checkout verification only within one synchronous scan. The next scan verifies repository identity again; no long-lived checkout cache can cross a repository change. This keeps startup catalog delivery ahead of repeated Git subprocesses.
+Codex and Claude discovery share repeated checkout verification only within one scan. The next scan verifies repository identity again; no long-lived checkout cache can cross a repository change. This keeps startup catalog delivery ahead of repeated Git subprocesses.
 
 Subscribed transcript heads use a separate, single-flight transfer loop. A stalled head never occupies the current catalog publication slot; stopping the monitor cancels further queued reads. The iPhone keeps its historical backfill independent of both loops.
 
 Authenticated subscription and transcript requests pass the verified requester key to the encrypted reply. A requested page does not wait for copies addressed to other paired controllers. Shared catalogue and chat updates remain available to passive controllers.
+
+Periodic native discovery yields between small timed batches of source files.
+Warm metadata-cache hits share a batch instead of waiting behind one background
+Project projection for every unchanged file. The same provider parsers
+and metadata caches serve synchronous CLI readers and cooperative live-monitor
+readers. Checkout observations are scoped to one asynchronous scan, so unrelated
+requests cannot inherit an old directory result. Socket recovery immediately
+republishes the current catalog instead of waiting for the next periodic tick.

package/apps/bridge/src/sessions/README.md

@@ -3,6 +3,11 @@
 Public entry: `index.ts`. Provider readers discover local executions and keep
 their native source identity for explicit chat and nested-conversation requests.
 `session-activity.ts` owns provider selection and bounded child replies.
+`catalog.ts` owns provider selection and bounded live/history catalogs. The
+monitor uses cooperative Codex and Claude readers, yielding between timed batches
+so discovery cannot monopolize relay callbacks. Synchronous CLI readers use the
+same parsers. Published native bindings stay readable until a complete scan
+replaces them; checkout verification caches belong to one scan across its yields.
 
 Claude child reads use only the requested owned log and its bounded recent
 window. Native `agentId` remains authoritative when it differs from the filename;

package/apps/bridge/src/sessions/catalog.ts

@@ -0,0 +1,155 @@
+import type { SessionInfo } from "../../../../packages/protocol/schema";
+import { localTaskTransfers, localTransferContinuations } from "../task-transfer";
+import { loadRuntimeConfig } from "../config";
+import { timedProviderScan, timedProviderScanAsync } from "../machine-load/mcp/scan-cost";
+import { scanClaude, scanClaudeCooperatively } from "./scan/claude";
+import { scanCodex, scanCodexCooperatively } from "./scan/codex";
+import { scanCursor } from "./cursor";
+import { scanGrok } from "./scan/grok";
+import { MAX_FILES, MAX_HISTORY, MAX_LIVE, TOKEN_WINDOW_MS } from "./support/common";
+import { setImmediate } from "node:timers/promises";
+
+type ProviderScan = ReturnType<typeof scanClaude>;
+
+function sessionKey(session: SessionInfo): string {
+  return `${session.agent}\0${session.sessionId}`;
+}
+
+function emptyScan(): ProviderScan {
+  return { sessions: [], tokensRecent: 0 };
+}
+
+/**
+ * Explicit provider roots isolate fixtures and diagnostics from real user logs.
+ * In normal operation (no overrides) every installed provider is scanned.
+ */
+function providerReaders(maxFiles: number) {
+  const enabled = loadRuntimeConfig().providerSettings;
+  const explicit = {
+    claude: Boolean(process.env.GRANTTAP_CLAUDE_PROJECTS_DIR || process.env.NODVOX_CLAUDE_PROJECTS_DIR),
+    codex: Boolean(process.env.GRANTTAP_CODEX_SESSIONS_DIR || process.env.NODVOX_CODEX_SESSIONS_DIR),
+    cursor: Boolean(process.env.GRANTTAP_CURSOR_TRANSCRIPTS_DIR || process.env.GRANTTAP_CURSOR_STATE_DB),
+    grok: Boolean(process.env.GRANTTAP_GROK_SESSIONS_DIR || process.env.GROK_HOME),
+  };
+  const isolated = Object.values(explicit).some(Boolean);
+  const cooperative = { claude: scanClaudeCooperatively, codex: scanCodexCooperatively,
+    cursor: async (limit: number) => scanCursor(limit), grok: async (limit: number) => scanGrok(limit) };
+  return Object.entries({ claude: scanClaude, codex: scanCodex, cursor: scanCursor, grok: scanGrok })
+    .map(([agent, read]) => {
+      const key = agent as keyof typeof explicit;
+      return { agent, read: () => read(maxFiles), cooperative: () => cooperative[key](maxFiles),
+        enabled: enabled[key] && (!isolated || explicit[key]) };
+    });
+}
+
+function providerScans(maxFiles = MAX_FILES): ProviderScan[] {
+  return providerReaders(maxFiles).map(reader => reader.enabled
+    ? timedProviderScan(reader.agent, reader.read) : emptyScan());
+}
+
+async function cooperativeProviderScans(maxFiles = MAX_FILES): Promise<ProviderScan[]> {
+  const scans: ProviderScan[] = [];
+  for (const reader of providerReaders(maxFiles)) {
+    await setImmediate();
+    scans.push(reader.enabled ? await timedProviderScanAsync(reader.agent, reader.cooperative) : emptyScan());
+  }
+  return scans;
+}
+
+function sortedUniqueSessions(scans: ProviderScan[]): SessionInfo[] {
+  const merged = new Map<string, SessionInfo>();
+  for (const session of scans.flatMap((scan) => scan.sessions)) {
+    const key = sessionKey(session);
+    const previous = merged.get(key);
+    if (!previous || session.lastActivityAt >= previous.lastActivityAt) {
+      merged.set(key, session);
+    }
+  }
+  const rank = { working: 0, waiting: 1, idle: 2 } as const;
+  return [...merged.values()].sort((a, b) =>
+    rank[a.state] - rank[b.state] || b.lastActivityAt - a.lastActivityAt
+  );
+}
+
+/** Preserve provider diversity when one agent has hundreds of recent logs. */
+function pickWithReserve(
+  candidates: SessionInfo[],
+  limit: number,
+  reservePerAgent: number,
+): SessionInfo[] {
+  if (candidates.length <= limit) return candidates;
+  const picked = new Map<string, SessionInfo>();
+  const agents = [...new Set(candidates.map((session) => session.agent))];
+  for (const agent of agents) {
+    for (const session of candidates.filter((item) => item.agent === agent).slice(0, reservePerAgent)) {
+      if (picked.size >= limit) break;
+      picked.set(sessionKey(session), session);
+    }
+  }
+  for (const session of candidates) {
+    if (picked.size >= limit) break;
+    picked.set(sessionKey(session), session);
+  }
+  const order = new Map(candidates.map((session, index) => [sessionKey(session), index]));
+  return [...picked.values()].sort(
+    (a, b) => (order.get(sessionKey(a)) ?? 0) - (order.get(sessionKey(b)) ?? 0),
+  );
+}
+
+function catalogFromScans(scans: ProviderScan[]) {
+  return {
+    all: localTaskTransfers().catalog(sortedUniqueSessions(scans)).map(session => ({ ...session,
+      transfer: localTransferContinuations().notice(session.sessionId) })),
+    tokensRecent: scans.reduce((sum, scan) => sum + scan.tokensRecent, 0),
+    sourceLimited: scans.some((scan) => scan.sourceLimited === true),
+  };
+}
+
+function scanCatalog(maxFiles = MAX_FILES) {
+  return catalogFromScans(providerScans(maxFiles));
+}
+
+export async function scanSessionsCooperatively() {
+  return liveCatalog(catalogFromScans(await cooperativeProviderScans()));
+}
+
+export async function scanSessionHistoryCooperatively(): Promise<SessionInfo[]> {
+  return historyCatalog(catalogFromScans(await cooperativeProviderScans()).all);
+}
+
+export function scanSessions(): { sessions: SessionInfo[]; tokensRecent: number } {
+  return liveCatalog(scanCatalog());
+}
+
+function liveCatalog({ all, tokensRecent }: { all: SessionInfo[]; tokensRecent: number }) {
+  const live = all.filter((session) =>
+    session.state !== "idle" || Date.now() - session.lastActivityAt <= TOKEN_WINDOW_MS
+  );
+  return {
+    sessions: pickWithReserve(live, MAX_LIVE, 10),
+    tokensRecent,
+  };
+}
+
+/** Bounded local history. Nested provider threads stay metadata on their parent. */
+export function scanSessionHistory(): SessionInfo[] {
+  return historyCatalog(scanCatalog().all);
+}
+
+function historyCatalog(sessions: SessionInfo[]): SessionInfo[] {
+  return pickWithReserve(sessions, Math.min(MAX_HISTORY, 200), 40);
+}
+
+/** The UI asks for older catalog rows only when its History list reaches the end. */
+export function scanSessionHistoryForPaging(maxFiles = MAX_FILES): { sessions: SessionInfo[]; sourceLimited: boolean } {
+  const scan = scanCatalog(maxFiles);
+  return {
+    sessions: scan.all.sort((left, right) =>
+      right.lastActivityAt - left.lastActivityAt
+      || left.agent.localeCompare(right.agent)
+      || left.sessionId.localeCompare(right.sessionId)
+    ),
+    sourceLimited: scan.sourceLimited,
+  };
+}
+

package/apps/bridge/src/sessions/cooperative-scan.ts

@@ -0,0 +1,21 @@
+import { setImmediate } from "node:timers/promises";
+import { performance } from "node:perf_hooks";
+
+/** Shared provider readers preserve the same result for CLI and live transport callers. */
+export function finishScan<T>(scan: Generator<void, T>): T {
+  let step = scan.next();
+  while (!step.done) step = scan.next();
+  return step.value;
+}
+
+/** Let relay input, pongs, decisions and timers run between native files. */
+export async function finishScanCooperatively<T>(scan: Generator<void, T>): Promise<T> {
+  for (;;) {
+    await setImmediate();
+    const deadline = performance.now() + 8;
+    do {
+      const step = scan.next();
+      if (step.done) return step.value;
+    } while (performance.now() < deadline);
+  }
+}

package/apps/bridge/src/sessions/index.ts

@@ -5,7 +5,6 @@
  * observations beside their session summary. Activity and telemetry therefore
  * do not trigger a second filesystem walk during the monitor publish cycle.
  */
-import { localTaskTransfers, localTransferContinuations } from "../task-transfer";
 import { recentProjectDecisions } from "../policy/decision-log";
 import type {
   ActivityEntry,
@@ -19,25 +18,18 @@ import {
   MAX_ACTIVITY_TEXT,
 } from "./support/activity-helpers";
 import {
-  MAX_HISTORY,
-  MAX_FILES,
-  MAX_LIVE,
   TOKEN_WINDOW_HOURS,
-  TOKEN_WINDOW_MS,
 } from "./support/common";
 import {
   claudeCapabilityUsage,
-  scanClaude,
 } from "./scan/claude";
 import {
   codexCapabilityUsage,
-  scanCodex,
 } from "./scan/codex";
 import {
   cursorCapabilityUsage,
-  scanCursor,
 } from "./cursor";
-import { grokCapabilityUsage, scanGrok } from "./scan/grok";
+import { grokCapabilityUsage } from "./scan/grok";
 import { activityForSession } from './session-activity';
 export { MAX_THREAD_ENTRIES, scanThreadActivity } from './session-activity';
 import {
@@ -46,125 +38,13 @@ import {
   toRemoteCapabilityUsageEvent,
 } from "./telemetry";
 import { createCapabilityTotals } from "./support/capability-totals";
-import { loadRuntimeConfig } from "../config";
-import { timedProviderScan } from "../machine-load/mcp/scan-cost";
 
 export { MAX_ACTIVITY_ENTRIES, MAX_ACTIVITY_TEXT, TOKEN_WINDOW_HOURS };
 export { nativeTranscriptRoots, nativeTranscriptSource, restoreNativeTranscriptSource } from "./native-source";
 
-type ProviderScan = ReturnType<typeof scanClaude>;
-
-function sessionKey(session: SessionInfo): string {
-  return `${session.agent}\0${session.sessionId}`;
-}
-
-function emptyScan(): ProviderScan {
-  return { sessions: [], tokensRecent: 0 };
-}
-
-/**
- * Explicit provider roots isolate fixtures and diagnostics from real user logs.
- * In normal operation (no overrides) every installed provider is scanned.
- */
-function providerScans(maxFiles = MAX_FILES): ProviderScan[] {
-  const enabled = loadRuntimeConfig().providerSettings;
-  const explicit = {
-    claude: Boolean(process.env.GRANTTAP_CLAUDE_PROJECTS_DIR || process.env.NODVOX_CLAUDE_PROJECTS_DIR),
-    codex: Boolean(process.env.GRANTTAP_CODEX_SESSIONS_DIR || process.env.NODVOX_CODEX_SESSIONS_DIR),
-    cursor: Boolean(process.env.GRANTTAP_CURSOR_TRANSCRIPTS_DIR || process.env.GRANTTAP_CURSOR_STATE_DB),
-    grok: Boolean(process.env.GRANTTAP_GROK_SESSIONS_DIR || process.env.GROK_HOME),
-  };
-  const isolated = Object.values(explicit).some(Boolean);
-  return [
-    enabled.claude && (!isolated || explicit.claude)
-      ? timedProviderScan("claude", () => scanClaude(maxFiles)) : emptyScan(),
-    enabled.codex && (!isolated || explicit.codex)
-      ? timedProviderScan("codex", () => scanCodex(maxFiles)) : emptyScan(),
-    enabled.cursor && (!isolated || explicit.cursor)
-      ? timedProviderScan("cursor", () => scanCursor(maxFiles)) : emptyScan(),
-    enabled.grok && (!isolated || explicit.grok)
-      ? timedProviderScan("grok", () => scanGrok(maxFiles)) : emptyScan(),
-  ];
-}
-
-function sortedUniqueSessions(scans: ProviderScan[]): SessionInfo[] {
-  const merged = new Map<string, SessionInfo>();
-  for (const session of scans.flatMap((scan) => scan.sessions)) {
-    const key = sessionKey(session);
-    const previous = merged.get(key);
-    if (!previous || session.lastActivityAt >= previous.lastActivityAt) {
-      merged.set(key, session);
-    }
-  }
-  const rank = { working: 0, waiting: 1, idle: 2 } as const;
-  return [...merged.values()].sort((a, b) =>
-    rank[a.state] - rank[b.state] || b.lastActivityAt - a.lastActivityAt
-  );
-}
-
-/** Preserve provider diversity when one agent has hundreds of recent logs. */
-function pickWithReserve(
-  candidates: SessionInfo[],
-  limit: number,
-  reservePerAgent: number,
-): SessionInfo[] {
-  if (candidates.length <= limit) return candidates;
-  const picked = new Map<string, SessionInfo>();
-  const agents = [...new Set(candidates.map((session) => session.agent))];
-  for (const agent of agents) {
-    for (const session of candidates.filter((item) => item.agent === agent).slice(0, reservePerAgent)) {
-      if (picked.size >= limit) break;
-      picked.set(sessionKey(session), session);
-    }
-  }
-  for (const session of candidates) {
-    if (picked.size >= limit) break;
-    picked.set(sessionKey(session), session);
-  }
-  const order = new Map(candidates.map((session, index) => [sessionKey(session), index]));
-  return [...picked.values()].sort(
-    (a, b) => (order.get(sessionKey(a)) ?? 0) - (order.get(sessionKey(b)) ?? 0),
-  );
-}
-
-function scanCatalog(maxFiles = MAX_FILES): { all: SessionInfo[]; tokensRecent: number; sourceLimited: boolean } {
-  const scans = providerScans(maxFiles);
-  return {
-    all: localTaskTransfers().catalog(sortedUniqueSessions(scans)).map(session => ({ ...session,
-      transfer: localTransferContinuations().notice(session.sessionId) })),
-    tokensRecent: scans.reduce((sum, scan) => sum + scan.tokensRecent, 0),
-    sourceLimited: scans.some((scan) => scan.sourceLimited === true),
-  };
-}
-
-export function scanSessions(): { sessions: SessionInfo[]; tokensRecent: number } {
-  const { all, tokensRecent } = scanCatalog();
-  const live = all.filter((session) =>
-    session.state !== "idle" || Date.now() - session.lastActivityAt <= TOKEN_WINDOW_MS
-  );
-  return {
-    sessions: pickWithReserve(live, MAX_LIVE, 10),
-    tokensRecent,
-  };
-}
-
-/** Bounded local history. Nested provider threads stay metadata on their parent. */
-export function scanSessionHistory(): SessionInfo[] {
-  return pickWithReserve(scanCatalog().all, Math.min(MAX_HISTORY, 200), 40);
-}
-
-/** The UI asks for older catalog rows only when its History list reaches the end. */
-export function scanSessionHistoryForPaging(maxFiles = MAX_FILES): { sessions: SessionInfo[]; sourceLimited: boolean } {
-  const scan = scanCatalog(maxFiles);
-  return {
-    sessions: scan.all.sort((left, right) =>
-      right.lastActivityAt - left.lastActivityAt
-      || left.agent.localeCompare(right.agent)
-      || left.sessionId.localeCompare(right.sessionId)
-    ),
-    sourceLimited: scan.sourceLimited,
-  };
-}
+export { scanSessions, scanSessionHistory, scanSessionHistoryForPaging,
+  scanSessionsCooperatively, scanSessionHistoryCooperatively } from "./catalog";
+import { scanSessions, scanSessionHistory } from "./catalog";
 
 /**
  * Keep the person's chat first. Newest child rows used to fill the whole

package/apps/bridge/src/sessions/scan/claude/scan.ts

@@ -1,3 +1,5 @@
+import { finishScan, finishScanCooperatively } from "../../cooperative-scan";
+import { withCheckoutObservationCache } from "../../support/repository-checkout";
 import {
   claudeChildLogPathsBySession,
   claudeLogPathBySession,
@@ -8,6 +10,14 @@ import { recentLogs, claudeProjectsRoot, MAX_FILES, TOKEN_WINDOW_MS, type Scan }
 import type { SessionInfo } from "../../../../../../packages/protocol/schema";
 
 export function scanClaude(maxFiles = MAX_FILES): Scan {
+  return withCheckoutObservationCache(() => finishScan(scanClaudeCatalog(maxFiles)));
+}
+
+export function scanClaudeCooperatively(maxFiles = MAX_FILES): Promise<Scan> {
+  return withCheckoutObservationCache(() => finishScanCooperatively(scanClaudeCatalog(maxFiles)));
+}
+
+function* scanClaudeCatalog(maxFiles: number): Generator<void, Scan> {
   const root = claudeProjectsRoot();
   const sessions: SessionInfo[] = [];
   let tokensRecent = 0;
@@ -15,15 +25,14 @@ export function scanClaude(maxFiles = MAX_FILES): Scan {
   const files = listed.slice(0, maxFiles);
   const activeFiles = new Set(files);
   const seenSessionIds = new Set<string>();
-  claudeLogPathBySession.clear();
-  claudeChildLogPathsBySession.clear();
+  const sources: Array<{ sessionId: string; file: string; childPaths: string[] }> = [];
 
   for (const file of files) {
+    yield;
     const parsed = parseClaudeFile(file);
     if (!parsed || seenSessionIds.has(parsed.session.sessionId)) continue;
     seenSessionIds.add(parsed.session.sessionId);
-    claudeLogPathBySession.set(parsed.session.sessionId, file);
-    claudeChildLogPathsBySession.set(parsed.session.sessionId, parsed.childPaths);
+    sources.push({ sessionId: parsed.session.sessionId, file, childPaths: parsed.childPaths });
     if (Date.now() - parsed.session.lastActivityAt <= TOKEN_WINDOW_MS) {
       tokensRecent += parsed.tokensSession;
     }
@@ -32,5 +41,11 @@ export function scanClaude(maxFiles = MAX_FILES): Scan {
   for (const file of claudeSummaryCache.keys()) {
     if (!activeFiles.has(file)) claudeSummaryCache.delete(file);
   }
+  claudeLogPathBySession.clear();
+  claudeChildLogPathsBySession.clear();
+  for (const source of sources) {
+    claudeLogPathBySession.set(source.sessionId, source.file);
+    claudeChildLogPathsBySession.set(source.sessionId, source.childPaths);
+  }
   return { sessions, tokensRecent, sourceLimited: listed.length > maxFiles };
 }

package/apps/bridge/src/sessions/scan/codex/scan.ts

@@ -1,3 +1,4 @@
+import { finishScan, finishScanCooperatively } from "../../cooperative-scan";
 import {
   codexActivitySourcesBySession,
   codexAggregatedObservationsBySession,
@@ -11,21 +12,22 @@ import { recentLogs, codexSessionsRoot, MAX_FILES, type Scan } from "../../suppo
 import { withCheckoutObservationCache } from "../../support/repository-checkout";
 
 export function scanCodex(maxFiles = MAX_FILES): Scan {
-  return withCheckoutObservationCache(() => scanCodexCatalog(maxFiles));
+  return withCheckoutObservationCache(() => finishScan(scanCodexCatalog(maxFiles)));
 }
 
-function scanCodexCatalog(maxFiles: number): Scan {
+export function scanCodexCooperatively(maxFiles = MAX_FILES): Promise<Scan> {
+  return withCheckoutObservationCache(() => finishScanCooperatively(scanCodexCatalog(maxFiles)));
+}
+
+function* scanCodexCatalog(maxFiles: number): Generator<void, Scan> {
   const root = codexSessionsRoot();
   const listed = recentLogs(root, 5, maxFiles + 1);
   const files = listed.slice(0, maxFiles);
   const activeFiles = new Set(files);
   const seenSessionIds = new Set<string>();
   const candidates: CodexCandidate[] = [];
-  codexLogPathBySession.clear();
-  codexActivitySourcesBySession.clear();
-  codexAggregatedObservationsBySession.clear();
-
   for (const file of files) {
+    yield;
     const candidate = parseCodexFile(file);
     if (!candidate || seenSessionIds.has(candidate.session.sessionId)) continue;
     seenSessionIds.add(candidate.session.sessionId);
@@ -34,5 +36,8 @@ function scanCodexCatalog(maxFiles: number): Scan {
   for (const file of codexSummaryCache.keys()) {
     if (!activeFiles.has(file)) codexSummaryCache.delete(file);
   }
+  codexLogPathBySession.clear();
+  codexActivitySourcesBySession.clear();
+  codexAggregatedObservationsBySession.clear();
   return { ...assembleCodexScan(candidates), sourceLimited: listed.length > maxFiles };
 }

package/apps/bridge/src/sessions/support/repository-checkout/index.ts

@@ -1,18 +1,17 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { execFileSync } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { isAbsolute } from "node:path";
 
-let scanRoots: Map<string, string | undefined> | undefined;
+const checkoutScans = new AsyncLocalStorage<Map<string, string | undefined>>();
 
-/** Share verified lookups only during this synchronous catalog pass. */
+/** Share verified lookups only during one catalog pass, including cooperative asynchronous readers. */
 export function withCheckoutObservationCache<T>(scan: () => T): T {
-  if (scanRoots) return scan();
-  scanRoots = new Map();
-  try { return scan(); }
-  finally { scanRoots = undefined; }
+  return checkoutScans.getStore() ? scan() : checkoutScans.run(new Map(), scan);
 }
 
 function gitRoot(path: string): string | undefined {
+  const scanRoots = checkoutScans.getStore();
   if (scanRoots?.has(path)) return scanRoots.get(path);
   let root: string | undefined;
   try {

package/cursor-plugin/README.md

@@ -10,7 +10,7 @@ keeps each phone response tied to the exact originating chat and prompt.
 Install the supported CLI on this computer, then run:
 
 ```bash
-npm install -g granttap-mcp@0.8.84
+npm install -g granttap-mcp@0.8.86
 granttap setup
 granttap status
 ```

package/cursor-plugin/mcp.json

@@ -4,7 +4,7 @@
       "command": "node",
       "args": [
         "-e",
-        "\"use strict\";\n\n// Cursor may start this MCP from any cwd. Execute JavaScript entry points with\n// Node itself: Windows batch shims require shell quoting that differs by host.\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { delimiter, dirname, join } = require(\"node:path\");\n\nconst PACKAGE = \"granttap-mcp@0.8.84\";\nconst dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === \"1\";\nconst platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM\n  ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;\nconst nodeRoot = dryRun && process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT\n  ? process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT : dirname(process.execPath);\nconst pathRoots = (process.env.PATH || \"\").split(delimiter).filter(Boolean);\nconst appData = process.env.APPDATA;\nconst roots = [nodeRoot, ...pathRoots, ...(appData ? [join(appData, \"npm\")] : [])];\nconst first = (paths) => paths.find((path) => existsSync(path));\n\nfunction launch() {\n  if (platform !== \"win32\") {\n    const installed = first(roots.map((root) => join(root, \"granttap-mcp\")));\n    if (installed) return { command: installed, args: [] };\n    const npx = first(roots.map((root) => join(root, \"npx\"))) || \"npx\";\n    return { command: npx, args: [\"-y\", PACKAGE] };\n  }\n  const installed = first(roots.map((root) =>\n    join(root, \"node_modules\", \"granttap-mcp\", \"bin\", \"granttap-mcp.mjs\")));\n  if (installed) return { command: process.execPath, args: [installed] };\n  const npx = first(roots.map((root) =>\n    join(root, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\")));\n  if (npx) return { command: process.execPath, args: [npx, \"-y\", PACKAGE] };\n  throw new Error(\"Node.js/npm 22.13.0+ is required on this Windows device. Install npm and retry GrantTap.\");\n}\n\nlet target;\ntry { target = launch(); }\ncatch (error) {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n}\n\nif (dryRun) {\n  process.stdout.write(JSON.stringify(target));\n  process.exit(0);\n}\n\nconst child = spawn(target.command, target.args, { stdio: \"inherit\", windowsHide: true });\nchild.on(\"error\", (error) => {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n  if (signal && platform !== \"win32\") {\n    try { process.kill(process.pid, signal); } catch { process.exit(code ?? 1); }\n    return;\n  }\n  process.exit(code ?? 1);\n});\n"
+        "\"use strict\";\n\n// Cursor may start this MCP from any cwd. Execute JavaScript entry points with\n// Node itself: Windows batch shims require shell quoting that differs by host.\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { delimiter, dirname, join } = require(\"node:path\");\n\nconst PACKAGE = \"granttap-mcp@0.8.86\";\nconst dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === \"1\";\nconst platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM\n  ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;\nconst nodeRoot = dryRun && process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT\n  ? process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT : dirname(process.execPath);\nconst pathRoots = (process.env.PATH || \"\").split(delimiter).filter(Boolean);\nconst appData = process.env.APPDATA;\nconst roots = [nodeRoot, ...pathRoots, ...(appData ? [join(appData, \"npm\")] : [])];\nconst first = (paths) => paths.find((path) => existsSync(path));\n\nfunction launch() {\n  if (platform !== \"win32\") {\n    const installed = first(roots.map((root) => join(root, \"granttap-mcp\")));\n    if (installed) return { command: installed, args: [] };\n    const npx = first(roots.map((root) => join(root, \"npx\"))) || \"npx\";\n    return { command: npx, args: [\"-y\", PACKAGE] };\n  }\n  const installed = first(roots.map((root) =>\n    join(root, \"node_modules\", \"granttap-mcp\", \"bin\", \"granttap-mcp.mjs\")));\n  if (installed) return { command: process.execPath, args: [installed] };\n  const npx = first(roots.map((root) =>\n    join(root, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\")));\n  if (npx) return { command: process.execPath, args: [npx, \"-y\", PACKAGE] };\n  throw new Error(\"Node.js/npm 22.13.0+ is required on this Windows device. Install npm and retry GrantTap.\");\n}\n\nlet target;\ntry { target = launch(); }\ncatch (error) {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n}\n\nif (dryRun) {\n  process.stdout.write(JSON.stringify(target));\n  process.exit(0);\n}\n\nconst child = spawn(target.command, target.args, { stdio: \"inherit\", windowsHide: true });\nchild.on(\"error\", (error) => {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n  if (signal && platform !== \"win32\") {\n    try { process.kill(process.pid, signal); } catch { process.exit(code ?? 1); }\n    return;\n  }\n  process.exit(code ?? 1);\n});\n"
       ]
     }
   }

package/cursor-plugin/stdio-bootstrap.cjs

@@ -7,7 +7,7 @@ const { spawn } = require("node:child_process");
 const { existsSync } = require("node:fs");
 const { delimiter, dirname, join } = require("node:path");
 
-const PACKAGE = "granttap-mcp@0.8.84";
+const PACKAGE = "granttap-mcp@0.8.86";
 const dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === "1";
 const platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM
   ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granttap-mcp",
-  "version": "0.8.84",
+  "version": "0.8.86",
   "description": "Commercial computer runtime connecting local coding agents to GrantTap on Mac, iPhone, iPad and Apple Watch.",
   "type": "module",
   "bin": {

package/packages/core/relay-client.ts

@@ -1,8 +1,8 @@
 /** Shared authenticated relay transport. See README.md for delivery and encryption boundaries. */
 import WebSocket from "ws";
-import { ManagedRelayLease, RelaySocketHealth, RelayReconnectBackoff, relayUpgradeHeaders } from "./socket-lifecycle";
+import { ManagedRelayLease, RelaySocketHealth, RelayReconnectBackoff, RelayConnectionNotifications, relayUpgradeHeaders } from "./socket-lifecycle";
 import { OutboundFrameQueue, sendEncryptedPayload } from "./outbound-scheduler";
-import { openRelayMessage } from "./relay-inbound";
+import { openRelayMessage, parseRelayControl } from "./relay-inbound";
 import { consumeTaskJobOffer, type TaskDispatchListener } from "./task-dispatch";
 import { Payload, type Role } from "../protocol/schema";
 import { peerPublicKeys } from "./crypto";
@@ -19,6 +19,7 @@ export class RelayClient {
   private recipientRouting = false;
   private frames?: OutboundFrameQueue;
   private listeners = new Set<Listener>();
+  private readonly connections = new RelayConnectionNotifications();
   private taskDispatchListeners = new Set<TaskDispatchListener>();
   private taskOfferListeners = new Set<(control: unknown) => void | Promise<void>>();
   private intentionalClose = false;
@@ -97,6 +98,7 @@ export class RelayClient {
           )
           .catch(() => {});
         resolve();
+        this.connections.connected();
       });
       ws.on("message", (data: WebSocket.RawData) => void this.onRaw(data.toString()));
       ws.on('unexpected-response', (_request, response) => {
@@ -125,7 +127,7 @@ export class RelayClient {
   }
 
   private async onRaw(raw: string): Promise<void> {
-    const control = safeJson(raw) as { type?: string; recipientRouting?: boolean } | null;
+    const control = parseRelayControl(raw) as { type?: string; recipientRouting?: boolean } | null;
     if (control?.type === "relay.capabilities" && control.recipientRouting === true) {
       this.recipientRouting = true;
       return;
@@ -239,6 +241,11 @@ export class RelayClient {
     return () => { this.taskOfferListeners.delete(listener); };
   }
 
+  /** Observe each actual socket recovery so replaceable snapshots are sent immediately. */
+  onConnected(listener: () => void | Promise<void>): () => void {
+    return this.connections.subscribe(listener);
+  }
+
   onMessage(l: Listener): () => void {
     this.listeners.add(l);
     return () => this.listeners.delete(l);
@@ -290,11 +297,3 @@ export class RelayClient {
     this.reconnectTimer.unref?.();
   }
 }
-
-function safeJson(s: string): unknown {
-  try {
-    return JSON.parse(s);
-  } catch {
-    return null;
-  }
-}

package/packages/core/relay-inbound/index.ts

@@ -4,6 +4,12 @@ import type { PeerConfig } from '../relay-client-types';
 import { publicKeyIdentifier } from '../ciphertext-recipient';
 import { openFromPeersWithIdentity, openWithTransferKey } from '../crypto';
 
+/** Invalid control frames have no routing or delivery effect. */
+export function parseRelayControl(raw: string): unknown {
+  try { return JSON.parse(raw); }
+  catch { return null; }
+}
+
 /** Authenticate routing, peer identity and optional task encryption before consumers run. */
 export function openRelayMessage(cfg: PeerConfig, raw: unknown, sessionKeys: Map<string, string>,
   peerAllowed: (key: string) => boolean) {

package/packages/core/socket-lifecycle/README.md

@@ -16,5 +16,8 @@ transient machine hooks, so a server can refuse a cooled identity before it
 receives any ciphertext. This digest grants no permissions or decryption rights.
 
 The real WebSocket integration is in `tests/core/managed-relay-renewal.test.ts`.
+`RelayClient.onConnected` observes each actual socket opening, including recovery.
+Consumers can immediately replace stale snapshots; notification failures cannot
+interrupt the transport, and unsubscribing prevents later callbacks.
 
 Licensed under the GrantTap Commercial Source License in the repository root.

package/packages/core/socket-lifecycle/connection-notifications.ts

@@ -0,0 +1,18 @@
+type ConnectionListener = () => void | Promise<void>;
+
+/** Socket notifications cannot interrupt transport setup or another consumer. */
+export class RelayConnectionNotifications {
+  private readonly listeners = new Set<ConnectionListener>();
+
+  subscribe(listener: ConnectionListener): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  connected(): void {
+    for (const listener of this.listeners) {
+      try { void Promise.resolve(listener()).catch(() => {}); }
+      catch { /* A consumer failure does not close a healthy socket. */ }
+    }
+  }
+}

package/packages/core/socket-lifecycle/index.ts

@@ -1,5 +1,6 @@
 export { ManagedRelayLease } from "./managed-relay-lease";
 export { RelaySocketHealth } from "./relay-socket-health";
 export { RelayReconnectBackoff } from "./reconnect-backoff";
+export { RelayConnectionNotifications } from "./connection-notifications";
 
 export { relayUpgradeHeaders } from "./upgrade-headers";