granttap-mcp 0.8.1 → 0.8.2

package/README.md

@@ -78,11 +78,34 @@ 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. The destination is refused just
+committed state and leaving that work behind. 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; the destination says so if the commit has not reached it.
+
+Claims do not wait for an agent to announce them. Every edit an agent makes is
+visible in its transcript, so the runtime derives an intent claim from each
+recent write — marked as seen rather than said, and expiring ten minutes after
+the writing stops. Overlap is judged twice: the same file is a conflict, and
+the same module is the warning that comes before it. A module is recognised
+from the path alone, so every computer and the phone reach the same answer,
+and the Task screen names who else is in this Task's files or modules while it
+can still be avoided. The destination is refused just
 as explicitly when the named commit is not on its computer, or when the
 capsule's own resource claims overlap another execution's; GrantTap never
 pushes or fetches on its own.
 
+A Project usually binds more than one repository, and a bound repository can
+say which of the others sit on the far side of its databases, topics, and APIs:
+commit a [`WEAVATRIX.md`](https://github.com/Weavatrix/weavatrix-md) next to the
+README and the runtime reads it — only the edges it states, nothing inferred —
+and publishes them with the Project. The Task screen then names another Task
+that is working on the other side of a contract this Task touches (the consumer
+of a topic it produces, the caller of an API it changes), and the scoped
+`granttap://mesh/{capability}` resource gives the agent the same `peers`,
+`otherSide`, and `neighbours` so it can coordinate before it commits.
+
 ### Grok Bot as a scoped Mesh participant
 
 Grok Bot is a persistent agent, not a coding-agent integration. The iPhone
@@ -182,6 +205,51 @@ The bounded encrypted protocol preserves:
 An optional bounded `errorClass` may describe an error category. Full tool
 error payloads are not copied into usage telemetry by default.
 
+### One computer, whatever the network calls it
+
+The Mesh keys a computer by an identity written down once, on first use, in
+`computer.json` in the config directory — the hostname it had then — and
+keeps it. A Mac renamed by the network it joins ("Mac.lan" at home,
+"Serhiis-MacBook-Pro.local" elsewhere) used to become a second computer with
+its own open executions and repository bindings; now every later hostname is
+remembered as a former name of the same machine, its leftover executions are
+closed and its bindings marked unavailable, and the current hostname stays
+what people see. `GRANTTAP_COMPUTER_ID` overrides the stored id.
+
+### Run journal and prompt-time context
+
+A message from the phone is answered by a fresh `claude -p --resume` of the
+same chat. Its turns land in the transcript, but a session holding that chat
+open never sees them — its context was built before they happened. The runtime
+therefore journals every delivery: what was asked (without the attachment
+note), what came back, which files were written, how many tool calls it took,
+and whether the run was cut off by the ten-minute delivery limit. The Task
+carries the same digest as `TASK_PROGRESS`, so the phone's timeline and the
+Mesh show it. A `UserPromptSubmit` hook, installed beside the approval hook by
+`granttap setup`, adds the unread journal to the next prompt of the live
+session together with the Mesh brief — the other live Tasks in the Project,
+who is in the same file or module, the other side of the repository, and any
+question still unanswered — and names the MCP resource
+`granttap://mesh/{capability}/map`, one page of markdown with the whole
+Project: Tasks, who edits which module, the other side of each repository,
+dependencies, and what just happened. Background runs themselves receive
+nothing from the hook; the journal is kept for the session a person is in.
+
+### Tool versions and updates from the phone
+
+The status also names each provider's command-line tool as it answers on this
+computer — its version, how it is kept current, and, for Claude Code, whether a
+newer copy already sits on the disk (the Claude desktop app keeps its own; the
+runtime uses the newest one it finds). A tool that lags the rest of the
+environment fails in ways the phone can only report, so the phone can ask this
+computer to update one: the phone names only the tool, and the command is the
+runtime's, fixed by how the tool was installed — `claude update`, `agent
+update`, `grok update`, the npm that owns the tool's prefix, or Homebrew. The
+runtime never downloads a tool itself; a tool installed by an installer script
+is left to a trusted terminal, with the command spelled out in the answer. The
+result — version before and after, the updater's own output — comes back as
+`tool.update.result`.
+
 Cost is reported as attributed rather than measured, because that is what it
 is. A call is read back from the transcript once it has finished, so it can
 never be measured directly: an MCP server outlives its calls and is sampled
@@ -206,6 +274,34 @@ The user-facing approval modes map to the existing runtime policy:
 
 Legacy custom levels remain compatible but are not part of the primary flow.
 
+## Project Governance
+
+Capabilities are decided per Project, not per task. A policy names an effect —
+`allow`, `ask`, or `deny` — for each kind (skills, MCP servers, shell and
+scripts, file writes, deploy, network), and may name one capability alone: one
+MCP server can be forbidden without forbidding every server. A named rule wins
+over its kind, and a global deny always wins over a Project.
+
+The phone authors the policy and hands it to every Project computer through the
+relay, which holds the encrypted packet until each computer reads its mailbox;
+a computer that was asleep receives it when it returns. Each computer applies
+the policy through the GrantTap Engine, acknowledges the revision it enforces,
+and reports coverage — enforced, observed only, unsupported, or unknown — per
+capability kind, so the phone shows what is actually in force rather than what
+was sent. Revision zero is a Project with no policy yet, and it is reported so
+the first policy can be written.
+
+Evaluation happens in the provider hook before the action runs, with a deadline
+long enough for a busy machine to answer. A missed answer falls back to the
+legacy GrantTap gate rather than to a silent allow, and content never crosses
+to the engine: it receives a capability fingerprint, not the command or file.
+
+A refusal is said where the action was. Each one is written down for its chat,
+and the timeline carries it as a status row naming the rule and the reason,
+beside the call it stopped. On the phone a rule is written where the need for
+it appears: touch and hold a tool on the Project page, or use the Governance
+menu on a tool's call history, to allow, ask, or deny it for the Project.
+
 ## Relay boundary
 
 Pairing and task keys are generated locally. The relay receives opaque routing

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

@@ -12,6 +12,7 @@
  * Fails closed: any error or timeout denies the tool call rather than letting it
  * through unattended — unless GrantTap auto-accept allows it locally.
  */
+import { recordProjectDecision } from "../policy/decision-log";
 import { claudeToRequest, decisionToClaudeOutput, type HookInput } from "../adapters";
 import { isUnanswered, requestApproval } from "../approval";
 import {
@@ -82,6 +83,13 @@ async function handlePreToolUse(input: HookInput): Promise<void> {
     legacyDenyReason: blocked?.reason,
   });
   if (projectDecision.effect === "deny") {
+    // Say so where the action was, not only to the agent.
+    if (input.session_id) {
+      recordProjectDecision(input.session_id, {
+        at: Date.now(), toolName: input.tool_name ?? "tool", reason: projectDecision.reason,
+        ruleId: projectDecision.rule_id,
+      });
+    }
     writePermission("deny", projectDecision.reason);
     return;
   }

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Claude Code UserPromptSubmit hook entry point.
+ *
+ * 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.
+ *
+ *   Reads:  UserPromptSubmit JSON on stdin ({ session_id, prompt, cwd, ... })
+ *   Writes: { hookSpecificOutput: { hookEventName, additionalContext } } on stdout
+ */
+import { promptContext } from "../mesh/prompt-context";
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main(): Promise<void> {
+  // A background run answering the phone is itself a prompt submission; it is
+  // not the live session the journal is kept for.
+  if (process.env.GRANTTAP_DELIVERY) return;
+  const raw = await readStdin();
+  let input: { session_id?: unknown };
+  try {
+    input = JSON.parse(raw) as { session_id?: unknown };
+  } catch {
+    return;
+  }
+  const sessionId = typeof input.session_id === "string" ? input.session_id.trim() : "";
+  const text = promptContext(sessionId);
+  if (!text) return;
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: text },
+  }));
+}
+
+main().catch(() => undefined).finally(() => process.exit(0));

package/apps/bridge/src/bin/codex-policy-hook.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env -S npx tsx
 /** Codex PreToolUse: deterministic deny or one-shot Project ASK handoff. */
+import { recordProjectDecision } from "../policy/decision-log";
 import type { HookInput } from "../adapters";
 import { blockedSessionCapability, isProviderEnabled } from "../config";
 import { recordCodexProjectAsk } from "../policy/codex-project-ask";
@@ -39,6 +40,11 @@ async function main(): Promise<void> {
     legacyDenyReason: blocked?.reason,
   });
   if (decision.effect === "deny") {
+    if (input.session_id) {
+      recordProjectDecision(input.session_id, {
+        at: Date.now(), toolName: input.tool_name ?? "tool", reason: decision.reason, ruleId: decision.rule_id,
+      });
+    }
     deny(decision.reason);
     return;
   }

package/apps/bridge/src/bin/cursor-hook.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env -S npx tsx
 /** Cursor beforeShellExecution: exact chat block, otherwise phone/native approval. */
+import { recordProjectDecision } from "../policy/decision-log";
 import {
   cursorToRequest,
   decisionToCursorOutput,
@@ -83,6 +84,12 @@ async function handleShell(input: CursorHookInput): Promise<void> {
     legacyDenyReason: blocked?.reason,
   });
   if (projectDecision.effect === "deny") {
+    if (sessionId) {
+      recordProjectDecision(sessionId, {
+        at: Date.now(), toolName: input.tool_name ?? "Shell",
+        reason: projectDecision.reason, ruleId: projectDecision.rule_id,
+      });
+    }
     deny(projectDecision.reason);
     return;
   }

package/apps/bridge/src/bin/cursor-mcp-hook.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env -S npx tsx
 /** Cursor beforeMCPExecution: exact server/chat block, otherwise phone/native approval. */
+import { recordProjectDecision } from "../policy/decision-log";
 import { randomId } from "../../../../packages/core/crypto";
 import type { ApprovalRequest } from "../../../../packages/protocol/schema";
 import { decisionToCursorOutput } from "../adapters";
@@ -97,6 +98,12 @@ async function handleMcp(input: CursorMcpHookInput): Promise<void> {
     legacyDenyReason: blocked?.reason,
   });
   if (projectDecision.effect === "deny") {
+    if (sessionId) {
+      recordProjectDecision(sessionId, {
+        at: Date.now(), toolName: server ? `mcp__${server}__${toolName}` : toolName,
+        reason: projectDecision.reason, ruleId: projectDecision.rule_id,
+      });
+    }
     deny(projectDecision.reason);
     return;
   }

package/apps/bridge/src/claude-bin.ts

@@ -0,0 +1,112 @@
+/**
+ * Which Claude Code answers the phone.
+ *
+ * A chat the user opened in the Claude desktop app was written by the Claude
+ * Code the app ships, and an older `claude` on PATH cannot resume it: the API
+ * refuses with "Claude Code X does not support model version Y". The app keeps
+ * its own copies of Claude Code on this Mac, and the native installer keeps
+ * every version it ever installed, so the newest one present is the one to
+ * use. Nothing is downloaded or updated here — the helper never changes the
+ * user's tools — only chosen. An explicit `GRANTTAP_CLAUDE_BIN` still wins.
+ */
+import { accessSync, constants, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { binaryVersion } from "./tools/version";
+
+export type ClaudeBinary = { path: string; version?: string };
+
+function executable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `2.1.260` from an installer's directory name such as `2.1.260`. */
+export function versionOf(segment: string): string | undefined {
+  return /^v?(\d+\.\d+\.\d+)$/.exec(segment.trim())?.[1];
+}
+
+export function compareVersions(left: string, right: string): number {
+  const a = left.split(".").map(Number);
+  const b = right.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    const delta = (a[index] ?? 0) - (b[index] ?? 0);
+    if (delta !== 0) return delta;
+  }
+  return 0;
+}
+
+export function executableOnPath(command: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  for (const dir of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    const candidate = join(dir, command);
+    if (executable(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function versioned(path: string): ClaudeBinary {
+  // The native installer and the app state the version in the path; any other
+  // install is asked once and remembered until the binary changes.
+  const version = binaryVersion(path);
+  return version ? { path, version } : { path };
+}
+
+function children(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+/** Every Claude Code this Mac keeps, newest first; PATH's own `claude` included. */
+export function installedClaudeBinaries(
+  home = homedir(),
+  env: NodeJS.ProcessEnv = process.env,
+): ClaudeBinary[] {
+  const found: ClaudeBinary[] = [];
+  const fromPath = executableOnPath("claude", env);
+  if (fromPath) found.push(versioned(fromPath));
+  const installer = join(home, ".local", "share", "claude", "versions");
+  for (const name of children(installer)) {
+    const path = join(installer, name);
+    if (versionOf(name) && executable(path)) found.push({ path, version: versionOf(name) });
+  }
+  const app = join(home, "Library", "Application Support", "Claude", "claude-code");
+  for (const name of children(app)) {
+    const path = join(app, name, "claude.app", "Contents", "MacOS", "claude");
+    if (versionOf(name) && executable(path)) found.push({ path, version: versionOf(name) });
+  }
+  return found.sort((left, right) => {
+    if (left.version && right.version) return compareVersions(right.version, left.version);
+    return left.version ? -1 : right.version ? 1 : 0;
+  });
+}
+
+/**
+ * The Claude Code to run: the explicit override, else the newest installed,
+ * else plain `claude` for PATH to resolve.
+ */
+export function resolveClaudeBinary(
+  home = homedir(),
+  env: NodeJS.ProcessEnv = process.env,
+): ClaudeBinary {
+  const override = env.GRANTTAP_CLAUDE_BIN ?? env.NODVOX_CLAUDE_BIN;
+  if (override) return versioned(override);
+  return installedClaudeBinaries(home, env)[0] ?? { path: "claude" };
+}
+
+/**
+ * The failure a too-old Claude Code reports, with the way out attached: the
+ * version that answered, and the one command that replaces it.
+ */
+export function explainClaudeFailure(error: string, binary: ClaudeBinary): string {
+  if (!/does not support|not supported|outdated|update claude code|upgrade/i.test(error)) return error;
+  const which = binary.version ? `Claude Code ${binary.version}` : "This Claude Code";
+  return `${error.trim()} — ${which} at ${binary.path} is older than this chat needs. `
+    + "Run `claude update` on this Mac, or open the chat in the Claude app once so its newer Claude Code is present.";
+}

package/apps/bridge/src/install.ts

@@ -18,6 +18,8 @@ import {
   readFileSync,
   writeFileSync,
 } from "node:fs";
+import { resolveClaudeBinary } from "./claude-bin";
+import { describeCommand, inspectTools, updatingTools } from "./tools/updater";
 import { resolveCursorAgentBin } from "./reply/cursor-agent-bin";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
@@ -31,6 +33,7 @@ const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..")
 
 export type HookRoute =
   | "claude"
+  | "claude-prompt"
   | "codex"
   | "codex-policy"
   | "cursor"
@@ -60,6 +63,10 @@ export type AgentIntegrationStatus = {
   agent: CodingAgent;
   installed: boolean;
   hookConfigured: boolean;
+  version?: string;
+  updateCommand?: string;
+  newerOnThisMac?: string;
+  updating?: boolean;
 };
 
 function executableAvailable(command: string): boolean {
@@ -244,17 +251,28 @@ export function inspectCursorIntegration(): CursorIntegrationStatus {
 /** Read-only capability check used by phone/watch connection states. */
 export function inspectAgentIntegrations(): AgentIntegrationStatus[] {
   const codex = process.env.GRANTTAP_CODEX_BIN ?? process.env.NODVOX_CODEX_BIN ?? "codex";
-  const claude = process.env.GRANTTAP_CLAUDE_BIN ?? process.env.NODVOX_CLAUDE_BIN ?? "claude";
+  const claude = resolveClaudeBinary().path;
   const cursor = process.env.GRANTTAP_CURSOR_AGENT_BIN ?? resolveCursorAgentBin();
   const grok = process.env.GRANTTAP_GROK_BIN ?? "grok";
   const cursorStatus = inspectCursorIntegration();
+  const tools = new Map(inspectTools().map((tool) => [tool.agent, tool]));
+  const updating = new Set(updatingTools());
+  const tool = (agent: CodingAgent): Partial<AgentIntegrationStatus> => {
+    const status = tools.get(agent);
+    const extra: Partial<AgentIntegrationStatus> = {};
+    if (status?.version) extra.version = status.version;
+    if (status?.update) extra.updateCommand = describeCommand(status.update);
+    if (status?.newerOnThisMac) extra.newerOnThisMac = status.newerOnThisMac;
+    if (updating.has(agent)) extra.updating = true;
+    return extra;
+  };
   return [
-    { agent: "codex", installed: executableAvailable(codex), hookConfigured: codexHookConfigured() },
-    { agent: "claude", installed: executableAvailable(claude), hookConfigured: claudeHookConfigured() },
-    { agent: "cursor", installed: executableAvailable(cursor), hookConfigured: cursorStatus.hookConfigured },
+    { agent: "codex", installed: executableAvailable(codex), hookConfigured: codexHookConfigured(), ...tool("codex") },
+    { agent: "claude", installed: executableAvailable(claude), hookConfigured: claudeHookConfigured(), ...tool("claude") },
+    { agent: "cursor", installed: executableAvailable(cursor), hookConfigured: cursorStatus.hookConfigured, ...tool("cursor") },
     // Grok Build's headless session contract is direct; GrantTap does not
     // claim an approval hook exists when none has been installed.
-    { agent: "grok", installed: executableAvailable(grok), hookConfigured: false },
+    { agent: "grok", installed: executableAvailable(grok), hookConfigured: false, ...tool("grok") },
   ];
 }
 
@@ -550,6 +568,10 @@ export function installClaudeHook(): InstallResult {
     }
   }
 
+  // The prompt hook rides along with the approval hook: what the chat could
+  // not know by itself — background runs in it, the Mesh around it — is added
+  // to each prompt. It never blocks; anything wrong, and it adds nothing.
+  const promptHookChanged = ensureClaudePromptHook(settings);
   const entries: any[] = (((settings.hooks ??= {}).PreToolUse ??= []) as any[]);
   const currentCommand = hookCommand("claude");
   const presentEntry = entries.find((entry) =>
@@ -563,11 +585,14 @@ export function installClaudeHook(): InstallResult {
   if (present && presentEntry) {
     const matcherChanged = repairClaudeMatcher(presentEntry);
     const commandChanged = present.command !== currentCommand;
-    if (!matcherChanged && !commandChanged) return { status: "already", detail: path };
+    if (!matcherChanged && !commandChanged && !promptHookChanged) return { status: "already", detail: path };
     backupOnce(path);
     present.command = currentCommand;
     writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
-    return { status: "installed", detail: `${path}, GrantTap hook and matcher repaired` };
+    const detail = !matcherChanged && !commandChanged
+      ? `${path}, GrantTap prompt hook added`
+      : `${path}, GrantTap hook and matcher repaired`;
+    return { status: "installed", detail };
   }
 
   const legacyEntry = entries.find((entry) =>
@@ -597,6 +622,22 @@ export function installClaudeHook(): InstallResult {
   return { status: "installed", detail: path };
 }
 
+/** Make sure the UserPromptSubmit hook is registered once, at the current command. */
+function ensureClaudePromptHook(settings: any): boolean {
+  const entries: any[] = (((settings.hooks ??= {}).UserPromptSubmit ??= []) as any[]);
+  const command = hookCommand("claude-prompt");
+  const present = entries
+    .flatMap((entry) => (Array.isArray(entry?.hooks) ? entry.hooks : []))
+    .find((hook: any) => commandHasRoute(hook?.command, "claude-prompt"));
+  if (present) {
+    if (present.command === command) return false;
+    present.command = command;
+    return true;
+  }
+  entries.push({ hooks: [{ type: "command", command, timeout: 10 }] });
+  return true;
+}
+
 // --------------------------------------------------------------------- Codex
 
 function rewriteDisabledCodexHooks(config: string): { config: string; changed: boolean } {

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

@@ -8,6 +8,7 @@ import {
 } from "../../../../packages/protocol/schema";
 import { workingTreeState } from "./catalog";
 import type { MeshStore } from "./store";
+import type { Checkpoint } from "./checkpoint";
 
 function git(cwd: string, args: string[]): string | undefined {
   try {
@@ -51,6 +52,7 @@ export function buildTaskCapsule(
   session: SessionInfo,
   request: MeshHandoffPrepare,
   computerId: string,
+  checkpoint?: Checkpoint,
 ): CapsuleValue | undefined {
   const cwd = session.worktree ?? session.cwd;
   const snapshot = store.snapshot(request.projectId);
@@ -83,6 +85,28 @@ export function buildTaskCapsule(
     importantDecisions: [],
     createdAt: Date.now(),
   };
-  const parsed = TaskCapsule.safeParse(capsule);
+  // A checkpoint commit is the fact the capsule carries instead of the dirty
+  // tree: it holds every change the tree had, so relative to it the tree is
+  // clean. Whether the destination has that commit is its own check.
+  const described = checkpoint
+    ? {
+      ...capsule,
+      latestCommit: checkpoint.sha,
+      branch: checkpoint.branch,
+      dirtyDiffHash: undefined,
+      workingTree: "clean" as const,
+      filesChanged: changedFilesBetween(cwd, head, checkpoint.sha),
+      remainingWork: [
+        `Continue from checkpoint ${checkpoint.sha.slice(0, 12)} on ${checkpoint.branch}.`,
+        `Push ${checkpoint.branch} from ${computerId} if the destination does not have it.`,
+      ],
+    }
+    : capsule;
+  const parsed = TaskCapsule.safeParse(described);
   return parsed.success ? parsed.data : undefined;
 }
+
+function changedFilesBetween(cwd: string, from: string, to: string): string[] {
+  const listed = git(cwd, ["diff", "--name-only", `${from}..${to}`]) ?? "";
+  return [...new Set(listed.split("\n").map((line) => line.trim()).filter(Boolean))].slice(0, 64);
+}

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

@@ -14,6 +14,8 @@ import {
   sanitizedRepositoryRemote,
   taskIdentity,
 } from "./identity";
+import { formerComputerNames } from "./computer-identity";
+import { readIntegrationMap } from "./integration-map";
 import type { MeshStore } from "./store";
 import { syncProjectBinding } from "../engine/engine-projects";
 
@@ -119,7 +121,12 @@ export function linkSessionsToProjects(
   sessions: SessionInfo[],
   computerId: string,
   inspect: (cwd: string) => RepositoryFacts = inspectRepository,
+  formerNames: string[] = formerComputerNames(),
 ): SessionInfo[] {
+  // Records kept under a name this computer used to go by are this computer's
+  // leftovers, not a second machine: their executions are over and their
+  // bindings unavailable.
+  store.retireComputerNames(computerId, formerNames);
   // A vanished session never says it ended, so sweep first: an execution left
   // open holds the Task, keeps its old title, and keeps its last state.
   store.closeVanishedExecutions(
@@ -172,6 +179,9 @@ export function linkSessionsToProjects(
     // same pass, which is what an escaping throw did.
     try {
       store.upsertBinding(binding);
+      store.recordIntegrationPeers(
+        projectId, repository.canonicalRepositoryId, readIntegrationMap(repository.root),
+      );
       void syncProjectBinding(project, {
         summary: binding,
         localRoot: repository.root,
@@ -202,6 +212,7 @@ export function linkSessionsToProjects(
       provider: agent,
       computerId,
       workspace: cwd,
+      repositoryId: repository.canonicalRepositoryId,
       branch: session.branch,
       worktree: repository.worktree,
       uncommitted: hasUncommittedWork(repository.worktree ?? cwd),

package/apps/bridge/src/mesh/checkpoint.ts

@@ -0,0 +1,52 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Commit everything uncommitted to a checkpoint branch, touching nothing else.
+ *
+ * A Task Capsule carries a commit, so uncommitted work used to block the move
+ * until the person committed by hand. This makes the commit for them — on a
+ * branch of its own, from a temporary index, so HEAD, the current branch, and
+ * the working tree are exactly as the agent left them. Nothing is pushed:
+ * publishing a branch is the person's decision, and the destination says so
+ * if the commit has not reached it yet.
+ */
+export type Checkpoint = { sha: string; branch: string; files: number };
+
+export const CHECKPOINT_BRANCH_PREFIX = "granttap/checkpoint/";
+
+function git(cwd: string, args: string[], env: NodeJS.ProcessEnv = process.env): string {
+  return execFileSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 30_000, env,
+    maxBuffer: 16 * 1_024 * 1_024,
+  }).trim();
+}
+
+export function checkpointBranchName(taskId: string): string {
+  return CHECKPOINT_BRANCH_PREFIX + taskId.replace(/[^A-Za-z0-9._-]/g, "-").slice(0, 64);
+}
+
+export function createCheckpoint(cwd: string, taskId: string, title: string): Checkpoint | undefined {
+  const scratch = mkdtempSync(join(tmpdir(), "granttap-checkpoint-"));
+  try {
+    const head = git(cwd, ["rev-parse", "HEAD"]);
+    const env = { ...process.env, GIT_INDEX_FILE: join(scratch, "index") };
+    // Start the scratch index from HEAD so deletions are recorded too.
+    git(cwd, ["read-tree", "HEAD"], env);
+    git(cwd, ["add", "-A"], env);
+    const tree = git(cwd, ["write-tree"], env);
+    if (tree === git(cwd, ["rev-parse", "HEAD^{tree}"])) return undefined; // nothing to keep
+    const message = `GrantTap checkpoint: ${title.replace(/\s+/g, " ").slice(0, 120)}`;
+    const sha = git(cwd, ["commit-tree", tree, "-p", head, "-m", message], env);
+    const branch = checkpointBranchName(taskId);
+    git(cwd, ["branch", "-f", branch, sha]);
+    const files = git(cwd, ["diff", "--name-only", `${head}..${sha}`]).split("\n").filter(Boolean).length;
+    return { sha, branch, files };
+  } catch {
+    return undefined;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}