granttap-mcp 0.8.55 → 0.8.56

package/README.md

@@ -23,6 +23,12 @@ index so a restart can send current heads of the saved Now chats before a fresh
 discovery scan. The Apple clients keep downloaded conversations, pictures, and
 Mesh data locally for offline use; clearing that cache preserves the account login.
 
+The chat's **Files** pill opens recorded changes for the current reply and the
+Task's **All files** tree. Directory and text reads are paged, encrypted for the
+requesting controller, and restricted to that native execution's admitted
+checkout. Received previews remain on the device for offline inspection.
+**Agents** opens nested execution conversations within the same Task.
+
 The MCP runtime, plugins, and CLI are open source under the MIT License.
 The Apple apps, Engine, relay, and website are separately licensed commercial
 products or source. Their licenses do not change this repository's MIT grant.
@@ -150,6 +156,21 @@ separate from their path identity. Missing content evidence remains unknown.
 
 <p align="center"><em>These are deterministic simulator fixtures, not reports from a live customer repository.</em></p>
 
+Health and Graph share one architecture build state. With Engine enabled,
+active repository bindings schedule missing or changed analysis automatically;
+manual rebuilds join pending work and return their own delivery receipts.
+Usable reports persist privately on the computer across MCP restarts, while
+the phone keeps its last received map visible during a rebuild. Source Git
+revision and analysis content fingerprint are separate freshness facts.
+Partial and unavailable reports retain their scope and status.
+
+<p align="center">
+  <img src="docs/images/iphone-chat-work-summary.png" width="200" alt="Files and Agents above the composer with deterministic sample work">
+  <img src="docs/images/iphone-chat-files.png" width="200" alt="Saved Task checkout folder tree">
+</p>
+
+<p align="center"><em>Native build181 captures with deterministic sample data.</em></p>
+
 An authenticated controller can request a separate, one-time device credential
 for another iPhone or iPad from each Live linked computer. The phone packages
 the resulting links in an encrypted, single-use QR. This adds the new phone to

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

@@ -16,6 +16,11 @@ ticks reuse a fresh bounded report, and failed analyses back off. An absent
 report leaves the graph unavailable and Cortex degraded; it does not block
 policy IPC: repository analysis owns a separate bounded-lifetime socket, while
 policy and Backbone requests keep their control connection. It does not turn a repository label into an architecture result.
+Explicit builds join and prioritize the same pending repository job. Confirmed
+reports are retained in a bounded private computer cache across restarts, served
+while a new observation runs, and refreshed after the observation expires. Git
+admission revision (`sourceRevision`) remains separate from Weavatrix's content
+fingerprint (`revision`). Failed analyses cannot erase the durable last report.
 Claude, Codex, and Cursor hooks can evaluate the engine's local Project
 Governance policy only when both `GRANTTAP_ENGINE_ENABLED` and
 `GRANTTAP_PROJECT_POLICY_ENABLED` are enabled. Project `DENY` and `ASK` precede

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

@@ -16,6 +16,7 @@ import type {
 } from "../protocol/engine-protocol";
 import { RepositoryGraphJobs } from "./repository-graph-jobs";
 import { fitRepositoryGraph } from "./repository-graph/fit";
+import { RepositoryGraphCache } from "./repository-graph/cache";
 
 export type LocalProjectBinding = {
   summary: ProjectBindingSummary;
@@ -27,9 +28,11 @@ export type LocalProjectBinding = {
 
 let sharedClient: EngineClient | undefined;
 const pendingBindingSyncs = new Map<string, Promise<boolean>>();
-const MAX_REPOSITORY_GRAPH_WIRE_BYTES = 256 * 1_024;
+// The Apple Mesh envelope is 256KiB; leave room for Tasks, bindings and receipts.
+const MAX_REPOSITORY_GRAPH_WIRE_BYTES = 192 * 1_024 - 128;
 const MAX_SINGLE_GRAPH_WIRE_BYTES = 192 * 1_024;
-const repositoryGraphJobs = new RepositoryGraphJobs<ProjectRepositoryGraph>();
+const repositoryGraphJobs = new RepositoryGraphJobs<ProjectRepositoryGraph>(Date.now,120_000,300_000,32,
+  new RepositoryGraphCache(()=>join(configDir(),"repository-graph-cache")));
 
 export async function syncProjectBinding(
   project: Project,
@@ -192,19 +195,19 @@ export async function projectRepositoryGraphs(
   const graphs = options.background
     ? repositories.map((binding) => repositoryGraphJobs.read(
       JSON.stringify([projectId, binding.repositoryId, binding.revision]),
-      () => analyzeRepositoryGraph(client, projectId, binding.repositoryId, 120_000),
+      () => analyzeRepositoryGraph(client, projectId, binding.repositoryId, 120_000, binding.revision),
       options.priority ?? 0,
     ))
-    : await Promise.all(repositories.map((binding) =>
-      analyzeRepositoryGraph(client, projectId, binding.repositoryId, 120_000).then((graph) => {
-        repositoryGraphJobs.remember(JSON.stringify([projectId, binding.repositoryId, binding.revision]), graph);
-        return graph;
-      })));
+    : await Promise.all(repositories.map((binding) => repositoryGraphJobs.refresh(
+      JSON.stringify([projectId, binding.repositoryId, binding.revision]),
+      () => analyzeRepositoryGraph(client, projectId, binding.repositoryId, 120_000, binding.revision),
+    )));
   return boundRepositoryGraphs(graphs.filter((item): item is ProjectRepositoryGraph => item != null));
 }
 
 async function analyzeRepositoryGraph(
   client: EngineClientLike | undefined, projectId: string, repositoryId: string, timeoutMs: number,
+  sourceRevision?: string,
 ): Promise<ProjectRepositoryGraph | undefined> {
   // The daemon serves a socket serially. Analysis must not occupy the channel
   // used for policy, bindings and Backbone reads while a repository is scanned.
@@ -222,6 +225,7 @@ async function analyzeRepositoryGraph(
     return {
       projectId: graph.project_id, repositoryId: graph.repository_id,
       revision: graph.revision, weavatrixVersion: graph.weavatrix_version,
+      sourceRevision,
       analysisId: graph.analysis_id ?? undefined,
       analysisStatus: graph.analysis_status,
       architectureHypotheses: graph.architecture_hypotheses,
@@ -269,9 +273,10 @@ async function analyzeRepositoryGraph(
 function boundRepositoryGraphs(graphs: ProjectRepositoryGraph[]): ProjectRepositoryGraph[] {
   const result: ProjectRepositoryGraph[] = [];
   let remaining = MAX_REPOSITORY_GRAPH_WIRE_BYTES;
-  for (const graph of graphs) {
+  for (const [index, graph] of graphs.entries()) {
     if (remaining < 1_024) break;
-    const bounded = fitRepositoryGraph(graph, Math.min(remaining, MAX_SINGLE_GRAPH_WIRE_BYTES));
+    const fairShare = Math.floor(remaining / (graphs.length - index));
+    const bounded = fitRepositoryGraph(graph, Math.min(fairShare, MAX_SINGLE_GRAPH_WIRE_BYTES));
     if (!bounded) continue;
     result.push(bounded);
     remaining -= Buffer.byteLength(JSON.stringify(bounded), "utf8");

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

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, renameSync, statSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { ProjectRepositoryGraph } from '../../../../../../packages/protocol/schema';
+import { fitRepositoryGraph } from './fit';
+/** Private computer-side observations; no hand-authored architecture enters this cache. */
+export class RepositoryGraphCache {
+    constructor(private readonly directory: string | (() => string), private readonly now: () => number = Date.now) { }
+    read(key: string): {
+        value: ProjectRepositoryGraph;
+        savedAt: number;
+    } | undefined {
+        try {
+            const path = this.path(key);
+            if (statSync(path).size > 256 * 1024)
+                return undefined;
+            const record = JSON.parse(readFileSync(path, 'utf8'));
+            const graph = ProjectRepositoryGraph.safeParse(record.value);
+            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 };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    write(key: string, value: ProjectRepositoryGraph): 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() });
+        if (Buffer.byteLength(json) > 256 * 1024)
+            return;
+        try {
+            const directory = typeof this.directory === 'function' ? this.directory() : this.directory;
+            mkdirSync(directory, { recursive: true, mode: 0o700 });
+            const path = this.path(key), temporary = path + '.tmp';
+            writeFileSync(temporary, json, { mode: 0o600 });
+            renameSync(temporary, path);
+            const files = readdirSync(directory).filter(name => name.endsWith('.json'))
+                .map(name => ({ path: join(directory, name), mtime: statSync(join(directory, name)).mtimeMs }))
+                .sort((a, b) => b.mtime - a.mtime);
+            for (const file of files.slice(128))
+                unlinkSync(file.path);
+        }
+        catch { /* The live graph remains available when disk storage is unavailable. */ }
+    }
+    private path(key: string): string {
+        const directory = typeof this.directory === 'function' ? this.directory() : this.directory;
+        return join(directory, createHash('sha256').update(key).digest('hex') + '.json');
+    }
+}

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

@@ -4,6 +4,7 @@ export class RepositoryGraphJobs<T> {
     value?: T;
     retryAt: number;
     pending: boolean;
+    listeners: Array<(value: T | undefined) => void>;
   }>();
   private readonly queue: Array<{
     key: string; run: () => Promise<T | undefined>; priority: number;
@@ -15,25 +16,61 @@ 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},
   ) {}
 
-  read(key: string, run: () => Promise<T | undefined>, priority = 0): T | undefined {
+  read(key: string, run: () => Promise<T | undefined>, priority = 0, force = false): 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:[]});
+    }
     const previous = this.entries.get(key);
     if (previous?.pending) return previous.value;
-    if (previous && this.now() < previous.retryAt) return previous.value;
-    if (this.queue.length >= this.capacity) return undefined;
+    if (previous && !force && this.now() < previous.retryAt) 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 });
+    this.entries.set(key, { value: previous?.value, retryAt: 0, pending: true, listeners: [] });
     const before = this.queue.findIndex((job) => job.priority < priority);
     this.queue.splice(before < 0 ? this.queue.length : before, 0, { key, run, 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);
+    const entry = this.entries.get(key);
+    if (!entry?.pending) return Promise.resolve(undefined);
+    const index = this.queue.findIndex(job => job.key === key);
+    if (index >= 0) {
+      const job = this.queue.splice(index, 1)[0]!;
+      job.priority = Math.max(priority, job.priority);
+      const before = this.queue.findIndex(other => other.priority < job.priority);
+      this.queue.splice(before < 0 ? this.queue.length : before, 0, job);
+    }
+    return new Promise(resolve => entry.listeners.push(resolve));
+  }
+
+  private admit(priority: number): boolean {
+    if (this.queue.length < this.capacity) return true;
+    const last = this.queue[this.queue.length - 1];
+    if (!last || last.priority >= priority) return false;
+    this.queue.pop();
+    const entry = this.entries.get(last.key);
+    if (entry) {
+      entry.pending = false;
+      entry.retryAt = this.now() + this.failureMs;
+      for (const listener of entry.listeners) listener(undefined);
+      entry.listeners = [];
+    }
+    return true;
+  }
+
   /** An explicit refresh supersedes an older queued or running observation. */
   remember(key: string, value: T | undefined): void {
     for (let index = this.queue.length - 1; index >= 0; index--) {
@@ -44,7 +81,9 @@ export class RepositoryGraphJobs<T> {
       if (!oldest) return;
       this.entries.delete(oldest);
     }
-    this.entries.set(key, { value, pending: false,
+    for (const listener of this.entries.get(key)?.listeners ?? []) listener(value);
+    if (value !== undefined) this.storage?.write(key, value);
+    this.entries.set(key, { value, pending: false, listeners: [],
       retryAt: this.now() + (value === undefined ? this.failureMs : this.successMs) });
   }
 
@@ -58,11 +97,14 @@ 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);
         this.entries.set(job.key, {
           value,
           retryAt: this.now() + (value === undefined ? this.failureMs : this.successMs),
           pending: false,
+          listeners: [],
         });
+        for (const listener of entry?.listeners ?? []) listener(value);
       }
     } finally {
       this.running = false;

package/apps/bridge/src/host/session-key-store/README.md

@@ -0,0 +1,12 @@
+# Task key persistence
+
+`persistedSessionKey` preserves one stable task encryption key across concurrent
+MCP processes. New keys use an exclusive computer-local creation lock, re-read
+the current dictionary under that lock, and atomically replace the protected
+snapshot. Existing keys remain readable without waiting for another creator.
+An unreadable dictionary is never replaced with an empty one. Locks left by
+terminated owners can be recovered; active owners are never displaced.
+
+The public transport entry remains `../session-keys.ts`. Tests exercise actual
+concurrent processes and the durable dictionary without logging key material.
+This module uses the repository MIT License.

package/apps/bridge/src/host/session-key-store/index.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { generateTransferKey } from "../../../../../packages/core/crypto";
+type SessionKeys = Record<string, string>;
+const pause = new Int32Array(new SharedArrayBuffer(4));
+export function loadSessionKeys(path: string): SessionKeys {
+    if (!existsSync(path))
+        return {};
+    if (statSync(path).size > 8 * 1024 * 1024)
+        throw Error("Task key store exceeds its private storage limit");
+    let value: unknown;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw Error("Task key store is unreadable");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw Error("Task key store is unreadable");
+    return Object.fromEntries(Object.entries(value).filter((entry): entry is [
+        string,
+        string
+    ] => typeof entry[1] === "string" && entry[1].length >= 43 && entry[1].length <= 44));
+}
+/** Creation is serialized across local MCP processes; reads use atomic snapshots. */
+export function persistedSessionKey(path: string, sessionId: string, waitMs = 5000): string {
+    const existing = loadSessionKeys(path);
+    if (Object.hasOwn(existing, sessionId))
+        return existing[sessionId]!;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const lock = path + ".lock", deadline = Date.now() + waitMs;
+    const owner = acquire(lock, deadline);
+    try {
+        const keys = loadSessionKeys(path);
+        if (Object.hasOwn(keys, sessionId))
+            return keys[sessionId]!;
+        const key = generateTransferKey();
+        const temporary = path + "." + process.pid + "." + randomUUID() + ".tmp";
+        try {
+            writeFileSync(temporary, JSON.stringify({ ...keys, [sessionId]: key }) + "\n", { mode: 0o600 });
+            renameSync(temporary, path);
+        }
+        finally {
+            try {
+                unlinkSync(temporary);
+            }
+            catch { }
+        }
+        return key;
+    }
+    finally {
+        unlinkSync(owner);
+        rmdirSync(lock);
+    }
+}
+function acquire(path: string, deadline: number): string {
+    for (;;) {
+        try {
+            mkdirSync(path, { mode: 0o700 });
+            const owner = path + "/owner-" + process.pid + "-" + randomUUID();
+            writeFileSync(owner, "", { flag: "wx", mode: 0o600 });
+            return owner;
+        }
+        catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "EEXIST")
+                throw error;
+            removeDeadOwner(path);
+            if (Date.now() >= deadline)
+                throw Error("Task key creation is busy; retry later");
+            Atomics.wait(pause, 0, 0, 10);
+        }
+    }
+}
+function removeDeadOwner(path: string): void {
+    try {
+        const entries = readdirSync(path);
+        if (entries.length === 0) {
+            if (Date.now() - statSync(path).mtimeMs > 30000)
+                rmdirSync(path);
+            return;
+        }
+        if (entries.length !== 1)
+            return;
+        const owner = entries[0]!, match = /^owner-(\d+)-/.exec(owner);
+        if (!match)
+            return;
+        const pid = Number(match[1]);
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            return;
+        try {
+            process.kill(pid, 0);
+        }
+        catch (error) {
+            if ((error as NodeJS.ErrnoException).code === "ESRCH") {
+                unlinkSync(path + "/" + owner);
+                rmdirSync(path);
+            }
+        }
+    }
+    catch { /* Another creator may already have released the lock. */ }
+}

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

@@ -1,6 +1,6 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { generateTransferKey } from "../../../../packages/core/crypto";
+import { loadSessionKeys, persistedSessionKey } from "./session-key-store";
 import { RelayClient, type SendOptions } from "../../../../packages/core/relay-client";
 import type {
   MeshClaimReleaseResult,
@@ -13,41 +13,17 @@ import type {
 } from "../../../../packages/protocol/schema";
 import { configDir } from "../config";
 
-type SessionKeys = Record<string, string>;
-
 export function sessionKeysPath(): string {
   return join(configDir(), "session-keys.json");
 }
 
-function load(): SessionKeys {
-  try {
-    const value = JSON.parse(readFileSync(sessionKeysPath(), "utf8")) as unknown;
-    if (!value || typeof value !== "object" || Array.isArray(value)) return {};
-    return Object.fromEntries(Object.entries(value).filter((entry): entry is [string, string] =>
-      typeof entry[1] === "string" && entry[1].length >= 43 && entry[1].length <= 44));
-  } catch {
-    return {};
-  }
-}
-
-function save(keys: SessionKeys): void {
-  mkdirSync(configDir(), { recursive: true });
-  writeFileSync(sessionKeysPath(), `${JSON.stringify(keys, null, 2)}\n`, { mode: 0o600 });
-  chmodSync(sessionKeysPath(), 0o600);
-}
-
 export function sessionKey(sessionId: string): string {
-  const keys = load();
-  if (keys[sessionId]) return keys[sessionId]!;
-  const key = generateTransferKey();
-  keys[sessionId] = key;
-  save(keys);
-  return key;
+  return persistedSessionKey(sessionKeysPath(), sessionId);
 }
 
 export function primeSessionKeys(client: RelayClient): void {
   if (!existsSync(sessionKeysPath())) return;
-  for (const [sessionId, key] of Object.entries(load())) client.setSessionKey(sessionId, key);
+  for (const [sessionId, key] of Object.entries(loadSessionKeys(sessionKeysPath()))) client.setSessionKey(sessionId, key);
 }
 
 /**

package/apps/bridge/src/monitor/handlers/inbound.ts

@@ -35,6 +35,7 @@ import { handleTaskCreate } from "./task-create";
 import { handleUserMessage } from "./user-message";
 import { publishSessionEvents } from "./catalog";
 import { publishSessionImage } from '../../session-images';
+import { publishTaskWorkspace } from '../../task-files/relay';
 import { publishHistoryPage } from "../history/pages";
 import { requestProjectGraphRefresh } from "../graph-refresh";
 import { handleControllerPairRequest, handleInboundKnowledgeWrite } from "../controller-knowledge";
@@ -84,7 +85,7 @@ export async function handleMonitorMessage(
       return true;
     } else if (payload.type === "session.subscribe") {
       return handleInboundSubscription(client, payload, subscriptions, publish, input.peerPublicKey);
-    } else if (payload.type === "session.events" || payload.type === "session.image.query") {
+    } else if (payload.type === "session.events" || payload.type === "session.image.query" || payload.type === "session.workspace.query") {
       return handleSessionRead(client, payload, input.peerPublicKey);
     } else if (payload.type === "sessions.refresh") {
       return handleInboundRefresh(client, payload, publish);
@@ -277,9 +278,10 @@ function handleInboundSubscription(
 }
 
 async function handleSessionRead(client: RelayClient,
-  payload: Extract<Payload, { type: 'session.events' | 'session.image.query' }>,
+  payload: Extract<Payload, { type: 'session.events' | 'session.image.query' | 'session.workspace.query' }>,
   peerPublicKey?: string): Promise<boolean> {
-  if (payload.type === 'session.image.query') await publishSessionImage(client, payload, peerPublicKey);
+  if (payload.type === 'session.workspace.query') await publishTaskWorkspace(client, payload, peerPublicKey);
+  else if (payload.type === 'session.image.query') await publishSessionImage(client, payload, peerPublicKey);
   else await publishSessionEvents(client, payload.sessionId, undefined, payload.threadId,
     { ...payload, peerPublicKey }).catch(() => false);
   return true;

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

@@ -1,5 +1,8 @@
 # Mesh publication
 
+Ready enriched Projects are delivered independently. A slow binding restoration
+or unavailable Project cannot delay a completed report from another Project.
+
 `index.ts` owns one background Mesh publication per monitor transport. Project
 projection yields to live decisions and uses the observed native catalog. Plain
 snapshots, policy reports, and Engine enrichment remain separate from fresh chat

package/apps/bridge/src/monitor/mesh-publication/enrichment.ts

@@ -0,0 +1,11 @@
+import type { MeshSnapshot } from '../../../../../packages/protocol/schema';
+import { enrichMeshSnapshot } from '../../mesh/runtime/snapshot/enriched';
+/** Publish ready Projects independently so one slow binding cannot hold other reports. */
+export async function publishEnrichedMeshes(snapshots: MeshSnapshot[], send: (snapshot: MeshSnapshot) => Promise<void>, enrich: typeof enrichMeshSnapshot = enrichMeshSnapshot): Promise<void> {
+    await Promise.all(snapshots.map(async (snapshot) => {
+        try {
+            await send(await enrich(snapshot));
+        }
+        catch { /* This Project is retried on the next publication tick. */ }
+    }));
+}

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

@@ -1,7 +1,8 @@
 import type { RelayClient } from "../../../../../packages/core/relay-client";
 import type { SessionsStatus } from "../../../../../packages/protocol/schema";
 import { localMeshStore } from "../../mesh/local-remote/local";
-import { meshSnapshotsAsync, meshSnapshotsWithEngine } from "../../mesh/runtime";
+import { meshSnapshotsAsync } from "../../mesh/runtime";
+import { publishEnrichedMeshes } from "./enrichment";
 import { deriveObservedClaims } from "../../mesh/observed/claims";
 import { ingestRuntimeInvocations } from "../../engine/invocation/ingest";
 import { publishProjectPolicyStatuses } from "../../project-policy/runtime";
@@ -29,11 +30,10 @@ export function publishMonitorMeshes(client: RelayClient, status: SessionsStatus
     }
     if (!token.active || !client.isConnected) return;
     await publishProjectPolicyStatuses(client, snapshots.map(mesh => mesh.projectId)).catch(() => {});
-    const enriched = await meshSnapshotsWithEngine(snapshots);
-    for (const snapshot of enriched) {
+    await publishEnrichedMeshes(snapshots, async snapshot => {
       if (!token.active || !client.isConnected) return;
       await sendMeshPayload(client, snapshot, "phone", { ttlMs: INTERVAL_MS * 24, reliable: false }).catch(() => {});
-    }
+    });
   })();
   void work.catch(() => {}).finally(() => { if (pending.get(client) === token) pending.delete(client); });
 }

package/apps/bridge/src/task-files/README.md

@@ -0,0 +1,16 @@
+# Task files
+
+`readTaskWorkspace` reads a directory page or a bounded UTF-8 file from the exact
+native execution workspace. It accepts relative paths, resolves symlinks inside
+that workspace, and rejects credentials, traversal and external paths. The
+viewer performs no writes, shell operations, model calls or provider actions.
+
+`publishTaskWorkspace` resolves the execution through the computer's published
+catalog and returns an authenticated task-encrypted reply to the requesting
+controller. The local Mac counterpart validates Project, Task and Execution
+identity before using the same reader. Directory pages contain at most 200
+entries; file previews contain at most 128 KiB and explicitly mark truncation.
+
+Module tests cover real files, nested directories, boundaries and pagination.
+
+This module uses the repository MIT License.

package/apps/bridge/src/task-files/index.ts

@@ -0,0 +1,96 @@
+import { isUtf8 } from 'node:buffer';
+import { closeSync, lstatSync, openSync, readSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import type { SessionInfo } from '../../../../packages/protocol/schema';
+export type TaskWorkspaceQuery = {
+    mode: 'directory' | 'file';
+    path: string;
+    offset?: number;
+};
+export type TaskWorkspaceEntry = {
+    path: string;
+    name: string;
+    kind: 'directory' | 'file';
+    size?: number;
+};
+export type TaskWorkspaceRead = {
+    path: string;
+    entries?: TaskWorkspaceEntry[];
+    text?: string;
+    truncated: boolean;
+    nextOffset?: number;
+};
+const protectedPath = (path: string) => path.split('/').some(part => /^\.env(?:\.|$)/i.test(part)
+    || ['.git', '.ssh', '.aws', '.private_keys', '.codex', '.claude', '.cursor', '.granttap', '.nodvox'].includes(part)
+    || /\.(?:p8|pem|key)$/i.test(part));
+function admittedPath(root: string, path: string): string | undefined {
+    if (path.includes('\0') || path.includes('\\') || isAbsolute(path) || /^[A-Za-z]:/.test(path)
+        || path.split('/').includes('..') || protectedPath(path))
+        return undefined;
+    try {
+        const target = realpathSync(resolve(root, path));
+        const within = relative(root, target);
+        return within === '..' || within.startsWith('..' + sep) || isAbsolute(within)
+            || protectedPath(within.split(sep).join('/')) ? undefined : target;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Only the exact known native execution's workspace is readable. */
+export function readTaskWorkspace(session: SessionInfo, query: TaskWorkspaceQuery): TaskWorkspaceRead | undefined {
+    const path = session.worktree ?? session.cwd;
+    if (!path || !['directory', 'file'].includes(query.mode))
+        return undefined;
+    try {
+        const root = realpathSync(path), target = admittedPath(root, query.path);
+        if (!target || !statSync(root).isDirectory())
+            return undefined;
+        const offset = query.offset ?? 0;
+        if (!Number.isSafeInteger(offset) || offset < 0)
+            return undefined;
+        if (query.mode === 'file')
+            return file(target, query.path, offset);
+        if (!statSync(target).isDirectory())
+            return undefined;
+        const entries = readdirSync(target).flatMap(name => {
+            const path = query.path ? query.path + '/' + name : name;
+            const full = admittedPath(root, path);
+            if (!full)
+                return [];
+            const info = statSync(full);
+            if (!info.isDirectory() && !info.isFile())
+                return [];
+            return [{ path, name, kind: info.isDirectory() ? 'directory' as const : 'file' as const,
+                    ...(info.isFile() ? { size: info.size } : {}) }];
+        }).sort((a, b) => a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === 'directory' ? -1 : 1);
+        const next = offset + 200, truncated = next < entries.length;
+        return { path: query.path, entries: entries.slice(offset, next), truncated,
+            ...(truncated ? { nextOffset: next } : {}) };
+    }
+    catch {
+        return undefined;
+    }
+}
+function file(target: string, path: string, offset: number): TaskWorkspaceRead | undefined {
+    const info = lstatSync(target);
+    if (!info.isFile() || offset > info.size)
+        return undefined;
+    const fd = openSync(target, 'r');
+    try {
+        const bytes = Buffer.alloc(Math.min(info.size - offset, 128 * 1024));
+        const count = readSync(fd, bytes, 0, bytes.length, offset);
+        let read = bytes.subarray(0, count);
+        // A bounded preview may end inside a UTF8 character; invalid interior bytes remain refused.
+        if (info.size > offset + count)
+            for (let trim = 1; trim <= 3 && !isUtf8(read); trim++)
+                read = bytes.subarray(0, count - trim);
+        if (!isUtf8(read) || /[\x00-\x08\x0B\x0C\x0E-\x1F]/.test(read.toString('utf8')))
+            return undefined;
+        const next = offset + read.length, truncated = info.size > next;
+        return { path, text: read.toString('utf8'), truncated, ...(truncated ? { nextOffset: next } : {}) };
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/apps/bridge/src/task-files/relay.ts

@@ -0,0 +1,14 @@
+import type { RelayClient } from '../../../../packages/core/relay-client';
+import { SessionWorkspaceResult, type SessionWorkspaceQuery } from '../../../../packages/protocol/schema';
+import { publishedSession } from '../session-catalog';
+import { sendSessionPayload } from '../host/session-keys';
+import { readTaskWorkspace } from '.';
+/** Session identity comes from the computer's admitted catalog, never from a requested root. */
+export async function publishTaskWorkspace(client: RelayClient, query: SessionWorkspaceQuery, peerPublicKey?: string): Promise<boolean> {
+    const session = publishedSession(client, query.sessionId);
+    const result = session ? readTaskWorkspace(session, query) : undefined;
+    await sendSessionPayload(client, SessionWorkspaceResult.parse({ type: 'session.workspace.result',
+        sessionId: query.sessionId, requestId: query.requestId,
+        ...(result ?? { path: query.path, truncated: false, unavailable: true }), createdAt: Date.now() }), query.sessionId, 'phone', { peerPublicKey, ttlMs: 30000, reliable: false });
+    return result !== undefined;
+}

package/apps/mcp/src/desktop/engine-bridge.ts

@@ -18,7 +18,7 @@ export const DESKTOP_OPERATIONS = new Set([
   "project.list_bindings", "policy.get", "policy.coverage",
   "graph.get_backbone", "memory.history", "invocation.history",
   "desktop.project", "desktop.mesh_snapshot", "desktop.workspace", "desktop.task_activity",
-  "desktop.machine_load", "desktop.capability_usage", "desktop.task_image",
+  "desktop.machine_load", "desktop.capability_usage", "desktop.task_image", "desktop.task_workspace",
   "desktop.installed_skills", "desktop.policy_status", "desktop.policy_set", "desktop.project_auto_accept",
   "desktop.mesh_snapshots",
   "desktop.task_send",

package/apps/mcp/src/desktop/operations/index.ts

@@ -10,6 +10,7 @@ import type { DesktopTaskActivityRunner } from "../task-activity-runner";
 import type { EngineClient } from "../../../../bridge/src/engine/runtime/engine-client";
 import type { EngineOperation } from "../../../../bridge/src/engine/protocol/engine-protocol";
 import { desktopTaskSend } from "../delivery/task-send";
+import { desktopTaskWorkspace } from "../workspace/task-files";
 import { desktopTaskHandoff } from "../delivery/task-handoff";
 import { desktopTaskCreate } from "../delivery/task-create";
 import { desktopMeshCreate } from "../delivery/mesh-create";
@@ -54,6 +55,7 @@ export function desktopReadOperation(input: {
   if (operation === "desktop.machine_load") return desktopMachineLoad();
   if (operation === "desktop.task_activity") return activity.read(queryInput, storePath);
   if (operation === "desktop.task_image") return activity.image(queryInput, storePath);
+  if (operation === "desktop.task_workspace") return Promise.resolve(desktopTaskWorkspace(queryInput, storePath));
   if (operation === "desktop.task_send") return desktopTaskSend(queryInput, storePath);
   if (operation === "desktop.task_handoff") return desktopTaskHandoff(queryInput, storePath);
   if (operation === "desktop.task_create") return desktopTaskCreate(queryInput, storePath);

package/apps/mcp/src/desktop/workspace/README.md

@@ -0,0 +1,8 @@
+# Task workspace reader
+
+`desktopTaskWorkspace` admits a Project, Task and exact native Execution before
+reading its recorded workspace through the shared `task-files` public entry.
+It exposes paged directory listings and bounded UTF-8 previews, with no writes.
+Tests live in `../models/tests/task-workspace.test.ts`.
+
+This module uses the repository MIT License.

package/apps/mcp/src/desktop/workspace/task-files.ts

@@ -0,0 +1,30 @@
+import { join } from 'node:path';
+import { configDir } from '../../../../bridge/src/config';
+import { readStoreState } from '../../../../bridge/src/mesh/store/state';
+import { readTaskWorkspace } from '../../../../bridge/src/task-files';
+import type { SessionInfo } from '../../../../../packages/protocol/schema';
+/** Native desktop requests must match the Task's recorded execution exactly. */
+export function desktopTaskWorkspace(input: unknown, storePath = join(configDir(), 'project-mesh.json')) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return undefined;
+    const query = input as Record<string, unknown>;
+    const { project_id: projectId, task_id: taskId, session_id: sessionId, mode, path, offset } = query;
+    if (typeof projectId !== 'string' || typeof taskId !== 'string' || typeof sessionId !== 'string'
+        || !['directory', 'file'].includes(String(mode)) || typeof path !== 'string' || path.length > 4096
+        || offset !== undefined && (!Number.isSafeInteger(offset) || Number(offset) < 0))
+        return undefined;
+    const loaded = readStoreState(storePath);
+    if (loaded.status !== 'ok')
+        return undefined;
+    const tasks = loaded.state.tasks.filter(t => t.taskId === taskId);
+    if (tasks.length !== 1 || tasks[0]?.projectId !== projectId)
+        return undefined;
+    const executions = loaded.state.executions.filter(e => e.taskId === taskId && e.sessionId === sessionId);
+    if (executions.length !== 1)
+        return undefined;
+    const execution = executions[0]!;
+    const session: SessionInfo = { sessionId, agent: execution.provider, cwd: execution.workspace,
+        state: 'idle', startedAt: execution.startedAt, lastActivityAt: execution.updatedAt ?? execution.startedAt, tokensSession: 0, tokensLastTurn: 0 };
+    const result = readTaskWorkspace(session, { mode: mode as 'directory' | 'file', path, offset: offset as number | undefined });
+    return result ? { operation: 'desktop.task_workspace', ...result } : undefined;
+}

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.55
+npm install -g granttap-mcp@0.8.56
 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.55\";\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 20+ 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.56\";\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 20+ 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.55";
+const PACKAGE = "granttap-mcp@0.8.56";
 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.55",
+  "version": "0.8.56",
   "description": "Personal live control center runtime for local coding agents on iPhone and Apple Watch.",
   "type": "module",
   "bin": {

package/packages/protocol/messages/mesh/snapshot.ts

@@ -154,6 +154,7 @@ export const ProjectRepositoryGraph = z.object({
   repositoryId: z.string().trim().min(1).max(512),
   revision: z.string().trim().min(1).max(512),
   weavatrixVersion: z.string().trim().min(1).max(64),
+  sourceRevision: z.string().trim().min(1).max(512).optional(),
   analysisId: z.string().trim().min(1).max(128).optional(),
   analysisStatus: z.enum(["COMPLETE", "INCOMPLETE", "UNAVAILABLE"]).optional(),
   analysisErrorCode: z.string().regex(/^[A-Z_]{2,64}$/).optional(),

package/packages/protocol/messages/sessions/workspace.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+const scope = { sessionId: z.string().min(1).max(512), requestId: z.string().min(1).max(128) };
+export const SessionWorkspaceQuery = z.object({ type: z.literal('session.workspace.query'), ...scope,
+    mode: z.enum(['directory', 'file']), path: z.string().max(4096), offset: z.number().int().nonnegative().optional(),
+    createdAt: z.number().finite() }).strict();
+export type SessionWorkspaceQuery = z.infer<typeof SessionWorkspaceQuery>;
+export const SessionWorkspaceResult = z.object({ type: z.literal('session.workspace.result'), ...scope,
+    path: z.string().max(4096), entries: z.array(z.object({ path: z.string().max(4096), name: z.string().max(1024),
+        kind: z.enum(['directory', 'file']), size: z.number().int().nonnegative().optional() }).strict()).max(200).optional(),
+    text: z.string().max(128 * 1024).optional(), truncated: z.boolean(),
+    nextOffset: z.number().int().nonnegative().optional(), unavailable: z.boolean().optional(),
+    createdAt: z.number().finite() }).strict();
+export type SessionWorkspaceResult = z.infer<typeof SessionWorkspaceResult>;

package/packages/protocol/schema.ts

@@ -1,6 +1,8 @@
 /** Public encrypted wire protocol entry point. */
 import { z } from "zod";
 import { SessionImageQuery, SessionImageChunk } from './messages/session-images';
+import { SessionWorkspaceQuery, SessionWorkspaceResult } from './messages/sessions/workspace';
+export { SessionWorkspaceQuery, SessionWorkspaceResult } from './messages/sessions/workspace';
 export { SessionImageQuery, SessionImageChunk } from './messages/session-images';
 import { ProviderHookTrust, ProviderHookTrustResult } from "./messages/provider-hooks";
 import {
@@ -126,6 +128,8 @@ export const Payload = z.union([
   SessionActivity,
   SessionImageQuery,
   SessionImageChunk,
+  SessionWorkspaceQuery,
+  SessionWorkspaceResult,
   CapabilityUsageStatus,
   SessionKeyGrant,
   SessionSealed,