@staix/agent-mem 0.7.0 → 0.9.1

package/src/memory/project-export.ts

@@ -11,14 +11,14 @@ import { aliasedKeys, shardDir } from "./shard.ts";
 import { WorkListStore } from "./work-lists.ts";
 
 /**
- * #15 T5 / D3: `amem project export <key> --to <file>`. One project's capture rows, curated notes, goals and work lists as one portable JSON bundle,
- * written once to a new file with mode 0600. It changes no content file of the home: it opens the capture databases read-only and the curated store only to
+ * #15 T5 / D3 and F17: `amem project export <key> --to <file>`. One project's capture rows, curated notes, goals and work lists as a portable JSON bundle,
+ * JSONL stream or Markdown document, written once to a new file with mode 0600. It changes no content file of the home: it opens the capture databases read-only and the curated store only to
  * read, and only derived files (the curated `index.db`, `search.db`, SQLite sidecars) may refresh, as they do for any read. A destination inside the home is refused.
  *
  * The bundle leaves the home, so it is screened like sync and promotion are: a secret-looking value is withheld, and so is anything the host policy (when
  * one is passed) declines. `withheld` counts the capture rows, notes and goals left out; a work list the policy declines is left out silently by its own store.
- * A forgotten project cannot be exported (the person's decision stands); an archived one can. The write streams row by row, so a shard at its cap never has to
- * fit in memory, and a failure removes the partial file it created.
+ * A forgotten project cannot be exported (the person's decision stands); an archived one can. A failure removes the partial file it created.
+ * ponytail: JSONL capture, goal and work-list rows stream, but curated authored rows are materialized to preserve ids. Add a bounded authored-row iterator before raising shard limits.
  */
 
 export const EXPORT_SCHEMA = "agent-mem.project-export/v1";
@@ -27,8 +27,10 @@ export const EXPORT_SCHEMA = "agent-mem.project-export/v1";
  * the file in the gap between them, which is the only way to show that O_EXCL, not the check, keeps an export from replacing someone else's file.
  */
 export const exportHooks: { afterCheck?: (file: string) => void } = {};
+export type ProjectExportFormat = "json" | "jsonl" | "markdown";
 export interface ExportCounts { capture: number; curated: number; goals: number; workLists: number }
-export interface ExportResult { file: string; project: string; counts: ExportCounts; withheld: number }
+export interface ExportResult { file: string; project: string; format: ProjectExportFormat; counts: ExportCounts; withheld: number }
+type ExportSection = keyof ExportCounts;
 const PAGE = 500;
 
 interface CaptureRowRaw { id: number; at: string; project: string; agent: string; event: string; tool: string | null; paths: string; status: string | null; excerpt: string }
@@ -47,8 +49,25 @@ function destination(base: string, to: string): string {
   return join(parentReal, name);
 }
 
-export async function exportProject(base: string, key: string, opts: { to: string; policy?: MemoryPolicy }): Promise<ExportResult> {
-  const project = requireShard(base, key);
+function markdownInline(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function markdownRecord(section: ExportSection, value: unknown): string {
+  const row = value as Record<string, unknown>;
+  const body = section === "capture" ? row.excerpt : section === "curated" ? row.text : undefined;
+  const identity = typeof row.id === "string" ? ` ${row.id}` : "";
+  const metadata = { ...row };
+  if (section === "capture") delete metadata.excerpt;
+  if (section === "curated") delete metadata.text;
+  const lines = [`### ${section}${identity}`, "", `    ${JSON.stringify(metadata)}`, ""];
+  if (typeof body === "string") lines.push(...body.split(/\r\n|\r|\n/).map(line => `    ${line}`), "");
+  return `${lines.join("\n")}\n`;
+}
+
+export async function exportProject(base: string, key: string, opts: { to: string; policy?: MemoryPolicy; format?: ProjectExportFormat }): Promise<ExportResult> {
+  const project = requireShard(base, key), format = opts.format ?? "json";
+  if (!["json", "jsonl", "markdown"].includes(format)) throw new Error("export format must be json, jsonl or markdown");
   if (projectState(base, project) === "forgotten") throw new Error(`project ${project} is forgotten: it cannot be exported`);
   const file = destination(base, opts.to), policy = opts.policy ?? createStandalonePolicy();
   exportHooks.afterCheck?.(file);
@@ -59,10 +78,24 @@ export async function exportProject(base: string, key: string, opts: { to: strin
   try { fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
   catch { throw new Error("the destination exists; export never overwrites"); }
   const out = (text: string) => { writeSync(fd, text); };
+  const exportedAt = new Date().toISOString();
+  let first = true, section: ExportSection = "capture";
+  const begin = (jsonPrefix: string, next: ExportSection, heading: string) => {
+    section = next; first = true;
+    if (format === "json") out(jsonPrefix);
+    else if (format === "markdown") out(`\n## ${heading}\n\n`);
+  };
+  const emit = (value: unknown) => {
+    if (format === "json") out(`${first ? "" : ","}${JSON.stringify(value)}`);
+    else if (format === "jsonl") out(`${JSON.stringify({ schema: EXPORT_SCHEMA, project, type: section, value })}\n`);
+    else out(markdownRecord(section, value));
+    first = false;
+  };
   const stores: { close(): void }[] = [];
   try {
-    out(`{"schema":${JSON.stringify(EXPORT_SCHEMA)},"project":${JSON.stringify(project)},"exportedAt":${JSON.stringify(new Date().toISOString())},"capture":[`);
-    let first = true;
+    if (format === "jsonl") out(`${JSON.stringify({ schema: EXPORT_SCHEMA, project, exportedAt, type: "header", aliases: aliasedKeys(base, project) })}\n`);
+    else if (format === "markdown") out(`# Project export ${markdownInline(JSON.stringify(project))}\n\nExported at ${exportedAt}\n`);
+    begin(`{"schema":${JSON.stringify(EXPORT_SCHEMA)},"project":${JSON.stringify(project)},"exportedAt":${JSON.stringify(exportedAt)},"capture":[`, "capture", "Capture");
     const shard = walkShards(base).find(candidate => candidate.key === project);
     for (const dir of shard?.machineDirs ?? []) {
       const dbFile = join(dir, "capture.db");
@@ -76,40 +109,42 @@ export async function exportProject(base: string, key: string, opts: { to: strin
             after = r.id;
             const row = { at: r.at, agent: r.agent, event: r.event, tool: r.tool, paths: JSON.parse(r.paths) as string[], status: r.status, excerpt: r.excerpt };
             if (!await allowed(row)) { withheld++; continue; }
-            out(`${first ? "" : ","}${JSON.stringify(row)}`); first = false; counts.capture++;
+            emit(row); counts.capture++;
           }
           if (rows.length < PAGE) break;
         }
       } finally { db.close(); }
     }
-    out(`],"curated":[`);
+    begin(`],"curated":[`, "curated", "Curated notes");
     const store = openCuratedForRead(base, project);
     if (store) stores.push(store);
     // The project's own rows and those of a key aliased to it; another project's shared note is not this project's and stays out of its bundle.
     const keys = new Set([project, ...aliasedKeys(base, project)]);
-    first = true;
+    const authored = format === "jsonl" ? new Map((store?.portableNotes(project) ?? []).map(row => [row.id, row])) : undefined;
     for (const view of store?.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true }) ?? []) {
       if (!keys.has(view.project)) continue;
-      if (!await allowed(view)) { withheld++; continue; }
-      out(`${first ? "" : ","}${JSON.stringify(view)}`); first = false; counts.curated++;
+      const value = format === "jsonl" ? authored!.get(view.id) : view;
+      if (!value) throw new Error("exported note's authored row is unavailable");
+      if (!await allowed(value)) { withheld++; continue; }
+      emit(value); counts.curated++;
     }
-    out(`],"goals":[`);
-    first = true;
+    begin(`],"goals":[`, "goals", "Goals");
     for (const goal of store?.goals(project) ?? []) {
       if (!keys.has(goal.project)) continue;
       if (!await allowed(goal)) { withheld++; continue; }
-      out(`${first ? "" : ","}${JSON.stringify(goal)}`); first = false; counts.goals++;
+      emit(goal); counts.goals++;
     }
-    out(`],"workLists":[`);
-    first = true;
+    begin(`],"workLists":[`, "workLists", "Work lists");
     // The bundle holds what the project's own reads show: the canonical work log and that of every key aliased to it (the same reconciliation the CLI, MCP and brief use).
     const workKeys = [project, ...aliasedKeys(base, project)];
     if (workKeys.some(key => existsSync(join(shardDir(base, key), "work")))) {
       const work = new WorkListStore({ base, project, policy: allowed, aliases: workKeys.slice(1) });
       stores.push({ close: () => work.close() });
-      for (const list of await work.read(undefined, true)) { out(`${first ? "" : ","}${JSON.stringify(list)}`); first = false; counts.workLists++; }
+      for (const list of await work.read(undefined, true)) { emit(list); counts.workLists++; }
     }
-    out(`],"counts":${JSON.stringify(counts)},"withheld":${withheld}}\n`);
+    if (format === "json") out(`],"counts":${JSON.stringify(counts)},"withheld":${withheld}}\n`);
+    else if (format === "jsonl") out(`${JSON.stringify({ schema: EXPORT_SCHEMA, project, type: "counts", counts, withheld })}\n`);
+    else out(`\n## Counts\n\n${JSON.stringify({ counts, withheld })}\n`);
   } catch (error) {
     try { closeSync(fd); } catch { /* already closed */ }
     rmSync(file, { force: true });          // the file is ours: O_EXCL created it, so a partial bundle is removed, never left behind
@@ -118,5 +153,5 @@ export async function exportProject(base: string, key: string, opts: { to: strin
     for (const store of stores) { try { store.close(); } catch { /* best effort */ } }
   }
   closeSync(fd);
-  return { file, project, counts, withheld };
+  return { file, project, format, counts, withheld };
 }

package/src/memory/project-import.ts

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream, fstatSync, openSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { isDeepStrictEqual } from "node:util";
+import { legacyEntries } from "./bridge.ts";
+import { stripPrivateDeep, stripPrivateSpans } from "./private-spans.ts";
+import { EXPORT_SCHEMA } from "./project-export.ts";
+import { aliasedKeys } from "./shard.ts";
+import { looksSecret, type MemoryStore, type NoteInput } from "./store.ts";
+
+export const PROJECT_IMPORT_MAX_BYTES = 64 * 1024 * 1024;
+export const PROJECT_IMPORT_MAX_LINE_BYTES = 64 * 1024;
+export const PROJECT_IMPORT_FUTURE_SKEW_MS = 5 * 60 * 1000;
+const NOTE_KEYS = new Set(["schema", "id", "at", "machine", "op", "project", "scope", "tier", "kind", "peer", "title", "text", "task", "about", "supersedes", "promotedFrom", "source", "expires"]);
+const OPERATIONS_WARNING = "Supersede, demote, settle and forget operations are not exported; re-import restores authored note rows only.";
+
+type ImportedNote = { id: string; at: string; machine: string; note: NoteInput };
+type Provenance = { source: Record<string, number>; peer: Record<string, number>; scope: Record<string, number> };
+export interface ProjectImportResult {
+  applied: boolean;
+  project: string;
+  read: number;
+  added: number;
+  wouldAdd: number;
+  skipped: { invalid: number; policy: number; other: number };
+  provenance: Provenance;
+  warnings: string[];
+}
+
+function importedNote(value: unknown, projects: readonly string[]): ImportedNote | undefined {
+  try {
+    if (!value || typeof value !== "object" || Array.isArray(value) || !Object.keys(value).every(key => NOTE_KEYS.has(key))) return undefined;
+    const bytes = Buffer.from(`${JSON.stringify(value)}\n`);
+    const [row] = legacyEntries([{ source: "legacy-local", path: "log/project-import.jsonl", bytes, offset: bytes.length,
+      hash: createHash("sha256").update(bytes).digest("hex"), local: false, tailBytes: 0 }], { strict: true });
+    if (row?.op !== "note" || !projects.includes(row.project)) return undefined;
+    const { id, at, machine, ...rest } = row;
+    const note = Object.fromEntries(Object.entries(rest).filter(([key]) => key !== "schema")) as NoteInput;
+    return { id, at, machine, note };
+  } catch { return undefined; }
+}
+
+function increment(counts: Map<string, number>, value: string | undefined): void {
+  const key = value ?? "unspecified";
+  counts.set(key, (counts.get(key) ?? 0) + 1);
+}
+
+function provenance(notes: Iterable<ImportedNote>): Provenance {
+  const source = new Map<string, number>(), peer = new Map<string, number>(), scope = new Map<string, number>();
+  for (const { note } of notes) {
+    increment(source, note.source);
+    increment(peer, note.peer);
+    increment(scope, note.scope);
+  }
+  return { source: Object.fromEntries(source), peer: Object.fromEntries(peer), scope: Object.fromEntries(scope) };
+}
+
+function unchangedAfterNormalization(note: NoteInput): boolean {
+  return stripPrivateSpans(note.text).slice(0, 4000) === note.text
+    && (typeof note.title !== "string" || stripPrivateSpans(note.title).slice(0, 200) === note.title);
+}
+
+/** Preview by default; confirm applies only after every row, relationship, identity and policy decision has passed without a curated write. */
+export async function importProject(store: MemoryStore, opts: {
+  from: string;
+  project: string;
+  confirm?: boolean;
+  allowShared?: boolean;
+  policy: (note: NoteInput) => boolean | Promise<boolean>;
+}): Promise<ProjectImportResult> {
+  const fd = openSync(opts.from, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  const stream = createReadStream(opts.from, { fd, encoding: "utf8" });
+  const result: ProjectImportResult = { applied: opts.confirm === true, project: opts.project, read: 0, added: 0, wouldAdd: 0,
+    skipped: { invalid: 0, policy: 0, other: 0 }, provenance: { source: {}, peer: {}, scope: {} }, warnings: [OPERATIONS_WARNING] };
+  let header = false, bytes = 0;
+  let aliases: string[] = [];
+  const pending = new Map<string, ImportedNote>(), accepted: ImportedNote[] = [];
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > PROJECT_IMPORT_MAX_BYTES) throw new Error("project import needs a regular JSONL file of at most 64 MiB");
+    const lines = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+      for await (const line of lines) {
+        bytes += Buffer.byteLength(line, "utf8") + 1;
+        if (bytes > PROJECT_IMPORT_MAX_BYTES) throw new Error("project import exceeded 64 MiB while reading");
+        if (Buffer.byteLength(line, "utf8") > PROJECT_IMPORT_MAX_LINE_BYTES) { result.skipped.invalid++; continue; }
+        if (!line.trim()) continue;
+        let row: Record<string, unknown>;
+        try {
+          const parsed: unknown = JSON.parse(line);
+          if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+          row = parsed as Record<string, unknown>;
+        } catch { result.skipped.invalid++; continue; }
+        if (row.schema !== EXPORT_SCHEMA || row.project !== opts.project) throw new Error("project import schema or project mismatch");
+        if (row.type === "header") {
+          if (header) throw new Error("project import has more than one header");
+          if (!Array.isArray(row.aliases) || !row.aliases.every(alias => typeof alias === "string")) throw new Error("project import aliases are invalid");
+          aliases = [...row.aliases] as string[];
+          const available = aliasedKeys(store.profile.home, opts.project);
+          if (aliases.some(alias => !available.includes(alias))) throw new Error("project import requires the exported aliases in the target home");
+          header = true; continue;
+        }
+        if (!header) throw new Error("project import needs its header first");
+        if (row.type === "counts") continue;
+        if (row.type !== "curated") { result.skipped.other++; continue; }
+        result.read++;
+        const imported = importedNote(row.value, [opts.project, ...aliases]);
+        if (!imported || Date.parse(imported.at) > store.readNow() + PROJECT_IMPORT_FUTURE_SKEW_MS
+          || imported.note.scope === "shared" && opts.allowShared !== true || !unchangedAfterNormalization(imported.note)) {
+          result.skipped.invalid++;
+          continue;
+        }
+        const prior = pending.get(imported.id);
+        if (prior) {
+          if (!isDeepStrictEqual(prior, imported)) throw new Error("project import has conflicting rows for one entry id");
+          continue;
+        }
+        pending.set(imported.id, imported);
+      }
+    } finally { lines.close(); }
+    if (!header) throw new Error("project import has no header");
+
+    for (const imported of pending.values()) {
+      if (["supersedes", "promotedFrom"].some(field => {
+        const target = imported.note[field as "supersedes" | "promotedFrom"] as string | null | undefined;
+        return target !== undefined && target !== null && !pending.has(target);
+      })) {
+        result.skipped.invalid++;
+        continue;
+      }
+      const screened = stripPrivateDeep(imported.note);
+      if (looksSecret(JSON.stringify(screened)) || !await opts.policy(screened)) { result.skipped.policy++; continue; }
+      accepted.push(imported);
+    }
+    result.provenance = provenance(accepted);
+    const existing = new Set(store.portableNotes(opts.project).map(note => note.id));
+    result.wouldAdd = accepted.filter(note => !existing.has(note.id)).length;
+    if (opts.confirm === true) {
+      for (const imported of accepted) {
+        const written = store.importNote(imported.note, imported.at, { machine: imported.machine, expectedId: imported.id });
+        if (written.added) result.added++;
+      }
+      store.refresh();
+    }
+    return result;
+  } finally { stream.destroy(); }
+}

package/src/memory/shard-sync-format.ts

@@ -102,10 +102,9 @@ export function decodeShardPack(path: string, bytes: Uint8Array, realm: ShardSyn
     catch { throw new ShardSyncFormatError(label, "malformed pack row"); }
     const row = publicRow(value, label);
     if (hash(row.machine) !== match[1]) throw new ShardSyncFormatError(label, "pack author mismatch");
-    if (row.op === "prune") {
-      // ponytail: #404 needs a generation-neutral public-witness transport; never retag or skip a foreign prune.
-      if (row.generation !== generation) throw new ShardSyncFormatError(label, "foreign-generation prune");
-    } else if (row.op === "note" || row.op === "goal") {
+    // Generation is preserved in the original prune payload. Acceptance here is structural,
+    // never permission to apply it: the engine proves each original generation and holds foreign rows.
+    if (row.op === "note" || row.op === "goal") {
       if (realm.scope === "project" ? row.scope !== "project" || row.project !== realm.key : row.scope !== "shared") {
         throw new ShardSyncFormatError(label, "row scope mismatch");
       }

package/src/memory/shard-sync.ts

@@ -1,5 +1,5 @@
 import { randomBytes, createHash } from "node:crypto";
-import { constants, closeSync, existsSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readSync, rmSync, writeSync } from "node:fs";
+import { constants, closeSync, existsSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readSync, renameSync, rmSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { canonicalJSON, fsyncDirectory, hashJSON, readProfileJSON } from "./generation.ts";
 import { generationSyncLock } from "./generation-sync.ts";
@@ -14,8 +14,14 @@ import type { Entry, MemoryStore } from "./store.ts";
 const OID = /^[a-f0-9]{40}$/, PACK = /^rows\/[a-f0-9]{64}\/[a-f0-9]{64}\.jsonl$/;
 const digest = (bytes: string | Uint8Array): string => createHash("sha256").update(bytes).digest("hex");
 const zero = "0".repeat(40);
+// The descriptor is at most 64 KiB and an original prune at most 16 KiB; keep receipt parsing bounded.
+const HOLD_MAX_BYTES = 128 * 1024;
 type PendingPrune = { plan: PrunePlan; row: PruneRow; line: string; offset: number; prefixHash: string };
-type Target = { store: MemoryStore; realm: ShardSyncRealm; rows: Map<string, ShardSyncRow>; fetched: Set<string>; sources: PruneSourceRow[]; pending: PendingPrune[]; generation: string; local?: string; remote?: string; commit?: string };
+type HoldSource = { ref: string; commit: string; pack: string; blob: string };
+type HoldReceipt = { schema: "agent-mem.prune-hold/v1"; remote: string; realm: ShardSyncRealm; receivingGeneration: string; row: PruneRow; payloadHash: string; source: HoldSource };
+type Hold = { file: string; bytes: Buffer };
+type SyncPhase = "published" | "hold-written" | "hold-installed" | "imported";
+type Target = { store: MemoryStore; realm: ShardSyncRealm; rows: Map<string, ShardSyncRow>; fetched: Set<string>; sources: PruneSourceRow[]; pending: PendingPrune[]; origins: Map<string, HoldSource>; holds: Hold[]; generation: string; local?: string; remote?: string; commit?: string };
 class SyncRefusal extends Error {}
 function refuse(reason: string): never { throw new SyncRefusal(reason); }
 function directory(path: string): void {
@@ -146,8 +152,10 @@ function provePrunes(targets: readonly Target[]): void {
     }
     const snapshot: PruneSnapshot = { rows: [...sources.values()], expiries: [] };
     const prunes = [...target.rows.values()].filter((row): row is PruneRow => row.op === "prune");
-    const proof = reducePruneRows(prunes.map(row => ({ row, placement: "synced" as const })), snapshot, target.generation);
-    if (proof.invalid || proof.pending.length) refuse(`${shardSyncLabel(target.realm)}: prune lacks complete public witnesses`);
+    for (const generation of new Set(prunes.map(row => row.generation))) {
+      const proof = reducePruneRows(prunes.filter(row => row.generation === generation).map(row => ({ row, placement: "synced" as const })), snapshot, generation);
+      if (proof.invalid || proof.pending.length) refuse(`${shardSyncLabel(target.realm)}: prune lacks complete public witnesses`);
+    }
   }
 }
 function installPack(store: MemoryStore, bytes: Buffer): void {
@@ -176,7 +184,7 @@ function importRows(target: Target): void {
   for (const pending of target.pending) {
     port.persistPrunePlan(pending.plan); port.appendPrune(pending.row, pending.line, pending.plan.seal); resumed.add(pending.row.id);
   }
-  for (const row of target.rows.values()) if (row.op === "prune") {
+  for (const row of target.rows.values()) if (row.op === "prune" && row.generation === target.generation) {
     if (resumed.has(row.id)) continue;
     // A transport imports an already-authored person row without changing its author or generation.
     // Native durable-plan append confirms fsync even for an already parsed id after a crash.
@@ -186,8 +194,104 @@ function importRows(target: Target): void {
   port.refresh();
 }
 
-/** Sync only the borrowed canonical project and user targets. The internal third argument is a test-only observer, never a CLI/SyncOptions port. */
-export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions = {}, testOnlyUnexpectedError?: (error: unknown) => void): Promise<SyncResult> {
+/** Receipts are private, immutable transport metadata, outside every native generation reducer.
+ * ponytail: foreign targets remain visible; an explicit cross-generation apply protocol must
+ * re-prove witnesses and establish a compatible reader floor before lifting this hold ceiling. */
+const hasHoldPath = (file: string): boolean => lstatSync(file, { throwIfNoEntry: false }) !== undefined;
+function privateHoldPath(file: string, folder: boolean): void {
+  if (folder) directory(file); else regular(file);
+  if (lstatSync(file).mode & 0o077) refuse("shard sync prune holds require private permissions");
+}
+function checkPendingHold(file: string, bytes: Buffer): void {
+  privateHoldPath(file, false);
+  if (lstatSync(file).size > bytes.length || !readFileSync(file).equals(bytes.subarray(0, lstatSync(file).size))) refuse("shard sync partial prune hold conflicts with verified receipt");
+}
+function installHold(root: string, hold: Hold, phase?: (phase: SyncPhase) => void): void {
+  const parts = hold.file.slice(root.length + 1).split("/"), name = parts.pop()!;
+  let folder = root;
+  for (const part of parts) {
+    const parent = folder; folder = join(folder, part);
+    if (!hasHoldPath(folder)) mkdirSync(folder, { mode: 0o700 });
+    privateHoldPath(folder, true); fsyncDirectory(parent);
+  }
+  const file = join(folder, name), pending = file + ".pending";
+  if (hasHoldPath(file)) {
+    privateHoldPath(file, false);
+    if (!readFileSync(file).equals(hold.bytes)) refuse("shard sync immutable prune hold conflict");
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW); try { fsyncSync(fd); } finally { closeSync(fd); }
+    fsyncDirectory(folder); return;
+  }
+  if (hasHoldPath(pending)) checkPendingHold(pending, hold.bytes);
+  const fd = openSync(pending, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+  try {
+    // Interrupted private staging bytes may be completed; committed receipts are never rewritten.
+    let offset = 0; while (offset < hold.bytes.length) { const n = writeSync(fd, hold.bytes, offset, hold.bytes.length - offset, offset); if (n <= 0) refuse("shard sync prune hold write unavailable"); offset += n; }
+    fsyncSync(fd);
+  } finally { closeSync(fd); }
+  phase?.("hold-written");
+  // The transport mutation lock serializes this create-once rename. Unlike hard-link installation,
+  // a crash cannot leave a committed receipt with a second link that later fails validation.
+  if (hasHoldPath(file)) refuse("shard sync prune hold changed concurrently");
+  renameSync(pending, file); fsyncDirectory(folder); phase?.("hold-installed");
+}
+function holdWarning(targets: readonly Target[], root: string): string | undefined {
+  const warnings: string[] = [];
+  for (const target of targets) if (target.holds.length) {
+    const rows = [...target.rows.values()].filter((row): row is PruneRow => row.op === "prune" && row.generation !== target.generation);
+    const ids = [...new Set(rows.flatMap(row => row.targets.map(item => item.id)))].sort(), shown = ids.slice(0, 10);
+    const location = target.holds[0]!.file.slice(root.length + 1).split("/").slice(0, -2).join("/");
+    warnings.push(`${shardSyncLabel(target.realm)}: ${rows.length} foreign-generation prune(s) held, not applied; targets ${shown.join(",")}${ids.length > shown.length ? ` (+${ids.length - shown.length} more)` : ""} may remain visible; receipts shard-sync/${location}; bring this machine to the origin generation, or prune the entry here as the person`);
+  }
+  return warnings.length ? warnings.join("; ") : undefined;
+}
+
+type ProveHoldSource = (target: Target, receipt: HoldReceipt) => Promise<void>;
+async function prepareHold(root: string, url: string, target: Target, row: PruneRow, proveSource: ProveHoldSource): Promise<Hold> {
+  const source = target.origins.get(row.id);
+  if (!source || !target.remote || !target.fetched.has(row.id)) refuse(`${shardSyncLabel(target.realm)}: foreign prune has no fetched provenance`);
+  const receipt: HoldReceipt = { schema: "agent-mem.prune-hold/v1", remote: digest(url), realm: target.realm,
+    receivingGeneration: target.generation, row, payloadHash: hashJSON(row), source };
+  const folders = ["prune-holds", receipt.remote, digest(shardSyncRef(target.realm)), target.generation, row.generation];
+  let folder = root;
+  for (const name of folders) { folder = join(folder, name); if (hasHoldPath(folder)) privateHoldPath(folder, true); }
+  const file = join(folder, `${row.id}-${receipt.payloadHash}.json`);
+  let selected = receipt;
+  if (hasHoldPath(file)) {
+    privateHoldPath(file, false);
+    const value = readProfileJSON(file, HOLD_MAX_BYTES) as HoldReceipt | undefined;
+    if (!value || !value.source || Object.keys(value.source).length !== 4 || !OID.test(value.source.commit)
+      || !OID.test(value.source.blob) || !PACK.test(value.source.pack)
+      || canonicalJSON({ ...value, source }) !== canonicalJSON(receipt)) refuse(`${shardSyncLabel(target.realm)}: invalid prune hold receipt`);
+    // A receipt is evidence of a hold, never application authority. Recheck its original
+    // immutable source against this invocation's fully audited selected remote history.
+    await proveSource(target, value);
+    selected = value;
+  }
+  const bytes = Buffer.from(canonicalJSON(selected) + "\n");
+  if (bytes.length > HOLD_MAX_BYTES) refuse("shard sync prune hold exceeds metadata bound");
+  if (hasHoldPath(file) && !readFileSync(file).equals(bytes)) refuse("shard sync prune hold is not canonical");
+  if (hasHoldPath(file + ".pending")) checkPendingHold(file + ".pending", bytes);
+  return { file, bytes };
+}
+async function prepareHolds(targets: readonly Target[], root: string, url: string, proveSource: ProveHoldSource): Promise<void> {
+  for (const target of targets) {
+    target.holds = [];
+    for (const row of target.rows.values()) if (row.op === "prune" && row.generation !== target.generation) {
+      target.holds.push(await prepareHold(root, url, target, row, proveSource));
+    }
+  }
+}
+function mergePackOrigins(into: Map<string, HoldSource>, byRealm: Map<string, Map<string, HoldSource>>, rows: readonly ShardSyncRow[], source: HoldSource): void {
+  const first = byRealm.get(source.ref) ?? new Map<string, HoldSource>(); byRealm.set(source.ref, first);
+  // Oldest-first history keeps a receipt's source stable across tip advancement and partial-write retry.
+  for (const row of rows) {
+    if (!first.has(row.id)) first.set(row.id, source);
+    if (!into.has(row.id)) into.set(row.id, first.get(row.id)!);
+  }
+}
+
+/** Sync only borrowed canonical project/user targets. Internal error/phase observers are test-only, never CLI/SyncOptions ports. */
+export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions = {}, testOnlyUnexpectedError?: (error: unknown) => void, testOnlyPhase?: (phase: SyncPhase) => void): Promise<SyncResult> {
   let pushed = false, releaseTransport: (() => void) | undefined, releaseSync: (() => void) | undefined;
   const releases: (() => void)[] = [], transient: string[] = [], temporary: string[] = [];
   const fail = (error: string): SyncResult => ({ ok: false, pushed, entries: 0, error });
@@ -216,7 +320,7 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
     targets = borrowed.map(opened => {
       const profile = opened.profile;
       if (!profile.sharded || profile.kind !== "generation" || !profile.generation || !profile.shardUser && !profile.shardKey) refuse("shard sync target identity unavailable");
-      return { store: opened, realm: profile.shardUser ? { scope: "user" as const } : { scope: "project" as const, key: profile.shardKey! }, rows: new Map<string, ShardSyncRow>(), fetched: new Set<string>(), sources: [], pending: [], generation: profile.generation };
+      return { store: opened, realm: profile.shardUser ? { scope: "user" as const } : { scope: "project" as const, key: profile.shardKey! }, rows: new Map<string, ShardSyncRow>(), fetched: new Set<string>(), sources: [], pending: [], origins: new Map<string, HoldSource>(), holds: [], generation: profile.generation };
     });
     if (!targets.length || targets.length > 2 || targets.some(target => target.store.profile.home !== store.profile.home)
       || new Set(targets.map(target => shardSyncRef(target.realm))).size !== targets.length
@@ -280,12 +384,13 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
       if (identity !== object) refuse("shard sync public blob identity mismatch");
       blobCache.set(object, bytes); return bytes;
     };
-    type History = { rows: Map<string, ShardSyncRow>; files: Map<string, Buffer> };
+    type History = { rows: Map<string, ShardSyncRow>; files: Map<string, Buffer>; origins: Map<string, HoldSource> };
     // Keep only requested tips. Per-commit full row maps would make append-only history quadratic in memory.
     const histories = new Map<string, History>(), audited = new Set<string>();
+    const firstOrigins = new Map<string, Map<string, HoldSource>>();
     const treeState = async (commit: string, target: Target): Promise<History> => {
       const entries = (await required(["ls-tree", "-r", "-z", commit], "shard sync tree unavailable")).split("\0").filter(Boolean);
-      const rows = new Map<string, ShardSyncRow>(), files = new Map<string, Buffer>();
+      const rows = new Map<string, ShardSyncRow>(), files = new Map<string, Buffer>(), origins = new Map<string, HoldSource>();
       for (const entry of entries) {
         const match = /^100644 blob ([a-f0-9]{40})\t(.+)$/.exec(entry);
         if (!match || match[2] !== "shard.json" && !PACK.test(match[2]!)) refuse(`${shardSyncLabel(target.realm)}: forbidden historical tree entry`);
@@ -298,10 +403,11 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
           if (!pack) { pack = decodeShardPack(path, bytes, target.realm, target.generation); decoded.set(key, pack); }
           else if (!path.endsWith(`/${digest(bytes)}.jsonl`) || pack.some(row => path !== `rows/${digest(row.machine)}/${digest(bytes)}.jsonl`)) refuse(`${shardSyncLabel(target.realm)}: immutable pack path changed`);
           mergeRows(rows, pack, target.realm);
+          mergePackOrigins(origins, firstOrigins, pack, { ref: shardSyncRef(target.realm), commit, pack: path, blob: object });
         }
       }
       if (!files.has("shard.json")) refuse(`${shardSyncLabel(target.realm)}: historical descriptor missing`);
-      return { rows, files };
+      return { rows, files, origins };
     };
     const history = async (tip: string, target: Target): Promise<History> => {
       const key = `${shardSyncRef(target.realm)}:${tip}`, cached = histories.get(key); if (cached) return cached;
@@ -345,7 +451,7 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
         if (target.local) await required(["merge-base", "--is-ancestor", target.local, tip], `${shardSyncLabel(target.realm)}: remote history is not fast-forward`);
         const remote = await history(tip, target); target.remote = tip;
         mergeRows(target.rows, Array.from(remote.rows.values()), target.realm);
-        for (const row of remote.rows.values()) target.fetched.add(row.id);
+        for (const row of remote.rows.values()) { target.fetched.add(row.id); target.origins.set(row.id, remote.origins.get(row.id)!); }
       }
     };
     const localTargets = () => {
@@ -385,10 +491,17 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
         await history(target.commit, target);
       }
     };
-    localTargets(); await fetchTargets(); localTargets(); provePrunes(targets); check();
+    const proveHoldSource: ProveHoldSource = async (target, value) => {
+      await required(["merge-base", "--is-ancestor", value.source.commit, target.remote!], "shard sync prune hold source is not remote history");
+      const original = await history(value.source.commit, target), bytes = original.files.get(value.source.pack);
+      if (!bytes || createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex") !== value.source.blob
+        || !decodeShardPack(value.source.pack, bytes, target.realm, target.generation).some(item => canonicalJSON(item) === canonicalJSON(value.row))
+        || value.source.ref !== shardSyncRef(target.realm)) refuse(`${shardSyncLabel(target.realm)}: prune hold source mismatch`);
+    };
+    localTargets(); await fetchTargets(); localTargets(); provePrunes(targets); await prepareHolds(targets, root, url, proveHoldSource); check();
     // Every selected realm, including its complete remote history/prunes, is preflighted before the first append or publication.
     for (let attempt = 0; attempt < 2; attempt++) {
-      if (attempt) { await fetchTargets(); localTargets(); provePrunes(targets); check(); }
+      if (attempt) { await fetchTargets(); localTargets(); provePrunes(targets); await prepareHolds(targets, root, url, proveHoldSource); check(); }
       await buildTargets(); check();
       const sent = await git(["push", "--atomic", "--no-follow-tags", "-q", "origin", ...targets.map(target => `${target.commit!}:${shardSyncRef(target.realm)}`)]);
       if (sent.code === 0) pushed = true;
@@ -396,13 +509,18 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
       if (sent.code === 0) {
         pushed = true;
         // No local append before a successful atomic publication: a raced foreign prune can still refuse the entire retry safely.
-        localTargets(); provePrunes(targets); check();
+        localTargets(); provePrunes(targets); check(); testOnlyPhase?.("published");
+        // No selected ordinary/native imports can precede durable receipts for every foreign prune.
+        for (const target of targets) for (const hold of target.holds) installHold(root, hold, testOnlyPhase);
+        check();
         for (const target of targets) {
           assertCuratedShardPaths(target.store.profile.home, target.realm.scope === "user" ? { user: true } : { project: target.realm.key });
-          importRows(target);
+          importRows(target); testOnlyPhase?.("imported");
         }
         for (const target of targets) await required(["update-ref", "--no-deref", shardSyncRef(target.realm), target.commit!, target.local ?? zero], "shard sync cached ref changed concurrently");
-        return { ok: true, pushed, entries: targets.reduce((n, target) => n + [...target.rows.values()].filter(row => row.op === "note").length, 0) };
+        const warning = holdWarning(targets, root);
+        return { ok: true, pushed, entries: targets.reduce((n, target) => n + [...target.rows.values()].filter(row => row.op === "note").length, 0),
+          ...(warning ? { warning } : {}) };
       }
       if (opts.signal?.aborted) return fail("stopped");
     }