@staix/agent-mem 0.20.3 → 0.22.0

package/src/memory/sync-screen.ts

@@ -1,7 +1,12 @@
-import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
+import { createHash } from "node:crypto";
+import { types } from "node:util";
 import { join } from "node:path";
+import { OP_CONTRACTS } from "./ops-contract.ts";
+import { SUGGESTED } from "./store.ts";
+import { checkedEntry } from "./bridge.ts";
 import { loadAmemConfig } from "./config.ts";
-import { createStandalonePolicy } from "./policy.ts";
+import { createStandalonePolicy, type StandalonePolicyDecline } from "./policy.ts";
 import type { MemoryStore } from "./store.ts";
 
 /**
@@ -19,7 +24,8 @@ import type { MemoryStore } from "./store.ts";
  * ponytail: a person clears a declined entry by removing the offending pattern or editing the policy; sync does not skip a row, and `amem forget` is an
  * append-only op that leaves the original row in the log. Upgrade: a per-row placement that keeps a declined note local without refusing the sync.
  */
-const MAX_BYTES = 8 * 1024 * 1024, MAX_ROWS = 20_000;
+export const SYNC_SCREEN_MAX_BYTES = 8 * 1024 * 1024, SYNC_SCREEN_MAX_ROWS = 20_000;
+const MAX_BYTES = SYNC_SCREEN_MAX_BYTES, MAX_ROWS = SYNC_SCREEN_MAX_ROWS;
 
 export type SyncScreen = { ok: true } | { ok: false; reason: string };
 
@@ -27,19 +33,55 @@ export type SyncScreen = { ok: true } | { ok: false; reason: string };
  * What a row says: everything except the fields the library itself generates (ids, hashes, times, the op and enum names, machine and actor ids). Left IN on purpose
  * are `project`, `peer`, `task`, `about`, `title`, `text`, `milestones` and any field this file has never heard of: an unknown text field must be screened, never skipped.
  */
-const GENERATED = new Set(["id", "schema", "op", "at", "machine", "actor", "target", "promotedFrom", "supersedes", "expires", "by", "tier", "scope", "kind", "source"]);
-function textOf(row: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(row)) if (!GENERATED.has(key)) out[key] = value;
+const GENERATED = new Set(["id", "schema", "op", "at", "machine", "actor", "promotedFrom", "supersedes", "expires", "tier", "scope", "kind", "source"]);
+/** Only a known operation's validated id/enum/time operand is generated metadata.
+ * A task key, an unknown operand field or an unsupported operand shape remains content. */
+function generatedOperand(operation: unknown, key: string, value: unknown): boolean {
+  if (key !== "target" && key !== "by" || typeof operation !== "string" || !Object.hasOwn(OP_CONTRACTS, operation)) return false;
+  const field = OP_CONTRACTS[operation]?.payloadSchema?.fields[key];
+  if (typeof value !== "string" || !field) return false;
+  if (field.format === "id") return /^[a-f0-9]{32}$/.test(value);
+  if (field.format === "utc") return Number.isFinite(Date.parse(value));
+  if (field.values) return field.values.includes(value);
+  // Suggestion operands are a closed relation enum plus an immutable entry id, not task text.
+  if (operation === "suggest" && key === "by") {
+    const match = /^([^:]+):[a-f0-9]{32}$/.exec(value);
+    return match !== null && (SUGGESTED as readonly string[]).includes(match[1]!);
+  }
+  return false;
+}
+
+export function syncOutboundContent(row: unknown): Record<string, unknown> {
+  if (!row || typeof row !== "object" || Array.isArray(row) || types.isProxy(row) || Object.getOwnPropertySymbols(row).length) throw new Error("outbound row unavailable");
+  const out: Record<string, unknown> = {}, descriptors = Object.getOwnPropertyDescriptors(row);
+  const operation = descriptors.op?.value;
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (GENERATED.has(key) || generatedOperand(operation, key, descriptor.value)) continue;
+    if (!("value" in descriptor) || !descriptor.enumerable) throw new Error("outbound row unavailable");
+    Object.defineProperty(out, key, { value: descriptor.value, enumerable: true, writable: true, configurable: true });
+  }
   return out;
 }
 
 /** A row passes when the machine's configured policy and the caller's extra screen (if any) both accept its text. */
 export type RowScreen = (row: Record<string, unknown>) => boolean;
-export function outboundScreen(home: string, extra?: RowScreen): RowScreen {
+export type SyncPolicyCategory = StandalonePolicyDecline | "host";
+export type OutboundVerdict = { ok: true } | { ok: false; category: SyncPolicyCategory };
+/** One evaluator for actual sync and public inspection, with the same projection and AND composition. */
+export function outboundPolicyEvaluator(home: string, extra?: RowScreen): (row: Record<string, unknown>) => OutboundVerdict {
   const { config } = loadAmemConfig(home);
   const policy = createStandalonePolicy({ denyPaths: config.denyPaths, piiPatterns: config.piiPatterns });
-  return row => { const text = textOf(row); return policy.screenStandalone(text) && (extra?.(text) ?? true); };
+  return row => {
+    const text = syncOutboundContent(row), own = policy.inspectStandalone(text);
+    if (!own.ok) return own;
+    const accepted = extra === undefined ? true : extra(text);
+    if (typeof accepted !== "boolean") throw new Error("outbound policy unavailable");
+    return accepted ? { ok: true } : { ok: false, category: "host" };
+  };
+}
+export function outboundScreen(home: string, extra?: RowScreen): RowScreen {
+  const evaluate = outboundPolicyEvaluator(home, extra);
+  return row => evaluate(row).ok;
 }
 const refusal = (declined: string[]): SyncScreen => declined.length ? { ok: false, reason: `the configured privacy policy declines ${declined.length} long-term entr${declined.length === 1 ? "y" : "ies"} (${declined.slice(0, 8).join(", ")}${declined.length > 8 ? ", ..." : ""}); fix the entry or the policy, then sync again` } : { ok: true };
 const idOf = (row: Record<string, unknown>) => typeof row.id === "string" ? row.id.slice(0, 8) : "(no id)";
@@ -48,39 +90,92 @@ const idOf = (row: Record<string, unknown>) => typeof row.id === "string" ? row.
 export function screenOutboundRows(store: MemoryStore, pass: RowScreen): SyncScreen {
   const declined: string[] = [];
   let rows = 0;
-  let snapshot: ReturnType<ReturnType<MemoryStore["prunePort"]>["snapshot"]>;
-  // A bootstrap-only handle has no snapshot: that is a refusal like any unreadable source, never an exception out of sync (which promises a result).
-  try { snapshot = store.prunePort().snapshot(); } catch { return { ok: false, reason: "this store's long-term rows cannot be read, so they were not screened" }; }
-  for (const source of snapshot.rows) {
-    if (source.placement !== "synced" || !(source.own || source.legacy)) continue;
-    if (++rows > MAX_ROWS) return { ok: false, reason: `more than ${MAX_ROWS} long-term rows, so they were not screened` };
-    if (!pass(source.row as unknown as Record<string, unknown>)) declined.push(idOf(source.row as unknown as Record<string, unknown>));
-  }
+  // Actual sync retains its existing canonical refresh/recovery snapshot. Public inspection uses the read-only
+  // source visitor instead, so it never performs this derived-state mutation or adopts a torn prune recovery tail.
+  try {
+    const snapshot = store.prunePort().snapshot();
+    for (const source of snapshot.rows) {
+      if (source.placement !== "synced" || !(source.own || source.legacy)) continue;
+      if (++rows > MAX_ROWS) return { ok: false, reason: `more than ${MAX_ROWS} long-term rows, so they were not screened` };
+      if (!pass(source.row as unknown as Record<string, unknown>)) declined.push(idOf(source.row as unknown as Record<string, unknown>));
+    }
+  } catch { return { ok: false, reason: "this store's long-term rows cannot be read, so they were not screened; inspect the local inputs and reopen the store before retrying" }; }
   return refusal(declined);
 }
 
-/** Screen one machine's own long-term segment under `dir`. */
-export function screenOwnSegment(dir: string, machineId: string, pass: RowScreen): SyncScreen {
-  const file = join(dir, "log", `${machineId}.jsonl`);
+export class SyncScreenInputError extends Error {
+  constructor(readonly code: "input-unavailable" | "input-bound" | "input-changed", readonly bound?: "bytes" | "rows") { super(code); }
+}
+const sameStat = (a: BigIntStats, b: BigIntStats) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
+
+/** One bounded physical segment. The returned check pins it across the other opened targets and host callbacks too. */
+export function visitOwnSegment(dir: string, machineId: string, visit: (row: Record<string, unknown>) => void): () => void {
+  const parent = join(dir, "log"), parentStat = lstatSync(parent, { bigint: true, throwIfNoEntry: false });
+  if (parentStat && (!parentStat.isDirectory() || parentStat.isSymbolicLink())) throw new SyncScreenInputError("input-unavailable");
+  const checkParent = () => {
+    const now = lstatSync(parent, { bigint: true, throwIfNoEntry: false });
+    if (parentStat ? !now || !now.isDirectory() || now.isSymbolicLink() || now.dev !== parentStat.dev || now.ino !== parentStat.ino : now !== undefined) throw new SyncScreenInputError("input-changed");
+  };
+  const file = join(parent, `${machineId}.jsonl`);
   let fd: number;
   try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
   catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { ok: true };   // nothing authored here: nothing to push
-    return { ok: false, reason: "this machine's long-term segment cannot be read, so it was not screened" };
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return () => {
+      checkParent();
+      if (lstatSync(file, { throwIfNoEntry: false })) throw new SyncScreenInputError("input-changed");
+    };
+    throw new SyncScreenInputError("input-unavailable");
   }
   try {
-    const stat = fstatSync(fd);
-    if (!stat.isFile() || stat.size > MAX_BYTES) return { ok: false, reason: `this machine's long-term segment is not a plain file within ${MAX_BYTES} bytes, so it was not screened` };
-    const declined: string[] = [];
-    let rows = 0;
-    for (const line of readFileSync(fd, "utf8").split("\n")) {
+    const stat = fstatSync(fd, { bigint: true });
+    if (!stat.isFile() || stat.nlink !== 1n) throw new SyncScreenInputError("input-unavailable");
+    if (stat.size > BigInt(MAX_BYTES)) throw new SyncScreenInputError("input-bound", "bytes");
+    const check = () => {
+      checkParent();
+      const named = lstatSync(file, { bigint: true });
+      if (!named.isFile() || named.isSymbolicLink() || !sameStat(stat, named)) throw new SyncScreenInputError("input-changed");
+    };
+    check();
+    // No whole-file string/split array: the stat bound precedes allocation; the row bound precedes parsing each row.
+    const bytes = Buffer.alloc(Number(stat.size));
+    let at = 0;
+    while (at < bytes.length) { const n = readSync(fd, bytes, at, bytes.length - at, at); if (!n) throw new SyncScreenInputError("input-changed"); at += n; }
+    if (bytes.length && bytes.at(-1) !== 10) throw new SyncScreenInputError("input-unavailable");
+    let start = 0, rows = 0;
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    for (let end = 0; end < bytes.length; end++) {
+      if (bytes[end] !== 10) continue;
+      if (start === end) { start = end + 1; continue; }
+      const line = decoder.decode(bytes.subarray(start, end)); start = end + 1;
       if (!line.trim()) continue;
-      if (++rows > MAX_ROWS) return { ok: false, reason: `more than ${MAX_ROWS} long-term rows, so they were not screened` };
-      let row: Record<string, unknown>;
-      try { row = JSON.parse(line) as Record<string, unknown>; } catch { return { ok: false, reason: "a line of this machine's long-term segment does not parse, so it was not screened" }; }
-      // Every row kind is read, not only notes: a goal's title and milestones sync too, and so does any text an op adds later (see `textOf`).
-      if (!pass(row)) declined.push(idOf(row));
+      if (++rows > MAX_ROWS) throw new SyncScreenInputError("input-bound", "rows");
+      let row: unknown;
+      try { row = checkedEntry(JSON.parse(line)); } catch { throw new SyncScreenInputError("input-unavailable"); }
+      visit(row as Record<string, unknown>);
     }
-    return refusal(declined);
+    const expected = createHash("sha256").update(bytes).digest("hex"), digest = createHash("sha256"), buffer = Buffer.alloc(65_536);
+    at = 0;
+    while (at < bytes.length) { const n = readSync(fd, buffer, 0, Math.min(buffer.length, bytes.length - at), at); if (!n) throw new SyncScreenInputError("input-changed"); digest.update(buffer.subarray(0, n)); at += n; }
+    if (expected !== digest.digest("hex") || !sameStat(stat, fstatSync(fd, { bigint: true }))) throw new SyncScreenInputError("input-changed");
+    check(); return check;
   } finally { closeSync(fd); }
 }
+
+/** Screen one machine's own long-term segment under `dir`, using the inspector's same bounded reader. */
+export function screenOwnSegment(dir: string, machineId: string, pass: RowScreen): SyncScreen {
+  const declined: string[] = [];
+  try { visitOwnSegment(dir, machineId, row => { if (!pass(row)) declined.push(idOf(row)); })(); }
+  catch (error) {
+    let code: unknown, bound: unknown;
+    if (error && typeof error === "object" && !types.isProxy(error)) {
+      code = Object.getOwnPropertyDescriptor(error, "code")?.value;
+      bound = Object.getOwnPropertyDescriptor(error, "bound")?.value;
+    }
+    const inspect = "; inspect the local input and reopen the store before retrying";
+    if (code === "input-bound" && bound === "rows") return { ok: false, reason: `more than ${MAX_ROWS} long-term rows, so they were not screened${inspect}` };
+    if (code === "input-bound" && bound === "bytes") return { ok: false, reason: `this machine's long-term segment exceeds ${MAX_BYTES} bytes, so it was not screened${inspect}` };
+    if (code === "input-changed") return { ok: false, reason: "this machine's long-term segment changed while being screened, so it was not screened; wait for writers to finish and retry" };
+    return { ok: false, reason: "this machine's long-term segment is not readable as complete valid rows, so it was not screened" + inspect };
+  }
+  return refusal(declined);
+}

package/src/memory/sync.ts

@@ -1,13 +1,15 @@
+import type { PlacementCapturePort } from "./sync-placement-capture.ts";
+import { placementRuntimeRefusal } from "./sync-placement-guard.ts";
 import { assertFormatFloor } from "./formats.ts";
-import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, rmSync, writeFileSync, writeSync, type BigIntStats } from "node:fs";
-import { createHash } from "node:crypto";
-import { dirname, join, relative, sep } from "node:path";
+import { closeSync, constants, existsSync, openSync, readFileSync, rmSync, writeFileSync, writeSync } from "node:fs";
+import { join } from "node:path";
 import { rebindPublicPruneProfile } from "./generation.ts";
 import { memoryGitArgv, memoryGitEnv, processLiveness, processSignature } from "./platform.ts";
 import { acquireMutation } from "./mutation.ts";
 import type { MemoryStore } from "./store.ts";
 import { syncGenerationMemory } from "./generation-sync.ts";
 import { outboundScreen, screenOutboundRows, screenOwnSegment, type RowScreen } from "./sync-screen.ts";
+import { shardSyncBinding } from "./sync-binding.ts";
 
 /**
  * #258 phase 2: hub memory between a person's machines through a git remote they configure. The memory directory is a
@@ -16,6 +18,8 @@ import { outboundScreen, screenOutboundRows, screenOwnSegment, type RowScreen }
  */
 export type Visibility = "public" | "private" | "unknown";
 export interface SyncResult { ok: boolean; pushed: boolean; entries: number; warning?: string; error?: string;
+  placementPublication?: { attemptHash?: string; outcome: "committed" | "unknown" | "not-needed"; withheld: number; exported: number;
+    lastPolicyHash?: string; lastPolicyCheckUnixMs?: number; policyCheckSource?: "live" | "durable-intent"; policyCeiling: "last-positive-check-before-in-flight-push"; recovered?: boolean };
   pruneApplication?: {transport:"durable"|"unconfirmed";proofComplete:number;projectionActive:number|null;nativeApplied:number|null;held:number;phase:"preflight"|"prepared"|"active"|"complete"};
 }
 
@@ -214,6 +218,8 @@ function lock(dir: string): (() => void) | undefined {
 }
 
 export interface SyncOptions {
+  /** Fresh compatibility facts for an already activated v3 profile; never activates a legacy profile or bypasses policy. */
+  placementAttestation?: PlacementCapturePort["attest"];
   /** Set (or replace) the remote first: a person's choice. */
   remote?: string;
   visibility?: (url: string) => Promise<Visibility>;
@@ -225,67 +231,13 @@ export interface SyncOptions {
   signal?: AbortSignal;
 }
 
-/** Metadata-only sharded sync epoch. Hash complete source bytes, never notes or unopened shards. */
-export function shardSyncBinding(store: MemoryStore): string { return captureShardSyncBinding(store, true); }
-/** Selection bytes may change only after this sync commits; source/policy identity remains pinned across that commit. */
-export function shardSyncSourceBinding(store: MemoryStore): string { return captureShardSyncBinding(store, false); }
-function captureShardSyncBinding(store: MemoryStore, selection: boolean): string {
-  const unavailable = (): never => { throw new Error("sharded sync binding unavailable"); };
-  if (!store.profile.sharded) return unavailable();
-  const uid = process.getuid?.(); if (uid === undefined) return unavailable();
-  const same = (a: BigIntStats, b: BigIntStats) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
-  const owned = (stat: BigIntStats, directory: boolean, privateMode = true) => {
-    if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1n)
-      || stat.uid !== BigInt(uid) || privateMode && (stat.mode & 0o077n) !== 0n) unavailable();
-  };
-  const home = store.profile.home, digest = createHash("sha256"), directories = new Map<string, BigIntStats>(), checks: (() => void)[] = [];
-  const emit = (value: unknown) => { digest.update(JSON.stringify(value) + "\n"); };
-  const directory = (dir: string): void => {
-    if (directories.has(dir)) return;
-    const rel = relative(home, dir); if (rel === ".." || rel.startsWith(".." + sep)) unavailable();
-    if (dir !== home) directory(dirname(dir));
-    const before = lstatSync(dir, { bigint: true }); owned(before, true); directories.set(dir, before);
-    emit(["directory", dir, String(before.dev), String(before.ino)]);
-    checks.push(() => { const now = lstatSync(dir, { bigint: true }); owned(now, true); if (!same(before, now)) unavailable(); });
-  };
-  // Policy config keeps its established file modes inside this already-private owned home. Its complete bytes/inode still bind the epoch.
-  const source = (file: string, privateMode = true): void => {
-    directory(dirname(file));
-    let before: BigIntStats;
-    try { before = lstatSync(file, { bigint: true }); }
-    catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-      emit(["source", file, "absent"]);
-      checks.push(() => { if (lstatSync(file, { bigint: true, throwIfNoEntry: false }) !== undefined) unavailable(); }); return;
-    }
-    owned(before, false, privateMode);
-    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-    try {
-      const opened = fstatSync(fd, { bigint: true }); owned(opened, false, privateMode); if (!same(before, opened)) unavailable();
-      const content = createHash("sha256"), buffer = Buffer.allocUnsafe(65_536); let bytes = 0n;
-      for (;;) { const n = readSync(fd, buffer, 0, buffer.length, null); if (!n) break; content.update(buffer.subarray(0, n)); bytes += BigInt(n); }
-      const after = fstatSync(fd, { bigint: true }); owned(after, false, privateMode);
-      if (bytes !== before.size || !same(before, after) || !same(before, lstatSync(file, { bigint: true }))) unavailable();
-      emit(["source", file, "present", String(before.dev), String(before.ino), String(before.size), String(before.mtimeNs), String(before.ctimeNs), content.digest("hex")]);
-    } finally { closeSync(fd); }
-    checks.push(() => { const now = lstatSync(file, { bigint: true }); owned(now, false, privateMode); if (!same(before, now)) unavailable(); });
-  };
-  try {
-    directory(home);
-    for (const name of [...(selection ? ["profile.json", "shards.json"] : []), "aliases.jsonl", "amem.config.json", "machine.json"]) source(join(home, name), name !== "amem.config.json");
-    const targets = [...store.openedSyncTargets()].sort((a, b) => a.dir.localeCompare(b.dir));
-    for (const target of targets) {
-      directory(target.dir);
-      emit(["target", target.dir, target.profile.generation ?? null, target.machine.id, target.profile.shardUser ?? false, target.profile.shardKey ?? null]);
-      for (const name of ["project.json", "generation.json", "generation-seal.json", "machine.json"]) source(join(target.dir, name));
-    }
-    for (const check of checks) check();
-    return digest.digest("hex");
-  } catch { return unavailable(); }
-}
+export { shardSyncBinding, shardSyncSourceBinding } from "./sync-binding.ts";
 
 export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Promise<SyncResult> {
   assertFormatFloor(store.profile.home, "sync");
+  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 (await import("./sync-placement-transport.ts")).syncPlacementMemory(store, opts);
   if (store.profile.sharded) {
     try {
       // Refresh only through the existing proved monotone profile rebind before pinning this attempt.
@@ -297,20 +249,23 @@ export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Pr
       assertBinding();
       const screen = outboundScreen(store.profile.home, opts.screen);
       const pass: RowScreen = row => { assertBinding(); const accepted = screen(row); assertBinding(); if (typeof accepted !== "boolean") throw new Error("invalid screen result"); return accepted; };
+      const errors: string[] = [];
       for (const target of store.openedSyncTargets()) {
         const screened = screenOutboundRows(target, pass); assertBinding();
-        if (!screened.ok) return { ok: false, pushed: false, entries: 0, error: screened.reason };
+        if (!screened.ok) errors.push(screened.reason);
       }
+      if (errors.length) return { ok: false, pushed: false, entries: 0, error: errors.join("; ") };
       const transport = await import("./shard-sync.ts"); assertBinding();
       return transport.syncShardedMemory(store, opts);
     } catch { return { ok: false, pushed: false, entries: 0, error: "sharded sync binding or policy unavailable or changed" }; }
   }
   // F4: before anything is staged or pushed, this machine's own long-term notes pass the person's configured policy (every profile: single log, generation, shards).
-  const pass = outboundScreen(store.profile.home, opts.screen);
+  const pass = outboundScreen(store.profile.home, opts.screen), errors: string[] = [];
   for (const target of store.openedSyncTargets()) {
     const screened = target.profile.kind === "generation" ? screenOutboundRows(target, pass) : screenOwnSegment(target.dir, target.machine.id, pass);
-    if (!screened.ok) return { ok: false, pushed: false, entries: 0, error: screened.reason };
+    if (!screened.ok) errors.push(screened.reason);
   }
+  if (errors.length) return { ok: false, pushed: false, entries: 0, error: errors.join("; ") };
   if (store.profile.kind === "generation") return syncGenerationMemory(store, opts);
   const dir = store.dir;
   const fail = (error: string): SyncResult => ({ ok: false, pushed: false, entries: 0, error });

package/src/setup.ts

@@ -10,11 +10,11 @@ import { JCODE_CAPTURE_EVENTS, putJcodeHooks } from "./setup-jcode.ts";
 const jcodeHookCommand = (bun: string, entry: string) => `${quote(bun)} --smol ${quote(entry)} hook jcode`;
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, renameSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, opendirSync, readFileSync, readSync, renameSync, rmdirSync, rmSync, writeFileSync, type BigIntStats } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { isDeepStrictEqual } from "node:util";
+import { isDeepStrictEqual, types } from "node:util";
 import { HOOK_EVENTS } from "./hook-contract.ts";
 import { memoryHome } from "./memory/home.ts";
 import { label, PLAIN, singleLine, type Style } from "./memory/style.ts";
@@ -209,20 +209,16 @@ function assertOpencodeLayout(c: ReturnType<typeof context>, mode: SetupPlan["mo
 }
 function intent(c: ReturnType<typeof context>, target: SetupTarget): string { return digest([1, target, c.paths[target], c.bun, c.entry, ...(["codex", "kimi", "qwen"].includes(target) ? ["capture-json-v1"] : []), ...(target === "jcode" ? ["jcode-hooks-v1"] : []), ...(["claude", "codex", "kimi", "pi", "qwen", "jcode"].includes(target) ? ["root-hooks-v2"] : []), ...(target === "agy" ? [c.workspace!.root] : [])]); }
 function journal(c: ReturnType<typeof context>, target: SetupTarget): string { return join(c.state, target === "agy" ? `agy-${digest(c.workspace!.root)}.json` : `${target}.json`); }
-function receipt(c: ReturnType<typeof context>, target: SetupTarget, requireRuntime = false): Receipt | undefined {
-  const raw = read(journal(c, target), JOURNAL_MAX); if (raw.bytes === null) return;
-  const value = record(JSON.parse(Buffer.from(raw.bytes, "base64").toString("utf8")));
+function decodeReceipt(value: Record<string, unknown>, target: SetupTarget, count: number, strict = false): Receipt {
+  if (strict && Object.keys(value).some(key => !["version", "target", "intent", "phase", "changes", "createdDirectory"].includes(key))) throw Error("setup receipt invalid");
   if (value.version !== 1 && value.version !== 2) throw Error("setup receipt version is unsupported; run setup or undo with the release that wrote it");
-  if (value.target !== target || typeof value.intent !== "string" || !/^[a-f0-9]{64}$/.test(value.intent) || requireRuntime && value.intent !== intent(c, target) || !["prepared", "applied"].includes(String(value.phase)) || !Array.isArray(value.changes) || value.changes.length !== c.paths[target].length && !(target === "jcode" && value.changes.length === 1)) throw Error("setup receipt does not match this installation");
+  if (value.target !== target || typeof value.intent !== "string" || !/^[a-f0-9]{64}$/.test(value.intent) || strict && value.intent.length !== 64 || !["prepared", "applied"].includes(String(value.phase)) || !Array.isArray(value.changes) || value.changes.length !== count && !(target === "jcode" && value.changes.length === 1)) throw Error("setup receipt does not match this installation");
   for (let i = 0; i < value.changes.length; i++) {
-    const change = record(value.changes[i]); const currentPath = c.paths[target][i], legacyRedirect = c.redirects.some(row => row.target === target && row.from === change.path && row.to === currentPath);
-    if (target === "claude" && i === 0 && typeof change.path === "string" && change.path !== currentPath && !legacyRedirect
-      && resolveSetupPaths({ ...c.env, CLAUDE_CONFIG_DIR: dirname(change.path) }, c.home).redirects.some(row => row.from === change.path && row.to === currentPath))
-      throw Error("setup receipt was written from an Orca Claude profile; rerun setup from that Orca profile");
-    if (change.path !== currentPath && !legacyRedirect || change.key !== `${target}:${i}`) throw Error("setup receipt target mismatch");
+    const change = record(value.changes[i]);
+    if (change.key !== `${target}:${i}` || strict && (Object.keys(change).some(key => !["key", "path", "before", "after", "start"].includes(key)) || typeof change.path !== "string" || !isAbsolute(change.path) || change.path.length > 4096 || change.path.includes("\0"))) throw Error("setup receipt target mismatch");
     for (const key of ["before", "after", ...(change.start !== undefined ? ["start"] : [])]) {
       const v = record(change[key]);
-      if (!Number.isInteger(v.mode) || Number(v.mode) < 0 || Number(v.mode) > 0o777 || v.bytes !== null && (typeof v.bytes !== "string" || v.bytes.length > 2 * MAX || Buffer.from(v.bytes, "base64").toString("base64") !== v.bytes)) throw Error("setup receipt invalid");
+      if (strict && Object.keys(v).sort().join() !== "bytes,mode" || !Number.isInteger(v.mode) || Number(v.mode) < 0 || Number(v.mode) > 0o777 || v.bytes !== null && (typeof v.bytes !== "string" || v.bytes.length > 2 * MAX || strict && (v.bytes.length > Math.ceil(MAX / 3) * 4 || v.bytes.length / 4 * 3 - (v.bytes.endsWith("==") ? 2 : v.bytes.endsWith("=") ? 1 : 0) > MAX) || Buffer.from(v.bytes, "base64").toString("base64") !== v.bytes)) throw Error("setup receipt invalid");
     }
   }
   if (value.createdDirectory !== undefined) {
@@ -231,6 +227,19 @@ function receipt(c: ReturnType<typeof context>, target: SetupTarget, requireRunt
   }
   return value as unknown as Receipt;
 }
+function receipt(c: ReturnType<typeof context>, target: SetupTarget, requireRuntime = false): Receipt | undefined {
+  const raw = read(journal(c, target), JOURNAL_MAX); if (raw.bytes === null) return;
+  const value = decodeReceipt(record(JSON.parse(Buffer.from(raw.bytes, "base64").toString("utf8"))), target, c.paths[target].length);
+  if (requireRuntime && value.intent !== intent(c, target)) throw Error("setup receipt does not match this installation");
+  for (let i = 0; i < value.changes.length; i++) {
+    const change = value.changes[i]!, currentPath = c.paths[target][i], legacyRedirect = c.redirects.some(row => row.target === target && row.from === change.path && row.to === currentPath);
+    if (target === "claude" && i === 0 && typeof change.path === "string" && change.path !== currentPath && !legacyRedirect
+      && resolveSetupPaths({ ...c.env, CLAUDE_CONFIG_DIR: dirname(change.path) }, c.home).redirects.some(row => row.from === change.path && row.to === currentPath))
+      throw Error("setup receipt was written from an Orca Claude profile; rerun setup from that Orca profile");
+    if (change.path !== currentPath && !legacyRedirect) throw Error("setup receipt target mismatch");
+  }
+  return value;
+}
 function plannedHooks(c: ReturnType<typeof context>, target: SetupTarget): PlannedHook[] {
   if (target === "jcode") return JCODE_CAPTURE_EVENTS.map(event => ({ event, command: jcodeHookCommand(c.bun, c.entry), timeout: 1 }));
   if (target === "opencode" || target === "gemini" || target === "agy") return [];
@@ -407,9 +416,14 @@ function previousRuntimes(target: SetupTarget, images: readonly Image[], bun: st
   return [...found.values()];
 }
 /** The runtime of a generated `<bun> --smol <entry> mcp` server record, if the record is exactly that shape. */
-function launcher(value: unknown): { bun: string; entry: string } | undefined {
+function launcher(value: unknown, target?: SetupTarget): { bun: string; entry: string } | undefined {
   if (!value || typeof value !== "object" || Array.isArray(value)) return;
-  const server = value as Record<string, unknown>, args = server.args;
+  const server = value as Record<string, unknown>;
+  if (target === "opencode") {
+    if (server.type !== "local" || !Array.isArray(server.command) || server.command.length !== 4) return;
+    return launcher({ command: server.command[0], args: server.command.slice(1) });
+  }
+  const args = server.args;
   return typeof server.command === "string" && isAbsolute(server.command) && Array.isArray(args) && args.length === 3
     && args[0] === "--smol" && typeof args[1] === "string" && isAbsolute(args[1]) && args[2] === "mcp" ? { bun: server.command, entry: args[1] } : undefined;
 }
@@ -720,3 +734,76 @@ export async function runSetup(target: string, mode: SetupPlan["mode"], options:
   const result = mode === "apply" ? applySetup(plan, options) : undoSetup(plan, options);
   return options.json ? JSON.stringify(result, null, 2) : setupResultText(result, s);
 }
+
+
+/** Fixed safe category only; receipt text, native paths and external error messages are never diagnostics. */
+export class SetupWriterRootsError extends Error {
+  readonly code = "setup_writer_roots_unavailable";
+  constructor(readonly category: "unsafe" | "changed" | "bound" | "unsupported" | "pending" | "unavailable") {
+    super(`Setup writer inventory ${category}; have the person inspect setup receipts and rerun setup before activation.`);
+    this.name = "SetupWriterRootsError";
+  }
+}
+/** Current managed MCP AFTER images only. Native configuration paths and historical BEFORE/START images are never opened. */
+export function readSetupWriterRoots(home: string): string[] {
+  function fail(category: SetupWriterRootsError["category"]): never { throw new SetupWriterRootsError(category); }
+  try {
+    const owned = (stat: BigIntStats) => { if (stat.isSymbolicLink() || stat.uid !== BigInt(process.getuid?.() ?? -1) || (stat.mode & 0o077n) !== 0n) fail("unsafe"); };
+    const stamp = (stat: BigIntStats) => JSON.stringify([stat.dev, stat.ino, stat.uid, stat.mode, stat.nlink, stat.size, stat.mtimeNs, stat.ctimeNs].map(String));
+    const base = lstatSync(home, { bigint: true, throwIfNoEntry: false }); if (!base) return []; owned(base); if (!base.isDirectory()) fail("unsafe");
+    const directory = join(home, "setup"), initial = lstatSync(directory, { bigint: true, throwIfNoEntry: false });
+    if (!initial) return [];
+    owned(initial); if (!initial.isDirectory()) fail("unsafe");
+    // ponytail:256 setup namespace entries and doctor's existing32MiB aggregate receipt-byte ceiling.
+    // A reviewed metadata-only setup inventory is required before increasing either ceiling.
+    const files: { name: string; stat: BigIntStats }[] = [], namespace: string[] = [], iterator = opendirSync(directory);
+    let entries = 0, totalBytes = 0;
+    try { for (;;) {
+      const entry = iterator.readSync(); if (!entry) break;
+      namespace.push(entry.name);
+      if (++entries > 256) fail("bound"); if (entry.name === "setup.lock") fail("pending");
+      if (!entry.name.endsWith(".json")) continue; // Retained .json.stale-* and unregistered temps are historical, never current authority.
+      const stat = lstatSync(join(directory, entry.name), { bigint: true }); owned(stat); if (!stat.isFile() || stat.nlink !== 1n) fail("unsafe");
+      if (stat.size > BigInt(JOURNAL_MAX) || totalBytes + Number(stat.size) > 32 * 1024 * 1024) fail("bound");
+      totalBytes += Number(stat.size); files.push({ name: entry.name, stat });
+    } } finally { iterator.closeSync(); }
+    const roots = new Set<string>(), launchers: { entry: string; root: string }[] = [];
+    for (const file of files.sort((a, b) => a.name.localeCompare(b.name))) {
+      const target = (file.name.startsWith("agy-") && /^agy-[a-f0-9]{64}\.json$/.test(file.name) ? "agy" : file.name.slice(0, -5)) as SetupTarget;
+      if (!SETUP_TARGETS.includes(target) || target === "agy" && !/^agy-[a-f0-9]{64}\.json$/.test(file.name)) fail("unsupported");
+      const path = join(directory, file.name), fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+      let text: string;
+      try {
+        const opened = fstatSync(fd, { bigint: true }); owned(opened); if (!opened.isFile() || opened.nlink !== 1n || stamp(opened) !== stamp(file.stat)) fail("changed");
+        const data = Buffer.alloc(Number(opened.size) + 1); let count = 0;
+        while (count < data.length) { const n = readSync(fd, data, count, data.length - count, count); if (!n) break; count += n; }
+        if (count !== Number(opened.size) || stamp(fstatSync(fd, { bigint: true })) !== stamp(opened) || stamp(lstatSync(path, { bigint: true })) !== stamp(opened)) fail("changed");
+        text = new TextDecoder("utf-8", { fatal: true }).decode(data.subarray(0, count));
+      } finally { closeSync(fd); }
+      const counts: Record<SetupTarget, number> = { claude: 2, codex: 2, kimi: 2, pi: 2, qwen: 1, jcode: 2, opencode: 1, gemini: 1, agy: 1 };
+      let value: Receipt;
+      try { value = decodeReceipt(record(JSON.parse(text)), target, counts[target], true); } catch { return fail("unsupported"); }
+      if (value.phase !== "applied") fail("pending");
+      const runtime = launcher(mcpRecord(target, value.changes[0]!.after), target);
+      if (!runtime || runtime.bun.includes("\0") || runtime.entry.length > 4096 || runtime.entry.includes("\0") || !["/bin/amem.js", "/src/cli.ts"].some(suffix => runtime.entry.endsWith(suffix))
+        || target === "opencode" && [runtime.bun, runtime.entry].some(value => /\{(?:env|file):/.test(value))) fail("unsupported");
+      const root = realPath(dirname(dirname(runtime.entry))); if (!lstatSync(root).isDirectory()) fail("unavailable");
+      roots.add(root); launchers.push({ entry: runtime.entry, root });
+    }
+    const finalHome = lstatSync(home, { bigint: true }); owned(finalHome);
+    if (!finalHome.isDirectory() || stamp(lstatSync(directory, { bigint: true })) !== stamp(initial) || finalHome.dev !== base.dev || finalHome.ino !== base.ino) fail("changed");
+    const finalNames: string[] = [], finalDirectory = opendirSync(directory);
+    try { for (;;) { const entry = finalDirectory.readSync(); if (!entry) break; if (finalNames.length >= namespace.length) fail("changed"); finalNames.push(entry.name); } }
+    finally { finalDirectory.closeSync(); }
+    if (JSON.stringify(finalNames.sort()) !== JSON.stringify(namespace.sort())) fail("changed");
+    for (const file of files) if (stamp(lstatSync(join(directory, file.name), { bigint: true })) !== stamp(file.stat)) fail("changed");
+    for (const runtime of launchers) if (realPath(dirname(dirname(runtime.entry))) !== runtime.root) fail("changed");
+    return [...roots].sort();
+  } catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error) && error instanceof SetupWriterRootsError) {
+      const category = Object.getOwnPropertyDescriptor(error, "category");
+      if (category && "value" in category && ["unsafe", "changed", "bound", "unsupported", "pending", "unavailable"].includes(category.value)) throw new SetupWriterRootsError(category.value);
+    }
+    throw new SetupWriterRootsError("unavailable");
+  }
+}