@staix/agent-mem 0.21.0 → 0.22.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.21.0",
+  "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.21.0. 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
 
@@ -555,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.21.0",
+  "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",

package/src/cli.ts

@@ -1,5 +1,5 @@
 import { assertFormatFloor } from "./memory/formats.ts";
-import { placementRuntimeRefusal } from "./memory/sync-placement-guard.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";
@@ -20,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";
@@ -378,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]");
@@ -472,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");
@@ -1062,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 {
@@ -1082,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/index.ts

@@ -72,3 +72,9 @@ 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/commands.ts

@@ -206,11 +206,12 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
         const r = await syncMemory(store, { ...opts.sync, ...(remote ? { remote } : {}) });
         if (json) return JSON.stringify(r, null, 2);
         if (!r.ok) fail(`${names.memory} sync: ${r.error}`);
+        const placement = r.placementPublication, placementText = placement ? `; placement ${placement.outcome}, ${placement.exported} exported, ${placement.withheld} withheld this attempt` : "";
         if (r.pruneApplication) {
           const a = r.pruneApplication;
-          return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries transported; ${a.proofComplete} prune proofs complete, ${a.projectionActive ?? "pending"} foreign projections active, ${a.nativeApplied ?? "pending"} native prunes applied, ${a.held} held${r.warning ? `\nnote: ${r.warning}` : ""}`;
+          return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries transported; ${a.proofComplete} prune proofs complete, ${a.projectionActive ?? "pending"} foreign projections active, ${a.nativeApplied ?? "pending"} native prunes applied, ${a.held} held${placementText}${r.warning ? `\nnote: ${r.warning}` : ""}`;
         }
-        return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries visible here${r.warning ? `\nnote: ${r.warning}` : ""}`;
+        return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries visible here${placementText}${r.warning ? `\nnote: ${r.warning}` : ""}`;
       }
       case "dedupe": {
         const apply = rest.includes("--apply");

package/src/memory/public-prune-activation.ts

@@ -80,7 +80,7 @@ function realmBinding(home: string, realms: Realm[]): void {
   for (const realm of realms) guard(metadata(realm.profile) === realm.metadata);
 }
 /** Atomic create-once publication, recovering only this exact complete staging pair. */
-function immutable(file: string, text: string): void {
+export function writeImmutableActivationMetadata(file: string, text: string): void {
   const base = dirname(file); if (!lstatSync(base, { throwIfNoEntry: false })) { mkdirSync(base, { mode: 0o700 }); fsyncDirectory(dirname(base)); } owned(base, true);
   const bytes = Buffer.from(text), temp = file + ".pending-" + createHash("sha256").update(bytes).digest("hex");
   if (lstatSync(file, { throwIfNoEntry: false })) {
@@ -231,7 +231,7 @@ export async function activatePublicPruneView(options: PublicPruneActivationOpti
       const dirs = [...new Set([home, ...intent.realms.map(realm => realm.profile.dir)])].sort();
       for (const dir of dirs) { assertNoLiveReaders(dir, {includeShards:true}); const release = acquireMutation(dir); guard(release); releases.push(release); }
       validateAdvance(intent);
-      if (pending) immutable(intentFile, canonicalJSON(intent) + "\n");
+      if (pending) writeImmutableActivationMetadata(intentFile, canonicalJSON(intent) + "\n");
       if (!pending) {
         guard(readProfileBytes(home) === intent.previousProfile && raw(join(home, "shards.json")) === intent.previousShards && aliases(home) === intent.aliases);
         realmBinding(home, intent.realms);
@@ -240,14 +240,14 @@ export async function activatePublicPruneView(options: PublicPruneActivationOpti
         }) }, home);
       }
       const viewHash = publicPruneViewHash(intent.view);
-      immutable(join(home, "public-prune-input-sets", viewHash + ".json"), canonicalJSON(intent.view) + "\n");
+      writeImmutableActivationMetadata(join(home, "public-prune-input-sets", viewHash + ".json"), canonicalJSON(intent.view) + "\n");
       readPublicPruneViewForActivation(home, viewHash, intent.generation);
       let profile = readProfileBytes(home), shards = raw(join(home, "shards.json"));
       guard((profile === intent.previousProfile || profile === intent.finalProfile) && (shards === intent.previousShards || shards === intent.finalShards));
       guard(profile !== intent.finalProfile || shards === intent.finalShards);
       verify(intent, profile, shards); for (const realm of intent.realms) syncIndex(nextProfile(realm, intent));
       if (!pending && profile === intent.finalProfile && shards === intent.finalShards) return { mode: options.mode, generation: intent.generation, active: true, alreadyActive: true, realms: intent.realms.length, viewHash, maskBuildCheck: "verified" };
-      immutable(intentFile, canonicalJSON(intent) + "\n");
+      writeImmutableActivationMetadata(intentFile, canonicalJSON(intent) + "\n");
       await options.checkpoint?.("after-intent"); verify(intent, profile, shards);
       if (shards !== intent.finalShards) { writeProfileJSON(join(home, "shards.json"), JSON.parse(intent.finalShards)); shards = intent.finalShards; }
       await options.checkpoint?.("after-shards"); verify(intent, profile, shards);

package/src/memory/shard-sync.ts

@@ -1,4 +1,3 @@
-import { syncPlacementMemory } from "./sync-placement-transport.ts";
 import { ShardSyncApplications, ShardSyncApplicationError } from "./shard-sync-applications.ts";
 import { ShardHistoryAuditor, ShardHistoryError, shardHistoryRefusal } from "./shard-sync-history.ts";
 import { validatePlacementProfile, type PlacementProfile } from "./sync-placement-format.ts";
@@ -446,7 +445,7 @@ async function prepareHolds(targets: readonly Target[], root: string, url: strin
 export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions = {}, testOnlyUnexpectedError?: (error: unknown) => void, testOnlyPhase?: (phase: SyncPhase) => void): Promise<SyncResult> {
   const placementRefusal = placementRuntimeRefusal(store.profile.home, store.profile);
   if (placementRefusal) return { ok: false, pushed: false, entries: 0, error: placementRefusal };
-  if (store.profile.publicationFormat === "agent-mem.sync-placement/v1") return syncPlacementMemory(store, opts);
+  if (store.profile.publicationFormat === "agent-mem.sync-placement/v1") return (await import("./sync-placement-transport.ts")).syncPlacementMemory(store, opts);
   let pushed = false, releaseTransport: (() => void) | undefined, releaseSync: (() => void) | undefined;
   const releases: (() => void)[] = [], transient: string[] = [], temporary: string[] = [];
   const v2 = store.profile.foreignPruneFormat === "agent-mem.public-prune-witness/v1";

package/src/memory/sync-cadence.ts

@@ -88,8 +88,9 @@ export function endLikeSignal(name: string): void {
  */
 function syncRepository(home: string): string | undefined {
   try {
-    if (lstatSync(join(home, "shards.json"), { throwIfNoEntry: false })) return join(home, "shard-sync", "objects.git", "config");
     const { selector } = readSelector(home);
+    if (selector?.schema === "agent-mem.profile/v3") return join(home,"shard-sync-placement","objects.git","config");
+    if (lstatSync(join(home, "shards.json"), { throwIfNoEntry: false })) return join(home, "shard-sync", "objects.git", "config");
     if (selector?.kind === "generation") return join(generationDir(home, selector.generation!), ".git", "config");
     return join(home, ".git", "config");
   } catch { return undefined; }

package/src/memory/sync-placement-abandon.ts

@@ -0,0 +1,142 @@
+/** Person coordinator's precommit-only metadata cleanup. No rollback, source rewrite, renewal or package measurement. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, opendirSync, readSync, rmdirSync, unlinkSync, type BigIntStats } from "node:fs";
+import { dirname, join } from "node:path";
+import { types } from "node:util";
+import { canonicalJSON } from "./generation.ts";
+import { realPath } from "./platform.ts";
+import { assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { placementEpochHash, SyncPlacementJournalError, type SyncPlacementJournalErrorCode } from "./sync-placement-journal-format.ts";
+import { validatePlacementActivationIntent, readPlacementActivationIntent, clearPlacementActivationIntent, PLACEMENT_ACTIVATION_INTENT_FILE, type PlacementActivationIntent } from "./sync-placement-activation-storage.ts";
+import { planSyncPlacementWriterRoots, SYNC_PLACEMENT_WRITER_ROOTS_FILE } from "./sync-placement-writer-roots.ts";
+import { syncPlacementWriterId } from "./sync-placement-writers.ts";
+import { SYNC_SCREEN_MAX_BYTES, SYNC_SCREEN_MAX_ROWS } from "./sync-screen.ts";
+
+export interface PlacementAbandonOptions { mutation: MutationHandle; assertCurrent(): void }
+export class PlacementActivationAbandonError extends Error {
+  readonly code: "forward" | "metadata" | "bound";
+  constructor(code: "forward" | "metadata" | "bound" = "metadata") {
+    super(code === "forward"
+      ? "activation markers or active fence changed; use forward --resume with a compatible recovery release"
+      : code === "bound" ? "activation cleanup metadata exceeds the supported bound; inspect it with a compatible recovery release"
+      : "activation cleanup metadata is unsafe, changed or unknown; inspect it with a compatible recovery release before deleting anything");
+    this.name = "PlacementActivationAbandonError"; this.code = code;
+  }
+}
+function fail(code: SyncPlacementJournalErrorCode = "corrupt"): never { throw new SyncPlacementJournalError(code); }
+const bytes = (value: unknown) => Buffer.from(canonicalJSON(value) + "\n");
+const hash = (value: Uint8Array) => createHash("sha256").update(value).digest("hex");
+const identity = (s: BigIntStats) => [s.dev, s.ino, s.uid, s.mode].map(String).join(":");
+const stamp = (s: BigIntStats) => [s.dev, s.ino, s.uid, s.mode, s.nlink, s.size, s.mtimeNs, s.ctimeNs].map(String).join(":");
+function owned(s: BigIntStats, directory = false, links: readonly bigint[] = [1n], marker = false): void {
+  if (s.isSymbolicLink() || s.uid !== BigInt(process.getuid?.() ?? -1)
+    || (directory ? !s.isDirectory() || (s.mode & 0o077n) !== 0n : !s.isFile() || !links.includes(s.nlink) || (marker ? (s.mode & 0o022n) !== 0n : (s.mode & 0o777n) !== 0o600n))) fail();
+}
+interface Member { stat: BigIntStats; expected: Buffer }
+interface State { files: Map<string, Member>; dirs: Map<string, BigIntStats> }
+function readMember(file: string, expected: Buffer, prefix = false, links: readonly bigint[] = [1n], marker = false): Member | undefined {
+  const before = lstatSync(file, { bigint: true, throwIfNoEntry: false }); if (!before) return undefined;
+  owned(before, false, links, marker); if (before.size > BigInt(expected.length)) fail("bound");
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd, { bigint: true }); if (stamp(opened) !== stamp(before)) fail("changed");
+    const data = Buffer.alloc(Number(opened.size) + 1); let at = 0;
+    while (at < data.length) { const n = readSync(fd, data, at, data.length - at, at); if (!n) break; at += n; }
+    if (at !== Number(opened.size) || stamp(fstatSync(fd, { bigint: true })) !== stamp(opened) || stamp(lstatSync(file, { bigint: true })) !== stamp(opened)) fail("changed");
+    if ((!prefix && at !== expected.length) || !data.subarray(0, at).equals(expected.subarray(0, at))) fail("conflict");
+    return { stat: opened, expected };
+  } finally { closeSync(fd); }
+}
+function directory(path: string): BigIntStats | undefined {
+  const value = lstatSync(path, { bigint: true, throwIfNoEntry: false }); if (value) owned(value, true); return value;
+}
+function names(path: string, maximum: number): string[] {
+  const result: string[] = [], iterator = opendirSync(path); let size = 2;
+  try { for (;;) { const entry = iterator.readSync(); if (!entry) break; if (result.length >= maximum) fail("bound");
+    size += Buffer.byteLength(JSON.stringify(entry.name)) + 1; if (size > SYNC_SCREEN_MAX_BYTES) fail("bound"); result.push(entry.name);
+  } } finally { iterator.closeSync(); } return result.sort();
+}
+/** Called only after person approval and under activation's existing live profile/readers/sync/mutation fences. */
+export function abandonPlacementActivation(homeInput: string, input: PlacementActivationIntent, options: PlacementAbandonOptions): void {
+  try {
+    const intent = validatePlacementActivationIntent(input), initialHome = lstatSync(homeInput, { bigint: true }); owned(initialHome, true);
+    const home = realPath(homeInput); if (home !== intent.home || identity(directory(home)!) !== identity(initialHome)) fail("changed");
+    const epochHash = placementEpochHash(intent.epoch), storage = join(home, "sync-placement"), epochs = join(storage, "epochs"), epochDir = join(epochs, epochHash);
+    const intentFile = join(home, PLACEMENT_ACTIVATION_INTENT_FILE), intentBytes = bytes(intent), intentTemp = intentFile + ".pending-" + hash(intentBytes);
+    const roots = intent.roots.map(root => {
+      const writerId = syncPlacementWriterId(root), writer = intent.plan.writers.find(value => value.writerId === writerId); if (!writer) fail("conflict");
+      return { root, writerId, version: writer.version, pin: writer.pin };
+    });
+    const locatorBytes = bytes(planSyncPlacementWriterRoots({ epochHash, homeHash: intent.epoch.homeHash, activationHash: intent.plan.seal, roots },
+      { epochHash, homeHash: intent.epoch.homeHash, activationHash: intent.plan.seal, writers: intent.plan.writers }));
+    const locator = join(home, SYNC_PLACEMENT_WRITER_ROOTS_FILE), locatorTemp = locator + ".pending-" + hash(locatorBytes);
+    const expectedEpoch = new Map([["epoch.json", bytes(intent.epoch)], ["activation.json", bytes(intent.plan)]]);
+    let clearing = false;
+    const proof = () => {
+      assertMutationHandle(options.mutation, home); options.assertCurrent(); assertMutationHandle(options.mutation, home);
+      if (identity(directory(home)!) !== identity(initialHome)) fail("changed");
+      try {
+        if (!readMember(join(home, "profile.json"), Buffer.from(intent.previousProfile), false, [1n], true)
+          || !readMember(join(home, "shards.json"), Buffer.from(intent.previousShards), false, [1n], true)) throw new PlacementActivationAbandonError("forward");
+      } catch { throw new PlacementActivationAbandonError("forward"); }
+      if (directory(storage) && lstatSync(join(storage, "active.json"), { throwIfNoEntry: false })) throw new PlacementActivationAbandonError("forward");
+      const actual = readPlacementActivationIntent(home);
+      if (actual ? canonicalJSON(actual) !== canonicalJSON(intent) : !clearing) fail("changed");
+    };
+    const scan = (): State => {
+      const files = new Map<string, Member>(), dirs = new Map<string, BigIntStats>([[home, directory(home)!]]);
+      for (const path of [storage, epochs, epochDir]) { const stat = directory(path); if (stat) dirs.set(path, stat); }
+      if (dirs.has(storage)) for (const name of names(storage, 2)) if (name !== "epochs") fail("corrupt");
+      const knownTemps = new Set([intentTemp, locatorTemp]);
+      for (const name of names(home, SYNC_SCREEN_MAX_ROWS)) if (name.startsWith(PLACEMENT_ACTIVATION_INTENT_FILE + ".pending-") || name.startsWith(SYNC_PLACEMENT_WRITER_ROOTS_FILE + ".pending-"))
+        if (!knownTemps.has(join(home, name))) fail("corrupt");
+      const add = (path: string, expected: Buffer, prefix = false, links: readonly bigint[] = [1n]) => { const value = readMember(path, expected, prefix, links); if (value) files.set(path, value); return value; };
+      const final = add(locator, locatorBytes, false, [1n, 2n]), temp = add(locatorTemp, locatorBytes, true, [1n, 2n]);
+      if (final?.stat.nlink === 2n || temp?.stat.nlink === 2n) {
+        if (!final || !temp || final.stat.size !== BigInt(locatorBytes.length) || temp.stat.size !== BigInt(locatorBytes.length) || stamp(final.stat) !== stamp(temp.stat)) fail("corrupt");
+      }
+      if (dirs.has(epochDir)) for (const name of names(epochDir, 3)) { const expected = expectedEpoch.get(name); if (!expected) fail("corrupt"); add(join(epochDir, name), expected, true); }
+      const current = add(intentFile, intentBytes, false, [1n, 2n]), companion = add(intentTemp, intentBytes, false, [1n, 2n]);
+      if (current?.stat.nlink === 2n || companion) {
+        if (!current || !companion || current.stat.nlink !== 2n || companion.stat.nlink !== 2n || stamp(current.stat) !== stamp(companion.stat)) fail("corrupt");
+      }
+      if (!current && !clearing) fail("changed"); return { files, dirs };
+    };
+    proof(); let state = scan();
+    const check = () => {
+      proof(); const next = scan();
+      const expectedFiles = [...state.files.keys()].filter(path => !clearing || path !== intentFile).sort(), foundFiles = [...next.files.keys()].filter(path => !clearing || path !== intentFile).sort();
+      if (canonicalJSON(expectedFiles) !== canonicalJSON(foundFiles) || canonicalJSON([...state.dirs.keys()].sort()) !== canonicalJSON([...next.dirs.keys()].sort())) fail("changed");
+      for (const [path, before] of state.files) { const after = next.files.get(path); if (clearing && path === intentFile && !after) continue; if (!after || stamp(before.stat) !== stamp(after.stat)) fail("changed"); }
+      for (const [path, before] of state.dirs) if (identity(before) !== identity(next.dirs.get(path)!)) fail("changed");
+    };
+    const sync = (path: string) => {
+      check(); const expected = state.dirs.get(path); if (!expected) fail("changed"); const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+      try { if (identity(fstatSync(fd, { bigint: true })) !== identity(expected)) fail("changed"); fsyncSync(fd); } finally { closeSync(fd); } check();
+    };
+    const remove = (path: string) => {
+      if (!state.files.has(path)) return; check(); const before = state.files.get(path)!; unlinkSync(path); state.files.delete(path);
+      for (const [peer, item] of state.files) if (item.stat.dev === before.stat.dev && item.stat.ino === before.stat.ino) {
+        const now = lstatSync(peer, { bigint: true }); owned(now);
+        if (before.stat.nlink !== 2n || now.nlink !== 1n || now.dev !== item.stat.dev || now.ino !== item.stat.ino || now.uid !== item.stat.uid || now.mode !== item.stat.mode || now.size !== item.stat.size || now.mtimeNs !== item.stat.mtimeNs) fail("changed");
+        item.stat = now;
+      }
+      sync(dirname(path));
+    };
+    remove(locatorTemp); remove(locator);
+    for (const name of ["activation.json", "epoch.json"]) remove(join(epochDir, name));
+    if (state.dirs.has(epochDir)) { check(); if (names(epochDir, 1).length) fail("changed"); rmdirSync(epochDir); state.dirs.delete(epochDir); sync(epochs); }
+    remove(intentTemp);
+    // A prior owner may have unlinked a member or removed this epoch before its directory fsync.
+    // Reassert every retained parent before the intent can acknowledge that cleanup as complete.
+    for (const path of [epochs, storage, home]) if (state.dirs.has(path)) sync(path);
+    check(); clearing = true;
+    clearPlacementActivationIntent(home, intent, { mutation: options.mutation, assertCurrent: check }); state.files.delete(intentFile); check();
+  } catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error) && error instanceof PlacementActivationAbandonError) throw error;
+    if (error && typeof error === "object" && !types.isProxy(error) && error instanceof SyncPlacementJournalError) {
+      const value = Object.getOwnPropertyDescriptor(error, "code"); if (value && "value" in value && ["invalid", "corrupt", "bound", "conflict", "pending", "changed", "authorization", "policy", "local", "busy"].includes(value.value)) throw new PlacementActivationAbandonError(value.value === "bound" ? "bound" : "metadata");
+    }
+    throw new PlacementActivationAbandonError();
+  }
+}

package/src/memory/sync-placement-activation-locks.ts

@@ -0,0 +1,28 @@
+/** Shared person-migration fences. No serialized value grants ownership. */
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { withProfileLock } from "./generation.ts";
+import { acquireMutation, type MutationHandle } from "./mutation.ts";
+import { generationSyncLock } from "./generation-sync.ts";
+import { assertNoLiveReaders } from "./reader-lease.ts";
+import { createPlacementActivationOwner } from "./sync-placement-activation-proof.ts";
+export class PlacementInventoryFenceError extends Error{
+  constructor(readonly causeClass:"readers"|"busy"){super(`Sync placement migration is ${causeClass}; close cooperating readers/writers, then run amem migrate --sync-placement --dry-run before retrying.`);this.name="PlacementInventoryFenceError";}
+}
+function fail(cause:"readers"|"busy"):never{throw new PlacementInventoryFenceError(cause);}
+export async function withPlacementActivationFences<T>(home:string,directories:readonly string[],work:(mutation:MutationHandle,owner:ReturnType<typeof createPlacementActivationOwner>)=>Promise<T>):Promise<T> {
+  return withProfileLock(home,async()=>{
+    const releases:(()=>void)[]=[];
+    try {
+      const transports=["shard-sync","shard-sync-placement"].map(name=>join(home,name)).filter(dir=>lstatSync(dir,{throwIfNoEntry:false})!==undefined);
+      const dirs=[...new Set([home,...directories,...transports])].sort();let mutation:MutationHandle|undefined;
+      for(const dir of dirs){
+        try{assertNoLiveReaders(dir,{includeShards:true});}catch{fail("readers");}
+        const handle=acquireMutation(dir);if(!handle)fail("busy");releases.push(handle);if(dir===home)mutation=handle;
+      }
+      if(!mutation)fail("busy");
+      for(const dir of [home,...transports]){const release=generationSyncLock(dir);if(!release)fail("busy");releases.push(release);}
+      const owner=createPlacementActivationOwner(home,mutation);return await work(mutation,owner);
+    }finally{for(const release of releases.reverse())release();}
+  });
+}

package/src/memory/sync-placement-activation-path.ts

@@ -0,0 +1,2 @@
+/** Pending coordinator metadata, outside the closed placement-journal namespace. */
+export const PLACEMENT_ACTIVATION_INTENT = "sync-placement-activation.json";

package/src/memory/sync-placement-activation-proof.ts

@@ -0,0 +1,68 @@
+/** Internal activation-owner proof. No serialized object or boolean grants lock bypass authority. */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { processSignature, realPath } from "./platform.ts";
+import type { PlacementActivationMarkerSnapshot } from "./sync-placement-capture.ts";
+import { readPlacementActivationIntent, validatePlacementActivationIntent, placementActivationFinalMarkers, type PlacementActivationIntent } from "./sync-placement-activation-storage.ts";
+
+declare const ownerBrand: unique symbol, captureBrand: unique symbol;
+export interface PlacementActivationOwner { readonly [ownerBrand]: true }
+export interface PlacementActivationCaptureProof { readonly [captureBrand]: true }
+interface Owner { home: string; mutation: MutationHandle; root: BigIntStats; lock: string; lockStamp: string }
+const owners = new WeakMap<PlacementActivationOwner, Owner>();
+const captures = new WeakMap<PlacementActivationCaptureProof, { owner: PlacementActivationOwner; intent: PlacementActivationIntent }>();
+const stamp = (s: BigIntStats) => [s.dev,s.ino,s.size,s.mtimeNs,s.ctimeNs].map(String).join(":");
+function fail(): never { throw Error("Sync placement activation ownership or retained evidence changed; close cooperating writers and run amem migrate --sync-placement --resume after person inspection."); }
+function lockBytes(home: string): { text: string; stamp: string } {
+  const file = join(home,"profile.lock"), before = lstatSync(file,{bigint:true});
+  if (!before.isFile() || before.isSymbolicLink() || before.uid !== BigInt(process.getuid?.() ?? -1) || (before.mode & 0o077n) !== 0n || before.nlink !== 1n || before.size < 1n || before.size > 4096n) fail();
+  const fd = openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd,{bigint:true}); if (stamp(opened) !== stamp(before)) fail();
+    const out = Buffer.alloc(Number(opened.size)); let at = 0;
+    while (at < out.length) { const n = readSync(fd,out,at,out.length-at,at); if (!n) fail(); at += n; }
+    if (stamp(fstatSync(fd,{bigint:true})) !== stamp(opened) || stamp(lstatSync(file,{bigint:true})) !== stamp(opened)) fail();
+    return { text: new TextDecoder("utf-8",{fatal:true}).decode(out), stamp: stamp(opened) };
+  } finally { closeSync(fd); }
+}
+export function createPlacementActivationOwner(homeInput: string, mutation: MutationHandle): PlacementActivationOwner {
+  try {
+    const home = realPath(homeInput); assertMutationHandle(mutation,home);
+    const root = lstatSync(home,{bigint:true}), lock = lockBytes(home), value = JSON.parse(lock.text) as Record<string,unknown>;
+    if (!root.isDirectory() || root.isSymbolicLink() || root.uid !== BigInt(process.getuid?.() ?? -1) || (root.mode & 0o077n) !== 0n
+      || Object.keys(value).sort().join() !== "pid,signature,token" || value.pid !== process.pid || value.signature !== processSignature(process.pid)
+      || typeof value.signature !== "string" || !value.signature || typeof value.token !== "string" || !/^[a-f0-9]{32}$/.test(value.token)) fail();
+    const token = Object.freeze({}) as PlacementActivationOwner;
+    owners.set(token,{home,mutation,root,lock:lock.text,lockStamp:lock.stamp}); return token;
+  } catch { return fail(); }
+}
+export function assertPlacementActivationOwner(token: PlacementActivationOwner, home?: string): void {
+  try {
+    const owner = owners.get(token); if (!owner) fail(); assertMutationHandle(owner.mutation,owner.home);
+    if(home!==undefined&&realPath(home)!==owner.home)fail();
+    const root = lstatSync(owner.home,{bigint:true}), lock = lockBytes(owner.home);
+    if (!root.isDirectory() || root.isSymbolicLink() || root.dev !== owner.root.dev || root.ino !== owner.root.ino || root.uid !== owner.root.uid || (root.mode & 0o077n) !== 0n
+      || lock.text !== owner.lock || lock.stamp !== owner.lockStamp) fail();
+    assertMutationHandle(owner.mutation,owner.home);
+  } catch { fail(); }
+}
+export function createPlacementActivationCaptureProof(owner: PlacementActivationOwner, input: PlacementActivationIntent): PlacementActivationCaptureProof {
+  assertPlacementActivationOwner(owner);
+  const state = owners.get(owner)!;
+  const intent = validatePlacementActivationIntent(input), actual = readPlacementActivationIntent(state.home);
+  if (!intent || !actual || canonicalJSON(intent) !== canonicalJSON(actual)
+    || actual.home !== state.home || actual.epoch.homeHash !== hashJSON([state.home,String(state.root.dev),String(state.root.ino),String(state.root.uid)])) fail();
+  const token = Object.freeze({}) as PlacementActivationCaptureProof; captures.set(token,{owner,intent:actual}); return token;
+}
+export function activationSourceMarkers(token: PlacementActivationCaptureProof, home: string, markers: { profileText: string; shardsText: string; profileStamp: readonly string[]; shardsStamp: readonly string[] }): PlacementActivationMarkerSnapshot {
+  const scope = captures.get(token); if (!scope) fail(); assertPlacementActivationOwner(scope.owner);
+  const state = owners.get(scope.owner)!, actual = readPlacementActivationIntent(home), intent = scope.intent;
+  if (home !== state.home || !actual || canonicalJSON(actual) !== canonicalJSON(intent)) fail();
+  const { profileText, shardsText } = markers;
+  const final = placementActivationFinalMarkers(intent), oldProfile = profileText === intent.previousProfile, oldShards = shardsText === intent.previousShards;
+  if ((!oldProfile && profileText !== final.profile) || (!oldShards && shardsText !== final.shards) || !oldProfile && shardsText !== final.shards) fail();
+  if (oldProfile && canonicalJSON(markers.profileStamp) !== canonicalJSON(intent.profileStamp) || oldShards && canonicalJSON(markers.shardsStamp) !== canonicalJSON(intent.shardsStamp)) fail();
+  return { profileText:intent.previousProfile,shardsText:intent.previousShards,profileStamp:[...intent.profileStamp],shardsStamp:[...intent.shardsStamp] };
+}