@staix/agent-mem 0.21.0 → 0.22.0

package/src/memory/sync-placement-writer-roots.ts

@@ -0,0 +1,167 @@
+/** Immutable initial install locator only. Returned paths are never fresh compatibility or quiescence evidence. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { types } from "node:util";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { memoryPolicySnapshot } from "./policy.ts";
+import { realPath } from "./platform.ts";
+import { assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { readPlacementRuntimeMarkers } from "./sync-placement-guard.ts";
+import { readActivePlacementBinding } from "./sync-placement-active.ts";
+import { readPlacementJournal } from "./sync-placement-journal-storage.ts";
+import { writeImmutableActivationMetadata } from "./public-prune-activation.ts";
+import { measureSyncPlacementWriters, SyncPlacementWriterError, type MeasuredSyncPlacementWriterRoot } from "./sync-placement-writers.ts";
+import { PLACEMENT_FORMAT } from "./sync-placement-format.ts";
+import type { SyncPlacementWriterAttestation } from "./sync-placement-plan.ts";
+
+export const SYNC_PLACEMENT_WRITER_ROOTS_FILE="sync-placement-writer-roots.json";
+export const SYNC_PLACEMENT_WRITER_ROOTS_SCHEMA="agent-mem.sync-placement-writer-roots/v1";
+interface LocatorBody {
+  schema:typeof SYNC_PLACEMENT_WRITER_ROOTS_SCHEMA;homeHash:string;epochHash:string;activationHash:string;
+  roots:{root:string;writerId:string}[];
+}
+export interface InitialSyncPlacementWriterLocator extends LocatorBody {seal:string}
+type Locator=InitialSyncPlacementWriterLocator;
+const MAX_BYTES=256*1024,MAX_ROOTS=256,MAX_PATH=4096;
+const hash=(text:string)=>createHash("sha256").update(text).digest("hex");
+const hex=(value:unknown):value is string=>typeof value==="string"&&value.length===64&&/^[a-f0-9]+$/.test(value);
+const stamp=(s:BigIntStats)=>[s.dev,s.ino,s.mode,s.uid,s.nlink,s.size,s.mtimeNs,s.ctimeNs].map(String).join(":");
+function fail():never {throw new SyncPlacementWriterError("unavailable");}
+function protectedCall<T>(work:()=>T):T {try{return work();}catch(error){
+  if(error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof SyncPlacementWriterError){const code=Object.getOwnPropertyDescriptor(error,"code");if(code&&"value"in code&&code.value==="bound")throw new SyncPlacementWriterError("bound");}
+  return fail();
+}}
+function directory(home:string):BigIntStats {
+  const s=lstatSync(home,{bigint:true});
+  if(!s.isDirectory()||s.isSymbolicLink()||s.uid!==BigInt(process.getuid?.()??-1)||(s.mode&0o777n)!==0o700n)fail();return s;
+}
+function fileState(file:string):BigIntStats {
+  const s=lstatSync(file,{bigint:true});
+  if(!s.isFile()||s.isSymbolicLink()||s.uid!==BigInt(process.getuid?.()??-1)||(s.mode&0o777n)!==0o600n
+    ||s.nlink!==1n&&s.nlink!==2n||s.size<1n||s.size>BigInt(MAX_BYTES))fail();return s;
+}
+function object(input:unknown,keys:readonly string[]):Record<string,unknown> {
+  if(!input||typeof input!=="object"||types.isProxy(input)||Array.isArray(input)||![Object.prototype,null].includes(Object.getPrototypeOf(input))||Object.getOwnPropertySymbols(input).length)fail();
+  const fields=Object.getOwnPropertyDescriptors(input);if(Object.keys(fields).sort().join()!==[...keys].sort().join())fail();
+  const out:Record<string,unknown>=Object.create(null);
+  for(const key of keys){const field=fields[key];if(!field||!("value"in field)||!field.enumerable)fail();out[key]=field.value;}return out;
+}
+function array(input:unknown):unknown[] {
+  if(!input||typeof input!=="object"||types.isProxy(input)||!Array.isArray(input)||Object.getPrototypeOf(input)!==Array.prototype||Object.getOwnPropertySymbols(input).length)fail();
+  const fields=Object.getOwnPropertyDescriptors(input),length=Object.getOwnPropertyDescriptor(input,"length")?.value;
+  if(!Number.isSafeInteger(length)||length<1||length>MAX_ROOTS||Object.keys(fields).length!==length+1)fail();
+  const out:unknown[]=[];for(let i=0;i<length;i++){const field=fields[String(i)];if(!field||!("value"in field)||!field.enumerable)fail();out.push(field.value);}return out;
+}
+function validate(input:unknown):Locator {
+  const value=object(input,["schema","homeHash","epochHash","activationHash","roots","seal"]);
+  if(value.schema!==SYNC_PLACEMENT_WRITER_ROOTS_SCHEMA||!hex(value.homeHash)||!hex(value.epochHash)||!hex(value.activationHash)||!hex(value.seal)
+    )fail();
+  const roots:{root:string;writerId:string}[]=[],ids=new Set<string>();let prior="";
+  for(const entry of array(value.roots)){
+    const item=object(entry,["root","writerId"]);
+    if(typeof item.root!=="string"||!isAbsolute(item.root)||resolve(item.root)!==item.root||Buffer.byteLength(item.root)>MAX_PATH||item.root.includes("\0")
+      ||item.root<=prior||!hex(item.writerId)||ids.has(item.writerId))fail();
+    roots.push({root:item.root,writerId:item.writerId});prior=item.root;ids.add(item.writerId);
+  }
+  const body:LocatorBody={schema:SYNC_PLACEMENT_WRITER_ROOTS_SCHEMA,homeHash:value.homeHash,epochHash:value.epochHash,activationHash:value.activationHash,roots};
+  if(hashJSON(body)!==value.seal)fail();
+  if(Buffer.byteLength(canonicalJSON(value)+"\n")>MAX_BYTES)throw new SyncPlacementWriterError("bound");
+  return{...body,seal:value.seal};
+}
+function idSet(writers:readonly SyncPlacementWriterAttestation[]):string[] {
+  const copy=memoryPolicySnapshot(writers);if(!Array.isArray(copy)||copy.length<1||copy.length>MAX_ROOTS)fail();
+  const ids=copy.map(writer=>{if(!writer||typeof writer!=="object"||!hex(writer.writerId))fail();return writer.writerId;}).sort();
+  if(new Set(ids).size!==ids.length)fail();return ids;
+}
+function bind(value:Locator,expected:{homeHash:string;epochHash:string;activationHash:string},writers:readonly SyncPlacementWriterAttestation[]):void {
+  if(value.homeHash!==expected.homeHash||value.epochHash!==expected.epochHash||value.activationHash!==expected.activationHash
+    ||canonicalJSON(value.roots.map(root=>root.writerId).sort())!==canonicalJSON(idSet(writers)))fail();
+}
+function readOwned(file:string):{text:string;check():void} {
+  const before=fileState(file),fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+  try{
+    if(stamp(fstatSync(fd,{bigint:true}))!==stamp(before))fail();
+    const data=Buffer.alloc(Number(before.size)+1);let at=0;
+    while(at<data.length){const count=readSync(fd,data,at,data.length-at,at);if(!count)break;at+=count;}
+    if(at!==Number(before.size)||stamp(fstatSync(fd,{bigint:true}))!==stamp(before)||stamp(fileState(file))!==stamp(before))fail();
+    const text=new TextDecoder("utf-8",{fatal:true}).decode(data.subarray(0,at)),companion=`${file}.pending-${hash(text)}`;
+    const paired=lstatSync(companion,{bigint:true,throwIfNoEntry:false});
+    if(before.nlink===2n){const peer=fileState(companion);if(peer.dev!==before.dev||peer.ino!==before.ino||stamp(peer)!==stamp(before))fail();}
+    else if(paired)fail();
+    return{text,check(){if(stamp(fileState(file))!==stamp(before))fail();
+      const now=lstatSync(companion,{bigint:true,throwIfNoEntry:false});
+      if(paired? !now||stamp(fileState(companion))!==stamp(paired):!!now)fail();}};
+  }finally{closeSync(fd);}
+}
+export interface SyncPlacementWriterRootsInput {epochHash:string;homeHash:string;activationHash:string;roots:readonly MeasuredSyncPlacementWriterRoot[]}
+export interface SyncPlacementWriterRootsBinding {homeHash:string;epochHash:string;activationHash:string;writers:readonly SyncPlacementWriterAttestation[]}
+function copiedInput(input:SyncPlacementWriterRootsInput) {
+  const copied=object(input,["epochHash","homeHash","activationHash","roots"]);
+  if(!hex(copied.epochHash)||!hex(copied.homeHash)||!hex(copied.activationHash))fail();
+  const roots=array(copied.roots).map(value=>{
+    const root=object(value,["root","writerId","version","pin"]);
+    if(typeof root.root!=="string"||typeof root.version!=="string"||!hex(root.writerId)||!hex(root.pin))fail();
+    return{root:root.root,writerId:root.writerId,version:root.version,pin:root.pin};
+  }).sort((a,b)=>a.root<b.root?-1:a.root>b.root?1:0);
+  return{homeHash:copied.homeHash,epochHash:copied.epochHash,activationHash:copied.activationHash,roots};
+}
+/** Pure initial-locator data plan. It proves framing/binding/bounds only, never fresh install bytes or permission. */
+export function planSyncPlacementWriterRoots(input:SyncPlacementWriterRootsInput,binding:SyncPlacementWriterRootsBinding):Locator {
+  return protectedCall(()=>{
+    const copied=copiedInput(input),expected=object(binding,["homeHash","epochHash","activationHash","writers"]);
+    if(!hex(expected.homeHash)||!hex(expected.epochHash)||!hex(expected.activationHash))fail();
+    const writers=memoryPolicySnapshot(expected.writers) as readonly SyncPlacementWriterAttestation[]|undefined;if(!writers)fail();idSet(writers);
+    const proposed=copied.roots.map(({writerId,version,pin})=>({writerId,version,pin,publicationFormat:PLACEMENT_FORMAT,compatible:true})).sort((a,b)=>a.writerId.localeCompare(b.writerId));
+    if(canonicalJSON(proposed)!==canonicalJSON([...writers].sort((a,b)=>a.writerId.localeCompare(b.writerId))))fail();
+    const body:LocatorBody={schema:SYNC_PLACEMENT_WRITER_ROOTS_SCHEMA,homeHash:copied.homeHash,epochHash:copied.epochHash,activationHash:copied.activationHash,
+      roots:copied.roots.map(({root,writerId})=>({root,writerId}))};
+    const value=validate({...body,seal:hashJSON(body)});
+    bind(value,{homeHash:expected.homeHash,epochHash:expected.epochHash,activationHash:expected.activationHash},writers);return value;
+  });
+}
+export interface SyncPlacementWriterRootsWriteOptions {mutation:MutationHandle;assertCurrent():void}
+/** Called only under activation's live fences. Initial bytes are immutable; renewal belongs to its own reviewed protocol. */
+export function writeSyncPlacementWriterRoots(homeInput:string,input:SyncPlacementWriterRootsInput,expectedWriters:readonly SyncPlacementWriterAttestation[],options:SyncPlacementWriterRootsWriteOptions):void {
+  protectedCall(()=>{
+    const home=realPath(homeInput),before=directory(home);assertMutationHandle(options.mutation,home);options.assertCurrent();
+    const copied=copiedInput(input),roots=copied.roots;
+    const measured=measureSyncPlacementWriters(roots.map(root=>root.root));
+    if(canonicalJSON(measured.roots)!==canonicalJSON(roots.sort((a,b)=>a.root<b.root?-1:a.root>b.root?1:0)))fail();
+    const journal=readPlacementJournal(home,copied.epochHash),expected=memoryPolicySnapshot(expectedWriters);
+    if(!expected||!Array.isArray(expected))fail();idSet(expected);
+    const sorted=(writers:readonly SyncPlacementWriterAttestation[])=>[...writers].sort((a,b)=>a.writerId.localeCompare(b.writerId));
+    if(canonicalJSON(sorted(measured.writers))!==canonicalJSON(sorted(expected))||canonicalJSON(sorted(measured.writers))!==canonicalJSON(sorted(journal.activation.writers)))fail();
+    const value=planSyncPlacementWriterRoots({...copied,roots:measured.roots},{homeHash:journal.epoch.homeHash,epochHash:hashJSON(journal.epoch),activationHash:journal.activation.seal,writers:journal.activation.writers});
+    if(canonicalJSON(idSet(expected))!==canonicalJSON(idSet(journal.activation.writers)))fail();
+    assertMutationHandle(options.mutation,home);options.assertCurrent();
+    const file=join(home,SYNC_PLACEMENT_WRITER_ROOTS_FILE),text=canonicalJSON(value)+"\n";
+    const existing=lstatSync(file,{throwIfNoEntry:false});if(existing){const read=readOwned(file);if(read.text!==text)fail();read.check();}
+    // The shared writer reads a crash-left orphan before its own content check. Bound that read here,
+    // after the final caller proof; only its exact deterministic staging name can be resumed.
+    const staging=lstatSync(`${file}.pending-${hash(text)}`,{bigint:true,throwIfNoEntry:false});
+    if(staging){
+      if(!staging.isFile()||staging.isSymbolicLink()||staging.uid!==BigInt(process.getuid?.()??-1)||(staging.mode&0o777n)!==0o600n||staging.size>BigInt(MAX_BYTES))fail();
+      if(existing){const final=fileState(file);if(final.nlink!==2n||staging.nlink!==2n||stamp(staging)!==stamp(final))fail();}
+      else if(staging.nlink!==1n)fail();
+    }
+    writeImmutableActivationMetadata(file,text);
+    assertMutationHandle(options.mutation,home);options.assertCurrent();
+    const after=directory(home);if(after.dev!==before.dev||after.ino!==before.ino)fail();
+    const read=readOwned(file);if(read.text!==text)fail();read.check();
+  });
+}
+/** Returns only initial locator paths; the caller must independently remeasure their actual bytes at each attestation. */
+export function readInitialSyncPlacementWriterLocator(homeInput:string):InitialSyncPlacementWriterLocator {
+  return protectedCall(()=>{
+    const home=realPath(homeInput),before=directory(home);
+    const active=()=>{const markers=readPlacementRuntimeMarkers(home),value=readActivePlacementBinding(home,markers.profile,markers.shards);if(!value)fail();return value;};
+    const initial=active(),read=readOwned(join(home,SYNC_PLACEMENT_WRITER_ROOTS_FILE)),value=validate(JSON.parse(read.text));
+    if(canonicalJSON(value)+"\n"!==read.text)fail();
+    bind(value,{homeHash:initial.epoch.homeHash,epochHash:initial.profile.placementHead,activationHash:initial.activation.seal},initial.activation.writers);
+    const final=active();if(canonicalJSON(final)!==canonicalJSON(initial))fail();
+    const after=directory(home);if(after.dev!==before.dev||after.ino!==before.ino)fail();read.check();
+    return value;
+  });
+}
+export function readSyncPlacementWriterRoots(homeInput:string):string[]{return readInitialSyncPlacementWriterLocator(homeInput).roots.map(root=>root.root);}

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

@@ -0,0 +1,135 @@
+/** Read-only install measurement. Pins are exact-byte facts, not person authority or host quiescence. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync, type BigIntStats } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { types } from "node:util";
+import { hashJSON } from "./generation.ts";
+import { realPath } from "./platform.ts";
+import { PLACEMENT_FORMAT } from "./sync-placement-format.ts";
+import type { SyncPlacementWriterAttestation } from "./sync-placement-plan.ts";
+
+export interface MeasuredSyncPlacementWriterRoot { root: string; writerId: string; version: string; pin: string }
+export interface SyncPlacementWriterMeasurement { roots: MeasuredSyncPlacementWriterRoot[]; writers: SyncPlacementWriterAttestation[] }
+export type SyncPlacementWriterErrorCode = "invalid" | "unavailable" | "unsupported" | "bound" | "changed";
+const causes: Record<SyncPlacementWriterErrorCode,string> = {
+  invalid:"invalid or duplicate writer-root inventory",unavailable:"unreadable or unsafe writer-root runtime files",
+  unsupported:"unsupported writer-root package identity or release",bound:"writer-root inventory exceeds its supported bound",changed:"writer-root changed during measurement",
+};
+export type SyncPlacementWriterFailureDetail = "below-minimum" | "wrong-package" | "writable-runtime" | "unreadable" | "invalid-version" | "invalid-inventory" | "unsafe-runtime" | "missing-runtime" | "bound" | "changed";
+const details:Record<SyncPlacementWriterFailureDetail,string>={
+  "below-minimum":"release is below 0.21.0", "wrong-package":"package is not @staix/agent-mem", "writable-runtime":"runtime code is group- or world-writable",
+  unreadable:"runtime files are unreadable or missing", "invalid-version":"package version is not a supported plain release", "invalid-inventory":"root inventory is invalid or duplicated",
+  "unsafe-runtime":"runtime files have unsafe types or symlinks", "missing-runtime":"required bin/amem.js or src/index.ts is missing",bound:"inventory exceeds a supported bound",changed:"install changed during measurement",
+};
+export class SyncPlacementWriterError extends Error {
+  constructor(readonly code: SyncPlacementWriterErrorCode, readonly rootIndex?: number, readonly detail:SyncPlacementWriterFailureDetail=code==="unsupported"?"invalid-version":code==="invalid"?"invalid-inventory":code==="bound"?"bound":code==="changed"?"changed":"unreadable") {
+    super(`Sync placement ${causes[code]} (${details[detail]}); upgrade or repair the amem install and its host exact pin, then rerun amem migrate --sync-placement --dry-run. For a managed writer, rerun amem setup <target> --apply after upgrading.`);
+    this.name="SyncPlacementWriterError";
+  }
+}
+/** Closed own data only: external error messages, accessors and proxies are never diagnostic authority. */
+export function extractSyncPlacementWriterFailure(error:unknown):{code:SyncPlacementWriterErrorCode;detail:SyncPlacementWriterFailureDetail;rootIndex?:number}|undefined {
+  try{
+    if(!error||typeof error!=="object"||types.isProxy(error)||!(error instanceof SyncPlacementWriterError))return;
+    const fields=Object.getOwnPropertyDescriptors(error),code=fields.code?.value,detail=fields.detail?.value,index=fields.rootIndex;
+    if(typeof code!=="string"||!Object.hasOwn(causes,code)||typeof detail!=="string"||!Object.hasOwn(details,detail)
+      ||index&&!("value"in index))return;
+    const rootIndex=index?.value;if(rootIndex!==undefined&&(!Number.isSafeInteger(rootIndex)||rootIndex<0||rootIndex>=256))return;
+    return{code:code as SyncPlacementWriterErrorCode,detail:detail as SyncPlacementWriterFailureDetail,...(rootIndex===undefined?{}:{rootIndex})};
+  }catch{return;}
+}
+const MAX_ROOTS=256,MAX_FILES=4096,MAX_BYTES=64*1024*1024,MAX_PACKAGE=64*1024,MAX_PATH=4096,MAX_NODES=8192;
+// ponytail: namespace traversal also caps 8192 entries and depth64; larger installs need a reviewed chunked inventory.
+const RUNTIME=["src","bin","hooks",".claude-plugin"] as const;
+const stamp=(s:BigIntStats)=>[s.dev,s.ino,s.mode,s.uid,s.gid,s.nlink,s.size,s.mtimeNs,s.ctimeNs].map(String).join(":");
+const digest=(bytes:Uint8Array)=>createHash("sha256").update(bytes).digest("hex");
+
+/** Internal frozen-locator identity; callers validate canonical paths before treating it as a writer key. */
+export function syncPlacementWriterId(root:string):string {return hashJSON(["agent-mem.sync-placement-writer/v1",root]);}
+
+export function measureSyncPlacementWriters(input:readonly string[]):SyncPlacementWriterMeasurement {
+  let index:number|undefined;
+  function fail(code:SyncPlacementWriterErrorCode,detail?:SyncPlacementWriterFailureDetail):never {throw new SyncPlacementWriterError(code,index,detail);}
+  if(!input||typeof input!=="object"||types.isProxy(input)||!Array.isArray(input)||Object.getPrototypeOf(input)!==Array.prototype
+    ||input.length<1||Object.getOwnPropertySymbols(input).length)fail("invalid");
+  if(input.length>MAX_ROOTS)fail("bound");
+  const fields=Object.getOwnPropertyDescriptors(input);
+  if(Object.keys(fields).length!==input.length+1)fail("invalid");
+  const requested:string[]=[],seen=new Set<string>(),checks:(()=>void)[]=[],namespaces:(()=>void)[]=[],measured:MeasuredSyncPlacementWriterRoot[]=[];
+  let files=0,bytes=0,nodes=0;
+  const rememberCheck=(check:()=>void)=>{const rootIndex=index;checks.push(()=>{index=rootIndex;check();});};
+  try {
+    const node=(file:string,directory:boolean):BigIntStats=>{
+      const s=lstatSync(file,{bigint:true});
+      // Public installs may be readable by everyone and share Bun's hardlinked cache. Writeable code is unsafe.
+      if(s.isSymbolicLink()||(directory?!s.isDirectory():!s.isFile()))fail("unavailable","unsafe-runtime");
+      if((s.mode&0o022n)!==0n)fail("unavailable","writable-runtime");
+      return s;
+    };
+    for(index=0;index<input.length;index++){
+      const field=fields[String(index)];if(!field||!("value"in field)||!field.enumerable)fail("invalid");
+      const value:unknown=field.value;
+      if(typeof value!=="string"||!isAbsolute(value)||Buffer.byteLength(value)>MAX_PATH||value.includes("\0"))fail("invalid");
+      requested.push(value);
+    }
+    for(index=0;index<requested.length;index++){
+      const requestedRoot=requested[index]!,root=realPath(requestedRoot);
+      if(Buffer.byteLength(root)>MAX_PATH||seen.has(root))fail("invalid");seen.add(root);
+      const rootStat=node(root,true),inventory:[string,string][]=[];
+      rememberCheck(()=>{if(realPath(requestedRoot)!==root||stamp(node(root,true))!==stamp(rootStat))fail("changed");});
+      const remember=(file:string,before:BigIntStats,directory:boolean)=>rememberCheck(()=>{if(stamp(node(file,directory))!==stamp(before))fail("changed");});
+      const path=(relative:string)=>{if(Buffer.byteLength(relative)>MAX_PATH||Buffer.byteLength(join(root,relative))>MAX_PATH)fail("bound");return join(root,relative);};
+      const read=(relative:string,maximum:number):Buffer=>{
+        const file=path(relative),before=node(file,false);
+        if(++files>MAX_FILES||before.size>BigInt(maximum)||before.size>BigInt(MAX_BYTES-bytes))fail("bound");
+        const fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+        try{
+          if(stamp(fstatSync(fd,{bigint:true}))!==stamp(before))fail("changed");
+          const data=Buffer.alloc(Number(before.size));let at=0;
+          while(at<data.length){const count=readSync(fd,data,at,data.length-at,at);if(count<=0)fail("changed");at+=count;}
+          if(stamp(fstatSync(fd,{bigint:true}))!==stamp(before)||stamp(node(file,false))!==stamp(before))fail("changed");
+          bytes+=data.length;inventory.push([relative,digest(data)]);remember(file,before,false);return data;
+        }finally{closeSync(fd);}
+      };
+      const visit=(relative:string,depth=0)=>{
+        if(depth>64)fail("bound");
+        const file=path(relative),before=node(file,true),names:string[]=[];remember(file,before,true);
+        const dir=opendirSync(file);
+        try{for(;;){const entry=dir.readSync();if(!entry)break;if(++nodes>MAX_NODES)fail("bound");names.push(entry.name);}}finally{dir.closeSync();}
+        if(stamp(node(file,true))!==stamp(before))fail("changed");
+        const rootIndex=index;
+        namespaces.push(()=>{
+          index=rootIndex;const current:string[]=[],reader=opendirSync(file);
+          try{for(;;){const entry=reader.readSync();if(!entry)break;if(current.length>=names.length)fail("changed");current.push(entry.name);}}finally{reader.closeSync();}
+          if(JSON.stringify(current.sort())!==JSON.stringify(names))fail("changed");
+        });
+        for(const name of names.sort()){
+          const child=`${relative}/${name}`,s=lstatSync(path(child),{bigint:true});
+          if(s.isSymbolicLink())fail("unavailable","unsafe-runtime");
+          if(s.isDirectory())visit(child,depth+1);else read(child,MAX_BYTES);
+        }
+      };
+      const packageBytes=read("package.json",MAX_PACKAGE);let pkg:unknown;
+      try{pkg=JSON.parse(new TextDecoder("utf-8",{fatal:true}).decode(packageBytes));}catch(error){if(error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof SyncPlacementWriterError)throw error;fail("unsupported");}
+      const version=pkg&&typeof pkg==="object"&&!Array.isArray(pkg)?Object.getOwnPropertyDescriptor(pkg,"version")?.value:undefined;
+      const name=pkg&&typeof pkg==="object"?Object.getOwnPropertyDescriptor(pkg,"name")?.value:undefined;
+      const match=typeof version==="string"&&version.length<=64?/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(version):null;
+      if(name!=="@staix/agent-mem")fail("unsupported","wrong-package");
+      if(!match||match[0]!==version)fail("unsupported","invalid-version");
+      const parts=match.slice(1).map(Number);if(!parts.every(Number.isSafeInteger))fail("unsupported","invalid-version");
+      if(parts[0]===0&&parts[1]!<21)fail("unsupported","below-minimum");
+      for(const relative of RUNTIME){
+        const file=path(relative),s=lstatSync(file,{bigint:true,throwIfNoEntry:false});
+        if(s)visit(relative);else rememberCheck(()=>{if(lstatSync(file,{throwIfNoEntry:false}))fail("changed");});
+      }
+      if(!inventory.some(([file])=>file==="bin/amem.js")||!inventory.some(([file])=>file==="src/index.ts"))fail("unsupported","missing-runtime");
+      inventory.sort(([a],[b])=>a<b?-1:a>b?1:0);
+      measured.push({root,writerId:syncPlacementWriterId(root),version:version as string,pin:hashJSON(inventory)});
+    }
+    for(const check of checks)check();
+    for(const check of namespaces)check();
+    measured.sort((a,b)=>a.root<b.root?-1:a.root>b.root?1:0);
+    const writers=measured.map<SyncPlacementWriterAttestation>(({writerId,version,pin})=>({writerId,version,pin,publicationFormat:PLACEMENT_FORMAT,compatible:true})).sort((a,b)=>a.writerId.localeCompare(b.writerId));
+    return{roots:measured,writers};
+  }catch(error){if(error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof SyncPlacementWriterError)throw error;return fail("unavailable");}
+}

package/src/memory/sync.ts

@@ -1,4 +1,3 @@
-import { syncPlacementMemory } from "./sync-placement-transport.ts";
 import type { PlacementCapturePort } from "./sync-placement-capture.ts";
 import { placementRuntimeRefusal } from "./sync-placement-guard.ts";
 import { assertFormatFloor } from "./formats.ts";
@@ -238,7 +237,7 @@ export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Pr
   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 syncPlacementMemory(store, opts);
+  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.

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");
+  }
+}