granttap-mcp 0.8.69 → 0.8.71

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/graph/binding-sync.ts

@@ -5,7 +5,15 @@ 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. */
+/**
+ * Re-admit this computer's verified checkouts before an explicit Graph build.
+ *
+ * Only a repository whose Graph is genuinely unavailable is reported. A plain
+ * folder an agent ran in, a subfolder of a repository, a removed checkout and
+ * a former identity of a checkout another binding already describes are not
+ * repositories with a broken Graph; reporting them filled Mesh Health with
+ * errors nobody could act on.
+ */
 export async function refreshLocalGraphBindings(
   snapshot: MeshSnapshot,
   dependencies: {
@@ -18,19 +26,23 @@ export async function refreshLocalGraphBindings(
   const candidates = (snapshot.bindings ?? []).filter((binding) =>
     binding.endpointId === localEndpoint && binding.available && binding.localPathHint);
   const failures: ProjectRepositoryGraph[] = [];
-  await Promise.all(candidates.map(async (binding) => {
+  const checkouts = candidates.flatMap((binding) => {
+    const facts = readCheckout(dependencies.inspect, binding.localPathHint!);
+    return facts ? [{ binding, facts, real: realpathSync(facts.root) }] : [];
+  });
+  await Promise.all(checkouts.map(async ({ binding, facts, real }) => {
+    const pathIdentity = matchesLocalCheckout(binding.repositoryId, facts.root);
+    if (facts.canonicalRepositoryId !== binding.repositoryId && !pathIdentity) {
+      const described = checkouts.some((other) => other.real === real
+        && (other.binding.repositoryId === facts.canonicalRepositoryId
+          || matchesLocalCheckout(other.binding.repositoryId, facts.root)));
+      if (!described) failures.push({ projectId: snapshot.projectId, repositoryId: binding.repositoryId,
+        revision: "unverified", weavatrixVersion: "unknown", analysisStatus: "UNAVAILABLE",
+        analysisErrorCode: "REPOSITORY_IDENTITY_MISMATCH",
+        nodes: [], relations: [], totalNodes: 0, totalRelations: 0, truncated: false });
+      return;
+    }
     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 && !pathIdentity)) {
-        failures.push({ projectId: snapshot.projectId, repositoryId: binding.repositoryId,
-          revision: "unverified", weavatrixVersion: "unknown", analysisStatus: "UNAVAILABLE",
-          analysisErrorCode: facts.worktree ? "REPOSITORY_IDENTITY_MISMATCH" : "REPOSITORY_IDENTITY_UNVERIFIED",
-          nodes: [], relations: [], totalNodes: 0, totalRelations: 0, truncated: false });
-        return;
-      }
       const admitted = await dependencies.sync(snapshot.project, {
         summary: binding,
         localRoot: facts.root,
@@ -45,6 +57,17 @@ export async function refreshLocalGraphBindings(
   return failures;
 }
 
+/** A Git checkout rooted exactly at the bound path, or nothing a Graph can be built from. */
+function readCheckout(inspect: typeof inspectRepository, path: string) {
+  try {
+    const facts = inspect(path);
+    if (!facts.worktree || realpathSync(facts.root) !== realpathSync(path)) return undefined;
+    return facts;
+  } catch {
+    return undefined;
+  }
+}
+
 function admissionFailure(snapshot: MeshSnapshot, binding: NonNullable<MeshSnapshot["bindings"]>[number]): ProjectRepositoryGraph {
   return { projectId: snapshot.projectId, repositoryId: binding.repositoryId,
     revision: "unverified", weavatrixVersion: "unknown", analysisStatus: "UNAVAILABLE",

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/apps/bridge/src/monitor/README.md

@@ -15,6 +15,10 @@ beside `mesh-publication`. This module uses the repository Apache License 2.0.
 `message-delivery/index.ts` reserves the durable delivery lease, then
 emits a non-terminal processing receipt only after workspace, attachment and
 provider validation. Duplicate validated requests replay that receipt without
-starting another provider run. The eleven-minute lease covers the ten-minute
-provider timeout. New-task startup events are status updates; the correlated
-result is terminal. Delivery integration tests live in `tests/delivery`.
+starting another provider run. A message is delivered once the agent has
+taken it: `message-delivery/acceptance.ts` reports an immediate failure as that
+failure and accepts a run still going after a short window, so the
+eleven-minute lease only has to cover that window. The answer, or the reason a
+long run stopped, reaches the chat when the run ends; unattended runs are
+bounded at six hours. New-task startup events are status updates; the
+correlated result is terminal. Delivery integration tests live in `tests/delivery`.

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

@@ -4,8 +4,6 @@ import type { RelayClient } from "../../../../../packages/core/relay-client";
 import { pruneAttachments, takeAttachment } from "../../delivery/attachment-store";
 import { sendSessionPayload } from "../../host/session-keys";
 
-export const DELIVERY_TIMEOUT_MS = 10 * 60_000;
-
 export async function sendDeliveryReceipt(
   client: RelayClient,
   messageId: string,

package/apps/bridge/src/monitor/handlers/task-create.ts

@@ -9,6 +9,7 @@ import {
   createCodexSession,
   createCursorSession,
   createGrokSession,
+  type ReplyResult,
 } from "../../reply";
 import { acceptInstanceEpoch } from "../../host/instance-epoch";
 import { evaluateCreateTask } from "../../mesh/tasks/create-task";
@@ -16,7 +17,7 @@ import { recordDelegation } from "../../mesh/handoff/delegation-loop";
 import { enqueuePinnedTask } from "../../mesh/tasks/queue";
 import { sendSessionPayload } from "../../host/session-keys";
 import { resolveMessageAttachments } from "./receipts";
-import { DELIVERY_TIMEOUT_MS } from "./receipts";
+import { acceptWhenStarted, PHONE_RUN_LIMIT_MS } from "../message-delivery/acceptance";
 
 export type TaskCreateAdmission =
   | { status: "accepted" }
@@ -99,15 +100,16 @@ export async function handleTaskCreate(
     cursor: createCursorSession,
     grok: createGrokSession,
   }[agent];
-  const result = await create(
-    message.text, message.cwd, DELIVERY_TIMEOUT_MS, resolved.attachments, message.model,
+  const run = create(
+    message.text, message.cwd, PHONE_RUN_LIMIT_MS, resolved.attachments, message.model,
     message.operationId,
   );
-  if (result.ok) {
-    await say(result.text, result.sessionId, true);
-  } else {
-    await say(`Could not create a ${displayName} task: ${result.error}`, undefined, true);
-    return { status: "rejected", error: "Provider delivery failed." };
-  }
-  return { status: "accepted" };
+  const settle = (result: ReplyResult, late: boolean) => result.ok
+    ? say(result.text, result.sessionId, true)
+    : say(late ? `The ${displayName} task stopped: ${result.error}`
+      : `Could not create a ${displayName} task: ${result.error}`, undefined, true);
+  const early = await acceptWhenStarted(run, (result) => settle(result, true));
+  if (early === "started") return { status: "accepted" };
+  await settle(early, false);
+  return early.ok ? { status: "accepted" } : { status: "rejected", error: "Provider delivery failed." };
 }

package/apps/bridge/src/monitor/handlers/user-message.ts

@@ -10,6 +10,7 @@ import {
   createCursorSession,
   createGrokSession,
   deliverToSession,
+  type ReplyResult,
 } from "../../reply";
 import { noteDeliveredRun } from "../../mesh/delivery/run-digest";
 import { evaluateCreateTask } from "../../mesh/tasks/create-task";
@@ -17,7 +18,7 @@ import { sendSessionPayload } from "../../host/session-keys";
 import { scanSessions } from "../../sessions";
 import { agentEventForUserMessage, sendDeliveryReceipt } from "./receipts";
 import { resolveMessageAttachments } from "./receipts";
-import { DELIVERY_TIMEOUT_MS } from "./receipts";
+import { acceptWhenStarted, PHONE_RUN_LIMIT_MS } from "../message-delivery/acceptance";
 
 async function startNewAgentTask(input: {
   client: RelayClient;
@@ -66,16 +67,17 @@ async function startNewAgentTask(input: {
     cursor: createCursorSession,
     grok: createGrokSession,
   }[agent];
-  const result = await create(
-    message.text, requestedCwd, DELIVERY_TIMEOUT_MS, resolved.attachments, message.model, undefined, message.effort,
+  const run = create(
+    message.text, requestedCwd, PHONE_RUN_LIMIT_MS, resolved.attachments, message.model, undefined, message.effort,
   );
-  if (result.ok) {
-    await say(result.text, result.sessionId, true);
-    return "accepted";
-  } else {
-    await say(`Could not create a ${displayName} task: ${result.error}`, undefined, true);
-    return "rejected";
-  }
+  const settle = (result: ReplyResult, late: boolean) => result.ok
+    ? say(result.text, result.sessionId, true)
+    : say(late ? `The ${displayName} task stopped: ${result.error}`
+      : `Could not create a ${displayName} task: ${result.error}`, undefined, true);
+  const early = await acceptWhenStarted(run, (result) => settle(result, true));
+  if (early === "started") return "accepted";
+  await settle(early, false);
+  return early.ok ? "accepted" : "rejected";
 }
 
 export async function handleUserMessage(
@@ -125,32 +127,34 @@ export async function handleUserMessage(
   // marks the person's bubble, and the next words in the chat are the answer.
   await onProcessing?.();
   const startedAt = Date.now();
-  const result = await deliverToSession(target, message.text, DELIVERY_TIMEOUT_MS, attachments, {
+  const run = deliverToSession(target, message.text, PHONE_RUN_LIMIT_MS, attachments, {
     preferredMcp: message.preferredMcp,
     skill: message.skill,
     model: message.model,
     permissionMode: message.permissionMode,
     effort: message.effort,
   });
-  // The run's turns are in the transcript, but a session holding this chat
-  // open never sees them; the journal is how it finds out on its next prompt,
-  // and the Task carries the same digest as progress.
-  const noted = noteDeliveredRun({
-    session: target,
-    prompt: message.text,
-    result,
-    startedAt,
-    endedAt: Date.now(),
-  });
-  if (noted?.event) {
-    await sendSessionPayload(client, noted.event, noted.event.taskId, "phone", { ttlMs: 24 * 60 * 60_000 })
-      .catch(() => {});
-  }
-  if (result.ok) {
-    await say(result.text, result.sessionId ?? target.sessionId, true);
-    return "accepted";
-  } else {
-    await say(`Could not deliver the message: ${result.error}`, target.sessionId, true);
-    return "rejected";
-  }
+  const settle = async (result: ReplyResult, late: boolean) => {
+    // The run's turns are in the transcript, but a session holding this chat
+    // open never sees them; the journal is how it finds out on its next prompt,
+    // and the Task carries the same digest as progress.
+    const noted = noteDeliveredRun({
+      session: target,
+      prompt: message.text,
+      result,
+      startedAt,
+      endedAt: Date.now(),
+    });
+    if (noted?.event) {
+      await sendSessionPayload(client, noted.event, noted.event.taskId, "phone", { ttlMs: 24 * 60 * 60_000 })
+        .catch(() => {});
+    }
+    if (result.ok) await say(result.text, result.sessionId ?? target.sessionId, true);
+    else await say(late ? `The run stopped: ${result.error}` : `Could not deliver the message: ${result.error}`,
+      target.sessionId, true);
+  };
+  const early = await acceptWhenStarted(run, (result) => settle(result, true));
+  if (early === "started") return "accepted";
+  await settle(early, false);
+  return early.ok ? "accepted" : "rejected";
 }

package/apps/bridge/src/monitor/message-delivery/README.md

@@ -5,6 +5,9 @@ sequence for non-correlated phone messages. Validation happens before the first
 processing receipt, and duplicate validated messages never start another run.
 Terminal responses remain correlated to the original message id.
 
+`acceptance.ts` decides when a phone message counts as delivered: when the agent
+has taken it, not when its whole turn ends. Tests live in `tests/acceptance.test.ts`.
+
 Integration tests: `tests/delivery/processing-receipt.test.ts`; attachment rejection
 coverage: `tests/attachment/attachment-uploads.test.ts`. See the monitor README.
 

package/apps/bridge/src/monitor/message-delivery/acceptance.ts

@@ -0,0 +1,33 @@
+/**
+ * When a message from the phone counts as delivered.
+ *
+ * Delivery used to mean "the agent finished its whole turn within ten
+ * minutes": a longer turn was killed at the deadline and the person's bubble
+ * turned "Not delivered" although the agent had taken the message and was
+ * working on it. Delivered now means the agent took it. A run that fails at
+ * once (paused, transferred, a CLI that will not start) is still that
+ * failure; a run that is still going after a short window is delivered, and
+ * its answer — or the reason it stopped — reaches the chat when it ends.
+ */
+
+/** Long enough for a provider CLI to refuse at once, short enough not to keep the phone waiting. */
+export const ACCEPTANCE_WINDOW_MS = 15_000;
+
+/** A safety bound for an unattended turn; the person stops a run with Stop, not with a deadline. */
+export const PHONE_RUN_LIMIT_MS = 6 * 60 * 60_000;
+
+export async function acceptWhenStarted<T>(
+  run: Promise<T>,
+  finish: (result: T) => Promise<unknown>,
+  windowMs = ACCEPTANCE_WINDOW_MS,
+): Promise<T | "started"> {
+  let timer: NodeJS.Timeout | undefined;
+  const started = new Promise<"started">((resolve) => {
+    timer = setTimeout(() => resolve("started"), windowMs);
+  });
+  const first = await Promise.race([run, started]);
+  clearTimeout(timer);
+  if (first !== "started") return first;
+  void run.then(finish).catch(() => {});
+  return "started";
+}

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.71
 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.71\";\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.71";
 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.71",
   "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(),
   /**