granttap-mcp 0.8.21 → 0.8.23

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

@@ -31,6 +31,7 @@ import { loadExecutionPolicy } from "../runtime/execution-policy";
 import { loadEnvironment, redactEnvironment } from "../context/env";
 import { loadRestrictions } from "../restrictions";
 import { MeshStoreBase } from "./base";
+import { activeProjectKnowledge, supersededProjectKnowledgeIds } from "../knowledge/active";
 import {
   projectCapabilityRequests,
 } from "../catalog/project/requests";
@@ -268,6 +269,12 @@ export class MeshStore extends MeshStoreBase {
     return this.state.events.filter((event) => event.projectId === projectId).slice(-128);
   }
 
+  /** Retained, structured evidence for a one-time Memory backfill. */
+  historyEventsForProject(projectId: string): MeshEventValue[] {
+    this.sync();
+    return this.state.events.filter((event) => event.projectId === projectId);
+  }
+
   projectIds(): string[] {
     this.sync();
     return this.state.projects.map((project) => project.projectId);
@@ -331,6 +338,7 @@ export class MeshStore extends MeshStoreBase {
     const execution = loadExecutionPolicy(projectId);
     const restrictions = loadRestrictions(projectId);
     const environment = redactEnvironment(loadEnvironment(projectId));
+    const correctedIds = supersededProjectKnowledgeIds(projectId, this.state.knowledge);
     return MeshSnapshot.parse({
       type: "mesh.snapshot",
       sessionId: projectId,
@@ -360,8 +368,9 @@ export class MeshStore extends MeshStoreBase {
       claims: this.activeClaims().filter((item) => item.projectId === projectId && taskIds.has(item.taskId)).slice(-128),
       dependencies: this.state.dependencies.filter((item) => taskIds.has(item.taskId)).slice(-128),
       events: this.eventsForProject(projectId).filter((event) => taskIds.has(event.taskId)),
-      knowledge: this.state.knowledge.filter((item) => item.projectId === projectId)
+      knowledge: activeProjectKnowledge(projectId, this.state.knowledge)
         .slice(-16).reverse(),
+      ...(correctedIds.length > 0 ? { supersededKnowledgeRecordIds: correctedIds } : {}),
       generatedAt: this.now(),
     });
   }

package/apps/bridge/src/monitor/controller-knowledge/index.ts

@@ -0,0 +1,51 @@
+import type { RelayClient } from "../../../../../packages/core/relay-client";
+import type { ControllerPairRequest, KnowledgeWrite } from "../../../../../packages/protocol/schema";
+import { loadRuntimeConfig } from "../../config";
+import { loadConfig, machineConfigPath } from "../../config";
+import { localMeshStore } from "../../mesh/local-remote/local";
+import { createOneTimePairing, parkedPairingHalves } from "../../pairing";
+import { issueControllerOffer } from "../../pairing/controller-invites";
+import { handleKnowledgeWrite } from "../../mesh/knowledge/write";
+import { recordProjectKnowledge } from "../../engine/runtime/engine-memory";
+import { computerId } from "../../mesh/identity/computer";
+
+/** The requester's device key scopes the new controller code, not Project access. */
+export async function handleControllerPairRequest(
+  client: RelayClient, request: ControllerPairRequest, peerPublicKey?: string,
+): Promise<boolean> {
+  if (!peerPublicKey || !parkedPairingHalves()) return false;
+  const machine = loadConfig(machineConfigPath());
+  if (machine.room !== client.room) return false;
+  return issueControllerOffer(client, peerPublicKey, request, async () => {
+    const pairing = await createOneTimePairing(machine.relayUrl, {
+      installHooks: false, addController: true,
+    });
+    return { room: pairing.machineCfg.room, peerPublicKey: pairing.phoneCfg.myPublicKey,
+      uri: pairing.qrPayload };
+  });
+}
+
+/** A phone gets a recorded receipt only after the local Engine commits Memory. */
+export async function handleInboundKnowledgeWrite(
+  client: RelayClient, request: KnowledgeWrite, peerPublicKey: string | undefined,
+  publish: () => Promise<void>,
+): Promise<boolean> {
+  if (!peerPublicKey) return false;
+  const endpointId = computerId();
+  let recorded = false;
+  const handled = await handleKnowledgeWrite(request, {
+    now: Date.now, endpointId,
+    snapshot: (projectId) => {
+      if (!loadRuntimeConfig().meshEnabled) return undefined;
+      const snapshot = localMeshStore().snapshot(projectId, endpointId);
+      return snapshot && { tasks: snapshot.tasks, bindings: snapshot.bindings ?? [] };
+    },
+    record: async (entry) => {
+      recorded = await recordProjectKnowledge(entry);
+      return recorded;
+    },
+    send: (result) => client.sendToPeer(result, peerPublicKey),
+  });
+  if (recorded) void publish().catch(() => {});
+  return handled;
+}

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

@@ -34,6 +34,7 @@ import { handleUserMessage } from "./user-message";
 import { publishSessionEvents } from "./catalog";
 import { publishHistoryPage } from "../history/pages";
 import { requestProjectGraphRefresh } from "../graph-refresh";
+import { handleControllerPairRequest, handleInboundKnowledgeWrite } from "../controller-knowledge";
 
 export async function handleMonitorMessage(
   client: RelayClient,
@@ -42,6 +43,7 @@ export async function handleMonitorMessage(
     leadership: { acquire: () => boolean };
     subscriptions: Set<string>;
     publish: (forceHistory?: boolean) => Promise<void>;
+    peerPublicKey?: string;
   },
 ): Promise<boolean> {
   const { leadership, subscriptions, publish } = input;
@@ -52,6 +54,12 @@ export async function handleMonitorMessage(
     // Codex may start one MCP server per open task. Exactly one instance owns
     // phone routing, so a single phone message can never create duplicate tasks.
     if (!leadership.acquire()) return false;
+    if (payload.type === "controller.pair.request") {
+      return handleControllerPairRequest(client, payload, input.peerPublicKey);
+    }
+    if (payload.type === "knowledge.write") {
+      return handleInboundKnowledgeWrite(client, payload, input.peerPublicKey, publish);
+    }
     if (payload.type === "user.message") {
       return handleInboundUserMessage(client, payload, publish);
     } else if (payload.type === "user.attachment") {
@@ -121,17 +129,23 @@ export async function handleMonitorMessage(
       if (prepared) void publish().catch(() => {});
       return prepared;
     } else if (payload.type === "mesh.claim.release" && loadRuntimeConfig().meshEnabled) {
-      // The person's own authority, not an owner's event: written down, then
-      // applied, and answered either way, so a refusal is seen where it was asked.
-      const outcome = releaseClaimByPerson(localMeshStore(), payload);
-      await sendProjectPayload(client, releaseResult(payload, outcome), "phone", { ttlMs: 15 * 60_000 })
-        .catch(() => {});
-      if (outcome.released) void publish().catch(() => {});
-      return true;
+      return handleInboundClaimRelease(client, payload, publish);
     }
     return false;
 }
 
+async function handleInboundClaimRelease(
+  client: RelayClient, payload: Extract<Payload, { type: "mesh.claim.release" }>,
+  publish: (forceHistory?: boolean) => Promise<void>,
+): Promise<boolean> {
+  // The person's authority is recorded and answered even when release fails.
+  const outcome = releaseClaimByPerson(localMeshStore(), payload);
+  await sendProjectPayload(client, releaseResult(payload, outcome), "phone", { ttlMs: 15 * 60_000 })
+    .catch(() => {});
+  if (outcome.released) void publish().catch(() => {});
+  return true;
+}
+
 function handleInboundRefresh(
   client: RelayClient, payload: Extract<Payload, { type: "sessions.refresh" }>,
   publish: (forceHistory?: boolean) => Promise<void>,

package/apps/bridge/src/monitor/support/runtime.ts

@@ -273,7 +273,7 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
     if (payload.type === "hello" && payload.role === "phone") {
       confirmPendingController(client.room, peerPublicKey);
     }
-    return handleMonitorMessage(client, payload, { leadership, subscriptions, publish });
+    return handleMonitorMessage(client, payload, { leadership, subscriptions, publish, peerPublicKey });
   });
 
   const stopCatalog = startPublishLoop({

package/apps/bridge/src/pairing/controller-invites.ts

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ControllerPairOffer, ControllerPairRequest } from "../../../../packages/protocol/schema";
+import { configDir } from "../config/runtime/paths";
+import { writePrivateFile } from "../config/access/write-private";
+
+type Record = { requestId: string; requesterKey: string; offer: ControllerPairOffer };
+type Transport = {
+  room: string;
+  addControllerPeer: (key: string) => void;
+  sendToPeer: (offer: ControllerPairOffer, key: string) => Promise<void>;
+};
+type Mint = () => Promise<{ room: string; peerPublicKey: string; uri: string }>;
+
+const pending = new Map<string, Promise<boolean>>();
+let issuance = Promise.resolve();
+
+function journalPath(): string { return join(configDir(), "controller-pair-offers.json"); }
+
+function load(now: number): Record[] | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(journalPath(), "utf8"));
+    if (!Array.isArray(parsed) || parsed.length > 16) return null;
+    const valid = (value: unknown): value is Record => {
+      if (!value || typeof value !== "object") return false;
+      const record = value as Partial<Record>;
+      return typeof record.requestId === "string" && typeof record.requesterKey === "string"
+        && typeof record.offer?.expiresAt === "number" && typeof record.offer.uri === "string"
+        && record.offer.status === "ready";
+    };
+    if (!parsed.every(valid)) return null;
+    return parsed.filter((record: Record) => (record.offer.expiresAt ?? 0) > now);
+  } catch { return existsSync(journalPath()) ? null : []; }
+}
+
+function persist(records: Record[]): void {
+  writePrivateFile(journalPath(), `${JSON.stringify(records)}\n`);
+}
+
+function rejected(requestId: string, room: string, reason: string, now: number): ControllerPairOffer {
+  return { type: "controller.pair.offer", requestId, room, status: "rejected", reason,
+    createdAt: now };
+}
+
+async function issue(
+  client: Transport, requesterKey: string, request: ControllerPairRequest, mint: Mint,
+  now: number,
+): Promise<boolean> {
+  const records = load(now);
+  let offer: ControllerPairOffer;
+  if (!records) {
+    offer = rejected(request.requestId, client.room, "Pairing journal needs repair on the computer.", now);
+  } else {
+    const prior = records.find((item) => item.requestId === request.requestId);
+    if (prior && prior.requesterKey !== requesterKey) {
+      offer = rejected(request.requestId, client.room, "This request belongs to another controller.", now);
+    } else if (prior) {
+      offer = prior.offer;
+    } else if (Math.abs(now - request.createdAt) > 5 * 60_000) {
+      offer = rejected(request.requestId, client.room, "Request expired. Try again.", now);
+    } else {
+      try {
+        const created = await mint();
+        if (created.room !== client.room) throw new Error("room changed");
+        client.addControllerPeer(created.peerPublicKey);
+        offer = { type: "controller.pair.offer", requestId: request.requestId,
+          room: client.room, status: "ready", uri: created.uri,
+          expiresAt: now + 15 * 60_000, createdAt: now };
+        persist([...records, { requestId: request.requestId, requesterKey, offer }].slice(-16));
+      } catch {
+        offer = rejected(request.requestId, client.room, "Could not create a controller code.", now);
+      }
+    }
+  }
+  await client.sendToPeer(offer, requesterKey);
+  return true;
+}
+
+/** Durable, scoped offer: a relay retry cannot mint a second controller key. */
+export function issueControllerOffer(
+  client: Transport, requesterKey: string, request: ControllerPairRequest, mint: Mint,
+  now = Date.now(),
+): Promise<boolean> {
+  const id = `${client.room}:${request.requestId}`;
+  const existing = pending.get(id);
+  if (existing) return existing;
+  const work = issuance.then(() => issue(client, requesterKey, request, mint, now));
+  issuance = work.then(() => undefined, () => undefined);
+  pending.set(id, work);
+  void work.finally(() => { pending.delete(id); }).catch(() => undefined);
+  return work;
+}

package/apps/mcp/src/connection-center/bridge.js

@@ -43,6 +43,13 @@ async function initializeBridge() {
     });
     if (initialized?.protocolVersion !== "2026-01-26") throw new Error("Unsupported UI protocol");
     post({ method: "ui/notifications/initialized" });
+    // The compatibility API is an explicit tool-call capability. In Codex it
+    // avoids an iframe proxy that can initialize but time out on tools/call.
+    legacyBridge = typeof window.openai?.callTool === "function";
+    if (!legacyBridge && !initialized.hostCapabilities?.serverTools) {
+      message("This host cannot call GrantTap tools from the card. Ask the agent to open connection status or add a device.");
+      return;
+    }
     bridgeReady = true;
   } catch {
     if (!window.openai?.callTool) {

package/apps/mcp/src/connection-center/widget.html

@@ -38,7 +38,7 @@ details{border-top:1px solid #8884;padding-top:14px}summary{cursor:pointer;font-
     <h3>Provider readiness</h3><ul id="providers"></ul>
     <p>No GrantTap account or password is required. Pair using GrantTap on iPhone → Settings → Connections.
     Provider sign-in is separate.</p>
-    <p>Missing hooks or background sync? Run <code>npm install -g granttap-mcp@0.8.21</code> and <code>granttap setup</code> locally.
+    <p>Missing hooks or background sync? Run <code>npm install -g granttap-mcp@0.8.23</code> and <code>granttap setup</code> locally.
     A saved pairing alone does not prove your phone or the background helper is online.</p>
     <p><a href="https://granttap.com" target="_blank" rel="noopener noreferrer">Website</a> ·
     <a href="https://granttap.com/privacy" target="_blank" rel="noopener noreferrer">Privacy</a> ·

package/apps/mcp/src/mcp-tools/connect/widget.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
-export const CONNECTION_WIDGET_URI = "ui://granttap/connection/v2.html";
+export const CONNECTION_WIDGET_URI = "ui://granttap/connection/v3.html";
 
 import { readFileSync } from "node:fs";
 

package/bin/granttap-mcp.mjs

@@ -16,6 +16,8 @@ const usage = [
   "  granttap setup                    Detect agents and install or repair GrantTap",
   "  granttap status [--json]          Show pairing, helper, and provider readiness",
   "  granttap connect [--relay <url>]  Pair this computer with iPhone/Apple Watch",
+  "  granttap phone add              Show a QR for another controller phone",
+  "  granttap phone reconnect        Show a QR to restore the same phone",
   "  granttap reset [--yes]            Reset this computer's phone pairing",
   "  granttap mesh connect <invite>    Redeem a one-time Grok Bot Mesh invite",
   "  granttap restrictions check [dir] Check files against Mesh / .granttap restrictions",
@@ -36,6 +38,8 @@ if (command === "mcp") {
   entry = join(root, "apps", "bridge", "src", "bin", "cli", "setup.ts");
 } else if (command === "connect") {
   entry = join(root, "apps", "bridge", "src", "bin", "cli", "connect.ts");
+} else if (command === "phone" && ["add", "reconnect"].includes(argument)) {
+  entry = join(root, "apps", "bridge", "src", "bin", "cli", "phone.ts");
 } else if (command === "status") {
   entry = join(root, "apps", "mcp", "src", "bin", "status.ts");
 } else if (command === "reset") {
@@ -100,8 +104,8 @@ if (!preflight || !loader) {
   process.exit(1);
 }
 
-const forwardedArgs = ["connect", "status", "reset", "mesh", "setup", "restrictions"].includes(command)
-  ? (command === "mesh" || command === "restrictions" ? commandArgs.slice(1) : commandArgs)
+const forwardedArgs = ["connect", "status", "reset", "mesh", "setup", "restrictions", "phone"].includes(command)
+  ? (command === "mesh" || command === "restrictions" || command === "phone" ? commandArgs.slice(1) : commandArgs)
   : [];
 const child = spawn(
   process.execPath,

package/cursor-plugin/.cursor-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "granttap",
   "displayName": "GrantTap",
-  "version": "0.1.14",
-  "description": "The agent connects this computer in chat. Authorize in plugin settings opens the device window. Scan the QR in GrantTap — that scan authorizes. Device list and Add another stay there and in the GrantTap app.",
+  "version": "0.1.16",
+  "description": "GrantTap pairs this computer with iPhone. The connection card shows a one-time QR when Cursor supports interactive MCP Apps; an interactive terminal command is available if it does not. The website approves the coding app.",
   "author": {
     "name": "GrantTap",
     "email": "support@granttap.com",

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.21
+npm install -g granttap-mcp@0.8.23
 granttap setup
 granttap status
 ```
@@ -22,9 +22,12 @@ The commands have separate jobs:
 2. `granttap setup` also installs the background task-sync helper.
 3. `granttap status` performs a read-only readiness check.
 
-After `granttap setup`, pair on `granttap.com/connect` — Approve this coding
-app, Reconnect, or Add another. A saved pairing still opens that page. Scan
-in the GrantTap app only when a new device joins. Cloud **Error · fetch
+After `granttap setup`, open the GrantTap connection card in Cursor for **Add a
+device**, **Add another device**, or **Reconnect**. Scan its QR in the phone
+app. If Cursor does not render or operate the card, run `granttap phone add`
+in your own interactive terminal; it never prints the QR to an agent log.
+`granttap.com/connect` approves the coding app and shows phone observations.
+Cloud **Error · fetch
 failed** is a leftover HTTP MCP at `http://127.0.0.1:17342/mcp` — either a
 user Customize → MCPs row or an old plugin `mcp.json`. The current plugin is
 stdio (`node -e`) so Cloud never fetches loopback.

package/cursor-plugin/commands/connect.md

@@ -7,6 +7,7 @@ Call GrantTap tools yourself. Do not ask the person to pair in this chat.
 1. Call `connection_status`.
 2. If this computer is not paired, call `connect`.
 3. Do not print a pairing URI, token, or QR in chat.
-4. Device list, Approve, Add another device, and Reconnect belong on
-   granttap.com/connect, in GrantTap plugin settings, and in the GrantTap
-   app — not in chat.
+4. The GrantTap connection card shows the device list and one-time QR when
+   Cursor supports interactive MCP Apps. `granttap.com/connect` approves the
+   coding app but does not display a pairing QR. If the card cannot call tools,
+   tell the person to run `granttap phone add` in their own terminal.

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.21\";\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.23\";\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/skills/connect/SKILL.md

@@ -12,19 +12,20 @@ The person does not pair in chat. You connect this computer by calling tools.
 1. Call `connection_status`.
 2. If this computer is not paired, call `connect`.
 3. Never print a pairing URI, manual token, or QR in chat.
-4. Never tell the person to scan something in this conversation, open a website,
-   or type a setup command.
+4. Never put a private pairing QR in this conversation. If the host cannot
+   call tools from the connection card, explain the local interactive-terminal
+   fallback: `granttap phone add` or `granttap phone reconnect`.
 
 A saved pairing is reused. Do not call `reconnect` unless they confirmed
 Add another device or Reconnect in plugin settings.
 
 ## Settings (the person)
 
-Device list, Approve, Add another device, and Reconnect live on
-granttap.com/connect, in the GrantTap plugin settings of this host, and in
-the GrantTap app. Authenticate opens that page even when this computer is
-already paired. The same pairing room is shared across those hosts on this
-computer.
+The GrantTap connection card in this host shows the device list and one-time
+QR under Add a device, Add another device, or Reconnect when the host supports
+interactive MCP Apps. GrantTap on iPhone scans it in Settings → Connections.
+granttap.com/connect handles coding-app approval and phone observations, but
+does not display a pairing QR. All coding apps on this computer share one room.
 
 For an interactive question, send the same complete prompt to Cursor and
 GrantTap under one exact correlation. The first answer with that correlation

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.21";
+const PACKAGE = "granttap-mcp@0.8.23";
 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.21",
+  "version": "0.8.23",
   "description": "Personal live control center runtime for local coding agents on iPhone and Apple Watch.",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "setup": "node bin/granttap-mcp.mjs setup",
     "status": "node bin/granttap-mcp.mjs status",
     "test": "HOME=$(mktemp -d) GRANTTAP_SKIP_LAUNCHCTL=1 node scripts/quality/run-tests.mjs",
-    "test:coverage": "HOME=$(mktemp -d) GRANTTAP_SKIP_LAUNCHCTL=1 c8 --all --extension .ts --extension .js --exclude '**/tests/**' --exclude 'scripts/**' --exclude 'packages/core/relay-client-types.ts' --exclude 'apps/bridge/src/capabilities/types.ts' --exclude 'apps/bridge/src/reply/payload/types.ts' --exclude 'apps/bridge/src/mesh/runtime/dependencies.ts' --check-coverage --lines 95 --statements 95 --functions 95 --branches 85 node scripts/quality/run-tests.mjs",
+    "test:coverage": "HOME=$(mktemp -d) GRANTTAP_SKIP_LAUNCHCTL=1 c8 --all --extension .ts --extension .js --exclude '**/tests/**' --exclude 'scripts/**' --exclude 'packages/core/relay-client-types.ts' --exclude 'apps/bridge/src/capabilities/types.ts' --exclude 'apps/bridge/src/reply/payload/types.ts' --exclude 'apps/bridge/src/mesh/runtime/dependencies.ts' --check-coverage --lines 90 --statements 90 --functions 90 --branches 85 node scripts/quality/run-tests.mjs",
     "inventory": "node scripts/quality/source-inventory.mjs",
     "structure": "node scripts/quality/structure.mjs",
     "package:allowlist": "node scripts/quality/package-allowlist.mjs",

package/packages/core/relay-client.ts

@@ -238,6 +238,27 @@ export class RelayClient {
     }
   }
 
+  /** Add a newly issued controller without waiting for the monitor to restart. */
+  addControllerPeer(peerPublicKey: string): void {
+    if (this.cfg.role !== "machine" || !this.peerIsAllowed(peerPublicKey)) {
+      throw new Error("controller peer is not authorized");
+    }
+    const peers = this.cfg.extraPeerPublicKeys ?? [];
+    if (peerPublicKey !== this.cfg.peerPublicKey && !peers.includes(peerPublicKey)) {
+      if (peers.length >= 16) throw new Error("controller device limit reached");
+      this.cfg.extraPeerPublicKeys = [...peers, peerPublicKey];
+    }
+  }
+
+  /** Keep a controller invitation visible only to the requesting phone key. */
+  async sendToPeer(payload: Payload, peerPublicKey: string, options: SendOptions = {}): Promise<void> {
+    const ws = this.ws;
+    if (!ws || ws.readyState !== WebSocket.OPEN) throw new Error("relay not connected");
+    if (!peerPublicKeys(this.cfg.peerPublicKey, this.cfg.extraPeerPublicKeys).includes(peerPublicKey)
+      || !this.peerIsAllowed(peerPublicKey)) throw new Error("controller peer is not authorized");
+    ws.send(sealEnvelope({ ...this.cfg, peerPublicKey }, payload, this.otherRole(), options));
+  }
+
   setSessionKey(sessionId: string, key: string): void {
     this.sessionKeys.set(sessionId, key);
   }

package/packages/protocol/messages/README.md

@@ -20,6 +20,12 @@ sealed with the same independent Project key as Mesh snapshots. Coverage keeps
 `enforced`, `observed`, `unsupported`, and `unknown` distinct so clients never
 claim a provider can block an action when it cannot.
 
+`device/controller-pairing.ts` lets an authenticated controller ask its linked
+computer for another one-time controller credential. The reply is sealed only
+to the requester. It is device-network pairing, not Project membership.
+`mesh/knowledge/write.ts` carries a Task-bound human decision or correction and a
+separate Engine-confirmed result.
+
 Tests are discoverable in `tests/core.test.ts` and the feature-level bridge and MCP suites.
 
 License: this module is distributed under the MIT License in the repository-root `LICENSE` file.

package/packages/protocol/messages/device/controller-pairing.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+const RequestId = z.string().uuid();
+
+/** A trusted phone asks its paired computer to mint a separate controller key. */
+export const ControllerPairRequest = z.object({
+  type: z.literal("controller.pair.request"),
+  requestId: RequestId,
+  createdAt: z.number().nonnegative(),
+}).strict();
+export type ControllerPairRequest = z.infer<typeof ControllerPairRequest>;
+
+/** Sent only through the authenticated device box, never a Project channel. */
+export const ControllerPairOffer = z.object({
+  type: z.literal("controller.pair.offer"),
+  requestId: RequestId,
+  room: z.string().regex(/^[a-f0-9]{16,64}$/),
+  status: z.enum(["ready", "rejected"]),
+  uri: z.string().max(1024).optional(),
+  expiresAt: z.number().nonnegative().optional(),
+  reason: z.string().max(200).optional(),
+  createdAt: z.number().nonnegative(),
+}).strict().superRefine((offer, ctx) => {
+  if (offer.status === "ready" && (!offer.uri?.startsWith("granttap://pair-v2?")
+    || !offer.expiresAt || offer.expiresAt <= offer.createdAt)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "ready offer needs a valid URI and expiry" });
+  }
+  if (offer.status === "rejected" && offer.uri) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "rejected offer cannot carry a URI" });
+  }
+});
+export type ControllerPairOffer = z.infer<typeof ControllerPairOffer>;

package/packages/protocol/messages/mesh/knowledge/index.ts

@@ -13,6 +13,7 @@ export const ProjectKnowledgeRecord = z.object({
   visibility: z.enum(["task", "project"]),
   repositoryId: z.string().trim().min(1).max(512).optional(),
   commitSha: z.string().regex(/^[a-f0-9]{7,64}$/i).optional(),
+  supersedesRecordId: Identifier.optional(),
   recordedAt: z.number().int().nonnegative(),
   streamVersion: z.number().int().nonnegative(),
 }).strict();

package/packages/protocol/messages/mesh/knowledge/write.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { Identifier } from "../endpoint";
+
+/** A person's explicit statement, never inferred from a chat title. */
+export const KnowledgeWrite = z.object({
+  type: z.literal("knowledge.write"),
+  projectId: Identifier,
+  taskId: Identifier,
+  recordId: Identifier,
+  content: z.string().trim().min(1).max(4_096),
+  repositoryId: z.string().trim().min(1).max(512).optional(),
+  supersedesRecordId: Identifier.optional(),
+  createdAt: z.number().int().nonnegative(),
+}).strict().refine((request) => request.recordId !== request.supersedesRecordId,
+  "a decision cannot supersede itself");
+export type KnowledgeWrite = z.infer<typeof KnowledgeWrite>;
+
+export const KnowledgeWriteResult = z.object({
+  type: z.literal("knowledge.write.result"),
+  projectId: Identifier,
+  taskId: Identifier,
+  recordId: Identifier,
+  status: z.enum(["recorded", "rejected"]),
+  reason: z.string().max(200).optional(),
+  createdAt: z.number().int().nonnegative(),
+}).strict();
+export type KnowledgeWriteResult = z.infer<typeof KnowledgeWriteResult>;

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

@@ -239,6 +239,7 @@ export const MeshSnapshot = z.object({
   repositoryGraphs: z.array(ProjectRepositoryGraph).max(64).optional(),
   cortex: z.array(ProjectCortexIntegration).max(32).optional(),
   knowledge: z.array(ProjectKnowledgeRecord).max(32).optional(),
+  supersededKnowledgeRecordIds: z.array(Identifier).max(128).optional(),
   tasks: z.array(MeshTask).max(64),
   executions: z.array(ExecutionSessionLink).max(128),
   claims: z.array(ResourceClaim).max(128),
@@ -295,6 +296,11 @@ export const MeshSnapshot = z.object({
     ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["repositoryGraphs"], message: "invalid repository graph scope" });
   }
   const knowledgeIds = new Set(value.knowledge?.map((item) => item.recordId));
+  const supersededKnowledgeIds = new Set(value.supersededKnowledgeRecordIds);
+  if (supersededKnowledgeIds.size !== (value.supersededKnowledgeRecordIds?.length ?? 0)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["supersededKnowledgeRecordIds"],
+      message: "duplicate superseded knowledge identity" });
+  }
   if ((value.knowledge?.length ?? 0) !== knowledgeIds.size
     || value.knowledge?.some((item) => item.projectId !== value.projectId
       || item.visibility !== "project")) {

package/packages/protocol/schema.ts

@@ -31,6 +31,8 @@ import {
 } from "./messages/mesh";
 import { MachineLoad } from "./messages/machine";
 import { PairingJoin } from "./messages/pairing-join";
+import { ControllerPairOffer, ControllerPairRequest } from "./messages/device/controller-pairing";
+import { KnowledgeWrite, KnowledgeWriteResult } from "./messages/mesh/knowledge/write";
 import { MeshInvocationPage, MeshInvocationQuery } from "./messages/mesh/invocations";
 import {
   ProjectPolicyAck,
@@ -63,6 +65,8 @@ export * from "./messages/capabilities";
 export * from "./messages/interaction";
 export * from "./messages/machine";
 export * from "./messages/pairing-join";
+export * from "./messages/device/controller-pairing";
+export * from "./messages/mesh/knowledge/write";
 export * from "./messages/mesh";
 export * from "./messages/mesh/invocations";
 export * from "./messages/primitives";
@@ -147,6 +151,10 @@ export const Payload = z.union([
   MachineHeartbeat,
   MachineLoad,
   PairingJoin,
+  ControllerPairRequest,
+  ControllerPairOffer,
+  KnowledgeWrite,
+  KnowledgeWriteResult,
 ]).superRefine((payload, ctx) => {
   if (payload.type !== "user.message") return;
   const encodedCharacters = payload.attachments?.reduce(