@staix/agent-mem 0.22.0 → 0.22.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "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.22.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.22.1. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,10 @@
     "@staix/agent-mem-v013": "npm:@staix/agent-mem@0.13.0",
     "@staix/agent-mem-v015": "npm:@staix/agent-mem@0.15.0",
     "@staix/agent-mem-v017": "npm:@staix/agent-mem@0.17.0",
-    "@staix/agent-mem-v018": "npm:@staix/agent-mem@0.18.0"
+    "@staix/agent-mem-v018": "npm:@staix/agent-mem@0.18.0",
+    "bun-types-host-1-4-2": "npm:bun-types@1.4.2",
+    "@staix/agent-mem-v0220": "npm:@staix/agent-mem@0.22.0",
+    "@types/bun-host-1-4-2": "npm:@types/bun@1.4.2"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/cli-agent-reads.ts

@@ -1,6 +1,7 @@
 import { noteDisplayActor } from "./memory/cli-attribution.ts";
 import { singleLine } from "./memory/style.ts";
 import { createMemoryMcp } from "./mcp-memory.ts";
+import { safeProfileLockMessage } from "./memory/profile-lock-diagnostic.ts";
 import { memoryHome } from "./memory/home.ts";
 import type { ParsedCommand } from "./commands-table.ts";
 
@@ -111,7 +112,8 @@ export async function agentCliRead(
       return shown;
     }
     return output;
-  } catch {
+  } catch (error) {
+    if(safeProfileLockMessage(error))throw error;
     throw new Error(UNAVAILABLE);
   } finally {
     try { memory?.close(); } catch { /* close failures do not expose partial reads */ }

package/src/cli.ts

@@ -12,6 +12,7 @@ import { createRecallStalenessProbe } from "./memory/recall-staleness.ts";
 import { recordMemoryUse } from "./memory/use-telemetry.ts";
 import { DecayApplyError } from "./memory/decay-review.ts";
 import { createMemoryMcp } from "./mcp-memory.ts";
+import { safeProfileLockMessage } from "./memory/profile-lock-diagnostic.ts";
 import { MCP_TOOLS, serveMcp, writeConfirmed } from "./mcp.ts";
 import { createStandalonePolicy } from "./memory/policy.ts";
 import { configuredPolicy, configuredPolicyOptions, loadAmemConfig, repoConfigRoot } from "./memory/config.ts";
@@ -314,6 +315,7 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     }
     // Data-free errors (decided before any store or file is opened) keep their own message.
     if (marked && error instanceof AgentUsageError) throw error;
+    const recovery=marked?safeProfileLockMessage(error):undefined;if(recovery)throw new Error(recovery);
     if (marked) {
       // parseCommand is pure: when it rejects argv, the error it raised is a usage error, not memory data.
       let usage: Error | undefined, parsed: ReturnType<typeof parseCommand> | undefined;

package/src/memory/generation.ts

@@ -9,6 +9,7 @@ import { dirname, join } from "node:path";
 import { canonicalPath, processLiveness, processSignature, realPath } from "./platform.ts";
 import { shardDir, userShardDir } from "./shard.ts";
 import { readPublicPruneInputSetChain } from "./public-prune-input-chain.ts";
+import { profileLockRecoveryError, safeProfileLockMessage } from "./profile-lock-diagnostic.ts";
 
 export interface BoundProfile {
   kind: "shared-v1" | "generation";
@@ -96,12 +97,14 @@ export function readSelector(memoryDir: string, absoluteDeadline?: number): { se
       const current = readProfileJSON(join(memoryDir, "profile.json"));
       if (result.revision === (current === undefined ? "absent" : hashJSON(current))) return result;
     } catch (error) {
-      if (error instanceof SyncPlacementRuntimeError) throw error;
-      if (error instanceof Error && error.message === "public prune view unavailable") throw error; // A spent wait budget is never restarted.
+      if (safeProfileLockMessage(error)) throw error;
+      if (error instanceof SyncPlacementRuntimeError) throw profileLockRecoveryError(memoryDir) ?? error;
+      if (error instanceof Error && error.message === "public prune view unavailable") throw profileLockRecoveryError(memoryDir) ?? error; // A spent wait budget is never restarted.
       if (!lstatSync(join(memoryDir, PUBLIC_PRUNE_INTENT), { throwIfNoEntry: false }) && !lstatSync(join(memoryDir, "profile.lock"), { throwIfNoEntry: false })) throw error;
-      waitForPublicPruneWriter(memoryDir, deadline);
+      try { waitForPublicPruneWriter(memoryDir, deadline); } catch (failure) { throw profileLockRecoveryError(memoryDir) ?? failure; }
     }
   }
+  const diagnostic=profileLockRecoveryError(memoryDir);if(diagnostic)throw diagnostic;
   return unavailable();
 }
 

package/src/memory/profile-lock-diagnostic.ts

@@ -0,0 +1,69 @@
+/** Read-only error hints, never admission, recovery or proof that an owner is dead. */
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync, type BigIntStats } from "node:fs";
+import { join } from "node:path";
+import { realPath } from "./platform.ts";
+
+const messages={
+  shards:"An interrupted or still-running person shard migration retains profile.lock; have the person finish it or run amem migrate --shards --resume.",
+  prune:"An interrupted or still-running person public-prune view migration retains profile.lock; have the person finish it or run amem migrate --public-prune-view --resume.",
+  activation:"An interrupted or still-running person sync-placement activation retains profile.lock; have the person run amem migrate --sync-placement --resume, or amem migrate --sync-placement --abandon only while both markers retain their original v2 bytes.",
+  renewal:"An interrupted or still-running person writer-inventory renewal retains profile.lock; have the person run amem migrate --sync-placement --resume, or amem migrate --sync-placement --abandon only before the first commit-log byte.",
+  staging:"An interrupted or still-running person writer-inventory renewal retains profile.lock and unpublished intent staging; have the person run amem migrate --sync-placement --abandon, then amem migrate --sync-placement --dry-run before another apply.",
+} as const;
+type Family=keyof typeof messages;
+const recognised=new WeakMap<object,string>();
+/** A privacy-safe exception carries only one of our fixed messages, never a caught message or path. */
+export function rememberProfileLockError(error:object,text:string):void {
+  if((Object.values(messages) as readonly string[]).includes(text))recognised.set(error,text);
+}
+export function safeProfileLockMessage(error:unknown):string|undefined {
+  return error!==null&&(typeof error==="object"||typeof error==="function")?recognised.get(error):undefined;
+}
+const same=(a:BigIntStats,b:BigIntStats)=>a.dev===b.dev&&a.ino===b.ino&&a.uid===b.uid&&a.mode===b.mode&&a.nlink===b.nlink&&a.size===b.size&&a.mtimeNs===b.mtimeNs&&a.ctimeNs===b.ctimeNs;
+function owned(s:BigIntStats,limit:number,privateFile=true):void {
+  if(!s.isFile()||s.isSymbolicLink()||s.uid!==BigInt(process.getuid?.()??-1)||s.nlink!==1n||(s.mode&(privateFile?0o077n:0o022n))!==0n||s.size>BigInt(limit))throw Error();
+}
+const object=(v:unknown):v is Record<string,unknown>=>!!v&&typeof v==="object"&&!Array.isArray(v);
+const hex=(v:unknown,width:number)=>typeof v==="string"&&v.length===width&&!/[^a-f0-9]/.test(v);
+/** Only called after an existing refusal. Absent lock means no extra marker/intent read at all.
+ * ponytail: fixed metadata limits plus20000 home names/256 staging files; a reviewed bounded descriptor inventory is needed to grow this hint. */
+export function profileLockRefusal(home:string):string|undefined {
+  try{
+    const checks:(()=>void)[]=[];
+    const read=(name:string,limit:number,privateFile=true):Record<string,unknown>|undefined=>{
+      const file=join(home,name),before=lstatSync(file,{bigint:true,throwIfNoEntry:false});
+      if(!before){checks.push(()=>{if(lstatSync(file,{throwIfNoEntry:false}))throw Error();});return;}
+      owned(before,limit,privateFile);const fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+      try{
+        const s=fstatSync(fd,{bigint:true});if(!same(before,s))throw Error();
+        const bytes=Buffer.alloc(Number(s.size)+1);let count=0;
+        while(count<bytes.length){const n=readSync(fd,bytes,count,bytes.length-count,count);if(!n)break;count+=n;}
+        if(count!==Number(s.size)||!same(s,fstatSync(fd,{bigint:true}))||!same(s,lstatSync(file,{bigint:true})))throw Error();
+        const value:unknown=JSON.parse(new TextDecoder("utf-8",{fatal:true}).decode(bytes.subarray(0,count)));if(!object(value))throw Error();
+        checks.push(()=>{if(!same(s,lstatSync(file,{bigint:true})))throw Error();});return value;
+      }finally{closeSync(fd);}
+    };
+    const owner=read("profile.lock",4096);if(!owner)return;
+    if(Object.keys(owner).sort().join()!=="pid,signature,token"||!Number.isSafeInteger(owner.pid)||Number(owner.pid)<=0||!hex(owner.signature,64)||!hex(owner.token,32))return;
+    const canonical=realPath(home),profile=read("profile.json",262144,false),shards=read("shards.json",262144,false);
+    const prune=read("public-prune-view.intent.json",1048576),activation=read("sync-placement-activation.json",1048576),renewal=read("sync-placement-writer-renewal.json",1048576);
+    const families=new Set<Family>();
+    if(prune){if(prune.schema!=="agent-mem.public-prune-activation/v1"&&prune.schema!=="agent-mem.public-prune-advance/v1"||prune.home!==canonical||!hex(prune.generation,32))return;families.add("prune");}
+    if(activation){if(activation.schema!=="agent-mem.sync-placement-activation/v1"||activation.home!==canonical||!object(activation.epoch)||!hex(activation.epoch.generation,32))return;families.add("activation");}
+    if(renewal){if(renewal.schema!=="agent-mem.sync-placement-writer-renewal/v1"||renewal.home!==canonical||!object(renewal.revision)||renewal.revision.schema!=="agent-mem.sync-placement-writer-revision/v1"||!hex(renewal.revision.generation,32)||!hex(renewal.revision.epochHash,64))return;families.add("renewal");}
+    if(shards?.schema==="agent-mem.shards/v1"&&shards.phase==="captured"&&hex(shards.generation,32))families.add("shards");
+    if(!families.size&&profile?.schema==="agent-mem.profile/v3"&&shards?.schema==="agent-mem.shards/v3"&&shards.phase==="active"&&hex(profile.generation,32)&&shards.generation===profile.generation&&hex(profile.placementHead,64)&&profile.placementHead===shards.placementHead){
+      const reader=opendirSync(home);let names=0,staging=0,nameBytes=0;
+      try{for(;;){const entry=reader.readSync();if(!entry)break;if(++names>20000||(nameBytes+=Buffer.byteLength(entry.name))>8*1024*1024)throw Error();
+        const prefix="sync-placement-writer-renewal.json.pending-";if(!entry.name.startsWith(prefix)||!hex(entry.name.slice(prefix.length),64))continue;
+        if(++staging>256)throw Error();const file=join(home,entry.name),s=lstatSync(file,{bigint:true});owned(s,1048576);checks.push(()=>{if(!same(s,lstatSync(file,{bigint:true})))throw Error();});
+      }}finally{reader.closeSync();}
+      if(staging)families.add("staging");
+    }
+    for(const check of checks)check();if(families.size!==1)return;
+    return messages[[...families][0]!];
+  }catch{return undefined;}
+}
+export function profileLockRecoveryError(home:string):Error|undefined {
+  const text=profileLockRefusal(home);if(!text)return;const error=new Error(text);error.name="ProfileLockMigrationError";rememberProfileLockError(error,text);return error;
+}

package/src/memory/reader-lease.ts

@@ -4,6 +4,7 @@ import { readProfileJSON, writeProfileJSON } from "./generation.ts";
 import { readerAdmissionDatabase } from "./mutation.ts";
 import { processLiveness, processSignature } from "./platform.ts";
 import { waitForPublicPruneWriter } from "./public-prune-view.ts";
+import { profileLockRecoveryError, safeProfileLockMessage } from "./profile-lock-diagnostic.ts";
 
 const READER_LEASE_SCHEMA = "agent-mem.reader-lease/v1";
 const RENEW_MS = 25_000;
@@ -52,8 +53,8 @@ function admitReader(memoryDir: string): void {
   // Even a malformed or stale marker refuses admission; only the profile-lock owner may reclaim it.
   try {
     waitForPublicPruneWriter(memoryDir);
-    if (lstatSync(join(memoryDir, "profile.lock"), { throwIfNoEntry: false })) throw new Error("profile lock prevents reader admission; finish or resume the migration with amem migrate --resume");
-  } catch { throw new Error("profile lock prevents reader admission; finish or resume the migration with amem migrate --resume"); }
+    if (lstatSync(join(memoryDir, "profile.lock"), { throwIfNoEntry: false })) throw profileLockRecoveryError(memoryDir) ?? new Error("profile lock prevents reader admission; finish or resume the migration with amem migrate --resume");
+  } catch (error) { if(safeProfileLockMessage(error))throw error;throw profileLockRecoveryError(memoryDir) ?? new Error("profile lock prevents reader admission; finish or resume the migration with amem migrate --resume"); }
 }
 
 /** One lease per process/home/namespace, reference-counted across handles.

package/src/memory/shard.ts

@@ -8,6 +8,7 @@ import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, rmSync, write
 import { join } from "node:path";
 import { canonicalJSON, generationDescriptor, hashJSON, readProfileJSON, readSelector, validGeneration, PROFILE_LOCK_TIMEOUT_MS, type BoundProfile, type GenerationSeal } from "./generation.ts";
 import { SHARD_SCHEMA, resolveAlias } from "./aliases.ts";
+import { profileLockRecoveryError, safeProfileLockMessage } from "./profile-lock-diagnostic.ts";
 
 /**
  * #15 T1: the per-project shard layout under the user home. One shard per project key at `projects/<key-hash>/`;
@@ -126,6 +127,7 @@ function shardSnapshot(memoryDir: string, deadline: number) {
     let selector: ReturnType<typeof readSelector>;
     try { selector = readSelector(memoryDir, deadline); }
     catch (error) {
+      if(safeProfileLockMessage(error))throw error;
       if (error instanceof SyncPlacementRuntimeError) throw error;
       // The writer's spent wait budget or unavailable proof is never restarted here.
       if (error instanceof Error && error.message === "public prune view unavailable") throw error;
@@ -145,8 +147,10 @@ function shardSnapshot(memoryDir: string, deadline: number) {
   throw new Error("curated shard selector changed");
 }
 export function readShardedSelection(memoryDir: string): ShardedSelection {
+  try {
   const { journal } = shardSnapshot(memoryDir, Date.now() + PROFILE_LOCK_TIMEOUT_MS);
   return { schema: journal.schema, generation: journal.generation, phase: "active", selectorRevision: journal.selectorRevision };
+  }catch(error){if(safeProfileLockMessage(error))throw error;throw profileLockRecoveryError(memoryDir)??error;}
 }
 
 /** Fixed curated paths cannot redirect writes into legacy inputs or another shard.

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

@@ -7,13 +7,14 @@ import { LOCAL_METADATA_MAX_BYTES, legacyProfileMarkerShape, type BoundProfile }
 import { legacyShardMarkerShape } from "./shard.ts";
 import { PLACEMENT_PROFILE_SCHEMA, PLACEMENT_SHARDS_SCHEMA, validatePlacementProfile, validatePlacementShards } from "./sync-placement-format.ts";
 import { PLACEMENT_ACTIVATION_INTENT } from "./sync-placement-activation-path.ts";
+import { profileLockRefusal, rememberProfileLockError } from "./profile-lock-diagnostic.ts";
 
 export const PLACEMENT_STAGE1_REFUSAL = "sync placement v3 requires matching durable activation metadata; keep the current compatible profile active until person-authorized activation is complete";
 export const PLACEMENT_MARKER_REFUSAL = "sync placement metadata is invalid or unsupported; person inspection and a compatible reader are required before continuing";
 export const PLACEMENT_ACTIVATION_PENDING = "sync placement activation is pending or incomplete; have the person inspect retained evidence and run amem migrate --sync-placement --resume, or --abandon only while both markers retain their original v2 bytes";
 export class SyncPlacementRuntimeError extends Error {
   readonly code: "sync_placement_not_enabled" | "sync_placement_unavailable";
-  constructor(reason: string) { super(reason); this.name = "SyncPlacementRuntimeError"; this.code = reason === PLACEMENT_STAGE1_REFUSAL ? "sync_placement_not_enabled" : "sync_placement_unavailable"; }
+  constructor(reason: string) { super(reason); this.name = "SyncPlacementRuntimeError"; this.code = reason === PLACEMENT_STAGE1_REFUSAL ? "sync_placement_not_enabled" : "sync_placement_unavailable";rememberProfileLockError(this,reason); }
 }
 class MarkerChanged extends Error {}
 const same = (left: BigIntStats, right: BigIntStats) => left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
@@ -65,6 +66,9 @@ export function placementMarkerRefusal(profile: unknown, shards: unknown): strin
 /** Selector preflight only recognizes v3. Legacy malformed/split metadata must retain its existing reader/recovery path. */
 // This narrow probe is not a data/transport gate; effects must still use the full runtime guard.
 export function placementSelectorRefusal(home: string): string | undefined {
+  const refusal=selectorRefusal(home);return refusal?profileLockRefusal(home)??refusal:undefined;
+}
+function selectorRefusal(home:string):string|undefined {
   // A durable placement fence forbids falling back to raw legacy sync after marker rollback.
   const fenced = placementFencePresent(home);
   const pending = placementActivationPending(home);
@@ -100,5 +104,5 @@ export function placementRuntimeRefusal(home: string, bound?: Pick<BoundProfile,
   catch { return PLACEMENT_MARKER_REFUSAL; }
 }
 export function assertPlacementRuntime(home: string): void {
-  const refusal = placementRuntimeRefusal(home); if (refusal) throw new SyncPlacementRuntimeError(refusal);
+  const refusal = placementRuntimeRefusal(home); if (refusal) throw new SyncPlacementRuntimeError(profileLockRefusal(home)??refusal);
 }

package/src/setup-toml.ts

@@ -37,7 +37,7 @@ function inline(value: unknown): string {
   // Bun emits scalars and many arrays as one assignment. Reuse that literal when it is safe in this scope.
   // Objects/AOTs may become headers; those need the inline form below to avoid changing subsequent table scope.
   let rendered = "";
-  try { rendered = Bun.TOML.stringify({ setup_value: value }); } catch { /* The validated inline encoder covers values the built-in writer cannot emit. */ }
+  try { rendered = Bun.TOML.stringify({ setup_value: value }) ?? ""; } catch { /* The validated inline encoder covers values the built-in writer cannot emit. */ }
   const literal = /^setup_value\s*=\s*([^\r\n]*)\r?\n?$/.exec(rendered)?.[1];
   if (literal !== undefined && isDeepStrictEqual(shape(parse(rendered).setup_value), shape(value))) return literal;
   const encode = (part: unknown): string => {
@@ -255,7 +255,8 @@ function arrayEdit(before: readonly unknown[], after: readonly unknown[]): { kee
 function appendedTables(path: readonly string[], values: readonly unknown[], eol: string): string {
   if (!values.every(plain)) return error();
   const document: Record<string, unknown> = {}; edit(document, path, [...values]);
-  let source: string; try { source = Bun.TOML.stringify(document); } catch { return error(); }
+  let source: string | undefined; try { source = Bun.TOML.stringify(document); } catch { return error(); }
+  if (source === undefined) return error();
   const sourceUnits = statements(source), rows = sourceUnits.filter(unit => prefix(path, unit.path));
   if (rows.filter(unit => unit.header && unit.array && unit.path.length === path.length).length !== values.length) return error();
   return rows.map(unit => source.slice(unit.start, unit.end)).join("").replace(/\r?\n/g, eol);