granttap-mcp 0.8.21 → 0.8.22

package/README.md

@@ -80,12 +80,34 @@ separate from their path identity. Missing content evidence remains unknown.
 
 <p align="center">
   <img src="docs/images/iphone-projects-shared.png" width="200" alt="Projects: one owned by this phone, one shared by another">
+  <img src="docs/images/iphone-linked-projects.png" width="200" alt="Two linked Projects with separate access scopes">
   <img src="docs/images/iphone-project-mesh.png" width="200" alt="A Project: Governance, members and computers, Mesh status, repositories, Tasks">
   <img src="docs/images/iphone-task-route.png" width="200" alt="A Task: executions, Runtime history, and resource claims">
   <img src="docs/images/iphone-handoff.png" width="200" alt="Task handoff: destination, push, and readiness checks">
 </p>
 
-<p align="center"><em>Projects, one of them shared by another phone · a Project with its Governance, members, computers, repositories, and Tasks · a Task with executions, Runtime history, and claims · a handoff with its readiness checks</em></p>
+<p align="center"><em>Shared Projects · linked repository bindings with separate Project access · Project management · Task execution history · handoff readiness</em></p>
+
+<p align="center">
+  <img src="docs/images/iphone-weavatrix-graph.png" width="200" alt="Full-screen architecture graph with sample evidence">
+  <img src="docs/images/iphone-health-code-towers.png" width="200" alt="Full-screen Health code towers with sample evidence">
+</p>
+
+<p align="center"><em>These are deterministic simulator fixtures, not reports from a live customer repository.</em></p>
+
+An authenticated controller can request a separate, one-time device credential
+for another iPhone or iPad from each Live linked computer. The phone packages
+the resulting links in an encrypted, single-use QR. This adds the new phone to
+the same device network; it does not grant Project membership. Explicit human
+decisions for a bound Project Task can be recorded through Engine Memory, and
+a same-scope correction supersedes an earlier decision while retaining history.
+The computer returns `recorded` only after the Engine confirms storage.
+
+The capability catalog distinguishes local observations from installed and
+initialized state. It does not yet transfer and apply complete MCP or skill
+bundles to every host. Usage figures do not enforce spending caps. Project
+Environment secrets injected into an agent process remain readable by that
+process; a use-only credential broker is not part of this runtime yet.
 
 For Claude Code, Codex, and Cursor, the provider hook runs inside the agent's
 own session and sees the exact call. GrantTap attributes every `notify` to the

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

@@ -2,4 +2,9 @@
 
 This module discovers provider-configured MCP servers and available skills. Metadata probing is isolated because it may start an MCP transport; local descriptors and skill discovery remain read-only.
 
+Skill digests cover the bounded bundle, including scripts and references.
+Catalog observations and Project requests do not install a skill or native MCP
+configuration on another host. Availability requires a separate native apply
+and independently observed initialization; that rollout is still unfinished.
+
 License: this module is distributed under the MIT License in the repository-root `LICENSE` file.

package/apps/bridge/src/cortex/integration.ts

@@ -14,6 +14,7 @@ import type { ScopedMeshView } from "../mesh/snapshot/scoped-view";
 import { loadRuntimeConfig } from "../config/runtime";
 import { computerId } from "../mesh/identity/computer";
 import { defaultCortexConfig } from "./config";
+import { activeProjectKnowledge, activeScopedKnowledge, unrecordedKnowledgeEvents } from "../mesh/knowledge/active";
 
 type CortexDependencies = {
   provenance?: typeof projectEngineProvenance;
@@ -109,15 +110,16 @@ export function cortexSnapshotEvidence(
     `repository.${graph.repositoryId}`, "weavatrix.repository", JSON.stringify(graph),
     "high", "verified", "graph", graph.revision,
   ));
-  const knowledge = (snapshot.knowledge ?? []).filter((record) =>
+  const knowledge = activeProjectKnowledge(snapshot.projectId, snapshot.knowledge ?? []).filter((record) =>
     record.taskId === taskId || record.visibility === "project").slice(0, 16);
   for (const record of knowledge) evidence.push(item(
     `knowledge.${record.recordId}`, "weavatrix.memory", JSON.stringify(record),
     "high", "unverified", "memory", `memory:${record.streamVersion}`,
   ));
-  const recorded = new Set(knowledge.map((record) => record.sourceRef));
-  for (const event of snapshot.events.filter((value) => value.taskId === taskId
-    && !recorded.has(value.eventId)).slice(-32)) {
+  for (const event of unrecordedKnowledgeEvents(
+    snapshot.events.filter((value) => value.taskId === taskId),
+    snapshot.knowledge ?? [], snapshot.supersededKnowledgeRecordIds,
+  ).slice(-32)) {
     evidence.push(item(
       `event.${event.eventId}`, "mesh.event", JSON.stringify(event),
       "normal", "unverified", "memory", `event:${event.createdAt}`,
@@ -145,13 +147,14 @@ export function cortexScopedEvidence(view: ScopedMeshView): EngineContextEvidenc
     `repository.${graph.repositoryId}`, "weavatrix.repository", JSON.stringify(graph),
     "high", "verified", "graph", graph.revision,
   ));
-  const knowledge = (view.knowledge ?? []).slice(0, 16);
+  const knowledge = activeScopedKnowledge(view.project.projectId, view.knowledge ?? [], taskId).slice(0, 16);
   for (const record of knowledge) evidence.push(item(
     `knowledge.${record.recordId}`, "weavatrix.memory", JSON.stringify(record),
     "high", "unverified", "memory", `memory:${record.streamVersion}`,
   ));
-  const recorded = new Set(knowledge.map((record) => record.sourceRef));
-  for (const event of view.events.filter((value) => !recorded.has(value.eventId)).slice(-32)) evidence.push(item(
+  for (const event of unrecordedKnowledgeEvents(
+    view.events, view.knowledge ?? [], view.supersededKnowledgeRecordIds,
+  ).slice(-32)) evidence.push(item(
     `event.${event.eventId}`, "mesh.event", JSON.stringify(event),
     "normal", "unverified", "memory", `event:${event.createdAt}`,
   ));

package/apps/bridge/src/engine/protocol/engine-memory-protocol.ts

@@ -12,6 +12,7 @@ export type KnowledgeRecordInput = {
   visibility: KnowledgeVisibility;
   repository_id?: string | null;
   commit_sha?: string | null;
+  supersedes_record_id?: string | null;
   recorded_at: number;
 };
 
@@ -28,6 +29,7 @@ export type MemoryEngineOperation =
   | { operation: "memory.history"; input: {
     project_id: string; task_id?: string | null; visibility?: KnowledgeVisibility | null;
     before_version?: number | null; limit?: number | null;
+    include_superseded?: boolean;
   } };
 export type MemoryEngineResult =
   | { operation: "memory.recorded"; record_id: string; stream_version: number }
@@ -62,6 +64,7 @@ export function parseMemoryResult(result: Record<string, unknown>, invalid: () =
     if (entry.repository_id != null) bounded(entry.repository_id, 512, invalid);
     if (entry.commit_sha != null && (typeof entry.commit_sha !== "string"
       || !/^[0-9a-f]{7,64}$/i.test(entry.commit_sha))) invalid();
+    if (entry.supersedes_record_id != null) bounded(entry.supersedes_record_id, 128, invalid);
     integer(entry.recorded_at, invalid);
     integer(entry.stream_version, invalid);
   }

package/apps/bridge/src/engine/runtime/engine-memory.ts

@@ -7,10 +7,11 @@ import { EngineClient } from "./engine-client";
 import { engineFeatureEnabled, type EngineClientLike } from "./engine-supervisor";
 
 type Options = { env?: NodeJS.ProcessEnv; client?: EngineClientLike };
+type KnowledgeSourceWindow = Pick<MeshSnapshot, "projectId" | "events">;
 let sharedClient: EngineClient | undefined;
 const synced = new Set<string>();
 const pendingSyncs = new Map<string, Promise<void>>();
-const nextIndex = new Map<string, number>();
+const queuedSyncs = new Map<string, { snapshot: KnowledgeSourceWindow; options: Options }>();
 
 function client(options: Options): EngineClientLike {
   return options.client ?? (sharedClient ??= new EngineClient({
@@ -34,23 +35,36 @@ export async function projectKnowledge(
 ): Promise<ProjectKnowledgeRecord[] | undefined> {
   if (!engineFeatureEnabled(options.env ?? process.env)) return undefined;
   try {
-    const result = await client(options).request({
-      operation: "memory.history",
-      input: { project_id: projectId, task_id: taskId,
-        visibility: taskId ? undefined : "project", limit: 32 },
-    }, { timeoutMs: 250 });
-    if (result.operation !== "memory.history" || result.page.project_id !== projectId) return undefined;
-    return result.page.entries.filter((entry) => taskId
-      ? entry.task_id === taskId || entry.visibility === "project"
-      : entry.visibility === "project").map((entry) => ({
-      projectId: entry.project_id, taskId: entry.task_id,
-      recordId: entry.record_id, category: entry.category,
-      content: entry.content, source: entry.source,
-      sourceRef: entry.source_ref, visibility: entry.visibility,
-      repositoryId: entry.repository_id ?? undefined,
-      commitSha: entry.commit_sha ?? undefined,
-      recordedAt: entry.recorded_at, streamVersion: entry.stream_version,
-    }));
+    const records: ProjectKnowledgeRecord[] = [];
+    let beforeVersion: number | undefined;
+    // The local Mesh cache holds at most 256 records. Read that same bounded
+    // window, including corrections, before deciding which entries are active.
+    for (let page = 0; page < 4; page += 1) {
+      const result = await client(options).request({
+        operation: "memory.history",
+        input: { project_id: projectId, task_id: taskId,
+          visibility: taskId ? undefined : "project", limit: 64,
+          include_superseded: true, before_version: beforeVersion },
+      }, { timeoutMs: 250 });
+      if (result.operation !== "memory.history" || result.page.project_id !== projectId) return undefined;
+      records.push(...result.page.entries.filter((entry) => taskId
+        ? entry.task_id === taskId || entry.visibility === "project"
+        : entry.visibility === "project").map((entry) => ({
+        projectId: entry.project_id, taskId: entry.task_id,
+        recordId: entry.record_id, category: entry.category,
+        content: entry.content, source: entry.source,
+        sourceRef: entry.source_ref, visibility: entry.visibility,
+        repositoryId: entry.repository_id ?? undefined,
+        commitSha: entry.commit_sha ?? undefined,
+        supersedesRecordId: entry.supersedes_record_id ?? undefined,
+        recordedAt: entry.recorded_at, streamVersion: entry.stream_version,
+      })));
+      const next = result.page.next_before_version;
+      if (!result.page.incomplete || next == null
+        || beforeVersion != null && next >= beforeVersion) break;
+      beforeVersion = next;
+    }
+    return records;
   } catch { return undefined; }
 }
 
@@ -86,31 +100,39 @@ export function recordsFromEvent(event: MeshEvent): KnowledgeRecordInput[] {
   return [];
 }
 
-/** Backfill the bounded event window once per process, then append only new IDs. */
-export async function syncProjectKnowledge(snapshot: MeshSnapshot, options: Options = {}): Promise<void> {
+/** Backfill retained structured events; a failed Engine write stops this pass. */
+export async function syncProjectKnowledge(snapshot: KnowledgeSourceWindow, options: Options = {}): Promise<void> {
   if (!engineFeatureEnabled(options.env ?? process.env)) return;
   const candidates = snapshot.events.flatMap(recordsFromEvent)
-    .filter((entry) => !synced.has(`${entry.project_id}\0${entry.record_id}`));
+    .filter((entry) => entry.project_id === snapshot.projectId
+      && !synced.has(`${entry.project_id}\0${entry.record_id}`))
+    .slice(-512);
   if (candidates.length === 0) return;
-  const start = (nextIndex.get(snapshot.projectId) ?? 0) % candidates.length;
-  const count = Math.min(candidates.length, 16);
-  nextIndex.set(snapshot.projectId, start + count);
-  for (let offset = 0; offset < count; offset += 1) {
-    const entry = candidates[(start + offset) % candidates.length]!;
-    const key = `${entry.project_id}\0${entry.record_id}`;
-    if (await recordProjectKnowledge(entry, options)) {
-      synced.add(key);
-      if (synced.size > 4_096) synced.delete(synced.values().next().value!);
+  for (const [index, entry] of candidates.entries()) {
+    if (index > 0 && index % 16 === 0) {
+      await new Promise<void>((resolve) => setTimeout(resolve, 0));
     }
+    const key = `${entry.project_id}\0${entry.record_id}`;
+    if (!await recordProjectKnowledge(entry, options)) break;
+    synced.add(key);
+    if (synced.size > 4_096) synced.delete(synced.values().next().value!);
   }
 }
 
 /** Publish never waits for the memory backfill; one bounded writer runs per Project. */
-export function queueProjectKnowledgeSync(snapshot: MeshSnapshot): void {
-  if (pendingSyncs.has(snapshot.projectId)) return;
-  const pending = syncProjectKnowledge(snapshot);
+export function queueProjectKnowledgeSync(snapshot: KnowledgeSourceWindow, options: Options = {}): void {
+  if (pendingSyncs.has(snapshot.projectId)) {
+    queuedSyncs.set(snapshot.projectId, { snapshot, options });
+    return;
+  }
+  const pending = syncProjectKnowledge(snapshot, options);
   pendingSyncs.set(snapshot.projectId, pending);
   void pending.catch(() => undefined).finally(() => {
-    if (pendingSyncs.get(snapshot.projectId) === pending) pendingSyncs.delete(snapshot.projectId);
+    if (pendingSyncs.get(snapshot.projectId) !== pending) return;
+    pendingSyncs.delete(snapshot.projectId);
+    const next = queuedSyncs.get(snapshot.projectId);
+    if (!next) return;
+    queuedSyncs.delete(snapshot.projectId);
+    queueProjectKnowledgeSync(next.snapshot, next.options);
   });
 }

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

@@ -55,6 +55,13 @@ function mcpObservation(
   if (candidates.length === 0) return { state: "not_found" };
   const digests = new Set(candidates.map((server) => server.configDigest).filter(Boolean));
   const artifactDigest = digests.size === 1 ? [...digests][0] : undefined;
+  if (request.artifactDigest) {
+    if (candidates.some((server) => server.configDigest
+      && server.configDigest !== request.artifactDigest)) {
+      return { state: "version_conflict", artifactDigest };
+    }
+    if (candidates.some((server) => !server.configDigest)) return { state: "unsupported" };
+  }
   if (!request.artifactDigest) {
     if (digests.size > 1) return { state: "version_conflict" };
     if (digests.size === 1 && candidates.some((server) => !server.configDigest)) {

package/apps/bridge/src/mesh/context/env.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { ProjectEnvironment, ProjectEnvVar } from "../../../../../packages/protocol/schema";
 import { ProjectEnvironment as EnvironmentSchema } from "../../../../../packages/protocol/schema";
@@ -10,6 +10,7 @@ type StoreFile = { environments: ProjectEnvironment[] };
 const PROTECTED_KEYS = new Set([
   "HOME", "PATH", "SHELL", "USER", "LOGNAME", "TMPDIR", "NODE_OPTIONS",
 ]);
+const MANAGED_HEADER = "# GrantTap Project environment. Secrets stay on the Mesh, not here.";
 
 function protectedRuntimeKey(key: string): boolean {
   return PROTECTED_KEYS.has(key)
@@ -76,6 +77,7 @@ export function rememberEnvironment(
 ): ProjectEnvironment | undefined {
   const others = loadAll().filter((item) => item.projectId !== projectId);
   if (!environment) {
+    if (repositoryRoot) removeManagedRepoEnv(repositoryRoot);
     saveAll(others);
     return undefined;
   }
@@ -83,6 +85,8 @@ export function rememberEnvironment(
   const stored = mergeEnvironment({ ...environment, projectId }, loadEnvironment(projectId));
   if (stored.shareNonSecretsWithRepo && repositoryRoot) {
     writeRepoEnv(repositoryRoot, stored.variables);
+  } else if (repositoryRoot) {
+    removeManagedRepoEnv(repositoryRoot);
   }
   saveAll([...others, stored]);
   return stored;
@@ -120,13 +124,39 @@ export function writeRepoEnv(root: string, variables: ProjectEnvVar[]): void {
     .map((item) => `${item.key}=${escapeEnv(item.value ?? "")}`);
   const path = repoEnvPath(root);
   mkdirSync(dirname(path), { recursive: true });
+  if (!lstatSync(dirname(path)).isDirectory()) throw new Error("repository export directory is unsafe");
+  const stat = lstatSync(path, { throwIfNoEntry: false });
+  if (stat) {
+    if (!stat.isFile() || !readFileSync(path, "utf8").startsWith(`${MANAGED_HEADER}\n`)) {
+      throw new Error("repository environment file is not managed by GrantTap");
+    }
+  }
   writeFileSync(
     path,
-    `${["# GrantTap Project environment. Secrets stay on the Mesh, not here.", ...lines].join("\n")}\n`,
+    `${[MANAGED_HEADER, ...lines].join("\n")}\n`,
     { mode: 0o644 },
   );
 }
 
+/** Revoking a share removes a managed export and reports unsafe leftovers. */
+export function removeManagedRepoEnv(root: string): boolean {
+  const path = repoEnvPath(root);
+  try {
+    if (!lstatSync(dirname(path)).isDirectory()) {
+      throw new Error("repository environment directory is unsafe");
+    }
+    if (!lstatSync(path).isFile()
+      || !readFileSync(path, "utf8").startsWith(`${MANAGED_HEADER}\n`)) {
+      throw new Error("repository environment file is not managed by GrantTap");
+    }
+    unlinkSync(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
 function escapeEnv(value: string): string {
   if (!/[\s#"\\]/.test(value)) return value;
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;

package/apps/bridge/src/mesh/context/project.ts

@@ -5,6 +5,9 @@
 import type { ScopedMeshView } from "../snapshot/scoped-view";
 import { compileMeshContext } from "./packet";
 import { projectKnowledge } from "../../engine/runtime/engine-memory";
+import {
+  activeScopedKnowledge, supersededScopedKnowledgeIds, unrecordedKnowledgeEvents,
+} from "../knowledge/active";
 
 export type ProjectContextMode = "compact" | "full" | "legacy";
 
@@ -139,8 +142,16 @@ export async function renderProjectContext(
   const local = await projectKnowledge(view.project.projectId, view.execution.taskId);
   const records = new Map((view.knowledge ?? []).map((item) => [item.recordId, item]));
   for (const item of local ?? []) records.set(item.recordId, item);
-  const scoped = { ...view, knowledge: [...records.values()]
-    .sort((a, b) => b.recordedAt - a.recordedAt).slice(0, 32) };
+  const all = [...records.values()];
+  const supersededKnowledgeRecordIds = [...new Set([
+    ...(view.supersededKnowledgeRecordIds ?? []),
+    ...supersededScopedKnowledgeIds(view.project.projectId, all, view.execution.taskId),
+  ])];
+  const scoped = { ...view,
+    knowledge: activeScopedKnowledge(view.project.projectId, all, view.execution.taskId)
+      .sort((a, b) => b.recordedAt - a.recordedAt).slice(0, 32),
+    supersededKnowledgeRecordIds,
+    events: unrecordedKnowledgeEvents(view.events, all, supersededKnowledgeRecordIds) };
   const contextPacket = await compileMeshContext(scoped);
   if (mode === "compact") return { ...renderCompactProjectContext(scoped), contextPacket };
   if (mode === "legacy") {

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

@@ -0,0 +1,14 @@
+# Mesh knowledge projection
+
+`active.ts` filters a Project's bounded phone projection using recorded
+supersession links. The Engine journal remains the durable source and retains
+the complete audit history. A correction only hides an earlier record when both
+records have the same Project, visibility, category, and repository scope.
+
+`write.ts` accepts an explicit human decision for an existing Task on a locally
+bound Project, records it through Engine Memory, and returns a `recorded` receipt
+only after the Engine confirms. A correction carries the old record ID; the
+Engine validates its scope. The phone may replay the same ID after a lost reply.
+This is not a migration of old chats into verified knowledge.
+
+MIT License.

package/apps/bridge/src/mesh/knowledge/active.ts

@@ -0,0 +1,64 @@
+import { createHash } from "node:crypto";
+import type { MeshEvent, ProjectKnowledgeRecord } from "../../../../../packages/protocol/schema";
+
+/** Supersession is monotone across stale Mesh snapshots; only a same-scope record can hide another. */
+export function activeProjectKnowledge(
+  projectId: string, records: ProjectKnowledgeRecord[],
+): ProjectKnowledgeRecord[] {
+  return activeScopedKnowledge(projectId, records);
+}
+
+/** Task-private records stay available only to their own Task. */
+export function activeScopedKnowledge(
+  projectId: string, records: ProjectKnowledgeRecord[], taskId?: string,
+): ProjectKnowledgeRecord[] {
+  const scoped = records.filter((item) => item.projectId === projectId
+    && (item.visibility === "project" || item.visibility === "task" && item.taskId === taskId));
+  const byId = new Map(scoped.map((item) => [item.recordId, item]));
+  const superseded = new Set(scoped.flatMap((item) => {
+    const previous = item.supersedesRecordId && byId.get(item.supersedesRecordId);
+    return previous && previous.category === item.category
+      && previous.visibility === item.visibility
+      && previous.repositoryId === item.repositoryId
+      && (item.visibility !== "task" || previous.taskId === item.taskId)
+      ? [previous.recordId] : [];
+  }));
+  return scoped.filter((item) => !superseded.has(item.recordId));
+}
+
+/** Keep correction tombstones even when the old record is outside the phone's bounded page. */
+export function supersededProjectKnowledgeIds(
+  projectId: string, records: ProjectKnowledgeRecord[],
+): string[] {
+  return supersededScopedKnowledgeIds(projectId, records);
+}
+
+export function supersededScopedKnowledgeIds(
+  projectId: string, records: ProjectKnowledgeRecord[], taskId?: string,
+): string[] {
+  return [...new Set(records.filter((item) => item.projectId === projectId
+    && (item.visibility === "project" || item.visibility === "task" && item.taskId === taskId))
+    .sort((left, right) => right.recordedAt - left.recordedAt)
+    .flatMap((item) => item.supersedesRecordId ? [item.supersedesRecordId] : [])
+    .slice(0, 128))].sort();
+}
+
+/** Keep unrelated event context, but remove decisions already recorded or corrected. */
+export function unrecordedKnowledgeEvents(
+  events: MeshEvent[], records: ProjectKnowledgeRecord[], supersededIds: string[] = [],
+): MeshEvent[] {
+  const covered = new Set([...records.map((item) => item.recordId), ...supersededIds]);
+  return events.flatMap((event) => {
+    const capsule = event.eventType === "HANDOFF_REQUEST" ? event.payload.capsule : undefined;
+    if (capsule) {
+      const importantDecisions = capsule.importantDecisions.filter((_, index) => {
+        const id = `capsule-${createHash("sha256")
+          .update(JSON.stringify([event.eventId, index])).digest("hex")}`;
+        return !covered.has(id);
+      });
+      return [{ ...event, payload: { ...event.payload,
+        capsule: { ...capsule, importantDecisions } } }];
+    }
+    return covered.has(event.eventId) ? [] : [event];
+  });
+}

package/apps/bridge/src/mesh/knowledge/write.ts

@@ -0,0 +1,45 @@
+import type { KnowledgeWrite, KnowledgeWriteResult } from "../../../../../packages/protocol/schema";
+import type { KnowledgeRecordInput } from "../../engine/protocol/engine-memory-protocol";
+
+type Scope = {
+  tasks: Array<{ taskId: string }>;
+  bindings: Array<{ endpointId: string }>;
+};
+
+type Dependencies = {
+  now: () => number;
+  endpointId: string;
+  snapshot: (projectId: string) => Scope | undefined;
+  record: (input: KnowledgeRecordInput) => Promise<boolean>;
+  send: (result: KnowledgeWriteResult) => Promise<void>;
+};
+
+/** A person's confirmed statement enters Memory only through a bound Project/Task. */
+export async function handleKnowledgeWrite(
+  request: KnowledgeWrite, deps: Dependencies,
+): Promise<boolean> {
+  const now = deps.now();
+  const scope = deps.snapshot(request.projectId);
+  let reason: string | undefined;
+  if (!scope || !scope.bindings.some((item) => item.endpointId === deps.endpointId)
+    || !scope.tasks.some((item) => item.taskId === request.taskId)) {
+    reason = "Project, Task, or local computer binding is unavailable.";
+  } else if (Math.abs(now - request.createdAt) > 5 * 60_000) {
+    reason = "Decision request expired. Try again.";
+  } else {
+    const input: KnowledgeRecordInput = {
+      project_id: request.projectId, task_id: request.taskId,
+      record_id: request.recordId, category: "decision", content: request.content,
+      source: "user_decision", source_ref: `phone:${request.recordId}`,
+      visibility: "project", recorded_at: request.createdAt,
+      ...(request.repositoryId ? { repository_id: request.repositoryId } : {}),
+      ...(request.supersedesRecordId
+        ? { supersedes_record_id: request.supersedesRecordId } : {}),
+    };
+    if (!await deps.record(input)) reason = "Memory did not confirm the decision.";
+  }
+  await deps.send({ type: "knowledge.write.result", projectId: request.projectId,
+    taskId: request.taskId, recordId: request.recordId,
+    status: reason ? "rejected" : "recorded", ...(reason ? { reason } : {}), createdAt: now });
+  return true;
+}

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

@@ -38,6 +38,7 @@ import { handoffReadiness } from "../tasks/readiness";
 import { createHandoffFlow } from "./handoff";
 import type { MeshRuntimeDependencies } from "./dependencies";
 import { localMeshStore } from "../local-remote/local";
+import { activeProjectKnowledge, supersededProjectKnowledgeIds } from "../knowledge/active";
 import { createHandoffWorktree, repositoryHasCommit } from "./worktree";
 import { fetchRevision, pushBranch } from "../local-remote/remote";
 import { projectSessionCapabilityInventory, projectExecutionCapabilitySessions } from "./capabilities";
@@ -249,7 +250,10 @@ export function requestProjectCapability(input: ProjectCapabilityRequestSet): bo
 export async function meshSnapshotsWithEngine(): Promise<MeshSnapshot[]> {
   return Promise.all(meshSnapshots().map(async (snapshot) => {
     await waitForProjectBindingSync(snapshot.projectId);
-    queueProjectKnowledgeSync(snapshot);
+    queueProjectKnowledgeSync({
+      projectId: snapshot.projectId,
+      events: localMeshStore().historyEventsForProject(snapshot.projectId),
+    });
     const [backbone, repositoryGraphs, knowledge] = await Promise.all([
       projectBackbone(snapshot.projectId),
       projectRepositoryGraphs(snapshot.projectId, snapshot.bindings ?? [], {
@@ -262,8 +266,15 @@ export async function meshSnapshotsWithEngine(): Promise<MeshSnapshot[]> {
     if (sharedKnowledge) localMeshStore().cacheKnowledge(snapshot.projectId, sharedKnowledge);
     const memoryRows = new Map((snapshot.knowledge ?? []).map((item) => [item.recordId, item]));
     for (const item of sharedKnowledge ?? []) memoryRows.set(item.recordId, item);
+    const allMemory = [...memoryRows.values()];
+    const correctedIds = [...new Set([
+      ...(snapshot.supersededKnowledgeRecordIds ?? []),
+      ...supersededProjectKnowledgeIds(snapshot.projectId, allMemory),
+    ])].sort().slice(-128);
     const enriched = { ...snapshot, backbone, repositoryGraphs,
-      knowledge: [...memoryRows.values()].sort((a, b) => b.recordedAt - a.recordedAt).slice(0, 16) };
+      knowledge: activeProjectKnowledge(snapshot.projectId, allMemory)
+        .sort((a, b) => b.recordedAt - a.recordedAt).slice(0, 16),
+      ...(correctedIds.length > 0 ? { supersededKnowledgeRecordIds: correctedIds } : {}) };
     const cortex = await projectCortexIntegration(enriched);
     return {
       ...enriched,

package/apps/bridge/src/mesh/snapshot/scoped-view.ts

@@ -10,6 +10,7 @@ import type { ExecutionCapability } from "../catalog/capability";
 import { liveExecutionScope } from "../catalog/capability";
 import { otherSide, type OtherSideRow } from "../handoff/other-side";
 import { scopedOverlapKind } from "../store/support";
+import { unrecordedKnowledgeEvents } from "../knowledge/active";
 
 const MAX_SCOPED_EVENTS = 32;
 const MAX_NEIGHBOURS = 32;
@@ -44,6 +45,7 @@ export type ScopedMeshView = {
   environment?: MeshSnapshot["environment"];
   cortex?: NonNullable<MeshSnapshot["cortex"]>;
   knowledge?: NonNullable<MeshSnapshot["knowledge"]>;
+  supersededKnowledgeRecordIds?: NonNullable<MeshSnapshot["supersededKnowledgeRecordIds"]>;
   /** Other Tasks working right now on the far side of this Task's repository. */
   otherSide: OtherSideRow[];
   dependencies: MeshSnapshot["dependencies"];
@@ -121,9 +123,11 @@ export function scopedMeshView(
     cortex: snapshot.cortex ?? [],
     knowledge: snapshot.knowledge?.filter((item) => item.taskId === capability.taskId
       || item.visibility === "project"),
+    supersededKnowledgeRecordIds: snapshot.supersededKnowledgeRecordIds,
     otherSide: otherSide(snapshot, capability.taskId),
     dependencies: snapshot.dependencies,
-    events: scopedEvents(snapshot, capability),
+    events: unrecordedKnowledgeEvents(scopedEvents(snapshot, capability),
+      snapshot.knowledge ?? [], snapshot.supersededKnowledgeRecordIds),
     allowedEventTypes: capability.allowedEventTypes,
   };
 }

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/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.22</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/cursor-plugin/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "granttap",
   "displayName": "GrantTap",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "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.",
   "author": {
     "name": "GrantTap",

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.22
 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.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.22\";\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.21";
+const PACKAGE = "granttap-mcp@0.8.22";
 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.22",
   "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(