@staix/agent-mem 0.12.0 → 0.14.0

package/src/memory/shard.ts

@@ -1,7 +1,8 @@
+import { assertNoPublicPruneIntent, readPublicPruneView } from "./public-prune-view.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { canonicalJSON, generationDescriptor, hashJSON, readProfileJSON, readSelector, validGeneration, type BoundProfile, type GenerationSeal } from "./generation.ts";
+import { canonicalJSON, generationDescriptor, hashJSON, readProfileJSON, readSelector, validGeneration, PROFILE_LOCK_TIMEOUT_MS, type BoundProfile, type GenerationSeal } from "./generation.ts";
 import { SHARD_SCHEMA, resolveAlias } from "./aliases.ts";
 
 /**
@@ -80,16 +81,53 @@ export function captureShardDir(base: string, key: string, machine: string): str
 }
 
 export const SHARDED_SCHEMA = "agent-mem.shards/v1";
-export interface ShardedSelection { schema: typeof SHARDED_SCHEMA; generation: string; phase: "active"; selectorRevision: string }
+export const SHARDED_V2_SCHEMA = "agent-mem.shards/v2";
+export const SHARDED_V2_FIELDS = ["schema", "generation", "phase", "selectorRevision", "sourceGeneration", "sources", "machine", "legacyCommit", "deadLeasesRemoved"] as const;
+export interface ShardedSelection { schema: typeof SHARDED_SCHEMA | typeof SHARDED_V2_SCHEMA; generation: string; phase: "active"; selectorRevision: string }
 
 export function userShardDir(base: string): string {
   return join(base, "user");
 }
 
+type ShardedJournal = Record<string, unknown> & ShardedSelection;
+function shardJournal(memoryDir: string): ShardedJournal {
+  const value = readProfileJSON(join(memoryDir, "shards.json")) as Record<string, unknown> | undefined;
+  if (!value || (value.schema !== SHARDED_SCHEMA && value.schema !== SHARDED_V2_SCHEMA) || !validGeneration(value.generation) || value.phase !== "active" || typeof value.selectorRevision !== "string") throw new Error("no active curated shard migration");
+  if (value.schema === SHARDED_V2_SCHEMA && Object.keys(value).some(key => !(SHARDED_V2_FIELDS as readonly string[]).includes(key))) throw new Error("unsupported curated shard view");
+  return value as ShardedJournal;
+}
+function compatibleShardAdvance(before: ShardedJournal, after: ShardedJournal): boolean {
+  if (before.schema !== SHARDED_V2_SCHEMA || after.schema !== SHARDED_V2_SCHEMA) return false;
+  const { selectorRevision: _old, ...old } = before, { selectorRevision: _next, ...next } = after;
+  return canonicalJSON(old) === canonicalJSON(next);
+}
+function shardSnapshot(memoryDir: string, deadline: number) {
+  assertNoPublicPruneIntent(memoryDir, deadline);
+  let journal = shardJournal(memoryDir);
+  for (let attempt = 0; attempt < 6 && Date.now() <= deadline; attempt++) {
+    let selector: ReturnType<typeof readSelector>;
+    try { selector = readSelector(memoryDir, deadline); }
+    catch (error) {
+      // The writer's spent wait budget or unavailable proof is never restarted here.
+      if (error instanceof Error && error.message === "public prune view unavailable") throw error;
+      const current = shardJournal(memoryDir);
+      if (current.selectorRevision === journal.selectorRevision || !compatibleShardAdvance(journal, current)) throw error;
+      journal = current; continue;
+    }
+    const current = shardJournal(memoryDir);
+    if (canonicalJSON(current) !== canonicalJSON(journal)) {
+      if (!compatibleShardAdvance(journal, current)) throw new Error("curated shard selector changed");
+      journal = current; continue;
+    }
+    if ((journal.schema === SHARDED_V2_SCHEMA) !== (selector.selector?.schema === "agent-mem.profile/v2")) throw new Error("curated shard selector changed");
+    if (journal.schema === SHARDED_V2_SCHEMA && (selector.revision !== journal.selectorRevision || selector.selector?.generation !== journal.generation)) continue;
+    return { journal, selector };
+  }
+  throw new Error("curated shard selector changed");
+}
 export function readShardedSelection(memoryDir: string): ShardedSelection {
-  const value = readProfileJSON(join(memoryDir, "shards.json")) as { schema?: unknown; generation?: unknown; phase?: unknown; selectorRevision?: unknown } | undefined;
-  if (!value || value.schema !== SHARDED_SCHEMA || !validGeneration(value.generation) || value.phase !== "active" || typeof value.selectorRevision !== "string") throw new Error("no active curated shard migration");
-  return { schema: SHARDED_SCHEMA, generation: value.generation, phase: "active", selectorRevision: value.selectorRevision };
+  const { journal } = shardSnapshot(memoryDir, Date.now() + PROFILE_LOCK_TIMEOUT_MS);
+  return { schema: journal.schema, generation: journal.generation, phase: "active", selectorRevision: journal.selectorRevision };
 }
 
 /** Fixed curated paths cannot redirect writes into legacy inputs or another shard.
@@ -107,14 +145,14 @@ export function assertCuratedShardPaths(memoryDir: string, opts: { project?: str
   check(dir, true);
   for (const folder of ["log", "local", "legacy", "legacy/log", "legacy/local", "legacy-main", "legacy-main/log", "legacy-main/local"]) check(join(dir, folder), true);
   for (const name of ["project.json", "generation.json", "generation-seal.json", "migration-sources.json", "machine.json", "legacy/machine.json", "legacy-main/machine.json", "prune-translations.jsonl"]) check(join(dir, name), false);
-  for (const database of ["index.db", "search.db", "mutation-lock.db"]) for (const suffix of ["", "-wal", "-shm", "-journal"]) check(join(dir, database + suffix), false);
+  for (const database of ["index.db", "index-v2.db", "search.db", "mutation-lock.db"]) for (const suffix of ["", "-wal", "-shm", "-journal"]) check(join(dir, database + suffix), false);
 }
 
 /** Open one already-sealed shard without consulting the legacy home or the catalog. */
 export function resolveShardProfile(memoryDir: string, opts: { project?: string; user?: boolean }): BoundProfile {
   if (opts.user === true && opts.project !== undefined || opts.user !== true && !opts.project) throw new Error("choose exactly one project or the user shard");
   assertCuratedShardPaths(memoryDir, opts);
-  const selection = readShardedSelection(memoryDir), generation = selection.generation;
+  const deadline = Date.now() + PROFILE_LOCK_TIMEOUT_MS, initial = shardSnapshot(memoryDir, deadline), generation = initial.journal.generation;
   const dir = opts.user === true ? userShardDir(memoryDir) : shardDir(memoryDir, opts.project!);
   if (opts.project !== undefined && readShardDescriptor(memoryDir, shardKeyHash(opts.project))?.key !== opts.project) throw new Error("curated shard project identity mismatch");
   const expected = generationDescriptor(generation);
@@ -127,10 +165,13 @@ export function resolveShardProfile(memoryDir: string, opts: { project?: string;
   const rootMachine = readProfileJSON(join(memoryDir, "machine.json"), 4096) as { id?: unknown } | undefined;
   const shardMachine = readProfileJSON(join(dir, "machine.json"), 4096) as { id?: unknown } | undefined;
   if (typeof rootMachine?.id !== "string" || !/^[a-f0-9]{16}$/.test(rootMachine.id) || rootMachine.id !== shardMachine?.id) throw new Error("curated shard machine identity mismatch");
-  const selector = readSelector(memoryDir);
-  if (selector.revision !== selection.selectorRevision) throw new Error("curated shard selector changed; resume or inspect migration state");
+  const final = shardSnapshot(memoryDir, deadline), selector = final.selector;
+  if (canonicalJSON(final.journal) !== canonicalJSON(initial.journal) && !compatibleShardAdvance(initial.journal, final.journal)
+    || selector.revision !== final.journal.selectorRevision) throw new Error("curated shard selector changed; resume or inspect migration state");
+  if (selector.selector?.schema === "agent-mem.profile/v2") readPublicPruneView(memoryDir, selector.selector.pruneInputSetHash, generation, deadline);
   const legacyMainHome = join(dir, "legacy-main");
   const hasLegacyMain = existsSync(legacyMainHome) || sources.sources.some(source => !!source && typeof source === "object" && "source" in source && source.source === "legacy-main");
   return { kind: "generation", home: memoryDir, dir, generation, selectorRevision: selector.revision,
+    ...(selector.selector?.schema === "agent-mem.profile/v2" ? { foreignPruneFormat: selector.selector.foreignPruneFormat, pruneInputSetHash: selector.selector.pruneInputSetHash } : {}),
     legacyHome: join(dir, "legacy"), ...(hasLegacyMain ? { legacyMainHome } : {}), sharded: true, ...(opts.user === true ? { shardUser: true } : { shardKey: opts.project! }) };
 }

package/src/memory/store.ts

@@ -1,3 +1,6 @@
+import { readPublicPruneView } from "./public-prune-view.ts";
+import { readShardLegacySnapshot } from "./shard-bridge.ts";
+import { cliAttribution } from "./cli-attribution.ts";
 import { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { appendFileSync, chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -16,13 +19,13 @@ import { readWindowSql, readRef, type ReadWindow, type ReadRef, SearchIndex, cap
 import { assertCuratedShardPaths, ensureShardDescriptor, readShardDescriptor, readShardedSelection, aliasedKeys, resolveAlias, resolveShardProfile, shardDir, shardKeyHash, shardMachineDir, userShardDir } from "./shard.ts";
 import { readCaptureConfig, type CaptureRow } from "./capture.ts";
 import { assertSharedV1Op } from "./ops-contract.ts";
-import { generationDescriptor, generationDir, fsyncDirectory, canonicalJSON, hashJSON, readProfileJSON, resolveProfile, writeProfileJSON, readSelector, type BoundProfile, type ProfileInput, validateVaultLinkRow, vaultLinkId, type VaultLink, type VaultLinkRow } from "./generation.ts";
+import { generationDescriptor, generationDir, fsyncDirectory, canonicalJSON, hashJSON, readProfileJSON, resolveProfile, writeProfileJSON, readSelector, type BoundProfile, type ProfileInput, validateVaultLinkRow, vaultLinkId, type VaultLink, type VaultLinkRow, rebindPublicPruneProfile } from "./generation.ts";
 import { GenerationIndex, coalesceGenerationSource, explicitExpirySnapshot, GENERATION_TABLES } from "./generation-index.ts";
 import { legacyEntries, readLegacySnapshot, SegmentReader, type LegacyCheckpoint } from "./bridge.ts";
 import { readMigrationSources } from "./migrate.ts";
 import type { PruneSourceRow, PruneStorePort } from "./prune.ts";
 import { isDeepStrictEqual } from "node:util";
-import { registerReaderLease } from "./reader-lease.ts";
+import { registerReaderLease, type ReaderLease } from "./reader-lease.ts";
 
 /**
  * #258: the hub's own memory. Append-only JSONL logs are the truth: `log/<machine>.jsonl` holds long-term entries and
@@ -193,7 +196,7 @@ export interface StoreOptions { home?: string; memoryDir?: string; ttlMs?: numbe
   lifecycle?: "enforce" | "ignore";
   /** #27: read the `aliases` keys' curated rows as part of the `canonical` project (CLI and MCP only); the library default reads the raw key. Rows are presented under `canonical`. */
   reconcile?: { canonical: string; aliases: readonly string[] };
-  /** Person-only project import may initialize configured alias shards; read-only reconciliation still never creates them. */
+  /** Explicit project import may initialize configured alias shards; read-only reconciliation still never creates them. */
   createAliases?: boolean;
 }
 
@@ -214,7 +217,7 @@ export class MemoryStore {
   /** #13: the derived FTS5 copy of the curated rows, and the memory home base for capture shard resolution (#15 T1). */
   private readonly searchIndex: SearchIndex;
   private readonly memoryBaseDir: string;
-  private releaseReaderLease?: () => void;
+  private releaseReaderLease?: ReaderLease;
   private readonly userOverlay?: MemoryStore;
   /** #27: the other keys' shards of a reconciled read (curated shards); shared-v1 reads them from its own index. */
   private readonly aliasStores: MemoryStore[];
@@ -247,10 +250,16 @@ export class MemoryStore {
     this.screen = opts.screen;
     this.deferPromotions = opts.deferPromotions ?? false;
     // Announce before opening derived handles or reading rows; failed admission leaks no database handles.
-    if (!bootstrap) this.releaseReaderLease = registerReaderLease(this.profile.home);
+    if (!bootstrap || bootstrap.authoring === true) this.releaseReaderLease = registerReaderLease(this.profile.home, this.profile.sharded ? {scope:"shard"} : {});
     let openedDb: Database | undefined, openedMutation: Database | undefined, openedSearch: SearchIndex | undefined;
     try {
-      const db = openedDb = new Database(join(this.dir, "index.db"), { create: true });
+      const indexFile = join(this.dir, this.profile.foreignPruneFormat ? "index-v2.db" : "index.db");
+      if (this.profile.foreignPruneFormat) for (const suffix of ["", "-wal", "-shm", "-journal"]) {
+        const stat = lstatSync(indexFile + suffix, {throwIfNoEntry:false});
+        if (stat && (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid?.())) throw new Error("v2 index path unavailable");
+      }
+      const db = openedDb = new Database(indexFile, { create: true });
+      if (this.profile.foreignPruneFormat) chmodSync(indexFile, 0o600);
       db.run(`PRAGMA busy_timeout = ${MEMORY_DB_BUSY_TIMEOUT_MS}`);
       db.run("PRAGMA journal_mode = WAL");
       if ((db.query("PRAGMA user_version").get() as { user_version: number }).user_version !== INDEX_VERSION) {
@@ -271,7 +280,7 @@ export class MemoryStore {
       // One derived FTS copy per profile: a generation handle and a shared-v1 handle on one home never resync-fight.
       this.searchIndex = openedSearch = new SearchIndex(this.profile.sharded ? join(this.dir, "search.db") : join(home, this.profile.kind === "generation" ? `search-${this.profile.generation}.db` : "search.db"));
       this.memoryBaseDir = home;
-      try { chmodSync(join(this.dir, "index.db"), 0o600); } catch { /* best effort */ }
+      try { chmodSync(join(this.dir, this.profile.foreignPruneFormat ? "index-v2.db" : "index.db"), 0o600); } catch { /* best effort */ }
       if (this.profile.kind === "generation") this.generationIndex = new GenerationIndex({ profile: this.profile, db, now: this.now,
         apply: (line, source) => this.apply(line, source), withMutation: work => this.withMutation(work),
         ...(bootstrap ? { limits: bootstrap.limits } : {}), ...(bootstrap?.commit ? { commit: bootstrap.commit } : {}) });
@@ -589,7 +598,7 @@ export class MemoryStore {
     let applied = 0;
     if (apply) for (const group of groups) for (const head of group.heads) {
       if (head === group.target) continue;
-      if (!this.supersede(head, group.target, "user", project)) throw new Error("memory dedupe replacement refused; rerun to inspect current relations");
+      if (!this.supersede(head, group.target, cliAttribution()?.actor ?? "user", project)) throw new Error("memory dedupe replacement refused; rerun to inspect current relations");
       applied++;
     }
     return { groups, applied };
@@ -1002,6 +1011,8 @@ export class MemoryStore {
 
   /** Index deferred writes before any note, goal or suggestion read. */
   private ensureFresh(): void {
+    this.releaseReaderLease?.verify();
+    if (!this.bootstrapOnly) rebindPublicPruneProfile(this.profile);
     this.userOverlay?.ensureFresh();
     for (const store of this.aliasStores) store.ensureFresh();
     if (this.generationIndex) { this.generationIndex.refresh(); return; }
@@ -1163,6 +1174,7 @@ export class MemoryStore {
     };
     const roots = new Set<string>(), fixed = new Set<string>();
     for (const store of this.readStores()) {
+      if (!store.bootstrapOnly) rebindPublicPruneProfile(store.profile);
       roots.add(store.dir);
       for (const name of ["profile.json", "shards.json", "aliases.jsonl", "lifecycle.jsonl", "machine.json"]) fixed.add(join(store.profile.home, name));
       for (const name of ["generation.json", "generation-seal.json", "migration-sources.json", "machine.json"]) fixed.add(join(store.dir, name));
@@ -1194,6 +1206,7 @@ export class MemoryStore {
   }
   private prepareRecallRead(stores: readonly MemoryStore[]): void {
     for (const store of stores) {
+      if (!store.bootstrapOnly) rebindPublicPruneProfile(store.profile);
       const active = readSelector(store.profile.home);
       if (active.revision !== store.profile.selectorRevision) throw Error("recall profile changed");
       if (store.profile.sharded) {
@@ -1256,6 +1269,7 @@ export class MemoryStore {
       if (!Number.isFinite(time) || new Date(time).toISOString() !== value || time > present) throw Error("as-of must be a past canonical UTC date or timestamp");
     }
     const frontier = () => {
+      if (!this.bootstrapOnly) for (const store of this.readStores()) rebindPublicPruneProfile(store.profile);
       const active = readSelector(this.profile.home);
       if (active.revision !== this.profile.selectorRevision) throw Error("recall profile changed or is not active");
       if (this.profile.sharded) {
@@ -1552,6 +1566,18 @@ export function buildGenerationIndex(profile: BoundProfile, sources: readonly Le
   finally { store.close(); }
 }
 
+/** Trusted activation bootstrap; caller holds profile + realm mutation fences. */
+export function buildPublicPruneIndex(profile: BoundProfile): {targets:string[];sourceHash:string} {
+  const sources = readShardLegacySnapshot(profile, {}).map(({bytes:_bytes,local:_local,...prefix}) => prefix);
+  const store = new MemoryStore({deferPromotions:true}, {token:MIGRATION_BOOTSTRAP, profile, limits:sources});
+  try {
+    const before = store.derivedTables(); store.rebuild(); const tables = store.derivedTables();
+    if (!isDeepStrictEqual(before, tables)) throw new Error("public prune view rebuild differs from incremental index");
+    return { targets: (tables.generation_targets as {id:string}[]).map(row=>row.id).sort(),
+      sourceHash: hashJSON([tables.generation_rows, tables.generation_prunes, tables.generation_segments, tables.generation_state]) };
+  } finally {store.close();}
+}
+
 function initializeShard(home: string, opts: { project?: string; user?: boolean }): void {
   const selection = readShardedSelection(home), generation = selection.generation;
   const dir = opts.user === true ? userShardDir(home) : shardDir(home, opts.project!), machine = machineId(home);
@@ -1564,7 +1590,9 @@ function initializeShard(home: string, opts: { project?: string; user?: boolean
   }
   const legacyHome = join(dir, "legacy"), sources = readMigrationSources(legacyHome);
   writeProfileJSON(join(dir, "migration-sources.json"), { schema: "agent-mem.migration-sources/v1", sources });
+  const selected = readSelector(home).selector;
   const profile: BoundProfile = { kind: "generation", home, dir, generation, selectorRevision: selection.selectorRevision,
+    ...(selected?.schema === "agent-mem.profile/v2" ? {foreignPruneFormat: selected.foreignPruneFormat, pruneInputSetHash: selected.pruneInputSetHash} : {}),
     legacyHome, legacyMainHome: join(dir, "legacy-main"), sharded: true, ...(opts.user === true ? { shardUser: true } : { shardKey: opts.project! }) };
   buildGenerationIndex(profile, sources);
   writeProfileJSON(join(dir, "generation-seal.json"), { schema: "agent-mem.generation-seal/v1", generation,
@@ -1577,17 +1605,27 @@ export function openShardStore(opts: StoreOptions & { project?: string; user?: b
   if (opts.memoryDir !== undefined && (opts.home !== undefined || typeof opts.memoryDir !== "string" || !opts.memoryDir.trim())) throw new Error("choose a memory home or one explicit memory directory");
   const home = opts.memoryDir ?? (opts.home === undefined ? memoryHome() : join(opts.home, "memory"));
   assertCuratedShardPaths(home, opts);
-  // #15 T5: the one gate every recall path shares, checked before a shard can be created. The user shard has no lifecycle.
+  // Lifecycle refusal must remain before admission creates any lease/fence file.
   if (opts.user !== true && opts.lifecycle !== "ignore") assertProjectActive(home, opts.project!);
+  readShardedSelection(home); // validate the floor before any lazy shard initialization
+  const admission = registerReaderLease(home, {scope:"shard"});
+  try {
   const dir = opts.user === true ? userShardDir(home) : shardDir(home, opts.project!);
   const missing = !existsSync(join(dir, "generation.json"));
-  if (missing) initializeShard(home, opts);
+  if (missing) {
+    const selected = readSelector(home).selector;
+    if (selected?.schema === "agent-mem.profile/v2") {
+      const view = readPublicPruneView(home, selected.pruneInputSetHash, selected.generation), key = opts.user ? "user" : `project:${opts.project}`;
+      if (view.realms[key] || ["generation-seal.json", "migration-sources.json", "machine.json"].some(name => existsSync(join(dir, name)))) throw new Error("v2 generation input unavailable; reader cannot repair committed inputs");
+    }
+    initializeShard(home, opts);
+  }
   const profile = resolveShardProfile(home, opts);
   const { reconcile, ...plain } = opts;
   const userOverlay = opts.user === true ? undefined : openShardStore({ ...plain, project: undefined, user: true });
   const aliasStores: MemoryStore[] = [];
   try {
-    // #27: read-only reconciliation never creates an alias shard. A person-only project import explicitly can.
+    // #27: read-only reconciliation never creates an alias shard. An explicit project import can.
     if (opts.user !== true && reconcile && reconcile.canonical === opts.project) {
       for (const alias of reconcile.aliases) {
         if (alias === opts.project || !opts.createAliases && !existsSync(join(shardDir(home, alias), "generation.json"))) continue;
@@ -1598,9 +1636,10 @@ export function openShardStore(opts: StoreOptions & { project?: string; user?: b
     }
     return new MemoryStore(opts, { token: MIGRATION_BOOTSTRAP, profile, authoring: true, userOverlay, aliasStores });
   } catch (error) { for (const store of aliasStores) store.close(); userOverlay?.close(); throw error; }
+  } finally { admission(); }
 }
 
-/** Person-only migration receipt; this inspector reads raw rows without opening a store or writing any index. */
+/** Administrative migration receipt; this inspector reads raw rows without opening a store or writing any index. */
 export function summarizeRawExpiry(rawLines: string[], now: number, tailBytes: number): import("./migrate.ts").MigrationCounts {
   const bytes = Buffer.from(rawLines.filter(Boolean).join("\n") + (rawLines.length ? "\n" : ""));
   let malformed = 0;

package/src/memory/style.ts

@@ -23,6 +23,9 @@ export function style(color: boolean): Style {
 }
 export const PLAIN: Style = style(false);
 
+/** Data stays on one human-output row and cannot inject terminal or bidirectional controls. */
+export const singleLine = (text: string): string => text.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, " ");
+
 /** Status label, padded so the columns line up; the word is always present. */
 export function label(s: Style, state: "ok" | "attention" | "skipped" | "unavailable" | "error"): string {
   const word = { ok: "OK", attention: "ATTENTION", skipped: "SKIPPED", unavailable: "UNAVAILABLE", error: "ERROR" }[state].padEnd(11);

package/src/memory/sync.ts

@@ -1,5 +1,7 @@
-import { closeSync, existsSync, openSync, readFileSync, rmSync, writeFileSync, writeSync } from "node:fs";
-import { join } from "node:path";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, rmSync, writeFileSync, writeSync, type BigIntStats } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join, relative, sep } from "node:path";
+import { rebindPublicPruneProfile } from "./generation.ts";
 import { memoryGitArgv, memoryGitEnv, processLiveness, processSignature } from "./platform.ts";
 import { acquireMutation } from "./mutation.ts";
 import type { MemoryStore } from "./store.ts";
@@ -12,7 +14,9 @@ import { outboundScreen, screenOutboundRows, screenOwnSegment, type RowScreen }
  * machine's history never conflicts. Pull, then push; fail-open: a failure is a result with one reason, never a throw.
  */
 export type Visibility = "public" | "private" | "unknown";
-export interface SyncResult { ok: boolean; pushed: boolean; entries: number; warning?: string; error?: string }
+export interface SyncResult { ok: boolean; pushed: boolean; entries: number; warning?: string; error?: string;
+  pruneApplication?: {transport:"durable"|"unconfirmed";proofComplete:number;projectionActive:number|null;nativeApplied:number|null;held:number;phase:"preflight"|"prepared"|"active"|"complete"};
+}
 
 const GITIGNORE = "/*\n!/.gitignore\n!/log/\n/log/*\n!/log/*.jsonl\n";
 const STEP_MS = 60_000;
@@ -62,13 +66,19 @@ async function git(dir: string, args: string[], signal?: AbortSignal, ms = STEP_
 
 export { git as syncGit };
 
+/** Shared hardening for text history queries and bounded binary object reads. */
+function spawnGenerationGit(dir: string, args: string[], group: boolean) {
+  // The shell receives only positional arguments; its umask is child-local.
+  return Bun.spawn(["/bin/sh", "-c", 'umask 077; exec "$@"', "amem-git", ...memoryGitArgv(["-C", dir, ...args], { credentials: true })], { stdout: "pipe", stderr: "pipe", stdin: "ignore", env: memoryGitEnv(process.env, { repositoryIsolation: true }), ...(group ? { detached: true } : {}) });
+}
+
 /** Generation-only process isolation; shared-v1 above retains its pre-P9 spawn and environment contract. */
 export async function generationSyncGit(dir: string, args: string[], signal?: AbortSignal, ms = STEP_MS): Promise<{ code: number; out: string; err: string }> {
   if (signal?.aborted) return { code: -1, out: "", err: "stopped" };
   // A fixed child-only umask keeps Git-created metadata private without changing the daemon's process umask.
   // Args are positional shell parameters, never interpolated or evaluated as shell code.
   const group = signal !== undefined;   // see `git` above: own process group when the caller has a deadline
-  const p = Bun.spawn(["/bin/sh", "-c", 'umask 077; exec "$@"', "amem-git", ...memoryGitArgv(["-C", dir, ...args], { credentials: true })], { stdout: "pipe", stderr: "pipe", stdin: "ignore", env: memoryGitEnv(process.env, { repositoryIsolation: true }), ...(group ? { detached: true } : {}) });
+  const p = spawnGenerationGit(dir, args, group);
   const send = (name: "SIGTERM" | "SIGKILL") => { if (group) { try { process.kill(-p.pid, name); return; } catch { /* no group left: fall through to the pid */ } } p.kill(name); };
   const unregister = group ? register(p.pid) : () => {};
   // SIGTERM first, so git removes its lock files; SIGKILL only if it is still there after a grace period.
@@ -89,6 +99,53 @@ export async function generationSyncGit(dir: string, args: string[], signal?: Ab
 }
 
 
+/** Exact Git object bytes. Bounds apply only here, never to full text history audits. */
+export async function generationSyncGitBytes(dir: string, args: string[], signal?: AbortSignal, ms = STEP_MS, maxBytes = 2 * 1024 * 1024): Promise<{ code: number; out: Uint8Array; err: string }> {
+  const empty = () => new Uint8Array(0);
+  if (signal?.aborted) return { code: -1, out: empty(), err: "stopped" };
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || !Number.isFinite(ms) || ms <= 0) return { code: -1, out: empty(), err: "invalid git output bound or deadline" };
+  // A bound or deadline can stop this call even without a caller signal, so always own its group.
+  const p = spawnGenerationGit(dir, args, true), unregister = register(p.pid);
+  const send = (name: "SIGTERM" | "SIGKILL") => {
+    try { process.kill(-p.pid, name); } catch { try { p.kill(name); } catch { /* already exited */ } }
+  };
+  let hard: ReturnType<typeof setTimeout> | undefined, stopped = false, overflow = false;
+  const kill = () => { stopped = true; send("SIGTERM"); hard ??= setTimeout(() => send("SIGKILL"), 2_000); };
+  const timer = setTimeout(kill, ms);
+  signal?.addEventListener("abort", kill, { once: true });
+  // Drain both pipes concurrently, including after overflow. Waiting on exit before draining
+  // deadlocks a full pipe; cancelling a reader can leave inherited child pipes unaccounted for.
+  const collect = async (stream: ReadableStream<Uint8Array>, limit: number, refuse: boolean): Promise<Buffer> => {
+    const reader = stream.getReader(), chunks: Buffer[] = []; let size = 0;
+    try {
+      for (;;) {
+        const part = await reader.read(); if (part.done) break;
+        const bytes = part.value, remaining = limit - size;
+        if (refuse && bytes.byteLength > remaining) { overflow = true; chunks.length = 0; kill(); }
+        if (!refuse || !overflow) {
+          const keep = Math.min(remaining, bytes.byteLength);
+          if (keep) { chunks.push(Buffer.from(bytes.subarray(0, keep))); size += keep; }
+        }
+      }
+      return Buffer.concat(chunks);
+    } finally { reader.releaseLock(); }
+  };
+  const operations = [p.exited, collect(p.stdout, maxBytes, true), collect(p.stderr, 65_536, false)] as const;
+  try {
+    const [code, out, err] = await Promise.all(operations);
+    return overflow ? { code: -1, out: empty(), err: "git output exceeds byte bound" }
+      : stopped ? { code: -1, out: empty(), err: "stopped" } : { code, out, err: err.toString("utf8").trim() };
+  } catch {
+    kill(); await Promise.allSettled(operations);
+    return { code: -1, out: empty(), err: "git output unavailable" };
+  } finally {
+    // Reap descendants even if Git exited first while they retained its pipe handles.
+    if (stopped) send("SIGKILL");
+    unregister(); clearTimeout(timer); if (hard) clearTimeout(hard); signal?.removeEventListener("abort", kill);
+  }
+}
+
+
 /**
  * The `owner/repo` of a remote URL whose host is EXACTLY `github.com` (case-insensitive) over `https://`, `ssh://git@github.com/` or the scp form
  * `[git@]github.com:`; anything else is undefined, so it is `unknown` and never asked. An unanchored match let `https://notgithub.com/acme/notes`,
@@ -161,18 +218,97 @@ export interface SyncOptions {
   visibility?: (url: string) => Promise<Visibility>;
   /** An extra screen over each outbound row's text, on top of the machine's configured policy (the CLI passes the repository-narrowed policy). */
   screen?: RowScreen;
+  /** Host-only policy binding stamp, never authorization or a substitute for screening. */
+  policyVersion?: () => string;
   /** A stopping hub aborts: the running git step is killed and the sync ends without touching the store. */
   signal?: AbortSignal;
 }
 
+/** Metadata-only sharded sync epoch. Hash complete source bytes, never notes or unopened shards. */
+export function shardSyncBinding(store: MemoryStore): string { return captureShardSyncBinding(store, true); }
+/** Selection bytes may change only after this sync commits; source/policy identity remains pinned across that commit. */
+export function shardSyncSourceBinding(store: MemoryStore): string { return captureShardSyncBinding(store, false); }
+function captureShardSyncBinding(store: MemoryStore, selection: boolean): string {
+  const unavailable = (): never => { throw new Error("sharded sync binding unavailable"); };
+  if (!store.profile.sharded) return unavailable();
+  const uid = process.getuid?.(); if (uid === undefined) return unavailable();
+  const same = (a: BigIntStats, b: BigIntStats) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
+  const owned = (stat: BigIntStats, directory: boolean, privateMode = true) => {
+    if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1n)
+      || stat.uid !== BigInt(uid) || privateMode && (stat.mode & 0o077n) !== 0n) unavailable();
+  };
+  const home = store.profile.home, digest = createHash("sha256"), directories = new Map<string, BigIntStats>(), checks: (() => void)[] = [];
+  const emit = (value: unknown) => { digest.update(JSON.stringify(value) + "\n"); };
+  const directory = (dir: string): void => {
+    if (directories.has(dir)) return;
+    const rel = relative(home, dir); if (rel === ".." || rel.startsWith(".." + sep)) unavailable();
+    if (dir !== home) directory(dirname(dir));
+    const before = lstatSync(dir, { bigint: true }); owned(before, true); directories.set(dir, before);
+    emit(["directory", dir, String(before.dev), String(before.ino)]);
+    checks.push(() => { const now = lstatSync(dir, { bigint: true }); owned(now, true); if (!same(before, now)) unavailable(); });
+  };
+  // Policy config keeps its established file modes inside this already-private owned home. Its complete bytes/inode still bind the epoch.
+  const source = (file: string, privateMode = true): void => {
+    directory(dirname(file));
+    let before: BigIntStats;
+    try { before = lstatSync(file, { bigint: true }); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      emit(["source", file, "absent"]);
+      checks.push(() => { if (lstatSync(file, { bigint: true, throwIfNoEntry: false }) !== undefined) unavailable(); }); return;
+    }
+    owned(before, false, privateMode);
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const opened = fstatSync(fd, { bigint: true }); owned(opened, false, privateMode); if (!same(before, opened)) unavailable();
+      const content = createHash("sha256"), buffer = Buffer.allocUnsafe(65_536); let bytes = 0n;
+      for (;;) { const n = readSync(fd, buffer, 0, buffer.length, null); if (!n) break; content.update(buffer.subarray(0, n)); bytes += BigInt(n); }
+      const after = fstatSync(fd, { bigint: true }); owned(after, false, privateMode);
+      if (bytes !== before.size || !same(before, after) || !same(before, lstatSync(file, { bigint: true }))) unavailable();
+      emit(["source", file, "present", String(before.dev), String(before.ino), String(before.size), String(before.mtimeNs), String(before.ctimeNs), content.digest("hex")]);
+    } finally { closeSync(fd); }
+    checks.push(() => { const now = lstatSync(file, { bigint: true }); owned(now, false, privateMode); if (!same(before, now)) unavailable(); });
+  };
+  try {
+    directory(home);
+    for (const name of [...(selection ? ["profile.json", "shards.json"] : []), "aliases.jsonl", "amem.config.json", "machine.json"]) source(join(home, name), name !== "amem.config.json");
+    const targets = [...store.openedSyncTargets()].sort((a, b) => a.dir.localeCompare(b.dir));
+    for (const target of targets) {
+      directory(target.dir);
+      emit(["target", target.dir, target.profile.generation ?? null, target.machine.id, target.profile.shardUser ?? false, target.profile.shardKey ?? null]);
+      for (const name of ["project.json", "generation.json", "generation-seal.json", "machine.json"]) source(join(target.dir, name));
+    }
+    for (const check of checks) check();
+    return digest.digest("hex");
+  } catch { return unavailable(); }
+}
+
 export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Promise<SyncResult> {
+  if (store.profile.sharded) {
+    try {
+      // Refresh only through the existing proved monotone profile rebind before pinning this attempt.
+      for (const target of store.openedSyncTargets()) rebindPublicPruneProfile(target.profile);
+      const binding = shardSyncBinding(store), policyVersion = opts.policyVersion?.();
+      const assertBinding = () => {
+        if (opts.policyVersion?.() !== policyVersion || shardSyncBinding(store) !== binding) throw new Error("binding changed");
+      };
+      assertBinding();
+      const screen = outboundScreen(store.profile.home, opts.screen);
+      const pass: RowScreen = row => { assertBinding(); const accepted = screen(row); assertBinding(); if (typeof accepted !== "boolean") throw new Error("invalid screen result"); return accepted; };
+      for (const target of store.openedSyncTargets()) {
+        const screened = screenOutboundRows(target, pass); assertBinding();
+        if (!screened.ok) return { ok: false, pushed: false, entries: 0, error: screened.reason };
+      }
+      const transport = await import("./shard-sync.ts"); assertBinding();
+      return transport.syncShardedMemory(store, opts);
+    } catch { return { ok: false, pushed: false, entries: 0, error: "sharded sync binding or policy unavailable or changed" }; }
+  }
   // F4: before anything is staged or pushed, this machine's own long-term notes pass the person's configured policy (every profile: single log, generation, shards).
   const pass = outboundScreen(store.profile.home, opts.screen);
   for (const target of store.openedSyncTargets()) {
     const screened = target.profile.kind === "generation" ? screenOutboundRows(target, pass) : screenOwnSegment(target.dir, target.machine.id, pass);
     if (!screened.ok) return { ok: false, pushed: false, entries: 0, error: screened.reason };
   }
-  if (store.profile.sharded) return (await import("./shard-sync.ts")).syncShardedMemory(store, opts);
   if (store.profile.kind === "generation") return syncGenerationMemory(store, opts);
   const dir = store.dir;
   const fail = (error: string): SyncResult => ({ ok: false, pushed: false, entries: 0, error });

package/src/memory/vault.ts

@@ -1,6 +1,7 @@
 import { validVaultPath } from "./generation.ts";
 import { createStandalonePolicy, type MemoryPolicy } from "./policy.ts";
 import type { MemoryStore, View, VaultEntry } from "./store.ts";
+import { label, PLAIN, singleLine, type Style } from "./style.ts";
 
 export interface VaultSelection { project: string; policy: MemoryPolicy; limit?: number }
 export type { VaultEntry } from "./store.ts";
@@ -29,6 +30,36 @@ export async function vaultCandidates(store: MemoryStore, options: VaultSelectio
     .sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id)).slice(0, options.limit ?? 50);
 }
 
+/** Human-readable list of screened vault candidates; raw note text is intentionally omitted. */
+export function vaultCandidatesText(rows: readonly View[], s: Style = PLAIN): string {
+  return [
+    `amem vault-candidates: ${rows.length ? s.attention("attention") : s.ok("complete")}`,
+    `${label(s, rows.length ? "attention" : "skipped")} candidates: ${rows.length}`,
+    ...rows.map(row => {
+      const title = singleLine(row.title ?? "(untitled)").slice(0, 120);
+      return `  ${label(s, "attention")} ${singleLine(row.project)}: ${row.id}  ${row.kind}  ${title}`;
+    }),
+    `Next action: ${rows.length ? "open the source repository, then review a candidate with amem show <id> before recording it in your vault" : "none; no screened durable candidates are available"}`,
+  ].join("\n");
+}
+
+/** Human-readable cross-project list, preserving project grouping and omitting note bodies. */
+export function vaultCandidatesAllText(result: {
+  crossedProjects: boolean;
+  projects: readonly { project: string; candidates: readonly View[] }[];
+}, s: Style = PLAIN): string {
+  const count = result.projects.reduce((sum, group) => sum + group.candidates.length, 0);
+  return [
+    `amem vault-candidates: ${count ? s.attention("attention") : s.ok("complete")}${result.crossedProjects ? " (across projects)" : ""}`,
+    `${label(s, count ? "attention" : "skipped")} candidates: ${count}`,
+    ...result.projects.flatMap(group => group.candidates.map(row => {
+      const title = singleLine(row.title ?? "(untitled)").slice(0, 120);
+      return `  ${label(s, "attention")} ${singleLine(group.project)}: ${row.id}  ${row.kind}  ${title}`;
+    })),
+    `Next action: ${count ? (result.crossedProjects ? "open the candidate's source repository, then review it with amem show <id> before recording it in your vault" : "open the source repository, then review a candidate with amem show <id> before recording it in your vault") : "none; no screened durable candidates are available"}`,
+  ].join("\n");
+}
+
 /** Person-facing hosts authenticate intent before calling; no MCP vault-link tool is provided. */
 export async function recordVaultLink(store: MemoryStore, id: string, path: string, options: VaultSelection): Promise<string> {
   const policy = selection(options);