granttap-mcp 0.8.66 → 0.8.68

package/apps/bridge/src/bin/cli/phone.ts

@@ -5,7 +5,8 @@ import { createOneTimePairing, DEFAULT_RELAY, PAIRING_CODE_TTL_MINUTES } from ".
 import { isMachineConfigured, readOnlyMachineConfigPath } from "../../../../mcp/src/status/pairing-status";
 import { installHttpMcpService } from "../../../../mcp/src/http-service";
 
-const mode = process.argv[2];
+// Direct invocation may retain the `phone` route; the published launcher strips it.
+const mode = process.argv[2] === "phone" ? process.argv[3] : process.argv[2];
 
 async function main(): Promise<void> {
   if (mode !== "add" && mode !== "reconnect") {

package/apps/bridge/src/bin/hooks/claude-prompt-hook.ts

@@ -5,11 +5,13 @@
  * Registered in ~/.claude/settings.json so that when a person submits a
  * prompt, this program adds what the chat could not know by itself: the
  * background runs that answered phone messages in it, and the Mesh brief for
- * its Task. It never blocks a prompt — anything wrong, and it adds nothing.
+ * its Task. Transferred chats require explicit continuation; ordinary prompts retain the existing context behavior.
  *
  *   Reads:  UserPromptSubmit JSON on stdin ({ session_id, prompt, cwd, ... })
  *   Writes: { hookSpecificOutput: { hookEventName, additionalContext } } on stdout
  */
+import { localTransferContinuations } from "../../task-transfer";
+import { localRoutingRequests } from '../../task-routing/requests';
 import { promptContext } from "../../mesh/context/prompt";
 
 async function readStdin(): Promise<string> {
@@ -30,6 +32,10 @@ async function main(): Promise<void> {
     return;
   }
   const sessionId = typeof input.session_id === "string" ? input.session_id.trim() : "";
+  const transferred = localTransferContinuations().blockReason(sessionId) ?? localRoutingRequests().blockReason(sessionId);
+  if (transferred) {
+    process.stdout.write(JSON.stringify({ decision: "block", reason: transferred })); return;
+  }
   const text = promptContext(sessionId);
   if (!text) return;
   process.stdout.write(JSON.stringify({

package/apps/bridge/src/bin/runtime/monitor.ts

@@ -12,11 +12,16 @@ import { applyNetworkRoute } from "../../device-network/settings";
 import { startEndpointPublisher } from "../../device-network/directory";
 import { managedAdmissionOptions } from "../../managed-admission";
 
+import { startTaskDispatchMonitor } from "../../task-dispatch/worker/monitor";
+import { startTaskNetworkMonitor } from '../../task-network/runtime';
+
 let client: RelayClient;
 let monitor: ReturnType<typeof startSessionMonitor>;
 const engine = new EngineSupervisor();
 let stopping = false;
 let stopEndpointPublisher = () => {};
+let stopTaskDispatch = () => {};
+let stopTaskNetwork = () => {};
 
 try {
   const cfg = applyNetworkRoute(loadConfig(machineConfigPath()));
@@ -27,6 +32,10 @@ try {
     peerAllowed: controllerPeerGate(cfg),
   });
   monitor = startSessionMonitor(client);
+  stopTaskDispatch = startTaskDispatchMonitor({ config: cfg, client,
+    isLeader: monitor.isLeader, peerAllowed: controllerPeerGate(cfg), publish: monitor.publish });
+  stopTaskNetwork = startTaskNetworkMonitor({ config: cfg, client,
+    isLeader: monitor.isLeader, peerAllowed: controllerPeerGate(cfg), publish: monitor.publish });
   stopEndpointPublisher = startEndpointPublisher(cfg);
 } catch (error) {
   process.stderr.write(
@@ -38,6 +47,8 @@ try {
 const stop = (): void => {
   if (stopping) return;
   stopping = true;
+  stopTaskDispatch();
+  stopTaskNetwork();
   monitor.close();
   stopEndpointPublisher();
   client.close();

package/apps/bridge/src/capabilities/index.ts

@@ -3,6 +3,7 @@ import { descriptorsForProvider, descriptorsForSession, mcpConfigDigest } from "
 import { cachedMetadata, refreshDescriptorMetadata } from "./metadata";
 
 export { projectSharedSkills, workspaceSkills } from "./skills";
+export { deliveryRoutingError } from "./routing";
 export { mcpConfigDigest } from "./descriptors";
 
 /** Resolve real MCP initialization metadata and cache it for a session. */

package/apps/bridge/src/capabilities/routing/index.ts

@@ -0,0 +1,28 @@
+import type { SessionInfo } from "../../../../../packages/protocol/schema";
+import { loadRuntimeConfig } from "../../config";
+import type { DeliveryOptions } from "../../reply/payload/types";
+import { mcpServersForSession, workspaceSkills } from "..";
+
+/** Validate explicit routing against current machine and Task capability rules. */
+export function deliveryRoutingError(target: SessionInfo, options: DeliveryOptions): string | undefined {
+  const runtime = loadRuntimeConfig();
+  const settings = runtime.providerSettings;
+  if (target.agent in settings && settings[target.agent as keyof typeof settings] === false) {
+    return "This agent is disabled in GrantTap Settings.";
+  }
+  if (options.preferredMcp) {
+    const disabled = runtime.sessionMcpDisabled[target.sessionId] ?? [];
+    if (!mcpServersForSession(target, disabled).some(server => server.name === options.preferredMcp && server.allowed)) {
+      return "The selected MCP server is not allowed for this task.";
+    }
+  }
+  if (options.skill) {
+    if (!workspaceSkills(target.cwd).some(skill => skill.name === options.skill)) {
+      return "The selected project skill is no longer available in this task's folder.";
+    }
+    if ((runtime.sessionSkillsDisabled[target.sessionId] ?? []).includes(options.skill)) {
+      return "The selected project skill is disabled for this task.";
+    }
+  }
+  return undefined;
+}

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

@@ -54,6 +54,7 @@ export function preferExecution(
   if ((current.endedAt != null) !== (incoming.endedAt != null)) {
     const ended = current.endedAt != null ? current : incoming;
     const live = current.endedAt != null ? incoming : current;
+    if (live.continuedAt != null && live.continuedAt > ended.endedAt!) return live;
     return { ...live, endedAt: ended.endedAt };
   }
   const currentAt = current.updatedAt ?? current.startedAt;

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

@@ -81,7 +81,9 @@ export function workspaceForRepository(
     .filter((task) => projectIds.has(task.projectId)).map((task) => task.taskId));
   const local = state.executions.find((item) =>
     taskIds.has(item.taskId) && (computerId == null || item.computerId === computerId));
-  if (computerId != null) return local?.worktree ?? local?.workspace;
+  if (computerId != null) return local?.worktree ?? local?.workspace
+    ?? state.bindings.find(binding => binding.endpointId === computerId
+      && binding.repositoryId === canonicalRepositoryId && binding.available)?.localPathHint;
   return local?.worktree ?? local?.workspace
     ?? state.projects.find((item) => projectIds.has(item.projectId))?.repositoryRoot;
 }

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

@@ -224,6 +224,7 @@ function linkSession(input: {
     workspace: cwd,
     repositoryId: repository.canonicalRepositoryId,
     activeAt: session.lastActivityAt,
+    state: session.state, continuedAt: session.transfer?.continuedAt,
     branch: repository.branch ?? session.branch,
     worktree: repository.worktree,
     uncommitted: hasUncommittedWork(repository.worktree ?? cwd),

package/apps/bridge/src/mesh/identity/call-scope.ts

@@ -49,7 +49,7 @@ function canonical(value: unknown): unknown {
 export function grantTapToolName(rawToolName: unknown): string | undefined {
   const raw = String(rawToolName ?? "").trim();
   const tool = raw.includes("__") ? raw.split("__").at(-1)! : raw;
-  return ["notify", "connect", "ask", "ask_yes_no"].includes(tool) ? tool : undefined;
+  return ["notify", "connect", "ask", "ask_yes_no", "offload_task"].includes(tool) ? tool : undefined;
 }
 
 export function meshCallKey(tool: string, args: unknown): string {

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

@@ -5,6 +5,7 @@ import type {
   MeshProvider,
   MeshSnapshot,
   SessionInfo,
+  TaskCapsule,
 } from "../../../../../packages/protocol/schema";
 import type { createCodexSession, deliverToSession } from "../../reply";
 import type { MeshStore } from "../store";
@@ -15,6 +16,12 @@ type WorktreeResult = NonNullable<ReturnType<typeof createHandoffWorktree>>;
 
 export type MeshRuntimeDependencies = {
   store: () => MeshStore;
+  continuations?: () => import("../../task-transfer").TransferContinuations;
+  transfers?: () => import('../../task-transfer').PreparedTaskTransfers;
+  captureTransferContext?: typeof import('../../task-transfer').captureTransferContext;
+  sourceCaptureCurrent?: (session: SessionInfo, capsule: TaskCapsule) => boolean;
+  dispatchPreparedTransfer?: (event: MeshEvent, session: SessionInfo,
+    confirmContext: () => Promise<boolean>) => Promise<boolean>;
   sessions: () => SessionInfo[];
   /** Observed native configuration for a session on this endpoint. */
   capabilityInventory?: (session: SessionInfo) => SessionInfo;
@@ -34,6 +41,7 @@ export type MeshRuntimeDependencies = {
     taskId: string,
     provider: MeshProvider,
     revision: string,
+    operationId?: string,
   ) => WorktreeResult | undefined | null;
   hasCommit: (repository: string, revision: string) => boolean;
   /** Publish the branch a capsule names, when the person asked for it. */

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

@@ -0,0 +1,26 @@
+# Repository graph refresh
+
+Public entry point: `analysis.ts` for explicit builds; `binding-sync.ts` for
+verified local admission and recovery; `checkout-identity.ts` for checkout scope.
+
+A remote identity must match the checkout's observed Git origin. A `local:`
+identity must resolve to the exact Git root it names. Gaining an origin does not
+invalidate an existing local-directory binding or move it to another Project.
+Local bindings are admitted to Engine as path identities without a canonical
+remote claim. Changed remote identities and local paths to different checkouts
+remain rejected. Neither Task identity nor Project membership is rewritten.
+
+After admission, `graphAnalysisBindings` selects one graph per endpoint and real
+checkout path, preferring an admitted canonical binding over a duplicate local
+alias. Failed bindings remain visible with their original error. Both the Mac
+projection and phone refresh use this rule. The graph contains actual Engine
+analysis; unavailable analysis is never synthesized as a successful graph.
+
+Behavior tests: `tests/`, root `tests/graph/graph-binding-sync.test.ts`, and
+`apps/mcp/src/desktop/projection/tests/graph-refresh.test.ts`. The optional
+`engine-selection-live.test.ts` uses `GRANTTAP_ENGINE_TEST_BINARY` to verify the
+actual native scanner respects `.git/info/exclude` and retains untracked source.
+
+## License
+
+Apache License 2.0. See [LICENSE](../../../../../../LICENSE).

package/apps/bridge/src/mesh/runtime/graph/analysis.ts

@@ -5,6 +5,7 @@ import { sendMeshPayload } from "../../../host/session-keys";
 import { publishedCatalog } from "../../../session-catalog";
 import { meshSnapshot, meshSnapshots } from "..";
 import { refreshLocalGraphBindings } from "./binding-sync";
+import { graphAnalysisBindings } from "./checkout-identity";
 
 /** A person's explicit Graph refresh bypasses background job backoff. */
 type GraphAnalysisDependencies = {
@@ -48,7 +49,8 @@ export async function analyzeProjectGraphNow(
   const rejected = new Set(failures.map(report => report.repositoryId));
   const [backbone, repositoryGraphs] = await Promise.all([
     dependencies.backbone(projectId),
-    dependencies.graphs(projectId, (current.bindings ?? []).filter(binding => !rejected.has(binding.repositoryId)), { background: false }),
+    dependencies.graphs(projectId, graphAnalysisBindings((current.bindings ?? [])
+      .filter(binding => !rejected.has(binding.repositoryId))), { background: false }),
   ]);
   const observed = [...repositoryGraphs, ...failures];
   const reports = observed.length > 0 ? observed : [{

package/apps/bridge/src/mesh/runtime/graph/binding-sync.ts

@@ -3,6 +3,7 @@ import type { MeshSnapshot, ProjectRepositoryGraph } from "../../../../../../pac
 import { queueProjectBindingSync } from "../../../engine/runtime/engine-projects";
 import { inspectRepository } from "../../catalog";
 import { computerId } from "../../identity/computer";
+import { matchesLocalCheckout } from "./checkout-identity";
 
 /** Re-admit this computer's verified checkouts before an explicit Graph build. */
 export async function refreshLocalGraphBindings(
@@ -21,8 +22,9 @@ export async function refreshLocalGraphBindings(
     try {
       const path = binding.localPathHint!;
       const facts = dependencies.inspect(path);
+      const pathIdentity = matchesLocalCheckout(binding.repositoryId, facts.root);
       if (!facts.worktree || realpathSync(facts.root) !== realpathSync(path)
-        || facts.canonicalRepositoryId !== binding.repositoryId) {
+        || (facts.canonicalRepositoryId !== binding.repositoryId && !pathIdentity)) {
         failures.push({ projectId: snapshot.projectId, repositoryId: binding.repositoryId,
           revision: "unverified", weavatrixVersion: "unknown", analysisStatus: "UNAVAILABLE",
           analysisErrorCode: facts.worktree ? "REPOSITORY_IDENTITY_MISMATCH" : "REPOSITORY_IDENTITY_UNVERIFIED",
@@ -32,7 +34,9 @@ export async function refreshLocalGraphBindings(
       const admitted = await dependencies.sync(snapshot.project, {
         summary: binding,
         localRoot: facts.root,
-        canonicalRemote: facts.baseRemote,
+        // A local binding is scoped by its verified path. Do not relabel it as
+        // a remote repository or move it into that repository's Project scope.
+        canonicalRemote: pathIdentity ? undefined : facts.baseRemote,
         lastSeenAt: Date.now(),
       });
       if (!admitted) failures.push(admissionFailure(snapshot, binding));

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

@@ -0,0 +1,29 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import type { ProjectBindingSummary } from "../../../../../../packages/protocol/schema";
+
+/** Local identities name an exact directory, even after that directory gains an origin. */
+export function matchesLocalCheckout(repositoryId: string, root: string): boolean {
+  if (!repositoryId.startsWith("local:")) return false;
+  const path = repositoryId.slice("local:".length);
+  if (!isAbsolute(path)) return false;
+  try { return realpathSync(path) === realpathSync(root); }
+  catch { return false; }
+}
+
+/** Once admitted, one checkout contributes one graph to this Mesh. */
+export function graphAnalysisBindings(bindings: ProjectBindingSummary[]): ProjectBindingSummary[] {
+  const selected = new Map<string, ProjectBindingSummary>();
+  for (const binding of bindings) {
+    let path: string | undefined;
+    if (binding.available && binding.localPathHint) {
+      try { path = realpathSync(binding.localPathHint); } catch { /* Keep an unavailable checkout distinct. */ }
+    }
+    const key = JSON.stringify([binding.endpointId, path ?? binding.repositoryId]);
+    const previous = selected.get(key);
+    if (!previous || (previous.repositoryId.startsWith("local:") && !binding.repositoryId.startsWith("local:"))) {
+      selected.set(key, binding);
+    }
+  }
+  return [...selected.values()];
+}

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

@@ -6,8 +6,9 @@
  * catalog, snapshots, and inbound routing.
  */
 import type { RelayClient } from "../../../../../packages/core/relay-client";
-import type { MeshEvent, MeshHandoffPrepare, TaskCapsule } from "../../../../../packages/protocol/schema";
-import { handoffReceipt } from "../handoff";
+import type { MeshEvent, MeshHandoffPrepare, TaskCapsule, SessionInfo } from "../../../../../packages/protocol/schema";
+import { handoffReceipt, capsuleHash } from "../handoff";
+import { localTaskTransfers, localTransferContinuations, transferDigest } from "../../task-transfer";
 import type { MeshRuntimeDependencies } from "./dependencies";
 
 function capsulePrompt(capsule: TaskCapsule): string {
@@ -132,23 +133,42 @@ async function acceptHandoff(
       + "or hand off from a commit this computer already has.",
     );
   }
-  const worktree = deps.worktree(
-    repository,
-    event.taskId,
-    capsule.targetProvider,
-    revision,
-  );
+  const transfers = capsule.launch === "on_message" ? (deps.transfers ?? localTaskTransfers)() : undefined;
+  const previous = transfers?.forEvent(event.eventId);
+  if (previous && (previous.projectId !== event.projectId
+    || previous.sourceSessionId !== event.sourceSessionId
+    || capsuleHash(previous.capsule) !== capsuleHash(capsule))) {
+    return rejectHandoff(deps, client, event, "This transfer id already names different work.");
+  }
+  if (transfers && !previous && (!event.payload.transferContext || !capsule.title
+    || transferDigest(event.payload.transferContext) !== capsule.contextHash)) {
+    return rejectHandoff(deps, client, event, "The complete transfer context could not be confirmed.");
+  }
+  const worktree = previous ? { path: previous.workspace, branch: previous.branch }
+    : transfers ? deps.worktree(repository, event.taskId, capsule.targetProvider, revision, event.eventId)
+      : deps.worktree(repository, event.taskId, capsule.targetProvider, revision);
   if (!worktree) return rejectHandoff(deps, client, event, "A separate handoff worktree could not be created.");
-  const result = await deps.start(
-    capsule.targetProvider, capsulePrompt(capsule), worktree.path, capsule.targetModel,
-  );
-  if (!result.ok || !result.sessionId) {
-    const reason = result.ok ? "The target agent did not create a session." : result.error;
-    return rejectHandoff(deps, client, event, reason);
+  let targetSessionId: string;
+  if (transfers) {
+    try {
+      targetSessionId = previous?.sessionId ?? transfers.prepare({ eventId: event.eventId,
+        projectId: event.projectId, sourceSessionId: event.sourceSessionId,
+        title: capsule.title!, capsule, workspace: worktree.path, branch: worktree.branch,
+        context: event.payload.transferContext!, acceptedAt: deps.now() }).sessionId;
+    } catch {
+      return rejectHandoff(deps, client, event, "The complete transfer could not be saved on this computer.");
+    }
+  } else {
+    const result = await deps.start(capsule.targetProvider, capsulePrompt(capsule), worktree.path, capsule.targetModel);
+    if (!result.ok || !result.sessionId) {
+      const reason = result.ok ? "The target agent did not create a session." : result.error;
+      return rejectHandoff(deps, client, event, reason);
+    }
+    targetSessionId = result.sessionId;
   }
   store.linkExecution({
     taskId: event.taskId,
-    sessionId: result.sessionId,
+    sessionId: targetSessionId,
     provider: capsule.targetProvider,
     computerId: deps.computer(),
     workspace: worktree.path,
@@ -156,10 +176,18 @@ async function acceptHandoff(
     worktree: worktree.path,
     startedAt: deps.now(),
   });
-  const receipt = handoffReceipt(capsule, event.sourceSessionId, result.sessionId, deps.now());
+  const receipt = handoffReceipt(capsule, event.sourceSessionId, targetSessionId, previous?.acceptedAt ?? deps.now());
+  if (transfers) {
+    receipt.prepared = true;
+    if (capsule.sourceComputer === deps.computer()) (deps.continuations ?? localTransferContinuations)().record({
+      sourceSessionId: receipt.sourceSessionId, targetSessionId: receipt.targetSessionId,
+      taskId: receipt.taskId, projectId: event.projectId, capsuleHash: receipt.capsuleHash,
+      acceptedAt: receipt.acceptedAt, queuedAt: event.createdAt,
+    }, (deps.transfers ?? localTaskTransfers)().nativeSession({ sessionId: receipt.sourceSessionId } as SessionInfo).sessionId);
+  }
   store.recordReceipt(receipt);
   const accepted = responseEvent({
-    deps, source: event, sourceSessionId: result.sessionId, eventType: "HANDOFF_ACCEPTED",
+    deps, source: event, sourceSessionId: targetSessionId, eventType: "HANDOFF_ACCEPTED",
     payload: { receipt },
   });
   store.acceptEvent(accepted);

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

@@ -10,6 +10,7 @@ import type {
   SessionInfo,
   TaskCapsule,
 } from "../../../../../packages/protocol/schema";
+import { captureTransferContext, localTransferContinuations, localTaskTransfers } from "../../task-transfer";
 import { configDir } from "../../config";
 import {
   createClaudeSession,
@@ -20,7 +21,7 @@ import {
 } from "../../reply";
 import { isProviderEnabled } from "../../config/runtime";
 import { sendMeshPayload } from "../../host/session-keys";
-import { linkSessionsToProjects, workingTreeState } from "../catalog";
+import { inspectRepository, linkSessionsToProjects, workingTreeState } from "../catalog";
 import { catalogFromEndpoint } from "../catalog/models";
 import { saveProjectCapabilityRequest } from "../catalog/project/requests";
 import { computerId } from "../identity/computer";
@@ -36,6 +37,7 @@ 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';
 
 export type { MeshRuntimeDependencies };
 
@@ -56,6 +58,14 @@ const defaultDependencies: MeshRuntimeDependencies = {
   now: Date.now,
   eventId: randomUUID,
   providerEnabled: isProviderEnabled,
+  sourceCaptureCurrent: (session, capsule) => {
+    const cwd = session.worktree ?? session.cwd;
+    try { return Boolean(cwd && workingTreeState(cwd) === 'clean'
+      && inspectRepository(cwd).revision === (capsule.latestCommit ?? capsule.baseSha)); }
+    catch { return false; }
+  },
+  dispatchPreparedTransfer: async (event, session, confirm) =>
+    (await import('../../task-network/runtime')).submitNetworkTransfer(event, session, confirm),
   start: async (provider, prompt, cwd, model) => {
     if (provider === "claude") return createClaudeSession(prompt, cwd, 240_000, [], model);
     if (provider === "codex") return createCodexSession(prompt, cwd, 240_000, [], model);
@@ -67,12 +77,13 @@ const defaultDependencies: MeshRuntimeDependencies = {
   push: pushBranch,
   fetch: fetchRevision,
   send: (client, payload, options) => sendMeshPayload(client, payload, "phone", options),
-  worktree: (repository, taskId, provider, revision) => createHandoffWorktree({
+  worktree: (repository, taskId, provider, revision, operationId) => createHandoffWorktree({
     repository,
     worktreeRoot: join(configDir(), "worktrees"),
     taskId,
     provider,
     baseSha: revision,
+    operationId,
   }),
 };
 
@@ -89,6 +100,10 @@ async function prepareHandoff(
   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)
@@ -100,7 +115,7 @@ async function prepareHandoff(
       && (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);
+  let capsule = buildTaskCapsule(deps.store(), session, request, deps.computer(), checkpoint);
   const readiness = handoffReadiness({
     capsule,
     targetProviderEnabled: request.targetProvider === "grok_bot"
@@ -119,6 +134,19 @@ async function prepareHandoff(
     return false;
   }
   if (!capsule) return false;
+  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);
@@ -138,10 +166,22 @@ async function prepareHandoff(
     eventType: "HANDOFF_REQUEST",
     createdAt,
     expiresAt: createdAt + 60 * 60_000,
-    payload: { capsule },
+    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, event, { ttlMs: 60 * 60_000, wake: true });
+  await deps.send(client, request.prepareOnly ? preparedHandoffMetadata(event) : event, { ttlMs: 60 * 60_000, wake: true });
   if (local) await acceptHandoff(client, event);
   return true;
 }
@@ -199,8 +239,20 @@ export function createMeshRuntime(deps: MeshRuntimeDependencies) {
         return true;
       }
       const fresh = store.acceptEvent(payload);
+      if (payload.eventType === "HANDOFF_REQUEST" && origin === "relay"
+        && (fresh || payload.payload.capsule?.launch === "on_message")) await acceptHandoff(client, payload);
       if (!fresh) return true;
-      if (payload.eventType === "HANDOFF_REQUEST" && origin === "relay") await acceptHandoff(client, payload);
+      if (payload.eventType === "HANDOFF_ACCEPTED" && payload.payload.receipt?.prepared) {
+        const receipt = payload.payload.receipt;
+        const request = store.eventsForProject(payload.projectId).find(event =>
+          event.eventType === "HANDOFF_REQUEST" && event.sourceSessionId === receipt.sourceSessionId
+          && event.payload.capsule?.sourceComputer === deps.computer());
+        if (request) (deps.continuations ?? localTransferContinuations)().record({
+          sourceSessionId: receipt.sourceSessionId, targetSessionId: receipt.targetSessionId,
+          projectId: payload.projectId, taskId: receipt.taskId, capsuleHash: receipt.capsuleHash,
+          acceptedAt: receipt.acceptedAt, queuedAt: request.createdAt,
+        }, (deps.transfers ?? localTaskTransfers)().nativeSession({ sessionId: receipt.sourceSessionId } as SessionInfo).sessionId);
+      }
       if (payload.eventType === "AGENT_QUESTION") await answerAgentQuestion(client, payload);
       return true;
     },
@@ -211,7 +263,12 @@ export function createMeshRuntime(deps: MeshRuntimeDependencies) {
   };
 }
 
-const defaultRuntime = createMeshRuntime(defaultDependencies);
+/** Local adapters may replace a scoped transport without rebuilding runtime dependencies. */
+export function createLocalMeshRuntime(overrides: Partial<MeshRuntimeDependencies> = {}) {
+  return createMeshRuntime({ ...defaultDependencies, ...overrides });
+}
+
+const defaultRuntime = createLocalMeshRuntime();
 
 export function meshCatalog(sessions: SessionInfo[]): SessionInfo[] {
   return defaultRuntime.catalog(sessions);

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

@@ -0,0 +1,27 @@
+import type { MeshEvent, SessionInfo, TaskCapsule } from '../../../../../../packages/protocol/schema';
+import type { MeshRuntimeDependencies } from '../dependencies';
+import { captureTransferContext } from '../../../task-transfer';
+
+/** The private computer transport owns context; phone notifications are observations only. */
+export function preparedHandoffMetadata(event: MeshEvent): MeshEvent {
+  const { transferContext: _context, ...payload } = event.payload;
+  return { ...event, payload };
+}
+
+/** Retains the original archive facts so reconfirmation hashes the same conversation. */
+export async function capturePreparedHandoff(deps: MeshRuntimeDependencies, session: SessionInfo, facts: TaskCapsule) {
+  const capture = deps.captureTransferContext ?? captureTransferContext;
+  const captured = await capture(session, facts);
+  const task = deps.store().task(facts.taskId);
+  return { transferContext: captured.context,
+    capsule: { ...facts, title: task?.title ?? session.title ?? facts.goal.slice(0, 160),
+      launch: 'on_message' as const, contextHash: captured.hash },
+    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; }
+      catch { return false; }
+    } };
+}

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

@@ -1,4 +1,5 @@
 import { refreshLocalGraphBindings } from "../graph/binding-sync";
+import { graphAnalysisBindings } from "../graph/checkout-identity";
 import type { MeshSnapshot } from "../../../../../../packages/protocol/schema";
 import {
   projectBackbone, projectRepositoryGraphs, waitForProjectBindingSync,
@@ -16,7 +17,8 @@ export async function enrichMeshSnapshot(
 ): Promise<MeshSnapshot> {
   const identityFailures = await refreshLocalGraphBindings(snapshot);
   const excludedRepositories = new Set(identityFailures.map((report) => report.repositoryId));
-  const bindings = (snapshot.bindings ?? []).filter((binding) => !excludedRepositories.has(binding.repositoryId));
+  const bindings = graphAnalysisBindings((snapshot.bindings ?? [])
+    .filter((binding) => !excludedRepositories.has(binding.repositoryId)));
   await waitForProjectBindingSync(snapshot.projectId);
   queueProjectKnowledgeSync({
     projectId: snapshot.projectId,

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

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, lstatSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
 
 export type HandoffWorktree = { path: string; branch: string };
 
@@ -28,15 +29,19 @@ export function createHandoffWorktree(input: {
   provider: string;
   baseSha: string;
   now?: number;
+  operationId?: string;
 }): HandoffWorktree | undefined {
   const { repository, worktreeRoot, taskId, provider, baseSha, now = Date.now() } = input;
   if (!/^[0-9a-f]{7,64}$/i.test(baseSha)) return undefined;
+  if (input.operationId !== undefined && (!input.operationId || input.operationId.length > 128)) return undefined;
   const task = safeSegment(taskId) || "task";
   const agent = safeSegment(provider) || "agent";
-  const suffix = Math.trunc(now).toString(36);
+  const suffix = input.operationId ? createHash('sha256').update(input.operationId).digest('hex').slice(0, 24)
+    : Math.trunc(now).toString(36);
   const branch = `granttap/${agent}/${task}-${suffix}`;
   const path = join(worktreeRoot, `${task}-${agent}-${suffix}`);
-  if (existsSync(path)) return undefined;
+  if (existsSync(path)) return input.operationId && reusableWorktree(path, repository, baseSha, branch)
+    ? { path, branch } : undefined;
   mkdirSync(worktreeRoot, { recursive: true, mode: 0o700 });
   try {
     execFileSync("git", ["-C", repository, "cat-file", "-e", `${baseSha}^{commit}`], {
@@ -50,3 +55,19 @@ export function createHandoffWorktree(input: {
     return undefined;
   }
 }
+
+function reusableWorktree(path: string, repository: string, revision: string, branch: string): boolean {
+  const git = (cwd: string, args: string[]) => execFileSync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3_000, maxBuffer: 512 * 1_024,
+  }).trim();
+  try {
+    if (lstatSync(path).isSymbolicLink() || !lstatSync(path).isDirectory()) return false;
+    const root = realpathSync(path);
+    return realpathSync(git(path, ['rev-parse', '--show-toplevel'])) === root
+      && realpathSync(resolve(path, git(path, ['rev-parse', '--git-common-dir'])))
+        === realpathSync(resolve(repository, git(repository, ['rev-parse', '--git-common-dir'])))
+      && git(path, ['rev-parse', 'HEAD']) === git(repository, ['rev-parse', `${revision}^{commit}`])
+      && git(path, ['branch', '--show-current']) === branch
+      && git(path, ['status', '--porcelain=v1', '--untracked-files=all']) === '';
+  } catch { return false; }
+}