granttap-mcp 0.8.86 → 0.8.87

package/README.md

@@ -843,3 +843,7 @@ sustained structured work in a different checkout without interpreting chat
 titles. Task identity and its original coordination/access scope survive.
 
 See [repository observations](apps/bridge/src/mesh/repository-details/README.md).
+
+The relay can retain recipient-encrypted catalogs, Mesh snapshots, capability usage and recent chat heads for reconnect without the computer. This bounded seven-day read cache is separate from the durable encrypted command queue. See [relay state publication](packages/core/retained-state/README.md). The relay never receives decryption keys or readable chat content.
+
+Tools & Skills matches recorded usage to the exact computer, provider and execution. Codex's native history projection supplies actual MCP invocation IDs, results and durations, including calls made through Code Mode. Claude Code uses observed tool-use, result and Skill records, aggregating MCP and skill calls before its recent-detail cache is trimmed. Execution summaries remain available when older call details fall outside the recent-event budget. Counts describe recorded evidence; installation and permission do not prove usage. Missing resource measurements remain unknown. See [native capability history](apps/bridge/src/sessions/native-capability-history/README.md).

package/apps/bridge/src/host/session-keys.ts

@@ -1,3 +1,4 @@
+import { retainedPayloadOptions } from "../../../../packages/core/retained-state";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { loadSessionKeys, persistedSessionKey } from "./session-key-store";
@@ -70,6 +71,9 @@ async function sendScopedPayload(input: {
   options: SendOptions;
 }): Promise<void> {
   const { client, payload, sessionId, purpose, to, options } = input;
+  const retained = retainedPayloadOptions(payload);
+  const grantOptions = retained.stateKey ? {}
+    : { stateKey: undefined, stateRevision: undefined, statePriority: undefined, stateGroup: undefined };
   const key = sessionKey(sessionId);
   client.setSessionKey(sessionId, key);
   await client.send({
@@ -78,6 +82,6 @@ async function sendScopedPayload(input: {
     key,
     purpose,
     createdAt: Date.now(),
-  }, to, { ttlMs: options.ttlMs, peerPublicKey: options.peerPublicKey });
+  }, to, { ttlMs: options.ttlMs, peerPublicKey: options.peerPublicKey, ...grantOptions });
   await client.sendSession(payload, sessionId, to, options);
 }

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

@@ -1,7 +1,7 @@
 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";
+import { scanRecordedCapabilityUsage, scopeCapabilityUsageToRoom } from "../../sessions";
 
 type Publication = { running: boolean; closed: boolean; lastPublishedAt: number };
 const publications = new WeakMap<RelayClient, Publication>();
@@ -16,11 +16,16 @@ export function publishMonitorCapabilities(client: RelayClient, status: Sessions
   const work = (async () => {
     await setImmediate();
     if (state.closed || !client.isConnected) return;
+    const publish = async (sessions: SessionInfo[]) => {
+      const usage = await scanRecordedCapabilityUsage(sessions);
+      if (state.closed || !client.isConnected) return;
+      await client.send(scopeCapabilityUsageToRoom(usage, client.room), "phone",
+        { ttlMs: 90_000, reliable: false });
+    };
+    await publish(status.sessions);
     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 });
+    if (older.length) await publish([...status.sessions, ...older]);
     state.lastPublishedAt = Date.now();
   })();
   void work.catch(() => {}).finally(() => { state.running = false; });

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

@@ -128,17 +128,20 @@ async function publishMonitorTick(input: {
   if (!leadership.acquire()) return { lastHistoryPublishedAt };
   await client.send(approvalsStatus(), "phone", { ttlMs: INTERVAL_MS * 3, reliable: false });
   const initial = lastHistoryPublishedAt === 0;
+  if (initial && !resumedHeads.has(client)) {
+    const saved = publishedCatalog(client);
+    if (saved) await client.send(saved, "phone", { ttlMs: INTERVAL_MS * 24, reliable: false });
+    if (!input.active()) return { lastHistoryPublishedAt };
+    resumedHeads.add(client);
+    void resumePublishedChats(client,
+      (session, saved) => publishSessionEvents(client, session.sessionId, saved)).catch(() => {});
+  }
   const includeHistory = forceHistory || (!initial && Date.now() - lastHistoryPublishedAt >= HISTORY_INTERVAL_MS);
   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)) {
-    resumedHeads.add(client);
-    void resumePublishedChats(client,
-      (session, saved) => publishSessionEvents(client, session.sessionId, saved)).catch(() => {});
-  }
   // Provider review is independent of task visibility; a hung hook RPC must
   // never hold the current catalog behind its discovery timeout.
   void refreshCodexHooks().catch(() => {});

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

@@ -9,10 +9,11 @@ unreadable merely because hundreds of newer logs appeared.
 The private `session-catalog-cache.json` contains metadata and validated native
 source locations. It excludes messages, capability descriptions, and credentials.
 The room and provider roots bind its scope. On restart the primary monitor sends
-a fresh live catalog first, then resumes the saved Now chats' native heads under
-their independent task keys in the background. Closed-history discovery runs
-separately from that first live publication. It does not republish an old catalog
-as fresh. The phone continues its durable historical backfill independently.
+the saved catalog with its original timestamp before starting fresh discovery,
+and resumes the saved Now chats' native heads under their independent task keys
+in the background. Fresh discovery replaces that saved state. Closed-history
+discovery runs separately from the first live publication. The phone continues
+its durable historical backfill independently.
 
 Tests live in `tests/`. This runtime module uses the repository GrantTap Commercial Source License.
 

package/apps/bridge/src/session-catalog/publish-heads.ts

@@ -1,19 +1,25 @@
 import type { RelayClient } from "../../../../packages/core/relay-client";
 import type { SessionsStatus } from "../../../../packages/protocol/schema";
 
-type HeadRun = { running: boolean; closed: boolean };
+type HeadRun = { running: boolean; closed: boolean; cursor: number };
 const runs = new WeakMap<RelayClient, HeadRun>();
 
 /** Transcript transfers must never occupy the fresh catalog's publication slot. */
 export function publishCatalogHeads(client: RelayClient, status: SessionsStatus,
   subscriptions: ReadonlySet<string>,
   publish: (client: RelayClient, sessionId: string, status: SessionsStatus) => Promise<unknown>): void {
-  const state = runs.get(client) ?? { running: false, closed: false };
+  const state = runs.get(client) ?? { running: false, closed: false, cursor: 0 };
   runs.set(client, state);
-  if (state.running || state.closed || subscriptions.size === 0) return;
+  if (state.running || state.closed) return;
+  const candidates = [...new Set([...subscriptions,
+    ...(client.supportsRetainedState ? status.sessions.map(session => session.sessionId) : [])])];
+  if (!candidates.length) return;
+  const count = Math.min(32, candidates.length);
+  const selected = Array.from({ length: count }, (_, offset) => candidates[(state.cursor + offset) % candidates.length]!);
+  state.cursor = (state.cursor + count) % candidates.length;
   state.running = true;
   void (async () => {
-    for (const sessionId of [...subscriptions]) {
+    for (const sessionId of selected) {
       await new Promise<void>(resolve => setImmediate(resolve));
       if (state.closed || !client.isConnected) break;
       await publish(client, sessionId, status).catch(() => {});

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

@@ -18,6 +18,14 @@ the child snapshot. Root chat pagination remains in `TranscriptHistory`.
 Feature tests live in `tests/`; the reusable multi-provider conversation harness
 lives in the repository `tests/thread/` directory.
 
+## Grok Build history
+
+Grok discovery reads the local session summaries and visible conversation history.
+Both role-based records and current typed user/assistant records are supported.
+Typed user records must have a valid prompt index. Environment preambles, synthetic
+reminders, system messages, and hidden reasoning are excluded from the timeline.
+Session continuation uses the installed Grok CLI and its existing authentication.
+
 ## License
 
 Licensed under the GrantTap Commercial Source License. See LICENSE and NOTICE.

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

@@ -38,6 +38,9 @@ import {
   toRemoteCapabilityUsageEvent,
 } from "./telemetry";
 import { createCapabilityTotals } from "./support/capability-totals";
+import { createExecutionSummaries, budgetExecutionSummaries } from './telemetry/execution-summaries';
+import { readCodexCapabilityHistory, type NativeCapabilityEvidence } from './native-capability-history';
+import { recordedClaudeUsage } from './scan/claude';
 
 export { MAX_ACTIVITY_ENTRIES, MAX_ACTIVITY_TEXT, TOKEN_WINDOW_HOURS };
 export { nativeTranscriptRoots, nativeTranscriptSource, restoreNativeTranscriptSource } from "./native-source";
@@ -115,11 +118,13 @@ export function scanSessionActivity(session: SessionInfo): SessionActivity {
  */
 export function scanCapabilityUsage(
   sessions: SessionInfo[] = [...scanSessions().sessions, ...scanSessionHistory()],
+  native?: NativeCapabilityEvidence,
 ): CapabilityUsageStatus {
   const candidates: RemoteCapabilityUsageEvent[] = [];
   // Totals count every observation as it streams past; the candidate list is
   // trimmed to a byte budget and can never answer for a whole period.
   const totals = createCapabilityTotals();
+  const summaries = createExecutionSummaries();
   const seenSessions = new Set<string>();
   for (const session of sessions) {
     const nativeScope = `${session.agent}\0${session.sessionId}`;
@@ -131,19 +136,35 @@ export function scanCapabilityUsage(
           : session.agent === "cursor" ? cursorCapabilityUsage(session)
             : session.agent === "grok" ? grokCapabilityUsage(session)
             : [];
-    for (const observation of observations) {
-      const converted = toRemoteCapabilityUsageEvent(observation);
-      if (!converted) continue;
+    const recorded = session.agent === 'codex' && native?.scopes.includes(session.sessionId);
+    const claudeRecorded = session.agent === 'claude' ? recordedClaudeUsage(observations) : undefined;
+    const events = observations.map(toRemoteCapabilityUsageEvent).filter(
+      (event): event is RemoteCapabilityUsageEvent => event != null
+        && !(recorded && event.kind === 'mcp'));
+    if (recorded) events.push(...native!.events.filter(event => event.sessionId === session.sessionId));
+    for (const converted of events) {
       const event = { ...converted, agent: session.agent };
-      totals.add(event);
+      if (!claudeRecorded || event.kind === 'cli') {
+        totals.add(event);
+        summaries.add(event, recorded && event.kind === 'mcp' ? 'native-history' : 'transcript');
+      }
       rememberCapabilityUsageCandidate(candidates, event);
     }
+    for (const summary of claudeRecorded?.summaries ?? []) summaries.merge(summary);
+    for (const total of claudeRecorded?.totals ?? []) totals.merge(total);
   }
-  const envelope = { type: "capability.usage.status" as const,
+  const metadata = { type: "capability.usage.status" as const,
     totals: totals.rows(), generatedAt: Date.now() };
+  const executionSummaries = budgetExecutionSummaries(summaries.rows(), metadata);
+  const envelope = { ...metadata, ...(executionSummaries.length ? { executionSummaries } : {}) };
   return { ...envelope, events: limitCapabilityUsageEvents(candidates, envelope) };
 }
 
+/** Native metadata enrichment runs off the relay event loop. */
+export async function scanRecordedCapabilityUsage(sessions: SessionInfo[]): Promise<CapabilityUsageStatus> {
+  return scanCapabilityUsage(sessions, await readCodexCapabilityHistory(sessions));
+}
+
 /** Bind every local observation to the authenticated relay room before publish. */
 export function scopeCapabilityUsageToRoom(
   status: CapabilityUsageStatus,

package/apps/bridge/src/sessions/native-capability-history/README.md

@@ -0,0 +1,20 @@
+# Native capability history
+
+`index.ts` reads Codex's local history projection through a bounded worker.
+Native MCP execution records provide call identity, outcome, and duration even
+when the call happened through Code Mode and the transcript preview omits it.
+The database is opened read only. Native projection watermarks and the provider's
+updated-page index restrict warm reads to changed calls; a completion replaces
+its original call rather than adding another one. Queries run in a worker with
+a bounded deadline and never occupy the relay event loop. Missing or incompatible projections remain
+unknown; the existing transcript reader remains a compatibility fallback.
+
+Only requested executions and their recorded children are queried. The worker
+returns metadata, never prompts, arguments, or tool results. Its thirty-day,
+20,000-record bound and per-result size bound make summaries observed evidence,
+not a claim of complete lifetime usage. The recent-call list and execution
+summaries are bounded independently. File paths follow the configured Codex
+root and contain no machine-specific fallback.
+
+Tests use a real SQLite history projection and reopen it after the writer closes.
+This module uses the repository GrantTap Commercial Source License.

package/apps/bridge/src/sessions/native-capability-history/completed-item.ts

@@ -0,0 +1,31 @@
+import type { SessionInfo } from '../../../../../packages/protocol/schema';
+import type { CapabilityObservation } from '../telemetry';
+import { ts } from '../support/common';
+
+/** Only host-authored execution records establish inner Code Mode calls. */
+export function completedCodexMcp(row: any, session: SessionInfo): CapabilityObservation | undefined {
+  const payload = row?.payload;
+  if (row?.type !== 'event_msg' || payload?.type !== 'item_completed'
+    || (payload.thread_id != null && payload.thread_id !== session.sessionId)) return;
+  const item = payload.item;
+  if (!['McpToolCall', 'mcpToolCall'].includes(item?.type)) return;
+  if (![item.id, item.server, item.tool].every(x => typeof x === 'string' && x.trim() && x.length <= 240)) return;
+  const start = payload.started_at_ms ?? ts(row.timestamp) ?? session.lastActivityAt;
+  const elapsed = item.durationMs ?? (item.duration && Number.isFinite(item.duration.secs)
+    && Number.isFinite(item.duration.nanos) ? item.duration.secs * 1000 + item.duration.nanos / 1e6
+      : payload.completed_at_ms != null ? payload.completed_at_ms - start : undefined);
+  const outcome = item.status === 'failed' || item.result?.isError === true || item.result?.is_error === true
+    ? 'error' : ['cancelled', 'canceled'].includes(item.status) ? 'cancelled'
+      : item.status === 'completed' ? 'success' : 'unknown';
+  return { sourceId: `${session.sessionId}:${item.id}`, sessionId: session.sessionId,
+    toolName: `mcp__${item.server}__${item.tool}`, mcpServer: item.server, createdAt: start,
+    outcome, ...(Number.isFinite(elapsed) && elapsed >= 0
+      ? { durationMs: Math.min(3600000, Math.round(elapsed)) } : {}) };
+}
+
+export function recordedCodexToolName(payload: any): string {
+  const name = String(payload.name ?? payload.type);
+  const namespace = payload.namespace;
+  return typeof namespace === 'string' && /^mcp__[A-Za-z0-9_-]+$/.test(namespace)
+    ? `${namespace}__${name}` : name;
+}

package/apps/bridge/src/sessions/native-capability-history/index.ts

@@ -0,0 +1,67 @@
+import type { CapabilityExecutionSummary, RemoteCapabilityUsageEvent, SessionInfo } from '../../../../../packages/protocol/schema';
+import { Worker } from 'node:worker_threads';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { codexSessionsRoot } from '../support/common';
+export { completedCodexMcp, recordedCodexToolName } from './completed-item';
+export type NativeCapabilityEvidence = {
+  scopes: string[];
+  events: RemoteCapabilityUsageEvent[];
+  summaries: CapabilityExecutionSummary[];
+};
+
+const empty = (): NativeCapabilityEvidence => ({ scopes: [], events: [], summaries: [] });
+const cache = new Map<string, { at: number; value: Promise<NativeCapabilityEvidence> }>();
+type Cursor = { threadId: string; watermark: number; events: RemoteCapabilityUsageEvent[] };
+const cursors = new Map<string, Cursor[]>();
+
+/** Query only bounded call metadata in a worker; native conversation contents stay local. */
+export function readCodexCapabilityHistory(
+  sessions: SessionInfo[], root = process.env.GRANTTAP_CODEX_DIR ?? process.env.NODVOX_CODEX_DIR
+    ?? process.env.CODEX_HOME ?? dirname(codexSessionsRoot()),
+): Promise<NativeCapabilityEvidence> {
+  const database = join(root, 'thread_history_1.sqlite');
+  const owners = new Map<string, string>();
+  for (const session of sessions.filter(s => s.agent === 'codex')) {
+    owners.set(session.sessionId, session.sessionId);
+    for (const child of session.childThreads ?? []) {
+      if (!owners.has(child.threadId)) owners.set(child.threadId, session.sessionId);
+    }
+  }
+  const bindings = [...owners].slice(0, 512);
+  if (!bindings.length || !existsSync(database)) return Promise.resolve(empty());
+  const key = JSON.stringify([database, bindings]);
+  const previous = cache.get(key);
+  if (previous && Date.now() - previous.at < 30_000) return previous.value;
+  const value = readWorker(database, bindings);
+  cache.set(key, { at: Date.now(), value });
+  while (cache.size > 4) cache.delete(cache.keys().next().value!);
+  return value;
+}
+
+function readWorker(database: string, bindings: [string, string][]): Promise<NativeCapabilityEvidence> {
+  return new Promise(resolve => {
+    const requested = new Set(bindings.map(([thread]) => thread));
+    const worker = new Worker(new URL('./reader.js', import.meta.url), { execArgv: [],
+      workerData: { database, bindings, now: Date.now(),
+        previous: (cursors.get(database) ?? []).filter(cursor => requested.has(cursor.threadId)) },
+      resourceLimits: { maxOldGenerationSizeMb: 64 } });
+    let evidence = empty();
+    const timer = setTimeout(() => { void worker.terminate(); }, 45_000);
+    worker.once('message', (result: NativeCapabilityEvidence & { cursors?: Cursor[] }) => {
+      const { cursors: next, ...publicEvidence } = result;
+      if (next) {
+        const merged = [...next, ...(cursors.get(database) ?? []).filter(cursor => !requested.has(cursor.threadId))];
+        let count = 0;
+        cursors.set(database, merged.filter(cursor => {
+          count += cursor.events.length;
+          return count <= 20000;
+        }).slice(0, 512));
+        while (cursors.size > 4) cursors.delete(cursors.keys().next().value!);
+      }
+      evidence = publicEvidence;
+    });
+    worker.once('error', () => { evidence = empty(); });
+    worker.once('exit', code => { clearTimeout(timer); resolve(code === 0 ? evidence : empty()); });
+  });
+}

package/apps/bridge/src/sessions/native-capability-history/reader.js

@@ -0,0 +1,97 @@
+import { DatabaseSync } from 'node:sqlite';
+import { parentPort, workerData } from 'node:worker_threads';
+
+const LIMIT = 20000;
+const MAX_DURATION = 60 * 60_000;
+const validName = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 160;
+
+function outcome(row) {
+  if (row.status === 'failed' || row.resultError === 1) return 'error';
+  if (row.status === 'cancelled' || row.status === 'canceled') return 'cancelled';
+  return row.status === 'completed' ? 'success' : 'unknown';
+}
+
+function observe(row, sessionId, now) {
+  if (!validName(row.server) || !validName(row.tool) || typeof row.item_id !== 'string') return;
+  const createdAt = Number(row.started_at_ms ?? row.created_at_ms);
+  if (!Number.isFinite(createdAt) || createdAt <= 0 || createdAt > now + 300000) return;
+  const duration = row.durationMs ?? (row.completed_at_ms != null && row.started_at_ms != null
+    ? row.completed_at_ms - row.started_at_ms : undefined);
+  return { sourceId: `${row.thread_id}:${row.item_id}`.slice(0, 512), sessionId,
+    agent: 'codex', kind: 'mcp', name: row.server.trim(),
+    toolName: `mcp__${row.server.trim()}__${row.tool.trim()}`.slice(0, 240), createdAt,
+    outcome: outcome(row), ...(Number.isFinite(duration) && duration >= 0
+      ? { durationMs: Math.min(MAX_DURATION, Math.round(duration)) } : {}) };
+}
+
+function readThread(db, { threadId, previous, watermark, now, limit }) {
+  const valid = previous && previous.watermark <= watermark;
+  const cached = new Map((valid ? previous.events : []).filter(event => event.createdAt >= now - 30 * 86400000)
+    .map(event => [event.sourceId, event]));
+  if (valid && previous.watermark === watermark) return [...cached.values()].slice(0, limit);
+  // The provider's own updated-page index bounds subsequent reads to new or
+  // completed calls. Never add an index or write to the provider database.
+  const rows = db.prepare(`SELECT thread_id,item_id,created_at_ms,started_at_ms,completed_at_ms,
+    json_extract(item_json,'$.server') AS server,json_extract(item_json,'$.tool') AS tool,
+    json_extract(item_json,'$.status') AS status,json_extract(item_json,'$.durationMs') AS durationMs,
+    json_extract(item_json,'$.result.isError') AS resultError
+    FROM thread_items WHERE thread_id=? AND updated_at_ordinal>=? AND item_type='mcpToolCall'
+    AND created_at_ms>=? AND length(CAST(item_json AS BLOB))<=262144 AND json_valid(item_json)
+    ORDER BY updated_at_ordinal DESC LIMIT ${limit}`)
+    .all(threadId, valid ? previous.watermark : 0, now - 30 * 86400000);
+  for (const row of rows) {
+    const event = observe(row, threadId, now);
+    if (event) cached.set(event.sourceId, event);
+  }
+  return [...cached.values()].sort((a, b) => b.createdAt - a.createdAt).slice(0, limit);
+}
+
+function readHistory({ database, bindings, now, previous = [] }) {
+  const db = new DatabaseSync(database, { readOnly: true });
+  try {
+    db.exec('PRAGMA query_only=ON; PRAGMA busy_timeout=30;');
+    const owners = new Map(bindings);
+    const ids = [...owners.keys()];
+    const placeholders = ids.map(() => '?').join(',');
+    const projections = db.prepare(`SELECT thread_id,next_rollout_ordinal FROM thread_history_projection_state
+      WHERE thread_id IN (${placeholders})`).all(...ids);
+    const scopes = [...new Set(projections.map(row => owners.get(row.thread_id)))];
+    // Large tool results are excluded before JSON extraction. Neither prompts,
+    // tool arguments nor result contents cross the worker boundary.
+    const old = new Map(previous.map(cursor => [cursor.threadId, cursor]));
+    const next = [];
+    let remaining = LIMIT;
+    for (const row of projections.sort((a, b) => ids.indexOf(a.thread_id) - ids.indexOf(b.thread_id))) {
+      if (remaining <= 0) break;
+      const events = readThread(db, { threadId: row.thread_id, previous: old.get(row.thread_id),
+        watermark: row.next_rollout_ordinal, now, limit: remaining });
+      next.push({ threadId: row.thread_id, watermark: row.next_rollout_ordinal, events });
+      remaining -= events.length;
+    }
+    const events = next.flatMap(cursor => cursor.events.map(event => ({ ...event,
+      sessionId: owners.get(cursor.threadId) }))).sort((a, b) => b.createdAt - a.createdAt).slice(0, LIMIT);
+    const summaries = new Map();
+    for (const event of events) {
+      const sessionId = event.sessionId;
+      const key = JSON.stringify([sessionId, event.name]);
+      const summary = summaries.get(key) ?? { sessionId, agent: 'codex', kind: 'mcp',
+        name: event.name, count: 0, failures: 0, cancelled: 0, lastUsedAt: 0,
+        source: 'native-history' };
+      summary.count++;
+      summary.failures += event.outcome === 'error' ? 1 : 0;
+      summary.cancelled += event.outcome === 'cancelled' ? 1 : 0;
+      summary.lastUsedAt = Math.max(summary.lastUsedAt, event.createdAt);
+      if (event.durationMs != null) {
+        summary.durationMs = (summary.durationMs ?? 0) + event.durationMs;
+        summary.durationCount = (summary.durationCount ?? 0) + 1;
+      }
+      summaries.set(key, summary);
+    }
+    return { scopes, events, cursors: next, summaries: [...summaries.values()]
+      .sort((a, b) => b.lastUsedAt - a.lastUsedAt).slice(0, 128) };
+  } finally { db.close(); }
+}
+
+try { parentPort.postMessage(readHistory(workerData)); }
+catch { parentPort.postMessage({ scopes: [], events: [], summaries: [] }); }
+parentPort.close();

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

@@ -1,4 +1,5 @@
 import { claudeMessageIdentity } from "./message-identity";
+import { createClaudeUsageRecorder } from './recorded-usage';
 import { readFileSync, statSync } from "node:fs";
 import type { ActivityEntry, ChildThreadInfo, SessionInfo } from "../../../../../../packages/protocol/schema";
 import { safeParse, ts } from "../../support/common";
@@ -60,6 +61,11 @@ export function claudeCapabilityUsage(
   if (!lines) return [];
   const pending = new Map<string, PendingCapabilityTool>();
   const out: CapabilityObservation[] = [];
+  const recorder = createClaudeUsageRecorder();
+  const remember = (observation: CapabilityObservation) => {
+    recorder.remember(observation);
+    rememberCapabilityObservation(out, observation);
+  };
 
   let commandOrdinal = 0;
   for (const line of lines) {
@@ -71,7 +77,7 @@ export function claudeCapabilityUsage(
     const command = slashCommandSkill(row);
     if (command) {
       commandOrdinal += 1;
-      rememberCapabilityObservation(out, {
+      remember({
         sourceId: `${sourceThreadId}:command:${typeof row.uuid === "string" ? row.uuid : commandOrdinal}`,
         sessionId: session.sessionId,
         toolName: `/${command}`,
@@ -115,15 +121,16 @@ export function claudeCapabilityUsage(
           errorClass: block.is_error === true ? "tool_result" : undefined,
         }, "claude") ??
         pendingCapabilityObservation(item);
-      if (observation) rememberCapabilityObservation(out, observation);
+      if (observation) remember(observation);
       pending.delete(block.tool_use_id);
     }
   }
 
   for (const item of pending.values()) {
     const observation = pendingCapabilityObservation(item);
-    if (observation) rememberCapabilityObservation(out, observation);
+    if (observation) remember(observation);
   }
+  recorder.finish(out);
   return out;
 }
 

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

@@ -1,3 +1,4 @@
 export * from "./shared";
 export * from "./scan";
 export * from "./activity";
+export { recordedClaudeUsage } from './recorded-usage';

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

@@ -1,4 +1,5 @@
 import { readFileSync, statSync } from "node:fs";
+import { mergeRecordedClaudeUsage, recordedClaudeUsageIsCurrent } from './recorded-usage';
 import { basename } from "node:path";
 import type { ChildThreadInfo, SessionInfo } from "../../../../../../packages/protocol/schema";
 import { aggregateChildThreads, childTitle } from "../../support/child-threads";
@@ -124,7 +125,8 @@ export function parseClaudeFile(file: string): {
     cached &&
     cached.mtimeMs === fileStat.mtimeMs &&
     cached.size === fileStat.size &&
-    cached.childFingerprint === childFingerprint
+    cached.childFingerprint === childFingerprint &&
+    recordedClaudeUsageIsCurrent(cached.observations)
   ) {
     const session = {
       ...cached.session,
@@ -182,9 +184,11 @@ export function parseClaudeFile(file: string): {
     if (!childLines) continue;
     const child = claudeChildSummary(childPath, state.sessionId, childLines);
     childThreads.push(child);
-    for (const observation of claudeCapabilityUsage(ownSession, childLines, child.threadId)) {
+    const childObservations = claudeCapabilityUsage(ownSession, childLines, child.threadId);
+    for (const observation of childObservations) {
       rememberCapabilityObservation(observations, observation);
     }
+    mergeRecordedClaudeUsage(observations, childObservations);
   }
   const session = aggregateChildThreads(ownSession, childThreads);
   claudeSummaryCache.set(file, {

package/apps/bridge/src/sessions/scan/claude/recorded-usage/README.md

@@ -0,0 +1,17 @@
+# Recorded Claude capability usage
+
+Public entry point: [`index.ts`](index.ts).
+
+The Claude transcript parser records confirmed MCP and skill observations before
+the recent detail cache is trimmed. It keeps at most 20,000 metadata observations
+from the last 30 days while parsing, then retains compact execution and period
+aggregates keyed to the existing transcript cache. Inputs and result bodies are
+not retained by this module. Child transcript aggregates remain attributed to
+their parent execution. Missing duration or resource evidence stays unknown.
+
+Tests live in [`tests/recorded-usage.test.ts`](tests/recorded-usage.test.ts).
+The repository quality and public package boundaries apply to this module.
+
+## License
+
+This module is covered by the [GrantTap Commercial Source License](../../../../../../../LICENSE).

package/apps/bridge/src/sessions/scan/claude/recorded-usage/index.ts

@@ -0,0 +1,60 @@
+import type { CapabilityExecutionSummary, CapabilityUsageTotal, RemoteCapabilityUsageEvent } from '../../../../../../../packages/protocol/schema';
+import { CAPABILITY_TOTAL_WINDOWS, createCapabilityTotals } from '../../../support/capability-totals';
+import { createExecutionSummaries } from '../../../telemetry/execution-summaries';
+import { toRemoteCapabilityUsageEvent, type CapabilityObservation } from '../../../telemetry';
+
+type RecordedClaudeUsage = { summaries: CapabilityExecutionSummary[]; totals: CapabilityUsageTotal[]; nextExpiry: number };
+const recorded = new WeakMap<CapabilityObservation[], RecordedClaudeUsage>();
+
+/** Cached aggregates outlive the bounded details, without retaining inputs or result bodies. */
+export function recordedClaudeUsage(observations: CapabilityObservation[]): RecordedClaudeUsage | undefined {
+  return recorded.get(observations);
+}
+
+export function recordedClaudeUsageIsCurrent(observations: CapabilityObservation[]): boolean {
+  return Date.now() < (recorded.get(observations)?.nextExpiry ?? Infinity);
+}
+
+export function createClaudeUsageRecorder() {
+  const events = new Map<string, RemoteCapabilityUsageEvent>();
+  const cutoff = Date.now() - 30 * 86400_000;
+  return {
+    remember(observation: CapabilityObservation) {
+      if (!observation.mcpServer && !observation.skill) return;
+      const converted = toRemoteCapabilityUsageEvent(observation);
+      if (!converted || converted.createdAt < cutoff) return;
+      const event = { ...converted, agent: 'claude' as const };
+      events.delete(event.sourceId);
+      events.set(event.sourceId, event);
+      while (events.size > 20000) events.delete(events.keys().next().value!);
+    },
+    finish(observations: CapabilityObservation[]) {
+      const summaries = createExecutionSummaries(), totals = createCapabilityTotals();
+      const now = Date.now();
+      let nextExpiry = Infinity;
+      for (const event of events.values()) {
+        summaries.add(event, 'transcript');
+        totals.add(event);
+        for (const hours of CAPABILITY_TOTAL_WINDOWS) {
+          const expires = event.createdAt + hours * 3600_000;
+          if (expires > now) nextExpiry = Math.min(nextExpiry, expires);
+        }
+      }
+      recorded.set(observations, { summaries: summaries.rows(), totals: totals.rows(), nextExpiry });
+      events.clear();
+    },
+  };
+}
+
+/** Child source IDs belong to their own transcript; the Project uses the parent execution. */
+export function mergeRecordedClaudeUsage(parent: CapabilityObservation[], child: CapabilityObservation[]): void {
+  const summaries = createExecutionSummaries(), totals = createCapabilityTotals();
+  let nextExpiry = Infinity;
+  for (const observations of [parent, child]) {
+    const usage = recorded.get(observations);
+    for (const summary of usage?.summaries ?? []) summaries.merge(summary);
+    for (const total of usage?.totals ?? []) totals.merge(total);
+    nextExpiry = Math.min(nextExpiry, usage?.nextExpiry ?? Infinity);
+  }
+  recorded.set(parent, { summaries: summaries.rows(), totals: totals.rows(), nextExpiry });
+}

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

@@ -20,6 +20,7 @@ import {
 } from "../../telemetry";
 import { safeParse, ts } from "../../support/common";
 import { codexHeadRequest } from "../../support/codex-head";
+import { completedCodexMcp, recordedCodexToolName } from '../../native-capability-history';
 import {
   CODEX_ACTIVITY_HEAD_BYTES,
   CODEX_ACTIVITY_TAIL_BYTES,
@@ -93,9 +94,10 @@ export function codexCapabilityUsage(
   const pending = new Map<string, PendingCapabilityTool>();
   const nestedByCall = new Map<string, Array<{ toolName: string; server: string }>>();
   const out: CapabilityObservation[] = [];
+  const host = { observed: false };
 
   lines.forEach((line, index) => ingestCodexCapabilityRow({
-    line, index, session, pending, nestedByCall, out,
+    line, index, session, pending, nestedByCall, out, host,
   }));
 
   for (const [callId, item] of pending) {
@@ -103,7 +105,7 @@ export function codexCapabilityUsage(
     const nested = nestedByCall.get(callId) ?? [];
     if (observation && nested.length === 0) rememberCapabilityObservation(out, observation);
     const perCapability = Math.max(1, Math.ceil(estimateTokens(item.input) / Math.max(1, nested.length)));
-    for (const [nestedIndex, tool] of nested.entries()) {
+    for (const [nestedIndex, tool] of (host.observed ? [] : nested).entries()) {
       rememberCapabilityObservation(out, {
         sourceId: `${item.sourceId}:nested:${nestedIndex}`,
         sessionId: item.sessionId,
@@ -115,7 +117,7 @@ export function codexCapabilityUsage(
       });
     }
   }
-  return out;
+  return host.observed ? out.filter(item => !/:nested:\d+$/.test(item.sourceId)) : out;
 }
 
 function ingestCodexCapabilityRow(input: {
@@ -125,10 +127,18 @@ function ingestCodexCapabilityRow(input: {
   pending: Map<string, PendingCapabilityTool>;
   nestedByCall: Map<string, Array<{ toolName: string; server: string }>>;
   out: CapabilityObservation[];
+  host: { observed: boolean };
 }): void {
   const { line, index, session, pending, nestedByCall, out } = input;
   const row = safeParse(line);
-  if (!row || row.type !== "response_item") return;
+  if (!row) return;
+  if (row.type === 'event_msg' && row.payload?.type === 'item_completed') {
+    input.host.observed = true;
+    const actual = completedCodexMcp(row, session);
+    if (actual) rememberCapabilityObservation(out, actual);
+    return;
+  }
+  if (row.type !== "response_item") return;
   const payload = row.payload ?? {};
   const rowAt = ts(row.timestamp);
   if (["function_call", "custom_tool_call", "local_shell_call"].includes(payload.type)) {
@@ -136,7 +146,7 @@ function ingestCodexCapabilityRow(input: {
       const item: PendingCapabilityTool = {
         sourceId: `${session.sessionId}:${callId}`,
         sessionId: session.sessionId,
-        toolName: String(payload.name ?? payload.type),
+        toolName: recordedCodexToolName(payload),
         input: codexToolInput(payload),
         createdAt: rowAt || session.lastActivityAt,
         cwd: session.cwd ?? undefined,

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

@@ -71,6 +71,16 @@ function textBlocks(content: unknown): string[] {
   });
 }
 
+function visibleRole(row: Record<string, unknown>, message: Record<string, unknown>): string {
+  if (row.synthetic_reason != null || message.synthetic_reason != null) return "";
+  const role = message.role ?? row.role;
+  if (role != null) return String(role);
+  const type = message.type ?? row.type;
+  const index = message.prompt_index ?? row.prompt_index;
+  if (type === "user" && (typeof index !== "number" || !Number.isSafeInteger(index) || index < 0)) return "";
+  return typeof type === "string" ? type : "";
+}
+
 function parseLog(path: string, sessionId: string, fallbackTime: number, fullText = false): ParsedLog {
   let lines: string[];
   try { lines = readFileSync(path, "utf8").split("\n"); } catch {
@@ -87,7 +97,7 @@ function parseLog(path: string, sessionId: string, fallbackTime: number, fullTex
     const row = safeParse(line);
     if (!row) return;
     const message = row.message && typeof row.message === "object" ? row.message : row;
-    const role = String(message.role ?? row.role ?? "");
+    const role = visibleRole(row, message);
     if (role === "reasoning" || role === "system") return;
     const messageAt = ts(row.timestamp ?? message.timestamp);
     const createdAt = messageAt || fallbackTime + index;
@@ -154,9 +164,9 @@ export function scanGrok(maxFiles = MAX_FILES): Scan {
     try { stat = statSync(join(directory, "chat_history.jsonl")); } catch {
       try { stat = statSync(path); } catch { continue; }
     }
-    const parsed = parseLog(join(directory, "chat_history.jsonl"), sessionId, stat.mtimeMs);
     const updatedAt = ts(summary.updated_at) || stat.mtimeMs;
     const startedAt = ts(summary.created_at) || stat.birthtimeMs || updatedAt;
+    const parsed = parseLog(join(directory, "chat_history.jsonl"), sessionId, startedAt);
     const title = [summary.generated_title, summary.session_summary, parsed.firstUser]
       .find((value): value is string => typeof value === "string" && value.trim().length > 0);
     const cwd = typeof summary.info?.cwd === "string" ? summary.info.cwd : undefined;

package/apps/bridge/src/sessions/telemetry/execution-summaries.ts

@@ -0,0 +1,56 @@
+import type { CapabilityExecutionSummary, CapabilityUsageStatus, RemoteCapabilityUsageEvent } from '../../../../../packages/protocol/schema';
+import { MAX_CAPABILITY_USAGE_PAYLOAD_BYTES } from './wire-budget';
+
+/** Preserve execution attribution before recent call details are trimmed. */
+export function createExecutionSummaries() {
+  const rows = new Map<string, CapabilityExecutionSummary>();
+  const seen = new Set<string>();
+  return {
+    add(event: RemoteCapabilityUsageEvent, source: 'native-history' | 'transcript') {
+      if (event.kind === 'cli' || !event.sessionId || !event.agent) return;
+      const identity = JSON.stringify([event.agent, event.sessionId, event.sourceId]);
+      if (seen.has(identity)) return;
+      seen.add(identity);
+      const key = JSON.stringify([event.agent, event.sessionId, event.kind, event.name]);
+      const row = rows.get(key) ?? { sessionId: event.sessionId, agent: event.agent,
+        kind: event.kind, name: event.name, count: 0, failures: 0, cancelled: 0,
+        lastUsedAt: 0, source };
+      row.count++;
+      row.failures += event.outcome === 'error' ? 1 : 0;
+      row.cancelled += event.outcome === 'cancelled' ? 1 : 0;
+      row.lastUsedAt = Math.max(row.lastUsedAt, event.createdAt);
+      if (event.durationMs != null) {
+        row.durationMs = (row.durationMs ?? 0) + event.durationMs;
+        row.durationCount = (row.durationCount ?? 0) + 1;
+      }
+      rows.set(key, row);
+    },
+    merge(summary: CapabilityExecutionSummary) {
+      const key = JSON.stringify([summary.agent, summary.sessionId, summary.kind, summary.name]);
+      const previous = rows.get(key);
+      if (!previous) { rows.set(key, { ...summary }); return; }
+      previous.count += summary.count;
+      previous.failures += summary.failures;
+      previous.cancelled += summary.cancelled;
+      previous.lastUsedAt = Math.max(previous.lastUsedAt, summary.lastUsedAt);
+      if (summary.durationCount) {
+        previous.durationCount = (previous.durationCount ?? 0) + summary.durationCount;
+        previous.durationMs = (previous.durationMs ?? 0) + (summary.durationMs ?? 0);
+      }
+    },
+    rows: () => [...rows.values()].sort((a, b) => b.lastUsedAt - a.lastUsedAt).slice(0, 128),
+  };
+}
+
+export function budgetExecutionSummaries(rows: CapabilityExecutionSummary[],
+  envelope: Omit<CapabilityUsageStatus, 'events' | 'executionSummaries'>): CapabilityExecutionSummary[] {
+  const budget = Math.max(0, MAX_CAPABILITY_USAGE_PAYLOAD_BYTES - 8192
+    - Buffer.byteLength(JSON.stringify({ ...envelope, events: [], executionSummaries: [] })));
+  let bytes = 0;
+  return rows.filter(row => {
+    const size = Buffer.byteLength(JSON.stringify(row)) + 1;
+    if (bytes + size > budget) return false;
+    bytes += size;
+    return true;
+  }).slice(0, 128);
+}

package/apps/mcp/src/desktop/task-activity-worker.ts

@@ -1,7 +1,7 @@
 import { createInterface } from "node:readline";
 import { desktopTaskActivity } from "./task-activity";
 import { desktopTaskImage } from "./image";
-import { scanCapabilityUsage, scanSessions, scanSessionHistory } from "../../../bridge/src/sessions";
+import { scanRecordedCapabilityUsage, scanSessions, scanSessionHistory } from "../../../bridge/src/sessions";
 import { desktopSelectedMesh } from "./projection/selected-mesh";
 import { desktopUsageSessions } from "./projection/session-usage";
 import { desktopLiveCatalog } from "./live-catalog";
@@ -23,10 +23,10 @@ function cachedActivity(query: unknown, storePath?: string) {
   return result;
 }
 
-function cachedUsage(): unknown {
+async function cachedUsage(): Promise<unknown> {
   if (usageCache && Date.now() - usageCache.at < 120_000) return usageCache.result;
   const sessions = [...scanSessions().sessions, ...scanSessionHistory()];
-  const result = { ...scanCapabilityUsage(sessions), operation: "desktop.capability_usage",
+  const result = { ...await scanRecordedCapabilityUsage(sessions), operation: "desktop.capability_usage",
     sessions: desktopUsageSessions(sessions) };
   usageCache = { at: Date.now(), result };
   return result;
@@ -39,7 +39,7 @@ for await (const line of createInterface({ input: process.stdin, crlfDelay: Infi
     const request = JSON.parse(line) as { id: string; query: unknown; storePath?: string };
     const result = request.query && typeof request.query === "object"
       && (request.query as { operation?: string }).operation === "desktop.capability_usage"
-      ? cachedUsage()
+      ? await cachedUsage()
       : request.query && typeof request.query === "object"
         && (request.query as { operation?: string }).operation === "desktop.task_capabilities"
         ? desktopTaskCapabilities(request.query, request.storePath) ?? null

package/apps/mcp/src/http/README.md

@@ -0,0 +1,15 @@
+# Local HTTP service
+
+`http-server.ts` is the public entry point for the loopback MCP, OAuth and native
+desktop service. Listener addresses must be loopback addresses.
+
+`GET /healthz` and `GET /desktop/status` return bounded observations without
+starting provider CLIs or changing provider configuration. Desktop discovery
+uses the latest available hook observations; an unconfirmed status stays
+unconfirmed. Opening the Mac client does not wait for a Codex subprocess.
+
+Authenticated native operations use the desktop bridge. Pairing material and
+credentials are excluded from public status responses.
+## License
+
+Licensed under the GrantTap Commercial Source License. See LICENSE and NOTICE.

package/apps/mcp/src/http/http-server.ts

@@ -1,4 +1,3 @@
-import { refreshCodexHooks } from "../../../bridge/src/codex-hook-trust";
 /**
  * GrantTap MCP over Streamable HTTP + loopback OAuth with website consent.
  *
@@ -99,8 +98,7 @@ export async function startHttpMcpServer(options: ServeOptions = {}): Promise<{
       mcp: mcpUrl.href,
     });
   });
-  app.get("/desktop/status", async (_req, res) => {
-    await refreshCodexHooks();
+  app.get("/desktop/status", (_req, res) => {
     res.set("Cache-Control", "no-store");
     res.json(desktopStatusSnapshot(desktopBridge.socketPath));
   });

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.86
+npm install -g granttap-mcp@0.8.87
 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.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"
+        "\"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.87\";\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.86";
+const PACKAGE = "granttap-mcp@0.8.87";
 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.86",
+  "version": "0.8.87",
   "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-types.ts

@@ -46,6 +46,12 @@ export type RelayClientOptions = {
 };
 
 export type SendOptions = {
+  /** Negotiated opaque latest-state replay, independent of delivery ACKs. */
+  retainedState?: boolean;
+  stateKey?: string;
+  stateGroup?: string;
+  stateRevision?: number;
+  statePriority?: 0 | 1 | 2 | 3;
   /** Set by negotiated RelayClient transport; absent for older relays. */
   recipientRouting?: boolean;
   /** Reply only to the authenticated requester; absent means all authorized peers. */

package/packages/core/relay-client.ts

@@ -1,8 +1,9 @@
+import { retainedPayloadOptions } from "./retained-state";
 /** Shared authenticated relay transport. See README.md for delivery and encryption boundaries. */
 import WebSocket from "ws";
 import { ManagedRelayLease, RelaySocketHealth, RelayReconnectBackoff, RelayConnectionNotifications, relayUpgradeHeaders } from "./socket-lifecycle";
 import { OutboundFrameQueue, sendEncryptedPayload } from "./outbound-scheduler";
-import { openRelayMessage, parseRelayControl } from "./relay-inbound";
+import { openRelayMessage, parseRelayControl, waitForRelayPayload } from "./relay-inbound";
 import { consumeTaskJobOffer, type TaskDispatchListener } from "./task-dispatch";
 import { Payload, type Role } from "../protocol/schema";
 import { peerPublicKeys } from "./crypto";
@@ -17,6 +18,7 @@ type Listener = (p: Payload, peerPublicKey: string) => boolean | void | Promise<
 export class RelayClient {
   private ws?: WebSocket;
   private recipientRouting = false;
+  private retainedState = false;
   private frames?: OutboundFrameQueue;
   private listeners = new Set<Listener>();
   private readonly connections = new RelayConnectionNotifications();
@@ -61,6 +63,7 @@ export class RelayClient {
 
     this.intentionalClose = false;
     this.recipientRouting = false;
+    this.retainedState = false;
     const pending = Promise.resolve().then(() => this.opts.upgradeHeaders?.() ?? {})
       .then(headers => new Promise<void>((resolve, reject) => {
       // The room rides in the URL: the Cloudflare relay must pick a Durable
@@ -127,9 +130,10 @@ export class RelayClient {
   }
 
   private async onRaw(raw: string): Promise<void> {
-    const control = parseRelayControl(raw) as { type?: string; recipientRouting?: boolean } | null;
+    const control = parseRelayControl(raw) as { type?: string; recipientRouting?: boolean; retainedState?: boolean; retainedStateGroups?: boolean } | null;
     if (control?.type === "relay.capabilities" && control.recipientRouting === true) {
       this.recipientRouting = true;
+      this.retainedState = control.retainedState === true && control.retainedStateGroups === true;
       return;
     }
     if (control?.type === "relay.task-job") {
@@ -181,6 +185,7 @@ export class RelayClient {
     const ws = this.ws;
     if (!ws || ws.readyState !== WebSocket.OPEN) throw new Error("relay not connected");
     if (!this.frames) throw new Error("relay not connected");
+    options = { ...retainedPayloadOptions(payload), ...options, retainedState: this.retainedState };
     if (options.peerPublicKey) {
       await this.sendToPeer(payload, options.peerPublicKey, options);
       return;
@@ -208,7 +213,7 @@ export class RelayClient {
     if (!peerPublicKeys(this.cfg.peerPublicKey, this.cfg.extraPeerPublicKeys).includes(peerPublicKey)
       || !this.peerIsAllowed(peerPublicKey)) throw new Error("controller peer is not authorized");
     if (!this.frames) throw new Error("relay not connected");
-    await this.frames.send(sealEnvelope({ ...this.cfg, peerPublicKey }, payload, this.otherRole(), { ...options, recipientRouting: this.recipientRouting }), true);
+    await this.frames.send(sealEnvelope({ ...this.cfg, peerPublicKey }, payload, this.otherRole(), { ...retainedPayloadOptions(payload), ...options, retainedState: this.retainedState, recipientRouting: this.recipientRouting }), true);
   }
 
   setSessionKey(sessionId: string, key: string): void {
@@ -226,7 +231,7 @@ export class RelayClient {
     to: Role | "all" = this.otherRole(),
     options: SendOptions = {},
   ): Promise<void> {
-    await this.send(sealSessionPayload(payload, sessionId, this.sessionKeys.get(sessionId)), to, options);
+    await this.send(sealSessionPayload(payload, sessionId, this.sessionKeys.get(sessionId)), to, { ...retainedPayloadOptions(payload), ...options });
   }
 
   /** Register before connect so only durable receivers advertise task-job support. */
@@ -253,21 +258,7 @@ export class RelayClient {
 
   /** Resolve with the first payload matching `pred`, or reject on timeout. */
   waitFor<T extends Payload>(pred: (p: Payload) => p is T, timeoutMs: number): Promise<T> {
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        off();
-        reject(new Error("waitFor timeout"));
-      }, timeoutMs);
-      const off = this.onMessage((p) => {
-        if (pred(p)) {
-          clearTimeout(timer);
-          off();
-          resolve(p);
-          return true;
-        }
-        return false;
-      });
-    });
+    return waitForRelayPayload(listener => this.onMessage(listener), pred, timeoutMs);
   }
 
   close(): void {
@@ -281,6 +272,10 @@ export class RelayClient {
     this.ws = undefined;
   }
 
+  get supportsRetainedState(): boolean {
+    return this.retainedState;
+  }
+
   get isConnected(): boolean {
     return this.ws?.readyState === WebSocket.OPEN;
   }

package/packages/core/relay-envelope.ts

@@ -20,18 +20,22 @@ export function sealEnvelope(
   options: SendOptions = {},
 ): string {
   const { nonce, box } = seal(payload, cfg.peerPublicKey, cfg.mySecretKey);
+  const retained = cfg.role === "machine" && to === "phone" && options.retainedState && options.stateKey;
   const envelope: Envelope = {
+    ...(retained ? { stateKey: options.stateKey, stateRevision: options.stateRevision,
+      statePriority: options.statePriority, stateGroup: options.stateGroup } : {}),
     v: PROTOCOL_VERSION,
     room: cfg.room,
     from: cfg.role,
     to,
     senderId: cfg.senderId,
-    recipientKeyId: options.recipientRouting ? publicKeyIdentifier(cfg.peerPublicKey) : undefined,
-    deliveryId: options.reliable === false
+    recipientKeyId: options.recipientRouting || retained ? publicKeyIdentifier(cfg.peerPublicKey) : undefined,
+    deliveryId: retained || options.reliable === false
       ? undefined
       : options.deliveryId ?? randomUUID(),
     wake: options.wake,
-    expiresAt: options.ttlMs == null ? undefined : Date.now() + options.ttlMs,
+    expiresAt: retained ? Date.now() + 7 * 86400000 - 300000
+      : options.ttlMs == null ? undefined : Date.now() + options.ttlMs,
     nonce,
     box,
   };

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

@@ -54,3 +54,5 @@ function unwrapTaskPayload(payload: Payload, role: string, sessionKeys: Map<stri
     || sessionId !== payload.sessionId) return undefined;
   return inner.data;
 }
+
+export { waitForRelayPayload } from "./wait-for";

package/packages/core/relay-inbound/wait-for.ts

@@ -0,0 +1,19 @@
+import type { Payload } from "../../protocol/schema";
+
+/** One bounded payload wait, cancelled by its own match or deadline. */
+export function waitForRelayPayload<T extends Payload>(
+  subscribe: (listener: (payload: Payload) => boolean | void) => () => void,
+  predicate: (payload: Payload) => payload is T,
+  timeoutMs: number,
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => { off(); reject(new Error("waitFor timeout")); }, timeoutMs);
+    const off = subscribe(payload => {
+      if (!predicate(payload)) return;
+      clearTimeout(timer);
+      off();
+      resolve(payload);
+      return true;
+    });
+  });
+}

package/packages/core/retained-state/README.md

@@ -0,0 +1,23 @@
+# Relay state publication
+
+Public entry: `retainedPayloadOptions`. The transport negotiates latest-state
+retention before adding its opaque metadata. It retains catalogs, task-key
+grants, Mesh snapshots and transcript heads for each approved recipient. Commands,
+approval decisions and historical transcript pages never replace a current head.
+The relay keeps only ciphertext, bounded by its room capacity and expiry.
+
+Key grants replay first, followed by catalogs, Mesh and heads. Generation times
+remain unchanged, so saved work cannot pretend to be a new provider response.
+A catalog with historical tasks occupies a separate slot from the active-only
+catalog. Current heads are published in fair batches of at most 32 even when no
+phone subscribes, independently of catalog and heartbeat publication.
+
+The phone's queue is restored through the separate durable task-job API. Relay
+state caching does not execute commands or change provider policy. Older relays
+continue using live updates and the existing acknowledged mailbox.
+
+Tests live in `tests/` and run with the repository's test and release commands.
+
+GrantTap Commercial Source License; see the repository LICENSE.
+
+Opaque group identifiers keep each scoped key with its encrypted snapshots during eviction. Grants for historical pages or other noncached replies are not retained as read state. Oversized read payloads stay live rather than reserving an orphan key slot.

package/packages/core/retained-state/index.ts

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+import type { Payload } from '../../protocol/schema';
+import type { SendOptions } from '../relay-client-types';
+
+/** Only replaceable read state is retained. Decisions and commands are never replayed as state. */
+export function retainedPayloadOptions(payload: Payload): SendOptions {
+  let scope: string | undefined;
+  let revision: number | undefined;
+  let session: string | undefined;
+  let priority: 0 | 1 | 2 | 3 = 1;
+  switch (payload.type) {
+    case 'sessions.status': scope = payload.history ? 'catalog:history' : 'catalog'; revision = payload.generatedAt; break;
+    case 'session.key.grant': session = payload.sessionId; scope = `key:${payload.sessionId}`; revision = payload.createdAt; priority = 0; break;
+    case 'session.activity':
+      session = payload.sessionId;
+      if (!payload.history?.requestedCursor) scope = `activity:${payload.sessionId}:${payload.threadId ?? ''}`;
+      revision = payload.generatedAt; priority = 3; break;
+    case 'mesh.snapshot': session = payload.sessionId; scope = `mesh:${payload.projectId}`; revision = payload.generatedAt; priority = 2; break;
+    case 'capability.usage.status': session = 'capability-usage'; scope = 'capability-usage';
+      revision = payload.generatedAt; priority = 2; break;
+  }
+  if (!scope || !Number.isSafeInteger(revision) || revision! < 0
+    || Buffer.byteLength(JSON.stringify(payload)) > 900000) return {};
+  return { stateGroup: session ? createHash('sha256').update(`session:${session}`).digest('hex') : undefined, stateKey: createHash('sha256').update(scope).digest('hex'), stateRevision: revision, statePriority: priority };
+}

package/packages/protocol/messages/capabilities.ts

@@ -143,10 +143,27 @@ export const CapabilityUsageTotal = z.object({
 }).strict();
 export type CapabilityUsageTotal = z.infer<typeof CapabilityUsageTotal>;
 
+/** Recorded usage before the recent-call transport budget is applied. */
+export const CapabilityExecutionSummary = z.object({
+  sessionId: z.string().trim().min(1).max(256),
+  agent: z.string().trim().min(1).max(80),
+  kind: z.enum(["mcp", "skill"]),
+  name: CapabilityName,
+  count: z.number().int().positive(),
+  failures: z.number().int().nonnegative(),
+  cancelled: z.number().int().nonnegative(),
+  lastUsedAt: z.number().nonnegative(),
+  durationMs: z.number().int().nonnegative().optional(),
+  durationCount: z.number().int().nonnegative().optional(),
+  source: z.enum(["native-history", "transcript"]),
+}).strict();
+export type CapabilityExecutionSummary = z.infer<typeof CapabilityExecutionSummary>;
+
 export const CapabilityUsageStatus = z.object({
   type: z.literal("capability.usage.status"),
   events: z.array(CapabilityUsageEvent).max(200),
   totals: z.array(CapabilityUsageTotal).max(160).optional(),
+  executionSummaries: z.array(CapabilityExecutionSummary).max(128).optional(),
   generatedAt: z.number(),
 });
 export type CapabilityUsageStatus = z.infer<typeof CapabilityUsageStatus>;

package/packages/protocol/schema.ts

@@ -202,6 +202,10 @@ export type Payload = z.infer<typeof Payload>;
 
 /** The routed unit. `nonce`+`box` are the sealed Payload; relay cannot open it. */
 export const Envelope = z.object({
+  stateGroup: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+  stateKey: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+  stateRevision: z.number().int().nonnegative().optional(),
+  statePriority: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional(),
   recipientKeyId: z.string().regex(/^[a-f0-9]{64}$/).optional(),
   v: z.literal(PROTOCOL_VERSION),
   room: z.string(),