@staix/agent-mem 0.5.0 → 0.7.0

package/src/memory/project-export.ts

@@ -0,0 +1,122 @@
+import { Database } from "bun:sqlite";
+import { closeSync, constants, existsSync, lstatSync, openSync, rmSync, statSync, writeSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { walkShards } from "./catalog.ts";
+import { openCuratedForRead, requireShard } from "./curated-read.ts";
+import { projectState } from "./lifecycle.ts";
+import { realPath } from "./platform.ts";
+import { createStandalonePolicy, type MemoryPolicy } from "./policy.ts";
+import { looksSecret } from "./screen.ts";
+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
+ * 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.
+ */
+
+export const EXPORT_SCHEMA = "agent-mem.project-export/v1";
+/**
+ * ponytail: a seam, not a lock. The destination is checked (for the message) and then claimed with O_EXCL (for the guarantee); a test sets `afterCheck` to create
+ * 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 interface ExportCounts { capture: number; curated: number; goals: number; workLists: number }
+export interface ExportResult { file: string; project: string; counts: ExportCounts; withheld: number }
+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 }
+
+function destination(base: string, to: string): string {
+  if (typeof to !== "string" || !to.trim()) throw new Error("export needs --to <file>");
+  const file = resolve(to), parent = dirname(file), name = basename(file);
+  if (!name || file === parent) throw new Error("--to names a file, not a directory root");
+  let parentReal: string;
+  try { if (!statSync(parent).isDirectory()) throw new Error(); parentReal = realPath(parent); }
+  catch { throw new Error("the destination directory does not exist"); }
+  let homeReal = base;
+  try { homeReal = realPath(base); } catch { /* a home that is not there yet holds nothing to collide with */ }
+  if (parentReal === homeReal || parentReal.startsWith(homeReal + sep)) throw new Error("the destination is inside the memory home; choose a folder outside it");
+  if (lstatSync(file, { throwIfNoEntry: false })) throw new Error("the destination exists; export never overwrites");
+  return join(parentReal, name);
+}
+
+export async function exportProject(base: string, key: string, opts: { to: string; policy?: MemoryPolicy }): Promise<ExportResult> {
+  const project = requireShard(base, key);
+  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);
+  const allowed = async (value: unknown): Promise<boolean> => !looksSecret(JSON.stringify(value)) && await policy.screen(value);
+  const counts: ExportCounts = { capture: 0, curated: 0, goals: 0, workLists: 0 };
+  let withheld = 0;
+  let fd: number;
+  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 stores: { close(): void }[] = [];
+  try {
+    out(`{"schema":${JSON.stringify(EXPORT_SCHEMA)},"project":${JSON.stringify(project)},"exportedAt":${JSON.stringify(new Date().toISOString())},"capture":[`);
+    let first = true;
+    const shard = walkShards(base).find(candidate => candidate.key === project);
+    for (const dir of shard?.machineDirs ?? []) {
+      const dbFile = join(dir, "capture.db");
+      if (!existsSync(dbFile)) continue;
+      const db = new Database(dbFile, { readonly: true });
+      try {
+        db.run("PRAGMA busy_timeout = 3000");
+        for (let after = 0; ;) {
+          const rows = db.query("SELECT id, at, project, agent, event, tool, paths, status, excerpt FROM rows WHERE id > ? ORDER BY id LIMIT ?").all(after, PAGE) as CaptureRowRaw[];
+          for (const r of rows) {
+            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++;
+          }
+          if (rows.length < PAGE) break;
+        }
+      } finally { db.close(); }
+    }
+    out(`],"curated":[`);
+    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;
+    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++;
+    }
+    out(`],"goals":[`);
+    first = true;
+    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++;
+    }
+    out(`],"workLists":[`);
+    first = true;
+    // 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++; }
+    }
+    out(`],"counts":${JSON.stringify(counts)},"withheld":${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
+    throw error;
+  } finally {
+    for (const store of stores) { try { store.close(); } catch { /* best effort */ } }
+  }
+  closeSync(fd);
+  return { file, project, counts, withheld };
+}

package/src/memory/project.ts

@@ -1,14 +1,66 @@
 import { createHash } from "node:crypto";
-import { basename, dirname, resolve } from "node:path";
-import { readFileSync } from "node:fs";
-import { memoryGitSync, realPath } from "./platform.ts";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { lstatSync, readFileSync } from "node:fs";
+import { memoryGitEnv, memoryGitSync, realPath } from "./platform.ts";
 
-/** Project names from the outermost superproject down to this repo. */
-export function projectChain(cwd: string): string[] {
-  const git = (dir: string, arg: string) => memoryGitSync(["-C", dir, "rev-parse", arg], { encoding: "utf8" }).stdout?.trim() ?? "";
+/** Host-owned read-only Git transport. Arguments are the existing Git operation, before platform argv hardening. */
+export type ProjectGitRead = (args: string[], env: NodeJS.ProcessEnv) => {
+  stdout: string; status: number | null; error?: unknown; signal?: string | null;
+};
+
+interface ProjectIdentityOptions {
+  repositoryIsolation?: boolean;
+  /** Host-only: native intake must not rebind a failed Git identity to a local fallback. */
+  strictGitErrors?: boolean;
+  /** Host-only transport seam; callers retain the same strict status and shape checks. */
+  gitRead?: ProjectGitRead;
+}
+class GitIdentityUnavailable extends Error { constructor() { super("Git project identity unavailable"); } }
+const unavailable = (): never => { throw new GitIdentityUnavailable(); };
+function canonicalCwd(cwd: string, strict: boolean | undefined): string {
+  if (!strict) return cwd;
+  try { const canonical = realPath(cwd); if (!lstatSync(canonical).isDirectory()) unavailable(); return canonical; }
+  catch { return unavailable(); }
+}
+/** Filesystem evidence only; unknown ancestry never certifies an ordinary non-Git directory. */
+function physicalGit(cwd: string): boolean {
+  const present = (file: string) => {
+    try { return !!lstatSync(file, { throwIfNoEntry: false }); }
+    catch { return unavailable(); }
+  };
+  for (let dir = cwd, depth = 0; depth < 32; dir = dirname(dir), depth++) {
+    if (present(resolve(dir, ".git")) || present(resolve(dir, "HEAD")) && present(resolve(dir, "objects"))) return true;
+    if (dir === dirname(dir)) return false;
+  }
+  return unavailable();
+}
+function checkedGit(args: string[], env: NodeJS.ProcessEnv, strict: boolean, gitRead?: ProjectGitRead, statuses = [0]) {
+  const result = gitRead ? gitRead(args, env) : memoryGitSync(args, { encoding: "utf8", env });
+  if (strict && (result.error || result.signal || !statuses.includes(result.status ?? -1) || typeof result.stdout !== "string"
+    || result.stdout.length > 64 * 1024 || result.stdout.includes("\0"))) unavailable();
+  return result;
+}
+function pathText(text: string, strict: boolean, empty = false): string {
+  if (strict && (text ? !isAbsolute(text) || /[\r\n]/.test(text) : !empty)) unavailable();
+  return text;
+}
+
+/** Project names from the outermost superproject down to this repo; isolation binds native hook cwd over inherited Git routing. */
+export function projectChain(cwd: string, options: ProjectIdentityOptions = {}): string[] {
+  cwd = canonicalCwd(cwd, options.strictGitErrors);
+  const strict = options.strictGitErrors === true && physicalGit(cwd);
+  const env = memoryGitEnv(process.env, options);
+  const git = (dir: string, arg: string) => pathText(checkedGit(["-C", dir, "rev-parse", arg], env, strict, options.gitRead).stdout?.trim() ?? "", strict, arg === "--show-superproject-working-tree");
   const top = git(cwd, "--show-toplevel");
   if (!top) return [basename(cwd)];
+  return projectChainAtRoot(top, options);
+}
 
+/** Internal callers that have already resolved the working root do not repeat its git lookup. */
+function projectChainAtRoot(top: string, options: ProjectIdentityOptions): string[] {
+  const strict = options.strictGitErrors === true;
+  const env = memoryGitEnv(process.env, options);
+  const git = (dir: string, arg: string) => pathText(checkedGit(["-C", dir, "rev-parse", arg], env, strict, options.gitRead).stdout?.trim() ?? "", strict, true);
   // claude-mem's native identity for a worktree is [parent, parent/worktree].
   // The worktree's .git file points into <parent>/.git/worktrees/<name>; the
   // ordinary superproject walk below remains unchanged for repos and submodules.
@@ -19,12 +71,13 @@ export function projectChain(cwd: string): string[] {
       const gitDir = resolve(top, match[1]!);
       if (/[/\\]\.git[/\\]worktrees[/\\][^/\\]+$/.test(gitDir)) {
         const parentRoot = dirname(dirname(dirname(gitDir)));
-        const parent = projectChain(parentRoot);
+        const parent = projectChain(parentRoot, options);
         const parentName = basename(parentRoot);
         return [...parent, `${parentName}/${basename(top)}`];
       }
     }
-  } catch {
+  } catch (error) {
+    if (error instanceof GitIdentityUnavailable) throw error;
     // A missing or unreadable .git file falls through to git's normal chain.
   }
 
@@ -32,7 +85,7 @@ export function projectChain(cwd: string): string[] {
   for (let dir = top; dir && chain.length < 8; dir = git(dir, "--show-superproject-working-tree")) {
     chain.unshift(basename(dir));
   }
-  return chain.length ? chain : [basename(cwd)];
+  return chain.length ? chain : [basename(top)];
 }
 
 /**
@@ -41,8 +94,13 @@ export function projectChain(cwd: string): string[] {
  * the main working root keeps two unrelated repositories that share a name apart while the main checkout, a
  * subdirectory and a worktree resolve to one key (that key is this machine's only, and root-invoked keys stay stable).
  */
-export function memoryProjectKey(cwd: string): string {
-  const url = memoryGitSync(["-C", cwd, "remote", "get-url", "origin"], { encoding: "utf8" }).stdout?.trim() ?? "";
+export function memoryProjectKey(cwd: string, options: ProjectIdentityOptions = {}): string {
+  cwd = canonicalCwd(cwd, options.strictGitErrors);
+  const strict = options.strictGitErrors === true && physicalGit(cwd);
+  const env = memoryGitEnv(process.env, options);
+  const origin = checkedGit(["-C", cwd, "remote", "get-url", "origin"], env, strict, options.gitRead, [0, 2]);
+  const url = origin.stdout?.trim() ?? "";
+  if (strict && (origin.status === 0 ? !url || /[\r\n]/.test(url) : !!url)) unavailable();
   // A URL's default port is not part of the repository (`ssh://git@github.com:22/o/r` is `github.com/o/r`); any other
   // port is, since another service may run there. An scp-style `host:path` has no port.
   const u = /^([a-z+]+):\/\/(?:[^@/]+@)?(\[[^\]/]+\]|[^/:]+)(?::(\d*))?\/(.+?)(?:\.git)?\/?$/i.exec(url); // an IPv6 host is bracketed
@@ -60,26 +118,77 @@ export function memoryProjectKey(cwd: string): string {
   // No usable remote: hash the main working root, not the cwd or git dir. Root-invoked keys therefore keep their
   // pre-#15 value while the main checkout, a subdirectory and a worktree resolve to ONE key (#15 D2/AC2). A bare
   // repository has no working root: its own directory is the stable identity for it and its worktrees.
-  const common = memoryGitSync(["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" }).stdout?.trim() ?? "";
+  // The bounded native hook port reads all ordinary-repository metadata in its second Git call. Git itself
+  // resolves core.worktree for --show-toplevel; no config interpretation or root guess replaces that result.
+  let location: string[];
+  if (strict && options.gitRead) {
+    const metadata = checkedGit(["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir", "--git-dir", "--is-bare-repository", "--show-toplevel", "--show-superproject-working-tree"], env, true, options.gitRead, [0, 128]);
+    const fields = metadata.stdout.trim().split("\n");
+    if (fields.length < 3 || !isAbsolute(fields[0]!) || !isAbsolute(fields[1]!) || !/^(true|false)$/.test(fields[2]!)) unavailable();
+    location = fields.slice(0, 3);
+    if (metadata.status === 128) {
+      // A bare repository emits exactly the three proven metadata rows before show-toplevel refuses.
+      // Any other failed/partial shape stays unknown; stderr never participates in an identity decision.
+      if (fields.length !== 3 || fields[2] !== "true") unavailable();
+      if (fields[0] === fields[1]) {
+        const root = canonicalCwd(fields[0]!, true);
+        return `${basename(root)}@${createHash("sha256").update(root).digest("hex").slice(0, 8)}`;
+      }
+    } else {
+      if ((fields.length !== 4 && fields.length !== 5) || fields[2] !== "false") unavailable();
+      pathText(fields[3]!, true);
+      if (fields.length === 5) pathText(fields[4]!, true);
+      if (fields[0] === fields[1]) {
+        const root = canonicalCwd(fields[3]!, true), realCommon = canonicalCwd(fields[0]!, true);
+        // A separate/symlinked directory literally named .git can carry a historical parent-root key.
+        // Only the established config/root path below can distinguish an explicit core.worktree there.
+        if (basename(realCommon) !== ".git" || dirname(realCommon) === root) {
+          const chain = [basename(root)];
+          // Match the existing outermost-superproject walk, without reinterpreting a parent's worktree label.
+          for (let parent = fields[4] ?? ""; parent && chain.length < 8;) {
+            chain.unshift(basename(parent));
+            parent = pathText(checkedGit(["-C", parent, "rev-parse", "--show-superproject-working-tree"], env, true, options.gitRead).stdout.trim(), true, true);
+          }
+          return `${chain.join("/")}@${createHash("sha256").update(root).digest("hex").slice(0, 8)}`;
+        }
+      }
+    }
+    // Linked worktrees and ambiguous .git directory roots retain the established resolution below.
+  } else {
+    location = checkedGit(["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir", "--git-dir", "--is-bare-repository"], env, strict, options.gitRead).stdout?.trim().split("\n") ?? [];
+  }
+  if (strict && (location.length !== 3 || !isAbsolute(location[0]!) || !isAbsolute(location[1]!) || !/^(true|false)$/.test(location[2]!))) unavailable();
+  const ordinary = location.length === 3 && location[0] === location[1] && /^(true|false)$/.test(location[2]!);
+  const common = location.length === 3 ? location[0]! : checkedGit(["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"], env, strict, options.gitRead).stdout?.trim() ?? "";
   if (common) {
     let realCommon = common;
-    try { realCommon = realPath(common); } catch { /* as given */ }
-    const bare = (memoryGitSync(["--git-dir", realCommon, "rev-parse", "--is-bare-repository"], { encoding: "utf8" }).stdout?.trim() ?? "") === "true";
-    let root = realCommon;
+    try { realCommon = realPath(common); } catch { if (strict) unavailable(); /* as given */ }
+    const bareText = ordinary ? location[2]! : checkedGit(["--git-dir", realCommon, "rev-parse", "--is-bare-repository"], env, strict, options.gitRead).stdout?.trim() ?? "";
+    if (strict && !/^(true|false)$/.test(bareText)) unavailable();
+    const bare = bareText === "true";
+    let root = realCommon, knownWorkingRoot = false;
     if (!bare) {
-      const configured = memoryGitSync(["--git-dir", realCommon, "config", "--path", "core.worktree"], { encoding: "utf8" }).stdout?.trim() ?? "";
-      const top = memoryGitSync(["-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).stdout?.trim() ?? "";
+      const config = checkedGit(["--git-dir", realCommon, "config", "--path", "core.worktree"], env, strict, options.gitRead, [0, 1]);
+      const configured = config.stdout?.trim() ?? "";
+      if (strict && (config.status === 0 ? !configured || /[\r\n]/.test(configured) : !!configured)) unavailable();
+      // Only a separate git directory without core.worktree needs another root lookup.
+      // Ordinary repositories already bind their root through the canonical .git directory.
+      const top = !configured && basename(realCommon) !== ".git"
+        ? checkedGit(["-C", cwd, "rev-parse", "--show-toplevel"], env, strict, options.gitRead).stdout?.trim() ?? "" : "";
       // Only an actual `.git` directory makes its parent the working root. A separate git dir shares its parent
       // with unrelated repositories, so the real worktree root (or, as a last resort, the unique git dir) is safer.
+      if (strict && !configured && basename(realCommon) !== ".git") pathText(top, true);
       root = configured ? resolve(realCommon, configured) : basename(realCommon) === ".git" ? dirname(realCommon) : top || realCommon;
+      knownWorkingRoot = !configured && basename(realCommon) === ".git";
     }
     let realRoot = root;
-    try { realRoot = realPath(root); } catch { /* as given */ }
-    return `${projectChain(realRoot).join("/")}@${createHash("sha256").update(realRoot).digest("hex").slice(0, 8)}`;
+    try { realRoot = realPath(root); } catch { if (strict) unavailable(); /* as given */ }
+    const chain = strict && bare ? [basename(realRoot)] : knownWorkingRoot ? projectChainAtRoot(realRoot, options) : projectChain(realRoot, options);
+    return `${chain.join("/")}@${createHash("sha256").update(realRoot).digest("hex").slice(0, 8)}`;
   }
   let real = cwd;
   try { real = realPath(cwd); } catch { /* as given */ }
-  return `${projectChain(cwd).join("/")}@${createHash("sha256").update(real).digest("hex").slice(0, 8)}`;
+  return `${projectChain(cwd, options).join("/")}@${createHash("sha256").update(real).digest("hex").slice(0, 8)}`;
 }
 
 /**

package/src/memory/reader-lease.ts

@@ -8,14 +8,15 @@ const READER_LEASE_SCHEMA = "agent-mem.reader-lease/v1";
 const RENEW_MS = 25_000;
 interface Lease { schema: typeof READER_LEASE_SCHEMA; pid: number; signature: string; renewedAt: string }
 export interface ReaderLease { (): void; verify(): void }
-interface OpenLease { refs: number; timer: ReturnType<typeof setInterval> }
+interface OpenLease { refs: number; timer: ReturnType<typeof setInterval>; busyTimeoutMs: number }
 const open = new Map<string, OpenLease>();
+let activeIdentity: { pid: number; signature: string } | undefined;
 
 const fileFor = (memoryDir: string, pid: number, signature: string) => join(memoryDir, "readers", `${pid}-${signature}.json`);
 const record = (pid: number, signature: string): Lease => ({ schema: READER_LEASE_SCHEMA, pid, signature, renewedAt: new Date().toISOString() });
 
-function withFence<T>(memoryDir: string, work: () => T): T {
-  const db = readerAdmissionDatabase(memoryDir);
+function withFence<T>(memoryDir: string, work: () => T, busyTimeoutMs = 3000): T {
+  const db = readerAdmissionDatabase(memoryDir, busyTimeoutMs);
   try { return db.transaction(work).immediate(); } finally { db.close(); }
 }
 
@@ -52,10 +53,20 @@ function admitReader(memoryDir: string): void {
 }
 
 /** One lease per process, reference-counted across handles; an unref'd timer does not keep the process resident. */
-export function registerReaderLease(memoryDir: string): ReaderLease {
-  const pid = process.pid, signature = processSignature(pid);
+export function registerReaderLease(memoryDir: string, options: { busyTimeoutMs?: number; signature?: string } = {}): ReaderLease {
+  const requestedTimeout = options.busyTimeoutMs ?? 3000;
+  if (!Number.isSafeInteger(requestedTimeout) || requestedTimeout < 0 || requestedTimeout > 3000) throw new Error("invalid reader admission busy timeout");
+  if (options.signature !== undefined && (typeof options.signature !== "string" || !/^[a-f0-9]{64}$/.test(options.signature))) throw new Error("invalid reader lease identity");
+  const pid = process.pid;
+  // A live reference already established this process lifetime; nested readers keep the same identity.
+  // Ownership and admission are still checked under the fence for every registration.
+  const inherited = open.size > 0 && activeIdentity?.pid === pid ? activeIdentity.signature : undefined;
+  if (inherited && options.signature !== undefined && options.signature !== inherited) throw new Error("reader lease identity changed");
+  // Host-only: the supplied hash must already describe this process's pinned native ps identity.
+  const signature = inherited ?? options.signature ?? processSignature(pid);
   if (!signature) throw new Error("cannot establish reader lease identity");
   const file = fileFor(memoryDir, process.pid, signature);
+  const busyTimeoutMs = open.get(file)?.busyTimeoutMs ?? requestedTimeout;
   mkdirSync(memoryDir, { recursive: true, mode: 0o700 });
   withFence(memoryDir, () => {
     admitReader(memoryDir);
@@ -77,12 +88,13 @@ export function registerReaderLease(memoryDir: string): ReaderLease {
         withFence(memoryDir, () => {
           ownedLease(memoryDir, file, signature);
           writeProfileJSON(file, record(process.pid, signature));
-        });
+        }, busyTimeoutMs);
       } catch { /* keep unknown evidence; migration admission remains fail-closed */ }
     }, RENEW_MS);
     timer.unref();
-    open.set(file, { refs: 1, timer });
-  });
+    open.set(file, { refs: 1, timer, busyTimeoutMs });
+    activeIdentity = { pid, signature };
+  }, busyTimeoutMs);
   let released = false;
   const release = () => {
     if (released) return;
@@ -97,8 +109,8 @@ export function registerReaderLease(memoryDir: string): ReaderLease {
       withFence(memoryDir, () => {
         ownedLease(memoryDir, file, signature);
         rmSync(file);
-      });
-    } catch { /* another actor replaced it: never remove its lease */ }
+      }, held.busyTimeoutMs);
+    } catch { /* Contention or replacement keeps evidence; never remove another actor's lease. */ }
   };
   return Object.assign(release, {
     verify(): void {

package/src/memory/recall-staleness.ts

@@ -0,0 +1,56 @@
+import { lstatSync, type Stats } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { isDenied } from "./platform.ts";
+import { fold, type StandalonePolicy } from "./policy.ts";
+import { nodePath } from "./project.ts";
+import type { View } from "./store.ts";
+
+export interface RecallStalenessOptions {
+  cwd: string; rootConfirmed?: boolean; deny?: readonly string[]; policy?: () => StandalonePolicy;
+  /** Host-only lexical glob/private-path checks run before any filesystem probe. */
+  allowedPath?: (path: string) => boolean;
+  maxProbes?: number;
+  probe?: (path: string) => Pick<Stats, "isSymbolicLink" | "isDirectory" | "mtimeMs">;
+}
+type PathState = { state: "present"; mtime: number } | { state: "missing" | "unknown" };
+/** Call-scoped metadata hint only. Unknown/denied paths never become a marker or a filesystem query. */
+export function createRecallStalenessProbe(options: RecallStalenessOptions): (view: Pick<View, "about" | "at">) => boolean | undefined {
+  const root = resolve(options.cwd), cache = new Map<string, PathState>(), requested = options.maxProbes ?? 32;
+  let remaining = Number.isSafeInteger(requested) && requested >= 0 ? Math.min(requested, 32) : 0;
+  const allowed = (path: string): boolean => {
+    try { return !isDenied(path, [...options.deny ?? []]) && !isDenied(fold(path), [...options.deny ?? []].map(fold)) && options.allowedPath?.(path) !== false && (!options.policy || options.policy().screenStandalone({ path })); }
+    catch { return false; }
+  };
+  const inspect = (path: string): PathState => {
+    if (!path || path.length > 4096 || isAbsolute(path) || /[\p{Cc}\p{Cf}\\]/u.test(path) || path.split("/").includes("..") || !allowed(path)) return { state: "unknown" };
+    const target = resolve(root, path), rel = relative(root, target); let current = root;
+    if (!rel || rel.startsWith("../") || isAbsolute(rel)) return { state: "unknown" };
+    const chainAllowed = () => { let at = root; for (const part of rel.split("/")) { at = join(at, part); if (!allowed(relative(root, at))) return false; } return true; };
+    if (!chainAllowed()) return { state: "unknown" };
+    if (cache.has(path)) return cache.get(path)!;
+    for (const component of rel.split("/")) {
+      current = join(current, component); const name = relative(root, current);
+      if (remaining < 1 || !allowed(name)) return { state: "unknown" };
+      remaining--;
+      try {
+        const stat = (options.probe ?? lstatSync)(current);
+        if (stat.isSymbolicLink() || current !== target && !stat.isDirectory()) return { state: "unknown" };
+        if (current === target) { const value: PathState = Number.isFinite(stat.mtimeMs) ? { state: "present", mtime: stat.mtimeMs } : { state: "unknown" }; if (!chainAllowed()) return { state: "unknown" }; cache.set(path, value); return value; }
+      } catch (error) { const value: PathState = { state: (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unknown" }; if (!chainAllowed()) return { state: "unknown" }; cache.set(path, value); return value; }
+    }
+    return { state: "unknown" };
+  };
+  // ponytail: same-user ancestor swaps are outside the current metadata-only fence. Descriptor-relative traversal
+  // is required before treating concurrent hostile filesystem mutation as supported. No source/symbol index is stored.
+  return view => {
+    const at = Date.parse(view.at); if (!Number.isFinite(at)) return undefined;
+    let known = false;
+    for (const node of view.about) {
+      const path = nodePath(node); if (path === undefined) continue;
+      const state = inspect(path);
+      if (state.state === "missing" && options.rootConfirmed === true || state.state === "present" && state.mtime > at) return true;
+      known ||= state.state === "present";
+    }
+    return known ? false : undefined;
+  };
+}

package/src/memory/recall.ts

@@ -0,0 +1,74 @@
+import type { MemoryStore, RecallStateOptions, RetainedRecallState, Graph, View } from "./store.ts";
+
+export interface RecallOptions extends RecallStateOptions { query?: string; limit?: number }
+/** Only public read semantics; mutation and exact-revision callers continue to use Store.get directly. */
+export function recallViewIsLive(view: View, now: number): boolean {
+  return !view.supersededBy && Number.isFinite(Date.parse(view.at))
+    && (view.expiresAt === null || Number.isFinite(Date.parse(view.expiresAt)) && Date.parse(view.expiresAt) > now);
+}
+const PROMOTION_NOTICE = "promotion time unknown: tier before promotion cannot be recovered";
+/** Narrow promotion uncertainty to emitted rows while retaining independent source diagnostics. */
+export function recallForViews(state: RetainedRecallState, views: View[]): RetainedRecallState {
+  const notices = state.notices.filter(notice => notice !== PROMOTION_NOTICE || views.some(view => view.promotedFrom));
+  return { ...state, views, notices, incomplete: state.sourceIncomplete === true || state.malformed > 0 || notices.length > 0 };
+}
+function personRecall(options: RecallStateOptions): void {
+  if ((options.history || options.asOf !== undefined) && options.person !== true) throw Error("historical recall requires authenticated person intent from the host");
+}
+export function recallRows(store: MemoryStore, project: string, options: RecallOptions = {}): RetainedRecallState {
+  personRecall(options);
+  const limit = options.limit ?? 5000;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > Number.MAX_SAFE_INTEGER) throw Error("recall limit must be a positive safe integer");
+  const state: RetainedRecallState = options.history || options.asOf !== undefined ? store.recallState(project, options)
+    : store.withDeferredPromotions(() => ({ at: new Date(store.readNow()).toISOString(), views: store.list({ project, limit: Number.MAX_SAFE_INTEGER }).filter(view => recallViewIsLive(view, store.readNow())), forgotten: [], relations: [], malformed: 0, incomplete: false, notices: [] }));
+  const words = options.query?.toLowerCase().split(/\s+/).filter(Boolean) ?? [];
+  const rows = state.views.filter(view => words.every(word => `${view.title ?? ""}\n${view.text}\n${view.about.join(" ")}`.toLowerCase().includes(word)))
+    .sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id));
+  const selected = recallForViews(state, rows.slice(0, limit));
+  return { ...selected, incomplete: selected.incomplete || rows.length > limit };
+}
+export interface RecallShown { entry?: View; state?: RetainedRecallState; ids: string[] }
+export function recallShow(store: MemoryStore, project: string, rawId: string, options: RecallStateOptions = {}): RecallShown {
+  personRecall(options);
+  const id = rawId.replace(/^mem:/, "");
+  if (!/^[a-f0-9]{6,32}$/.test(id)) return { ids: [] };
+  if (!options.history && options.asOf === undefined) {
+    const view = store.withDeferredPromotions(() => store.get(id, project));
+    return view && recallViewIsLive(view, store.readNow()) ? { entry: view, ids: [view.id] } : { ids: [] };
+  }
+  const state = store.recallState(project, options), known = [...new Set([...state.views.map(view => view.id), ...state.forgotten.map(row => row.id)])];
+  const matches = known.includes(id) ? [id] : known.filter(value => value.startsWith(id));
+  if (matches.length !== 1) return { ids: [] };
+  const selected = new Set(matches), queue = [...matches], knownIds = new Set(known);
+  if (options.history) for (let index = 0; index < queue.length && queue.length <= 64; index++) {
+    for (const edge of state.relations) for (const next of edge.from === queue[index] ? [edge.to] : edge.to === queue[index] ? [edge.from] : []) {
+      if (knownIds.has(next) && !selected.has(next)) { selected.add(next); queue.push(next); }
+    }
+  }
+  if (queue.length > 64) throw Error("recall history chain exceeds 64 retained entries");
+  const views = state.views.filter(view => selected.has(view.id));
+  return { entry: views.find(view => view.id === matches[0]), ids: [...selected], state: { ...recallForViews(state, views), forgotten: state.forgotten.filter(row => selected.has(row.id)), relations: state.relations.filter(edge => selected.has(edge.from) && selected.has(edge.to)) } };
+}
+
+/** Public graph over live recall rows; retained history requires host-authenticated person intent. */
+export function recallGraph(store: MemoryStore, project: string, start: string, hops = 1, options: RecallOptions = {}, readable: (rows: View[]) => View[] = rows => rows): Graph {
+  personRecall(options);
+  const rows = readable(recallRows(store, project, { ...options, limit: Number.MAX_SAFE_INTEGER }).views);
+  let node = start;
+  if (!start.includes(":") || start.startsWith("mem:")) {
+    const id = start.replace(/^mem:/, ""), exact = rows.find(view => view.id === id), matches = exact ? [exact] : id.length >= 6 ? rows.filter(view => view.id.startsWith(id)) : [];
+    if (matches.length !== 1) return { nodes: [], edges: [] };
+    node = `mem:${matches[0]!.id}`;
+  }
+  return store.withDeferredPromotions(() => store.graph(project, node, hops, 200, rows));
+}
+
+/** One prepared snapshot; its revision guard rejects changes after asynchronous host policy work. */
+export function createIntentBriefSource(store: MemoryStore, project: string): { notes(): View[]; assertCurrent(): void; truncated(): boolean } {
+  let snapshot: ReturnType<MemoryStore["intentSnapshot"]> | undefined;
+  return {
+    notes: () => { snapshot ??= store.intentSnapshot(project); return snapshot.rows; },
+    assertCurrent: () => { if (!snapshot) throw Error("intent snapshot has not been prepared"); snapshot.assertCurrent(); },
+    truncated: () => snapshot?.truncated ?? false,
+  };
+}