granttap-mcp 0.8.120 → 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/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.120
+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.120\";\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.120";
+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.120",
+  "version": "0.8.121",
   "description": "Commercial computer runtime connecting local coding agents to GrantTap on Mac, iPhone, iPad and Apple Watch.",
   "type": "module",
   "bin": {