granttap-mcp 0.8.84 → 0.8.85

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/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 { scanCapabilityUsage, scanSessionHistoryCooperatively, scanSessionsCooperatively, scopeCapabilityUsageToRoom, TOKEN_WINDOW_HOURS } from "../../sessions";
 import { boundedCatalogHistory, INTERVAL_MS, publishSessionEvents } from "../handlers/catalog";
 import { sweepAttachments } from "../handlers/receipts";
 import { handleMonitorMessage } from "../handlers/inbound";
@@ -71,23 +71,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 +113,24 @@ async function publishMonitorTick(input: {
   client: RelayClient;
   leadership: ReturnType<typeof monitorLeadership>;
   subscriptions: Set<string>;
-  history: (force?: boolean) => SessionsStatus["sessions"];
+  history: (force?: boolean) => Promise<SessionsStatus["sessions"]>;
   clocks: { lastHistoryPublishedAt: number; lastCapabilityPublishedAt: number };
   loadLoop: { updateStatus: (status: SessionsStatus) => void };
   forceHistory: boolean;
+  active: () => boolean;
 }): Promise<{ lastHistoryPublishedAt: number; lastCapabilityPublishedAt: number }> {
   const { client, leadership, subscriptions, history, clocks, loadLoop, forceHistory } = input;
   let { lastHistoryPublishedAt, lastCapabilityPublishedAt } = clocks;
   if (!client.isConnected) return { lastHistoryPublishedAt, lastCapabilityPublishedAt };
   await publishHeartbeat(client).catch(() => {});
+  if (!input.active()) return { lastHistoryPublishedAt, lastCapabilityPublishedAt };
   if (!leadership.acquire()) return { lastHistoryPublishedAt, lastCapabilityPublishedAt };
   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, lastCapabilityPublishedAt };
+  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)) {
@@ -146,7 +149,7 @@ async function publishMonitorTick(input: {
   if (Date.now() - lastCapabilityPublishedAt >= 30_000) {
     const usage = scanCapabilityUsage([
       ...status.sessions,
-      ...history(false),
+      ...await history(false),
     ]);
     await client.send(scopeCapabilityUsageToRoom(usage, client.room), "phone", { ttlMs: 90_000, reliable: false });
     lastCapabilityPublishedAt = Date.now();
@@ -167,6 +170,7 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
   let historyCache: { generatedAt: number; sessions: SessionsStatus["sessions"] } | undefined;
   let lastHistoryPublishedAt = 0;
   let lastCapabilityPublishedAt = 0;
+  let closed = false;
   const publishMachineLoad = createMachineLoadPublisher({
     log: (line) => process.stderr.write(`[monitor] ${line}\n`),
   });
@@ -185,16 +189,18 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
     },
   });
 
-  const history = (force = false): SessionsStatus["sessions"] => {
+  const history = async (force = false): Promise<SessionsStatus["sessions"]> => {
     if (force || !historyCache || Date.now() - historyCache.generatedAt > 60_000) {
-      historyCache = { generatedAt: Date.now(), sessions: scanSessionHistory() };
+      historyCache = { generatedAt: Date.now(), sessions: await scanSessionHistoryCooperatively() };
     }
     return historyCache.sessions;
   };
 
   const publish = singleFlightPublisher(async (forceHistory: boolean): Promise<void> => {
+    if (closed) return;
     const next = await publishMonitorTick({
       client, leadership, subscriptions, history, loadLoop, forceHistory,
+      active: () => !closed,
       clocks: { lastHistoryPublishedAt, lastCapabilityPublishedAt },
     });
     lastHistoryPublishedAt = next.lastHistoryPublishedAt;
@@ -213,6 +219,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,6 +241,8 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
     publish: () => publish(false),
     isLeader: () => leadership.acquire(),
     close: () => {
+      closed = true;
+      offConnected?.();
       stopCatalog();
       stopCatalogHeads(client);
       stopMonitorMeshes(client);

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.85
 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.85\";\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.85";
 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.85",
   "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";