granttap-mcp 0.6.10 → 0.7.0

package/README.md

@@ -34,11 +34,47 @@ end-to-end encrypted.
 
 - Primary: Claude Code and Codex.
 - Beta: Cursor.
-- Experimental where available: GitHub Copilot CLI and Grok Build.
+- Experimental where available: Grok Build.
 
 GrantTap reports the depth each provider actually exposes. Visibility does not
 imply deterministic remote blocking or full mobile continuation.
 
+## Project Mesh and task handoff
+
+Project Mesh adds stable Project and Task identity above provider-native
+sessions. A Task can retain its `taskId` across multiple executions, agents,
+and computers while each native session remains intact.
+
+Agents can read the compact `granttap://mesh/current` MCP resource and publish
+bounded progress, dependency, question, answer, claim, conflict, and completion
+events through the existing `notify` tool. Full transcripts and hidden
+reasoning are never mesh payloads. Claims have TTLs; a colliding claim is
+rejected before it is recorded so agents can choose different work or contact
+the owner before escalating to Needs You.
+
+The first executable handoff path is Claude Code ↔ Codex across linked
+computers. GrantTap builds a bounded Task Capsule from explicit task/git facts,
+requires local phone authorization, creates a separate target branch/worktree,
+starts the target execution, and returns a receipt bound to the exact capsule.
+Cursor and Grok Build use the same provider-neutral schema and discovery model;
+unsupported remote-start paths fail closed instead of claiming parity.
+
+### Grok Bot as a scoped Mesh participant
+
+Grok Bot is a persistent agent, not a coding-agent integration. The iPhone
+issues a one-time encrypted Mesh Invite scoped to the Projects you select, and
+the invite is redeemed on the trusted CLI:
+
+```bash
+granttap mesh connect <one-time-invite>
+```
+
+Grok Bot then runs `granttap internal mesh-mcp`, a separate scoped MCP server
+that exposes only the twelve task-scoped Mesh operations. It cannot create
+invites, change the relay, expand Project scope, or reach `setup`; revoking the
+endpoint from the iPhone stops new Mesh operations immediately while local Task
+history stays on the device.
+
 ## Install
 
 ```bash
@@ -58,6 +94,7 @@ granttap setup
 granttap status [--json]
 granttap connect [--relay <wss-url>]
 granttap reset [--yes]
+granttap mesh connect <one-time-invite>
 ```
 
 `connect` reuses a valid pairing. If none exists, it creates a one-time QR.
@@ -89,6 +126,9 @@ MCP `connect` accepts no custom routing, replacement, or key-rotation input.
 Setup is CLI-only because it changes provider configuration and must not be
 available to a model through prompt injection.
 
+`notify` may alternatively carry one bounded task-scoped Mesh event. This does
+not add a fifth MCP tool or grant any global setup capability.
+
 Provider-native approvals and mobile continuation require the matching local
 adapter. MCP registration alone is never reported as proof that an integration
 is ready.
@@ -141,10 +181,19 @@ npm install
 npm run typecheck
 npm test
 npm run package:allowlist
+npm run test:coverage   # macOS only — see below
 ```
 
+`npm test` runs everywhere. Both suites run with an isolated `HOME`, so a
+developer's own Claude/Codex/Cursor data can never inflate a local result: the
+numbers on this machine and in CI are the same. The coverage contract is
+measured on macOS because the background helper, the Cursor OAuth service, and
+the installer only execute there, so a Linux percentage understates real
+runtime coverage. CI runs the cross-platform suite on Linux and the coverage
+gate on macOS, and `npm publish` enforces the same gate through
+`prepublishOnly`.
+
 Do not publish from a dirty checkout or before the package allowlist, tests,
 typecheck, and release checks pass.
 
-GrantTap is not affiliated with Anthropic, OpenAI, Apple, Microsoft, Anysphere,
-GitHub, or xAI.
+GrantTap is not affiliated with Anthropic, OpenAI, Apple, Anysphere, or xAI.

package/SECURITY.md

@@ -27,6 +27,9 @@ GrantTap does not send them to the relay.
   transfer key. The relay receives the mailbox ID and ciphertext, not the key.
 - Each attached task has an independent 256-bit task key. One task key cannot
   decrypt another task.
+- Project Mesh snapshots have independent project keys. Cross-computer events
+  remain under their Task key, and a linked destination receives either key
+  only through an explicit phone-mediated route.
 - Task keys travel only inside the authenticated device channel and are stored
   in device-protected storage.
 - Native phone/watch payloads remain authenticated ciphertext across the
@@ -46,6 +49,14 @@ whose independent keys were granted to it. The protection is against relay,
 database/network compromise, other pairings, and disclosure of a different
 task key—not against an endpoint already authorized for that task.
 
+Task Capsules are strict, bounded schemas containing goal, explicit status,
+repository/commit facts, changed-file names, tests, dependencies, claims,
+remaining work, and explicit decisions. Unknown fields are rejected; hidden
+reasoning and transcript replication are outside the contract. Handoff
+acceptance includes a SHA-256 receipt over a canonical capsule and the source,
+target, Task identity, and acceptance time. Stale claims expire, replayed event
+IDs are ignored, and destination routing is explicit.
+
 ## Runtime controls
 
 Provider hooks enforce policy on the computer. Global provider deny always
@@ -57,5 +68,14 @@ background services. The public MCP server can only connect an existing or new
 phone pairing, notify, and ask bounded questions; it cannot reconfigure the
 machine or select a custom relay.
 
+A Grok Bot endpoint is a separate scoped identity. Its one-time invite is
+created only on the iPhone, stored on the relay as ciphertext, redeemed only by
+the trusted `granttap mesh connect` CLI, and written to disk with `0600`
+permissions. Its MCP server exposes only task-scoped Mesh operations bound to
+one credential: every call re-checks endpoint, credential, policy revision,
+expiry, actor, Project scope, and operation, and a revoked or disabled endpoint
+fails closed. Invite creation, actor enablement, Project scope, and revocation
+stay in the iPhone UI and the trusted CLI, never in a model-callable tool.
+
 Relay vulnerabilities should be reported through the
 [GrantTap relay advisory form](https://github.com/sergii-ziborov/granttap-relay/security/advisories/new).

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

@@ -18,6 +18,7 @@ import {
   autoAcceptLevelFor,
   blockedSessionCapability,
   isGatingSkipped,
+  isProviderEnabled,
   loadConfig,
   machineConfigPath,
   shouldAutoAcceptTool,
@@ -48,6 +49,8 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (!isProviderEnabled("claude")) return;
+
   const blocked = blockedSessionCapability(
     input.session_id,
     input.tool_name,
@@ -69,19 +72,6 @@ async function main(): Promise<void> {
   // Claude already granted this chat unconditional tool access. GrantTap's
   // explicit MCP/skill/CLI blocks above still win, but phone approval must not
   // re-prompt a call Claude is intentionally running in bypass mode.
-  // TEMPORARY DIAGNOSTIC: record only permission-related metadata, never the
-  // tool input or any prompt text. Remove once the bypass field name is known.
-  try {
-    const { appendFileSync } = await import("node:fs");
-    appendFileSync("/tmp/granttap-hook-probe.log", JSON.stringify({
-      keys: Object.keys(input),
-      permission_mode: (input as Record<string, unknown>).permission_mode,
-      permissionMode: (input as Record<string, unknown>).permissionMode,
-      tool_name: (input as Record<string, unknown>).tool_name,
-      session_id: String((input as Record<string, unknown>).session_id ?? "").slice(0, 8),
-    }) + "\n");
-  } catch { /* diagnostics must never block a tool call */ }
-
   if (input.permission_mode === "bypassPermissions") return;
 
   // Gating paused, or this session is exempt → abstain (empty output = Claude

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

@@ -18,6 +18,7 @@ import {
   autoAcceptLevelFor,
   blockedSessionCapability,
   isGatingSkipped,
+  isProviderEnabled,
   loadConfig,
   machineConfigPath,
   shouldAutoAcceptTool,
@@ -49,6 +50,8 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (!isProviderEnabled("codex")) return;
+
   const blocked = blockedSessionCapability(
     input.session_id,
     input.tool_name,

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S npx tsx
 /** Deny-only Codex PreToolUse policy for exact per-chat capability switches. */
 import type { HookInput } from "../adapters";
-import { blockedSessionCapability } from "../config";
+import { blockedSessionCapability, isProviderEnabled } from "../config";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -10,6 +10,7 @@ async function readStdin(): Promise<string> {
 }
 
 async function main(): Promise<void> {
+  if (!isProviderEnabled("codex")) return;
   let input: HookInput;
   try {
     input = JSON.parse(await readStdin()) as HookInput;

package/apps/bridge/src/bin/cursor-after-shell.ts

@@ -7,7 +7,7 @@ import {
   resolvedFromOutcome,
   sendApprovalResolved,
 } from "../approval-state";
-import { loadConfig, machineConfigPath } from "../config";
+import { isProviderEnabled, loadConfig, machineConfigPath } from "../config";
 import { cursorRootSessionId } from "../sessions/cursor";
 
 const SHELL_TOOLS = new Set([
@@ -32,6 +32,10 @@ async function readStdin(): Promise<string> {
 }
 
 async function main(): Promise<void> {
+  if (!isProviderEnabled("cursor")) {
+    process.stdout.write("{}\n");
+    return;
+  }
   const raw = await readStdin().catch(() => "");
   let input: {
     conversation_id?: string;

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

@@ -10,6 +10,7 @@ import {
   autoAcceptLevelFor,
   blockedSessionCapability,
   isGatingSkipped,
+  isProviderEnabled,
   loadConfig,
   machineConfigPath,
   shouldAutoAcceptCursorShell,
@@ -38,6 +39,10 @@ async function main(): Promise<void> {
     nativeAsk("GrantTap could not read this shell call; use Cursor approval.");
     return;
   }
+  if (!isProviderEnabled("cursor")) {
+    nativeAsk("GrantTap monitoring for Cursor is disabled; use Cursor approval.");
+    return;
+  }
   const rawSessionId = input.conversation_id ?? input.session_id;
   const sessionId = cursorRootSessionId(rawSessionId) ?? rawSessionId;
   const blocked = blockedSessionCapability(

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

@@ -7,6 +7,7 @@ import { isUnanswered, requestApproval } from "../approval";
 import {
   blockedSessionMcpServer,
   isGatingSkipped,
+  isProviderEnabled,
   loadConfig,
   machineConfigPath,
   shouldAutoAcceptTool,
@@ -40,6 +41,10 @@ async function main(): Promise<void> {
     nativeAsk("GrantTap could not correlate this MCP call; use Cursor approval.");
     return;
   }
+  if (!isProviderEnabled("cursor")) {
+    nativeAsk("GrantTap monitoring for Cursor is disabled; use Cursor approval.");
+    return;
+  }
   const rawSessionId = cursorConversationId(input);
   const sessionId = cursorRootSessionId(rawSessionId) ?? rawSessionId;
   const server = resolveCursorMcpServer(input);

package/apps/bridge/src/bin/mesh-connect.ts

@@ -0,0 +1,27 @@
+import { connectGrokBotInvite } from "../mesh/endpoint";
+
+function inviteArgument(args: string[]): string {
+  if (args.length === 1 && !["--help", "-h"].includes(args[0]!)) return args[0]!;
+  process.stderr.write("Usage: granttap mesh connect <one-time-invite>\n");
+  process.exit(1);
+}
+
+const invite = inviteArgument(process.argv.slice(2));
+void connectGrokBotInvite(invite).then((bundle) => {
+  process.stdout.write([
+    "GrantTap Project Mesh",
+    "",
+    `Grok Bot endpoint  Connected (${bundle.endpoint.displayName})`,
+    `Actors             ${bundle.actors.length}`,
+    `Allowed projects   ${bundle.credential.projectIds.length}`,
+    "",
+    "Configure Grok Bot to run: granttap internal mesh-mcp",
+    "The scoped MCP server cannot create invites, change relay, or expand Project access.",
+    "",
+  ].join("\n"));
+}).catch((error: unknown) => {
+  process.stderr.write(`[granttap] Grok Bot connection failed: ${
+    error instanceof Error ? error.message : String(error)
+  }\n`);
+  process.exitCode = 1;
+});

package/apps/bridge/src/bin/setup.ts

@@ -79,6 +79,7 @@ async function main(): Promise<void> {
       ? codexHook.status === "manual" ? "Needs attention" : "Needs hook trust"
       : "Not installed"}`,
     `Cursor              ${before.cursor.installed ? `Beta · ${cursorReady ? "Authorize in Cursor" : "Needs repair"}` : "Not installed"}`,
+    `Grok Build          ${installed.has("grok") ? "Ready" : "Not installed"}`,
     "",
     paired && installed.has("codex")
       ? `Next: ${CODEX_TRUST_INSTRUCTION}`

package/apps/bridge/src/config/runtime.ts

@@ -1,5 +1,9 @@
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import type { AgentAccess } from "../../../../packages/protocol/schema";
+import type {
+  AgentAccess,
+  CodingAgent,
+  ProviderRuntimeSettings,
+} from "../../../../packages/protocol/schema";
 import {
   classifyAction,
   isAutoAcceptLevel,
@@ -19,6 +23,8 @@ export type RuntimeConfig = {
   sessionMcpDisabled: Record<string, string[]>;
   sessionSkillsDisabled: Record<string, string[]>;
   sessionShellDisabled: string[];
+  providerSettings: ProviderRuntimeSettings;
+  meshEnabled: boolean;
 };
 
 const DEFAULT_RUNTIME: RuntimeConfig = {
@@ -31,8 +37,23 @@ const DEFAULT_RUNTIME: RuntimeConfig = {
   sessionMcpDisabled: {},
   sessionSkillsDisabled: {},
   sessionShellDisabled: [],
+  providerSettings: { claude: true, codex: true, cursor: true, grok: true },
+  meshEnabled: true,
 };
 
+function parseProviderSettings(raw: unknown): ProviderRuntimeSettings {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ...DEFAULT_RUNTIME.providerSettings };
+  }
+  const value = raw as Record<string, unknown>;
+  return {
+    claude: value.claude !== false,
+    codex: value.codex !== false,
+    cursor: value.cursor !== false,
+    grok: value.grok !== false,
+  };
+}
+
 export function boundedIdentifier(raw: unknown, maxLength: number): string | null {
   if (typeof raw !== "string") return null;
   const value = raw.trim();
@@ -96,6 +117,8 @@ export function loadRuntimeConfig(): RuntimeConfig {
               .filter((sessionId): sessionId is string => sessionId != null),
           )]
         : [],
+      providerSettings: parseProviderSettings(raw.providerSettings),
+      meshEnabled: raw.meshEnabled !== false,
     };
   } catch {
     return {
@@ -105,10 +128,20 @@ export function loadRuntimeConfig(): RuntimeConfig {
       sessionMcpDisabled: {},
       sessionSkillsDisabled: {},
       sessionShellDisabled: [],
+      providerSettings: { ...DEFAULT_RUNTIME.providerSettings },
+      meshEnabled: true,
     };
   }
 }
 
+export function isProviderEnabled(provider: CodingAgent): boolean {
+  return loadRuntimeConfig().providerSettings[provider];
+}
+
+export function isMeshEnabled(): boolean {
+  return loadRuntimeConfig().meshEnabled;
+}
+
 export function saveRuntimeConfig(cfg: Partial<RuntimeConfig>): void {
   mkdirSync(configDir(), { recursive: true });
   const merged: RuntimeConfig = { ...loadRuntimeConfig(), ...cfg };

package/apps/bridge/src/install.ts

@@ -22,6 +22,7 @@ import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
+import type { CodingAgent } from "../../../packages/protocol/schema";
 import { configDir } from "./config";
 
 const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
@@ -54,7 +55,7 @@ export const CODEX_TRUST_INSTRUCTION =
   "Open /hooks in Codex, review and trust both GrantTap hooks, then restart Codex.";
 
 export type AgentIntegrationStatus = {
-  agent: "codex" | "claude";
+  agent: CodingAgent;
   installed: boolean;
   hookConfigured: boolean;
 };
@@ -242,9 +243,16 @@ export function inspectCursorIntegration(): CursorIntegrationStatus {
 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 cursor = process.env.GRANTTAP_CURSOR_AGENT_BIN ?? "cursor-agent";
+  const grok = process.env.GRANTTAP_GROK_BIN ?? "grok";
+  const cursorStatus = inspectCursorIntegration();
   return [
     { agent: "codex", installed: executableAvailable(codex), hookConfigured: codexHookConfigured() },
     { agent: "claude", installed: executableAvailable(claude), hookConfigured: claudeHookConfigured() },
+    { agent: "cursor", installed: executableAvailable(cursor), hookConfigured: cursorStatus.hookConfigured },
+    // 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 },
   ];
 }
 

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

@@ -0,0 +1,25 @@
+# Project Mesh runtime
+
+This module links discovered native sessions to stable Project and Task
+identities, persists bounded structured events, tracks expiring resource
+claims and dependencies, and executes authorized task handoffs.
+
+`runtime.ts` is the public runtime entry point. `catalog.ts` derives repository
+identity without replacing provider-native session discovery. `store.ts`
+deduplicates replayed events and expires stale claims. `capsule.ts` reads only
+explicit git and task facts; transcripts and hidden reasoning are never copied.
+`worktree.ts` creates a separate target branch/worktree before Claude Code or
+Codex is started. The provider abstraction already admits Cursor and Grok Build
+without changing the core contract, while their unsupported phase-one start
+paths fail closed.
+
+The read-only MCP resource `granttap://mesh/current` exposes compact local state
+to an agent. Structured events use the existing `notify` tool so the public MCP
+tool allowlist remains exactly `connect`, `notify`, `ask_yes_no`, and `ask`.
+Setup and global provider configuration remain CLI-only.
+
+Every event is schema-bounded and sent under an independent task key; snapshots
+use an independent project key. Resource claims are advisory, expire without a
+heartbeat, and a colliding claim is rejected before it is recorded. The agent
+may choose other work or ask the current owner; the conflict reaches the human
+only after explicit `needsUser` escalation.

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

@@ -0,0 +1,19 @@
+import type { MeshEventType } from "../../../../packages/protocol/schema";
+
+type AttentionFacts = {
+  category?: unknown;
+  resolved?: unknown;
+  needsUser?: unknown;
+  failed?: unknown;
+};
+
+/** Only deterministic, product-approved reasons may enter the human inbox. */
+export function classifyHumanAttention(type: MeshEventType, facts: AttentionFacts): boolean {
+  if (type === "AGENT_QUESTION") {
+    return ["product", "business", "security", "destructive"].includes(String(facts.category));
+  }
+  if (type === "CONFLICT") return facts.resolved !== true && facts.needsUser === true;
+  if (type === "TASK_BLOCKED") return facts.needsUser === true;
+  if (type === "HANDOFF_REJECTED") return facts.failed === true;
+  return false;
+}

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

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import {
+  TaskCapsule,
+  type MeshHandoffPrepare,
+  type SessionInfo,
+  type TaskCapsule as CapsuleValue,
+} from "../../../../packages/protocol/schema";
+import type { MeshStore } from "./store";
+
+function git(cwd: string, args: string[]): string | undefined {
+  try {
+    return execFileSync("git", ["-C", cwd, ...args], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 3_000,
+      maxBuffer: 512 * 1_024,
+    }).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function gitRaw(cwd: string, args: string[]): string | undefined {
+  try {
+    return execFileSync("git", ["-C", cwd, ...args], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 3_000,
+      maxBuffer: 512 * 1_024,
+    }) || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function changedFiles(cwd: string): string[] {
+  const status = gitRaw(cwd, ["status", "--porcelain=v1", "-z"]);
+  if (!status) return [];
+  const files = status.split("\0").flatMap((row) => {
+    const value = row.length > 3 ? row.slice(3).trim() : "";
+    return value ? [value.split(" -> ").at(-1)!] : [];
+  });
+  return [...new Set(files)].slice(0, 64);
+}
+
+function dirtyDiffHash(cwd: string): string | undefined {
+  const diff = git(cwd, ["diff", "--binary", "HEAD"]);
+  return diff ? createHash("sha256").update(diff).digest("hex") : undefined;
+}
+
+export function buildTaskCapsule(
+  store: MeshStore,
+  session: SessionInfo,
+  request: MeshHandoffPrepare,
+  computerId: string,
+): CapsuleValue | undefined {
+  const cwd = session.worktree ?? session.cwd;
+  const snapshot = store.snapshot(request.projectId);
+  const task = snapshot?.tasks.find((item) => item.taskId === request.taskId);
+  const project = snapshot?.project;
+  if (!cwd || !task || !project || session.taskId !== request.taskId) return undefined;
+  const head = git(cwd, ["rev-parse", "HEAD"]);
+  if (!head) return undefined;
+  const capsule = {
+    taskId: request.taskId,
+    goal: task.goal,
+    currentStatus: session.summary ?? session.title ?? task.title,
+    sourceProvider: session.agent,
+    sourceComputer: computerId,
+    targetProvider: request.targetProvider,
+    targetActorId: request.targetActorId,
+    targetComputer: request.targetComputer,
+    repository: project.canonicalRepositoryId,
+    baseSha: head,
+    branch: session.branch ?? git(cwd, ["branch", "--show-current"]),
+    latestCommit: head,
+    dirtyDiffHash: dirtyDiffHash(cwd),
+    filesChanged: changedFiles(cwd),
+    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."],
+    importantDecisions: [],
+    createdAt: Date.now(),
+  };
+  const parsed = TaskCapsule.safeParse(capsule);
+  return parsed.success ? parsed.data : undefined;
+}

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

@@ -0,0 +1,105 @@
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+import type {
+  MeshProvider,
+  MeshTask,
+  Project,
+  SessionInfo,
+  TaskState,
+} from "../../../../packages/protocol/schema";
+import { canonicalRepositoryIdentity, projectIdentity, taskIdentity } from "./identity";
+import type { MeshStore } from "./store";
+
+export type RepositoryFacts = {
+  root: string;
+  canonicalRepositoryId: string;
+  baseRemote?: string;
+  worktree?: string;
+};
+
+const repositoryCache = new Map<string, RepositoryFacts>();
+
+function git(cwd: string, args: string[]): string | undefined {
+  try {
+    return execFileSync("git", ["-C", cwd, ...args], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2_000,
+    }).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function inspectRepository(cwd: string): RepositoryFacts {
+  const cached = repositoryCache.get(cwd);
+  if (cached) return cached;
+  const root = git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
+  const baseRemote = git(root, ["remote", "get-url", "origin"]);
+  const facts = {
+    root,
+    baseRemote,
+    canonicalRepositoryId: canonicalRepositoryIdentity(baseRemote, root),
+    worktree: git(root, ["rev-parse", "--show-toplevel"]),
+  };
+  repositoryCache.set(cwd, facts);
+  return facts;
+}
+
+function provider(value: string): MeshProvider | undefined {
+  return ["claude", "codex", "cursor", "grok"].includes(value)
+    ? value as MeshProvider
+    : undefined;
+}
+
+function taskState(session: SessionInfo): TaskState {
+  if (session.state === "waiting") return "needs_user";
+  if (session.state === "working") return "working";
+  return "planned";
+}
+
+export function linkSessionsToProjects(
+  store: MeshStore,
+  sessions: SessionInfo[],
+  computerId: string,
+  inspect: (cwd: string) => RepositoryFacts = inspectRepository,
+): SessionInfo[] {
+  return sessions.map((session) => {
+    const agent = provider(session.agent);
+    const cwd = session.cwd?.trim();
+    if (!agent || !cwd) return session;
+    const repository = inspect(cwd);
+    const projectId = projectIdentity(repository.canonicalRepositoryId);
+    const project: Project = {
+      projectId,
+      name: basename(repository.root) || "Project",
+      repositoryRoot: repository.root,
+      canonicalRepositoryId: repository.canonicalRepositoryId,
+      baseRemote: repository.baseRemote,
+      createdAt: session.startedAt,
+    };
+    store.upsertProject(project);
+    const knownTask = store.taskForExecution(computerId, agent, session.sessionId);
+    const taskId = knownTask ?? taskIdentity(projectId, agent, session.sessionId);
+    const task: MeshTask = {
+      taskId,
+      projectId,
+      title: (session.title ?? session.summary ?? `${agent} task`).slice(0, 160),
+      goal: (session.summary ?? session.title ?? "Continue this coding task").slice(0, 1_000),
+      state: taskState(session),
+      ownerSessionId: session.sessionId,
+      createdAt: session.startedAt,
+      updatedAt: session.lastActivityAt,
+    };
+    store.upsertTask(task);
+    store.linkExecution({
+      taskId,
+      sessionId: session.sessionId,
+      provider: agent,
+      computerId,
+      workspace: cwd,
+      branch: session.branch,
+      worktree: repository.worktree,
+      startedAt: session.startedAt,
+    });
+    return { ...session, projectId, taskId, computerId, worktree: repository.worktree };
+  });
+}