granttap-mcp 0.8.54 → 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);
 }
 
 /**
@@ -102,6 +78,6 @@ async function sendScopedPayload(input: {
     key,
     purpose,
     createdAt: Date.now(),
-  }, to, { ttlMs: options.ttlMs });
+  }, to, { ttlMs: options.ttlMs, peerPublicKey: options.peerPublicKey });
   await client.sendSession(payload, sessionId, to, options);
 }

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

@@ -56,7 +56,7 @@ export async function publishSessionEvents(
   sessionId: string,
   status?: SessionsStatus,
   threadId?: string,
-  history?: { history?: boolean; historyCursor?: string },
+  history?: { history?: boolean; historyCursor?: string; peerPublicKey?: string },
 ): Promise<boolean> {
   const session = resolveSession(client, sessionId, status);
   if (!session) return false;
@@ -66,6 +66,7 @@ export async function publishSessionEvents(
   await sendSessionPayload(client, activityWithImages(activity), sessionId, "phone", {
     ttlMs: INTERVAL_MS * 24,
     reliable: false,
+    peerPublicKey: history?.peerPublicKey,
   });
   return true;
 }

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";
@@ -83,9 +84,9 @@ export async function handleMonitorMessage(
       void publish().catch(() => {});
       return true;
     } else if (payload.type === "session.subscribe") {
-      return handleInboundSubscription(client, payload, subscriptions, publish);
-    } else if (payload.type === "session.events" || payload.type === "session.image.query") {
-      return handleSessionRead(client, payload);
+      return handleInboundSubscription(client, payload, subscriptions, publish, input.peerPublicKey);
+    } 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);
     } else if (payload.type === "sessions.history.query") {
@@ -266,9 +267,10 @@ async function handleInboundTaskCreate(
 function handleInboundSubscription(
   client: RelayClient, payload: Extract<Payload, { type: "session.subscribe" }>,
   subscriptions: Set<string>, publish: (forceHistory?: boolean) => Promise<void>,
+  peerPublicKey?: string,
 ): boolean {
   // The transcript goes first, before a potentially slow catalog rescan.
-  void publishSessionEvents(client, payload.sessionId).catch(() => false);
+  void publishSessionEvents(client, payload.sessionId, undefined, undefined, { peerPublicKey }).catch(() => false);
   if (handleSubscription(subscriptions, payload)) {
     void publish().catch(() => {});
   }
@@ -276,8 +278,11 @@ function handleInboundSubscription(
 }
 
 async function handleSessionRead(client: RelayClient,
-  payload: Extract<Payload, { type: 'session.events' | 'session.image.query' }>): Promise<boolean> {
-  if (payload.type === 'session.image.query') await publishSessionImage(client, payload);
-  else await publishSessionEvents(client, payload.sessionId, undefined, payload.threadId, payload).catch(() => false);
+  payload: Extract<Payload, { type: 'session.events' | 'session.image.query' | 'session.workspace.query' }>,
+  peerPublicKey?: string): Promise<boolean> {
+  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/session-catalog/README.md

@@ -21,3 +21,5 @@ Engine binding recovery waits for the first connected catalog publication before
 Codex discovery shares repeated checkout verification only within one synchronous scan. The next scan verifies repository identity again; no long-lived checkout cache can cross a repository change. This keeps startup catalog delivery ahead of repeated Git subprocesses.
 
 Subscribed transcript heads use a separate, single-flight transfer loop. A stalled head never occupies the current catalog publication slot; stopping the monitor cancels further queued reads. The iPhone keeps its historical backfill independent of both loops.
+
+Authenticated subscription and transcript requests pass the verified requester key to the encrypted reply. A requested page does not wait for copies addressed to other paired controllers. Shared catalogue and chat updates remain available to passive controllers.

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

@@ -17,3 +17,9 @@ Native image identities remain readable after the chat head advances. Codex
 attachments are located by timestamp and content block together, so a caption
 with the same timestamp cannot hide the picture. Original bytes are delivered in
 bounded encrypted chunks and the Apple client retains them for offline use.
+
+An authenticated image query returns its key grant and chunk only to the requesting controller. Shared chat publication still retains every authorized controller, including one receiving passively.
+
+Saved native picture identities remain addressable after newer transcript pages append. Lookup walks bounded windows toward the original row, verifies the exact conversation and block identity, and stops at the file start or a non-advancing cursor. There is no page-count expiry for a previously advertised attachment.
+
+Workspace screenshots in older replies resolve the original native row and its exact advertised image identity before applying the existing Task, Execution and workspace access checks. A request never supplies a filesystem path, and looking up an older reply does not widen access outside its authorized workspace.

package/apps/bridge/src/session-images/index.ts

@@ -22,7 +22,8 @@ export function readSessionImage(query: SessionImageQuery, session: SessionInfo,
   return sessionImageChunk(session, activity, query.imageId, query.offset, query.historyCursor);
 }
 
-export async function publishSessionImage(client: RelayClient, query: SessionImageQuery): Promise<boolean> {
+export async function publishSessionImage(client: RelayClient, query: SessionImageQuery,
+  peerPublicKey?: string): Promise<boolean> {
   const session = publishedSession(client, query.sessionId)
     ?? scanSessions().sessions.find(s => s.sessionId === query.sessionId)
     ?? scanSessionHistory().find(s => s.sessionId === query.sessionId);
@@ -33,6 +34,6 @@ export async function publishSessionImage(client: RelayClient, query: SessionIma
     requestId: query.requestId, imageId: query.imageId, offset: query.offset,
     ...(chunk ? { mimeType: chunk.mime_type, totalBytes: chunk.total_bytes,
       dataBase64: chunk.data_base64 } : { unavailable: true }) }), query.sessionId,
-    'phone', { ttlMs: 20_000, reliable: false });
+    'phone', { ttlMs: 20_000, reliable: false, peerPublicKey });
   return chunk !== undefined;
 }

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/bridge/src/transcript-history/images/advertised-entry.ts

@@ -0,0 +1,43 @@
+import type { ActivityEntry, SessionInfo } from "../../../../../packages/protocol/schema";
+import { appendCodexActivity } from "../../sessions/scan/codex/activity";
+import { codexLogPathForSession } from "../../sessions/scan/codex/shared";
+import { appendClaudeActivity, claudeLogPath } from "../../sessions/scan/claude";
+import { safeParse, ts } from "../../sessions/support/common";
+import { previousNativeLines } from "../native-lines";
+
+/** Recover only the exact previously advertised row in this native conversation. */
+export function nativeTranscriptEntry(session: SessionInfo, entryId: string,
+  cursor?: string): ActivityEntry | undefined {
+  if (!entryId.startsWith(`${session.sessionId}:`)) return undefined;
+  const path = session.agent === "codex" ? codexLogPathForSession(session.sessionId, session.startedAt)
+    : session.agent === "claude" ? claudeLogPath(session.sessionId) : undefined;
+  if (!path) return undefined;
+  const stamp = session.agent === "codex" ? Number(entryId.slice(session.sessionId.length + 1).split(":")[0]) : undefined;
+  if (stamp != null && !Number.isFinite(stamp)) return undefined;
+  let pageCursor = cursor;
+  try {
+    while (true) {
+      const window = previousNativeLines(path, session.sessionId, pageCursor);
+      if (!window) return undefined;
+      let earliest = Infinity;
+      for (const line of window.lines) {
+        const row = safeParse(line.text), at = ts(row?.timestamp);
+        if (at) earliest = Math.min(earliest, at);
+        if (stamp != null && at !== stamp) continue;
+        const out: ActivityEntry[] = [], seen = new Set<string>(), observations = new Map();
+        if (session.agent === "codex") {
+          appendCodexActivity({ out, seen, session, lines: [line.text], observations,
+            changes: new Map(), details: new Map(), fullText: true });
+        } else {
+          appendClaudeActivity({ out, seen, session, lines: [line.text], observations, fullText: true });
+        }
+        const found = out.find(entry => entry.id === entryId);
+        if (found) return found;
+      }
+      if (window.start === 0 || (stamp != null && earliest < stamp)) return undefined;
+      const next = window.lines[0]?.offset ?? window.start;
+      if (next >= window.end) return undefined;
+      pageCursor = window.cursorAt(next);
+    }
+  } catch { return undefined; }
+}

package/apps/bridge/src/transcript-history/images/native.ts

@@ -22,7 +22,8 @@ export function nativeTranscriptImage(session: SessionInfo, imageId: string, off
   if (!path || !['claude', 'codex'].includes(session.agent)) return undefined;
   try {
     let pageCursor = cursor;
-    for (let page = 0; page < 32; page++) {
+    // Old advertised pictures remain readable as the conversation grows.
+    while (true) {
       const window = previousNativeLines(path, session.sessionId, pageCursor);
       if (!window) return undefined;
       const lines = window.lines.map(line => line.text);
@@ -49,7 +50,9 @@ export function nativeTranscriptImage(session: SessionInfo, imageId: string, off
       }
     }
       if (window.start === 0) break;
-      pageCursor = window.cursorAt(window.lines[0]?.offset ?? window.start);
+      const next = window.lines[0]?.offset ?? window.start;
+      if (next >= window.end) break;
+      pageCursor = window.cursorAt(next);
     }
   } catch { return undefined; }
   return undefined;

package/apps/bridge/src/transcript-history/images.ts

@@ -11,7 +11,9 @@ export function nativeImageLines(sessionId: string, entryId: string): string[] |
   if (!path || !Number.isFinite(stamp) || !Number.isSafeInteger(blockIndex) || blockIndex < 0) return undefined;
   let cursor: string | undefined;
   try {
-    for (let page = 0; page < 32; page++) {
+    // A saved attachment does not expire when newer transcript windows append.
+    // Each window stays bounded and its cursor must move toward the file start.
+    while (true) {
       const window = previousNativeLines(path, sessionId, cursor);
       if (!window) return undefined;
       let earliest = Infinity;
@@ -24,7 +26,9 @@ export function nativeImageLines(sessionId: string, entryId: string): string[] |
           && p.content[blockIndex]?.type === "input_image") return [line.text];
       }
       if (window.start === 0 || earliest < stamp) return undefined;
-      cursor = window.cursorAt(window.lines[0]?.offset ?? window.start);
+      const next = window.lines[0]?.offset ?? window.start;
+      if (next >= window.end) return undefined;
+      cursor = window.cursorAt(next);
     }
   } catch { return undefined; }
   return undefined;

package/apps/bridge/src/transcript-history/index.ts

@@ -8,6 +8,7 @@ import { recordedToolDetails } from "./tool-details";
 import { completedTurnChanges } from "./turn-changes";
 export { nativeImageLines } from "./images";
 export { nativeTranscriptImage } from './images/native';
+export { nativeTranscriptEntry } from './images/advertised-entry';
 
 function boundedEntry(entry: ActivityEntry): ActivityEntry {
   const result = { ...entry };

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/image/index.ts

@@ -1,7 +1,7 @@
 import { artifactImages, artifactImageChunk } from "./artifacts";
 import { desktopTaskActivity } from "../task-activity";
 import type { ActivityEntry, SessionInfo, SessionActivity } from '../../../../../packages/protocol/schema';
-import { nativeTranscriptImage } from '../../../../bridge/src/transcript-history';
+import { nativeTranscriptImage, nativeTranscriptEntry } from '../../../../bridge/src/transcript-history';
 import { readStoreState } from '../../../../bridge/src/mesh/store/state';
 import { configDir } from '../../../../bridge/src/config';
 import { join } from 'node:path';
@@ -10,16 +10,25 @@ export function transcriptImages(entry: ActivityEntry) {
   return artifactImages(entry).map(({ id, name, markdown }) => ({ id, name, markdown }));
 }
 
+function sessionArtifact(session: SessionInfo, activity: { entries: Array<Parameters<typeof artifactImages>[0]> },
+  imageId: string, cursor?: string) {
+  const current = activity.entries.flatMap(artifactImages).find(image => image.id === imageId);
+  if (current) return current;
+  const entryId = imageId.match(/^(.*):image:[a-f0-9]{24}$/)?.[1];
+  const saved = entryId ? nativeTranscriptEntry(session, entryId, cursor) : undefined;
+  return saved ? artifactImages(saved).find(image => image.id === imageId) : undefined;
+}
+
 export function sessionImageChunk(session: SessionInfo, activity: SessionActivity,
   imageId: string, offset: number, cursor?: string, storePath?: string) {
   if (activity.sessionId !== session.sessionId) return undefined;
   const native = activity.entries.some(entry => entry.id === imageId && entry.kind === 'user'
     && entry.attachments?.includes('Image'));
-  if (native || imageId.startsWith(`${session.sessionId}:`)) {
+  if (!imageId.includes(':image:') && (native || imageId.startsWith(`${session.sessionId}:`))) {
     const picture = nativeTranscriptImage(session, imageId, offset, cursor);
     if (picture) return picture;
   }
-  const artifact = activity.entries.flatMap(artifactImages).find(image => image.id === imageId);
+  const artifact = sessionArtifact(session, activity, imageId, cursor);
   if (!artifact) return undefined;
   const loaded = readStoreState(storePath ?? join(configDir(), 'project-mesh.json'));
   if (loaded.status !== 'ok') return undefined;
@@ -46,7 +55,11 @@ export function desktopTaskImage(input: unknown, storePath?: string,
   const activity = cachedActivity ?? desktopTaskActivity(query, storePath);
   if (!activity?.session_id || !activity.agent
     || activity.project_id !== query.project_id || activity.task_id !== query.task_id) return undefined;
-  const artifact = activity.entries.flatMap(artifactImages).find((image) => image.id === imageId);
+  const session: SessionInfo = { sessionId: activity.session_id, agent: activity.agent,
+    state: "idle", startedAt: 0, lastActivityAt: 0, tokensSession: 0, tokensLastTurn: 0 };
+  const cursor = query.history_cursor;
+  if (cursor !== undefined && (typeof cursor !== "string" || cursor.length > 512)) return undefined;
+  const artifact = sessionArtifact(session, activity, imageId, cursor as string | undefined);
   if (artifact) {
     const chunk = artifactImageChunk({ projectId: activity.project_id, taskId: activity.task_id,
       sessionId: activity.session_id, provider: activity.agent, image: artifact, offset, storePath });
@@ -55,10 +68,6 @@ export function desktopTaskImage(input: unknown, storePath?: string,
   if (!["codex", "claude"].includes(activity.agent)
     || !activity.entries.some((entry) => entry.id === imageId
       && entry.kind === "user" && entry.attachments?.includes("Image"))) return undefined;
-  const cursor = query.history_cursor;
-  if (cursor !== undefined && (typeof cursor !== "string" || cursor.length > 512)) return undefined;
-  const session: SessionInfo = { sessionId: activity.session_id, agent: activity.agent,
-    state: "idle", startedAt: 0, lastActivityAt: 0, tokensSession: 0, tokensLastTurn: 0 };
   const chunk = nativeTranscriptImage(session, imageId, offset, cursor as string | undefined);
   return chunk ? { operation: "desktop.task_image", image_id: imageId, ...chunk } : undefined;
 }

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.54
+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.54\";\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.54";
+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.54",
+  "version": "0.8.56",
   "description": "Personal live control center runtime for local coding agents on iPhone and Apple Watch.",
   "type": "module",
   "bin": {

package/packages/core/outbound-scheduler/README.md

@@ -11,11 +11,13 @@ Tests live in `tests/`; they include an actual WebSocket server with the relay's
 rate limit. A socket write is transport evidence, never an approval receipt.
 
 MIT License; see the repository LICENSE.
-# Active controllers
+# Controller delivery
 
-Authenticated incoming phone traffic marks that controller active for 90 seconds.
-Large replaceable encrypted task/project data targets recent controllers while
-catalogs, liveness, approval status and reliable messages retain every authorized
-recipient. Current catalogs and liveness pass queued bulk frames. A transport with no recent controller falls back to
-the complete authorized set for legacy clients and reconnection. Routing never
-deletes a pairing or replaces the controller authorization gate.
+Catalogs, liveness and shared conversation updates reach every authorized
+controller, including a phone receiving passively. Silence never removes access
+to its local replica. Authenticated history, subscription and image requests
+return their independent key grant and encrypted result only to the requesting
+controller, with priority over queued periodic snapshots. Older callers without
+a requester retain the complete authorized recipient set. Every explicit target
+passes the pairing and controller authorization checks. Routing never deletes a
+pairing or changes approval policy.

package/packages/core/outbound-scheduler/index.ts

@@ -3,7 +3,6 @@ import type { PeerConfig, SendOptions } from "../relay-client-types";
 import type { Payload, Role } from "../../protocol/schema";
 import { peerPublicKeys } from "../crypto";
 import { sealEnvelope } from "../relay-envelope";
-export { ActiveControllerRecipients } from "./active-controllers";
 
 type Job = { frame: string; bytes: number; resolve: () => void; reject: (error: Error) => void };
 const CLOSED = () => new Error("relay connection closed before delivery");

package/packages/core/relay-client-types.ts

@@ -41,6 +41,8 @@ export type RelayClientOptions = {
 };
 
 export type SendOptions = {
+  /** Reply only to the authenticated requester; absent means all authorized peers. */
+  peerPublicKey?: string;
   /** Delivery lifetime for relay hold queues. Omit only for non-expiring hello packets. */
   ttlMs?: number;
   deliveryId?: string;

package/packages/core/relay-client.ts

@@ -10,7 +10,7 @@
  * the Cloudflare Durable Object deployment.
  */
 import WebSocket from "ws";
-import { OutboundFrameQueue, sendEncryptedPayload, ActiveControllerRecipients } from "./outbound-scheduler";
+import { OutboundFrameQueue, sendEncryptedPayload } from "./outbound-scheduler";
 import { createHash } from "node:crypto";
 import { Envelope, Payload, type Role } from "../protocol/schema";
 import { openFromPeersWithIdentity, openWithTransferKey, peerPublicKeys, seal, sealWithTransferKey } from "./crypto";
@@ -34,7 +34,6 @@ export class RelayClient {
   private livenessTimer?: NodeJS.Timeout;
   private awaitingPong = false;
   private readonly sessionKeys = new Map<string, string>();
-  private readonly activeControllers = new ActiveControllerRecipients();
   /**
    * Delivery ids are relay-controlled metadata, so replay protection is bound
    * to the authenticated ciphertext itself. Keep a bounded process-local set:
@@ -200,9 +199,6 @@ export class RelayClient {
       this.sessionKeys.set(payload.sessionId, payload.key);
     }
     if (this.processingCiphertexts.has(fingerprint)) return;
-    if (this.cfg.role === "machine" && (payload.type !== "hello" || payload.role === "phone")) {
-      this.activeControllers.observe(peerPublicKey);
-    }
     this.processingCiphertexts.add(fingerprint);
     try {
       const results = await Promise.all([...this.listeners].map(async (listener) => {
@@ -238,10 +234,11 @@ export class RelayClient {
     const ws = this.ws;
     if (!ws || ws.readyState !== WebSocket.OPEN) throw new Error("relay not connected");
     if (!this.frames) throw new Error("relay not connected");
-    const replaceable = this.cfg.role === "machine" && to === "phone"
-      && options.reliable === false && payload.type === "session.sealed";
-    await sendEncryptedPayload(this.frames, this.cfg,
-      key => this.peerIsAllowed(key) && this.activeControllers.allows(key, replaceable),
+    if (options.peerPublicKey) {
+      await this.sendToPeer(payload, options.peerPublicKey, options);
+      return;
+    }
+    await sendEncryptedPayload(this.frames, this.cfg, key => this.peerIsAllowed(key),
       { payload, to, options });
   }
 

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,

package/packages/core/outbound-scheduler/active-controllers.ts

@@ -1,15 +0,0 @@
-/** Activity routes replaceable traffic; authorization remains a separate check. */
-export class ActiveControllerRecipients {
-  private readonly seen = new Map<string, number>();
-
-  observe(peer: string, now = Date.now()): void {
-    this.seen.set(peer, now);
-  }
-
-  allows(peer: string, replaceable: boolean, now = Date.now()): boolean {
-    if (!replaceable) return true;
-    const active = [...this.seen].filter(([, at]) => now >= at && now - at <= 90_000);
-    // A newly connected transport has not heard its controllers yet.
-    return active.length === 0 || active.some(([key]) => key === peer);
-  }
-}