granttap-mcp 0.8.88 → 0.8.90

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

@@ -11,4 +11,10 @@ Catalog observations and Project requests do not install a skill or native MCP
 configuration on another host. Availability requires a separate native apply
 and independently observed initialization; that rollout is still unfinished.
 
+MCP descriptions come from `initialize.serverInfo.description`, trimmed and
+bounded to 4,000 characters. Descriptions, validated icons and website metadata
+travel with both session and Project catalogs; conflicting native implementations
+do not borrow an implementation's description or icon. These are display data,
+not instructions or evidence that a capability was used.
+
 License: this module is distributed under the GrantTap Commercial Source License in the repository-root `LICENSE` file.

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

@@ -117,9 +117,12 @@ function stringRecord(value: unknown): Record<string, string> {
 async function normalizeServerMetadata(info: Implementation | undefined, descriptor: McpDescriptor): Promise<ServerMetadata | undefined> {
   if (!info) return undefined;
   const title = typeof info.title === "string" && info.title.trim() ? info.title.trim().slice(0, 160) : undefined;
+  const description = typeof info.description === "string" && info.description.trim()
+    ? info.description.trim().slice(0, 4_000) : undefined;
   const website = typeof info.websiteUrl === "string" ? safeHttpsUrl(info.websiteUrl) : undefined;
   const version = typeof info.version === "string" && info.version.trim() ? info.version.trim().slice(0, 80) : undefined;
-  return { title, websiteUrl: website?.toString(), version, icons: await normalizedIcons(info, descriptor), metadataSource: "mcp" };
+  return { title, ...(description ? { description } : {}), websiteUrl: website?.toString(),
+    version, icons: await normalizedIcons(info, descriptor), metadataSource: "mcp" };
 }
 
 async function normalizedIcons(info: Implementation, descriptor: McpDescriptor): Promise<NonNullable<McpServerInfo["icons"]> | undefined> {

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

@@ -30,5 +30,5 @@ export type McpDescriptor = {
 
 export type ServerMetadata = Pick<
   McpServerInfo,
-  "title" | "websiteUrl" | "version" | "icons" | "metadataSource"
+  "title" | "description" | "websiteUrl" | "version" | "icons" | "metadataSource"
 >;

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/catalog/project/capabilities.ts

@@ -30,10 +30,16 @@ export function projectMcpServers(
         current.configuredEnabled &&= server.configuredEnabled;
         current.allowed &&= server.allowed;
         current.title ??= server.title;
+        if (server.description) current.description ??= server.description;
+        if (server.websiteUrl) current.websiteUrl ??= server.websiteUrl;
+        if (server.icons) current.icons ??= server.icons;
       } else {
         catalog.set(key, {
           name: server.name,
           title: server.title,
+          ...(server.description ? { description: server.description } : {}),
+          ...(server.websiteUrl ? { websiteUrl: server.websiteUrl } : {}),
+          ...(server.icons ? { icons: server.icons } : {}),
           provider,
           endpointId: session.computerId,
           configuredEnabled: server.configuredEnabled,

package/apps/bridge/src/mesh/catalog/project/configured-mcp.ts

@@ -16,6 +16,7 @@ export function configuredProjectMcpServers(
         const implementation = server.configDigest ?? "";
         const value: ProjectMcpServer = {
           name: server.name, title: server.title, provider, endpointId,
+          description: server.description, websiteUrl: server.websiteUrl, icons: server.icons,
           configuredEnabled: server.configuredEnabled, allowed: server.allowed,
           authStatus: server.authStatus, version: server.version,
           configDigest: server.configDigest,
@@ -29,6 +30,7 @@ export function configuredProjectMcpServers(
           // Two admitted workspaces disagree. Avoid claiming either version
           // as the Project's selected implementation.
           rows.set(key, { ...value, version: undefined, configDigest: undefined,
+            description: undefined, websiteUrl: undefined, icons: undefined,
             authStatus: "conflict" });
         } else if (!prior) rows.set(key, value);
         if (!prior) implementations.set(key, implementation);
@@ -63,6 +65,7 @@ export function mergeConfiguredMcpServers(
       || (configuredRow.configDigest != null || execution.configDigest != null)
       && configuredRow.configDigest !== execution.configDigest) {
       rows.set(key, { ...configuredRow, version: undefined, configDigest: undefined,
+        description: undefined, websiteUrl: undefined, icons: undefined,
         authStatus: "conflict",
         sessionIds: execution.sessionIds });
       continue;
@@ -70,6 +73,9 @@ export function mergeConfiguredMcpServers(
     rows.set(key, {
       ...configuredRow, ...execution,
       version: execution.version ?? configuredRow.version,
+      description: execution.description ?? configuredRow.description,
+      websiteUrl: execution.websiteUrl ?? configuredRow.websiteUrl,
+      icons: execution.icons ?? configuredRow.icons,
       configDigest: execution.configDigest ?? configuredRow.configDigest,
       authStatus: execution.authStatus ?? configuredRow.authStatus,
     });

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/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/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.88
+npm install -g granttap-mcp@0.8.90
 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.88\";\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.90\";\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.88";
+const PACKAGE = "granttap-mcp@0.8.90";
 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.88",
+  "version": "0.8.90",
   "description": "Commercial computer runtime connecting local coding agents to GrantTap on Mac, iPhone, iPad and Apple Watch.",
   "type": "module",
   "bin": {

package/packages/protocol/messages/capabilities.ts

@@ -183,6 +183,7 @@ export const McpServerInfo = z.object({
   allowed: z.boolean(),
   authStatus: z.string().optional(),
   title: z.string().max(160).optional(),
+  description: z.string().max(4_000).optional(),
   websiteUrl: z.string().url().optional(),
   version: z.string().max(80).optional(),
   configDigest: z.string().regex(/^[a-f0-9]{64}$/).optional(),

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/snapshot.ts

@@ -3,6 +3,7 @@ import { SharedSkill, EndpointModelCatalog } from "./catalog/provider";
 export * from "./catalog/provider";
 import { ProjectCodeMap } from "./graph/code-map";
 import { Identifier, Label, MeshProvider } from "./endpoint";
+import { McpIcon } from "../capabilities";
 import {
   ProjectEnvironment,
   ProjectExecutionPolicy,
@@ -44,6 +45,9 @@ export type IntegrationPeer = z.infer<typeof IntegrationPeer>;
 export const ProjectMcpServer = z.object({
   name: Label,
   title: Label.optional(),
+  description: z.string().max(4_000).optional(),
+  websiteUrl: z.string().url().optional(),
+  icons: z.array(McpIcon).max(2).optional(),
   provider: MeshProvider,
   endpointId: Identifier,
   configuredEnabled: z.boolean(),