granttap-mcp 0.8.69 → 0.8.70

package/README.md

@@ -207,10 +207,10 @@ offered for it. Unsupported remote-start paths fail closed instead of claiming
 parity.
 
 A capsule carries facts, not files. A handoff from a checkout with uncommitted
-changes is refused — "This task has uncommitted changes. Commit or checkpoint
-them before moving the task." — instead of silently continuing the Task from
-committed state and leaving that work behind. Asked to checkpoint from the
-phone, the source computer commits everything to `granttap/checkpoint/<task>`
+changes goes ahead with a warning — "This task has uncommitted changes. They stay
+on this computer; the next agent starts from the last commit." — and the capsule
+names the changes that stayed behind, so nothing is narrowed silently. Asked to
+checkpoint from the phone, the source computer commits everything to `granttap/checkpoint/<task>`
 from a temporary index, so HEAD, the current branch, and the working tree stay
 exactly as the agent left them, and the capsule carries that commit. Nothing is
 pushed unless the phone asks for it per handoff: then the source publishes the

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

@@ -26,12 +26,16 @@ tool so the public MCP tool allowlist remains exactly `connect`, `notify`,
 CLI-only.
 
 `readiness.ts` decides whether a handoff may leave at all. A capsule transfers
-committed facts, so uncommitted work blocks the handoff instead of silently
-staying behind, and the destination refuses just as explicitly when it lacks the
-named commit or when the capsule's resource claims overlap another execution.
-"Uncommitted" is read from `git status` including untracked files, because an
-untracked file is work no commit would carry. A probe that cannot answer
-publishes `unknown`, and only an explicit `clean` releases the handoff.
+committed facts, so uncommitted work stays on the source computer: that is the
+person's call, made with a warning rather than refused, and the capsule tells
+the next agent which changes stayed where. The destination refuses explicitly
+when it lacks the named commit or when the capsule's resource claims overlap
+another execution. "Uncommitted" is read from `git status` including untracked
+files, because an untracked file is work no commit would carry. A probe that
+cannot answer publishes `unknown`, which is warned about the same way, never
+taken for `clean`. A prepared transfer to another computer is confirmed only
+while the source checkout is still on the same commit with the same uncommitted
+changes it had when the person agreed to the move.
 `remote.ts` is the one place a remote is touched: a push of the branch the
 capsule names when the phone asked for it, never forced, and a fetch of that
 branch on a destination that lacks the commit. A handoff whose target is this

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

@@ -42,11 +42,22 @@ function changedFiles(cwd: string): string[] {
   return [...new Set(files)].slice(0, 64);
 }
 
-function dirtyDiffHash(cwd: string): string | undefined {
+/** 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"]);
   return diff ? createHash("sha256").update(diff).digest("hex") : undefined;
 }
 
+/**
+ * Uncommitted work that does not travel with the capsule. The move is allowed;
+ * the next agent is told what it does not have and where it stayed.
+ */
+function leftBehindWork(files: string[], computerId: string): string {
+  const named = files.slice(0, 8).join(", ") + (files.length > 8 ? ` and ${files.length - 8} more` : "");
+  return `Uncommitted changes to ${named || "this checkout"} stayed on ${computerId}; they are not in this commit.`
+    .slice(0, 1_000);
+}
+
 export function buildTaskCapsule(
   store: MeshStore,
   session: SessionInfo,
@@ -61,6 +72,8 @@ export function buildTaskCapsule(
   if (!cwd || !task || !project || session.taskId !== request.taskId) return undefined;
   const head = git(cwd, ["rev-parse", "HEAD"]);
   if (!head) return undefined;
+  const tree = workingTreeState(cwd);
+  const files = changedFiles(cwd);
   const capsule = {
     taskId: request.taskId,
     goal: task.goal,
@@ -77,13 +90,16 @@ export function buildTaskCapsule(
     branch: session.branch ?? git(cwd, ["branch", "--show-current"]),
     latestCommit: head,
     dirtyDiffHash: dirtyDiffHash(cwd),
-    workingTree: workingTreeState(cwd),
-    filesChanged: changedFiles(cwd),
+    workingTree: tree,
+    filesChanged: files,
     dependencies: snapshot.dependencies
       .filter((item) => item.taskId === request.taskId).map((item) => item.dependsOnTaskId).slice(0, 32),
     resourceClaims: snapshot.claims
       .filter((item) => item.taskId === request.taskId).map((item) => item.resource).slice(0, 64),
-    remainingWork: ["Continue the task from the current committed state."],
+    remainingWork: [
+      "Continue the task from the current committed state.",
+      ...(tree === "dirty" ? [leftBehindWork(files, computerId)] : []),
+    ],
     importantDecisions: [],
     createdAt: Date.now(),
   };

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

@@ -21,7 +21,7 @@ import {
 } from "../../reply";
 import { isProviderEnabled } from "../../config/runtime";
 import { sendMeshPayload } from "../../host/session-keys";
-import { inspectRepository, linkSessionsToProjects, workingTreeState } from "../catalog";
+import { linkSessionsToProjects, workingTreeState } from "../catalog";
 import { catalogFromEndpoint } from "../catalog/models";
 import { saveProjectCapabilityRequest } from "../catalog/project/requests";
 import { computerId } from "../identity/computer";
@@ -38,6 +38,7 @@ import { fetchRevision, pushBranch } from "../local-remote/remote";
 import { projectSessionCapabilityInventory } from "./capabilities";
 import { createMeshSessionCatalog } from "./catalog/session-catalog";
 import { capturePreparedHandoff, preparedHandoffMetadata } from './prepared-transfer';
+import { sourceCheckoutUnchanged } from './prepared-transfer/source-checkout';
 
 export type { MeshRuntimeDependencies };
 
@@ -58,12 +59,7 @@ 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; }
-  },
+  sourceCaptureCurrent: (session, capsule) => sourceCheckoutUnchanged(session.worktree ?? session.cwd, capsule),
   dispatchPreparedTransfer: async (event, session, confirm) =>
     (await import('../../task-network/runtime')).submitNetworkTransfer(event, session, confirm),
   start: async (provider, prompt, cwd, model) => {

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

@@ -0,0 +1,24 @@
+import type { TaskCapsule } from '../../../../../../packages/protocol/schema';
+import { dirtyDiffHash } from '../../admin/capsule';
+import { inspectRepository, workingTreeState } from '../../catalog';
+
+/**
+ * Whether the source checkout is still what its capsule described.
+ *
+ * A prepared transfer to another computer is confirmed later. Uncommitted work
+ * may be left behind — the person was warned — but it has to be the same work
+ * they agreed to leave, on the same commit. A checkpoint commit already holds
+ * that work, so the source only has to keep its commit.
+ */
+export function sourceCheckoutUnchanged(cwd: string | undefined, capsule: TaskCapsule): boolean {
+  if (!cwd) return false;
+  try {
+    if (inspectRepository(cwd).revision !== capsule.baseSha) return false;
+    if (capsule.checkpoint) return true;
+    const tree = workingTreeState(cwd);
+    if (tree !== (capsule.workingTree ?? 'unknown')) return false;
+    return tree !== 'dirty' || dirtyDiffHash(cwd) === capsule.dirtyDiffHash;
+  } catch {
+    return false;
+  }
+}

package/apps/bridge/src/mesh/tasks/readiness.ts

@@ -2,18 +2,18 @@
  * Handoff readiness.
  *
  * A Task Capsule carries facts, not files: the destination starts a worktree
- * from a commit. Anything still uncommitted stays on the source computer even
- * though the Task visibly continues elsewhere, so a handoff that would lose it
- * is refused instead of silently narrowing to committed state.
+ * from a commit. Anything still uncommitted stays on the source computer while
+ * the Task continues elsewhere. That is the person's call, so it is said out
+ * loud — on the phone, here, and in the capsule — rather than refused.
  */
 import type { ResourceClaim, TaskCapsule } from "../../../../../packages/protocol/schema";
 
-export const UNCOMMITTED_WORK_REASON =
-  "This task has uncommitted changes. Commit or checkpoint them before moving the task.";
+export const UNCOMMITTED_WORK_WARNING =
+  "This task has uncommitted changes. They stay on this computer; the next agent starts from the last commit.";
 
-/** An unread working tree blocks the move; only a positive "clean" releases it. */
-export const UNREADABLE_WORKING_TREE_REASON =
-  "GrantTap could not read this working tree, so it cannot promise a commit carries every change.";
+/** "We could not look" is not "clean", so an unread tree is warned about too. */
+export const UNREADABLE_WORKING_TREE_WARNING =
+  "GrantTap could not read this working tree, so uncommitted changes may stay on this computer.";
 
 export type HandoffCheckId = "repository" | "workingTree" | "claims" | "targetAgent";
 
@@ -48,11 +48,11 @@ function workingTree(capsule?: TaskCapsule): "clean" | "dirty" | "unknown" {
   return capsule?.workingTree ?? "unknown";
 }
 
-function workingTreeDetail(capsule?: TaskCapsule): string {
+function workingTreeWarning(capsule?: TaskCapsule): string | undefined {
   switch (workingTree(capsule)) {
-    case "clean": return "Clean";
-    case "dirty": return UNCOMMITTED_WORK_REASON;
-    default: return UNREADABLE_WORKING_TREE_REASON;
+    case "clean": return undefined;
+    case "dirty": return UNCOMMITTED_WORK_WARNING;
+    default: return UNREADABLE_WORKING_TREE_WARNING;
   }
 }
 
@@ -68,11 +68,7 @@ export function handoffReadiness(input: HandoffReadinessInput): HandoffReadiness
         ? `Commit ${capsule.latestCommit ?? capsule.baseSha} in ${capsule.repository}`
         : "No git repository, task, or commit was found for this execution.",
     ),
-    check(
-      "workingTree",
-      Boolean(capsule) && workingTree(capsule) === "clean",
-      workingTreeDetail(capsule),
-    ),
+    check("workingTree", Boolean(capsule), workingTreeWarning(capsule) ?? "Clean"),
     check(
       "claims",
       !conflict,
@@ -89,9 +85,11 @@ export function handoffReadiness(input: HandoffReadinessInput): HandoffReadiness
     ),
   ];
   const blocked = checks.find((item) => !item.ready);
+  const leftBehind = capsule ? workingTreeWarning(capsule) : undefined;
   // Same module, different file: the merge conflict that has not happened
   // yet. Said out loud, not enforced — two agents can share a module.
-  const warnings = (input.moduleOverlaps ?? []).slice(0, 8).map((claim) =>
+  const overlaps = (input.moduleOverlaps ?? []).slice(0, 8).map((claim) =>
     `${claim.ownerSessionId} is working in the same module (${claim.resource}).`);
+  const warnings = [...(leftBehind ? [leftBehind] : []), ...overlaps];
   return { ready: !blocked, blockedReason: blocked?.detail, checks, warnings };
 }

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

package/cursor-plugin/stdio-bootstrap.cjs

@@ -7,7 +7,7 @@ const { spawn } = require("node:child_process");
 const { existsSync } = require("node:fs");
 const { delimiter, dirname, join } = require("node:path");
 
-const PACKAGE = "granttap-mcp@0.8.69";
+const PACKAGE = "granttap-mcp@0.8.70";
 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.69",
+  "version": "0.8.70",
   "description": "Apache-2.0 computer runtime connecting local coding agents to GrantTap on Mac, iPhone, iPad and Apple Watch.",
   "type": "module",
   "bin": {

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

@@ -218,8 +218,9 @@ export const MeshHandoffPrepare = z.object({
   userComment: Detail.optional(),
   createdAt: z.number().nonnegative(),
   /**
-   * Commit uncommitted work to a checkpoint branch first, so the Task can
-   * leave without losing it. The branch is local: GrantTap never pushes.
+   * Commit uncommitted work to a checkpoint branch first, so the work travels
+   * with the Task instead of staying behind. The branch is local: GrantTap
+   * never pushes.
    */
   checkpoint: z.boolean().optional(),
   /**