granttap-mcp 0.8.21 → 0.8.23

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/bin/cli/connect.ts

@@ -28,7 +28,8 @@ async function connect(relayUrl: string): Promise<void> {
       "Background helper   Run granttap setup to verify",
       "",
       "Existing pairing reused. No QR or key rotation was needed.",
-      "Use granttap reset before pairing this computer again.",
+      "To link another iPhone or iPad, open the GrantTap connection card in your coding app and choose Add another device.",
+      "To repair the same phone, choose Reconnect in that card. Do not reset the computer pairing for either action.",
       "",
     ].join("\n"));
     return;

package/apps/bridge/src/bin/cli/phone.ts

@@ -0,0 +1,54 @@
+import QRCode from "qrcode";
+import { loadConfig } from "../../config";
+import { reloadPairingHelper } from "../../install";
+import { createOneTimePairing, DEFAULT_RELAY, PAIRING_CODE_TTL_MINUTES } from "../../pairing";
+import { isMachineConfigured, readOnlyMachineConfigPath } from "../../../../mcp/src/status/pairing-status";
+import { installHttpMcpService } from "../../../../mcp/src/http-service";
+
+const mode = process.argv[2];
+
+async function main(): Promise<void> {
+  if (mode !== "add" && mode !== "reconnect") {
+    process.stderr.write("Usage: granttap phone add|reconnect\n");
+    process.exitCode = 1;
+    return;
+  }
+  if (!process.stdout.isTTY) {
+    process.stderr.write("Open an interactive terminal and run this command yourself; the private pairing QR is never written to agent logs.\n");
+    process.exitCode = 1;
+    return;
+  }
+  const paired = isMachineConfigured();
+  if (!paired && mode === "reconnect") {
+    process.stderr.write("This computer has no saved pairing. Run granttap phone add instead.\n");
+    process.exitCode = 1;
+    return;
+  }
+  const relay = paired ? loadConfig(readOnlyMachineConfigPath()).relayUrl : DEFAULT_RELAY;
+  const result = await createOneTimePairing(relay, {
+    addController: paired && mode === "add",
+    installHooks: false,
+  });
+  const helper = reloadPairingHelper({ firstPairing: !paired });
+  const mcp = installHttpMcpService({ forceReload: true });
+  const qr = await QRCode.toString(result.qrPayload, {
+    type: "terminal", small: true, errorCorrectionLevel: "L",
+  });
+  process.stdout.write([
+    "",
+    mode === "add" ? "Add a controller iPhone or iPad" : "Reconnect the same controller phone",
+    "Open GrantTap on the phone → Settings → Connections → Add a device (Scan QR).",
+    "",
+    qr,
+    "",
+    `The QR expires in ${PAIRING_CODE_TTL_MINUTES} minutes. Never paste it into chat.`,
+    ...(helper?.status === "manual" || mcp.status === "manual"
+      ? ["Background connection needs attention. Run granttap setup after scanning."] : []),
+    "",
+  ].join("\n"));
+}
+
+void main().catch((error: unknown) => {
+  process.stderr.write(`GrantTap could not issue a phone QR: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

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,
   };
 }