@staix/agent-mem 0.13.0 → 0.15.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Bounded project memory tools and seven deterministic capture hooks, without a resident worker.",
   "mcpServers": {
     "agent-mem": {

package/README.md

@@ -2,7 +2,7 @@
 
 Curated memory with append-only JSONL logs, a derived SQLite index, short- and long-term tiers, a typed graph, goals with leases, and git sync between machines. Extracted from [agent-hub](https://github.com/STAIxBWLB/agent-hub), with compatible storage and entry IDs.
 
-Version: 0.13.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.15.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 
@@ -300,7 +300,7 @@ Prune apply still requires a sealed JSON plan. Save `amem prune --dry-run --cuto
 
 Intake runs at the end of each Codex, Kimi, Pi and Qwen session once `amem setup <cli> --apply` has registered it. Sync is off unless you ask for it: amem registers no sync hook and runs nothing between sessions. To sync on a schedule you have authorized, call `amem sync --if-due` from the chosen shell or scheduler; it has no TTY gate. This release registers no sync schedule or hook, and the configured privacy and remote-visibility checks still apply. It syncs at most hourly, backs off 15 minutes doubling to a day after failures, stops after 30 seconds, and does nothing without a remote set by `amem sync --remote <private git url>`. `--force` skips the schedule and the backoff.
 
-Split-home sync durably holds verified foreign-generation prunes with a "held, not applied" warning while unrelated sync continues; targets can remain visible, and full cross-generation removal remains a separate ceiling (see [the sync contract](docs/contracts.md#per-shard-private-sync-15-t3)).
+V1 split-home sync durably holds verified foreign-generation prunes with a "held, not applied" warning. The opt-in v2 path below applies eligible complete same-realm public prunes across generations after durable proof and root-map commitment. Unsupported historical lineage and multi-realm translations remain held; targets can remain visible and agent-mem#15 AC4 stays open (see [the sync contract](docs/contracts.md#per-shard-private-sync-15-t3)).
 
 ## Native transcript intake
 
@@ -481,3 +481,22 @@ Run `amem consolidate [--project <current-key>]` (another project is refused) to
 The CLI runs the deterministic pass only. A library host may explicitly enable an injected model callback for the person; no provider is built in. It has batch, byte, deadline and persistent daily limits. Model answers remain marked machine-local candidates that cannot be accepted; `amem note add` is the separate path for an independently authored note. A non-answer is never saved.
 
 Agents use `amem_evidence` with a question to get cited, live curated entries, not an answer. The complete JSON bundle is byte-capped (`maxBytes`, default 4096, range 256..8192); excerpted entries retain an exact `mem:` reference for fetching the full note. Capture, repository-only rows, pending candidates and model answers are excluded. amem makes no model call for this tool. Rendering a citation in the bundle records only `rendered` after successful output, never `delivered` or `cited`.
+
+### Public prune view and v2 sync (opt-in)
+
+On an active curated split, the person can preview and enable the forward-only v2 reader floor. This keeps the receiving generation and native logs/seals, builds a separate `index-v2.db`, and preserves every native/local mask. Once activated, explicit sync uses the v2 transport and can install complete generation-neutral public-prune proof; historical hold receipts alone never authorize a mask.
+
+```sh
+AMEM_HOME=/path/to/synthetic-memory amem migrate --public-prune-view --dry-run
+AMEM_HOME=/path/to/synthetic-memory amem migrate --public-prune-view --apply
+# Finish an interrupted activation, using its exact recorded forward state.
+AMEM_HOME=/path/to/synthetic-memory amem migrate --public-prune-view --resume
+```
+
+Dry-run writes nothing and reports mask building as deferred. Close cooperating reader handles for initial v1-to-v2 activation or its resume, and install compatible hosts first: older readers reject the new markers and transport tip. Initial activation preserves all native/local masks and currently performs ten old/new comparison rebuilds per realm across five verification passes, plus snapshot/index work. Deactivation is refused because v1 would omit foreign masks. Unannounced historical readers can still inspect unchanged old bytes; this is logical masking, not erasure.
+
+The first explicit v2 `amem sync` primes a private create-once publisher boundary for each selected shard/current machine. Only complete own prune rows appended after that boundary can receive new `post-seal` lineage; all earlier rows and unsupported historical lineage stay ineligible. Sync never infers a native-generation claim or rewrites native seals/rows. Both machines need compatible v2 readers and explicit sync. Stable exact project/user refs make a one-way v1-to-v2 history transition; returning a ref to v1 is refused.
+
+Sync validates all selected history and complete raw Git proof, and checks each realm's aggregate input/archive capacity before atomic publication. It then fsyncs immutable inputs and commits the root map before ordinary/native imports, preventing an unmasked first import. Already-v2 map advances preserve generation/format and monotone ancestry, use a forward-only intent and rebind existing readers without requiring them to close. A reader waits at most 3000 ms for a v2 writer; an unresolved intent, incompatible marker pair or missing committed proof reports unavailable. The same `--resume` command completes an interrupted advance forward. Read and capture never activate, prime a boundary or repair a pending operation.
+
+`SyncResult.pruneApplication` reports transport durability, complete-proof count, neutral projection activity, native application, held count and phase separately. Transport durability alone does not establish completed local application. Historical multi-realm translations and older unsupported lineage retain "held, not applied" warnings, so agent-mem#15 AC4 remains open. The [full contract](docs/generation-neutral-prune-witness.md) states the owned-source integrity and resource ceilings; this source behavior does not establish release or live-host verification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
     "@staix/agent-mem-v02": "npm:@staix/agent-mem@0.2.0",
     "@staix/agent-mem-pre-vault": "npm:@staix/agent-mem@0.3.1",
     "@staix/agent-mem-v011": "npm:@staix/agent-mem@0.11.0",
-    "@staix/agent-mem-v012": "npm:@staix/agent-mem@0.12.0"
+    "@staix/agent-mem-v012": "npm:@staix/agent-mem@0.12.0",
+    "@staix/agent-mem-v013": "npm:@staix/agent-mem@0.13.0"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/cli-agent-reads.ts

@@ -6,6 +6,16 @@ import type { ParsedCommand } from "./commands-table.ts";
 
 const UNAVAILABLE = "Memory operation unavailable or refused; no partial result is shown.";
 const RESULT_BYTES = 262_144;
+const AGENT_READS = "Agent reads: search, list, show, brief, graph, vault-candidates, capacity.";
+
+/** A refusal decided from the parsed command alone, before any store or file is opened: safe to show as is. */
+export class AgentUsageError extends Error {
+  constructor(message: string) { super(message); this.name = "AgentUsageError"; }
+}
+const accepts = (command: string, allowed: readonly string[]) => new AgentUsageError(allowed.length
+  ? `agent-marked ${command} accepts only ${allowed.length === 1 ? allowed[0] : `${allowed.slice(0, -1).join(", ")} and ${allowed.at(-1)}`}.`
+  : `agent-marked ${command} accepts no options.`);
+
 type ReadCall = { tool: keyof ReturnType<typeof createMemoryMcp>["tools"]; args: Record<string, unknown> };
 
 function values(argv: readonly string[], name: string): string[] {
@@ -29,50 +39,54 @@ function positiveLimit(value: string | boolean | undefined): number | undefined
 function route(parsed: ParsedCommand, argv: readonly string[]): ReadCall | undefined {
   const { path, options, positionals, definition } = parsed;
 
-  if (path[0] === "machine" && options["--label"] === undefined) throw new Error(UNAVAILABLE);
+  if (path[0] === "machine" && options["--label"] === undefined) throw new AgentUsageError(`amem machine without --label is not available to an agent-marked session. ${AGENT_READS}`);
   // Write/preview/confirmation paths continue through the guarded administrative handlers.
   if (definition.mutates !== undefined) return undefined;
-  if (path[0] === "project" && path[1] === "export") throw new Error(UNAVAILABLE);
+  if (path[0] === "project" && path[1] === "export") throw new AgentUsageError(`amem project export is not available to an agent-marked session. ${AGENT_READS}`);
   if (path[0] === "setup") return undefined;
 
   const flags = Object.keys(options).filter(key => key !== "--json" && key !== "--policy-free");
   const only = (...allowed: string[]) => flags.every(flag => allowed.includes(flag));
   const limit = positiveLimit(options["--limit"]);
-  if (options["--limit"] !== undefined && limit === undefined) throw new Error(UNAVAILABLE);
+  if (options["--limit"] !== undefined && limit === undefined) throw new AgentUsageError("--limit takes a whole number from 1 to 100.");
 
   if (path[0] === "search") {
-    if (!only("--limit", "--since", "--explain") || !positionals.join(" ").trim()) throw new Error(UNAVAILABLE);
+    if (!only("--limit", "--since", "--explain")) throw accepts("search", ["--limit", "--since", "--explain"]);
+    if (!positionals.join(" ").trim()) throw new AgentUsageError("agent-marked search needs a query.");
     return { tool: "amem_search", args: { query: positionals.join(" "), ...(limit === undefined ? {} : { limit }), ...(options["--since"] !== undefined ? { since: options["--since"] } : {}), ...(options["--explain"] === true ? { explain: true } : {}) } };
   }
   if (path[0] === "list") {
-    if (!only("--limit", "--since")) throw new Error(UNAVAILABLE);
+    if (!only("--limit", "--since")) throw accepts("list", ["--limit", "--since"]);
     return { tool: "amem_timeline", args: { ...(limit === undefined ? {} : { limit }), ...(options["--since"] !== undefined ? { since: options["--since"] } : {}) } };
   }
   if (path[0] === "show") {
-    if (!only() || positionals.length !== 1 || !positionals[0]!.trim()) throw new Error(UNAVAILABLE);
+    if (!only()) throw accepts("show", []);
+    if (positionals.length !== 1 || !positionals[0]!.trim()) throw new AgentUsageError("agent-marked show takes exactly one id.");
     return { tool: "amem_show", args: { id: positionals[0] } };
   }
   if (path[0] === "brief") {
-    if (!only("--for", "--paths", "--symbols", "--bytes") || typeof options["--for"] !== "string") throw new Error(UNAVAILABLE);
+    if (!only("--for", "--paths", "--symbols", "--bytes")) throw accepts("brief", ["--for", "--paths", "--symbols", "--bytes"]);
+    if (typeof options["--for"] !== "string") throw new AgentUsageError("agent-marked brief needs --for.");
     const rawBytes = options["--bytes"];
-    if (rawBytes !== undefined && !/^[1-9][0-9]*$/.test(String(rawBytes))) throw new Error(UNAVAILABLE);
+    if (rawBytes !== undefined && !/^[1-9][0-9]*$/.test(String(rawBytes))) throw new AgentUsageError("--bytes takes a positive whole number.");
     return { tool: "amem_brief", args: { intent: options["--for"], paths: values(argv, "--paths"), symbols: values(argv, "--symbols"), ...(rawBytes === undefined ? {} : { maxBytes: Number(rawBytes) }) } };
   }
   if (path[0] === "graph") {
-    if (!only("--hops") || positionals.length !== 1) throw new Error(UNAVAILABLE);
+    if (!only("--hops")) throw accepts("graph", ["--hops"]);
+    if (positionals.length !== 1) throw new AgentUsageError("agent-marked graph takes exactly one start id.");
     const hops = options["--hops"] === undefined ? 1 : Number(options["--hops"]);
-    if (hops !== 1 && hops !== 2) throw new Error(UNAVAILABLE);
+    if (hops !== 1 && hops !== 2) throw new AgentUsageError("--hops takes 1 or 2.");
     return { tool: "amem_graph", args: { start: positionals[0], ...(options["--hops"] === undefined ? {} : { hops }) } };
   }
   if (path[0] === "vault-candidates") {
-    if (!only("--limit") || options["--all-projects"] !== undefined || options["--project"] !== undefined) throw new Error(UNAVAILABLE);
+    if (!only("--limit") || options["--all-projects"] !== undefined || options["--project"] !== undefined) throw accepts("vault-candidates", ["--limit"]);
     return { tool: "amem_vault_candidates", args: limit === undefined ? {} : { limit } };
   }
   if (path[0] === "capacity" && path.length === 1) {
-    if (!only()) throw new Error(UNAVAILABLE);
+    if (!only()) throw accepts("capacity", []);
     return { tool: "amem_capacity", args: {} };
   }
-  throw new Error(UNAVAILABLE);
+  throw new AgentUsageError(`amem ${path.join(" ")} is not available to an agent-marked session. ${AGENT_READS}`);
 }
 
 /** Route marked-agent read commands through the same startup-bound MCP policy and handlers. */

package/src/cli.ts

@@ -1,4 +1,5 @@
-import { agentCliRead } from "./cli-agent-reads.ts";
+import { activatePublicPruneView } from "./memory/public-prune-activation.ts";
+import { AgentUsageError, agentCliRead } from "./cli-agent-reads.ts";
 import { cliAttribution, withCliAttribution } from "./memory/cli-attribution.ts";
 import { randomUUID } from "node:crypto";
 import type { Writable } from "node:stream";
@@ -211,6 +212,14 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
       if (!readable) throw new CliPartialApplyError(error.applied.length, error.jsonOutput);
       const safe = new DecayApplyError(error.report, undefined); safe.jsonOutput = error.jsonOutput; throw safe;
     }
+    // Data-free errors (decided before any store or file is opened) keep their own message.
+    if (marked && error instanceof AgentUsageError) throw error;
+    if (marked) {
+      // parseCommand is pure: when it rejects argv, the error it raised is a usage error, not memory data.
+      let usage: Error | undefined;
+      try { parseCommand(argv); } catch (parseError) { usage = parseError as Error; }
+      if (usage) throw Object.assign(new Error(usage.message), (error as { exitCode?: number }).exitCode === undefined ? {} : { exitCode: (error as { exitCode?: number }).exitCode });
+    }
     // Marked administrative failures must not reveal a target's private state or native errors.
     if (marked) throw Error("Memory operation unavailable or refused; no partial result is shown.");
     throw error;
@@ -222,14 +231,14 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
     await serveMcp({ tools: memory.tools, close: memory.close, onEmitted: memory.onEmitted, version: VERSION });
     return "";
   }
-  if (argv[0] === "hook") {
+  if (argv[0] === "hook" && !argv.includes("--help")) {
     const { hookMain } = await import("./hooks.ts");
     return hookMain(argv.slice(1));
   }
   if (argv[0] === "ingest") {
     // Capture-only native intake: no project/home override, policy bypass or curated write capability.
     const parsed = parseCommand(argv);
-    if (parsed.options["--help"] === true) return commandHelp();
+    if (parsed.options["--help"] === true) return commandHelp(argv);
     const kind = parsed.positionals[0];
     if (parsed.positionals.length !== 1 || !["codex", "kimi", "pi", "qwen"].includes(kind ?? "")) throw new Error("usage: amem ingest codex|kimi|pi|qwen [--since ISO] [--json]");
     const { ingestTranscript } = await import("./ingest.ts");
@@ -243,7 +252,7 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "version")) return `amem ${VERSION}`;
   if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "help")) return commandHelp();
   if (argv[0] === "--version" || argv[0] === "version") return `amem ${VERSION}`;
-  if (argv[0] === "--help" || argv[0] === "help" || argv.includes("--help")) return commandHelp();
+  if (argv[0] === "--help" || argv[0] === "help" || argv.includes("--help")) return commandHelp(argv);
   let parsed;
   try {
     parsed = parseCommand(argv);
@@ -344,6 +353,12 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
     if (modes.length > 1) throw new Error("migration modes are mutually exclusive");
     const mode = options["--apply"] ? "apply" : options["--resume"] ? "resume" : options["--deactivate"] ? "deactivate" : "dry-run";
     const common = { memoryDir: memoryHome(), ...(options["--generation"] ? { generation: String(options["--generation"]) } : {}), authorizedPerson: true, tty: true };
+    if (options["--public-prune-view"] === true) {
+      if (options["--deactivate"] || options["--generation"] || options["--shards"]) throw new Error("public prune view is forward-only on an active split; no deactivate, generation replacement or new split");
+      if (actor === "agent" && mode !== "dry-run") administrative({ command: "migrate --public-prune-view", mode });
+      const result = await activatePublicPruneView({ memoryDir: memoryHome(), mode: mode as "dry-run" | "apply" | "resume", authorizedPerson: true, tty: true });
+      return options["--json"] ? JSON.stringify(result, null, 2) : `public prune view: ${result.mode}; generation ${result.generation}; mask build ${result.maskBuildCheck}; forward-only, no deactivation`;
+    }
     const shardRequested = options["--shards"] === true || (mode === "resume" && shardStatePresent());
     if (shardRequested) {
       if (mode === "deactivate") throw new Error("--deactivate is not a shard migration mode");
@@ -882,7 +897,7 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   const stop = ifDue ? stopSignal(context.syncDeadlineMs ?? SYNC_IF_DUE_DEADLINE_MS, process) : undefined;
   try {
     output = await withRepoRows(await rawMemoryCommand(memoryArgs, cwd, { person: identity.actor === "person", rankedSearch: identity.actor === "person" && !legacySearch, ...(explainSearch ? { explainSearch: true } : {}), project: boundProject(), open, readable: notes => identity.actor === "person" ? notes : notes.filter(view => view.project === boundProject() && policyOf().screenStandalone(view)), stale: createRecallStalenessProbe({ cwd: recallRoot ?? cwd, rootConfirmed, policy: () => configured }), outputReady: notes => outputReady(notes.map(view => view.id)), importPolicy: () => text => configured.declinesPersonal(text),
-      sync: { screen: row => configured.screenStandalone(row), ...(stop ? { signal: stop.signal } : {}) },   // the repository-narrowed policy binds what sync publishes too
+      sync: { screen: row => configured.screenStandalone(row), policyVersion: () => JSON.stringify(configuredPolicyOptions(memoryHome(), policyCwd)), ...(stop ? { signal: stop.signal } : {}) },   // the repository-narrowed policy binds what sync publishes too
       onBridgeStatus: status => { receipt.bridgeStatus = status; } }));
   } catch (error) {
     if (sub === "sync") stampSync((error as Error).message, stop?.cause());

package/src/commands-table.ts

@@ -107,6 +107,7 @@ export const COMMANDS: Record<string, CommandDefinition> = {
     ...json, "--apply": flag("Apply the previewed migration"), "--dry-run": flag("Read-only migration receipt (default; kept as an alias)"), "--generation": text("Explicit 32-hex generation ID"),
     "--resume": flag("Resume the recorded migration"), "--deactivate": flag("Select shared v1 without deleting a generation"),
     "--shards": flag("Migrate the curated home into project and user shards"),
+    "--public-prune-view": flag("Enable the forward-only v2 public prune view on an active split"),
   } },
   status: { description: "Report shard migration and pending old-layout appends", options: json },
   doctor: { description: "One read-only report (F15): duplicates and stale notes, pending candidates, capture freshness per CLI, the brief's token cost, index equals rebuild, reader leases, the policy in effect, ingest and sync cadence", options: json },
@@ -166,7 +167,7 @@ export function parseCommand(argv: readonly string[]): ParsedCommand {
         options[token] = value;
       } else options[token] = true;
     } else if (definition.commands) {
-      const child: CommandDefinition | undefined = definition.commands[token];
+      const child: CommandDefinition | undefined = Object.hasOwn(definition.commands, token) ? definition.commands[token] : undefined;
       if (!child) throw new Error(`unknown command ${[...path, token].join(" ")}`);
       commandIndexes.add(i);
       definition = { ...definition, ...child }; path.push(token);
@@ -193,9 +194,36 @@ export function parseCommand(argv: readonly string[]): ParsedCommand {
   return { path, definition, options, positionals, rawArgs };
 }
 
-export function commandHelp(): string {
-  return ["usage: amem <command> [options]", "  [--help] [--version] [--json]", ...completionDefinitions().filter(row => row.path.length).map(row => {
-    const names = [...row.path, ...row.args.map(arg => `<${arg.name}>`)].join(" ");
-    return `  ${names}${Object.entries(row.options).map(([name, option]) => ` [${name}${option.value === undefined ? "" : ` <${Array.isArray(option.value) ? option.value.join("|") : option.value}>`}]`).join("")}`;
-  }), "--policy-free: accepted and ignored; the configured privacy policy (amem.config.json in the memory home, narrowed by .amem/config) always applies.", "Agent-marked reads use the MCP privacy ceiling. Explicit apply/confirm flags do not require a terminal; review walk and the note editor remain interactive."].join("\n");
+const optionLabel = (name: string, option: OptionDefinition) =>
+  `${name}${option.value === undefined ? "" : ` <${Array.isArray(option.value) ? option.value.join("|") : option.value}>`}`;
+const usageRow = (row: CompletionDefinition) =>
+  `${[...row.path, ...row.args.map(arg => `<${arg.name}>`)].join(" ")}${Object.entries(row.options).map(([name, option]) => ` [${optionLabel(name, option)}]`).join("")}`;
+const described = (rows: [string, string][]) => {
+  // Long enum labels (review --kind) would push every description far right; they overflow instead.
+  const width = Math.min(24, Math.max(...rows.map(([label]) => label.length)));
+  return rows.map(([label, description]) => `  ${label.padEnd(width)}  ${description}`);
+};
+
+/** Full command list, or one command's help when argv names a command path (defaultCommand is not applied). */
+export function commandHelp(argv: readonly string[] = []): string {
+  const path: string[] = [], rows = completionDefinitions();
+  let commands: Record<string, CommandDefinition> | undefined = COMMANDS, command: CommandDefinition | undefined, row = rows[0]!;
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]!;
+    if (token.startsWith("--")) {
+      // An option's value is never a command name.
+      if (!token.includes("=") && row.options[token]?.value !== undefined) i++;
+      continue;
+    }
+    if (!commands || !Object.hasOwn(commands, token)) break;
+    command = commands[token]!; path.push(token); commands = command.commands;
+    row = rows.find(candidate => candidate.path.join(" ") === path.join(" "))!;
+  }
+  if (command && path[0] !== "help") {
+    const lines = [`usage: amem ${usageRow(row)}`, "", command.description, "", "options:", ...described(Object.entries(row.options).map(([name, option]) => [optionLabel(name, option), option.description]))];
+    if (command.commands) lines.push("", "commands:", ...described(Object.entries(command.commands).map(([name, child]) => [name, child.description])));
+    return lines.join("\n");
+  }
+  return ["usage: amem <command> [options]", "  [--help] [--version] [--json]", ...completionDefinitions().filter(row => row.path.length).map(row => `  ${usageRow(row)}`),
+    "--policy-free: accepted and ignored; the configured privacy policy (amem.config.json in the memory home, narrowed by .amem/config) always applies.", "Agent-marked reads use the MCP privacy ceiling. Explicit apply/confirm flags do not require a terminal; review walk and the note editor remain interactive."].join("\n");
 }

package/src/memory/catalog.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import { chmodSync, existsSync, lstatSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { memoryBase } from "./home.ts";
-import { effectiveAliases, readShardDescriptor, SHARDED_SCHEMA } from "./shard.ts";
+import { effectiveAliases, readShardDescriptor, SHARDED_SCHEMA, SHARDED_V2_SCHEMA } from "./shard.ts";
 import { readProfileJSON, validGeneration } from "./generation.ts";
 import { captureShardStats, readCaptureConfig } from "./capture.ts";
 import { openShardStore } from "./store.ts";
@@ -36,7 +36,7 @@ const fromRow = (r: CatalogRow): CatalogProject => ({ hash: r.hash, key: r.key,
 function capturedSelection(base: string): boolean {
   const value = readProfileJSON(join(base, "shards.json")) as { schema?: unknown; generation?: unknown; phase?: unknown; selectorRevision?: unknown } | undefined;
   if (value === undefined) return false;
-  if (!value || value.schema !== SHARDED_SCHEMA || !validGeneration(value.generation) || (value.phase !== "captured" && value.phase !== "active") || typeof value.selectorRevision !== "string") throw new Error("curated shard selection is unavailable or invalid");
+  if (!value || (value.schema !== SHARDED_SCHEMA && value.schema !== SHARDED_V2_SCHEMA) || !validGeneration(value.generation) || (value.phase !== "captured" && value.phase !== "active") || typeof value.selectorRevision !== "string") throw new Error("curated shard selection is unavailable or invalid");
   return value.phase === "captured";
 }
 
@@ -48,10 +48,10 @@ function curatedStats(base: string, hash: string, key: string, captured: boolean
   if (!existsSync(join(dir, "generation.json")) && !existsSync(join(dir, "generation-seal.json"))) return { entries: 0, lastAt: null };
   const store = openShardStore({ memoryDir: base, project: key, deferPromotions: true, lifecycle: "ignore" });
   try {
-    const db = new Database(join(dir, "index.db"), { readonly: true });
+    const db = new Database(join(dir, store.profile.foreignPruneFormat ? "index-v2.db" : "index.db"), { readonly: true });
     try {
       db.run("PRAGMA busy_timeout = 0");
-      const row = db.query("SELECT COUNT(*) AS n, MAX(at) AS last FROM entries WHERE scope = 'project' AND project = ?").get(key) as { n: number; last: string | null };
+      const row = db.query("SELECT COUNT(*) AS n, MAX(at) AS last FROM entries WHERE scope = 'project' AND project = ?" + (store.profile.foreignPruneFormat ? " AND id NOT IN (SELECT id FROM generation_targets)" : "")).get(key) as { n: number; last: string | null };
       return { entries: row.n, lastAt: row.last };
     } finally { db.close(); }
   } finally { store.close(); }

package/src/memory/commands.ts

@@ -197,6 +197,10 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
         const r = await syncMemory(store, { ...opts.sync, ...(remote ? { remote } : {}) });
         if (json) return JSON.stringify(r, null, 2);
         if (!r.ok) fail(`${names.memory} sync: ${r.error}`);
+        if (r.pruneApplication) {
+          const a = r.pruneApplication;
+          return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries transported; ${a.proofComplete} prune proofs complete, ${a.projectionActive ?? "pending"} foreign projections active, ${a.nativeApplied ?? "pending"} native prunes applied, ${a.held} held${r.warning ? `\nnote: ${r.warning}` : ""}`;
+        }
         return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries visible here${r.warning ? `\nnote: ${r.warning}` : ""}`;
       }
       case "dedupe": {

package/src/memory/doctor.ts

@@ -1,6 +1,6 @@
-import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { Database } from "bun:sqlite";
 import { sessionStartBrief } from "../session-brief.ts";
 import { pendingSummary } from "./candidate-pending.ts";
@@ -87,8 +87,10 @@ class TooBig extends Error {}
 function copyTree(from: string, to: string, budget: { bytes: number }, skipNames: ReadonlySet<string> = new Set()): void {
   mkdirSync(to, { recursive: true, mode: 0o700 });
   for (const name of readdirSync(from)) {
-    if (SKIP.test(name) || skipNames.has(name)) continue;
+    const proofObject = basename(from) === "public-prune-objects" && /^[a-f0-9]{40}\.git$/.exec(name)?.[0] === name;
+    if (SKIP.test(name) && !proofObject || skipNames.has(name)) continue;
     const source = join(from, name), stat = lstatSync(source);
+    if (proofObject && !stat.isFile()) throw new Error("a public prune object is not a plain file");
     if (stat.isSymbolicLink()) throw new Error("the memory home holds a link where a plain file or directory is expected");
     if (stat.isDirectory()) copyTree(source, join(to, name), budget, skipNames);
     else if (stat.isFile()) { budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig(); copyFileSync(source, join(to, name)); }
@@ -103,6 +105,14 @@ function copyCurated(options: DoctorOptions, layout: Layout, scratch: string, bu
     const stat = statSync(join(home, name)); budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
     copyFileSync(join(home, name), join(scratch, name));
   }
+  const selected = readSelector(home).selector;
+  if (selected?.schema === "agent-mem.profile/v2") {
+    const name = `${selected.pruneInputSetHash}.json`, source = join(home, "public-prune-input-sets", name), stat = lstatSync(source);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error("the committed public prune view is not a plain file");
+    budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
+    const directory = join(scratch, "public-prune-input-sets"); mkdirSync(directory, { mode: 0o700 });
+    copyFileSync(source, join(directory, name)); chmodSync(join(directory, name), 0o600);
+  }
   if (layout === "split") {
     for (const key of [options.project, ...options.aliases]) {
       const dir = shardDir(home, key);

package/src/memory/generation-index.ts

@@ -1,16 +1,20 @@
-import { SHARDED_SCHEMA } from "./shard.ts";
+import { createPublicPruneReplayCache, type PublicPruneProjection } from "./public-prune-inputs.ts";
+import { readPublicPruneView, readPublicPruneViewForActivation } from "./public-prune-view.ts";
+import { SHARDED_SCHEMA, SHARDED_V2_SCHEMA } from "./shard.ts";
 import { readShardLegacySnapshot } from "./shard-bridge.ts";
 import type { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeSync } from "node:fs";
 import { join } from "node:path";
-import { canonicalJSON, hashJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile, validateVaultLinkRow, type VaultLink } from "./generation.ts";
+import { canonicalJSON, hashJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile, validateVaultLinkRow, type VaultLink, rebindPublicPruneProfile } from "./generation.ts";
 import { legacyEntries, legacyHead, readLegacySnapshot, SegmentReader, type LegacyCheckpoint, type LegacySegment } from "./bridge.ts";
 import { reducePruneRows, validatePruneRow, type PrunePlan, type PruneRow, type PruneSnapshot, type PruneSourceRow, type PruneStorePort } from "./prune.ts";
 import { PROMOTED_KINDS, type Entry } from "./store.ts";
 
+const FOREIGN_TABLES = ["generation_foreign_inputs", "generation_foreign_rows", "generation_foreign_targets"] as const;
 const digest = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
 const fail = (): never => { throw new Error("generation input unavailable or changed; person inspection required"); };
+class PublicPruneViewChanged extends Error { constructor() { super("public prune view changed repeatedly; retry the read"); } }
 export const GENERATION_TABLES = ["generation_vault_links", "generation_rows", "generation_prunes", "generation_targets", "generation_segments", "generation_state"] as const;
 export interface GenerationIndexOptions {
   profile: BoundProfile; db: Database; now: () => number;
@@ -65,9 +69,17 @@ export class GenerationIndex {
   private fullCapture = false;
   private retainedTail = false;
   private replayProvenance = false;
+  private foreignStamp?: string;
+  private foreignCache?: { set: string; load: () => PublicPruneProjection };
   constructor(private readonly options: GenerationIndexOptions) {
     this.profile = options.profile;
     const db = options.db;
+    if (this.profile.foreignPruneFormat) {
+      db.run("CREATE TABLE IF NOT EXISTS generation_foreign_inputs (id TEXT PRIMARY KEY)");
+      db.run("CREATE TABLE IF NOT EXISTS generation_foreign_rows (id TEXT PRIMARY KEY, hash TEXT NOT NULL)");
+      db.run("CREATE TABLE IF NOT EXISTS generation_foreign_targets (id TEXT PRIMARY KEY)");
+      this.replayProvenance = true; // persistent SQLite never supplies foreign membership
+    }
     db.run("CREATE TABLE IF NOT EXISTS generation_rows (id TEXT PRIMARY KEY, line TEXT NOT NULL, local INTEGER NOT NULL, public INTEGER NOT NULL, own INTEGER NOT NULL, legacy INTEGER NOT NULL)");
     if (!(db.query("PRAGMA table_info(generation_rows)").all() as { name: string }[]).some(row => row.name === "legacy")) { db.run("ALTER TABLE generation_rows ADD COLUMN legacy INTEGER NOT NULL DEFAULT 0"); this.replayProvenance = true; }
     db.run("CREATE TABLE IF NOT EXISTS generation_vault_links (id TEXT PRIMARY KEY, target TEXT NOT NULL, row_hash TEXT NOT NULL, project TEXT NOT NULL, path TEXT NOT NULL, at TEXT NOT NULL)");
@@ -93,9 +105,14 @@ export class GenerationIndex {
   /** Authoring handles cannot read or append a partially resumed split; migration index bootstraps use captured limits. */
   private shardFrontier(): string | undefined {
     if (!this.profile.sharded || this.options.limits !== undefined) return undefined;
-    const value = readProfileJSON(join(this.profile.home, "shards.json")) as { schema?: unknown; phase?: unknown; generation?: unknown; selectorRevision?: unknown } | undefined;
-    if (!value || value.schema !== SHARDED_SCHEMA || value.phase !== "active" || value.generation !== this.profile.generation || value.selectorRevision !== this.profile.selectorRevision) return fail();
-    return hashJSON(value);
+    for (let attempt = 0; attempt < 6; attempt++) {
+      rebindPublicPruneProfile(this.profile);
+      const value = readProfileJSON(join(this.profile.home, "shards.json")) as { schema?: unknown; phase?: unknown; generation?: unknown; selectorRevision?: unknown } | undefined;
+      if (selectorRevision(this.profile.home) !== this.profile.selectorRevision) { if (this.profile.foreignPruneFormat) continue; return fail(); }
+      if (!value || value.schema !== (this.profile.foreignPruneFormat ? SHARDED_V2_SCHEMA : SHARDED_SCHEMA) || value.phase !== "active" || value.generation !== this.profile.generation || value.selectorRevision !== this.profile.selectorRevision) return fail();
+      return hashJSON(value);
+    }
+    return fail();
   }
   private capture(reader: SegmentReader = this.reader): { segments: LegacySegment[]; commit?: string } {
     const shardBefore = this.shardFrontier();
@@ -119,7 +136,7 @@ export class GenerationIndex {
       const segment = own.find(s => s.path === old.path);
       if (!segment || segment.offset < old.offset) fail();
     }
-    if (this.shardFrontier() !== shardBefore) return fail();
+    if (this.shardFrontier() !== shardBefore) { if (this.profile.foreignPruneFormat) throw new PublicPruneViewChanged(); return fail(); }
     return { segments: [...legacy, ...own], ...(commit ? { commit } : {}) };
   }
   private index(captured: { segments: LegacySegment[]; commit?: string }): void {
@@ -161,7 +178,35 @@ export class GenerationIndex {
     const reduced = reducePruneRows(prunes, snapshot, this.profile.generation!);
     db.run("DELETE FROM generation_targets");
     for (const id of [...reduced.targets].sort()) db.query("INSERT INTO generation_targets VALUES (?)").run(id);
-    this.pruned = reduced.targets;
+    this.applyForeign(true);
+    this.pruned = new Set((db.query("SELECT id FROM generation_targets").all() as {id:string}[]).map(row => row.id));
+  }
+  private applyForeign(validateRows = false): void {
+    if (!this.profile.foreignPruneFormat) return;
+    const profile = this.profile;
+    if (!profile.pruneInputSetHash || !profile.generation || !profile.sharded) return fail();
+    const view = (this.options.limits !== undefined ? readPublicPruneViewForActivation : readPublicPruneView)(profile.home, profile.pruneInputSetHash, profile.generation);
+    const key = profile.shardUser ? "user" : `project:${profile.shardKey}`, set = view.realms[key];
+    const db = this.options.db;
+    if (!set) {
+      if ((db.query("SELECT COUNT(*) AS n FROM generation_foreign_inputs").get() as {n:number}).n) return fail();
+      return;
+    }
+    if (!this.foreignCache || this.foreignCache.set !== set) this.foreignCache = { set, load: createPublicPruneReplayCache({ dir: profile.dir,
+      realm: profile.shardUser ? { scope: "user" } : { scope: "project", key: profile.shardKey! }, receivingGeneration: profile.generation, inputSetHash: set }) };
+    const proof = this.foreignCache.load();
+    if (validateRows || this.foreignStamp !== set) for (const item of db.query("SELECT id,line FROM generation_rows").all() as {id:string;line:string}[]) {
+      const expected = proof.rowHashes.get(item.id); if (expected && hashJSON(JSON.parse(item.line)) !== expected) return fail();
+    }
+    if (validateRows || this.foreignStamp !== set) {
+    for (const table of FOREIGN_TABLES) db.run(`DELETE FROM ${table}`);
+    for (const id of proof.inputs) db.query("INSERT INTO generation_foreign_inputs VALUES (?)").run(id);
+    for (const [id, hash] of proof.rowHashes) db.query("INSERT INTO generation_foreign_rows VALUES (?,?)").run(id, hash);
+    for (const id of proof.targets) db.query("INSERT INTO generation_foreign_targets VALUES (?)").run(id);
+    this.foreignStamp = set;
+    }
+    const current = new Set((db.query("SELECT id FROM generation_targets").all() as {id:string}[]).map(row => row.id));
+    for (const id of proof.targets) if (!current.has(id)) db.query("INSERT INTO generation_targets VALUES (?)").run(id);
   }
   private recordSkipped(segment: LegacySegment): void {
     this.options.db.query("INSERT INTO generation_state VALUES (?,'1') ON CONFLICT(key) DO UPDATE SET value=CAST(CAST(value AS INTEGER)+1 AS TEXT)").run(`skipped:${segment.source}:${segment.path}`);
@@ -183,12 +228,12 @@ export class GenerationIndex {
     const before = this.frontier(), db = this.options.db;
     let input: ReturnType<GenerationIndex["capture"]>;
     try { input = this.capture(reader); }
-    catch (error) { if (attempt < 5 && this.frontier() !== before) return this.refresh(attempt + 1, reader); throw error; }
+    catch (error) { if (attempt < 5 && (error instanceof PublicPruneViewChanged || this.frontier() !== before)) return this.refresh(attempt + 1, reader); throw error; }
     if (this.frontier() !== before) { if (attempt < 5) return this.refresh(attempt + 1, reader); return fail(); }
     const known = db.query("SELECT source,path,offset,hash,commit_id,stamp FROM generation_segments").all() as { source: string; path: string; offset: number; hash: string; commit_id: string | null; stamp: string | null }[];
     const currentCommit = (db.query("SELECT value FROM generation_state WHERE key='legacyCommit'").get() as { value: string } | null)?.value;
     const unchanged = known.length === input.segments.length && currentCommit === input.commit && input.segments.every(segment => known.some(row => row.source === segment.source && row.path === segment.path && row.offset === segment.offset && row.hash === segment.hash && row.commit_id === (segment.commit ?? null) && row.stamp === (segment.stamp ?? null)));
-    if (unchanged) { this.retainedTail = input.segments.some(segment => segment.tailBytes > 0); this.pruned = new Set((db.query("SELECT id FROM generation_targets").all() as { id: string }[]).map(row => row.id)); return; }
+    if (unchanged) { if (this.profile.foreignPruneFormat) db.transaction(() => this.applyForeign()).deferred(); this.retainedTail = input.segments.some(segment => segment.tailBytes > 0); this.pruned = new Set((db.query("SELECT id FROM generation_targets").all() as { id: string }[]).map(row => row.id)); return; }
     const committed = db.transaction(() => { if (this.frontier() !== before) return false; this.index(input); return true; }).immediate();
     if (!committed) { if (attempt < 5) return this.refresh(attempt + 1, reader); return fail(); }
     this.retainedTail = input.segments.some(segment => segment.tailBytes > 0);
@@ -197,11 +242,11 @@ export class GenerationIndex {
     const before = this.frontier();
     let input: ReturnType<GenerationIndex["capture"]>;
     try { this.fullCapture = true; input = this.capture(reader); }
-    catch (error) { this.fullCapture = false; if (attempt < 5 && this.frontier() !== before) return this.rebuild(attempt + 1, reader); throw error; }
+    catch (error) { this.fullCapture = false; if (attempt < 5 && (error instanceof PublicPruneViewChanged || this.frontier() !== before)) return this.rebuild(attempt + 1, reader); throw error; }
     finally { this.fullCapture = false; }
     const committed = this.options.db.transaction(() => {
       if (this.frontier() !== before) return false;
-      for (const table of ["entries", "ops", "edges", "goals", "segments", "heads", ...GENERATION_TABLES]) this.options.db.run(`DELETE FROM ${table}`);
+      for (const table of ["entries", "ops", "edges", "goals", "segments", "heads", ...GENERATION_TABLES, ...(this.profile.foreignPruneFormat ? FOREIGN_TABLES : [])]) this.options.db.run(`DELETE FROM ${table}`);
       this.index(input); return true;
     }).immediate();
     if (!committed) { if (attempt < 5) return this.rebuild(attempt + 1, reader); return fail(); }