granttap-mcp 0.8.70 → 0.8.72

package/apps/bridge/src/cloud-runners/README.md

@@ -0,0 +1,48 @@
+# Cloud runners
+
+Public entry point: [`index.ts`](index.ts). A Task can be sent from the phone or
+the Mac app to a provider's own cloud runner, started by the computer that holds
+the Task with the CLI installed there:
+
+| Runner | Command the computer runs | What comes back |
+| --- | --- | --- |
+| Claude Code cloud session | `claude --cloud <capsule> [--name <title>] [--ref <branch>] [--model <m>] [--effort <e>]` | `Session ID:` and `View:` link |
+| Codex Cloud task | `codex cloud exec --env <environment> [--branch <branch>] <capsule>` | the `…/codex/tasks/<id>` link or `task_…` id |
+
+Both run with stdin closed and without a terminal. Claude Code then creates the
+session, prints its id and link, and exits; it never waits for the cloud turn.
+Where Claude Code would need the keyboard (its message *No cloud session was
+created or opened: it would open in this terminal…*), the CLI's own words are
+returned and nothing is started. Codex requires an environment: the person may
+name it; otherwise `codex cloud list --json` is read once and an environment is
+used only when exactly one recent task of this repository's `owner/repo` or
+`repo` label names it. GrantTap never guesses one.
+
+## Availability
+
+`withCloudRunners` marks the `claude`/`codex` integration rows with `cloud: true`
+only when that CLI is installed and its own help documents the headless start
+(`--cloud [description…` for Claude Code, `Usage: codex cloud exec … --env
+<ENV_ID>` for Codex). The help is read in the background, cached ten minutes per
+binary path, and a status cycle never waits for it. Cursor and Grok Build have no
+cloud runner here.
+
+## What the Mesh records
+
+[`mesh/runtime/cloud-handoff`](../mesh/runtime/cloud-handoff/index.ts) requires
+the target computer to be the one holding the Task, pushes the capsule's branch
+when the person asked (never by force) or confirms a remote-tracking branch
+already contains the commit, and otherwise refuses with the reason. Uncommitted
+work stays behind and the prompt says so, exactly like a computer transfer warns.
+
+A started run becomes an execution of the Task with `external: { runner, url }`
+and the CLI's id as its session id, plus a `TASK_PROGRESS` event naming the link.
+GrantTap cannot observe a cloud run, so it reports no progress, state or usage
+for it, and the vanished-session sweep never closes it. The local chat keeps the
+Task while it is open.
+
+The first message is the Task Capsule: goal, status, repository, branch and
+commit, the person's comment, decisions and remaining work, bounded to 12,000
+characters. The visible conversation archive is not uploaded.
+
+Tests: [`tests/`](tests/). Apache License 2.0, see [LICENSE](../../../../LICENSE).

package/apps/bridge/src/cloud-runners/capability.ts

@@ -0,0 +1,53 @@
+import { execFile } from "node:child_process";
+import { homedir } from "node:os";
+
+export type CloudRunnerSupport = { claude: boolean; codex: boolean };
+export type CloudBinaries = { claude: string; codex: string };
+type Probe = (binary: string, args: string[]) => Promise<string>;
+
+const REFRESH_MS = 10 * 60_000;
+
+/** Claude Code documents `--cloud [description|session_id|url]` in its help. */
+export function claudeSupportsCloud(help: string): boolean {
+  return /^\s*--cloud \[description/m.test(help);
+}
+
+/** Codex documents `codex cloud exec … --env <ENV_ID>` for a non-interactive submission. */
+export function codexSupportsCloud(help: string): boolean {
+  return /Usage: codex cloud exec\b/.test(help) && /--env <ENV_ID>/.test(help);
+}
+
+function readHelp(binary: string, args: string[]): Promise<string> {
+  return new Promise(resolve => execFile(binary, args,
+    { cwd: homedir(), timeout: 10_000, maxBuffer: 512_000, windowsHide: true },
+    (error, stdout) => resolve(error ? "" : stdout)));
+}
+
+/**
+ * Help text is read in the background and kept ten minutes per binary, so a
+ * status cycle never waits on a CLI and an updated CLI is asked again.
+ */
+export function createCloudSupportCache(probe: Probe = readHelp, clock = Date.now) {
+  const known = new Map<string, { at: number; supported: boolean }>();
+  const running = new Map<string, Promise<void>>();
+  const ask = (key: string, binary: string, args: string[], test: (help: string) => boolean): boolean => {
+    const entry = known.get(key);
+    if ((!entry || clock() - entry.at > REFRESH_MS) && !running.has(key)) {
+      running.set(key, probe(binary, args).then(help => { known.set(key, { at: clock(), supported: test(help) }); },
+        () => { known.set(key, { at: clock(), supported: false }); })
+        .finally(() => running.delete(key)));
+    }
+    return entry?.supported ?? false;
+  };
+  return {
+    current(binaries: CloudBinaries): CloudRunnerSupport {
+      return {
+        claude: ask(`claude\u001f${binaries.claude}`, binaries.claude, ["--help"], claudeSupportsCloud),
+        codex: ask(`codex\u001f${binaries.codex}`, binaries.codex, ["cloud", "exec", "--help"], codexSupportsCloud),
+      };
+    },
+    async settled(): Promise<void> {
+      await Promise.all([...running.values()]);
+    },
+  };
+}

package/apps/bridge/src/cloud-runners/claude.ts

@@ -0,0 +1,39 @@
+import { providerEffortArgs } from "../reply/process/provider-effort";
+
+const REFERENCE = /^(?:cse|session)_[A-Za-z0-9_-]{1,120}$/;
+const LINK = /^https:\/\/\S{1,1000}$/;
+
+export type CloudReference = { reference: string; url?: string };
+
+/**
+ * `claude --cloud <description>` without a terminal creates the session,
+ * prints its id and link, and exits; it never waits for the cloud turn.
+ */
+export function claudeCloudArgs(input: { prompt: string; branch?: string; title?: string;
+  model?: string; effort?: string }): string[] {
+  return ["--cloud", input.prompt,
+    ...(input.title ? ["--name", input.title.slice(0, 80)] : []),
+    ...(input.branch ? ["--ref", input.branch] : []),
+    ...(input.model ? ["--model", input.model] : []),
+    ...providerEffortArgs("claude", input.effort)];
+}
+
+function fromJson(stdout: string): CloudReference | undefined {
+  try {
+    const value = JSON.parse(stdout.trim()) as { ok?: unknown; session_id?: unknown; url?: unknown };
+    if (value.ok !== true || typeof value.session_id !== "string" || !REFERENCE.test(value.session_id)) return undefined;
+    return { reference: value.session_id,
+      ...(typeof value.url === "string" && LINK.test(value.url) ? { url: value.url } : {}) };
+  } catch { return undefined; }
+}
+
+/** Only the session id and link the CLI printed; anything else is not a cloud run. */
+export function parseClaudeCloud(stdout: string): CloudReference | undefined {
+  const json = fromJson(stdout);
+  if (json) return json;
+  const id = /^Session ID:\s*(\S+)\s*$/m.exec(stdout)?.[1]
+    ?? /^Resume with: claude --teleport (\S+)\s*$/m.exec(stdout)?.[1];
+  if (!id || !REFERENCE.test(id)) return undefined;
+  const url = /^View:\s*(\S+)\s*$/m.exec(stdout)?.[1];
+  return { reference: id, ...(url && LINK.test(url) ? { url } : {}) };
+}

package/apps/bridge/src/cloud-runners/codex.ts

@@ -0,0 +1,50 @@
+import type { CloudReference } from "./claude";
+
+const TASK = /^task_[a-z]_[A-Za-z0-9]{1,120}$/;
+
+/** `codex cloud exec` submits one task to an environment without the TUI. */
+export function codexCloudArgs(input: { prompt: string; environment: string; branch?: string }): string[] {
+  return ["cloud", "exec", "--env", input.environment,
+    ...(input.branch ? ["--branch", input.branch] : []), input.prompt];
+}
+
+/** The task link or id Codex printed; nothing else counts as a submitted task. */
+export function parseCodexCloud(stdout: string): CloudReference | undefined {
+  const link = /(https:\/\/[^\s/]+\/codex\/tasks\/([A-Za-z0-9_-]{1,128}))/.exec(stdout);
+  if (link && TASK.test(link[2]!)) return { reference: link[2]!, url: link[1]! };
+  const id = /\b(task_[a-z]_[A-Za-z0-9]{1,120})\b/.exec(stdout)?.[1];
+  return id ? { reference: id } : undefined;
+}
+
+/** `owner/repo` and `repo`, lower-cased, from any GitHub-style repository id. */
+function repositoryNames(repository: string): string[] {
+  const path = repository.trim().replace(/\.git$/i, "").replace(/^[a-z]+:\/\//i, "")
+    .replace(/^[^@/]+@/, "").replace(/^[^/:]+[/:]/, "").toLowerCase();
+  const parts = path.split("/").filter(Boolean);
+  return parts.length >= 2 ? [parts.slice(-2).join("/"), parts.at(-1)!] : parts;
+}
+
+function rows(value: unknown): Array<Record<string, unknown>> {
+  const list = Array.isArray(value) ? value
+    : (value as { tasks?: unknown; items?: unknown; data?: unknown } | null)?.tasks
+      ?? (value as { items?: unknown } | null)?.items ?? (value as { data?: unknown } | null)?.data;
+  return Array.isArray(list) ? list.filter((row): row is Record<string, unknown> => !!row && typeof row === "object") : [];
+}
+
+/**
+ * The environment this repository's recent Codex Cloud tasks ran in, when
+ * exactly one is labelled with the repository's name. Nothing is guessed.
+ */
+export function environmentForRepository(listJson: string, repository: string): string | undefined {
+  let parsed: unknown;
+  try { parsed = JSON.parse(listJson); } catch { return undefined; }
+  const names = new Set(repositoryNames(repository));
+  const matches = new Set<string>();
+  for (const row of rows(parsed)) {
+    const label = row.environment_label ?? row.environmentLabel;
+    if (typeof label !== "string" || !names.has(label.trim().toLowerCase())) continue;
+    const id = row.environment_id ?? row.environmentId;
+    matches.add(typeof id === "string" && id.trim() ? id.trim() : label.trim());
+  }
+  return matches.size === 1 ? [...matches][0] : undefined;
+}

package/apps/bridge/src/cloud-runners/index.ts

@@ -0,0 +1,28 @@
+/** Provider cloud runners a computer can start for a Task: Claude Code cloud sessions and Codex Cloud tasks. */
+import type { AgentIntegrationStatus } from "../../../../packages/protocol/schema";
+import { resolveClaudeBinary } from "../providers/claude-bin";
+import { resolveCodexBinary } from "../providers/codex-bin";
+import { createCloudSupportCache, type CloudBinaries, type CloudRunnerSupport } from "./capability";
+import { launchCloudRunner, runCloudCommand, type CloudLaunchInput, type CloudLaunchResult } from "./launch";
+
+export type { CloudLaunchInput, CloudLaunchResult } from "./launch";
+export type { CloudRunnerSupport } from "./capability";
+export { cloudTaskPrompt } from "./launch";
+
+const support = createCloudSupportCache();
+
+function binaries(): CloudBinaries {
+  return { claude: resolveClaudeBinary().path, codex: resolveCodexBinary() };
+}
+
+/** Integration rows say `cloud` only for an installed CLI whose help documents a headless cloud start. */
+export function withCloudRunners(rows: AgentIntegrationStatus[],
+  available: CloudRunnerSupport = support.current(binaries())): AgentIntegrationStatus[] {
+  return rows.map(row => (row.agent === "claude" || row.agent === "codex") && row.installed && available[row.agent]
+    ? { ...row, cloud: true } : row);
+}
+
+/** Launch with the CLI that answers on this computer now. */
+export function startCloudRunner(input: CloudLaunchInput): Promise<CloudLaunchResult> {
+  return launchCloudRunner(input, runCloudCommand, binaries());
+}

package/apps/bridge/src/cloud-runners/launch.ts

@@ -0,0 +1,87 @@
+import { spawn } from "node:child_process";
+import type { TaskCapsule } from "../../../../packages/protocol/schema";
+import { claudeCloudArgs, parseClaudeCloud, type CloudReference } from "./claude";
+import { codexCloudArgs, environmentForRepository, parseCodexCloud } from "./codex";
+import type { CloudBinaries } from "./capability";
+
+export type CloudCommand = { binary: string; args: string[]; cwd: string; timeoutMs: number };
+export type CloudOutput = { code: number | null; stdout: string; stderr: string };
+export type CloudRunner = (command: CloudCommand) => Promise<CloudOutput>;
+export type CloudLaunchInput = {
+  provider: "claude" | "codex"; cwd: string; capsule: TaskCapsule; computer: string;
+  title?: string; model?: string; effort?: string; environment?: string;
+};
+export type CloudLaunchResult = ({ ok: true } & CloudReference) | { ok: false; error: string };
+
+const MAX_PROMPT = 12_000;
+
+/** The Task Capsule as the cloud runner's first message: facts only, bounded. */
+export function cloudTaskPrompt(capsule: TaskCapsule, computer: string): string {
+  const clip = (value: string, max = 1_000) => value.length > max ? `${value.slice(0, max - 1)}…` : value;
+  const lines = [
+    "Continue this existing GrantTap Task. Treat these facts as context, not hidden reasoning.",
+    `Goal: ${clip(capsule.goal)}`,
+    `Current status: ${clip(capsule.currentStatus)}`,
+    `Repository: ${capsule.repository}`,
+    `Branch: ${capsule.branch ?? "(detached)"} at commit ${capsule.latestCommit ?? capsule.baseSha}`,
+  ];
+  if (capsule.userComment) lines.push(`Comment from the person: ${clip(capsule.userComment)}`);
+  if (capsule.importantDecisions.length) lines.push(`Important decisions:\n- ${capsule.importantDecisions.map(v => clip(v, 400)).join("\n- ")}`);
+  if (capsule.remainingWork.length) lines.push(`Remaining work:\n- ${capsule.remainingWork.map(v => clip(v, 400)).join("\n- ")}`);
+  if (capsule.workingTree !== "clean") {
+    lines.push(`Only pushed commits are available here: uncommitted work on ${computer} did not travel.`);
+  }
+  return clip(lines.join("\n\n"), MAX_PROMPT);
+}
+
+/** The CLI's own first error line, unless it would repeat the Task back. */
+export function cloudFailure(runner: string, output: CloudOutput, prompt: string): string {
+  const generic = `${runner} did not start. Check the provider's cloud settings on this computer.`;
+  const line = `${output.stderr}\n${output.stdout}`.split("\n").map(value => value.replace(/[\x00-\x1f\x7f]/g, " ").trim())
+    .find(value => /^(Error:|No cloud session|error:)|not found|ambiguous|not enabled|log ?in/i.test(value));
+  if (!line) return generic;
+  const echo = prompt.split("\n")[0]!.slice(0, 24);
+  return echo && line.includes(echo) ? generic : `${runner} did not start: ${line.slice(0, 300)}`;
+}
+
+/** Stdin is closed so the CLI never waits for a terminal or reads piped input. */
+export const runCloudCommand: CloudRunner = (command) => new Promise(resolve => {
+  const child = spawn(command.binary, command.args, { cwd: command.cwd, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+  let stdout = "";
+  let stderr = "";
+  const timer = setTimeout(() => child.kill("SIGTERM"), command.timeoutMs);
+  child.stdout.on("data", chunk => { if (stdout.length < 64_000) stdout += chunk; });
+  child.stderr.on("data", chunk => { if (stderr.length < 16_000) stderr += chunk; });
+  child.on("error", () => { clearTimeout(timer); resolve({ code: null, stdout, stderr }); });
+  child.on("close", code => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
+});
+
+async function codexEnvironment(input: CloudLaunchInput, run: CloudRunner, binary: string): Promise<string | undefined> {
+  if (input.environment) return input.environment;
+  const listed = await run({ binary, args: ["cloud", "list", "--json", "--limit", "20"], cwd: input.cwd, timeoutMs: 30_000 });
+  return listed.code === 0 ? environmentForRepository(listed.stdout, input.capsule.repository) : undefined;
+}
+
+/** Start one provider cloud run; success only when the CLI named what it created. */
+export async function launchCloudRunner(input: CloudLaunchInput, run: CloudRunner, binaries: CloudBinaries)
+  : Promise<CloudLaunchResult> {
+  const prompt = cloudTaskPrompt(input.capsule, input.computer);
+  const runner = input.provider === "claude" ? "Claude cloud" : "Codex Cloud";
+  let args: string[];
+  if (input.provider === "claude") {
+    args = claudeCloudArgs({ prompt, branch: input.capsule.branch, title: input.title,
+      model: input.model, effort: input.effort });
+  } else {
+    const environment = await codexEnvironment(input, run, binaries.codex);
+    if (!environment) {
+      return { ok: false, error: `Name the Codex Cloud environment for ${input.capsule.repository}: `
+        + `no recent Codex Cloud task names one. \`codex cloud\` on ${input.computer} lists them.` };
+    }
+    args = codexCloudArgs({ prompt, environment, branch: input.capsule.branch });
+  }
+  const output = await run({ binary: binaries[input.provider], args, cwd: input.cwd, timeoutMs: 180_000 });
+  const created = output.code === 0
+    ? (input.provider === "claude" ? parseClaudeCloud(output.stdout) : parseCodexCloud(output.stdout))
+    : undefined;
+  return created ? { ok: true, ...created } : { ok: false, error: cloudFailure(runner, output, prompt) };
+}

package/apps/bridge/src/install/inspect.ts

@@ -21,6 +21,7 @@ import {
 } from "node:fs";
 import { resolveClaudeBinary } from "../providers/claude-bin";
 import { resolveCodexBinary } from "../providers/codex-bin";
+import { resolveGrokBinary } from "../providers/grok-bin";
 import { describeCommand, inspectTools, updatingTools } from "../tools/updater";
 import { resolveCursorAgentBin } from "../reply/process/cursor-agent-bin";
 import { homedir } from "node:os";
@@ -205,7 +206,7 @@ export function inspectAgentIntegrations(): AgentIntegrationStatus[] {
   const codex = resolveCodexBinary();
   const claude = resolveClaudeBinary().path;
   const cursor = process.env.GRANTTAP_CURSOR_AGENT_BIN ?? resolveCursorAgentBin();
-  const grok = process.env.GRANTTAP_GROK_BIN ?? "grok";
+  const grok = resolveGrokBinary();
   const cursorStatus = inspectCursorIntegration();
   const tools = new Map(inspectTools().map((tool) => [tool.agent, tool]));
   const updating = new Set(updatingTools());

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

@@ -41,6 +41,12 @@ 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
 computer is taken up by `prepare` itself, since the request would only come
 back as a duplicate of an event the store already holds.
+A prepare request with `cloud` goes to `runtime/cloud-handoff`: the computer
+holding the Task pushes (or finds pushed, via `remoteHasCommit`) the capsule's
+branch and starts a Claude Code cloud session or Codex Cloud task with the
+installed CLI. The run is recorded as an `external` execution with the CLI's
+link and is never swept, owned or given progress; see
+[cloud runners](../cloud-runners/README.md).
 
 `convergence.ts` and `task-state.ts` keep one Task identity while snapshots and
 events arrive late, twice, and from several computers. Every writer raises the

package/apps/bridge/src/mesh/local-remote/remote.ts

@@ -53,3 +53,16 @@ export function fetchRevision(repository: string, revision: string, branch?: str
   }
   return repositoryHasCommit(repository, revision);
 }
+
+/**
+ * Whether a remote-tracking branch already holds the commit, as this checkout
+ * last saw its remote. A provider cloud runner can only fetch what is pushed.
+ */
+export function remoteHasCommit(cwd: string, revision: string): boolean {
+  if (!/^[0-9a-f]{7,64}$/i.test(revision)) return false;
+  try {
+    return git(cwd, ["branch", "-r", "--contains", revision], 10_000).length > 0;
+  } catch {
+    return false;
+  }
+}

package/apps/bridge/src/mesh/runtime/cloud-handoff/index.ts

@@ -0,0 +1,73 @@
+/**
+ * A Task sent to a provider cloud runner through the computer that holds it.
+ *
+ * The computer pushes (or finds already pushed) the branch the capsule names,
+ * starts the run with the installed CLI, and records it as an external
+ * execution of the Task with the link the CLI printed. GrantTap cannot see a
+ * cloud run's progress, so it reports none.
+ */
+import type { RelayClient } from "../../../../../../packages/core/relay-client";
+import type { MeshEvent, MeshHandoffPrepare, SessionInfo, TaskCapsule } from "../../../../../../packages/protocol/schema";
+import { startCloudRunner } from "../../../cloud-runners";
+import { remoteHasCommit } from "../../local-remote/remote";
+import type { MeshRuntimeDependencies } from "../dependencies";
+import { composeMeshSnapshot } from "../snapshot/compose";
+
+type Block = (client: RelayClient, request: MeshHandoffPrepare, reason: string) => Promise<void>;
+const DAY = 24 * 60 * 60_000;
+
+/** The pushed revision the cloud runner will fetch, or why it cannot. */
+function publishedRevision(deps: MeshRuntimeDependencies, request: MeshHandoffPrepare, cwd: string,
+  capsule: TaskCapsule): string | undefined {
+  const revision = capsule.latestCommit ?? capsule.baseSha;
+  if (request.push) {
+    const pushed = deps.push(cwd, capsule.branch);
+    return pushed.ok ? undefined : pushed.error;
+  }
+  if ((deps.remoteHasCommit ?? remoteHasCommit)(cwd, revision)) return undefined;
+  return `The cloud runner fetches ${capsule.branch ?? "the branch"} from the repository's remote, which does not `
+    + `have ${revision.slice(0, 12)} yet. Turn on pushing the branch, or push it yourself.`;
+}
+
+function startedEvent(deps: MeshRuntimeDependencies, request: MeshHandoffPrepare, summary: string): MeshEvent {
+  const createdAt = deps.now();
+  return { type: "mesh.event", sessionId: request.taskId, eventId: deps.eventId(), projectId: request.projectId,
+    taskId: request.taskId, sourceSessionId: request.sessionId, eventType: "TASK_PROGRESS", createdAt,
+    expiresAt: createdAt + DAY, payload: { summary: summary.slice(0, 1_000) } };
+}
+
+export async function prepareCloudHandoff(input: {
+  deps: MeshRuntimeDependencies; block: Block; client: RelayClient;
+  request: MeshHandoffPrepare; session: SessionInfo; capsule: TaskCapsule;
+}): Promise<boolean> {
+  const { deps, block, client, request, session, capsule } = input;
+  const provider = request.targetProvider;
+  const cwd = session.worktree ?? session.cwd;
+  if ((provider !== "claude" && provider !== "codex") || request.targetComputer !== deps.computer() || !cwd) {
+    await block(client, request, "A cloud runner starts from the computer that holds this Task. Choose the runner under that computer.");
+    return false;
+  }
+  const unpublished = publishedRevision(deps, request, cwd, capsule);
+  if (unpublished) {
+    await block(client, request, unpublished);
+    return false;
+  }
+  const launched = await (deps.launchCloud ?? startCloudRunner)({ provider, cwd, capsule, computer: deps.computer(),
+    title: session.title, model: request.targetModel, effort: request.cloud?.effort, environment: request.cloud?.environment });
+  if (!launched.ok) {
+    await block(client, request, launched.error);
+    return false;
+  }
+  const store = deps.store();
+  store.linkExecution({ taskId: request.taskId, sessionId: launched.reference, provider, computerId: deps.computer(),
+    workspace: cwd, repositoryId: capsule.repository, branch: capsule.branch, startedAt: deps.now(),
+    external: { runner: provider === "claude" ? "claude_cloud" : "codex_cloud", ...(launched.url ? { url: launched.url } : {}) } });
+  const name = provider === "claude" ? "Claude cloud session" : "Codex Cloud task";
+  const event = startedEvent(deps, request, `${name} started via ${deps.computer()}. GrantTap cannot follow its progress`
+    + (launched.url ? `: ${launched.url}` : `; its id is ${launched.reference}.`));
+  store.acceptEvent(event);
+  await deps.send(client, event, { ttlMs: DAY, wake: true });
+  const snapshot = composeMeshSnapshot(deps, request.projectId);
+  if (snapshot) await deps.send(client, snapshot, { ttlMs: 60 * 60_000 });
+  return true;
+}

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

@@ -8,6 +8,7 @@ import type {
   TaskCapsule,
 } from "../../../../../packages/protocol/schema";
 import type { createCodexSession, deliverToSession } from "../../reply";
+import type { CloudLaunchInput, CloudLaunchResult } from "../../cloud-runners";
 import type { MeshStore } from "../store";
 import type { createHandoffWorktree } from "./worktree";
 
@@ -48,4 +49,8 @@ export type MeshRuntimeDependencies = {
   push: (cwd: string, branch: string | undefined) => { ok: true; remote: string } | { ok: false; error: string };
   /** Bring a commit the capsule names to this checkout; whether it is here now. */
   fetch: (repository: string, revision: string, branch?: string) => boolean;
+  /** Whether the checkout's remote already has a commit a cloud runner must fetch. */
+  remoteHasCommit?: (cwd: string, revision: string) => boolean;
+  /** Start a provider cloud run with the installed CLI. */
+  launchCloud?: (input: CloudLaunchInput) => Promise<CloudLaunchResult>;
 };

package/apps/bridge/src/mesh/runtime/execution-sweep.ts

@@ -25,6 +25,8 @@ export function closeVanished(
   let closed = 0;
   for (const execution of executions) {
     if (execution.computerId !== computerId || execution.endedAt != null) continue;
+    // A provider cloud run is never a local chat, so its absence here says nothing.
+    if (execution.external) continue;
     if (!scannedProviders.has(execution.provider)) continue;
     if (liveSessionIds.has(execution.sessionId)) continue;
     execution.endedAt = endedAt;

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

@@ -39,6 +39,7 @@ import { projectSessionCapabilityInventory } from "./capabilities";
 import { createMeshSessionCatalog } from "./catalog/session-catalog";
 import { capturePreparedHandoff, preparedHandoffMetadata } from './prepared-transfer';
 import { sourceCheckoutUnchanged } from './prepared-transfer/source-checkout';
+import { prepareCloudHandoff } from "./cloud-handoff";
 
 export type { MeshRuntimeDependencies };
 
@@ -130,6 +131,7 @@ async function prepareHandoff(
     return false;
   }
   if (!capsule) return false;
+  if (request.cloud) return prepareCloudHandoff({ deps, block: blockHandoff, client, request, session, capsule });
   let transferContext: string | undefined;
   let confirmContext: (() => Promise<boolean>) | undefined;
   if (request.prepareOnly) {

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/apps/bridge/src/monitor/support/runtime.ts

@@ -6,6 +6,7 @@ import { loadRuntimeConfig, autoAcceptLevelFor } from "../../config";
 import { monitorLeadership } from "./leadership";
 import { mcpServersForSession, workspaceSkills } from "../../capabilities";
 import { inspectAgentIntegrations } from "../../install";
+import { withCloudRunners } from "../../cloud-runners";
 import { currentConfigRevision } from "../../config/commands";
 import { currentInstanceEpoch } from "../../host/instance-epoch";
 import { localMeshStore } from "../../mesh/local-remote/local";
@@ -102,7 +103,7 @@ function monitorSnapshot(input: {
     contextCompilerEnabled: runtime.contextCompilerEnabled,
     configRevision: currentConfigRevision(),
     instanceEpoch: currentInstanceEpoch(),
-    agents: inspectAgentIntegrations(),
+    agents: withCloudRunners(inspectAgentIntegrations()),
     generatedAt: Date.now(),
   };
 }

package/apps/bridge/src/provider-model-catalog/README.md

@@ -33,3 +33,21 @@ list of version numbers. Client model choices use the existing resume flags.
 
 Account percentages travel separately as optional `accountUsage` observations.
 See [provider account status](../provider-account-status/README.md).
+
+## Grok Build details and order
+
+`grok models` decides which Grok models exist. Grok Build's own account catalog
+(`models_cache.json` in its home, at most 24 hours old, 2 MB) only adds display
+names, descriptions and the reasoning levels each listed model accepts
+(`supportedEfforts`, e.g. `low…xhigh`); identity, endpoints, keys and headers
+are never read into a row. When the listing could not run at all (timeout or a
+crash) and Grok Build is installed and signed in, that fresh catalog stands in
+for it with its own fetch time; a signed-out listing advertises nothing.
+Cursor and Grok rows carry their CLI order as `priority`, so the phone shows
+them in the provider's order. The Grok binary is resolved like its turns
+(`GRANTTAP_GROK_BIN`, then `PATH`, then `~/.grok/bin/grok`), so a launchd PATH
+without Grok's installer directory no longer hides it.
+
+Claude Code has no listing command. Its picker keeps the CLI's documented aliases
+(`opus`, `sonnet`, `haiku`, `fable`); `--model` also accepts full names, which
+the phone does not invent. Tests: [`tests/grok-catalog.test.ts`](tests/grok-catalog.test.ts).

package/apps/bridge/src/provider-model-catalog/cli-models.ts

@@ -4,10 +4,14 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import type { AdvertisedModel } from "../../../../packages/protocol/schema";
 import { resolveCursorAgentBin } from "../reply/process/cursor-agent-bin";
+import { grokHome, resolveGrokBinary } from "../providers/grok-bin";
+import { enrichGrokModels, readGrokModelDetails } from "./grok-cache";
+
+const SIGNED_OUT = /not authenticated|please log in|login required/i;
 
 export function parseCLIModels(output: string, provider: "cursor" | "grok", endpointId: string,
   now: number): AdvertisedModel[] {
-  if (/not authenticated|please log in|login required/i.test(output)) return [];
+  if (SIGNED_OUT.test(output)) return [];
   const clean = output.replace(/\x1b\[[0-9;]*m/g, "");
   return clean.split("\n").flatMap(line => {
     const match = provider === "cursor"
@@ -15,7 +19,24 @@ export function parseCLIModels(output: string, provider: "cursor" | "grok", endp
       : /^\s*[*-]\s+([a-zA-Z0-9][a-zA-Z0-9._:/-]{0,159})(?:\s+\(([^)]+)\))?\s*$/.exec(line);
     return match ? [{ modelId: match[1]!, label: (provider === "cursor" ? match[2]! : match[1]!).slice(0, 160),
       provider, endpointId, observedAt: now, source: "advertised" as const }] : [];
-  }).slice(0, 240);
+  }).slice(0, 240).map((row, priority) => ({ ...row, priority }));
+}
+
+/**
+ * Both native listings as picker rows. Grok's own account catalog names and
+ * describes its listed models; when the listing could not run at all, that
+ * fresh catalog stands in for it. A signed-out listing advertises nothing.
+ */
+export function cliModelRows(cursorOutput: string, grokOutput: string, grokRoot: string,
+  endpointId: string, now: number): AdvertisedModel[] {
+  const cursor = parseCLIModels(cursorOutput, "cursor", endpointId, now);
+  let grok = parseCLIModels(grokOutput, "grok", endpointId, now);
+  if (!grokOutput.trim()) {
+    const cached = readGrokModelDetails(grokRoot, now);
+    grok = cached ? [...cached.models.keys()].map(modelId => ({ modelId, label: modelId, provider: "grok" as const,
+      endpointId, observedAt: cached.fetchedAt, source: "advertised" as const })) : [];
+  }
+  return [...cursor, ...enrichGrokModels(grok, grokRoot, now)];
 }
 
 let report: AdvertisedModel[] = [];
@@ -38,15 +59,16 @@ export function cachedCLIModels(endpointId: string, env = process.env): Advertis
     checkedAt = Date.now();
     pending = true;
     const cursor = resolveCursorAgentBin(env);
-    const grokRoot = env.GRANTTAP_GROK_DIR ?? join(homedir(), ".grok");
-    const grok = env.GRANTTAP_GROK_BIN ?? join(grokRoot, "bin/grok");
+    const grokRoot = grokHome(env);
+    const grok = resolveGrokBinary(env);
+    // Only an installed, signed-in Grok Build may stand in its cached catalog.
+    const usable = existsSync(join(grokRoot, "auth.json")) && existsSync(grok);
     void Promise.all([
       existsSync(cursor) ? read(cursor, ["models"]) : "",
-      existsSync(join(grokRoot, "auth.json")) && existsSync(grok) ? read(grok, ["models"]) : "",
+      usable ? read(grok, ["models"]) : "unavailable",
     ]).then(([a, b]) => {
-      if (scope === currentScope) report = [...parseCLIModels(a, "cursor", endpointId, Date.now()),
-        ...parseCLIModels(b, "grok", endpointId, Date.now())];
+      if (scope === currentScope) report = cliModelRows(a, b, grokRoot, endpointId, Date.now());
     }).finally(() => { pending = false; });
   }
-  return report.filter(row => Date.now() - row.observedAt <= 5 * 60_000);
+  return report.filter(row => Date.now() - row.observedAt <= (row.provider === "grok" ? 24 * 60 : 5) * 60_000);
 }

package/apps/bridge/src/provider-model-catalog/grok-cache.ts

@@ -0,0 +1,70 @@
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import type { AdvertisedModel } from "../../../../packages/protocol/schema";
+
+const MAX_BYTES = 2_000_000;
+const MAX_AGE = 24 * 60 * 60_000;
+const MODEL_ID = /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,159}$/;
+const EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
+type Effort = typeof EFFORTS[number];
+
+export type GrokModelDetail = Pick<AdvertisedModel, "label" | "description" | "supportedEfforts">;
+
+function text(value: unknown, max: number): string | undefined {
+  if (typeof value !== "string") return undefined;
+  return value.replace(/[\x00-\x1f\x7f]/g, " ").trim().slice(0, max) || undefined;
+}
+
+function readBounded(path: string): unknown {
+  const fd = openSync(path, "r");
+  try {
+    const size = fstatSync(fd).size;
+    if (size > MAX_BYTES) return undefined;
+    const bytes = Buffer.alloc(size);
+    return JSON.parse(bytes.subarray(0, readSync(fd, bytes, 0, size, 0)).toString("utf8"));
+  } finally { closeSync(fd); }
+}
+
+function efforts(info: Record<string, unknown>): Effort[] | undefined {
+  if (info.supports_reasoning_effort !== true || !Array.isArray(info.reasoning_efforts)) return undefined;
+  const values = info.reasoning_efforts.map((row) => (row as { value?: unknown } | null)?.value);
+  const known = EFFORTS.filter((effort) => values.includes(effort));
+  return known.length ? known : undefined;
+}
+
+/**
+ * Picker metadata from the catalog Grok Build itself fetched for this account:
+ * display names, descriptions and the reasoning levels each model accepts.
+ * Identity, endpoints, keys and headers never leave the file.
+ */
+export function readGrokModelDetails(
+  root: string, now = Date.now(),
+): { fetchedAt: number; models: Map<string, GrokModelDetail> } | undefined {
+  try {
+    const cache = readBounded(join(root, "models_cache.json")) as Record<string, unknown> | undefined;
+    if (!cache || typeof cache !== "object" || Array.isArray(cache)) return undefined;
+    const fetchedAt = typeof cache.fetched_at === "string" ? Date.parse(cache.fetched_at) : NaN;
+    if (!Number.isFinite(fetchedAt) || now - fetchedAt > MAX_AGE || fetchedAt - now > 5 * 60_000) return undefined;
+    if (!cache.models || typeof cache.models !== "object" || Array.isArray(cache.models)) return undefined;
+    const models = new Map<string, GrokModelDetail>();
+    for (const [key, value] of Object.entries(cache.models as Record<string, unknown>).slice(0, 64)) {
+      const info = (value as { info?: unknown } | null)?.info as Record<string, unknown> | undefined;
+      if (!info || typeof info !== "object" || info.hidden === true || !MODEL_ID.test(key)) continue;
+      const supportedEfforts = efforts(info);
+      models.set(key, { label: text(info.name, 160), description: text(info.description, 240),
+        ...(supportedEfforts ? { supportedEfforts } : {}) });
+    }
+    return { fetchedAt, models };
+  } catch { return undefined; }
+}
+
+/** The CLI list stays authoritative; the cache only names and describes its rows. */
+export function enrichGrokModels(rows: AdvertisedModel[], root: string, now = Date.now()): AdvertisedModel[] {
+  const details = readGrokModelDetails(root, now);
+  return rows.map((row, priority) => {
+    const detail = details?.models.get(row.modelId);
+    return { ...row, priority, ...(detail?.label ? { label: detail.label } : {}),
+      ...(detail?.description ? { description: detail.description } : {}),
+      ...(detail?.supportedEfforts ? { supportedEfforts: detail.supportedEfforts } : {}) };
+  });
+}

package/apps/bridge/src/providers/grok-bin.ts

@@ -0,0 +1,31 @@
+/** Resolve the Grok Build CLI the same way for its catalog, its turns and its status. */
+import { accessSync, constants } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { executableOnPath } from "./claude-bin";
+
+function executable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Grok's own home: `GRANTTAP_GROK_DIR` for tests and relocated installs, else ~/.grok. */
+export function grokHome(env: NodeJS.ProcessEnv = process.env, home = homedir()): string {
+  return env.GRANTTAP_GROK_DIR ?? join(home, ".grok");
+}
+
+/**
+ * launchd does not inherit an interactive shell's PATH, and Grok's installer
+ * keeps its binary under ~/.grok/bin. An explicit override still wins.
+ */
+export function resolveGrokBinary(env: NodeJS.ProcessEnv = process.env, home = homedir()): string {
+  if (env.GRANTTAP_GROK_BIN) return env.GRANTTAP_GROK_BIN;
+  const onPath = executableOnPath("grok", env);
+  if (onPath) return onPath;
+  const installed = join(grokHome(env, home), "bin", "grok");
+  return executable(installed) ? installed : "grok";
+}

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

@@ -18,3 +18,10 @@ in the repository-root `LICENSE` file.
 Model reasoning effort reaches resumed and new provider turns as native arguments.
 Codex uses `model_reasoning_effort`; Claude uses `--effort`; Grok uses
 `--reasoning-effort`. Cursor effort variants are native model IDs.
+
+Accepted levels: Codex `low…ultra`, Claude `low…max`, Grok `low…xhigh` (Grok
+Build lists `xhigh` for its current models and has no `max`). Anything else is
+dropped rather than passed. A prepared transfer's first turn uses the model and
+effort that message carries, else the capsule's `targetModel`. Grok Build is
+resolved with `providers/grok-bin.ts`. Tests:
+[`tests/model-effort-args.test.ts`](tests/model-effort-args.test.ts).

package/apps/bridge/src/reply/process/provider-effort.ts

@@ -1,9 +1,10 @@
 /** Provider-native controls, never interpolated into a prompt or shell. */
 export function providerEffortArgs(provider: string, effort?: string): string[] {
   if (!effort) return [];
+  // Grok Build lists low…xhigh per model in its own catalog; it has no max.
   const supported = provider === "codex" ? ["low", "medium", "high", "xhigh", "max", "ultra"]
     : provider === "claude" ? ["low", "medium", "high", "xhigh", "max"]
-    : provider === "grok" ? ["low", "medium", "high"] : [];
+    : provider === "grok" ? ["low", "medium", "high", "xhigh"] : [];
   if (!supported.includes(effort)) return [];
   return provider === "codex" ? ["-c", `model_reasoning_effort="${effort}"`]
     : [provider === "grok" ? "--reasoning-effort" : "--effort", effort];

package/apps/bridge/src/reply/process/provider-headless.ts

@@ -5,13 +5,14 @@ import { providerEffortArgs } from "./provider-effort";
 import type { ReplyResult } from "../payload/types";
 import type { DeliveryOptions } from "../payload/types";
 import { resolveCursorAgentBin } from "./cursor-agent-bin";
+import { resolveGrokBinary } from "../../providers/grok-bin";
 
 function cursorBin(): string {
   return resolveCursorAgentBin();
 }
 
 function grokBin(): string {
-  return process.env.GRANTTAP_GROK_BIN ?? "grok";
+  return resolveGrokBinary();
 }
 
 function parseCursor(stdout: string, fallback?: string): ReplyResult {

package/apps/mcp/src/desktop/delivery/task-handoff.ts

@@ -39,6 +39,10 @@ export async function desktopTaskHandoff(
     targetProvider: row.target_provider, targetComputer: row.target_computer,
     targetModel: row.target_model, userComment: row.user_comment,
     checkpoint: row.checkpoint, push: row.push, createdAt: Date.now(),
+    ...(row.cloud === true ? { cloud: {
+      ...(row.cloud_environment === undefined ? {} : { environment: row.cloud_environment }),
+      ...(row.cloud_effort === undefined ? {} : { effort: row.cloud_effort }),
+    } } : {}),
   });
   if (!request.success) return undefined;
   const loaded = readStoreState(storePath);

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.70
+npm install -g granttap-mcp@0.8.72
 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.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"
+        "\"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.72\";\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.70";
+const PACKAGE = "granttap-mcp@0.8.72";
 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.70",
+  "version": "0.8.72",
   "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

@@ -6,7 +6,7 @@ import {
   MeshExecutionProvider,
   Path,
 } from "./endpoint";
-import { ResourceClaim } from "./tasks";
+import { CloudLaunchRequest, ResourceClaim } from "./tasks";
 
 export const TaskCapsule = z.object({
   taskId: Identifier,
@@ -229,9 +229,18 @@ export const MeshHandoffPrepare = z.object({
    * Never a force push; the person asks for it per handoff.
    */
   push: z.boolean().optional(),
+  /**
+   * Start the Task in the provider's cloud runner instead of a local chat.
+   * The target computer launches it with its installed CLI, so it must be the
+   * computer that holds the Task. A Codex Cloud environment may be named.
+   */
+  cloud: CloudLaunchRequest.optional(),
 }).strict().superRefine((value, ctx) => {
   if ((value.targetProvider === "grok_bot") !== (value.targetActorId != null)) {
     ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["targetActorId"], message: "actor required" });
   }
+  if (value.cloud && value.targetProvider !== "claude" && value.targetProvider !== "codex") {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["cloud"], message: "cloud runner provider" });
+  }
 });
 export type MeshHandoffPrepare = z.infer<typeof MeshHandoffPrepare>;

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

@@ -58,6 +58,19 @@ export const MeshTask = z.object({
 }).strict();
 export type MeshTask = z.infer<typeof MeshTask>;
 
+/** A provider cloud run a computer started; GrantTap cannot observe its progress. */
+export const ExternalExecution = z.object({
+  runner: z.enum(["claude_cloud", "codex_cloud"]),
+  url: z.string().trim().max(1_024).regex(/^https:\/\/\S+$/).optional(),
+}).strict();
+export type ExternalExecution = z.infer<typeof ExternalExecution>;
+
+export const CloudLaunchRequest = z.object({
+  environment: z.string().trim().min(1).max(160).regex(/^[^\x00-\x1f\x7f]+$/).optional(),
+  effort: z.enum(["low", "medium", "high", "xhigh", "max"]).optional(),
+}).strict();
+export type CloudLaunchRequest = z.infer<typeof CloudLaunchRequest>;
+
 export const ExecutionSessionLink = z.object({
   continuedAt: z.number().nonnegative().optional(),
   state: z.enum(["working", "waiting", "idle"]).optional(),
@@ -84,6 +97,8 @@ export const ExecutionSessionLink = z.object({
   activeAt: z.number().nonnegative().optional(),
   startedAt: z.number().nonnegative(),
   endedAt: z.number().nonnegative().optional(),
+  // Set only for a provider cloud run: where to look at it, never progress.
+  external: ExternalExecution.optional(),
 }).strict().superRefine((value, ctx) => {
   if ((value.provider === "grok_bot") !== (value.actorId != null)) {
     ctx.addIssue({

package/packages/protocol/messages/provider-hooks/index.ts

@@ -48,6 +48,8 @@ export const AgentIntegrationStatus = z.object({
   updateCommand: z.string().trim().min(1).max(200).optional(),
   newerOnThisMac: z.string().trim().min(1).max(64).optional(),
   updating: z.boolean().optional(),
+  // The installed CLI can start the provider's cloud runner without a terminal.
+  cloud: z.boolean().optional(),
 });
 export type AgentIntegrationStatus = z.infer<typeof AgentIntegrationStatus>;