granttap-mcp 0.8.89 → 0.8.91

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

@@ -8,6 +8,7 @@ import type {
   MeshEvent,
   MeshSnapshot,
   MeshInvocationPage,
+  ProjectKnowledgePage,
   Payload,
   ProjectPolicyPayload,
   Role,
@@ -53,7 +54,7 @@ export async function sendMeshPayload(
 
 export async function sendProjectPayload(
   client: RelayClient,
-  payload: ProjectPolicyPayload | MeshClaimReleaseResult | MeshInvocationPage,
+  payload: ProjectPolicyPayload | MeshClaimReleaseResult | MeshInvocationPage | ProjectKnowledgePage,
   to: Role | "all" = "phone",
   options: SendOptions = {},
 ): Promise<void> {

package/apps/bridge/src/mesh/admin/capsule.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
 import {
   TaskCapsule,
   type MeshHandoffPrepare,
@@ -42,6 +43,11 @@ function changedFiles(cwd: string): string[] {
   return [...new Set(files)].slice(0, 64);
 }
 
+function sameCheckout(path: string | undefined, cwd: string): boolean {
+  try { return path != null && realpathSync(path) === realpathSync(cwd); }
+  catch { return false; }
+}
+
 /** The identity of the uncommitted changes, so a later reading can tell they are the same. */
 export function dirtyDiffHash(cwd: string): string | undefined {
   const diff = git(cwd, ["diff", "--binary", "HEAD"]);
@@ -74,6 +80,9 @@ export function buildTaskCapsule(
   if (!head) return undefined;
   const tree = workingTreeState(cwd);
   const files = changedFiles(cwd);
+  const sourceBinding = snapshot.bindings?.find(binding => binding.endpointId === computerId
+    && binding.available && sameCheckout(binding.localPathHint, cwd)
+    && (!request.sourceBindingId || binding.bindingId === request.sourceBindingId));
   const capsule = {
     taskId: request.taskId,
     goal: task.goal,
@@ -85,7 +94,7 @@ export function buildTaskCapsule(
     targetComputer: request.targetComputer,
     targetModel: request.targetModel,
     userComment: request.userComment,
-    repository: project.canonicalRepositoryId,
+    repository: sourceBinding?.repositoryId ?? project.canonicalRepositoryId,
     baseSha: head,
     branch: session.branch ?? git(cwd, ["branch", "--show-current"]),
     latestCommit: head,

package/apps/bridge/src/mesh/catalog/binding-state.ts

@@ -69,6 +69,11 @@ export function workspaceForRepository(
   canonicalRepositoryId: string,
   computerId?: string,
 ): string | undefined {
+  // A Project can contain several repositories. Its first execution may be
+  // rooted in their parent folder, so an exact owned binding takes precedence.
+  const binding = state.bindings.find(item => item.repositoryId === canonicalRepositoryId
+    && item.available && (computerId == null || item.endpointId === computerId));
+  if (binding?.localPathHint) return binding.localPathHint;
   const projectIds = new Set([
     ...state.bindings
       .filter((binding) => binding.repositoryId === canonicalRepositoryId)

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

@@ -139,6 +139,11 @@ export function linkSessionsToProjects(
   // Share one consistent reading within this catalog batch, then discard it.
   // A new Git checkout or origin must be discovered on the next refresh.
   const repositories = new Map<string, RepositoryFacts>();
+  const workingTrees = new Map<string, boolean | undefined>();
+  const inspectWorkingTree = (cwd: string): boolean | undefined => {
+    if (!workingTrees.has(cwd)) workingTrees.set(cwd, hasUncommittedWork(cwd));
+    return workingTrees.get(cwd);
+  };
   const inspectOnce = (cwd: string): RepositoryFacts => {
     let facts = repositories.get(cwd);
     if (!facts) {
@@ -147,7 +152,7 @@ export function linkSessionsToProjects(
     }
     return facts;
   };
-  return visible.map((session) => linkSession({ store, session, computerId, inspect: inspectOnce }));
+  return visible.map((session) => linkSession({ store, session, computerId, inspect: inspectOnce, inspectWorkingTree }));
 }
 
 function linkSession(input: {
@@ -155,6 +160,7 @@ function linkSession(input: {
   session: SessionInfo;
   computerId: string;
   inspect: (cwd: string) => RepositoryFacts;
+  inspectWorkingTree: (cwd: string) => boolean | undefined;
 }): SessionInfo {
   const { store, session, computerId, inspect } = input;
   const agent = provider(session.agent);
@@ -228,7 +234,7 @@ function linkSession(input: {
     state: session.state, continuedAt: session.transfer?.continuedAt,
     branch: repository.branch ?? session.branch,
     worktree: repository.worktree,
-    uncommitted: hasUncommittedWork(repository.worktree ?? cwd),
+    uncommitted: input.inspectWorkingTree(repository.worktree ?? cwd),
     startedAt: session.startedAt,
   });
   return { ...session, projectId, taskId, computerId, worktree: repository.worktree };

package/apps/bridge/src/mesh/knowledge/README.md

@@ -12,3 +12,11 @@ Engine validates its scope. The phone may replay the same ID after a lost reply.
 This is not a migration of old chats into verified knowledge.
 
 GrantTap Commercial Source License.
+
+`read.ts` is the bounded Project evidence read: Memory and the invocation journal
+run in parallel with independent deadlines. Calls may belong to older Tasks
+outside the current phone snapshot. A failed source leaves the other source
+available. Whole records are omitted to fit the encrypted frame budget; record
+content is never shortened. `runtime-read.ts` exposes this read over local Mac
+IPC and an authenticated, requester-scoped Project relay response. It does not
+rescan provider chats or rebuild architecture.

package/apps/bridge/src/mesh/knowledge/read.ts

@@ -0,0 +1,65 @@
+import type { MeshSnapshot, ProjectKnowledgeRecord } from "../../../../../packages/protocol/schema";
+import { ProjectKnowledgePage, ProjectKnowledgeQuery } from "../../../../../packages/protocol/messages/mesh/knowledge/refresh";
+import type { InvocationHistoryPage } from "../../engine/protocol/engine-invocation-protocol";
+import { activeProjectKnowledge, supersededProjectKnowledgeIds } from "./active";
+
+export type KnowledgeReadDependencies = {
+  snapshot: (projectId: string) => MeshSnapshot | undefined;
+  memory: (projectId: string) => Promise<ProjectKnowledgeRecord[] | undefined>;
+  history: (projectId: string) => Promise<InvocationHistoryPage | undefined>;
+  endpointId: string;
+  now: () => number;
+  timeoutMs?: number;
+};
+
+export async function readProjectKnowledge(
+  query: ProjectKnowledgeQuery, dependencies: KnowledgeReadDependencies,
+): Promise<ProjectKnowledgePage | undefined> {
+  if (!ProjectKnowledgeQuery.safeParse(query).success) return undefined;
+  const snapshot = dependencies.snapshot(query.projectId);
+  if (!snapshot || snapshot.projectId !== query.projectId) return undefined;
+  const timeout = dependencies.timeoutMs ?? 2_000;
+  let [memory, history] = await Promise.all([
+    boundedSource(() => dependencies.memory(query.projectId), timeout),
+    boundedSource(() => dependencies.history(query.projectId), timeout),
+  ]);
+  if (memory?.some(record => record.projectId !== query.projectId || record.visibility !== "project")) {
+    memory = undefined;
+  }
+  if (history?.events.some(row => row.event.project_id !== query.projectId)) history = undefined;
+  const records = memory ?? [];
+  const knowledge = activeProjectKnowledge(query.projectId, records)
+    .sort((a, b) => b.recordedAt - a.recordedAt).slice(0, 32);
+  const invocations = (history?.events ?? []).slice(-32);
+  const page: ProjectKnowledgePage = {
+    type: "mesh.knowledge.page", sessionId: query.projectId, projectId: query.projectId,
+    requestId: query.requestId, sourceEndpointId: dependencies.endpointId,
+    memoryAvailability: memory ? "ready" : "unavailable",
+    invocationAvailability: history ? "ready" : "unavailable",
+    knowledge, invocations,
+    supersededKnowledgeRecordIds: supersededProjectKnowledgeIds(query.projectId, records),
+    incomplete: records.length > knowledge.length || history?.has_older === true
+      || history?.has_more === true,
+    generatedAt: dependencies.now(),
+  };
+  // Keep encrypted frames below the transport limit without shortening a fact.
+  while (Buffer.byteLength(JSON.stringify(page)) > 128 * 1_024
+    && (knowledge.length > 0 || invocations.length > 0)) {
+    const oldestRecord = knowledge.at(-1)?.recordedAt ?? Infinity;
+    const oldestCall = invocations[0]?.event.occurred_at ?? Infinity;
+    if (oldestRecord <= oldestCall) knowledge.pop();
+    else invocations.shift();
+    page.incomplete = true;
+  }
+  return ProjectKnowledgePage.parse(page);
+}
+
+async function boundedSource<T>(read: () => Promise<T>, timeoutMs: number): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([Promise.resolve().then(read), new Promise<undefined>(resolve => {
+      timer = setTimeout(() => resolve(undefined), timeoutMs);
+    })]);
+  } catch { return undefined; }
+  finally { if (timer) clearTimeout(timer); }
+}

package/apps/bridge/src/mesh/knowledge/runtime-read.ts

@@ -0,0 +1,49 @@
+import { join } from "node:path";
+import type { RelayClient } from "../../../../../packages/core/relay-client";
+import { ProjectKnowledgeQuery } from "../../../../../packages/protocol/messages/mesh/knowledge/refresh";
+import { configDir } from "../../config/runtime/paths";
+import { EngineClient } from "../../engine/runtime/engine-client";
+import { engineFeatureEnabled } from "../../engine/runtime/engine-supervisor";
+import { projectKnowledge } from "../../engine/runtime/engine-memory";
+import { sendProjectPayload } from "../../host/session-keys";
+import { computerId } from "../identity/computer";
+import { localMeshStore } from "../local-remote/local";
+import { readProjectKnowledge } from "./read";
+
+const engine = new EngineClient({ socketPath: join(configDir(), "engine.sock") });
+
+export async function currentProjectKnowledge(query: ProjectKnowledgeQuery) {
+  return readProjectKnowledge(query, {
+    snapshot: projectId => localMeshStore().snapshot(projectId),
+    endpointId: computerId(), now: Date.now,
+    memory: projectId => projectKnowledge(projectId),
+    history: async projectId => {
+      if (!engineFeatureEnabled()) return undefined;
+      const result = await engine.request({ operation: "invocation.history",
+        input: { project_id: projectId, tail: true, limit: 32 } }, { timeoutMs: 1_000 });
+      return result.operation === "invocation.history" ? result.page : undefined;
+    },
+  });
+}
+
+export async function handleProjectKnowledgeQuery(
+  client: RelayClient, query: ProjectKnowledgeQuery, peerPublicKey?: string,
+): Promise<boolean> {
+  if (!peerPublicKey) return false;
+  const page = await currentProjectKnowledge(query);
+  if (!page) return false;
+  if (page.memoryAvailability === "ready") {
+    localMeshStore().cacheKnowledge(page.projectId, page.knowledge);
+  }
+  await sendProjectPayload(client, page, "phone", {
+    peerPublicKey, ttlMs: 15_000, reliable: false,
+  }).catch(() => {});
+  return true;
+}
+
+export async function desktopProjectKnowledge(input: unknown) {
+  const value = input as { project_id?: unknown; request_id?: unknown } | undefined;
+  const query = ProjectKnowledgeQuery.safeParse({ type: "mesh.knowledge.query",
+    projectId: value?.project_id, sessionId: value?.project_id, requestId: value?.request_id });
+  return query.success ? currentProjectKnowledge(query.data) : undefined;
+}

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

@@ -21,13 +21,10 @@ import {
 } from "../../reply";
 import { isProviderEnabled } from "../../config/runtime";
 import { sendMeshPayload } from "../../host/session-keys";
-import { linkSessionsToProjects, workingTreeState } from "../catalog";
+import { linkSessionsToProjects } from "../catalog";
 import { catalogFromEndpoint } from "../catalog/models";
 import { saveProjectCapabilityRequest } from "../catalog/project/requests";
 import { computerId } from "../identity/computer";
-import { createCheckpoint } from "../admin/checkpoint";
-import { buildTaskCapsule } from "../admin/capsule";
-import { handoffReadiness } from "../tasks/readiness";
 import { createHandoffFlow } from "./handoff";
 import type { MeshRuntimeDependencies } from "./dependencies";
 import { localMeshStore } from "../local-remote/local";
@@ -37,9 +34,8 @@ import { createHandoffWorktree, repositoryHasCommit } from "./worktree";
 import { fetchRevision, pushBranch } from "../local-remote/remote";
 import { projectSessionCapabilityInventory } from "./capabilities";
 import { createMeshSessionCatalog } from "./catalog/session-catalog";
-import { capturePreparedHandoff, preparedHandoffMetadata } from './prepared-transfer';
+import { prepareHandoff } from "./prepared-transfer/prepare";
 import { sourceCheckoutUnchanged } from './prepared-transfer/source-checkout';
-import { prepareCloudHandoff } from "./cloud-handoff";
 
 export type { MeshRuntimeDependencies };
 
@@ -84,105 +80,6 @@ const defaultDependencies: MeshRuntimeDependencies = {
   }),
 };
 
-async function prepareHandoff(
-  deps: MeshRuntimeDependencies,
-  flow: ReturnType<typeof createHandoffFlow>,
-  client: RelayClient,
-  request: MeshHandoffPrepare,
-  catalog: (sessions: SessionInfo[]) => SessionInfo[],
-): Promise<boolean> {
-  const { blockHandoff, acceptHandoff } = flow;
-  const sessions = catalog(deps.sessions());
-  const session = sessions.find((item) => item.sessionId === request.sessionId);
-  if (!session || session.projectId !== request.projectId || session.taskId !== request.taskId) {
-    return false;
-  }
-  if (request.prepareOnly && session.state === "working") {
-    await blockHandoff(client, request, "Pause or finish the current turn before transferring this Task.");
-    return false;
-  }
-  const cwd = session.worktree ?? session.cwd;
-  const made = request.checkpoint && cwd && workingTreeState(cwd) === "dirty"
-    ? createCheckpoint(cwd, request.taskId, session.title ?? request.taskId, request.createdAt)
-    : undefined;
-  const shared = made && cwd
-    ? sessions.some((other) =>
-      other.sessionId !== session.sessionId
-      && other.taskId != null && other.taskId !== request.taskId
-      && (other.worktree ?? other.cwd) === cwd)
-    : false;
-  const checkpoint = made && shared ? { ...made, status: "requires_review" as const } : made;
-  let capsule = buildTaskCapsule(deps.store(), session, request, deps.computer(), checkpoint);
-  const readiness = handoffReadiness({
-    capsule,
-    targetProviderEnabled: request.targetProvider === "grok_bot"
-      || deps.providerEnabled(request.targetProvider),
-    conflicts: (capsule?.resourceClaims ?? []).flatMap((resource) =>
-      deps.store().conflicts(request.projectId, request.sessionId, resource, {
-        repositoryId: capsule?.repository, endpointId: deps.computer(), worktree: cwd,
-      }, true)),
-    moduleOverlaps: (capsule?.resourceClaims ?? []).flatMap((resource) =>
-      deps.store().moduleOverlaps(request.projectId, request.sessionId, resource, {
-        repositoryId: capsule?.repository, endpointId: deps.computer(), worktree: cwd,
-      })),
-  });
-  if (!readiness.ready) {
-    await blockHandoff(client, request, readiness.blockedReason ?? "Handoff is not ready.");
-    return false;
-  }
-  if (!capsule) return false;
-  if (request.cloud) return prepareCloudHandoff({ deps, block: blockHandoff, client, request, session, capsule });
-  let transferContext: string | undefined;
-  let confirmContext: (() => Promise<boolean>) | undefined;
-  if (request.prepareOnly) {
-    try {
-      const captured = await capturePreparedHandoff(deps, session, capsule);
-      transferContext = captured.transferContext;
-      capsule = captured.capsule;
-      confirmContext = captured.confirm;
-    } catch (error) {
-      await blockHandoff(client, request, error instanceof Error ? error.message : "The complete transfer context is unavailable.");
-      return false;
-    }
-  }
-  const local = request.targetComputer === deps.computer();
-  if (request.push && !local && cwd) {
-    const pushed = deps.push(cwd, capsule.branch);
-    if (!pushed.ok) {
-      await blockHandoff(client, request, pushed.error);
-      return false;
-    }
-  }
-  const createdAt = deps.now();
-  const event: MeshEvent = {
-    type: "mesh.event",
-    sessionId: request.taskId,
-    eventId: deps.eventId(),
-    projectId: request.projectId,
-    taskId: request.taskId,
-    sourceSessionId: request.sessionId,
-    eventType: "HANDOFF_REQUEST",
-    createdAt,
-    expiresAt: createdAt + 60 * 60_000,
-    payload: { capsule, transferContext },
-  };
-  if (request.prepareOnly && !local && deps.dispatchPreparedTransfer) {
-    try {
-      if (await deps.dispatchPreparedTransfer(event, session, confirmContext!)) {
-        await deps.send(client, preparedHandoffMetadata(event), { ttlMs: 60 * 60_000, wake: true }).catch(() => {});
-        return true;
-      }
-      await blockHandoff(client, request, 'Project computer transfer is not configured for this destination. Connect its Project in GrantTap.');
-    } catch (error) {
-      await blockHandoff(client, request, error instanceof Error ? error.message : 'The transfer could not be saved.');
-    }
-    return false;
-  }
-  deps.store().acceptEvent(event);
-  await deps.send(client, request.prepareOnly ? preparedHandoffMetadata(event) : event, { ttlMs: 60 * 60_000, wake: true });
-  if (local) await acceptHandoff(client, event);
-  return true;
-}
 
 export function createMeshRuntime(deps: MeshRuntimeDependencies) {
   const flow = createHandoffFlow(deps);

package/apps/bridge/src/mesh/runtime/prepared-transfer/README.md

@@ -0,0 +1,26 @@
+# Preparing a Task transfer
+
+`prepare.ts` prepares one scoped transfer through the Mesh runtime's public
+entry point. `source.ts` checks the source facts and the explicit checkpoint
+choice; `index.ts` captures and confirms complete visible context.
+
+A missing source chat sends a scoped `TASK_BLOCKED` result so the controller can
+explain the refusal. Preparing does not launch the destination provider. Work
+starts when the person sends the prepared chat its first message.
+
+Catalog batches share a working-tree probe for chats in the same checkout.
+The next batch reads it again, including unknown results, so this never hides
+new uncommitted work behind a persistent cache.
+
+For a chat started above its repositories, `source-binding.ts` resolves an
+explicit `sourceBindingId` only within the owning endpoint's available Project
+bindings. It verifies the actual Git root and identity before capturing context.
+An exact repository binding takes precedence over a Project's parent execution
+folder. Preparing keeps the native source folder unchanged and launches no
+provider. Rejected preparations also publish their retained Project state.
+
+Tests: `tests/metadata.test.ts`, `tests/source-checkout.test.ts`,
+`tests/mesh/mesh-handoff-safety.test.ts`, and catalog
+`tests/working-tree-batch.test.ts`.
+
+Licensed under the GrantTap Commercial Source License. See LICENSE and NOTICE.

package/apps/bridge/src/mesh/runtime/prepared-transfer/index.ts

@@ -9,7 +9,8 @@ export function preparedHandoffMetadata(event: MeshEvent): MeshEvent {
 }
 
 /** Retains the original archive facts so reconfirmation hashes the same conversation. */
-export async function capturePreparedHandoff(deps: MeshRuntimeDependencies, session: SessionInfo, facts: TaskCapsule) {
+export async function capturePreparedHandoff(deps: MeshRuntimeDependencies, session: SessionInfo,
+  facts: TaskCapsule, native = session) {
   const capture = deps.captureTransferContext ?? captureTransferContext;
   const captured = await capture(session, facts);
   const task = deps.store().task(facts.taskId);
@@ -19,9 +20,10 @@ export async function capturePreparedHandoff(deps: MeshRuntimeDependencies, sess
     confirm: async () => {
       const current = deps.sessions().find(row => row.sessionId === session.sessionId);
       if (!current || current.state === 'working' || current.model !== session.model || current.effort !== session.effort
-        || (current.worktree ?? current.cwd) !== (session.worktree ?? session.cwd)
-        || deps.sourceCaptureCurrent && !deps.sourceCaptureCurrent(current, facts)) return false;
-      try { return (await capture(current, facts)).hash === captured.hash; }
+        || (current.worktree ?? current.cwd) !== (native.worktree ?? native.cwd)) return false;
+      const resolved = { ...current, worktree: session.worktree, branch: session.branch };
+      if (deps.sourceCaptureCurrent && !deps.sourceCaptureCurrent(resolved, facts)) return false;
+      try { return (await capture(resolved, facts)).hash === captured.hash; }
       catch { return false; }
     } };
 }

package/apps/bridge/src/mesh/runtime/prepared-transfer/prepare.ts

@@ -0,0 +1,93 @@
+import type { RelayClient } from "../../../../../../packages/core/relay-client";
+import type { MeshEvent, MeshHandoffPrepare, SessionInfo } from "../../../../../../packages/protocol/schema";
+import type { MeshRuntimeDependencies } from "../dependencies";
+import { createHandoffFlow } from "../handoff";
+import { prepareCloudHandoff } from "../cloud-handoff";
+import { capturePreparedHandoff, preparedHandoffMetadata } from ".";
+import { prepareSourceCapsule } from "./source";
+import { resolveHandoffSource } from "./source-binding";
+
+export async function prepareHandoff(
+  deps: MeshRuntimeDependencies,
+  flow: ReturnType<typeof createHandoffFlow>,
+  client: RelayClient,
+  request: MeshHandoffPrepare,
+  catalog: (sessions: SessionInfo[]) => SessionInfo[],
+): Promise<boolean> {
+  const { blockHandoff, acceptHandoff } = flow;
+  const sessions = catalog(deps.sessions());
+  const native = sessions.find((item) => item.sessionId === request.sessionId);
+  let session = native;
+  if (!session) {
+    const task = deps.store().task(request.taskId);
+    if (task?.projectId === request.projectId && task.ownerSessionId === request.sessionId) {
+      await blockHandoff(client, request, "The source chat is no longer available. Refresh this Task on its computer and retry.");
+    }
+    return false;
+  }
+  if (session.projectId !== request.projectId || session.taskId !== request.taskId) return false;
+  try { session = resolveHandoffSource(deps.store(), session, request, deps.computer()); }
+  catch (error) {
+    await blockHandoff(client, request, (error as Error).message);
+    return false;
+  }
+  if (request.prepareOnly && session.state === "working") {
+    await blockHandoff(client, request, "Pause or finish the current turn before transferring this Task.");
+    return false;
+  }
+  const cwd = session.worktree ?? session.cwd;
+  let capsule = await prepareSourceCapsule({ deps, blockHandoff, client, request, session, sessions });
+  if (!capsule) return false;
+  if (request.cloud) return prepareCloudHandoff({ deps, block: blockHandoff, client, request, session, capsule });
+  let transferContext: string | undefined;
+  let confirmContext: (() => Promise<boolean>) | undefined;
+  if (request.prepareOnly) {
+    try {
+      const captured = await capturePreparedHandoff(deps, session, capsule, native);
+      transferContext = captured.transferContext;
+      capsule = captured.capsule;
+      confirmContext = captured.confirm;
+    } catch (error) {
+      await blockHandoff(client, request, error instanceof Error ? error.message : "The complete transfer context is unavailable.");
+      return false;
+    }
+  }
+  const local = request.targetComputer === deps.computer();
+  if (request.push && !local && cwd) {
+    const pushed = deps.push(cwd, capsule.branch);
+    if (!pushed.ok) {
+      await blockHandoff(client, request, pushed.error);
+      return false;
+    }
+  }
+  const createdAt = deps.now();
+  const event: MeshEvent = {
+    type: "mesh.event",
+    sessionId: request.taskId,
+    eventId: deps.eventId(),
+    projectId: request.projectId,
+    taskId: request.taskId,
+    sourceSessionId: request.sessionId,
+    eventType: "HANDOFF_REQUEST",
+    createdAt,
+    expiresAt: createdAt + 60 * 60_000,
+    payload: { capsule, transferContext },
+  };
+  if (request.prepareOnly && !local && deps.dispatchPreparedTransfer) {
+    try {
+      if (await deps.dispatchPreparedTransfer(event, session, confirmContext!)) {
+        await deps.send(client, preparedHandoffMetadata(event), { ttlMs: 60 * 60_000, wake: true }).catch(() => {});
+        return true;
+      }
+      await blockHandoff(client, request, 'Project computer transfer is not configured for this destination. Connect its Project in GrantTap.');
+    } catch (error) {
+      await blockHandoff(client, request, error instanceof Error ? error.message : 'The transfer could not be saved.');
+    }
+    return false;
+  }
+  deps.store().acceptEvent(event);
+  await deps.send(client, request.prepareOnly ? preparedHandoffMetadata(event) : event, { ttlMs: 60 * 60_000, wake: true });
+  if (local) await acceptHandoff(client, event);
+  return true;
+}
+

package/apps/bridge/src/mesh/runtime/prepared-transfer/source-binding.ts

@@ -0,0 +1,24 @@
+import { realpathSync } from 'node:fs';
+import type { MeshHandoffPrepare, SessionInfo } from '../../../../../../packages/protocol/schema';
+import { inspectRepository } from '../../catalog';
+import type { MeshStore } from '../../store';
+import { matchesLocalCheckout } from '../graph/checkout-identity';
+
+/** The controller chooses an already admitted binding, never an arbitrary path. */
+export function resolveHandoffSource(store: MeshStore, session: SessionInfo,
+  request: MeshHandoffPrepare, computer: string): SessionInfo {
+  if (!request.sourceBindingId) return session;
+  const binding = store.snapshot(request.projectId)?.bindings?.find(row =>
+    row.bindingId === request.sourceBindingId && row.projectId === request.projectId
+      && row.endpointId === computer && row.available);
+  if (binding?.localPathHint) {
+    const facts = inspectRepository(binding.localPathHint);
+    try {
+      if (facts.worktree && facts.revision && realpathSync(facts.root) === realpathSync(binding.localPathHint)
+        && (facts.canonicalRepositoryId === binding.repositoryId || matchesLocalCheckout(binding.repositoryId, facts.root))) {
+        return { ...session, worktree: facts.root, branch: facts.branch };
+      }
+    } catch { /* A removed checkout is not an admitted replacement. */ }
+  }
+  throw new Error('The selected repository is not available on this computer. Refresh the Project and choose its checkout again.');
+}

package/apps/bridge/src/mesh/runtime/prepared-transfer/source.ts

@@ -0,0 +1,45 @@
+import type { RelayClient } from "../../../../../../packages/core/relay-client";
+import type { MeshHandoffPrepare, SessionInfo } from "../../../../../../packages/protocol/schema";
+import type { MeshRuntimeDependencies } from "../dependencies";
+import type { createHandoffFlow } from "../handoff";
+import { workingTreeState } from "../../catalog";
+import { createCheckpoint } from "../../admin/checkpoint";
+import { buildTaskCapsule } from "../../admin/capsule";
+import { handoffReadiness } from "../../tasks/readiness";
+
+/** Read source facts once, preserving the person's checkpoint choice. */
+export async function prepareSourceCapsule(input: { deps: MeshRuntimeDependencies;
+  blockHandoff: ReturnType<typeof createHandoffFlow>["blockHandoff"]; client: RelayClient;
+  request: MeshHandoffPrepare; session: SessionInfo; sessions: SessionInfo[] }) {
+  const { deps, blockHandoff, client, request, session, sessions } = input;
+  const cwd = session.worktree ?? session.cwd;
+  const made = request.checkpoint && cwd && workingTreeState(cwd) === "dirty"
+    ? createCheckpoint(cwd, request.taskId, session.title ?? request.taskId, request.createdAt)
+    : undefined;
+  const shared = made && cwd
+    ? sessions.some((other) =>
+      other.sessionId !== session.sessionId
+      && other.taskId != null && other.taskId !== request.taskId
+      && (other.worktree ?? other.cwd) === cwd)
+    : false;
+  const checkpoint = made && shared ? { ...made, status: "requires_review" as const } : made;
+  const capsule = buildTaskCapsule(deps.store(), session, request, deps.computer(), checkpoint);
+  const readiness = handoffReadiness({
+    capsule,
+    targetProviderEnabled: request.targetProvider === "grok_bot"
+      || deps.providerEnabled(request.targetProvider),
+    conflicts: (capsule?.resourceClaims ?? []).flatMap((resource) =>
+      deps.store().conflicts(request.projectId, request.sessionId, resource, {
+        repositoryId: capsule?.repository, endpointId: deps.computer(), worktree: cwd,
+      }, true)),
+    moduleOverlaps: (capsule?.resourceClaims ?? []).flatMap((resource) =>
+      deps.store().moduleOverlaps(request.projectId, request.sessionId, resource, {
+        repositoryId: capsule?.repository, endpointId: deps.computer(), worktree: cwd,
+      })),
+  });
+  if (!readiness.ready) {
+    await blockHandoff(client, request, readiness.blockedReason ?? "Handoff is not ready.");
+    return undefined;
+  }
+  return capsule;
+}

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

@@ -18,6 +18,7 @@ import {
 } from "../../mesh/runtime";
 import { releaseClaimByPerson, releaseResult } from "../../mesh/admin";
 import { handleInvocationQuery } from "../../engine/invocation/query";
+import { handleProjectKnowledgeQuery } from "../../mesh/knowledge/runtime-read";
 import { applyPairingJoin } from "../../pairing";
 import { recordPhoneSeen } from "../../pairing/presence";
 import { handleProjectPolicySet } from "../../project-policy/runtime";
@@ -123,6 +124,8 @@ export async function handleMonitorMessage(
       const accepted = requestProjectCapability(payload);
       if (accepted) void publish().catch(() => {});
       return accepted;
+    } else if (payload.type === "mesh.knowledge.query" && loadRuntimeConfig().meshEnabled) {
+      return handleProjectKnowledgeQuery(client, payload, input.peerPublicKey);
     } else if (payload.type === "mesh.invocation.query" && loadRuntimeConfig().meshEnabled) {
       return handleInvocationQuery(client, payload);
     } else if ((payload.type === "mesh.event" || payload.type === "mesh.snapshot")

package/apps/bridge/src/policy/governed-projects.ts

@@ -17,7 +17,7 @@ const MAX_PROJECTS = 256;
 
 const GovernedFile = z.object({
   version: z.literal(1),
-  projects: z.record(z.object({
+  projects: z.record(z.string(), z.object({
     revision: z.number().int().nonnegative(),
     at: z.number().nonnegative(),
   })),

package/apps/bridge/src/task-routing/admission/index.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { TaskRoutingNeeds } from '../../../../../packages/protocol/task-resources';
 import { loadConfig, loadRuntimeConfig, machineConfigPath } from '../../config';
 import { applyNetworkRoute } from '../../device-network/settings';
 import { scanSessions } from '../../sessions';
@@ -14,7 +15,7 @@ import { observedRoutingSession } from '../observed-turn';
 
 export const OffloadInput = z.object({ action: z.enum(['request', 'cancel', 'status']).optional(),
   operationId: z.string().trim().min(1).max(128).optional(),
-  requirements: RoutingRequirementsInput.partial().extend({ reason: RoutingRequirementsInput.shape.reason }).optional() }).strict();
+  requirements: TaskRoutingNeeds.partial().extend({ reason: RoutingRequirementsInput.shape.reason }).optional() }).strict();
 export type OffloadArguments = z.infer<typeof OffloadInput>;
 type Proof = { sessionId: string; provider: RoutingRequestSource['provider'] };
 type Ports = { store: RoutingRequests; enabled: () => boolean;

package/apps/bridge/src/task-transfer/runtime/commands.ts

@@ -4,9 +4,11 @@ import { prepareMeshHandoff } from '../../mesh/runtime';
 import { handleTransferContinuation } from './continuation';
 
 export async function handleTaskTransferCommand(client: RelayClient,
-  command: MeshHandoffPrepare | TaskTransferContinue, onAccepted: () => void): Promise<boolean> {
-  if (command.type === 'task.transfer.continue') return handleTransferContinuation(client, command, onAccepted);
-  const accepted = await prepareMeshHandoff(client, command);
-  if (accepted) onAccepted();
-  return accepted;
+  command: MeshHandoffPrepare | TaskTransferContinue, publish: () => void,
+  prepare = prepareMeshHandoff): Promise<boolean> {
+  if (command.type === 'task.transfer.continue') return handleTransferContinuation(client, command, publish);
+  // Rejections are durable state too. Publish them even if the direct result
+  // could not cross the socket, so reconnecting controllers can explain them.
+  try { return await prepare(client, command); }
+  finally { publish(); }
 }

package/apps/mcp/src/desktop/delivery/task-handoff.ts

@@ -38,6 +38,7 @@ export async function desktopTaskHandoff(
     sessionId: row.session_id, projectId: row.project_id, taskId: row.task_id,
     targetProvider: row.target_provider, targetComputer: row.target_computer,
     targetModel: row.target_model, userComment: row.user_comment,
+    ...(row.source_binding_id === undefined ? {} : { sourceBindingId: row.source_binding_id }),
     checkpoint: row.checkpoint, push: row.push, createdAt: Date.now(),
     ...(row.cloud === true ? { cloud: {
       ...(row.cloud_environment === undefined ? {} : { environment: row.cloud_environment }),

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

@@ -21,6 +21,7 @@ export const DESKTOP_OPERATIONS = new Set([
   "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.project_knowledge",
   "desktop.task_send", "desktop.task_queue", "desktop.transfer_continue", "desktop.task_control", "desktop.task_preferences",
   "desktop.task_handoff",
   "desktop.project_transport",

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

@@ -20,6 +20,7 @@ import { desktopTaskHandoff } from "../delivery/task-handoff";
 import { desktopTaskCreate } from "../delivery/task-create";
 import { desktopMeshCreate } from "../delivery/mesh-create";
 import { desktopInvocationHistory } from "../invocation";
+import { desktopProjectKnowledge } from "../../../../bridge/src/mesh/knowledge/runtime-read";
 import { desktopUsage } from "../projection/usage";
 import { desktopInstalledSkills } from "../projection/installed-skills";
 import type { DesktopControllerEnrollment } from "../pairing";
@@ -74,6 +75,7 @@ export function desktopReadOperation(input: {
   if (operation === "desktop.invocation_history") {
     return desktopInvocationHistory(queryInput, engine, storePath);
   }
+  if (operation === "desktop.project_knowledge") return desktopProjectKnowledge(queryInput);
   if (operation === "desktop.project") {
     return Promise.resolve(desktopMeshProject(queryInput, storePath));
   }

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.89
+npm install -g granttap-mcp@0.8.91
 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.89\";\nconst dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === \"1\";\nconst platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM\n  ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;\nconst nodeRoot = dryRun && process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT\n  ? process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT : dirname(process.execPath);\nconst pathRoots = (process.env.PATH || \"\").split(delimiter).filter(Boolean);\nconst appData = process.env.APPDATA;\nconst roots = [nodeRoot, ...pathRoots, ...(appData ? [join(appData, \"npm\")] : [])];\nconst first = (paths) => paths.find((path) => existsSync(path));\n\nfunction launch() {\n  if (platform !== \"win32\") {\n    const installed = first(roots.map((root) => join(root, \"granttap-mcp\")));\n    if (installed) return { command: installed, args: [] };\n    const npx = first(roots.map((root) => join(root, \"npx\"))) || \"npx\";\n    return { command: npx, args: [\"-y\", PACKAGE] };\n  }\n  const installed = first(roots.map((root) =>\n    join(root, \"node_modules\", \"granttap-mcp\", \"bin\", \"granttap-mcp.mjs\")));\n  if (installed) return { command: process.execPath, args: [installed] };\n  const npx = first(roots.map((root) =>\n    join(root, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\")));\n  if (npx) return { command: process.execPath, args: [npx, \"-y\", PACKAGE] };\n  throw new Error(\"Node.js/npm 22.13.0+ is required on this Windows device. Install npm and retry GrantTap.\");\n}\n\nlet target;\ntry { target = launch(); }\ncatch (error) {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n}\n\nif (dryRun) {\n  process.stdout.write(JSON.stringify(target));\n  process.exit(0);\n}\n\nconst child = spawn(target.command, target.args, { stdio: \"inherit\", windowsHide: true });\nchild.on(\"error\", (error) => {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n  if (signal && platform !== \"win32\") {\n    try { process.kill(process.pid, signal); } catch { process.exit(code ?? 1); }\n    return;\n  }\n  process.exit(code ?? 1);\n});\n"
+        "\"use strict\";\n\n// Cursor may start this MCP from any cwd. Execute JavaScript entry points with\n// Node itself: Windows batch shims require shell quoting that differs by host.\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { delimiter, dirname, join } = require(\"node:path\");\n\nconst PACKAGE = \"granttap-mcp@0.8.91\";\nconst dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === \"1\";\nconst platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM\n  ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;\nconst nodeRoot = dryRun && process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT\n  ? process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT : dirname(process.execPath);\nconst pathRoots = (process.env.PATH || \"\").split(delimiter).filter(Boolean);\nconst appData = process.env.APPDATA;\nconst roots = [nodeRoot, ...pathRoots, ...(appData ? [join(appData, \"npm\")] : [])];\nconst first = (paths) => paths.find((path) => existsSync(path));\n\nfunction launch() {\n  if (platform !== \"win32\") {\n    const installed = first(roots.map((root) => join(root, \"granttap-mcp\")));\n    if (installed) return { command: installed, args: [] };\n    const npx = first(roots.map((root) => join(root, \"npx\"))) || \"npx\";\n    return { command: npx, args: [\"-y\", PACKAGE] };\n  }\n  const installed = first(roots.map((root) =>\n    join(root, \"node_modules\", \"granttap-mcp\", \"bin\", \"granttap-mcp.mjs\")));\n  if (installed) return { command: process.execPath, args: [installed] };\n  const npx = first(roots.map((root) =>\n    join(root, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\")));\n  if (npx) return { command: process.execPath, args: [npx, \"-y\", PACKAGE] };\n  throw new Error(\"Node.js/npm 22.13.0+ is required on this Windows device. Install npm and retry GrantTap.\");\n}\n\nlet target;\ntry { target = launch(); }\ncatch (error) {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n}\n\nif (dryRun) {\n  process.stdout.write(JSON.stringify(target));\n  process.exit(0);\n}\n\nconst child = spawn(target.command, target.args, { stdio: \"inherit\", windowsHide: true });\nchild.on(\"error\", (error) => {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n  if (signal && platform !== \"win32\") {\n    try { process.kill(process.pid, signal); } catch { process.exit(code ?? 1); }\n    return;\n  }\n  process.exit(code ?? 1);\n});\n"
       ]
     }
   }

package/cursor-plugin/stdio-bootstrap.cjs

@@ -7,7 +7,7 @@ const { spawn } = require("node:child_process");
 const { existsSync } = require("node:fs");
 const { delimiter, dirname, join } = require("node:path");
 
-const PACKAGE = "granttap-mcp@0.8.89";
+const PACKAGE = "granttap-mcp@0.8.91";
 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.89",
+  "version": "0.8.91",
   "description": "Commercial computer runtime connecting local coding agents to GrantTap on Mac, iPhone, iPad and Apple Watch.",
   "type": "module",
   "bin": {
@@ -42,7 +42,7 @@
     "tsx": "^4.23.4",
     "tweetnacl": "^1.0.3",
     "ws": "^8.18.0",
-    "zod": "^3.24.1"
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "@types/express": "^5.0.3",

package/packages/protocol/messages/approval-questions/index.ts

@@ -15,7 +15,7 @@ export function questionAnswers(questions: z.infer<typeof ApprovalQuestions> | u
   note: string | null | undefined): Record<string, string> | undefined {
   if (!questions || !note || note.length > 20_000) return undefined;
   try {
-    const answers = z.record(z.string().trim().min(1).max(4_000)).parse(JSON.parse(note));
+    const answers = z.record(z.string(), z.string().trim().min(1).max(4_000)).parse(JSON.parse(note));
     if (Object.keys(answers).length !== questions.length
       || questions.some(item => !Object.hasOwn(answers, item.question))) return undefined;
     return answers;

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

@@ -206,6 +206,7 @@ export const MeshClaimReleaseResult = z.object({
 export type MeshClaimReleaseResult = z.infer<typeof MeshClaimReleaseResult>;
 
 export const MeshHandoffPrepare = z.object({
+  sourceBindingId: Identifier.optional(),
   prepareOnly: z.boolean().optional(),
   type: z.literal("mesh.handoff.prepare"),
   sessionId: Identifier,

package/packages/protocol/messages/mesh/knowledge/refresh.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { Identifier } from "../endpoint";
+import { MeshInvocationEvent } from "../invocations";
+import { ProjectKnowledgeRecord } from "./index";
+
+const Sequence = z.number().int().nonnegative().safe();
+export const ProjectKnowledgeQuery = z.object({
+  type: z.literal("mesh.knowledge.query"),
+  sessionId: Identifier, projectId: Identifier, requestId: Identifier,
+}).strict().refine(value => value.sessionId === value.projectId, "Project scope mismatch");
+export type ProjectKnowledgeQuery = z.infer<typeof ProjectKnowledgeQuery>;
+
+/** One bounded Project read; no architecture rebuild or per-Task fan-out. */
+export const ProjectKnowledgePage = z.object({
+  type: z.literal("mesh.knowledge.page"),
+  sessionId: Identifier, projectId: Identifier, requestId: Identifier,
+  sourceEndpointId: Identifier,
+  memoryAvailability: z.enum(["ready", "unavailable"]),
+  invocationAvailability: z.enum(["ready", "unavailable"]),
+  knowledge: z.array(ProjectKnowledgeRecord).max(32),
+  supersededKnowledgeRecordIds: z.array(Identifier).max(128),
+  invocations: z.array(z.object({ sequence: Sequence, event: MeshInvocationEvent }).strict()).max(32),
+  incomplete: z.boolean(), generatedAt: Sequence,
+}).strict().superRefine((value, ctx) => {
+  let previous = 0;
+  const seenCalls = new Set<string>();
+  const orderedCalls = value.invocations.every(row => {
+    const valid = row.sequence > previous && !seenCalls.has(row.event.event_id);
+    previous = row.sequence;
+    seenCalls.add(row.event.event_id);
+    return valid;
+  });
+  if (!orderedCalls
+    || new Set(value.knowledge.map(row => row.recordId)).size !== value.knowledge.length
+    || new Set(value.supersededKnowledgeRecordIds).size !== value.supersededKnowledgeRecordIds.length
+    || value.sessionId !== value.projectId
+    || value.knowledge.some(record => record.projectId !== value.projectId || record.visibility !== "project")
+    || value.invocations.some(row => row.event.project_id !== value.projectId)
+    || value.memoryAvailability === "unavailable" && value.knowledge.length > 0
+    || value.invocationAvailability === "unavailable" && value.invocations.length > 0) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Knowledge source or Project scope mismatch" });
+  }
+});
+export type ProjectKnowledgePage = z.infer<typeof ProjectKnowledgePage>;

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

@@ -149,8 +149,8 @@ export const SessionsStatus = z.object({
   gatingEnabled: z.boolean().optional(),
   excludedSessions: z.array(z.string()).optional(),
   autoAcceptDefault: AutoAcceptLevel.optional(),
-  autoAcceptBySession: z.record(AutoAcceptLevel).optional(),
-  autoAcceptByProject: z.record(AutoAcceptLevel).optional(),
+  autoAcceptBySession: z.record(z.string(), AutoAcceptLevel).optional(),
+  autoAcceptByProject: z.record(z.string(), AutoAcceptLevel).optional(),
   autoAcceptPaused: z.boolean().optional(),
   providerSettings: ProviderRuntimeSettings.optional(),
   meshEnabled: z.boolean().optional(),

package/packages/protocol/schema.ts

@@ -45,6 +45,7 @@ import { PairingJoin } from "./messages/pairing-join";
 import { ControllerPairOffer, ControllerPairRequest } from "./messages/device/controller-pairing";
 import { AccountMachineLink } from "./messages/device/account-machine-link";
 import { KnowledgeWrite, KnowledgeWriteResult } from "./messages/mesh/knowledge/write";
+import { ProjectKnowledgeQuery, ProjectKnowledgePage } from "./messages/mesh/knowledge/refresh";
 import { MeshInvocationPage, MeshInvocationQuery } from "./messages/mesh/invocations";
 import {
   ProjectPolicyAck,
@@ -82,6 +83,7 @@ export * from "./messages/pairing-join";
 export * from "./messages/device/controller-pairing";
 export * from "./messages/device/account-machine-link";
 export * from "./messages/mesh/knowledge/write";
+export * from "./messages/mesh/knowledge/refresh";
 export * from "./messages/mesh";
 export * from "./messages/mesh/invocations";
 export * from "./messages/primitives";
@@ -165,6 +167,8 @@ export const Payload = z.union([
   ProjectCapabilityRequestSet,
   MeshInvocationQuery,
   MeshInvocationPage,
+  ProjectKnowledgeQuery,
+  ProjectKnowledgePage,
   MeshEndpointPolicy,
   ProjectPolicySet,
   ProjectPolicyStatus,