granttap-mcp 0.8.119 → 0.8.121

package/apps/bridge/src/codex-questions/README.md

@@ -38,3 +38,8 @@ Recovery checks the private request's owning room, restores a discovered source
 inside the native Codex sessions root, and sends that exact question or its terminal
 state through the priority device channel. It does not require an admitted catalog,
 start a provider turn, send another wake notification, or schedule a full scan.
+
+Question publication reads the private record collection once per batch, then
+validates each matching question freshly before sending. Targeted notification
+replay reads the requested identity directly. This keeps multiple chats from
+repeatedly parsing the same collection.

package/apps/bridge/src/codex-questions/index.ts

@@ -13,7 +13,12 @@ const RETENTION_MS = 24 * 60 * 60_000;
 /** Phone questions travel as device-encrypted control events, independently of task-key grants. */
 export async function publishCodexQuestions(client: RelayClient, sessions: SessionInfo[],
   options: { replay?: boolean; peerPublicKey?: string; requestId?: string } = {}): Promise<void> {
-  for (const session of sessions.filter(s => s.agent === 'codex')) {
+  const nativeSessions = sessions.filter(s => s.agent === 'codex');
+  if (!nativeSessions.length) return;
+  const initial = options.requestId ? [readQuestion(options.requestId)].filter((record): record is QuestionRecord => !!record)
+    : storedQuestions();
+  const batch = new Map(initial.map(record => [record.requestId, record]));
+  for (const session of nativeSessions) {
     const path = nativeTranscriptSource(session);
     if (!path) continue;
     let observed;
@@ -22,13 +27,20 @@ export async function publishCodexQuestions(client: RelayClient, sessions: Sessi
     for (const question of observed.questions) {
       if (Date.now() - question.createdAt > RETENTION_MS) continue;
       const existing = readQuestion(question.requestId);
-      if (!existing) saveQuestion({ ...question, room: client.room, sourcePath: path });
-      else if (existing.room === client.room && existing.sourcePath !== path) saveQuestion({ ...existing, sourcePath: path });
+      if (!existing) {
+        const record = { ...question, room: client.room, sourcePath: path };
+        saveQuestion(record); batch.set(record.requestId, record);
+      } else {
+        if (existing.room === client.room && existing.sourcePath !== path) saveQuestion({ ...existing, sourcePath: path });
+        batch.set(existing.requestId, existing);
+      }
     }
-    const records = storedQuestions().filter(q => q.room === client.room && q.sessionId === session.sessionId
+    const records = [...batch.values()].filter(q => q.room === client.room && q.sessionId === session.sessionId
       && (!options.requestId || q.requestId === options.requestId))
       .sort((a, b) => a.createdAt - b.createdAt || a.index - b.index);
-    for (const record of records) {
+    for (const candidate of records) {
+      const record = readQuestion(candidate.requestId);
+      if (!record || record.room !== client.room || record.sessionId !== session.sessionId) continue;
       const expired = Date.now() - record.createdAt > RETENTION_MS;
       if (observed.answered.has(record.requestId) && !record.answered) {
         record.answered = true;

package/apps/bridge/src/engine/runtime/engine-projects.ts

@@ -18,6 +18,7 @@ import { RepositoryGraphJobs } from "./repository-graph-jobs";
 import { fitRepositoryGraph } from "./repository-graph/fit";
 import { RepositoryGraphCache } from "./repository-graph/cache";
 import { repositorySourceMap } from "./repository-graph/source-map";
+import { repositorySourceFingerprint } from "./repository-graph/source-state";
 
 export type LocalProjectBinding = {
   summary: ProjectBindingSummary;
@@ -193,15 +194,23 @@ export async function projectRepositoryGraphs(
   if (!engineFeatureEnabled(options.env ?? process.env)) return [];
   const client = options.client;
   const repositories = [...new Map(bindings.map((item) => [item.repositoryId, item])).values()].slice(0, 64);
+  const observations = await Promise.all(repositories.map(async binding => {
+    const fingerprint = binding.localPathHint
+      ? await repositorySourceFingerprint(binding.localPathHint, binding.revision, { fresh: !options.background })
+      : undefined;
+    return fingerprint ? { fingerprint, reusable: (graph: ProjectRepositoryGraph) =>
+      ['COMPLETE', 'INCOMPLETE'].includes(graph.analysisStatus ?? '') } : undefined;
+  }));
   const graphs = options.background
-    ? repositories.map((binding) => repositoryGraphJobs.read(
+    ? repositories.map((binding, index) => repositoryGraphJobs.read(
       JSON.stringify([projectId, binding.repositoryId, binding.revision]),
       () => analyzeRepositoryGraph(client, projectId, binding.repositoryId, 120_000, binding.revision),
-      options.priority ?? 0,
+      options.priority ?? 0, false, observations[index],
     ))
-    : await Promise.all(repositories.map((binding) => repositoryGraphJobs.refresh(
+    : await Promise.all(repositories.map((binding, index) => repositoryGraphJobs.refresh(
       JSON.stringify([projectId, binding.repositoryId, binding.revision]),
       () => analyzeRepositoryGraph(client, projectId, binding.repositoryId, 120_000, binding.revision),
+      Number.MAX_SAFE_INTEGER, observations[index],
     )));
   return boundRepositoryGraphs(graphs.filter((item): item is ProjectRepositoryGraph => item != null));
 }

package/apps/bridge/src/engine/runtime/repository-graph/README.md

@@ -18,3 +18,9 @@ under the repository's `tests/engine` harness.
 
 License: this module is distributed under the GrantTap Commercial Source License
 in the repository-root `LICENSE` file.
+
+Successful background reports retain an internal observation of Git-visible
+source state. Unchanged state reuses the report across time and MCP restart;
+changed state retains the existing analysis cooldown. Explicit refresh forces
+analysis, and temporary failures keep their retry behavior. Source observation
+is implemented by `source-state/`; its tests cover dirty edits and path changes.

package/apps/bridge/src/engine/runtime/repository-graph/cache.ts

@@ -9,6 +9,7 @@ export class RepositoryGraphCache {
     read(key: string): {
         value: ProjectRepositoryGraph;
         savedAt: number;
+        sourceFingerprint?: string;
     } | undefined {
         try {
             const path = this.path(key);
@@ -19,18 +20,22 @@ export class RepositoryGraphCache {
             if (record.key !== key || !Number.isFinite(record.savedAt) || !graph.success
                 || !['COMPLETE', 'INCOMPLETE'].includes(graph.data.analysisStatus ?? ''))
                 return undefined;
-            return { value: graph.data, savedAt: record.savedAt };
+            const sourceFingerprint = typeof record.sourceFingerprint === 'string'
+                && /^[a-f0-9]{64}$/.test(record.sourceFingerprint) ? record.sourceFingerprint : undefined;
+            return { value: graph.data, savedAt: record.savedAt,
+                ...(sourceFingerprint ? { sourceFingerprint } : {}) };
         }
         catch {
             return undefined;
         }
     }
-    write(key: string, value: ProjectRepositoryGraph): void {
+    write(key: string, value: ProjectRepositoryGraph, sourceFingerprint?: string): void {
         if (!['COMPLETE', 'INCOMPLETE'].includes(value.analysisStatus ?? ''))
             return;
         const bounded = fitRepositoryGraph(value, 192 * 1024);
         if (!bounded) return;
-        const json = JSON.stringify({ key, value: bounded, savedAt: this.now() });
+        const json = JSON.stringify({ key, value: bounded, savedAt: this.now(),
+            ...(sourceFingerprint && /^[a-f0-9]{64}$/.test(sourceFingerprint) ? { sourceFingerprint } : {}) });
         if (Buffer.byteLength(json) > 256 * 1024)
             return;
         try {

package/apps/bridge/src/engine/runtime/repository-graph/source-state/README.md

@@ -0,0 +1,24 @@
+# Repository source observation
+
+Public entry: `index.ts`. This private machine-side observation identifies the
+bound checkout, Git revision, staged and unstaged path status, and metadata of
+changed or untracked files. It includes repeated edits with the same Git status,
+renames, deletion and Unicode paths. Ignored build output does not invalidate it.
+It reads metadata without parsing source or executing a build.
+
+Background observations share in-flight work and a five-second observation
+window. Explicit refresh bypasses it. Output, path count, filesystem concurrency
+and retained observations are bounded. Unreadable or invalid state remains
+unknown; it never becomes proof of unchanged source.
+
+Repository graph jobs retain a successful report while this observation is
+unchanged, including across MCP restart. A changed observation retains the
+existing analysis cooldown; explicit builds still force analysis. Failed or
+legacy reports retain normal retry behavior. No provider policy, grants,
+repository files or user projects are changed.
+
+Behavior tests live in `tests/` and `../tests/unchanged-source.test.ts`.
+
+## License
+
+GrantTap Commercial Source License. See [LICENSE](../../../../../../../LICENSE).

package/apps/bridge/src/engine/runtime/repository-graph/source-state/index.ts

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { readRepositoryGit } from '../../../../mesh/catalog';
+
+const cached = new Map<string, { at: number; value?: string }>();
+const pending = new Map<string, Promise<string | undefined>>();
+
+function changedPaths(status: string): string[] | undefined {
+  const fields = status.split('\0');
+  const paths: string[] = [];
+  for (let index = 0; index < fields.length; index++) {
+    const field = fields[index]!;
+    if (!field) continue;
+    if (field.length < 4 || field[2] !== ' ') return undefined;
+    paths.push(field.slice(3));
+    if (/[RC]/.test(field.slice(0, 2))) {
+      const previous = fields[++index];
+      if (!previous) return undefined;
+      paths.push(previous);
+    }
+    if (paths.length > 4096) return undefined;
+  }
+  return [...new Set(paths)].sort();
+}
+
+async function capture(root: string, revision?: string): Promise<string | undefined> {
+  try {
+    const directory = await realpath(root);
+    const status = await readRepositoryGit(directory,
+      ['status', '--porcelain=v1', '--untracked-files=all', '-z'], { timeoutMs: 5_000, maxBuffer: 4 * 1024 * 1024 });
+    if (status === undefined) return undefined;
+    const paths = changedPaths(status);
+    if (!paths) return undefined;
+    const hash = createHash('sha256').update(JSON.stringify([directory, revision])).update(status);
+    for (let start = 0; start < paths.length; start += 16) {
+      const rows = await Promise.all(paths.slice(start, start + 16).map(async path => {
+        const absolute = resolve(directory, path);
+        if (isAbsolute(path) || !absolute.startsWith(directory + sep)) throw new Error('Invalid repository path');
+        try {
+          const stat = await lstat(absolute, { bigint: true });
+          return [path, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs, stat.mode].map(String);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [path, 'missing'];
+          throw error;
+        }
+      }));
+      hash.update(JSON.stringify(rows));
+    }
+    return hash.digest('hex');
+  } catch { return undefined; }
+}
+
+/** Observe committed and uncommitted source without parsing it or executing a build. */
+export function repositorySourceFingerprint(root: string, revision?: string,
+  options: { fresh?: boolean } = {}): Promise<string | undefined> {
+  const key = JSON.stringify([root, revision]), previous = cached.get(key), now = Date.now();
+  if (!options.fresh && previous && now >= previous.at && now - previous.at < 5_000) {
+    return Promise.resolve(previous.value);
+  }
+  const active = pending.get(key);
+  if (!options.fresh && active) return active;
+  const next = capture(root, revision).then(value => {
+    if (pending.get(key) === next) {
+      cached.delete(key);
+      if (cached.size >= 128) cached.delete(cached.keys().next().value!);
+      cached.set(key, { value, at: Date.now() });
+    }
+    return value;
+  }).finally(() => { if (pending.get(key) === next) pending.delete(key); });
+  pending.set(key, next);
+  return next;
+}

package/apps/bridge/src/engine/runtime/repository-graph-jobs.ts

@@ -1,3 +1,4 @@
+type SourceObservation<T> = { fingerprint: string; reusable?: (value: T) => boolean };
 /** Serializes expensive repository analysis without blocking Mesh snapshots. */
 export class RepositoryGraphJobs<T> {
   private readonly entries = new Map<string, {
@@ -5,6 +6,7 @@ export class RepositoryGraphJobs<T> {
     retryAt: number;
     pending: boolean;
     listeners: Array<(value: T | undefined) => void>;
+    sourceFingerprint?: string;
   }>();
   private readonly queue: Array<{
     key: string; run: () => Promise<T | undefined>; priority: number;
@@ -16,34 +18,50 @@ export class RepositoryGraphJobs<T> {
     private readonly successMs = 120_000,
     private readonly failureMs = 300_000,
     private readonly capacity = 32,
-    private readonly storage?: {read(key:string):{value:T;savedAt:number}|undefined;write(key:string,value:T):void},
+    private readonly storage?: {read(key:string):{value:T;savedAt:number;sourceFingerprint?:string}|undefined;
+      write(key:string,value:T,sourceFingerprint?:string):void},
   ) {}
 
-  read(key: string, run: () => Promise<T | undefined>, priority = 0, force = false): T | undefined {
+  read(key: string, run: () => Promise<T | undefined>, priority = 0, force = false,
+    source?: SourceObservation<T>): T | undefined {
     if (!this.entries.has(key)) {
       const saved = this.storage?.read(key);
       if (saved) this.entries.set(key, {value:saved.value,retryAt:saved.savedAt+this.successMs,
-        pending:false,listeners:[]});
+        pending:false,listeners:[],sourceFingerprint:saved.sourceFingerprint});
     }
     const previous = this.entries.get(key);
     if (previous?.pending) return previous.value;
     if (previous && !force && this.now() < previous.retryAt) return previous.value;
+    if (!force && source && previous?.value !== undefined
+      && previous.sourceFingerprint === source.fingerprint && source.reusable?.(previous.value) !== false) {
+      return previous.value;
+    }
     if (!this.admit(priority)) return undefined;
     if (!previous && this.entries.size >= this.capacity * 2) {
       const oldest = [...this.entries].find(([, entry]) => !entry.pending)?.[0];
       if (!oldest) return undefined;
       this.entries.delete(oldest);
     }
-    this.entries.set(key, { value: previous?.value, retryAt: 0, pending: true, listeners: [] });
+    this.entries.set(key, { value: previous?.value, retryAt: 0, pending: true, listeners: [],
+      sourceFingerprint: source?.fingerprint });
+    const admitted = this.entries.get(key);
     const before = this.queue.findIndex((job) => job.priority < priority);
-    this.queue.splice(before < 0 ? this.queue.length : before, 0, { key, run, priority });
+    const observedRun = async () => {
+      const value = await run();
+      if (value !== undefined && source?.reusable?.(value) === false && this.entries.get(key) === admitted) {
+        admitted!.sourceFingerprint = undefined;
+      }
+      return value;
+    };
+    this.queue.splice(before < 0 ? this.queue.length : before, 0, { key, run: observedRun, priority });
     void this.drain();
     return previous?.value;
   }
 
   /** A requested build joins the same revision's automatic job and raises its queue priority. */
-  refresh(key: string, run: () => Promise<T | undefined>, priority = Number.MAX_SAFE_INTEGER): Promise<T | undefined> {
-    if (!this.entries.get(key)?.pending) this.read(key, run, priority, true);
+  refresh(key: string, run: () => Promise<T | undefined>, priority = Number.MAX_SAFE_INTEGER,
+    source?: SourceObservation<T>): Promise<T | undefined> {
+    if (!this.entries.get(key)?.pending) this.read(key, run, priority, true, source);
     const entry = this.entries.get(key);
     if (!entry?.pending) return Promise.resolve(undefined);
     const index = this.queue.findIndex(job => job.key === key);
@@ -103,12 +121,13 @@ export class RepositoryGraphJobs<T> {
         let value: T | undefined;
         try { value = await job.run(); } catch { /* Retry after backoff. */ }
         if (this.entries.get(job.key) !== entry) continue;
-        if (value !== undefined) this.storage?.write(job.key, value);
+        if (value !== undefined) this.storage?.write(job.key, value, entry?.sourceFingerprint);
         this.entries.set(job.key, {
           value,
           retryAt: this.now() + (value === undefined ? this.failureMs : this.successMs),
           pending: false,
           listeners: [],
+          sourceFingerprint: entry?.sourceFingerprint,
         });
         for (const listener of entry?.listeners ?? []) listener(value);
       }

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

@@ -20,7 +20,7 @@ import type { MeshStore } from "../store";
 import { queueProjectBindingSync } from "../../engine/runtime/engine-projects";
 import { isCursorTaskCloneId } from "../../sessions/cursor/catalog";
 import { localTaskTransfers } from '../../task-transfer';
-export { inspectRepositoryAsync, inspectWorkingTreeAsync } from "./repository-inspection";
+export { inspectRepositoryAsync, inspectWorkingTreeAsync, readRepositoryGit } from "./repository-inspection";
 export { prepareMonitorInspection } from "./monitor-inspection";
 import type { CatalogInspection } from "./monitor-inspection";
 export type { CatalogInspection } from "./monitor-inspection";

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

@@ -7,18 +7,20 @@ const waiting: Array<() => void> = [];
 const pending = new Map<string, Promise<RepositoryFacts>>();
 
 /** Native read-only Git work stays bounded without blocking relay callbacks. */
-function git(cwd: string, args: string[], status = false): Promise<string | undefined> {
+export function readRepositoryGit(cwd: string, args: string[],
+  options: { timeoutMs?: number; maxBuffer?: number } = {}): Promise<string | undefined> {
   return new Promise(resolve => {
     const run = () => {
       running++;
       const done = (error: Error | null, stdout = "") => {
         running--;
         waiting.shift()?.();
-        resolve(error ? undefined : status ? stdout : stdout.trim() || undefined);
+        resolve(error ? undefined : stdout);
       };
       try {
-        execFile("git", ["-C", cwd, ...args], {
-          encoding: "utf8", timeout: status ? 5_000 : 2_000, maxBuffer: (status ? 4 : 1) * 1024 * 1024, windowsHide: true,
+        execFile("git", ["--no-optional-locks", "-C", cwd, ...args], {
+          encoding: "utf8", timeout: options.timeoutMs ?? 2_000,
+          maxBuffer: options.maxBuffer ?? 1024 * 1024, windowsHide: true,
         }, done);
       } catch { done(new Error("Repository command could not start")); }
     };
@@ -26,6 +28,10 @@ function git(cwd: string, args: string[], status = false): Promise<string | unde
   });
 }
 
+async function git(cwd: string, args: string[]): Promise<string | undefined> {
+  return (await readRepositoryGit(cwd, args))?.trim() || undefined;
+}
+
 async function inspect(cwd: string): Promise<RepositoryFacts> {
   const worktree = await git(cwd, ["rev-parse", "--show-toplevel"]);
   const root = worktree ?? cwd;
@@ -50,6 +56,7 @@ export function inspectRepositoryAsync(cwd: string): Promise<RepositoryFacts> {
 
 /** A fresh working-tree observation shares the bounded, nonblocking Git command pool. */
 export async function inspectWorkingTreeAsync(cwd: string): Promise<boolean | undefined> {
-  const output = await git(cwd, ['status', '--porcelain=v1', '--untracked-files=normal', '-z'], true);
+  const output = await readRepositoryGit(cwd, ['status', '--porcelain=v1', '--untracked-files=normal', '-z'],
+    { timeoutMs: 5_000, maxBuffer: 4 * 1024 * 1024 });
   return output === undefined ? undefined : output.length > 0;
 }

package/apps/bridge/src/mesh/repository-details/README.md

@@ -20,6 +20,15 @@ session's initial workspace. Titles and chat prose never select repositories.
 The Apple client uses this evidence for placement, preserving durable Task
 identity and access scope.
 
+Background Mesh publication shares one asynchronous checkout observation across
+admission, Graph selection and repository details. It reads working-tree status
+on every publication. Bounded history for an unchanged commit can be reused for
+up to 30 seconds in the background; explicit observations bypass that cache.
+History commands name the observed commit so a concurrent commit cannot silently
+substitute another revision. At most 128 history observations remain in memory.
+History, status and checkout metadata share a maximum of two native Git
+subprocesses, keeping background publication off the relay's event loop.
+
 Behavior tests live in `tests/`. See the [runtime README](../../../../../README.md).
 
 Licensed under the [GrantTap Commercial Source License](../../../../../LICENSE).

package/apps/bridge/src/mesh/repository-details/git.ts

@@ -0,0 +1,6 @@
+import { readRepositoryGit } from "../catalog";
+
+export async function git(path: string, args: string[]): Promise<string | undefined> {
+  const output = await readRepositoryGit(path, args, { maxBuffer: 256 * 1_024 });
+  return output?.trim();
+}

package/apps/bridge/src/mesh/repository-details/history.ts

@@ -0,0 +1,47 @@
+import type { ProjectRepositoryDetails } from "../../../../../packages/protocol/schema";
+import { git } from "./git";
+
+type History = Pick<ProjectRepositoryDetails, "commits" | "contributors" | "commitCount" | "contributorCount">;
+const cached = new Map<string, { value: History; at: number }>();
+const pending = new Map<string, Promise<History>>();
+const clean = (text: string, limit: number) => text.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, limit);
+
+async function read(path: string, revision?: string): Promise<History> {
+  const reference = revision ?? "HEAD";
+  const [history, shortlog, count] = await Promise.all([
+    git(path, ["log", "-8", "--format=%H%x1f%an%x1f%ct%x1f%s%x1e", reference]),
+    git(path, ["shortlog", "-sn", reference]), git(path, ["rev-list", "--count", reference]),
+  ]);
+  const commits = (history ?? "").split("\u001e").flatMap(row => {
+    const [sha, author, time, subject] = row.trim().split("\u001f");
+    return sha && /^[a-f0-9]{40,64}$/.test(sha) && Number.isFinite(Number(time)) && Number(time) >= 0
+      ? [{ sha, author: clean(author ?? "", 160), subject: clean(subject ?? "", 240), committedAt: Number(time) * 1_000 }] : [];
+  });
+  const contributors = (shortlog ?? "").split("\n").flatMap(row => {
+    const match = row.match(/^\s*(\d+)\s+(.+)$/);
+    return match ? [{ name: clean(match[2]!, 160), commits: Number(match[1]) }] : [];
+  });
+  return { commits, contributors: contributors.slice(0, 12),
+    commitCount: count == null ? (revision ? undefined : 0) : Number(count),
+    contributorCount: shortlog == null ? (revision ? undefined : 0) : contributors.length };
+}
+
+/** Only background history is reused; checkout metadata and working-tree state remain fresh. */
+export async function repositoryHistory(path: string, revision: string | undefined, background: boolean): Promise<History> {
+  const key = JSON.stringify([path, revision]), previous = cached.get(key), now = Date.now();
+  if (background && previous && now >= previous.at && now - previous.at < 30_000) {
+    return structuredClone(previous.value);
+  }
+  const active = pending.get(key);
+  if (background && active) return structuredClone(await active);
+  const next = read(path, revision).then(value => {
+    if (pending.get(key) === next) {
+      cached.delete(key);
+      if (cached.size >= 128) cached.delete(cached.keys().next().value!);
+      cached.set(key, { value: structuredClone(value), at: Date.now() });
+    }
+    return value;
+  }).finally(() => { if (pending.get(key) === next) pending.delete(key); });
+  pending.set(key, next);
+  return structuredClone(await next);
+}

package/apps/bridge/src/mesh/repository-details/index.ts

@@ -1,53 +1,38 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
 import { ProjectRepositoryDetails, type MeshSnapshot, type ProjectBindingSummary } from "../../../../../packages/protocol/schema";
-import { canonicalRepositoryIdentity } from "../identity";
+import { inspectRepositoryAsync, type RepositoryFacts } from "../catalog";
+import { git } from "./git";
+import { repositoryHistory } from "./history";
 
-const run = promisify(execFile);
-async function git(path: string, args: string[]): Promise<string | undefined> {
-  try {
-    const result=await run("git",["--no-optional-locks","-C",path,...args],
-      {encoding:"utf8",timeout:2_000,maxBuffer:256*1_024});
-    return result.stdout.trim();
-  } catch { return undefined; }
+type ObservationOptions = { background?: boolean; inspect?: (path: string) => RepositoryFacts };
+
+async function observed(path: string, options: ObservationOptions): Promise<RepositoryFacts> {
+  try { if (options.inspect) return options.inspect(path); }
+  catch { /* Removed paths still need an explicit unavailable report. */ }
+  return inspectRepositoryAsync(path);
 }
-const clean = (text: string, limit: number) => text.replace(/[\u0000-\u001f\u007f]/g," ").trim().slice(0,limit);
 
-async function read(binding: ProjectBindingSummary): Promise<ProjectRepositoryDetails> {
+async function read(binding: ProjectBindingSummary, options: ObservationOptions): Promise<ProjectRepositoryDetails> {
   const path=binding.localPathHint!;
-  const root=await git(path,["rev-parse","--show-toplevel"]);
+  const facts = await observed(path, options);
+  const root = facts.worktree;
   const base={projectId:binding.projectId,repositoryId:binding.repositoryId,endpointId:binding.endpointId,
     commits:[],contributors:[],observedAt:Date.now()};
   if (!root) {
     const exists=await import("node:fs/promises").then(fs=>fs.stat(path).then(s=>s.isDirectory(),()=>false));
     return {...base,status:exists ? "not_git" : "unavailable"};
   }
-  const [remote,revision,branch,status,history,shortlog,count]=await Promise.all([
-    git(root,["remote","get-url","origin"]),git(root,["rev-parse","--verify","HEAD"]),
-    git(root,["symbolic-ref","--quiet","--short","HEAD"]),
+  const [status, history] = await Promise.all([
     git(root,["status","--porcelain=v1","--untracked-files=normal"]),
-    git(root,["log","-8","--format=%H%x1f%an%x1f%ct%x1f%s%x1e","HEAD"]),
-    git(root,["shortlog","-sn","HEAD"]),git(root,["rev-list","--count","HEAD"]),
+    repositoryHistory(root, facts.revision, options.background === true),
   ]);
-  const commits=(history ?? "").split("\u001e").flatMap(row=>{
-    const [sha,author,time,subject]=row.trim().split("\u001f");
-    return sha && /^[a-f0-9]{40,64}$/.test(sha) && Number.isFinite(Number(time)) && Number(time)>=0
-      ? [{sha,author:clean(author ?? "",160),subject:clean(subject ?? "",240),committedAt:Number(time)*1_000}] : [];
-  });
-  const contributors=(shortlog ?? "").split("\n").flatMap(row=>{
-    const match=row.match(/^\s*(\d+)\s+(.+)$/);
-    return match ? [{name:clean(match[2]!,160),commits:Number(match[1])}] : [];
-  });
-  return ProjectRepositoryDetails.parse({...base,status:"ready",
-    canonicalRepositoryId:canonicalRepositoryIdentity(remote,root),revision:revision || undefined,
-    branch:branch || undefined,dirty:status == null ? undefined : status.length>0,
-    commitCount:count == null ? (revision ? undefined : 0) : Number(count),commits,
-    contributorCount:shortlog == null ? (revision ? undefined : 0) : contributors.length,
-    contributors:contributors.slice(0,12)});
+  return ProjectRepositoryDetails.parse({...base, ...history, status:"ready",
+    canonicalRepositoryId: facts.canonicalRepositoryId, revision: facts.revision,
+    branch: facts.branch, dirty:status == null ? undefined : status.length>0 });
 }
 
 /** Bounded Git observations published under the existing Mesh encryption scope. */
-export async function repositoryDetails(snapshot: MeshSnapshot, endpointId: string): Promise<ProjectRepositoryDetails[]> {
+export async function repositoryDetails(snapshot: MeshSnapshot, endpointId: string,
+  options: ObservationOptions = {}): Promise<ProjectRepositoryDetails[]> {
   const bindings=(snapshot.bindings ?? []).filter(binding=>binding.projectId===snapshot.projectId
     && binding.endpointId===endpointId && binding.available && binding.localPathHint);
   const reports:ProjectRepositoryDetails[]=[];
@@ -55,7 +40,7 @@ export async function repositoryDetails(snapshot: MeshSnapshot, endpointId: stri
   for (const binding of bindings.slice(0,64)) {
     if (seen.has(binding.repositoryId)) continue;
     seen.add(binding.repositoryId);
-    reports.push(await read(binding));
+    reports.push(await read(binding, options));
   }
   return reports;
 }

package/apps/bridge/src/mesh/runtime/graph/README.md

@@ -30,6 +30,10 @@ Behavior tests: `tests/`, root `tests/graph/graph-binding-sync.test.ts`, and
 `engine-selection-live.test.ts` uses `GRANTTAP_ENGINE_TEST_BINARY` to verify the
 actual native scanner respects `.git/info/exclude` and retains untracked source.
 
+Background publication prepares checkout facts asynchronously once and reuses
+that observation for admission and Graph selection. The selector never needs a
+second synchronous Git read in the monitor's relay event loop.
+
 ## License
 
 GrantTap Commercial Source License. See [LICENSE](../../../../../../LICENSE).

package/apps/bridge/src/mesh/runtime/graph/checkout-identity.ts

@@ -1,7 +1,24 @@
 import { realpathSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import type { ProjectBindingSummary } from "../../../../../../packages/protocol/schema";
-import { inspectRepository, type RepositoryFacts } from "../../catalog";
+import { inspectRepository, inspectRepositoryAsync, type RepositoryFacts } from "../../catalog";
+
+/** One nonblocking native observation shared by admission, graph selection and Git details. */
+export async function prepareGraphInspection(bindings: ProjectBindingSummary[], endpointId: string) {
+  const paths = new Set(bindings.filter(binding => binding.endpointId === endpointId
+    && binding.available && binding.localPathHint).flatMap(binding => {
+      try { return [realpathSync(binding.localPathHint!)]; } catch { return []; }
+    }));
+  const observations = new Map(await Promise.all([...paths].map(async path => {
+    try { return [path, await inspectRepositoryAsync(path)] as const; }
+    catch { return [path, undefined] as const; }
+  })));
+  return (path: string): RepositoryFacts => {
+    const facts = observations.get(realpathSync(path));
+    if (!facts) throw new Error("The checkout was not observed for this publication");
+    return { ...facts };
+  };
+}
 
 /** Local identities name an exact directory, even after that directory gains an origin. */
 export function matchesLocalCheckout(repositoryId: string, root: string): boolean {
@@ -13,7 +30,8 @@ export function matchesLocalCheckout(repositoryId: string, root: string): boolea
 }
 
 /** Once admitted, one checkout contributes one graph to this Mesh. */
-export function graphAnalysisBindings(bindings: ProjectBindingSummary[], endpointId?: string): ProjectBindingSummary[] {
+export function graphAnalysisBindings(bindings: ProjectBindingSummary[], endpointId?: string,
+  inspect: (path: string) => RepositoryFacts = inspectRepository): ProjectBindingSummary[] {
   const selected = new Map<string, ProjectBindingSummary>();
   const observations = new Map<string, RepositoryFacts | undefined>();
   const nonRepositories = new Set<string>();
@@ -27,7 +45,7 @@ export function graphAnalysisBindings(bindings: ProjectBindingSummary[], endpoin
     if (path && !observations.has(path)) {
       let facts: RepositoryFacts | undefined;
       try {
-        const observed = inspectRepository(path);
+        const observed = inspect(path);
         if (observed.worktree && realpathSync(observed.root) === path) facts = observed;
         else nonRepositories.add(path);
       } catch { /* Unavailable roots retain their own identity. */ }

package/apps/bridge/src/mesh/runtime/snapshot/enriched.ts

@@ -1,9 +1,9 @@
 import { projectRelationshipPeers, mergeRelationshipPeers } from "../../../engine/runtime/project-relationships";
 import { refreshLocalGraphBindings } from "../graph/binding-sync";
-import { graphAnalysisBindings } from "../graph/checkout-identity";
+import { graphAnalysisBindings, prepareGraphInspection } from "../graph/checkout-identity";
 import type { MeshSnapshot } from "../../../../../../packages/protocol/schema";
 import {
-  projectBackbone, projectRepositoryGraphs, waitForProjectBindingSync,
+  projectBackbone, projectRepositoryGraphs, waitForProjectBindingSync, queueProjectBindingSync,
 } from "../../../engine/runtime/engine-projects";
 import { projectCortexIntegration } from "../../../cortex/integration";
 import { projectKnowledge, queueProjectKnowledgeSync } from "../../../engine/runtime/engine-memory";
@@ -16,10 +16,14 @@ import { computerId } from "../../identity/computer";
 export async function enrichMeshSnapshot(
   snapshot: MeshSnapshot, options: { refreshGraph?: boolean } = {},
 ): Promise<MeshSnapshot> {
-  const identityFailures = await refreshLocalGraphBindings(snapshot);
+  const endpoint = computerId();
+  const inspect = await prepareGraphInspection(snapshot.bindings ?? [], endpoint);
+  const identityFailures = await refreshLocalGraphBindings(snapshot, {
+    endpoint: () => endpoint, inspect, sync: queueProjectBindingSync,
+  });
   const excludedRepositories = new Set(identityFailures.map((report) => report.repositoryId));
   const bindings = graphAnalysisBindings((snapshot.bindings ?? [])
-    .filter((binding) => !excludedRepositories.has(binding.repositoryId)), computerId());
+    .filter((binding) => !excludedRepositories.has(binding.repositoryId)), endpoint, inspect);
   await waitForProjectBindingSync(snapshot.projectId);
   queueProjectKnowledgeSync({
     projectId: snapshot.projectId,
@@ -32,7 +36,7 @@ export async function enrichMeshSnapshot(
       priority: snapshot.tasks.reduce((latest, task) => Math.max(latest, task.updatedAt), 0),
     }),
     projectKnowledge(snapshot.projectId),
-    repositoryDetails(snapshot, computerId()),
+    repositoryDetails(snapshot, endpoint, { background: options.refreshGraph !== true, inspect }),
   ]);
   const relationships = await projectRelationshipPeers(snapshot.projectId, bindings, {
     background: options.refreshGraph !== true,

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.119
+npm install -g granttap-mcp@0.8.121
 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.119\";\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.121\";\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.119";
+const PACKAGE = "granttap-mcp@0.8.121";
 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.119",
+  "version": "0.8.121",
   "description": "Commercial computer runtime connecting local coding agents to GrantTap on Mac, iPhone, iPad and Apple Watch.",
   "type": "module",
   "bin": {