@staix/agent-mem 0.20.2 → 0.21.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.20.2",
+  "version": "0.21.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.20.2. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.21.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 
@@ -32,7 +32,7 @@ From a checkout, install development dependencies with `bun install` and run `bu
 
 ## Setup / plugin
 
-For Orca-managed Claude and Codex homes, setup writes the personal source that Orca copies into new sessions. Claude hooks go to `$HOME/.claude/settings.json`, while its MCP entry stays in the profile's `.claude.json`. Codex MCP and hooks go to `$HOME/.codex/config.toml` and `hooks.json`. Detection requires an exact managed-home shape under `ORCA_USER_DATA_PATH` (default `~/Library/Application Support/orca`); a similar directory elsewhere is unchanged. Preview lists each redirect and its reason. Start a new Orca session after applying. Existing matching managed-copy receipts migrate on apply; undo restores the files and bytes recorded for that installation. Codex hooks still require the person's native `/hooks` review; setup never grants trust or writes `trusted_hash`.
+For Orca-managed Claude and Codex homes, setup writes the personal source that Orca copies into new sessions. Claude hooks go to `$HOME/.claude/settings.json` and its MCP entry to `$HOME/.claude.json`, because Orca syncs the personal `mcpServers` over each profile's copy (#243); the profile copies stay untouched. Codex MCP and hooks go to `$HOME/.codex/config.toml` and `hooks.json`. Detection requires an exact managed-home shape under `ORCA_USER_DATA_PATH` (default `~/Library/Application Support/orca`); a similar directory elsewhere is unchanged. Preview lists each redirect and its reason. Start a new Orca session after applying. Existing matching managed-copy receipts migrate on apply; undo restores the files and bytes recorded for that installation. Codex hooks still require the person's native `/hooks` review; setup never grants trust or writes `trusted_hash`.
 
 `amem setup agy` registers MCP only in the current git repository's `.agents/mcp_config.json`, with an explicit absolute repository cwd and a private receipt per repository. `setup all` excludes agy; run it separately in each repository. Setup refuses tracked config files and JSONC, and warns when the file is not ignored. Restart Antigravity after applying, use one workspace per session, and ensure no global, plugin or running server is also named `amem`. No global configuration, ingest command or hook is installed. Undo removes `.agents` only when setup created it and it is still empty; pre-existing or nonempty directories remain. Older receipts still restore their configuration without directory cleanup. See the [Antigravity contract and capture limitation](docs/antigravity.md).
 
@@ -157,7 +157,7 @@ Acceptance normalizes its note once, including timestamp, content ID and short-t
 
 ## 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.
+`@staix/agent-mem/ui-plugin` is a plugin for the local agent console `acon` (`@staix/agent-console` 0.1.0, 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
@@ -169,6 +169,7 @@ The manifest holds the absolute path and sha256 of `src/ui/plugin.ts` (of the `-
 
 - 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 shows the candidate kind, proposal, correction diff, stored evidence references, target-note quotes with dates and similar memories. Source sessions, proposing agents and times seen are not recorded by the candidate schema; the panel labels them unavailable rather than inferring them from capture data. An explicitly unavailable project is refused instead of falling back to another project.
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,7 @@
     "bun": ">=1.4.2"
   },
   "devDependencies": {
-    "@staix/agent-console": "github:STAIxBWLB/agent-console#952e962",
+    "@staix/agent-console": "0.1.3",
     "@types/bun": "^1.3.0",
     "typescript": "^5.8.0",
     "@staix/agent-mem-v1": "npm:@staix/agent-mem@0.1.1",

package/src/cli.ts

@@ -1,3 +1,5 @@
+import { assertFormatFloor } from "./memory/formats.ts";
+import { placementRuntimeRefusal } from "./memory/sync-placement-guard.ts";
 import { activatePublicPruneView } from "./memory/public-prune-activation.ts";
 import { AgentUsageError, agentCliRead } from "./cli-agent-reads.ts";
 import { cliAttribution, withCliAttribution } from "./memory/cli-attribution.ts";
@@ -250,6 +252,8 @@ function markedSetupApplyError(parsed: ReturnType<typeof parseCommand>, error: u
     cause = "setup_receipt_version_unsupported"; next = "Run setup or undo with the amem release that wrote the receipt."; partial = false;
   } else if (text === "setup receipt was written from an Orca Claude profile; rerun setup from that Orca profile") {
     cause = "setup_receipt_orca_profile"; next = "The receipt was written from an Orca Claude profile; rerun setup from that Orca profile."; partial = false;
+  } else if (text === "setup receipt is stale: its managed entries were replaced at another amem install root; rerun with --adopt-current to adopt the current wiring") {
+    cause = "setup_receipt_stale"; next = "The receipt's managed entries were replaced at another amem install root outside setup; rerun with --apply --adopt-current to keep the receipt aside and adopt the current wiring, which --undo then restores."; partial = false;
   } else if (/^setup-owned .+ changed; refusing to overwrite it$/.test(text) || text === "Pi amem-session extension already exists and is not this setup's file"
     || text === "previous-runtime hook settings are customized; review hook configuration before retrying setup"
     || /^setup receipt (?:does not match this installation|target mismatch|invalid|directory ownership invalid)$/.test(text)) {
@@ -375,7 +379,8 @@ 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|console [--root <abs path>] [--apply|--undo]");
+    if (parsed.positionals.length !== 1 || options["--apply"] === true && options["--undo"] === true
+      || options["--adopt-current"] === true && (options["--apply"] !== true || parsed.positionals[0] === "console")) throw new Error("usage: amem setup claude|codex|kimi|pi|qwen|jcode|opencode|gemini|agy|all|console [--root <abs path>] [--apply [--adopt-current]|--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";
@@ -387,6 +392,7 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
     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(),
       ...(typeof options["--root"] === "string" ? { root: options["--root"] } : {}),
+      ...(options["--adopt-current"] === true ? { adoptCurrent: true } : {}),
       ...(context.setupConfirm ? { confirm: context.setupConfirm } : {}), json: options["--json"] === true, style: outputStyle(context),
     });
   }
@@ -1031,6 +1037,7 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   // configured remote, nothing when the schedule or the failure backoff says it is not due (`--force` skips that), and it stops a running git step after 30 seconds.
   const ifDue = sub === "sync" && options["--if-due"] === true, syncHome = memoryHome();
   if (options["--force"] === true && !ifDue) throw new Error("--force only applies with sync --if-due");
+  if (sub === "sync") { assertFormatFloor(syncHome, "sync"); const refusal = placementRuntimeRefusal(syncHome); if (refusal) throw new Error("amem sync: " + refusal); }
   if (ifDue) {
     if (options["--remote"] === undefined && !remoteConfigured(syncHome)) return options["--json"] ? JSON.stringify({ ok: true, skipped: "no sync remote configured" }) : "no sync remote configured: nothing to do";
     const state = usableState(readSyncState(syncHome), Date.now());

package/src/commands-table.ts

@@ -26,7 +26,8 @@ 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, 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"),
-    "--root": { description: "Register this absolute install root (such as <install>/releases/<version>/, resolved to its real path) instead of the running one", value: "path" } }, args: [{ name: "target", values: ["claude", "codex", "kimi", "pi", "qwen", "jcode", "opencode", "gemini", "agy", "all", "console"] }] },
+    "--root": { description: "Register this absolute install root (such as <install>/releases/<version>/, resolved to its real path) instead of the running one", value: "path" },
+    "--adopt-current": flag("With --apply: keep a stale setup receipt aside (its entries were replaced at another install root) and adopt the current wiring, which --undo restores") }, 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" },
   manifest: { description: "Describe this install: package name, version, MCP server and tools (read-only ones marked), commands", options: json },
   hook: { description: "Run a fail-open, context-only Claude Code hook", args: [{ name: "event", values: [...HOOK_EVENTS] }] },

package/src/hook-spool.ts

@@ -450,6 +450,37 @@ function retireClaim(base: string, file: OwnedFile, preserve: boolean, batch?: Q
 const RETIRE_AFTER_MS = 7 * 24 * 3600_000, MISSING_CWD_AFTER_MS = 3600_000;
 interface MaintenanceBudget { files: number; bytes: number }
 const maintenanceBudget = (): MaintenanceBudget => ({ files: DRAIN_FILES, bytes: DRAIN_BYTES });
+/** Unpublished private files are not captures. Inspect at most four entries within this publication's maintenance allowance. */
+function cleanStaleWriting(writing: string, budget: MaintenanceBudget): void {
+  // ponytail: only the first four directory entries are inspected; young or unremovable entries can starve later stale files.
+  // Upgrade: rotate the bounded scan start with an owned maintenance cursor, like retirementCursor.
+  const reader = opendirSync(writing);
+  try {
+    for (let scanned = 0; scanned < 4 && budget.files > 0; scanned++) {
+      const entry = reader.readSync(); if (!entry) break;
+      budget.files--;
+      const canonical = entry.name.replace(/\.writing-[a-f0-9]{24}$/, ""), match = namePattern.exec(canonical);
+      if (!match || match[1] !== canonical) continue;
+      let file: OwnedFile | undefined;
+      try {
+        file = openOwned(join(writing, entry.name));
+        if (typeof process.getuid !== "function" || file.initial.uid !== process.getuid() || file.initial.mode & 0o077
+          || Date.now() - file.initial.mtimeMs < MISSING_CWD_AFTER_MS || file.initial.size > budget.bytes) continue;
+        budget.bytes -= file.initial.size;
+        const current = fstatSync(file.fd);
+        if (current.uid === process.getuid() && !(current.mode & 0o077) && owns(file)) rmSync(file.file);
+      } catch { /* Partial, replaced or unsafe evidence stays private; never acknowledge it as a capture. */ }
+      finally { if (file) closeSync(file.fd); }
+    }
+  } finally { reader.closeSync(); }
+}
+/** A writer can change its own size/mtime before a failed write, but never owns a replacement or a shared inode. */
+function ownsWriting(file: OwnedFile): boolean {
+  const named = lstatSync(file.file, { throwIfNoEntry: false }), current = fstatSync(file.fd), uid = process.getuid?.();
+  return !!named && named.isFile() && !named.isSymbolicLink() && named.nlink === 1 && current.nlink === 1
+    && uid !== undefined && current.uid === uid && !(current.mode & 0o077)
+    && named.dev === file.initial.dev && named.ino === file.initial.ino && current.dev === file.initial.dev && current.ino === file.initial.ino;
+}
 /** Private numeric maintenance cursor: each invocation inspects a different bounded slice. */
 function retirementCursor(base: string, capacity: boolean, length: number, pressure = false): { start: number; save(n: number): void } {
   const dir = join(directory(base), ".maintenance"); privateDirectory(dir);
@@ -680,6 +711,7 @@ function publishCapture(event: string, capture: NormalizedCaptureFields, options
   const dir = directory(base), writing = join(dir, ".writing"); privateDirectory(dir); privateDirectory(writing);
   let destination = dir, deferred = false, backlog = false;
   const budget = maintenanceBudget(), incomingBytes = Buffer.byteLength(bytes), cwdHash = hash(cwd);
+  if (event !== "SessionStart") cleanStaleWriting(writing, budget);
   const withinShare = (rows: ReturnType<typeof entries>, maximum: number) => rows.filter(row => namePattern.exec(row.name)?.[2] === cwdHash).length < maximum / 4;
   const name = `${v3 ? PREFIX_V3 : PREFIX}${cwdHash}-${scope ?? "0".repeat(64)}-${nonce}.json`;
   let activeInventory: ReturnType<typeof entries> | undefined, reserveInventory: ReturnType<typeof entries> | undefined;
@@ -739,9 +771,19 @@ function publishCapture(event: string, capture: NormalizedCaptureFields, options
       deferred = true;
     }
   }
-  const temporary = join(writing, name);
-  try { writeFileSync(temporary, bytes, { mode: 0o600, flag: "wx" }); renameSync(temporary, join(destination, name)); }
-  finally { rmSync(temporary, { force: true }); }
+  const temporary = join(writing, `${name}.writing-${randomBytes(12).toString("hex")}`);
+  let fd: number | undefined, created: OwnedFile | undefined;
+  try {
+    fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    created = { file: temporary, fd, initial: fstatSync(fd) };
+    if (!ownsWriting(created)) throw new Error("Hook publication refused: private temporary ownership unavailable. Retry the hook; inspect spool permissions and ownership if it repeats.");
+    writeFileSync(fd, bytes);
+    if (!ownsWriting(created) || !owns({ ...created, initial: fstatSync(fd) })) throw new Error("Hook publication refused: private temporary changed before publication. Retry the hook; inspect competing writers if it repeats.");
+    renameSync(temporary, join(destination, name));
+  } finally {
+    try { if (created && ownsWriting(created)) rmSync(temporary); }
+    finally { if (fd !== undefined) closeSync(fd); }
+  }
   return { name, cwd, receipt: hash(bytes), ...(deferred ? { deferred: true as const } : {}), ...(backlog ? { backlog: true as const } : {}) };
 }
 

package/src/index.ts

@@ -17,9 +17,21 @@ export * from "./memory/sync.ts";
 export * from "./memory/import.ts";
 export * from "./memory/project.ts";
 export * from "./memory/home.ts";
-export * from "./memory/platform.ts";
+export {
+  canonicalPath, realPath, DENY_SEGMENTS, DENY_NAMES, isDenied, memoryGitArgv, memoryGitEnv, memoryGitSync,
+  withGitTimeout, processSignature, processLiveness,
+} from "./memory/platform.ts";
+export type { Liveness } from "./memory/platform.ts";
 export * from "./memory/commands.ts";
-export * from "./memory/candidates.ts";
+export {
+  CANDIDATE_DB_BUSY_TIMEOUT_MS, ACCEPTED_CONSOLIDATION_PREFIX, CANDIDATE_RETENTION, CONSOLIDATION_REVIEW_LIMIT,
+  ConsolidationReviewLimit, COUNTER_RETENTION, candidateInputId, acceptedCorrectionText, goalPromotionLinked,
+  candidateTargetRevision, CandidateQueueFull, CandidateStore,
+} from "./memory/candidates.ts";
+export type {
+  CandidateVerdict, CandidateTarget, CandidateInput, CandidateStatus, Candidate, ConsolidationReview, CandidateFilter,
+  CounterKey, CounterValues, Counter, CandidateAcceptance, CandidateAcceptanceResult,
+} from "./memory/candidates.ts";
 export * from "./memory/ops-contract.ts";
 export * from "./memory/generation.ts";
 export * from "./memory/migrate.ts";
@@ -49,3 +61,14 @@ export * from "./memory/consolidate.ts";
 export * from "./memory/consolidation-clusters.ts";
 export * from "./memory/consolidation-model.ts";
 export * from "./memory/evidence.ts";
+
+export * from "./memory/sync-policy-inspection.ts";
+export * from "./memory/sync-placement-inspection.ts";
+export { syncOutboundContent } from "./memory/sync-screen.ts";
+
+export * from "./memory/sync-placement-format.ts";
+export * from "./memory/sync-placement-plan.ts";
+export * from "./memory/sync-placement-journal-format.ts";
+export * from "./memory/sync-placement-projection.ts";
+export * from "./memory/sync-placement-journal.ts";
+export type { PlacementCapturePort } from "./memory/sync-placement-capture.ts";

package/src/memory/bridge.ts

@@ -1,6 +1,6 @@
 import { createHash, randomBytes, type Hash } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, unlinkSync, writeSync } from "node:fs";
+import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, opendirSync, unlinkSync, writeSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { memoryGitArgv, memoryGitEnv, realPath } from "./platform.ts";
@@ -51,7 +51,39 @@ const statStamp = (stat: { dev: bigint | number; ino: bigint | number; size: big
 export class SegmentReader {
   private readonly prefixes = new Map<string, PrefixState>();
   private measured: SegmentReadMetrics = { bytesRead: 0, bytesHashed: 0, coldChanged: 0 };
-  constructor(private remainingBytes = Infinity) { if (remainingBytes !== Infinity && (!Number.isSafeInteger(remainingBytes) || remainingBytes < 0)) failure(); }
+  private remainingSourceBytes: number;
+  private remainingRows: number;
+  private remainingFiles: number;
+  private sourceBytes = 0;
+  private sourceRows = 0;
+  /** Optional inspection limits do not change ordinary incremental-reader semantics. */
+  readonly sourceByteLimit?: number;
+  readonly sourceFileLimit?: number;
+  constructor(private remainingBytes = Infinity, limits: { maxSourceBytes?: number; maxRows?: number } = {}) {
+    for (const value of [remainingBytes, limits.maxSourceBytes ?? Infinity, limits.maxRows ?? Infinity]) if (value !== Infinity && (!Number.isSafeInteger(value) || value < 0)) failure();
+    this.sourceByteLimit = limits.maxSourceBytes;
+    this.remainingSourceBytes = limits.maxSourceBytes ?? Infinity;
+    this.remainingRows = limits.maxRows ?? Infinity;
+    this.sourceFileLimit = limits.maxRows;
+    this.remainingFiles = limits.maxRows ?? Infinity;
+  }
+  inspectionMetrics(): { sourceBytes: number; rows: number } { return { sourceBytes: this.sourceBytes, rows: this.sourceRows }; }
+  /** Inspection counts directory entries and archived segment names before their arrays/maps can grow.
+   * ponytail: metadata entries share maxRows (public inspection: 20000), including empty files.
+   * Upgrade with a separately budgeted catalog proof if valid profiles need a larger metadata frontier.
+   */
+  reserveSourceFiles(count: number): void {
+    if (!Number.isSafeInteger(count) || count < 0 || count > this.remainingFiles) throw new SegmentReadBudgetError();
+    this.remainingFiles -= count;
+  }
+  listFiles(dir: string): string[] {
+    if (this.sourceFileLimit === undefined) return readdirSync(dir).sort();
+    const reader = opendirSync(dir), names: string[] = [];
+    try {
+      for (;;) { const entry = reader.readSync(); if (!entry) break; this.reserveSourceFiles(1); names.push(entry.name); }
+    } finally { reader.closeSync(); }
+    return names.sort();
+  }
   metrics(): SegmentReadMetrics { return { ...this.measured }; }
   resetMetrics(): void { this.measured = { bytesRead: 0, bytesHashed: 0, coldChanged: 0 }; }
   read(path: string, prior?: LegacyCheckpoint, full = false, immutable = false): SegmentBytes {
@@ -60,6 +92,8 @@ export class SegmentReader {
     const stamp = statStamp(before), size = Number(before.size);
     if (prior && size < prior.offset) failure();
     if (!full && prior?.stamp === stamp) return { bytes: Buffer.alloc(0), start: prior.offset, offset: prior.offset, hash: prior.hash, tailBytes: size - prior.offset, stamp };
+    if (size > this.remainingSourceBytes) throw new SegmentReadBudgetError();
+    this.remainingSourceBytes -= size; this.sourceBytes += size;
     const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
       const opened = fstatSync(fd, { bigint: true });
@@ -73,6 +107,11 @@ export class SegmentReader {
       const all = read(size), end = all.lastIndexOf(10) + 1, bytes = all.subarray(0, end);
       if (prior && end < prior.offset) failure();
       if (!read(end).equals(bytes) || fstatSync(fd, { bigint: true }).size < opened.size) failure();
+      // Count physical nonblank source rows before any canonical source map can grow.
+      if (this.remainingRows !== Infinity) for (const line of completeLines(bytes)) if (line.toString("utf8").trim()) {
+        if (this.remainingRows < 1) throw new SegmentReadBudgetError();
+        this.remainingRows--; this.sourceRows++;
+      }
       const after = lstatSync(path, { bigint: true });
       if (after.isSymbolicLink() || after.dev !== opened.dev || after.ino !== opened.ino) failure();
       const cached = immutable ? undefined : this.prefixes.get(path);
@@ -116,7 +155,7 @@ function checkpointMap(rows: readonly LegacyCheckpoint[] = []): Map<string, Lega
   return map;
 }
 
-function checkedEntry(value: unknown): Entry {
+export function checkedEntry(value: unknown): Entry {
   if (!value || typeof value !== "object" || Array.isArray(value)) malformed();
   const row = value as Record<string, unknown>;
   const operation = row.op;
@@ -141,7 +180,7 @@ function checkedEntry(value: unknown): Entry {
   return row as unknown as Entry;
 }
 
-function* completeLines(bytes: Buffer): Generator<Buffer> {
+export function* completeLines(bytes: Buffer): Generator<Buffer> {
   let start = 0;
   while (start < bytes.length) { const end = bytes.indexOf(10, start); if (end < 0) failure(); yield bytes.subarray(start, end); start = end + 1; }
 }
@@ -198,7 +237,7 @@ function snapshot(homeM: string, options: LegacySnapshotOptions): LegacySegment[
   for (const folder of ["log", "local"]) {
     const dir = join(root, folder);
     if (!directory(dir, true)) continue;
-    for (const name of readdirSync(dir).sort()) {
+    for (const name of options.reader ? options.reader.listFiles(dir) : readdirSync(dir).sort()) {
       if (!name.endsWith(".jsonl")) continue;
       const path = `${folder}/${name}`;
       if (!segmentPath(path)) failure();
@@ -212,11 +251,12 @@ function snapshot(homeM: string, options: LegacySnapshotOptions): LegacySegment[
   }
   if ((options.commit || options.previousCommit) && !options.generation || options.previousCommit && !commitId(options.previousCommit)) failure();
   if (options.generation !== undefined) {
-    const commit = options.commit ?? legacyHead(root, options.generation);
+    const commit = options.commit ?? legacyHead(root, options.generation, options.reader?.sourceByteLimit, options.reader?.sourceFileLimit);
     if (commit) {
-      const manifest = archived(root, options.generation, commit);
+      const manifest = archived(root, options.generation, commit, options.reader?.sourceByteLimit, options.reader?.sourceFileLimit);
+      options.reader?.reserveSourceFiles(manifest.segments.length);
       directory(join(archiveDir(root, options.generation, commit), "log"));
-      for (const prior of new Set([...(options.previousCommit ? [options.previousCommit] : []), ...[...checkpoints.values()].filter(row => row.source === remoteSource).map(row => row.commit!)])) if (!archivedAncestor(root, options.generation, prior, commit)) failure();
+      for (const prior of new Set([...(options.previousCommit ? [options.previousCommit] : []), ...[...checkpoints.values()].filter(row => row.source === remoteSource).map(row => row.commit!)])) if (!archivedAncestor(root, options.generation, prior, commit, options.reader?.sourceByteLimit)) failure();
       for (const segment of manifest.segments) {
         const reader = options.reader ?? new SegmentReader(), incremental = options.incremental && !limits;
         const data = reader.read(join(archiveDir(root, options.generation, commit), segment.path), incremental ? checkpoints.get(`${remoteSource}:${segment.path}`) : undefined, !incremental, true);
@@ -239,15 +279,21 @@ function snapshot(homeM: string, options: LegacySnapshotOptions): LegacySegment[
   return result;
 }
 
-function capturedIdentity(path: string): string {
+function capturedIdentity(path: string, maximum?: number): string {
   const before = lstatSync(path);
   if (before.isSymbolicLink() || !before.isFile()) failure();
   const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
   try {
     const stat = fstatSync(fd);
-    if (stat.dev !== before.dev || stat.ino !== before.ino || stat.size > 4096) failure();
+    if (maximum !== undefined && (before.size > maximum || stat.size > maximum)) throw new SegmentReadBudgetError();
+    if (stat.dev !== before.dev || stat.ino !== before.ino || stat.size > (maximum ?? 4096)) failure();
+    if (maximum !== undefined && (stat.size !== before.size || stat.mtimeMs !== before.mtimeMs || stat.ctimeMs !== before.ctimeMs)) failure();
     const bytes = Buffer.alloc(stat.size);
     if (readSync(fd, bytes, 0, bytes.length, 0) !== bytes.length) failure();
+    if (maximum !== undefined) {
+      const after = fstatSync(fd), named = lstatSync(path);
+      if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs || named.isSymbolicLink() || named.dev !== stat.dev || named.ino !== stat.ino) failure();
+    }
     return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
   } finally { closeSync(fd); }
 }
@@ -266,14 +312,14 @@ function cachedGit(cache: string, args: string[], allowMissing = false): Buffer
   return run.stdout;
 }
 /** Last explicitly fetched legacy main, not a claim about the current remote state. Never fetches or writes. */
-function head(homeM: string, generation: string): string | undefined {
+function head(homeM: string, generation: string, maximumArchiveBytes?: number, maximumArchiveSegments?: number): string | undefined {
   const root = realPath(homeM); directory(root);
   const dir = fixedGeneration(root, generation);
   if (!directory(dir, true)) return undefined;
   const active = readProfileJSON(join(dir, "bridge-snapshot.json"), 4096) as { schema?: unknown; generation?: unknown; commit?: unknown } | undefined;
   if (!active) return undefined;
   if (active.schema !== "agent-mem.legacy-head/v1" || active.generation !== generation || typeof active.commit !== "string" || !commitId(active.commit)) failure();
-  archived(root, generation, active.commit);
+  archived(root, generation, active.commit, maximumArchiveBytes, maximumArchiveSegments);
   return active.commit;
 }
 
@@ -281,8 +327,8 @@ function head(homeM: string, generation: string): string | undefined {
 export function readLegacySnapshot(homeM: string, options: LegacySnapshotOptions = {}): LegacySegment[] {
   try { return snapshot(homeM, options); } catch (error) { if (error instanceof SegmentReadBudgetError) throw error; return failure(); }
 }
-export function legacyHead(homeM: string, generation: string): string | undefined {
-  try { return head(homeM, generation); } catch { return failure(); }
+export function legacyHead(homeM: string, generation: string, maximumArchiveBytes?: number, maximumArchiveSegments?: number): string | undefined {
+  try { return head(homeM, generation, maximumArchiveBytes, maximumArchiveSegments); } catch (error) { if (error instanceof SegmentReadBudgetError) throw error; return failure(); }
 }
 
 
@@ -301,9 +347,11 @@ function archiveDir(root: string, generation: string, commit: string): string {
   const dir = join(fixedGeneration(root, generation), "bridge-snapshots");
   directory(dir); const target = join(dir, commit); directory(target); return target;
 }
-function archived(root: string, generation: string, commit: string): LegacyArchive {
-  const value = readProfileJSON(join(archiveDir(root, generation, commit), "snapshot.json"), 32 * 1024 * 1024) as LegacyArchive | undefined;
+function archived(root: string, generation: string, commit: string, maximumBytes?: number, maximumSegments?: number): LegacyArchive {
+  const file = join(archiveDir(root, generation, commit), "snapshot.json");
+  const value = (maximumBytes === undefined ? readProfileJSON(file, 32 * 1024 * 1024) : JSON.parse(capturedIdentity(file, Math.min(maximumBytes, 32 * 1024 * 1024)))) as LegacyArchive | undefined;
   if (!value || value.schema !== "agent-mem.legacy-snapshot/v1" || value.generation !== generation || value.commit !== commit || value.previousCommit !== undefined && !commitId(value.previousCommit) || !Array.isArray(value.segments)) failure();
+  if (maximumSegments !== undefined && value.segments.length > maximumSegments) throw new SegmentReadBudgetError();
   const paths = new Set<string>();
   for (const segment of value.segments) {
     if (!segment || !segmentPath(segment.path) || !segment.path.startsWith("log/") || paths.has(segment.path) || !Number.isSafeInteger(segment.offset) || segment.offset < 0 || !/^[a-f0-9]{64}$/.test(segment.hash) || !Number.isSafeInteger(segment.tailBytes) || segment.tailBytes < 0) failure();
@@ -311,9 +359,9 @@ function archived(root: string, generation: string, commit: string): LegacyArchi
   }
   return value;
 }
-function archivedAncestor(root: string, generation: string, previous: string, commit: string): boolean {
+function archivedAncestor(root: string, generation: string, previous: string, commit: string, maximumBytes?: number): boolean {
   const visited = new Set<string>();
-  for (let cursor: string | undefined = commit; cursor && !visited.has(cursor); cursor = archived(root, generation, cursor).previousCommit) {
+  for (let cursor: string | undefined = commit; cursor && !visited.has(cursor); cursor = archived(root, generation, cursor, maximumBytes).previousCommit) {
     if (cursor === previous) return true;
     visited.add(cursor);
   }

package/src/memory/candidates.ts

@@ -1,7 +1,7 @@
 import { assertFormatFloor } from "./formats.ts";
 import { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
-import { chmodSync, mkdirSync } from "node:fs";
+import { chmodSync, lstatSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { CANDIDATE_SHOWN_GRACE_MS, hasShownColumn } from "./candidate-pending.ts";
 import { oneLine } from "./note-add.ts";
@@ -130,6 +130,72 @@ function retryLocked(work: () => void): void {
   }
 }
 
+type CandidateRow = { id: string; payload: string; at: number; status: CandidateStatus; note_id: string | null };
+/** Canonical persisted decoding shared by the writer and its read-only inbox port. */
+function decodeCandidate(row: CandidateRow, unknownKind: () => void): Candidate | undefined {
+  const input = JSON.parse(row.payload) as CandidateInput;
+  if (input && typeof input === "object" && !KINDS.includes(input.kind)) { unknownKind(); 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 };
+}
+const CANDIDATE_EXPIRED_SQL = "at <= ? AND (status IN ('accepted', 'rejected') OR (shown_at IS NOT NULL AND shown_at <= ?))";
+const CANDIDATE_PRIORITY_SQL = "CASE WHEN status IN ('pending', 'accepting') AND shown_at IS NULL THEN 2 WHEN status IN ('pending', 'accepting') THEN 1 ELSE 0 END DESC, at DESC";
+export interface PendingCandidateReader { projects(): string[]; list(projects: readonly string[]): Candidate[]; nextExpiry(): number | null }
+/** Internal inbox read port. It neither creates/migrates a database nor prunes or stamps any row.
+ * The port is valid only during the synchronous callback. No immutable fallback may hide current WAL frames. */
+export function withPendingCandidates<T>(memoryDir: string, run: (reader: PendingCandidateReader) => T): T {
+  assertFormatFloor(memoryDir, "candidates");
+  const file = join(memoryDir, "candidates.db"), stat = lstatSync(file, { throwIfNoEntry: false });
+  if (!stat) {
+    let closed = false;
+    const assertOpen = () => { if (closed) throw new Error("pending candidate reader is closed"); };
+    try { return run({ projects() { assertOpen(); return []; }, list(projects) {
+      assertOpen(); if (!Array.isArray(projects) || projects.some(project => !text(project, 400))) throw new Error("invalid candidate project scope"); return [];
+    }, nextExpiry() { assertOpen(); return null; } }); } finally { closed = true; }
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("pending candidates unavailable");
+  const db = new Database(file, { readonly: true }); let closed = false;
+  try {
+    const shown = hasShownColumn(db), now = Date.now();
+    const live = (scope: boolean) => `WITH raw AS (SELECT rowid AS candidate_rowid, id, project, kind, payload, at, status, note_id, ${shown ? "shown_at" : "NULL AS shown_at"} FROM candidates${scope ? " WHERE project IN (SELECT value FROM json_each(?))" : ""}),
+      live AS (SELECT * FROM raw WHERE NOT (${CANDIDATE_EXPIRED_SQL})),
+      retained AS (SELECT *, row_number() OVER (PARTITION BY project ORDER BY ${CANDIDATE_PRIORITY_SQL}, candidate_rowid DESC) AS retention_rank FROM live)`;
+    const assertOpen = () => { if (closed) throw new Error("pending candidate reader is closed"); };
+    return run({
+      nextExpiry() {
+        assertOpen(); if (!shown) return null;
+        const row = db.query(`${live(false)} SELECT min(expiry) AS expiry FROM (
+          SELECT max(at + ?, shown_at + ?) AS expiry FROM retained WHERE retention_rank <= ? AND status = 'pending'
+            AND shown_at IS NOT NULL AND kind IN (SELECT value FROM json_each(?))) WHERE expiry > ?`)
+          .get(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS, CANDIDATE_RETENTION.ageMs,
+            CANDIDATE_SHOWN_GRACE_MS, CANDIDATE_RETENTION.count, JSON.stringify(KINDS), now) as { expiry: number | null };
+        if (row.expiry !== null && (!Number.isFinite(row.expiry) || row.expiry <= now)) throw new Error("pending candidate expiry unavailable");
+        return row.expiry;
+      },
+      projects() {
+        assertOpen();
+        const rows = db.query(`${live(false)} SELECT DISTINCT project FROM retained WHERE retention_rank <= ? AND status = 'pending' AND kind IN (SELECT value FROM json_each(?)) ORDER BY project`)
+          .all(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS, CANDIDATE_RETENTION.count, JSON.stringify(KINDS)) as { project: string }[];
+        if (rows.some(row => !text(row.project, 400))) throw new Error("pending candidate project unavailable");
+        return rows.map(row => row.project);
+      },
+      list(projects) {
+        assertOpen();
+        if (!Array.isArray(projects) || projects.some(project => !text(project, 400))) throw new Error("invalid candidate project scope");
+        if (!projects.length) return [];
+        const rows = db.query(`${live(true)} SELECT * FROM retained WHERE retention_rank <= ? AND status = 'pending' AND kind IN (SELECT value FROM json_each(?)) ORDER BY at DESC, candidate_rowid DESC LIMIT ?`)
+          .all(JSON.stringify([...new Set(projects)]), now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS, CANDIDATE_RETENTION.count, JSON.stringify(KINDS), CANDIDATE_RETENTION.count) as (CandidateRow & { project: string })[];
+        return rows.flatMap(row => {
+          const candidate = decodeCandidate(row, () => {});
+          if (candidate && candidate.input.project !== row.project) throw new Error("candidate project binding mismatch");
+          return candidate ? [candidate] : [];
+        });
+      },
+    });
+  } finally { closed = true; db.close(); }
+}
+
 /** The queue holds the cap's worth of candidates nobody has seen. Named so a caller (the MCP tool) can map it. */
 export class CandidateQueueFull extends Error {
   readonly code = "candidate_queue_full";
@@ -184,20 +250,16 @@ export class CandidateStore {
       this.retainConsolidationReviews();
       // Candidates (AC4, no candidate expires unshown): by age only a decided one, or a pending one that was shown and has had its grace period, goes. By count three tiers decide who is
       // kept: unshown pending first, then shown pending, then decided, so a cap eviction takes decided rows before a shown one (which is owed its grace) and shown ones before an unseen one.
-      this.db.query("DELETE FROM candidates WHERE at <= ? AND (status IN ('accepted', 'rejected') OR (shown_at IS NOT NULL AND shown_at <= ?))").run(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS);
-      this.db.query(`DELETE FROM candidates WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY CASE WHEN status IN ('pending', 'accepting') AND shown_at IS NULL THEN 2 WHEN status IN ('pending', 'accepting') THEN 1 ELSE 0 END DESC, at DESC, rowid DESC) AS rank FROM candidates) WHERE rank > ?)`).run(CANDIDATE_RETENTION.count);
+      this.db.query(`DELETE FROM candidates WHERE ${CANDIDATE_EXPIRED_SQL}`).run(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS);
+      this.db.query(`DELETE FROM candidates WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY ${CANDIDATE_PRIORITY_SQL}, rowid DESC) AS rank FROM candidates) WHERE rank > ?)`).run(CANDIDATE_RETENTION.count);
       this.db.query("DELETE FROM counters WHERE at <= ?").run(now - COUNTER_RETENTION.ageMs);
       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();
   }
   /** #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 };
+  private decode(row: CandidateRow): Candidate | undefined {
+    return decodeCandidate(row, () => { this.skippedUnknownKinds++; });
   }
   put(rawInput: CandidateInput, verdict: CandidateVerdict): string {
     // `<private>` spans are never stored: dropped before the input is validated, hashed (so the id) or written.