@staix/agent-mem 0.19.0 → 0.20.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.19.0",
+  "version": "0.20.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.19.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.20.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 
@@ -292,7 +292,7 @@ amem capacity apply --split [--confirm]   # each shard's share of the global cap
 - `capacity` also prints a per-shard split of the global disk-share budget. Each shard's weight halves every 14 days since its last capture, so recently used projects keep more capture and cold ones shrink first; the split never exceeds the budget, gives every shard at least 1 MB, keeps every shard at what it holds whenever the total fits, never proposes a retention shorter than a shard's idle time plus 30 days, and says when the budget forces a shard below what it holds. When the budget holds fewer whole MB than there are shards, no split is proposed and `capacity` says why (`splitRefused`). It proposes capture bounds only, and never evicts curated notes, goals or work lists. `capacity apply --split` previews, then `--confirm` writes exactly the previewed values to each shard's `config.json`, and only if the preview is under an hour old and the set of shards and every shard's config are unchanged since then (a `--disk-share` given only to `--confirm` changes nothing that is written).
 - amem lists vault candidates and never writes the vault.
 
-Resource budgets are acceptance criteria, measured by `bun scripts/measure-budget.ts` in CI on Ubuntu and macOS: a hook-like append (including the spool-and-exit path under contention) must stay under 150 ms p95 wall time and 100 MB peak RSS (R2), the search path under 100 MB idle and 200 MB peak RSS (R3), and no amem process may remain after exit (R1). The script prints a machine-readable verdict per budget and its CI log is also the FTS5 availability evidence for Linux (R5). The AC4 retrieval re-check of the frozen P0 query set is in [docs/p1-ac4-recheck.md](https://github.com/STAIxBWLB/agent-mem/blob/main/docs/p1-ac4-recheck.md).
+Resource budgets are acceptance criteria, measured by `bun scripts/measure-budget.ts` in CI on Ubuntu and macOS: a hook-like append (including the spool-and-exit path under contention) must stay under 150 ms p95 wall time and 100 MB RSS (R2), the search path under 100 MB idle and 200 MB peak RSS (R3), and no amem process may remain after exit (R1). For the actual-hook scripts (`measure-hooks-budget.ts`, `measure-transcript-budget.ts`, `measure-full-spool-budget.ts`) R2 is three gates: a 150 MB ceiling on every invocation, a regression gate of +10% over a committed per-runner p95 baseline (`docs/bench/r2-baseline.json`), and a 300 ms per-invocation maximum on the handler's own wall, with the outer CLI wall reported only (the transcript harness reports it until #226); see [docs/contracts.md](https://github.com/STAIxBWLB/agent-mem/blob/main/docs/contracts.md) (#228). The script prints a machine-readable verdict per budget and its CI log is also the FTS5 availability evidence for Linux (R5). The AC4 retrieval re-check of the frozen P0 query set is in [docs/p1-ac4-recheck.md](https://github.com/STAIxBWLB/agent-mem/blob/main/docs/p1-ac4-recheck.md).
 
 ## Claude Code hooks and SessionStart context
 
@@ -314,13 +314,13 @@ Before optional work starts, the parent screens the complete hook input and boun
 
 Pending capture has an ordinary soft tier of 256 files/2 MiB and a separate private reserve of 32 files/256 KiB, admitted before optional recovery. Replay is globally oldest-first across both tiers, at most 32 files/256 KiB per drain. A record replays only when its original non-null scope positively matches. Null scope is never adopted later, even with a physical cwd receipt: protecting project privacy takes priority over recovering an unattested event. Alias/profile/shard changes invalidate the derived identity cache and reader binding without changing pending scope. Positive fresh native project identity may still supply known-work context when pending scope is unknown; it does not authorize replay of those records.
 
-A valid pending body is eligible for retirement only after at least seven days and current evidence that its scope is unknown/mismatched or its original cwd is positively absent. A transiently removed or unmounted cwd younger than seven days keeps its data. A positively drainable foreign-project record is retained even when older than seven days; another project's admission does not make it undrainable. Retirement removes the body only after persisting a reason/count metric (`captureDrops` and `captureDropReason`, with `cwd_removed`, `undrainable_expired` or `scope_unknown`); failed counter persistence leaves the body pending. No retired body becomes a replay/context source. Malformed publications can be removed through bounded owned-file checks. Explicit current-policy rejection also retains only a numeric private receipt. This bounded loss policy prevents permanently undrainable records from disabling capture, while never rebinding them to a new project.
+Known-format pending records whose cwd is positively absent can retire after one hour (capture and file modification time must both exceed the grace). Other undrainable records keep the seven-day rule; a changed device/root/scope alone never proves cwd removal. Fair-share pressure can retire known-format records with a counted `scope_capacity` loss, while unknown/newer schemas retain seven-day protection. Each retirement persists numeric reason/count metrics before removing the body; a failed receipt leaves it pending. Retired bodies never become replay or context sources, and records are never rebound to the admitting project. Malformed publications still use bounded owned-file cleanup. See [the spool admission contract](docs/contracts.md#pending-spool-identity-and-admission-217) for identity, N-1 and retention details.
 
 If both replayable tiers fill, or SessionStart's reserve alone fills, the current event can be dropped. The library receipt reports `dropped: true`, `dropReason: "spool_full"`, `dropCount: 1`, and the metric reports `captureDrops: 1` with `captureDropReason: "spool_full"`. Non-SessionStart native stdout remains empty. Native SessionStart emits only `hookSpecificOutput`, placing a bounded notice with reason counts from the last 200 metric samples after its initial untrusted-data header inside `additionalContext`, not in new top-level fields. These are rolling-window counts, not all-time totals. The header stays first even when the brief is otherwise unavailable, and the combined context stays within its byte bound. Finite-capacity and retirement losses are observable rather than reported as captured. Exact-once replay applies to positively bound retained records that can progress; unlimited lossless intake is not promised. Soft-cap overshoot, unpublished `.writing/` leftovers and power-loss durability retain the [contracts ceiling](docs/contracts.md#p3-hook-and-native-intake-boundaries-13).
 
 SessionStart prioritizes known open work and defers unsafe curated refresh with a fixed coverage reason. Native capture reads the newest 128 rows through an existing read-only time index and marks excluded older history partial, instead of rejecting a larger store. It never creates schema/FTS or repairs indexes. Missing/locked/incompatible sources are explicitly unavailable. The standalone `sessionStartBrief()` retains all its original sources. Recovery failure cannot discard a computed brief. Work, reader-lease and capture host ports use zero busy-wait and cooperative deadline checks; ordinary library callers retain their original defaults, including 3,000 ms waits. No watcher, resident worker, model/network call, embedding job or vault access is added. Host policy callbacks remain unsupported by `runHook`, while the standalone brief composes them normally.
 
-SessionStart admits directly to the reserve with at most 32 metadata entries and performs no active-tier scan, retirement or replay. Non-SessionStart hooks maintain and drain both tiers. This is bounded reserve admission, not O(1) accounting; an atomic slot-reservation protocol is the upgrade. Parent brief storage still contains synchronous filesystem/SQLite work between cooperative deadline checks; asynchronous/deadline-aware storage remains the upgrade, not a larger handler limit. The R2 limits remain 150 ms p95 and 100 MB summed main/helper peak RSS, with a 140 ms handler budget. Functional tests construct a programmatic host-only deadline; the actual executable exposes no environment or CLI deadline extension. Its exec-only boot-clock handoff can only shorten the deadline and is cleared before hook import. Dedicated budget scripts retain the actual CLI, original sample counts, cold attempt 0 and timeout/reaper assertions. The [P3 receipt](docs/p3-hook-budget-2026-10-23.md) identifies prior-head evidence separately from current acceptance; the current rework has no newly claimed both-OS green CI result.
+SessionStart admits directly to the reserve with at most 32 metadata entries and performs no active-tier scan or replay. Both tiers use per-cwd fair shares (64 active records, 8 reserve records), grouping together all HOME/scope variants of a cwd. Admission can retire native records from an overrepresented cwd, counting each loss as `scope_capacity` before removal. Accepted summaries survive same-cwd pressure; new summaries backpressure without advancing their transcript cursor. A fully verified foreign all-summary inventory can use counted `summary_capacity` eviction; otherwise it stays pending for replay. All admission maintenance shares a 32-file/256 KiB body-read bound; unknown/newer schemas retain their seven-day protection. Non-SessionStart hooks maintain and drain both tiers. This is bounded reserve admission, not O(1) accounting; an atomic slot-reservation protocol is the upgrade. Parent brief storage still contains synchronous filesystem/SQLite work between cooperative deadline checks; asynchronous/deadline-aware storage remains the upgrade, not a larger handler limit. The R2 limits remain 150 ms p95 and 100 MB summed main/helper peak RSS, with a 140 ms handler budget. Functional tests construct a programmatic host-only deadline; the actual executable exposes no environment or CLI deadline extension. Its exec-only boot-clock handoff can only shorten the deadline and is cleared before hook import. Dedicated budget scripts retain the actual CLI, original sample counts, cold attempt 0 and timeout/reaper assertions. The [P3 receipt](docs/p3-hook-budget-2026-10-23.md) identifies prior-head evidence separately from current acceptance; the current rework has no newly claimed both-OS green CI result.
 
 A private admission cursor rotates bounded inspection across pending records (at most 32 files/256 KiB per pass), so a healthy first slice cannot indefinitely hide later removed/unknown entries from retirement checks. Git include/conditional identity dependencies are traversed within depth four and 16 files. Pending scope hashes relevant semantic project-identity values rather than unrelated full-config or HEAD churn; derived cache validity may additionally hash raw configuration/HEAD bytes. Unconditional and `gitdir` includes bind semantic identity values. Dynamic `onbranch`/`hasconfig` or unknown conditional trees without identity keys bind nothing; if they contain origin/rewrite/worktree identity keys, scope stays unknown. Native read-only identity may still supply known work, but it never adopts that pending capture; counted `scope_unknown` retirement needs seven days. This conservative ceiling is upgraded by evaluating `onbranch` against HEAD at drain time, not by adding a condition interpreter in this PR.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -17,7 +17,7 @@ import { vaultCandidates, vaultCandidatesText, vaultCandidatesAllText } from "./
 import type { IngestKind, IngestReceipt } from "./ingest.ts";
 import { importClaudeMemCapture, importClaudeMemWorkState } from "./memory/import.ts";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { MemoryStore, looksSecret, machineId, openShardStore, type StoreOptions } from "./memory/store.ts";
 import { rawMemoryCommand, rawGoalCommand, claudeMemImportText } from "./memory/commands.ts";
 import { memoryProjectKey } from "./memory/project.ts";
@@ -136,6 +136,39 @@ export function agentMarked(env: Readonly<Record<string, string | undefined>>):
   return ["AGENTHUB_PEER_ID", "CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"].some(key => env[key] !== undefined);
 }
 
+/** #217 PR2: pure checks only (no home, source or store access), so a bad invocation is refused before anything is read. */
+function assertSpoolReplayArguments(path: readonly string[], options: Record<string, unknown>): void {
+  if (path[1] !== "replay") throw new AgentUsageError("usage: amem spool replay [--json] [--source <absolute dir>] | amem spool replay --apply --plan <file>");
+  const apply = options["--apply"] === true, planFile = options["--plan"], source = options["--source"];
+  if (apply && typeof planFile !== "string") throw new AgentUsageError("spool replay --apply needs --plan <saved preview>; run `amem spool replay --json > plan.json` first");
+  if (!apply && planFile !== undefined) throw new AgentUsageError("--plan is only used with --apply; drop it to preview, or add --apply to apply it");
+  if (apply && source !== undefined) throw new AgentUsageError("--source is fixed by the saved plan; drop --source when applying");
+  if (options["--confirm-unverifiable"] === true && !apply) throw new AgentUsageError("--confirm-unverifiable only applies with --apply --plan; preview first, review the mappings, then apply");
+  if (typeof planFile === "string" && (!planFile || planFile.includes("\0"))) throw new AgentUsageError("--plan is empty or contains a NUL byte; pass the saved preview's path");
+  if (source !== undefined) {
+    if (typeof source !== "string" || !source || source.includes("\0")) throw new AgentUsageError("--source is empty or contains a NUL byte; pass an absolute path to a private directory");
+    if (!isAbsolute(source)) throw new AgentUsageError("--source is a relative path; pass the absolute path of the parked directory");
+  }
+}
+/** Body-free preview text: counts by class, then each record's cwd, current project and class for explicit confirmation. */
+function replayPreviewText(plan: { records: { name: string; cwd: string; project: string | null; class: string; event: string | null }[]; counts: Record<string, number>; digest: string; needsConfirmation: { cwd: string; project: string; count: number }[] }): string {
+  const lines = [`spool replay preview (no record bodies shown; plan ${plan.digest.slice(0, 12)})`,
+    ...Object.entries(plan.counts).filter(([, n]) => n > 0).map(([cls, n]) => `  ${cls}: ${n}`)];
+  const byCwd = new Map<string, { project: string | null; classes: Map<string, number> }>();
+  for (const record of plan.records) {
+    const row = byCwd.get(record.cwd) ?? { project: record.project, classes: new Map() };
+    row.classes.set(record.class, (row.classes.get(record.class) ?? 0) + 1); byCwd.set(record.cwd, row);
+  }
+  for (const [cwd, row] of byCwd) lines.push(`  ${cwd || "(unreadable record)"} -> ${row.project ?? "(project unresolved)"}: ${[...row.classes].map(([c, n]) => `${c} ${n}`).join(", ")}`);
+  if (plan.needsConfirmation.length) {
+    lines.push("Needs confirmation (decision A: this boot cannot prove the original identity; each maps by its own cwd):");
+    for (const group of plan.needsConfirmation) lines.push(`  ${group.cwd} -> ${group.project}: ${group.count}`);
+    lines.push("To apply these mappings too, after checking each one: amem spool replay --json > plan.json && amem spool replay --apply --plan plan.json --confirm-unverifiable");
+  }
+  lines.push("Without --confirm-unverifiable only replayable records are applied: amem spool replay --json > plan.json && amem spool replay --apply --plan plan.json");
+  return lines.join("\n");
+}
+
 /** Administrative metadata is checked as a complete value, never by stripping individual fields. */
 function assertAgentAdministrative(value: unknown, policy: ReturnType<typeof configuredPolicy>): void {
   if (cliAttribution()?.actor !== "agent") return;
@@ -340,7 +373,9 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
       } catch { return false; } finally { try { candidates?.close(); } catch { /* optional telemetry cannot fail emitted output */ } }
     } });
   };
-  if (["migrate", "prune", "capacity", "gc", "project", "alias", "machine", "sync", "import", "dedupe", "consolidate"].includes(sub)) administrative({ command: parsed.path, arguments: args });
+  // #217 PR2: pure argument refusals for spool replay run first, before the administrative policy read touches the home.
+  if (sub === "spool") assertSpoolReplayArguments(parsed.path, options);
+  if (["migrate", "prune", "capacity", "gc", "project", "alias", "machine", "sync", "import", "dedupe", "consolidate", "spool"].includes(sub)) administrative({ command: parsed.path, arguments: args });
   if (sub === "consolidate") {
     const requested = typeof options["--project"] === "string" ? options["--project"] as string : boundProject();
     if (!requested.trim() || requested.length > 400 || requested.includes("\0")) throw Error("invalid consolidation project");
@@ -669,6 +704,24 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
     }
     return options["--json"] ? JSON.stringify(report, null, 2) : evalText(report, builtin ? `built-in fixture ${file}` : file ?? "built-in fixture");
   }
+  if (sub === "spool") {
+    // #217 PR2. Every argument refusal runs before any home, source or store access; both actors take this guarded
+    // preview/apply path (no marker-only ban, no generic TTY gate). The replay module is loaded only here.
+    // Argument refusals already ran in assertSpoolReplayArguments, before any home access.
+    const apply = options["--apply"] === true, planFile = options["--plan"], source = options["--source"];
+    const replay = await import("./hook-spool-replay.ts");
+    if (!apply) {
+      const plan = administrative(await replay.planHookSpoolReplay({ base: memoryHome(), ...(typeof source === "string" ? { source } : {}) }));
+      return options["--json"] === true ? JSON.stringify(plan, null, 2) : replayPreviewText(plan);
+    }
+    let saved: unknown;
+    try { saved = JSON.parse(readFileSync(planFile as string, "utf8")); }
+    catch { throw new Error(`cannot read the replay plan ${planFile as string}; run \`amem spool replay --json > plan.json\` and pass that file`); }
+    const plan = administrative(replay.parseReplayPlan(saved));
+    const receipt = administrative(await replay.applyHookSpoolReplay({ base: memoryHome(), plan, confirmUnverifiable: options["--confirm-unverifiable"] === true }));
+    return options["--json"] === true ? JSON.stringify(receipt, null, 2)
+      : `replayed ${receipt.applied} (${receipt.spooled} via the capture spool), retired ${receipt.retired}, retained ${receipt.retained}, ${receipt.absent} absent (completed by an earlier run of this plan, or removed or drained by someone else; nothing was appended for it); ${receipt.outcomes.filter(o => o.outcome === "skipped").length} skipped by the plan`;
+  }
   if (sub === "capacity") {
     const share = options["--disk-share"];
     if (share !== undefined && (!Number.isFinite(Number(share)) || Number(share) <= 0 || Number(share) > 1)) throw new Error("--disk-share must be a number in (0, 1]");

package/src/commands-table.ts

@@ -43,6 +43,11 @@ export const COMMANDS: Record<string, CommandDefinition> = {
   usage: { description: "Totals and the largest project shards", options: { ...json, "--limit": text("Largest shards to list (1..100)"), "--all": flag("Include forgotten projects") } },
   eval: { description: "Replay a local question set against ranked store.search and report recall@k and MRR (no model, no network; the built-in synthetic set without --set, `--set ko` for the built-in Korean one)", options: { ...json,
     "--set": { description: "`ko` (the built-in Korean set) or a question set file (amem.eval/v1); with entries it is self-contained, without them its ids name entries of this project", value: "path" }, "--k": text("Cutoffs, comma separated (default 1,5,10; each 1..100)") } },
+  spool: { description: "Off-hook hook-spool maintenance (#217)", options: json, commands: {
+    replay: { description: "Preview (read-only, no record bodies) or apply a replay of orphaned or parked hook records; --apply takes the saved preview", mutates: "apply", options: { ...json,
+      "--source": { description: "Absolute path of a private parked directory to read instead of this home's hook spool", value: "path" },
+      "--apply": flag("Apply the saved preview given with --plan"), "--confirm-unverifiable": flag("With --apply: also replay the saved plan's 'needs confirmation' cwd -> project mappings (records this boot cannot prove)"), "--plan": { description: "Saved preview from `amem spool replay --json`", value: "path" } } },
+  } },
   gc: { description: "Apply each shard's retention and cap across shards in bounded batches (preview without --confirm)", mutates: "confirm", options: {
     ...json, "--confirm": flag("Evict now; without it, preview only"), "--batches": text("evict() windows per shard in this run (1..1000, default 1)") } },
   project: { description: "Per-project lifecycle and portable import/export (#15 D3, F17): one project only", options: json, commands: {

package/src/hook-contract.ts

@@ -1,12 +1,15 @@
 export const HOOK_EVENTS = ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "Stop", "SessionEnd"] as const;
 export type HookEvent = typeof HOOK_EVENTS[number];
 export const HOOK_INPUT_BYTES = 64 * 1024, HOOK_CONTEXT_BYTES = 1200, HOOK_OUTPUT_BYTES = 8192;
-export interface HookTranscriptProgress { offset?: number; stopReason?: "cap" | "deadline" | "spool_full" }
+/** `unavailable` (#221): the scan threw, so no progress is known; unlike the others it is a fault, never accepted progress. */
+export type HookTranscriptStopReason = "cap" | "deadline" | "spool_full" | "unavailable";
+export const HOOK_TRANSCRIPT_STOP_REASONS: readonly HookTranscriptStopReason[] = ["cap", "deadline", "spool_full", "unavailable"];
+export interface HookTranscriptProgress { offset?: number; stopReason?: HookTranscriptStopReason }
 export function isHookTranscriptProgress(value: unknown): value is HookTranscriptProgress {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const row = value as Record<string, unknown>;
   return Object.keys(row).every(key => key === "offset" || key === "stopReason")
     && (row.offset !== undefined || row.stopReason !== undefined)
     && (row.offset === undefined || Number.isSafeInteger(row.offset) && (row.offset as number) >= 0)
-    && (row.stopReason === undefined || ["cap", "deadline", "spool_full"].includes(row.stopReason as string));
+    && (row.stopReason === undefined || (HOOK_TRANSCRIPT_STOP_REASONS as readonly string[]).includes(row.stopReason as string));
 }

package/src/hook-rss-wire.ts

@@ -47,6 +47,8 @@ export class HookWorkerRss {
     }
     this.invalid = true;
   }
+  /** #226 Q2: a killed child that is not reaped is accounted from its last live sample only when one exists (Linux /proc). */
+  hasLiveSample(): boolean { return !!(this.image.hwmKB || this.image.virtualKB); }
   captureLive(read: typeof processImageMemory = processImageMemory): void {
     const retain = (before: Image | undefined, after: Image): Image => ({
       hwmKB: Math.max(before?.hwmKB ?? 0, after.hwmKB ?? 0) || undefined,

package/src/hook-spool-replay.ts

@@ -0,0 +1,332 @@
+/**
+ * #217 PR2: off-hook replay of orphaned or parked hook-spool records. CLI-only and lazily loaded: no hook imports it, it
+ * starts no resident process and makes no network or model call.
+ *
+ * Preview (`planHookSpoolReplay`) is read-only and body-free: it creates no directory, cache, database or index and changes
+ * no mode. It binds everything the apply step depends on. Apply (`applyHookSpoolReplay`) takes that saved plan, revalidates
+ * the whole binding before any effect, and replays only records the plan classified `replayable`.
+ *
+ * Decision A (owner, 2026-11-02): an opaque legacy root carries no writer or algorithm tag, so an unknown historical device
+ * hash does not prove a replacement. Such a record is `physical_identity_unverifiable` (plus `attribution_unproven`); the
+ * preview shows its recorded cwd, current project and count, and it is never guessed, rebound or retired automatically.
+ * Decision B: the saved plan is the resume token. The claim suffix is hash(plan digest, publication), so the same plan
+ * recognizes and resumes its own claims; any other claim (another plan's, or a live hook drainer's random one) is reported
+ * `claimed_elsewhere` and left alone. No
+ * durable mapping store exists.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync, type Stats } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { hookCaptureScope, hookLegacyCaptureScope, hookSpoolReplayInternals as spool, type HookSpoolOwnedFile } from "./hook-spool.ts";
+import { aliasedKeys, resolveAlias } from "./memory/aliases.ts";
+import { CaptureStore, type CaptureInput } from "./memory/capture.ts";
+import { configuredPolicyOptions } from "./memory/config.ts";
+import { projectState } from "./memory/lifecycle.ts";
+import { canonicalPath, realPath } from "./memory/platform.ts";
+import { createStandalonePolicy } from "./memory/policy.ts";
+import { memoryProjectKey } from "./memory/project.ts";
+
+export const REPLAY_PLAN_SCHEMA = "agent-mem.hook-spool-replay-plan/v1";
+const hash = (value: string | Uint8Array) => createHash("sha256").update(value).digest("hex");
+
+export type ReplayClass =
+  | "replayable"                       // decoded, scope verified on this boot, project resolved and active, policy-screened
+  | "physical_identity_unverifiable"   // decision A: scope mismatch only; applied solely with --confirm-unverifiable
+  | "attribution_unproven"             // project identity could not be resolved strictly from the record's own cwd
+  | "cwd_missing"                      // the recorded cwd no longer exists; never rebound
+  | "project_inactive"                 // the resolved project is archived or forgotten
+  | "policy_refused"                   // the record or its capture input fails the configured policy
+  | "unknown_schema"                   // #199: a newer or unknown schema stays pending, untouched
+  | "undecodable"                      // malformed or oversized: left for the hook path's own retirement rules
+  | "claimed_elsewhere";               // decision B: another plan's or a live drainer's claim, left alone
+
+export interface ReplayPlanRecord {
+  /** Publication canonical name (without any `.draining-` suffix) and where it was observed. */
+  name: string; tier: "active" | "capacity" | "source";
+  /** File identity and raw-byte digest bound at preview. */
+  dev: number; ino: number; size: number; mtimeMs: number; digest: string;
+  class: ReplayClass; reasons: ReplayClass[];
+  /** Shown for confirmation, never a body: the recorded cwd, the current project for it, and the scope the hook path would compute now. */
+  cwd: string; project: string | null; scope: string | null; event: string | null;
+  /** Present when this plan already holds the claim (a resumed plan). */
+  claimedBy?: "this_plan";
+  /** Decision A: an unverifiable record whose cwd exists, whose strict project resolves and is active, and that passed the
+   * full policy screen. Applied only with explicit confirmation of this plan's cwd -> project mapping. */
+  confirmable?: true;
+}
+export interface HookSpoolReplayPlan {
+  schema: typeof REPLAY_PLAN_SCHEMA;
+  /** Destination home, snapshotted once and used for replay, policy, attribution and receipts alike. */
+  home: string;
+  source: { kind: "home" | "explicit"; dir: string; dev: number; ino: number }[];
+  /** Policy-input revisions (home config, each repository config) and alias/lifecycle revisions bound at preview. */
+  revisions: { aliases: string; lifecycle: string; policy: Record<string, string> };
+  records: ReplayPlanRecord[];
+  counts: Record<ReplayClass, number>;
+  /** Decision A: the cwd -> project mappings (with counts) an explicit --confirm-unverifiable would apply, bound in the digest. */
+  needsConfirmation: { cwd: string; project: string; count: number }[];
+  /** Digest over everything above; the resume token and the claim-suffix seed. */
+  digest: string;
+}
+export interface HookSpoolReplayReceipt {
+  plan: string;
+  applied: number; spooled: number; retired: number; retained: number;
+  /** Planned publications no longer present (a resumed plan's completed records, or ones a drainer took): no effect. */
+  absent: number;
+  /** Per publication outcome; `applied_cleanup_failed` is still applied, never reported as not applied. */
+  outcomes: { name: string; outcome: "applied" | "spooled" | "applied_cleanup_failed" | "retained" | "skipped" | "absent"; reason?: string }[];
+}
+
+/** Every error says what failed and what to do next (REVIEW.md). */
+export class ReplayError extends Error {
+  constructor(readonly code: string, cause: string, next: string) { super(`${cause}; ${next}`); this.name = "ReplayError"; }
+}
+
+const zeroCounts = (): Record<ReplayClass, number> => ({ replayable: 0, physical_identity_unverifiable: 0, attribution_unproven: 0, cwd_missing: 0,
+  project_inactive: 0, policy_refused: 0, unknown_schema: 0, undecodable: 0, claimed_elsewhere: 0 });
+
+/** Pure argument and source checks, run before any home, source or store access. */
+export function assertReplaySource(source: string): void {
+  if (typeof source !== "string" || !source || source.includes("\0")) throw new ReplayError("replay_source_invalid", "the replay source is empty or contains a NUL byte", "pass an absolute path to a private directory");
+  if (!isAbsolute(source)) throw new ReplayError("replay_source_relative", "the replay source is a relative path", "pass the absolute path, for example ~/.agenthub/hook-spool-orphans-20261102 expanded");
+}
+
+function directoryIdentity(dir: string, kind: "home" | "explicit"): { kind: "home" | "explicit"; dir: string; dev: number; ino: number } | undefined {
+  const stat = lstatSync(dir, { throwIfNoEntry: false });
+  if (!stat) return undefined;
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new ReplayError("replay_source_not_directory", `${dir} is not a real directory`, "pass a directory, not a file or a symbolic link");
+  if (stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0) throw new ReplayError("replay_source_not_private", `${dir} is not a private directory owned by you`, "use the directory as amem created it (mode 0700); do not loosen its permissions");
+  return { kind, dir: realPath(dir), dev: stat.dev, ino: stat.ino };
+}
+
+/** Bounded directory listing of publication names (and `.draining-` claims), without reading bodies. */
+function listPublications(dir: string): { entry: string; stat: Stats }[] {
+  const rows: { entry: string; stat: Stats }[] = [], reader = opendirSync(dir);
+  try {
+    for (let scanned = 0; scanned < spool.MAX_FILES * 4; scanned++) {
+      const item = reader.readSync(); if (!item) break;
+      if (!spool.namePattern.test(item.name)) continue;
+      const stat = lstatSync(join(dir, item.name), { throwIfNoEntry: false });
+      if (stat && stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 1) rows.push({ entry: item.name, stat });
+    }
+  } finally { reader.closeSync(); }
+  return rows.sort((a, b) => a.stat.mtimeMs - b.stat.mtimeMs || a.entry.localeCompare(b.entry));
+}
+
+/** Small, bounded read of a control file's bytes for a revision hash; absent means empty. */
+function fileRevision(file: string): string {
+  try {
+    const stat = lstatSync(file, { throwIfNoEntry: false });
+    if (!stat) return hash("absent");
+    if (!stat.isFile() || stat.size > 1024 * 1024) return hash("unusable");
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try { const bytes = Buffer.alloc(fstatSync(fd).size); readSync(fd, bytes, 0, bytes.length, 0); return hash(bytes); } finally { closeSync(fd); }
+  } catch { return hash("unreadable"); }
+}
+
+/** Strict, read-only project identity for the record's own cwd. It never touches the hook identity cache. */
+function strictProject(cwd: string): string | undefined {
+  try { return memoryProjectKey(cwd, { repositoryIsolation: true, strictGitErrors: true }); }
+  catch (error) { if (exhausted(error)) throw resourceFailure(error)!; return undefined; }
+}
+
+/** One inspected publication. No descriptor outlives its inspection (I3): apply re-opens each record when it reaches it. */
+interface Inspected { record: ReplayPlanRecord; path?: string }
+/** Descriptor or process-table exhaustion (or any other non-race open failure) must fail the run loudly, never look like a vanished file. */
+const RACE_CODES = new Set(["ENOENT", "ELOOP", "ENOTDIR"]);
+const exhausted = (error: unknown) => ["EMFILE", "ENFILE"].includes(String((error as { code?: unknown } | null)?.code));
+function resourceFailure(error: unknown): ReplayError | undefined {
+  const code = (error as { code?: unknown } | null)?.code;
+  if (typeof code !== "string" || RACE_CODES.has(code)) return undefined;
+  return new ReplayError("replay_resource_exhausted", `reading the spool failed with ${code}${code === "EMFILE" || code === "ENFILE" ? " (too many open files)" : ""}`,
+    "raise the open-file limit (ulimit -n) or move part of the source into another private directory, then preview again");
+}
+async function inspect(home: string, dir: string, tier: ReplayPlanRecord["tier"], entry: string, stat: Stats, planDigest: string | undefined): Promise<Inspected> {
+  const match = spool.namePattern.exec(entry)!, name = match[1]!;
+  const claimSuffix = /\.draining-([a-f0-9]{24})$/.exec(entry)?.[1];
+  const base: Omit<ReplayPlanRecord, "class" | "reasons" | "digest"> = { name, tier, dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs,
+    cwd: "", project: null, scope: null, event: null };
+  const path = join(dir, entry);
+  const finish = (cls: ReplayClass, reasons: ReplayClass[], digest: string, extra: Partial<ReplayPlanRecord> = {}, readable = true): Inspected =>
+    ({ record: { ...base, ...extra, class: cls, reasons, digest }, ...(readable ? { path } : {}) });
+  if (claimSuffix !== undefined && (planDigest === undefined || claimSuffix !== claimFor(planDigest, name))) return finish("claimed_elsewhere", ["claimed_elsewhere"], "", {}, false);
+  const owned = spool.openOwned(path);
+  let decoded: ReturnType<typeof spool.decoded>, bytes: Buffer;
+  try {
+    decoded = spool.decoded(owned);
+    bytes = Buffer.alloc(Math.min(owned.initial.size, spool.RECORD_BYTES));
+    readSync(owned.fd, bytes, 0, bytes.length, 0);
+  } finally { closeSync(owned.fd); }
+  const digest = hash(bytes), claimed = claimSuffix !== undefined ? { claimedBy: "this_plan" as const } : {};
+  if (!decoded) return finish("undecodable", ["undecodable"], digest, claimed);
+  const value = decoded.value, cwd = typeof value.cwd === "string" ? value.cwd : "";
+  const event = typeof (value.capture as { event?: unknown } | undefined)?.event === "string" ? (value.capture as { event: string }).event : null;
+  if (decoded.unknown) return finish("unknown_schema", ["unknown_schema"], digest, { ...claimed, cwd, event });
+  if (value.nonce !== match[4] || value.cwd !== cwd || hash(cwd) !== match[2]) return finish("undecodable", ["undecodable"], digest, { ...claimed, cwd, event });
+  if (!lstatSync(cwd, { throwIfNoEntry: false })?.isDirectory()) return finish("cwd_missing", ["cwd_missing"], digest, { ...claimed, cwd, event });
+  const physical = realPath(cwd);
+  const scope = hookCaptureScope(physical, home) ?? null;
+  const project = strictProject(physical);
+  const canonical = project === undefined ? null : resolveAlias(home, project);
+  const reasons: ReplayClass[] = [];
+  // Decision A: the hook path's current scope, or the current-boot legacy device scope it also drains, proves the identity.
+  // Any other scope (a previous boot's device, a changed HOME) is a scope mismatch: physical_identity_unverifiable alone.
+  const legacy = hookLegacyCaptureScope(physical, home) ?? null;
+  const unverifiable = scope === null || value.scope !== scope && value.scope !== legacy;
+  // attribution_unproven only when no strict project resolves for the record's own cwd.
+  if (canonical === null) reasons.push("attribution_unproven");
+  else if (projectState(home, canonical) !== "active") reasons.push("project_inactive");
+  if (!reasons.length) {
+    const policy = createStandalonePolicy(configuredPolicyOptions(home, physical));
+    if (!await policy.screen(value) || !await policy.screen(captureInput(value.capture as never, canonical!))) reasons.push("policy_refused");
+  }
+  if (unverifiable) reasons.unshift("physical_identity_unverifiable");
+  const cls = reasons[0] ?? "replayable";
+  const confirmable = unverifiable && reasons.length === 1 ? { confirmable: true as const } : {};
+  return finish(cls, reasons.length ? reasons : ["replayable"], digest, { ...claimed, ...confirmable, cwd, event, scope, project: canonical });
+}
+
+function captureInput(c: { agent: string; event: string; at: string; paths: string[]; tool: string | null; status: string | null; excerpt: string; session?: string; subagent?: boolean }, project: string): CaptureInput {
+  return { project, agent: c.agent, event: c.event, at: c.at, paths: c.paths, ...(c.tool === null ? {} : { tool: c.tool }), ...(c.status === null ? {} : { status: c.status }),
+    excerpt: c.excerpt, ...(c.session === undefined ? {} : { session: c.session }), ...(c.subagent === undefined ? {} : { subagent: c.subagent }) };
+}
+
+/** Decision B: deterministic per plan and publication, so the same plan finds its own claims after a crash. */
+export const claimFor = (planDigest: string, name: string) => hash(`${planDigest}\0${name}`).slice(0, 24);
+
+function sources(home: string, source: string | undefined): { kind: "home" | "explicit"; dir: string; dev: number; ino: number }[] {
+  if (source !== undefined) {
+    const dir = directoryIdentity(source, "explicit");
+    if (!dir) throw new ReplayError("replay_source_missing", `${source} does not exist`, "check the path of the parked directory");
+    return [dir];
+  }
+  return [directoryIdentity(join(home, "hook-spool"), "home"), directoryIdentity(join(home, "hook-spool", ".capacity"), "home")]
+    .filter((dir): dir is NonNullable<typeof dir> => dir !== undefined);
+}
+
+function bindings(home: string, records: ReplayPlanRecord[]): HookSpoolReplayPlan["revisions"] {
+  const policy: Record<string, string> = { home: fileRevision(join(home, "amem.config.json")) };
+  for (const cwd of [...new Set(records.map(record => record.cwd).filter(Boolean))].sort()) {
+    try { policy[cwd] = hash(JSON.stringify(configuredPolicyOptions(home, realPath(cwd)))); } catch { policy[cwd] = hash("unavailable"); }
+  }
+  return { aliases: fileRevision(join(home, "aliases.jsonl")), lifecycle: hash(JSON.stringify([...new Set(records.map(r => r.project).filter(Boolean))].sort().map(p => [p, projectState(home, p!), aliasedKeys(home, p!)]))), policy };
+}
+const planDigest = (plan: Omit<HookSpoolReplayPlan, "digest">) => hash(JSON.stringify(plan));
+function confirmationGroups(records: ReplayPlanRecord[]): HookSpoolReplayPlan["needsConfirmation"] {
+  const groups = new Map<string, { cwd: string; project: string; count: number }>();
+  for (const record of records) if (record.confirmable) {
+    const key = JSON.stringify([record.cwd, record.project]), row = groups.get(key) ?? { cwd: record.cwd, project: record.project!, count: 0 };
+    row.count++; groups.set(key, row);
+  }
+  return [...groups.values()].sort((a, b) => a.cwd.localeCompare(b.cwd) || a.project.localeCompare(b.project));
+}
+/** A record this apply may replay: always a replayable one; a confirmable unverifiable one only with explicit confirmation. */
+const applicable = (record: ReplayPlanRecord, confirmUnverifiable: boolean) => record.class === "replayable" || confirmUnverifiable && record.confirmable === true
+  && record.class === "physical_identity_unverifiable" && record.reasons.length === 1 && record.project !== null;
+
+async function survey(home: string, dirs: HookSpoolReplayPlan["source"], digest: string | undefined): Promise<Inspected[]> {
+  const out: Inspected[] = [];
+  for (const dir of dirs) {
+    const tier = dir.kind === "explicit" ? "source" : dir.dir.endsWith("/.capacity") ? "capacity" : "active";
+    for (const { entry, stat } of listPublications(dir.dir)) {
+      try { out.push(await inspect(home, dir.dir, tier, entry, stat, digest)); }
+      catch (error) {
+        const failure = resourceFailure(error);
+        if (failure) throw failure;
+        /* vanished or replaced between list and open: it is simply not in this plan */
+      }
+    }
+  }
+  return out;
+}
+
+/** Read-only, body-free preview. Creates nothing and changes no mode. */
+export async function planHookSpoolReplay(options: { base: string; source?: string }): Promise<HookSpoolReplayPlan> {
+  if (options.source !== undefined) assertReplaySource(options.source);
+  const home = canonicalPath(options.base);
+  if (spool.belowFloor(home)) throw new ReplayError("replay_format_floor", "this home records a hook-spool format floor above this amem", "upgrade amem to the floor's version, then preview again");
+  const dirs = sources(home, options.source);
+  const inspected = await survey(home, dirs, undefined);
+  const records = inspected.map(item => item.record), counts = zeroCounts();
+  for (const record of records) counts[record.class]++;
+  const body: Omit<HookSpoolReplayPlan, "digest"> = { schema: REPLAY_PLAN_SCHEMA, home, source: dirs, revisions: bindings(home, records), records, counts, needsConfirmation: confirmationGroups(records) };
+  return { ...body, digest: planDigest(body) };
+}
+
+/** Validate the saved plan's own shape and digest before using any of it. */
+export function parseReplayPlan(value: unknown): HookSpoolReplayPlan {
+  const plan = value as HookSpoolReplayPlan;
+  if (!plan || typeof plan !== "object" || plan.schema !== REPLAY_PLAN_SCHEMA || !Array.isArray(plan.records) || !Array.isArray(plan.needsConfirmation) || typeof plan.digest !== "string")
+    throw new ReplayError("replay_plan_invalid", "the file is not an amem spool replay plan", "run `amem spool replay --json > plan.json` and pass that file");
+  const { digest, ...body } = plan;
+  if (planDigest(body) !== digest) throw new ReplayError("replay_plan_altered", "the plan file was edited after the preview", "preview again and apply the new, unedited plan");
+  return plan;
+}
+
+/**
+ * Apply a saved plan. The whole binding (home, source directories, revisions, and every record's identity, digest and class)
+ * is revalidated first; any change refuses with no effect. Records are replayed oldest first through one CaptureStore at a
+ * time; the durable append (or the capture spool's acknowledgement) completes before the exact owned claim retires.
+ */
+export async function applyHookSpoolReplay(options: { base: string; plan: HookSpoolReplayPlan; confirmUnverifiable?: boolean }): Promise<HookSpoolReplayReceipt> {
+  const plan = parseReplayPlan(options.plan), home = canonicalPath(options.base), confirm = options.confirmUnverifiable === true;
+  if (plan.home !== home) throw new ReplayError("replay_home_changed", "the plan was made for another memory home", "run the preview again from this home");
+  if (spool.belowFloor(home)) throw new ReplayError("replay_format_floor", "this home records a hook-spool format floor above this amem", "upgrade amem to the floor's version, then preview again");
+  const dirs = plan.source.map(dir => directoryIdentity(dir.dir, dir.kind));
+  if (dirs.some((dir, index) => !dir || dir.dev !== plan.source[index]!.dev || dir.ino !== plan.source[index]!.ino))
+    throw new ReplayError("replay_source_changed", "a source directory was replaced since the preview", "preview again and apply the new plan");
+  const current = await survey(home, plan.source, plan.digest);
+  {
+    const byName = new Map(current.map(item => [item.record.name, item]));
+    for (const planned of plan.records) {
+      if (!applicable(planned, confirm)) continue;
+      const now = byName.get(planned.name)?.record;
+      // I2: a planned publication that is gone (no source name and no claim under this plan's suffix) has no effect here.
+      // It was retired by an earlier run of this plan or taken by a live drainer that captured it; nothing is appended for it.
+      if (!now) continue;
+      if (now.dev !== planned.dev || now.ino !== planned.ino || now.size !== planned.size || now.digest !== planned.digest
+        || now.class !== planned.class || JSON.stringify(now.reasons) !== JSON.stringify(planned.reasons) || now.confirmable !== planned.confirmable
+        || now.project !== planned.project || now.scope !== planned.scope || now.cwd !== planned.cwd)
+        throw new ReplayError("replay_plan_stale", `${planned.name} changed since the preview (identity, bytes, scope, project or policy)`, "preview again and apply the new plan");
+    }
+    // Recompute the same bindings over the plan's own cwds and projects: any policy, alias or lifecycle change refuses.
+    if (JSON.stringify(bindings(home, plan.records)) !== JSON.stringify(plan.revisions))
+      throw new ReplayError("replay_plan_stale", "a policy, alias or lifecycle input changed since the preview", "preview again and apply the new plan");
+
+    const receipt: HookSpoolReplayReceipt = { plan: plan.digest, applied: 0, spooled: 0, retired: 0, retained: 0, absent: 0, outcomes: [] };
+    const planned = plan.records.filter(record => applicable(record, confirm)).sort((a, b) => a.mtimeMs - b.mtimeMs || a.name.localeCompare(b.name));
+    let store: CaptureStore | undefined, storeProject: string | undefined, held: HookSpoolOwnedFile | undefined;
+    try {
+      for (const record of planned) {
+        const item = byName.get(record.name);
+        if (!item) { receipt.absent++; receipt.outcomes.push({ name: record.name, outcome: "absent", reason: "completed by an earlier run of this plan, or removed or drained by someone else; nothing was appended for it" }); continue; }
+        const retain = (reason: string) => { receipt.retained++; receipt.outcomes.push({ name: record.name, outcome: "retained", reason }); };
+        if (!item.path) { retain("unavailable"); continue; }
+        // I3: one descriptor at a time. Re-open here and require the same inode, size, mtime and bytes the plan bound.
+        let owned: HookSpoolOwnedFile;
+        try { owned = spool.openOwned(item.path); }
+        catch (error) { const failure = resourceFailure(error); if (failure) throw failure; retain("unavailable"); continue; }
+        held = owned;
+        if (owned.initial.dev !== record.dev || owned.initial.ino !== record.ino || owned.initial.size !== record.size || owned.initial.mtimeMs !== record.mtimeMs) { retain("identity_changed"); closeSync(owned.fd); held = undefined; continue; }
+        // Decision B: claim under the plan's own deterministic suffix (an existing own claim is already that name).
+        const claim = item.record.claimedBy === "this_plan" ? owned : spool.claimAs(owned, `${record.name}`, claimFor(plan.digest, record.name));
+        if (!claim) { retain("claim_lost"); closeSync(owned.fd); held = undefined; continue; }
+        held = claim;
+        const decoded = spool.decoded(claim);
+        if (!decoded || decoded.unknown || hash(decoded.bytes) !== record.digest) { retain("decode_changed"); closeSync(claim.fd); held = undefined; continue; }
+        // One CaptureStore at a time: close the previous project's store before opening the next one.
+        if (storeProject !== record.project) { store?.close(); store = new CaptureStore({ memoryDir: home, project: record.project!, cwd: realPath(record.cwd) }); storeProject = record.project!; }
+        const result = store!.append(captureInput(decoded.value.capture as never, record.project!), { receipt: hash(decoded.bytes) });
+        const spooled = "spooled" in result;
+        if (spooled) receipt.spooled++; else receipt.applied++;
+        const retired = spool.retireOwned(claim);
+        closeSync(claim.fd); held = undefined;
+        if (retired) { receipt.retired++; receipt.outcomes.push({ name: record.name, outcome: spooled ? "spooled" : "applied" }); }
+        else receipt.outcomes.push({ name: record.name, outcome: "applied_cleanup_failed", reason: "the claim changed after the append; the row is recorded and the claim is kept" });
+      }
+    } finally { store?.close(); if (held) try { closeSync(held.fd); } catch { /* already closed */ } }
+    for (const record of plan.records) if (!applicable(record, confirm)) receipt.outcomes.push({ name: record.name, outcome: "skipped",
+      reason: record.confirmable ? "physical_identity_unverifiable: needs --confirm-unverifiable" : record.class });
+    return receipt;
+  }
+}