@staix/agent-mem 0.20.3 → 0.22.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.20.3",
+  "version": "0.22.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.3. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.22.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.
@@ -554,3 +555,29 @@ Private cursors under `hook-transcripts/` store only a session hash, file identi
 The follow-up bound is a benchmark parameter, not a production retry loop. Backlogs advance on later Stop/SessionEnd calls of the same session. Anything unread after its last hook remains uncaptured, so a cold install on a long session keeps only what its remaining hooks can scan; committed rows are not lost.
 
 Search gives these events the existing 1.25 conversation weight and session grouping. The brief selects up to two newest screened main-session Recap/Compact rows first, then fills from the existing chronological rows, under the same record, byte and token caps. With no summaries the output is unchanged. See [verification evidence](docs/bench/transcript-summaries-201.md).
+
+
+## Initial sync placement activation
+
+Available from 0.22.0. 0.21.0 contains the placement protocol but not this command.
+
+A person can activate per-row outbound placement on one whole memory home. It is forward-only, and never runs migrations, changes privacy policy or raises a reader floor automatically. Real-home activation still needs the person's separate authorization.
+
+1. Preview and complete the existing shard and public-prune migrations with `amem migrate --shards --dry-run` and `amem migrate --public-prune-view --dry-run` (then their separately reviewed `--apply` steps).
+2. On a 0.22 installation, have the person append the existing `home` floor at 0.22.0 in `formats.json`, preserving prior records, and close cooperating memory reader handles. This is recommended at activation and required before the first writer renewal, so old 0.21 readers refuse before opening a renewable home.
+3. Declare every local amem installation that writes this home, including an agent-hub library installation even if setup has no receipt for it. The CLI and current setup-receipt roots are mandatory members.
+
+```sh
+amem migrate --sync-placement --dry-run --writer-root '<cli-install-root>' --writer-root '<host-amem-install-root>' --json
+amem migrate --sync-placement --apply --writer-root '<cli-install-root>' --writer-root '<host-amem-install-root>' --json
+# Only for an interrupted initial activation, using its retained frozen inputs:
+amem migrate --sync-placement --resume --json
+# If inputs changed and BOTH marker files still have their original v2 bytes:
+amem migrate --sync-placement --abandon --json
+```
+
+Dry-run shows root versions/pins and safe policy counts, never row text or patterns, and writes nothing. Initial writer errors name the root category and cause, with upgrade/setup instructions. If a pre-marker interruption retained an intent and its inputs changed, person `--abandon` removes only its owned initial metadata so a fresh preview/apply can follow. It cannot remove a v3 marker, active fence or journal history. After apply, choose the private remote on the first v3 sync (`amem sync --remote <private-git-url>`); ordinary and cadence sync then read the immutable root locator and measure the installs afresh. Allowed originals can publish while declined originals remain in the local append-only history, with counts in the sync receipt. No writer roots need to be repeated on sync.
+
+On an active home, the same dry-run/apply commands explicitly renew the writer inventory on its existing epoch (#282). Declare the complete new 0.22.0-or-later roots after updating host pins and managed setup receipts. Ordinary and cadence sync then locate the new inventory and measure it afresh; original activation data, holds and prior receipts are unchanged. Pending publication or source-recovery work must first be finished with the inventoried install, for example after `dot ai rollback amem` or restoring the host's previous pin.
+
+An interrupted renewal resumes only its exact intent. Before commit append starts, person `--abandon` can discard its unpublished metadata; after the first commit-log byte, only forward resume is supported. Unpublished intent staging requires explicit `--abandon`, then a fresh dry-run; it is never cleaned automatically. Compatible ordinary reads remain available while only renewal metadata is pending. After a crash, a retained `profile.lock` still blocks new reader admission until person `--resume` or, before commit append, `--abandon`. Never edit activation files, downgrade markers or start another epoch to discard a hold. See the [renewal contract](docs/contracts.md#same-epoch-writer-inventory-renewal-282). Real-home renewal and release remain separately authorized person operations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.20.3",
+  "version": "0.22.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, readPlacementRuntimeMarkers } 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";
@@ -18,6 +20,7 @@ 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 { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
 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";
@@ -376,6 +379,14 @@ 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] === "migrate" && options["--sync-placement"] === true) {
+    const modes = ["--dry-run","--apply","--resume","--abandon","--deactivate"].filter(key=>options[key]===true);
+    if (modes.length>1 || parsed.positionals.length || ["--shards","--public-prune-view","--generation","--deactivate"].some(key=>options[key]!==undefined))
+      throw new AgentUsageError("Sync placement is a home-wide forward-only migration; use only --sync-placement with --dry-run, --apply, --resume or pre-marker --abandon and the writer roots, never combine migration families or deactivate.");
+    if (actor === "agent") throw new AgentUsageError("Sync placement activation requires a person; ask the person to run amem migrate --sync-placement --dry-run and review the home-wide forward-only transition.");
+  } else if (parsed.path[0] === "migrate" && (options["--writer-root"] !== undefined||options["--abandon"]!==undefined)) {
+    throw new AgentUsageError("--writer-root and --abandon apply only to --sync-placement; run amem migrate --sync-placement --dry-run to review the inventory.");
+  }
   if (parsed.path[0] === "setup") {
     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]");
@@ -470,9 +481,18 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   }
   if ((options["--history"] === true || options["--as-of"] !== undefined) && (options["--all-projects"] === true || options["--tier"] === "repo")) throw Error("historical recall selects this active project's curated store; cross-project/repo history is unavailable");
   if (sub === "migrate") {
-    const modes = ["--apply", "--dry-run", "--resume", "--deactivate"].filter(key => options[key] === true);
+    const modes = ["--apply", "--dry-run", "--resume", "--abandon", "--deactivate"].filter(key => options[key] === true);
     if (modes.length > 1) throw new Error("migration modes are mutually exclusive");
     const mode = options["--apply"] ? "apply" : options["--resume"] ? "resume" : options["--deactivate"] ? "deactivate" : "dry-run";
+    if (options["--sync-placement"] === true) {
+      const { activateSyncPlacement } = await import("./memory/sync-placement-activation.ts");
+      const result = await activateSyncPlacement({ memoryDir:memoryHome(),mode:options["--abandon"]?"abandon":mode as "dry-run"|"apply"|"resume",
+        writerRoots:repeated(argv,"--writer-root"),ownRoot:fileURLToPath(new URL("..",import.meta.url)),
+        authorize:()=>cliAttribution()?.actor==="person" });
+      if (options["--json"] === true) return JSON.stringify(result,null,2);
+      // Metadata only: the source reader and locator are never serialized into this receipt.
+      return `sync placement: ${result.mode}; ${result.active?"active":"inactive"}; home-wide, forward-only (no deactivate)\n${JSON.stringify(result,null,2)}`;
+    }
     const common = { memoryDir: memoryHome(), ...(options["--generation"] ? { generation: String(options["--generation"]) } : {}), authorizedPerson: true, tty: true };
     if (options["--public-prune-view"] === true) {
       if (options["--deactivate"] || options["--generation"] || options["--shards"]) throw new Error("public prune view is forward-only on an active split; no deactivate, generation replacement or new split");
@@ -1035,6 +1055,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());
@@ -1059,15 +1080,21 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   const syncArgs = args.filter((arg, index) => arg !== "--if-due" && arg !== "--force" && !captureArgs.has(index) && (!legacySearch || arg !== "--filter") && (!explainSearch || arg !== "--explain"));
   const memoryArgs = captureImport && !options["--json"] ? [...syncArgs, "--json"] : syncArgs;
   let output: string;
+  let placementWriters: import("./sync-placement-writer-context.ts").PlacementWriterContext | undefined;
   const stop = ifDue ? stopSignal(context.syncDeadlineMs ?? SYNC_IF_DUE_DEADLINE_MS, process) : undefined;
   try {
+    if (sub === "sync" && (readPlacementRuntimeMarkers(syncHome).profile as { publicationFormat?:string } | undefined)?.publicationFormat === "agent-mem.sync-placement/v1") {
+      const { activePlacementWriterContext } = await import("./sync-placement-writer-context.ts");
+      placementWriters = activePlacementWriterContext(syncHome,fileURLToPath(new URL("..",import.meta.url)));
+    }
     output = await withRepoRows(await rawMemoryCommand(memoryArgs, cwd, { person: identity.actor === "person", rankedSearch: identity.actor === "person" && !legacySearch, ...(explainSearch ? { explainSearch: true } : {}), project: boundProject(), open, readable: notes => identity.actor === "person" ? notes : notes.filter(view => view.project === boundProject() && policyOf().screenStandalone(view)), stale: createRecallStalenessProbe({ cwd: recallRoot ?? cwd, rootConfirmed, policy: () => configured }), outputReady: notes => outputReady(notes.map(view => view.id)), importPolicy: () => text => configured.declinesPersonal(text),
-      sync: { screen: row => configured.screenStandalone(row), policyVersion: () => JSON.stringify(configuredPolicyOptions(memoryHome(), policyCwd)), ...(stop ? { signal: stop.signal } : {}) },   // the repository-narrowed policy binds what sync publishes too
+      sync: { ...(placementWriters ? { placementAttestation:placementWriters.attest } : {}), screen: row => configured.screenStandalone(row), policyVersion: () => JSON.stringify(configuredPolicyOptions(memoryHome(), policyCwd)), ...(stop ? { signal: stop.signal } : {}) },   // the repository-narrowed policy binds what sync publishes too
       onBridgeStatus: status => { receipt.bridgeStatus = status; },
       // #188: ids-only listing of nearby machine-local rows; policy-refused rows are neither listed nor counted.
       forgetNearby: note => forgetNearby({ base: memoryHome(), project: note.project, text: note.text, title: note.title, screen: value => configured.screenStandalone(value) }) }));
   } catch (error) {
     if (sub === "sync") stampSync((error as Error).message, stop?.cause());
+    if (sub === "sync" && placementWriters?.lastRefusal) throw Error(`${placementWriters.lastRefusal.message} ${(error as Error).message}`);
     throw error;
   }
   finally {
@@ -1079,7 +1106,13 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   if (sub === "sync") {
     // `--json` returns the failed result instead of throwing: read the real outcome from it, never assume a returned string means the sync worked.
     let failure: string | undefined;
-    if (options["--json"]) { try { const result = JSON.parse(output) as { ok?: unknown; error?: unknown }; if (result.ok === false) failure = typeof result.error === "string" ? result.error : "sync failed"; } catch { /* not a sync result */ } }
+    if (options["--json"]) { try {
+      const result = JSON.parse(output) as { ok?: unknown; error?: unknown };
+      if (result.ok === false) {
+        failure = typeof result.error === "string" ? result.error : "sync failed";
+        if (placementWriters?.lastRefusal) { result.error = `${placementWriters.lastRefusal.message} ${failure}`; output = JSON.stringify(result,null,2); }
+      }
+    } catch { /* not a sync result */ } }
     stampSync(failure, stop?.cause());
   }
   if (captureImport) {

package/src/commands-table.ts

@@ -116,6 +116,9 @@ export const COMMANDS: Record<string, CommandDefinition> = {
     "--resume": flag("Resume the recorded migration"), "--deactivate": flag("Select shared v1 without deleting a generation"),
     "--shards": flag("Migrate the curated home into project and user shards"),
     "--public-prune-view": flag("Enable the forward-only v2 public prune view on an active split"),
+    "--sync-placement": flag("Person-only forward-only placement activation on this memory home; no automatic migration or renewal"),
+    "--abandon": flag("Person-only: discard an interrupted sync-placement attempt only before either v3 marker is installed"),
+    "--writer-root": { description: "Repeatable absolute amem install root in the complete local writer inventory", value: "path" },
   } },
   status: { description: "Report shard migration and pending old-layout appends", options: json },
   doctor: { description: "One read-only report (F15): duplicates and stale notes, pending candidates, capture freshness per CLI, the brief's token cost, index equals rebuild, reader leases, the policy in effect, ingest and sync cadence", options: json },

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,20 @@ 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";
+export { measureSyncPlacementWriters, SyncPlacementWriterError } from "./memory/sync-placement-writers.ts";
+export type { MeasuredSyncPlacementWriterRoot, SyncPlacementWriterMeasurement, SyncPlacementWriterErrorCode } from "./memory/sync-placement-writers.ts";
+export { readSyncPlacementWriterRoots } from "./memory/sync-placement-writer-roots.ts";
+export { readEffectiveSyncPlacementWriters, readEffectiveSyncPlacementWriterRoots } from "./memory/sync-placement-effective-writers.ts";
+export type { EffectiveSyncPlacementWriters } from "./memory/sync-placement-effective-writers.ts";
+export { readSetupWriterRoots, SetupWriterRootsError } from "./setup.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);
   }