@staix/agent-mem 0.16.0 → 0.18.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -2,7 +2,7 @@
 
 Curated memory with append-only JSONL logs, a derived SQLite index, short- and long-term tiers, a typed graph, goals with leases, and git sync between machines. Extracted from [agent-hub](https://github.com/STAIxBWLB/agent-hub), with compatible storage and entry IDs.
 
-Version: 0.16.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.18.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 
@@ -151,6 +151,24 @@ Open a review-only `MemoryStore` with `deferPromotions: true` to prevent unrelat
 
 Acceptance normalizes its note once, including timestamp, content ID and short-term expiry, then screens and appends that exact body. The final target-revision check and correction appends hold the same machine-local `mutation-lock.db` writer transaction used by this version's ordinary memory, import and sync writers. This lock is independent of the derived index, so an ordinary write still persists when SQLite is busy. External or older writers that edit segments without this lock do not participate in serialization. The logs remain authoritative after an interrupted acceptance; the next read refreshes the derived index.
 
+## Console (acon)
+
+`@staix/agent-mem/ui-plugin` is a plugin for the local agent console `acon` (STAIxBWLB/agent-console, contract api 1). It adds a Memory area with the panels Review, Recap, Search, Timeline, Work lists, Goals and Capacity, puts pending candidates (group `candidate`) and a capture capacity proposal (group `alert`) in the console inbox, and answers the console palette with memory search hits.
+
+```sh
+amem setup console           # preview
+amem setup console --apply   # write $AGENTHUB_HOME/console/plugins/amem.json
+amem setup console --undo    # remove it (only when it points at this install)
+```
+
+The manifest holds the absolute path and sha256 of `src/ui/plugin.ts`, in a 0700 directory and a 0600 file, as acon requires. acon refuses a module whose hash changed, so run `amem setup console --apply` again after upgrading amem. `setup all` does not include it.
+
+- Reads are screened. Search, Timeline and Work lists call the in-process `amem_search`, `amem_timeline` and `amem_work_state_read` handlers for the chosen project and forward every option the tool declares, so console search returns exactly the `amem_search` set for the same query. Goals and the review queue pass the configured policy; a candidate that fails it, or whose target fails it, is not shown (the panel counts it and points to `amem review walk`). The console never shows unscreened content, also not to the person. It runs in no repository, so a repository's `.amem/config` narrowing does not apply; the machine's `amem.config.json` does.
+- Recap computes the current SessionStart brief only on its own panel snapshots, using machine policy. Curated and work inputs use bounded private scratch copies; capture is read-only, and no live reader lease is taken. It shows the full context, coverage, partial status, token upper bound and generation time; it is not a stored copy of a prior session's injected brief. The console has no repository binding, so the repository section is absent. No recap or new capture field is stored in the memory home.
+- Review actions are the CLI's. Accept runs the same acceptance as `amem review accept` and writes the same note, edit-then-accept is `review walk`'s edit (the person's own note, then the candidate closed), reject is `review reject`. The console stamps the person as the actor (peer `person`). A privacy-screen hit refuses with a named reason and writes nothing. agent-mem keeps no reject reason, so a reason typed in the console is not recorded, and the reply says so.
+- Undo is offered for 10 seconds and stays bound to what that console just did: undoing an accept forgets the accepted note (an append-only forget op; a note a correction replaced shows again), undoing a reject makes the candidate pending again. A promotion has no undo. `merge_into` is not offered: the library has no merge operation.
+- Destructive forms (`gc`, `capacity_apply`, `project_forget`, `decay_apply`, `prune`) answer `needsConfirm` with the preview and `changes[]` and never write on the first call. The console's single-use confirm token carries the fingerprint back; the plugin recomputes the preview and writes only when it still matches. `prune` needs a generation home, as `amem prune` does.
+
 ## Shell completion
 
 Generate completion for `zsh`, `bash`, or `fish` with `amem completion <shell>`. Generation prints a script to stdout; it does not install files or edit shell configuration. The following commands configure shell completion.
@@ -217,6 +235,10 @@ The JSONL segments are authoritative. `index.db` is derived and can be rebuilt.
 
 From issue #13 (phase P1), the package carries a second, machine-local tier beside the curated store, born sharded (#15 T1): one capture shard per project key at `projects/<key-hash>/machine/<machine-id>/` under the memory home, with its own locks so two projects never contend. The capture tier records deterministic tool-event rows (project, agent, event, tool, paths, exit status and a bounded, secret-screened excerpt) in the shard's `capture.db`. It is never synced, never read as curated evidence, and never writes a curated log, so its maintenance can never evict notes, goals or work lists. Capture is bounded by a soft size cap and a retention window (defaults 512 MB per shard, 90 days), resolved at every invocation from the library options, then the shard's `config.json`, then the home default `capture-config.json`; eviction removes the oldest capture rows first in bounded batches. The 2026-10-17 owner decision keeps the P1 cap per shard; the machine-wide total is #15 T5. On lock contention a writer publishes a complete immutable per-writer spool segment and exits fast; the next uncontended writer replays the spool idempotently. The capture path makes no network or model call. The pre-T1 machine-wide `capture/` (an unreleased layout of this branch) is migrated per project on open and removed once empty.
 
+Claude's `PreToolUse`, `PostToolUse` and `PostToolUseFailure` excerpts start with a deterministic tool-input line before the existing content. String values use this key order: `command`, `pattern`, `query`, `url`, `description`, `prompt`, `skill`, `subject`, then other string fields in sorted key order. Bulk `content`, `old_string`, `new_string` and `edits` are omitted. Private spans are removed before clipping; the line is at most 512 UTF-8 bytes and the combined tool excerpt is at most 2,000 bytes or the lower configured `excerptBytes` limit. Existing envelope, secret/PII and path screens remain in force; a refused tool excerpt drops the row. Legacy rows and non-tool/other-client shaping are unchanged.
+
+Selected-project `store.search` and `amem_search` first reserve the existing unweighted result's non-capture cohort and capture slots. Only the capture slots are refilled: `Stop` and `UserPromptSubmit` receive a fixed 1.25x ordering weight, and only the best matching row per existing valid session hash is kept. A row without a hash is its own group. If distinct sessions run out, unused capture slots are omitted, yielding a shorter dense result while retaining the curated cohort and its relative order. Returned scores and explanations retain their unweighted priority values; the capture-slot ordering is separate. Collapsed rows remain accessible through timeline/show. The standalone `captureSearch` uses weighted session representatives too; `--all-projects` retains its existing separate merge. The SessionStart brief continues to use chronological capture pages, not this ranking or session collapse.
+
 Project identity (#15 D2) keeps `memoryProjectKey`: a worktree, a submodule and the main checkout of one repository share its key; two unrelated same-named repositories without a remote get distinct path-hash keys, flagged `local` in the shard's `project.json` and the catalog. A no-remote key hashes the main working root (using the actual top-level for a separate git dir), so keys written from the repository root keep their pre-#15 value. Known limit: a linked worktree of a no-remote separate-git-dir repository gets its own key, because git does not record that repository's main working root (probe: `alpha` and `alpha/sub` share `alpha@<hash>`, `alpha-wt` gets `alpha-wt@<hash>`); the key stays as is for root-key compatibility, and a reviewed alias reconciles its capture. Keys written by older builds from a subdirectory or worktree still used that invocation's cwd hash; an explicitly written alias maps such a key to its canonical one for capture, work lists and the CLI and MCP project binding. Curated rows written under the old key keep their key in the log (nothing is rewritten), and the CLI and MCP read them under the canonical project: the project filter of notes, goals, candidates, vault candidates and work lists covers the canonical key and every key aliased to it, and presents those rows under the canonical key (#27). The library `MemoryStore` still reads by the raw key unless a host passes `reconcile`, and shared rows stay visible as before. Writes still go to the key's own log and shard, and a settle or forget of an aliased row lands in the shard that holds it. `amem alias add <from-key> <to-key>` appends an op to `aliases.jsonl` (latest wins, never chained, never automatic), `amem alias remove <from-key>` appends a removal (the old key reads under itself again, the history stays), `amem alias list` shows the ops including removals. Both append an alias operation without a general TTY gate. An amem or hub older than this change ignores a removal and keeps the old binding until it is upgraded, so upgrade every host that shares the home first. A correction accepted on an aliased row lives under the canonical key, so after a removal the old key shows the superseded note again (see `docs/contracts.md`). `catalog.db` in the memory home (#15 D3's storage part) is derived only from the shards and the alias log and rebuilds to the same rows; the D3 management commands are #15 T5 and not built.
 
 `store.search(query, filter)` searches the curated tier and the current project's capture shard with SQLite FTS5 and BM25 plus tier/recency weighting: natural multi-word queries match partial term sets (the substring filter required every word), and a curated row outranks the same text in the capture tier. Prefix terms match inflections and Korean particles in either direction by retaining the original query term and adding a common-particle-stripped alternative. The FTS copy of the curated rows lives in its own derived `search.db` (`index.db`'s table set is a frozen contract and gains nothing); it is written from the same apply path as the index, and a prune, crash or rebuild is detected and resynced, so the incremental FTS copy equals a full resync. Where FTS5 is unavailable the engine falls back to the substring filter and reports `engine: "substring"`; capture recall needs FTS5 and is skipped in the fallback. The library entry exports `CaptureStore`, `captureSearch`, `readCaptureConfig`, `writeCaptureConfig`, `SearchIndex`, `fts5Available`, the shard helpers (`resolveAlias`, `appendAlias`, `listAliases`, `shardKeyHash`), the catalog (`rebuildCatalog`, `readCatalog`, `scanCatalog`) and the capacity advisor (`capacityReport`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,7 @@
     "bun": ">=1.4.2"
   },
   "devDependencies": {
+    "@staix/agent-console": "github:STAIxBWLB/agent-console#952e962",
     "@types/bun": "^1.3.0",
     "typescript": "^5.8.0",
     "@staix/agent-mem-v1": "npm:@staix/agent-mem@0.1.1",
@@ -20,11 +21,13 @@
     "@staix/agent-mem-v011": "npm:@staix/agent-mem@0.11.0",
     "@staix/agent-mem-v012": "npm:@staix/agent-mem@0.12.0",
     "@staix/agent-mem-v013": "npm:@staix/agent-mem@0.13.0",
-    "@staix/agent-mem-v015": "npm:@staix/agent-mem@0.15.0"
+    "@staix/agent-mem-v015": "npm:@staix/agent-mem@0.15.0",
+    "@staix/agent-mem-v017": "npm:@staix/agent-mem@0.17.0"
   },
   "exports": {
     ".": "./src/index.ts",
-    "./platform": "./src/memory/platform.ts"
+    "./platform": "./src/memory/platform.ts",
+    "./ui-plugin": "./src/ui/plugin.ts"
   },
   "bin": {
     "amem": "bin/amem.js"

package/src/cli.ts

@@ -271,7 +271,12 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   const { definition, options, rawArgs: args } = parsed;
   const identity = cliAttribution() ?? { actor: "person" as const, peer: "person" }, actor = identity.actor;
   if (parsed.path[0] === "setup") {
-    if (parsed.positionals.length !== 1 || options["--apply"] === true && options["--undo"] === true) throw new Error("usage: amem setup claude|codex|kimi|pi|qwen|jcode|opencode|gemini|agy|all [--apply|--undo]");
+    if (parsed.positionals.length !== 1 || options["--apply"] === true && options["--undo"] === true) throw new Error("usage: amem setup claude|codex|kimi|pi|qwen|jcode|opencode|gemini|agy|all|console [--apply|--undo]");
+    if (parsed.positionals[0] === "console") {
+      const { consoleSetup, consoleSetupText } = await import("./setup-console.ts");
+      const mode = options["--apply"] === true ? "apply" : options["--undo"] === true ? "undo" : "preview", result = consoleSetup(mode, context.env ?? process.env);
+      return options["--json"] === true ? JSON.stringify(result, null, 2) : consoleSetupText(result, mode);
+    }
     const { runSetup } = await import("./setup.ts");
     return runSetup(parsed.positionals[0]!, options["--apply"] === true ? "apply" : options["--undo"] === true ? "undo" : "preview", {
       env: context.env ?? process.env, stdinTTY: context.stdinTTY ?? process.stdin.isTTY, cwd: context.cwd ?? process.cwd(),

package/src/commands-table.ts

@@ -25,7 +25,7 @@ export const GLOBAL_OPTIONS = { "--help": flag("Show help") };
 export const ROOT_OPTIONS = { "--version": flag("Show version"), ...json };
 export const COMMANDS: Record<string, CommandDefinition> = {
   consolidate: { description: "Queue deterministic project-local consolidation candidates; curated notes change only after explicit acceptance", mutates: true, options: { ...json, "--project": text("The current project's key; another project is refused (run from its directory)") } },
-  setup: { description: "Preview reversible MCP setup and supported capture hooks for native coding CLIs; apply and undo use explicit flags", options: { ...json, "--apply": flag("Apply the previewed setup"), "--undo": flag("Restore the original configuration") }, args: [{ name: "target", values: ["claude", "codex", "kimi", "pi", "qwen", "jcode", "opencode", "gemini", "agy", "all"] }] },
+  setup: { description: "Preview reversible MCP setup and supported capture hooks for native coding CLIs, or the acon console plugin manifest (console); apply and undo use explicit flags", options: { ...json, "--apply": flag("Apply the previewed setup"), "--undo": flag("Restore the original configuration") }, args: [{ name: "target", values: ["claude", "codex", "kimi", "pi", "qwen", "jcode", "opencode", "gemini", "agy", "all", "console"] }] },
   mcp: { description: "Run the project-bound MCP stdio server for this session" },
   hook: { description: "Run a fail-open, context-only Claude Code hook", args: [{ name: "event", values: [...HOOK_EVENTS] }] },
   ingest: { description: "Incrementally capture native session transcripts without a watcher", options: { ...json, "--since": text("ISO date or time") }, args: [{ name: "kind", values: ["codex", "kimi", "pi", "qwen"] }] },

package/src/hook-spool.ts

@@ -3,7 +3,7 @@ import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openS
 import { dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import type { CaptureAppend, CaptureInput } from "./memory/capture.ts";
-import { normalizeCaptureFields, type NormalizedCaptureFields } from "./memory/capture-input.ts";
+import { CAPTURE_MAX_EXCERPT, clipCaptureUtf8, normalizeCaptureFields, toolCaptureExcerpt, toolInputLine, type NormalizedCaptureFields } from "./memory/capture-input.ts";
 import { canonicalPath, realPath } from "./memory/platform.ts";
 import { createStandalonePolicy, type StandalonePolicyOptions } from "./memory/policy.ts";
 import { configuredPolicyOptions, loadAmemConfig, repoConfigRoot } from "./memory/config.ts";
@@ -13,15 +13,18 @@ import { appendMetrics, type CaptureDropReason } from "./memory/metrics.ts";
 import { projectState } from "./memory/lifecycle.ts";
 import { HOOK_EVENTS, HOOK_INPUT_BYTES } from "./hook-contract.ts";
 
-const SCHEMA = "agent-mem.hook-capture/v1";
+// #199: v1 records (closed key set, no format field) are read, never written. Every 0.14-0.17 decoder deletes a record it cannot verify,
+// so a record that adds a field publishes under a name the v1 pattern does not match (`hook-v2-`); old versions then ignore it
+// (they still count it toward their file and byte caps). A later format that adds fields takes a new prefix again.
+const SCHEMA = "agent-mem.hook-capture/v1", FAMILY = "agent-mem.hook-capture", FORMAT = 2, PREFIX = "hook-v2-";
 const RECORD_BYTES = HOOK_INPUT_BYTES + 8192, MAX_FILES = 256, MAX_BYTES = 2 * 1024 * 1024;
 const DRAIN_FILES = 32, DRAIN_BYTES = 256 * 1024;
 // ponytail: a finite native admission reserve covers deferred replay, not unlimited locked intake.
 // Upgrade: coordinated append-only capacity accounting and observable backpressure at exhaustion.
 const CAPACITY_FILES = 32, CAPACITY_BYTES = 256 * 1024;
-const namePattern = /^(hook-([a-f0-9]{64})-([a-f0-9]{64})-([a-f0-9]{32})\.json)(?:\.draining-[a-f0-9]{24})?$/;
+const namePattern = /^(hook-(?:v2-)?([a-f0-9]{64})-([a-f0-9]{64})-([a-f0-9]{32})\.json)(?:\.draining-[a-f0-9]{24})?$/;
 const hash = (value: string | Uint8Array) => createHash("sha256").update(value).digest("hex");
-interface Record { schema: typeof SCHEMA; cwd: string; scope: string | null; root?: string; nonce: string; capture: NormalizedCaptureFields }
+interface Record { schema: string; format?: number; cwd: string; scope: string | null; root?: string; nonce: string; capture: NormalizedCaptureFields }
 export interface PendingHookCapture { name: string; cwd: string; receipt: string; deferred?: true; backlog?: true }
 export class HookSpoolFull extends Error { constructor() { super("hook storage full"); } }
 interface Options { cwd: string; base: string; policy?: StandalonePolicyOptions; deferAtCapacity?: true }
@@ -264,17 +267,21 @@ function claimOwned(base: string, name: string, file: OwnedFile): OwnedFile | un
   const owned = { ...file, file: claim };
   return owns(owned) ? owned : undefined;
 }
-function decoded(file: OwnedFile): { value: Record; bytes: Buffer } | undefined {
+/** `unknown`: a valid envelope (cwd, nonce, scope) under an unknown or newer schema. It stays pending until the TTL, never read as corrupt. */
+function decoded(file: OwnedFile): { value: Record; bytes: Buffer; unknown?: true } | undefined {
   if (file.initial.size > RECORD_BYTES) return undefined; // Positively oversized: do not materialize its body.
   const bytes = Buffer.alloc(file.initial.size);
   if (readSync(file.fd, bytes, 0, bytes.length, 0) !== bytes.length || !owns(file)) throw new Error("hook record changed");
   try {
     const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) as Record;
-    if (!value || typeof value !== "object" || Array.isArray(value) || ![5, 6].includes(Object.keys(value).length)
-      || Object.keys(value).some(key => !["schema", "cwd", "scope", "root", "nonce", "capture"].includes(key))
-      || value.root !== undefined && (typeof value.root !== "string" || !/^[a-f0-9]{64}$/.test(value.root))
-      || value.schema !== SCHEMA || typeof value.cwd !== "string" || !/^[a-f0-9]{32}$/.test(value.nonce)
+    if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.cwd !== "string" || typeof value.nonce !== "string" || !/^[a-f0-9]{32}$/.test(value.nonce)
       || value.scope !== null && (typeof value.scope !== "string" || !/^[a-f0-9]{64}$/.test(value.scope))) return undefined;
+    const v1 = value.schema === SCHEMA && !("format" in value), current = value.schema === FAMILY && value.format === FORMAT;
+    if (!v1 && !current) return typeof value.schema === "string" ? { value, bytes, unknown: true } : undefined;
+    const keys = current ? 1 : 0;
+    if (![5 + keys, 6 + keys].includes(Object.keys(value).length)
+      || Object.keys(value).some(key => !["schema", "cwd", "scope", "root", "nonce", "capture", ...current ? ["format"] : []].includes(key))
+      || value.root !== undefined && (typeof value.root !== "string" || !/^[a-f0-9]{64}$/.test(value.root))) return undefined;
     const c = value.capture;
     if (!c || typeof c !== "object" || Array.isArray(c) || Object.keys(c).length < 8 || Object.keys(c).length > 10
       || Object.keys(c).some(key => !["at", "agent", "event", "tool", "paths", "status", "excerpt", "bytes", "session", "subagent"].includes(key))
@@ -394,7 +401,11 @@ function retireUnresolved(base: string, _admittingCwd: string | undefined, inven
         const record = decoded(file);
         const valid = record && hash(record.value.cwd) === match[2] && record.value.nonce === match[4] && (record.value.scope ?? "0".repeat(64)) === match[3];
         let reason: CaptureDropReason | undefined;
-        if (valid) {
+        if (valid && record.unknown) {
+          // #199: a newer writer's record waits for a reader that knows it, then leaves with a counted reason, never at once.
+          if (Date.now() - row.modified < RETIRE_AFTER_MS) continue;
+          reason = "unknown_schema_expired";
+        } else if (valid) {
           if (Date.now() - Date.parse(record.value.capture.at) < RETIRE_AFTER_MS) continue;
           try { const cwd = lstatSync(record.value.cwd); if (!cwd.isDirectory() || cwd.isSymbolicLink()) reason = "cwd_removed"; }
           catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") reason = "cwd_removed"; }
@@ -465,19 +476,27 @@ export async function stageHookCapture(event: string, input: unknown, options: O
   // F4: the person's configured caps apply at staging. Replay (`decoded`) re-normalizes with the built-in caps, which are the ceiling, so a record
   // staged under a tighter cap still verifies after the cap is raised or removed.
   const configured = loadAmemConfig(base, repoConfigRoot(cwd)).config;   // the repository's .amem/config narrows here too
+  const toolEvent = event === "PreToolUse" || event === "PostToolUse" || event === "PostToolUseFailure";
+  const contentText = typeof content === "string" ? content : JSON.stringify(content) ?? "";
+  const excerpt = toolEvent
+    ? clipCaptureUtf8(toolCaptureExcerpt(toolInputLine(tool), contentText), Math.min(CAPTURE_MAX_EXCERPT, configured.excerptBytes ?? CAPTURE_MAX_EXCERPT))
+    : contentText;
   // #173: attribution. Only a fixed-width hash of the native session id is kept, never the id or transcript path;
   // a non-empty agent_id marks a subagent (or in-process teammate) event. Both are read from the already-screened input.
   const session = typeof value.session_id === "string" && value.session_id.length > 0 && value.session_id.length <= 256 ? hash(`amem-session\0${value.session_id}`).slice(0, 16) : undefined;
   const subagent = typeof value.agent_id === "string" && value.agent_id.length > 0;
   const capture = normalizeCaptureFields({ agent: "claude", event, paths, status: event === "PostToolUseFailure" ? "failed" : "ok",
     ...(session ? { session } : {}), ...(subagent ? { subagent: true } : {}),
-    ...(typeof value.tool_name === "string" ? { tool: value.tool_name } : {}), excerpt: typeof content === "string" ? content : JSON.stringify(content) },
+    ...(typeof value.tool_name === "string" ? { tool: value.tool_name } : {}), excerpt },
     undefined,
-    (text: string) => looksSecret(text) || configured.piiPatterns.some(pattern => fold(text).includes(fold(pattern))),   // the configured patterns redact the excerpt, as the store does
+    (text: string) => looksSecret(text) || configured.piiPatterns.some(pattern => fold(text).includes(fold(pattern))),   // keep the normalizer's screen as well as the full envelope and bounded tool text screens
     { excerptBytes: configured.excerptBytes, paths: configured.capturePaths, ...(configured.denyPaths.length ? { denyPaths: configured.denyPaths } : {}) });
+  // The unchanged normalizer screen and final whole-capture policy also cover the joined input/content.
+  // Enriched tool rows are refused rather than persisting the normalizer's redaction marker.
+  if (toolEvent && capture.excerpt === "[secret-screened]") return undefined;
   if (!await policy.screen({ cwd, capture })) return undefined;
   const scope = hookCaptureScope(cwd, base) ?? null, nonce = randomBytes(16).toString("hex");
-  const record: Record = { schema: SCHEMA, cwd, scope, root: physicalRoot(cwd), nonce, capture }, bytes = JSON.stringify(record);
+  const record: Record = { schema: FAMILY, format: FORMAT, cwd, scope, root: physicalRoot(cwd), nonce, capture }, bytes = JSON.stringify(record);
   if (Buffer.byteLength(bytes) > RECORD_BYTES) throw new Error("hook record bound");
   const dir = directory(base), writing = join(dir, ".writing"); privateDirectory(dir); privateDirectory(writing);
   let destination = dir, deferred = false, backlog = false;
@@ -506,7 +525,7 @@ export async function stageHookCapture(event: string, input: unknown, options: O
       deferred = true;
     }
   }
-  const name = `hook-${hash(cwd)}-${scope ?? "0".repeat(64)}-${nonce}.json`, temporary = join(writing, name);
+  const name = `${PREFIX}${hash(cwd)}-${scope ?? "0".repeat(64)}-${nonce}.json`, temporary = join(writing, name);
   try { writeFileSync(temporary, bytes, { mode: 0o600, flag: "wx" }); renameSync(temporary, join(destination, name)); }
   finally { rmSync(temporary, { force: true }); }
   return { name, cwd, receipt: hash(bytes), ...(deferred ? { deferred: true as const } : {}), ...(backlog ? { backlog: true as const } : {}) };
@@ -548,6 +567,14 @@ export async function drainHookCaptures(options: Options & { project: string; ex
       if (!record || record.value.cwd !== cwd || record.value.scope !== null && record.value.scope !== stamp || record.value.nonce !== match[4]) {
         retireClaim(base, claim, false); blocked++; continue;
       }
+      // #199: an unknown or newer schema stays claimed and pending (later passes reclaim it) until the TTL, then retires with a counted reason.
+      // ponytail: pending unknown records still take drain slots oldest first; a writer that adds fields uses a new prefix, so this is the fallback only.
+      if (record.unknown) {
+        if (Date.now() - row.modified < RETIRE_AFTER_MS) { blocked++; continue; }
+        appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", captureDrops: 1, captureDropReason: "unknown_schema_expired" }]);
+        if (!retireClaim(base, claim, false)) blocked++;
+        continue;
+      }
       const value = record.value, c = value.capture;
       if (value.scope === null) { blocked++; continue; }
       // #15 T5: a project the person archived or forgot takes no new capture. Retire the record here with a counted reason instead of leaving it pending:

package/src/mcp-memory.ts

@@ -201,11 +201,12 @@ export function createMemoryMcp(options: MemoryMcpOptions): MemoryMcp {
         try {
           const words = query.toLowerCase().split(/\s+/).filter(Boolean);
           const captureState: { engine?: "fts5" | "substring" } = {};
-          let batch: { body: string; ref: string; tier: string; at: string; value: SearchValue; expiresAt?: string | null }[] = [];
+          let batch: { body: string; ref: string; tier: string; at: string; value: SearchValue; expiresAt?: string | null; event?: string; session?: string }[] = [];
           const append = (value: SearchValue) => {
             const row = value.source === "capture" ? value.capture : value.view;
             batch.push(value.source === "capture"
-              ? { value, ref: `capture:${value.capture.id}`, at: row.at, tier: "capture", body: `${value.capture.excerpt}\n${value.capture.paths.join(" ")}\n${value.capture.event}` }
+              ? { value, ref: `capture:${value.capture.id}`, at: row.at, tier: "capture", body: `${value.capture.excerpt}\n${value.capture.paths.join(" ")}\n${value.capture.event}`,
+                event: value.capture.event, ...(typeof value.capture.session === "string" && /^[a-f0-9]{16}$/.test(value.capture.session) ? { session: value.capture.session } : {}) }
               : { value, ref: value.source === "repo" ? `repo:${value.view.id}` : value.view.id, at: row.at, tier: value.source === "repo" ? "long" : value.view.tier, body: `${value.view.title ?? ""}\n${value.view.text}\n${value.view.about.join(" ")}`, expiresAt: value.source === "curated" ? value.view.expiresAt : null });
             if (batch.length === READ_PAGE) { index.append(batch); batch = []; }
           };
@@ -223,7 +224,16 @@ export function createMemoryMcp(options: MemoryMcpOptions): MemoryMcp {
           const repoNotes = (await repoRows()).filter(view => (!since || Date.parse(view.at) >= Date.parse(since)) && (useFts || words.every(word => `${view.title ?? ""}\n${view.text}\n${view.about.join(" ")}`.toLowerCase().includes(word))));
           for (const view of repoNotes) append({ source: "repo", evidence: false, view });
           if (batch.length) index.append(batch);
-          const selected = index.best(query, limit, store.readNow(), useFts, args.explain === true).map(({ value, score, scoreDetails }) => {
+          const now = store.readNow(), baseline = index.best(query, limit, now, useFts, args.explain === true);
+          const captureSlots = baseline.filter(hit => hit.value.source === "capture").length;
+          const weightedCapture = captureSlots ? index.bestCaptureGroups(query, captureSlots, now, useFts, args.explain === true) : [];
+          let captureIndex = 0;
+          // Keep every baseline noncapture slot and position. Only its capture slots receive weighted,
+          // one-per-session rows from the separately screened TEMP corpus; exhausted slots are omitted.
+          const selected = baseline.flatMap(hit => {
+            if (hit.value.source !== "capture") return [hit];
+            const replacement = weightedCapture[captureIndex++]; return replacement ? [replacement] : [];
+          }).map(({ value, score, scoreDetails }) => {
             const hit = { ...value, score };
             return scoreDetails ? { ...hit, scoreDetails: { source: value.source, ...scoreDetails } } : hit;
           });

package/src/memory/candidates.ts

@@ -38,6 +38,7 @@ export type CandidateInput = { project: string } & (
 export type CandidateStatus = "pending" | "accepting" | "accepted" | "rejected";
 export interface Candidate { id: string; createdAt: string; status: CandidateStatus; input: CandidateInput; acceptedNoteId: string | null }
 export interface ConsolidationReview { status: Exclude<CandidateStatus, "pending">; acceptedNoteId: string | null }
+const KINDS: readonly string[] = ["correction", "fail", "decay", "memory", "promotion", "consolidation", "model-answer"] satisfies CandidateInput["kind"][];
 export interface CandidateFilter { project: string; status?: CandidateStatus | "all"; kind?: CandidateInput["kind"]; limit?: number }
 export interface CounterKey { entryId: string; project: string; task?: string | null; turn?: string | null; session?: string | null; deliveryId: string }
 export interface CounterValues { rendered?: number | null; delivered?: number | null; cited?: number | null }
@@ -187,8 +188,12 @@ export class CandidateStore {
       this.db.query("DELETE FROM counters WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY at DESC, rowid DESC) AS rank FROM counters) WHERE rank > ?)").run(COUNTER_RETENTION.count);
     }).immediate();
   }
-  private decode(row: { id: string; payload: string; at: number; status: CandidateStatus; note_id: string | null }): Candidate {
-    const input = JSON.parse(row.payload) as CandidateInput; validate(input);
+  /** #199: rows of a kind this version does not know (a newer writer's) are skipped and counted here, never thrown. */
+  skippedUnknownKinds = 0;
+  private decode(row: { id: string; payload: string; at: number; status: CandidateStatus; note_id: string | null }): Candidate | undefined {
+    const input = JSON.parse(row.payload) as CandidateInput;
+    if (input && typeof input === "object" && !KINDS.includes(input.kind)) { this.skippedUnknownKinds++; return undefined; }
+    validate(input);
     if (hash({ schema: "agent-mem.candidate/v1", input }) !== row.id) throw new Error("candidate content hash mismatch");
     return { id: row.id, createdAt: new Date(row.at).toISOString(), status: row.status, input, acceptedNoteId: row.note_id };
   }
@@ -230,14 +235,16 @@ export class CandidateStore {
     return row ? { status: row.status, acceptedNoteId: row.note_id } : undefined;
   }
   list(filter: CandidateFilter): Candidate[] {
-    if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !["correction", "fail", "decay", "memory", "promotion", "consolidation", "model-answer"].includes(filter.kind)) throw new Error("invalid candidate filter");
+    if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !KINDS.includes(filter.kind)) throw new Error("invalid candidate filter");
     const limit = filter.limit ?? CANDIDATE_RETENTION.count;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > CANDIDATE_RETENTION.count) throw new Error("candidate limit must be 1..500");
     this.prune();
     const where = ["project IN (SELECT value FROM json_each(?))"], bind: (string | number)[] = [this.scope(filter.project)];
     if (filter.status === undefined) where.push("status IN ('pending', 'accepting')"); else if (filter.status !== "all") { where.push("status = ?"); bind.push(filter.status); }
     if (filter.kind) { where.push("kind = ?"); bind.push(filter.kind); }
-    return (this.db.query(`SELECT * FROM candidates WHERE ${where.join(" AND ")} ORDER BY at DESC, rowid DESC LIMIT ?`).all(...bind, limit) as Parameters<CandidateStore["decode"]>[0][]).map(row => this.decode(row));
+    // #199: unknown kinds are skipped before LIMIT, so a newer writer's rows never displace a supported candidate; they are still counted.
+    this.skippedUnknownKinds += (this.db.query(`SELECT count(*) AS n FROM candidates WHERE ${where.join(" AND ")} AND kind NOT IN (SELECT value FROM json_each(?))`).get(...bind, JSON.stringify(KINDS)) as { n: number }).n;
+    return (this.db.query(`SELECT * FROM candidates WHERE ${where.join(" AND ")} AND kind IN (SELECT value FROM json_each(?)) ORDER BY at DESC, rowid DESC LIMIT ?`).all(...bind, JSON.stringify(KINDS), limit) as Parameters<CandidateStore["decode"]>[0][]).flatMap(row => this.decode(row) ?? []);
   }
   recordCounter(key: CounterKey, values: CounterValues, verdict: CandidateVerdict): string {
     publicOnly(verdict); const normalized = counterKey(key);
@@ -264,6 +271,38 @@ export class CandidateStore {
       if (candidate.input.kind === "consolidation") this.retainConsolidationReviews();
     }).immediate();
   }
+  /**
+   * Undo of a reject: the rejected candidate is pending again. Only a rejected one; an accepted one is undone by forgetting its note.
+   * Retention deletes a decided candidate older than 30 days on the next open, so a caller offering undo passes the candidate it rejected as
+   * `restore`: when the row is already gone it is written back as pending with its original time, after the same identity and hash checks as a read.
+   */
+  reopen(id: string, context: { project: string; actor: "person" | "agent"; restore?: Candidate }): void {
+    validActor(context.actor);
+    if (!candidateId(id) || !text(context.project, 400)) throw new Error("invalid candidate identity");
+    this.db.transaction(() => {
+      // No prune here: it would delete the very row this undoes.
+      const row = this.db.query("SELECT * FROM candidates WHERE id = ? AND project IN (SELECT value FROM json_each(?))").get(id, this.scope(context.project)) as Parameters<CandidateStore["decode"]>[0] | null;
+      const candidate = row ? this.decode(row) : undefined, restore = context.restore;
+      if (candidate) {
+        if (candidate.status !== "rejected") throw new Error("only a rejected candidate can be reopened");
+        this.db.query("UPDATE candidates SET status = 'pending' WHERE id = ? AND status = 'rejected'").run(id);
+      } else {
+        if (!restore || restore.id !== id || !(JSON.parse(this.scope(context.project)) as string[]).includes(restore.input.project)) throw new Error("candidate unavailable");
+        validate(restore.input);
+        if (hash({ schema: "agent-mem.candidate/v1", input: restore.input }) !== id) throw new Error("candidate content hash mismatch");
+        const at = Date.parse(restore.createdAt);
+        if (!Number.isFinite(at)) throw new Error("invalid candidate time");
+        this.db.query("INSERT INTO candidates (id, project, kind, payload, at, status) VALUES (?, ?, ?, ?, ?, 'pending')").run(id, restore.input.project, restore.input.kind, canonical(restore.input), at);
+      }
+      const input = candidate?.input ?? restore!.input;
+      // The lasting review identity would make a later proposal of the same consolidation a no-op; the decision is withdrawn.
+      if (input.kind === "consolidation") this.db.query("DELETE FROM consolidation_reviews WHERE id = ?").run(id);
+    }).immediate();
+  }
+  /** Projects with candidates waiting for review, as stored (an alias key is not resolved here). */
+  projects(): string[] {
+    return (this.db.query("SELECT DISTINCT project FROM candidates WHERE status IN ('pending', 'accepting') ORDER BY project").all() as { project: string }[]).map(row => row.project);
+  }
   accept(id: string, context: CandidateAcceptance): CandidateAcceptanceResult {
     validActor(context.actor); publicOnly(context.verdict);
     if (realPath(context.store.profile.home) !== realPath(this.dir) || typeof context.policy !== "function") throw new Error("candidate acceptance requires its memory store and a current host policy");

package/src/memory/capture-input.ts

@@ -4,6 +4,9 @@ import { stripPrivateSpans } from "./private-spans.ts";
 
 export const CAPTURE_MAX_EXCERPT = 2000;
 export const CAPTURE_MAX_PATHS = 32;
+export const TOOL_INPUT_LINE_BYTES = 512;
+const TOOL_INPUT_ORDER = ["command", "pattern", "query", "url", "description", "prompt", "skill", "subject"] as const;
+const TOOL_INPUT_OMIT = new Set(["content", "old_string", "new_string", "edits"]);
 const ROW_OVERHEAD_BYTES = 96;
 /** The session key is a fixed-width hash prefix, so it adds a bounded amount covered by the row overhead. */
 export const SESSION_KEY = /^[a-f0-9]{16}$/;
@@ -22,6 +25,37 @@ export interface NormalizedCaptureFields {
   session?: string; subagent?: true;
 }
 
+/** Clip a string at a UTF-8 boundary without splitting a code point. */
+export function clipCaptureUtf8(text: string, maximumBytes: number): string {
+  let out = "", bytes = 0;
+  for (const character of text) {
+    const size = Buffer.byteLength(character);
+    if (bytes + size > maximumBytes) break;
+    out += character; bytes += size;
+  }
+  return out;
+}
+
+/** Deterministic, value-only summary of Claude tool_input. Strip private spans before clipping. */
+export function toolInputLine(input: unknown): string {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return "";
+  const fields = Object.entries(input as Record<string, unknown>)
+    .filter(([key, value]) => typeof value === "string" && !TOOL_INPUT_OMIT.has(key.toLowerCase()) && value.length > 0);
+  const byKey = new Map(fields);
+  const known = TOOL_INPUT_ORDER.filter(key => byKey.has(key));
+  const other = fields.map(([key]) => key).filter(key => !(TOOL_INPUT_ORDER as readonly string[]).includes(key)).sort();
+  const values = [...known, ...other].map(key => clipCaptureUtf8(
+    stripPrivateSpans(byKey.get(key) as string).replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, " "), TOOL_INPUT_LINE_BYTES,
+  )).filter(Boolean);
+  return clipCaptureUtf8(values.join(" | "), TOOL_INPUT_LINE_BYTES).trimEnd();
+}
+
+/** Remove private content before joining tool input and content into the persisted excerpt. */
+export function toolCaptureExcerpt(inputLine: string, content: string): string {
+  const visibleContent = stripPrivateSpans(content);
+  return inputLine ? visibleContent ? `${inputLine}\n${visibleContent}` : inputLine : visibleContent;
+}
+
 /** Pure capture shaping; no store, project lookup or filesystem operation is loaded or invoked here. */
 /** The caps a person's configuration may lower (F4); the built-in caps are the ceiling, so a larger value is ignored. */
 export interface CaptureCaps { excerptBytes?: number; paths?: number; denyPaths?: readonly string[] }

package/src/memory/cross-project.ts

@@ -44,9 +44,10 @@ export function searchAllProjects(base: string, query: string, opts: { limit?: n
       }
     } finally { store?.close(); }
     if (opts.includeCapture !== false) {
+      // #196 fixes selected-project store/MCP capture slots; this separate cross-project merge keeps its legacy cohort.
       for (const dir of shard.machineDirs) {
         const days = readCaptureConfig(dir, base).retentionDays, cutoff = new Date(now - days * 24 * 3600_000);
-        for (const { row, rank } of captureSearch(dir, query, Math.max(limit * 4, 32), Number.isFinite(cutoff.getTime()) ? cutoff.toISOString() : undefined)) {
+        for (const { row, rank } of captureSearch(dir, query, Math.max(limit * 4, 32), Number.isFinite(cutoff.getTime()) ? cutoff.toISOString() : undefined, { weightEvents: false, onePerSession: false })) {
           hits.push({ source: "capture", score: -rank * 0.5, capture: row as CaptureRow, project: shard.key });
         }
       }

package/src/memory/doctor.ts

@@ -2,7 +2,8 @@ import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync,
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { Database } from "bun:sqlite";
-import { sessionStartBrief } from "../session-brief.ts";
+import { sessionStartBrief, type BriefOptions } from "../session-brief.ts";
+import { openCuratedForRead } from "./curated-read.ts";
 import { pendingSummary } from "./candidate-pending.ts";
 import { readCaptureDrops } from "./metrics.ts";
 import { walkShards } from "./catalog.ts";
@@ -12,7 +13,7 @@ import { processLiveness, withGitTimeout } from "./platform.ts";
 import { endLikeSignal, STOP_SIGNALS } from "./sync-cadence.ts";
 import { boundRepoRoot } from "./repo-scope.ts";
 import { facts, label, PLAIN, type Style } from "./style.ts";
-import { shardDir } from "./shard.ts";
+import { aliasedKeys, shardDir } from "./shard.ts";
 import type { MemoryStore, View } from "./store.ts";
 import { nextSyncAt, readSyncState, remoteConfigured, syncDue, usableState } from "./sync-cadence.ts";
 
@@ -93,7 +94,22 @@ function curatedPresent(home: string, project: string, layout: Layout): boolean
 /** What a scratch copy leaves out: databases, locks, repositories, the machine-local capture and work trees, spools and ingest cursors. */
 const SKIP = /\.db(-wal|-shm)?$|\.lock$|\.tmp$|^\.git$|\.git$|^spool$|^ingest$|^readers$/;
 class TooBig extends Error {}
-function copyTree(from: string, to: string, budget: { bytes: number }, skipNames: ReadonlySet<string> = new Set()): void {
+interface CopyBudget { bytes: number; verify?: (() => void)[] }
+function observedCopy(from: string, to: string, budget: CopyBudget): void {
+  budget.bytes += statSync(from).size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
+  if (budget.verify) {
+    const stamp = () => { const s = lstatSync(from, { bigint: true }); if (!s.isFile()) throw Error("recap source is not a plain file"); return `${s.dev}:${s.ino}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`; };
+    const before = stamp(); budget.verify.push(() => { if (stamp() !== before) throw Error("recap source changed"); });
+  }
+  copyFileSync(from, to);
+}
+function observeDirectory(from: string, budget: CopyBudget, keep: (name: string) => boolean): void {
+  if (!budget.verify) return;
+  const stamp = () => { const s = lstatSync(from, { bigint: true }); if (!s.isDirectory()) throw Error("recap source directory changed"); return JSON.stringify([String(s.dev), String(s.ino), readdirSync(from).filter(keep).sort()]); };
+  const before = stamp(); budget.verify.push(() => { if (stamp() !== before) throw Error("recap source directory changed"); });
+}
+function copyTree(from: string, to: string, budget: CopyBudget, skipNames: ReadonlySet<string> = new Set()): void {
+  observeDirectory(from, budget, name => !(SKIP.test(name) && !(basename(from) === "public-prune-objects" && /^[a-f0-9]{40}\.git$/.test(name))) && !skipNames.has(name));
   mkdirSync(to, { recursive: true, mode: 0o700 });
   for (const name of readdirSync(from)) {
     const proofObject = basename(from) === "public-prune-objects" && /^[a-f0-9]{40}\.git$/.exec(name)?.[0] === name;
@@ -102,25 +118,24 @@ function copyTree(from: string, to: string, budget: { bytes: number }, skipNames
     if (proofObject && !stat.isFile()) throw new Error("a public prune object is not a plain file");
     if (stat.isSymbolicLink()) throw new Error("the memory home holds a link where a plain file or directory is expected");
     if (stat.isDirectory()) copyTree(source, join(to, name), budget, skipNames);
-    else if (stat.isFile()) { budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig(); copyFileSync(source, join(to, name)); }
+    else if (stat.isFile()) observedCopy(source, join(to, name), budget);
   }
 }
 
 /** The curated side of the home, without any database: the logs of this project (and its aliases), and the small files that bind them. */
-function copyCurated(options: DoctorOptions, layout: Layout, scratch: string, budget: { bytes: number }): void {
+function copyCurated(options: Pick<DoctorOptions, "home" | "project" | "aliases">, layout: Layout, scratch: string, budget: CopyBudget): void {
   const home = options.home;
+  observeDirectory(home, budget, name => !SKIP.test(name) && regularFile(join(home, name)));
   for (const name of readdirSync(home)) {      // top-level plain files: machine.json, shards.json, profile.json, aliases.jsonl, lifecycle.jsonl, the configuration
     if (SKIP.test(name) || !regularFile(join(home, name))) continue;
-    const stat = statSync(join(home, name)); budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
-    copyFileSync(join(home, name), join(scratch, name));
+    observedCopy(join(home, name), join(scratch, name), budget);
   }
   const selected = readSelector(home).selector;
   if (selected?.schema === "agent-mem.profile/v2") {
     const name = `${selected.pruneInputSetHash}.json`, source = join(home, "public-prune-input-sets", name), stat = lstatSync(source);
     if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error("the committed public prune view is not a plain file");
-    budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
     const directory = join(scratch, "public-prune-input-sets"); mkdirSync(directory, { mode: 0o700 });
-    copyFileSync(source, join(directory, name)); chmodSync(join(directory, name), 0o600);
+    observedCopy(source, join(directory, name), budget); chmodSync(join(directory, name), 0o600);
   }
   if (layout === "split") {
     for (const key of [options.project, ...options.aliases]) {
@@ -135,19 +150,56 @@ function copyCurated(options: DoctorOptions, layout: Layout, scratch: string, bu
 }
 
 /** The work logs of this project and its aliases, in a private base of their own: the brief opens a work list read-write and migrates its index. */
-function copyWork(options: DoctorOptions, base: string, budget: { bytes: number }): boolean {
+function copyWork(options: Pick<DoctorOptions, "home" | "project" | "aliases">, base: string, budget: CopyBudget): boolean {
   let any = false;
-  for (const name of ["machine.json", "aliases.jsonl", "lifecycle.jsonl"]) if (regularFile(join(options.home, name))) { mkdirSync(base, { recursive: true, mode: 0o700 }); copyFileSync(join(options.home, name), join(base, name)); }
+  for (const name of ["machine.json", "aliases.jsonl", "lifecycle.jsonl"]) if (regularFile(join(options.home, name))) { mkdirSync(base, { recursive: true, mode: 0o700 }); observedCopy(join(options.home, name), join(base, name), budget); }
   for (const key of [options.project, ...options.aliases]) {
     const dir = shardDir(options.home, key), log = join(dir, "work", "log");
     if (!regularDir(log)) continue;
     copyTree(log, join(base, "projects", dir.split("/").pop()!, "work", "log"), budget);
-    if (regularFile(join(dir, "project.json"))) copyFileSync(join(dir, "project.json"), join(base, "projects", dir.split("/").pop()!, "project.json"));
+    if (regularFile(join(dir, "project.json"))) observedCopy(join(dir, "project.json"), join(base, "projects", dir.split("/").pop()!, "project.json"), budget);
     any = true;
   }
   return any;
 }
 
+/** Reuse doctor's bounded private inputs for an on-demand brief, never a live store or reader lease. */
+export async function withBriefSnapshot<T>(home: string, project: string, read: (inputs: NonNullable<BriefOptions["measureOnly"]>) => Promise<T>): Promise<T> {
+  const aliases = aliasedKeys(home, project), selection = readSelector(home).revision, layout = layoutOf(home), guard = guardScratch();
+  let scratch: string | undefined, curated: MemoryStore | undefined;
+  const budget: CopyBudget = { bytes: 0, verify: [] };
+  const inputDirectories = [join(home, "projects"), ...(layout === "split" ? [join(home, "user")] : [join(home, "log"), join(home, "local")]),
+    ...(layout === "generation" ? [join(home, "generations")] : []),
+    ...[project, ...aliases].flatMap(key => { const dir = shardDir(home, key); return [dir, join(dir, "work"), join(dir, "work", "log")]; })];
+  const checkDirectories = () => {
+    for (const dir of inputDirectories) { const stat = lstatSync(dir, { throwIfNoEntry: false }); if (stat && !stat.isDirectory()) throw Error("recap input is not a plain directory"); }
+  };
+  const check = () => {
+    checkDirectories();
+    if (readSelector(home).revision !== selection || layoutOf(home) !== layout || JSON.stringify(aliasedKeys(home, project)) !== JSON.stringify(aliases)) throw Error("recap binding changed");
+    for (const verify of budget.verify!) verify();
+  };
+  try {
+    checkDirectories();
+    scratch = mkdtempSync(join(tmpdir(), `amem-doctor-${process.pid}-`)); chmodSync(scratch, 0o700); guard.adopt(scratch);
+    const options = { home, project, aliases }, workBase = join(scratch, "work-base"); mkdirSync(workBase, { mode: 0o700 });
+    copyWork(options, workBase, budget);
+    if (curatedPresent(home, project, layout)) {
+      const copy = join(scratch, "home"); mkdirSync(copy, { mode: 0o700 }); copyCurated(options, layout, copy, budget);
+      curated = openCuratedForRead(copy, project);
+      if (!curated) throw Error("recap curated snapshot unavailable");
+    }
+    check();
+    const result = await read({ ...(curated ? { curated } : {}), workBase });
+    check(); return result;
+  } catch (error) {
+    if (error instanceof TooBig) throw Error("recap snapshot exceeds the 64 MiB copy limit");
+    throw error;
+  } finally {
+    try { curated?.close(); } finally { try { if (scratch) rmSync(scratch, { recursive: true, force: true }); } finally { guard.release(); } }
+  }
+}
+
 /** A snapshot of the live shared-v1 index (a read-only connection, so no checkpoint, no lease), or false when there is none. */
 function snapshotIndex(live: string, to: string): boolean {
   const file = join(live, "index.db");