@staix/agent-mem 0.22.0 → 0.23.0

package/src/memory/capture.ts

@@ -4,7 +4,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, opendirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { looksSecret } from "./screen.ts";
-import { captureAttribution, normalizeCaptureFields, SESSION_KEY, type CaptureFields } from "./capture-input.ts";
+import { captureAttribution, normalizeCaptureFields, RecordNormalizationRefusal, SESSION_KEY, type CaptureFields } from "./capture-input.ts";
 export { CAPTURE_MAX_EXCERPT, CAPTURE_MAX_PATHS } from "./capture-input.ts";
 import { memoryBase } from "./home.ts";
 import { captureShardDir, ensureShardDescriptor, readShardDescriptor, resolveAlias, shardKeyHash } from "./shard.ts";
@@ -292,6 +292,7 @@ export class CaptureStore {
       // #173: additive nullable columns. Older readers use explicit or `SELECT *` column names and ignore extras.
       addAttributionColumns(db);
       this.ensureBriefSummaryIndex(true);
+      this.ensureBriefRecordIndex(true);
       this.ensureFts();
     } catch (error) {
       if (!lockError(error)) { db.close(); throw error; }
@@ -390,7 +391,7 @@ export class CaptureStore {
   private briefReady = false;
   private prepareBriefSummaryIndex(): void {
     if (this.readOnly || this.briefReady) return;
-    try { this.ensureBriefSummaryIndex(false); this.briefReady = true; }
+    try { this.ensureBriefSummaryIndex(false); this.ensureBriefRecordIndex(false); this.briefReady = true; }
     catch { /* Optional summary coverage remains partial; query engines remain independent. */ }
   }
   /** One-time MCP read cost only: hooks neither create this derived index nor scan history to fill it. */
@@ -437,6 +438,11 @@ export class CaptureStore {
     const receipt = options.receipt;
     if (receipt !== undefined && (typeof receipt !== "string" || !/^[a-f0-9]{64}$/.test(receipt) || input.at === undefined)) throw new Error("capture receipt needs a stable time and a 64-hex digest");
     const row = this.normalize(input);
+    // Pending hook Records must stay whole when caps or screening change before replay.
+    // Check before receipt derivation or any spool/DB write; drainers retire this policy refusal whole.
+    if (input.event === "Record" && (row.excerpt !== input.excerpt || JSON.stringify(row.paths) !== JSON.stringify(input.paths ?? []))) {
+      throw new RecordNormalizationRefusal();
+    }
     // Reuse the immutable spool format and its existing unique index: a crash between capture and cursor
     // advance replays exactly the same screened line, whether first written directly or under contention.
     const spoolId = receipt === undefined ? null : createHash("sha256").update(this.spoolLine(row, receipt)).digest("hex");
@@ -661,6 +667,40 @@ export class CaptureStore {
     if (bounded) this.db.transaction(build).immediate(); else build();
   }
 
+  /** Share the summary index's atomic small-store and off-hook preparation rules. */
+  private ensureBriefRecordIndex(bounded: boolean): void {
+    if (this.db.query("SELECT 1 FROM sqlite_master WHERE name='rows_brief_records_v1' AND type='index'").get()) return;
+    const build = () => {
+      if (bounded) {
+        const count = (this.db.query("SELECT COUNT(*) AS n FROM (SELECT 1 FROM rows LIMIT 129)").get() as { n: number }).n;
+        if (count > 128) return;
+      }
+      this.db.run("CREATE INDEX IF NOT EXISTS rows_brief_records_v1 ON rows(project,at,id) WHERE event='Record' AND (subagent IS NULL OR subagent != 1)");
+    };
+    if (bounded) this.db.transaction(build).immediate(); else build();
+  }
+
+  /** A separate derived index leaves the released summary predicate unchanged. */
+  readBriefRecords(limit = BRIEF_SUMMARY_CANDIDATES): { rows: CaptureRow[]; partial: boolean } {
+    this.checkReadBinding();
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > BRIEF_SUMMARY_CANDIDATES) throw new Error("invalid brief Record limit; use an integer from 1 to 32");
+    const indexed = !!this.db.query("SELECT 1 FROM sqlite_master WHERE name='rows_brief_records_v1' AND type='index'").get();
+    let rows: RawRow[], partial = false;
+    if (indexed) {
+      rows = this.db.query("SELECT * FROM rows INDEXED BY rows_brief_records_v1 WHERE project=? AND event='Record' AND (subagent IS NULL OR subagent != 1) ORDER BY at DESC,id DESC LIMIT ?")
+        .all(this.key, limit + 1) as RawRow[];
+    } else {
+      // ponytail: inspect only 128 recent legacy rows until off-hook search prepares
+      // the index; an explicit bounded index-preparation command is the upgrade.
+      const hasSubagent = (this.db.query("PRAGMA table_info(rows)").all() as { name: string }[]).some(column => column.name === "subagent");
+      const subagent = hasSubagent ? " AND (subagent IS NULL OR subagent != 1)" : "";
+      rows = this.db.query(`SELECT * FROM (SELECT * FROM rows INDEXED BY rows_at ORDER BY at DESC,id DESC LIMIT 128) WHERE project=? AND event='Record'${subagent} ORDER BY at DESC,id DESC LIMIT ?`)
+        .all(this.key, limit + 1) as RawRow[];
+      partial = this.db.query("SELECT id FROM rows INDEXED BY rows_at ORDER BY at DESC,id DESC LIMIT 129").all().length > 128;
+    }
+    return { rows: rows.slice(0, limit).map(toRow), partial: partial || rows.length > limit };
+  }
+
   /** Index reads return at most33 bodies. Legacy fallback reads at most128 recent rows. */
   readBriefSummaries(limit = BRIEF_SUMMARY_CANDIDATES): { rows: CaptureRow[]; partial: boolean } {
     this.checkReadBinding();

package/src/memory/config.ts

@@ -17,10 +17,12 @@ export const CONFIG_FILE = "amem.config.json";
 export const REPO_CONFIG_DIR = ".amem";
 export const REPO_CONFIG_FILE = "config";
 const MAX_CONFIG_BYTES = 64 * 1024;
-const MACHINE_KEYS = ["home", "denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths", "capture"] as const;
-const REPO_KEYS = ["denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths"] as const;
+const MACHINE_KEYS = ["home", "denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths", "capture", "records"] as const;
+const REPO_KEYS = ["denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths", "records"] as const;
 
 export interface AmemConfig {
+  /** Static SessionStart record instruction; absent means enabled. Repository false only narrows. */
+  records?: boolean;
   /** The memory home, when the file moves it (a pointer file: see `configuredHome`). `AMEM_HOME` still wins. Machine file only. */
   home?: string;
   denyPaths: string[];
@@ -77,6 +79,10 @@ function parseFile(raw: unknown, label: string, keys: readonly string[]): Partia
   const out: Partial<AmemConfig> & { capture?: AmemConfig["capture"] } = {
     denyPaths: listOf(body.denyPaths, "denyPaths", label), piiPatterns: listOf(body.piiPatterns, "piiPatterns", label),
   };
+  if (Object.hasOwn(body, "records")) {
+    if (typeof body.records !== "boolean") return fail(label, "records is not a boolean");
+    out.records = body.records;
+  }
   const briefBytes = countOf(body.briefBytes, "briefBytes", label, 1_000_000); if (briefBytes !== undefined) out.briefBytes = briefBytes;
   const excerptBytes = countOf(body.excerptBytes, "excerptBytes", label, 100_000); if (excerptBytes !== undefined) out.excerptBytes = excerptBytes;
   const capturePaths = countOf(body.capturePaths, "capturePaths", label, 1000); if (capturePaths !== undefined) out.capturePaths = capturePaths;
@@ -149,6 +155,7 @@ export function loadAmemConfig(base: string, repoRoot?: string): LoadedConfig {
   if (piiPatterns.length > 64) fail(machinePath, "piiPatterns and the repository's piiPatterns name more than 64 entries together");
   const config: AmemConfig = { denyPaths, piiPatterns, capture: { ...(machine?.capture ?? {}) } };
   if (machine?.home !== undefined) config.home = machine.home;
+  if (machine?.records !== undefined || repo?.records !== undefined) config.records = machine?.records !== false && repo?.records !== false;
   for (const key of ["briefBytes", "excerptBytes", "capturePaths"] as const) { const value = lower(machine?.[key], repo?.[key]); if (value !== undefined) config[key] = value; }
   return { config, source: { machine: machineRaw === undefined ? null : machinePath, repo: repoPath } };
 }

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/metrics.ts

@@ -1,10 +1,11 @@
 import { closeSync, constants, fstatSync, openSync, readSync, appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import type { RecordDropReason } from "../hook-record.ts";
 import type { HookRssSources } from "../hook-resources.ts";
 import type { HookTranscriptStopReason } from "../hook-contract.ts";
 import { join } from "node:path";
 
 /** Rolling resource samples; importing this leaf never loads a memory store or capacity probe. */
-export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; rssSources?: HookRssSources; rssScope?: "owned-images"; transcriptOffset?: number; transcriptStopReason?: HookTranscriptStopReason; /** #226: owned children killed but still alive when the hook returned (bounded reap). */ abandonedChildren?: number; /** #226: a killed worker skipped this call's drain; staged records stay pending (not a capture drop). */ drainSkipped?: number; /** #226: when the worker drain started (ms after hook start) and how many records it committed. */ drainStartMs?: number; drained?: number; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
+export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; rssSources?: HookRssSources; rssScope?: "owned-images"; transcriptOffset?: number; transcriptStopReason?: HookTranscriptStopReason; /** #226: owned children killed but still alive when the hook returned (bounded reap). */ abandonedChildren?: number; /** #226: a killed worker skipped this call's drain; staged records stay pending (not a capture drop). */ drainSkipped?: number; /** #226: when the worker drain started (ms after hook start) and how many records it committed. */ drainStartMs?: number; drained?: number; idleMB?: number; recordInstructionBytes?: number; recordInstructionEstimatedTokens?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
 const METRICS_MAX_BYTES = 64 * 1024, METRICS_KEEP = 200;
 
 export function metricsPath(base: string): string {
@@ -38,8 +39,8 @@ export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[]
 }
 
 
-export type CaptureDropReason = "summary_capacity" | "scope_capacity" | "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten" | "unknown_schema_expired" | "transcript_line_bound";
-const DROP_REASONS: readonly CaptureDropReason[] = ["summary_capacity", "scope_capacity", "spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired", "transcript_line_bound"];
+export type CaptureDropReason = "summary_capacity" | "scope_capacity" | "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten" | "unknown_schema_expired" | "transcript_line_bound" | RecordDropReason;
+const DROP_REASONS: readonly CaptureDropReason[] = ["summary_capacity", "scope_capacity", "spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired", "transcript_line_bound", "record_invalid", "record_count", "record_length", "record_policy", "record_identity", "record_timestamp"];
 /** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. Fails open to no counts: hooks never deny over metrics. */
 export function captureDropSummary(base: string): Partial<Record<CaptureDropReason, number>> {
   const read = readCaptureDrops(base);

package/src/memory/private-spans.ts

@@ -9,17 +9,20 @@
  */
 const TAG = /<\s*(\/?)\s*private(?=[\s/>])[^<>]*>/gi;
 
-export function stripPrivateSpans(text: string): string {
+/** The optional range observer receives only omitted offsets, never private text. */
+export function stripPrivateSpans(text: string, omitted?: (start: number, end: number) => void): string {
   if (!/<\s*\/?\s*private(?=[\s/>])/i.test(text)) return text;
-  let out = "", depth = 0, last = 0, match: RegExpExecArray | null;
+  let out = "", depth = 0, last = 0, privateStart = 0, match: RegExpExecArray | null;
   TAG.lastIndex = 0;
   while ((match = TAG.exec(text))) {
     const closing = match[1] === "/", stray = closing && depth === 0;
     if (depth === 0) out += text.slice(last, stray ? match.index + match[0].length : match.index);   // a stray closer is plain text: keep it
-    if (closing) { if (depth > 0) depth--; } else depth++;
+    if (closing) { if (depth > 0 && --depth === 0) omitted?.(privateStart, match.index + match[0].length); }
+    else { if (depth === 0) privateStart = match.index; depth++; }
     last = match.index + match[0].length;
   }
   if (depth === 0) out += text.slice(last);
+  else omitted?.(privateStart, text.length);
   return out;
 }
 

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/repo-scope.ts

@@ -284,8 +284,14 @@ export function namesPrivatePath(text: string): boolean {
   return HOME_PATH.some(re => re.test(folded)) || (home.length > 3 && folded.includes(home));
 }
 const SAFE_NODE = /^(?:path|symbol|issue):/;
-/** A graph node that may be committed: a repository-relative path or symbol, or an issue. Private task, goal and memory references and absolute or escaping paths stay out. */
+// Offline syntax only (#185): no lookup. DOI `10.<registrant>/<suffix>` with printable, space-free ASCII suffix; arXiv new (`YYMM.NNNN[N]`) and old (`archive[.XX]/YYMMNNN`) ids, optional `vN`.
+const DOI_NODE = /^doi:10\.\d{4,9}(?:\.\d+)*\/[\x21-\x7e]+$/;
+const ARXIV_NODE = /^arxiv:(?:\d{2}(?:0[1-9]|1[0-2])\.\d{4,5}|[a-z]+(?:-[a-z]+)*(?:\.[A-Z]{2})?\/\d{2}(?:0[1-9]|1[0-2])\d{3})(?:v[1-9]\d*)?$/;
+/** A public literature identifier (`doi:` or `arxiv:`) that is well formed and so may be committed to repo scope. */
+export function publicIdentifierNode(node: string): boolean { return DOI_NODE.test(node) || ARXIV_NODE.test(node); }
+/** A graph node that may be committed: a repository-relative path or symbol, an issue, or a well-formed public `doi:`/`arxiv:` identifier. Private task, goal, memory and host-local (`run:`) references, malformed identifiers and absolute or escaping paths stay out. */
 function committableNode(node: string): boolean {
+  if (node.startsWith("doi:") || node.startsWith("arxiv:")) return publicIdentifierNode(node);
   if (!SAFE_NODE.test(node)) return false;
   const where = node.startsWith("path:") ? node.slice(5) : node.startsWith("symbol:") && node.includes("@") ? node.slice(node.lastIndexOf("@") + 1) : "";
   if (!where) return !node.startsWith("path:") && !node.startsWith("symbol:");

package/src/memory/search-score.ts

@@ -14,16 +14,18 @@ type ScoreExpr = { op: "rank" | "tier" | "age" } | { op: "constant"; value: numb
 const MONTH_DAYS = 30;
 const TIER_WEIGHTS: Readonly<Record<string, number>> = { long: 1, capture: 0.5 };
 const DEFAULT_TIER_WEIGHT = 0.9;
-// ponytail: fixed 1.25x ceiling for conversational capture, not a learned relevance model.
+// ponytail: fixed 1.25x conversation and 1.5x Record weights, not a learned relevance model.
 // Raise it only with fresh S/M no-loss and private-capture evidence; curated tier factors stay unchanged.
 export const CAPTURE_CONVERSATION_WEIGHT = 1.25;
+const CAPTURE_RECORD_WEIGHT = 1.5;
 const CONVERSATIONAL_CAPTURE_EVENTS = ["Stop", "UserPromptSubmit", "Title", "Recap", "Compact"] as const;
 export function captureEventWeight(event: string): number {
+  if (event === "Record") return CAPTURE_RECORD_WEIGHT;
   return (CONVERSATIONAL_CAPTURE_EVENTS as readonly string[]).includes(event) ? CAPTURE_CONVERSATION_WEIGHT : 1;
 }
 /** Only fixed internal SQL identifiers are supplied by callers; event values remain stored data. */
 export function captureEventWeightSql(eventColumn: string): string {
-  return `(CASE WHEN ${eventColumn} IN (${CONVERSATIONAL_CAPTURE_EVENTS.map(event => `'${event}'`).join(", ")}) THEN ${CAPTURE_CONVERSATION_WEIGHT} ELSE 1.0 END)`;
+  return `(CASE WHEN ${eventColumn} = 'Record' THEN ${CAPTURE_RECORD_WEIGHT} WHEN ${eventColumn} IN (${CONVERSATIONAL_CAPTURE_EVENTS.map(event => `'${event}'`).join(", ")}) THEN ${CAPTURE_CONVERSATION_WEIGHT} ELSE 1.0 END)`;
 }
 const TIER_FACTOR: ScoreExpr = { op: "tier" };
 const DENOMINATOR: ScoreExpr = { op: "add", left: { op: "constant", value: 1 }, right: { op: "max", left: { op: "constant", value: 0 }, right: { op: "age" } } };

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/memory/sync-placement-prerequisites.ts

@@ -9,6 +9,13 @@ import { PLACEMENT_PROFILE_SCHEMA, validatePlacementBaseV2, type PlacementBaseV2
 
 export const PLACEMENT_ACTIVATION_MIN_READER = "0.21.0";
 const preview = "amem migrate --sync-placement --dry-run";
+/** Typed only for safe adapter diagnostics; the floor predicate and remedy stay shared. */
+export class PlacementHomeFloorError extends Error {
+  constructor(minReader: string) {
+    super(`Sync placement requires a person-authored home floor of ${minReader} or later in formats.json; have the person append that record, then rerun ${preview}.`);
+    this.name = "PlacementHomeFloorError";
+  }
+}
 function requireHomeFloor(home: string,minReader:string): string {
   assertFormatFloor(home, "curated"); assertFormatFloor(home, "sync");
   const floors = readFormatFloors(home), minimum = minReader.split(".").map(Number);
@@ -18,7 +25,7 @@ function requireHomeFloor(home: string,minReader:string): string {
     for (let i = 0; i < 3; i++) if (parts[i] !== minimum[i]) return parts[i]! > minimum[i]!;
     return true;
   });
-  if (!adequate) throw Error(`Sync placement requires a person-authored home floor of ${minReader} or later in formats.json; have the person append that record, then rerun ${preview}.`);
+  if (!adequate) throw new PlacementHomeFloorError(minReader);
   return hashJSON(floors);
 }
 export function requirePlacementHomeFloor(home:string):string{return requireHomeFloor(home,PLACEMENT_ACTIVATION_MIN_READER);}

package/src/session-brief-worker.ts

@@ -121,7 +121,7 @@ if (import.meta.main) {
         else try {
           const { scanHookTranscriptTail } = await import("./hook-transcript.ts");
           const scanned = await scanHookTranscriptTail(scan.transcript, {
-            cwd: scan.cwd, base: scan.base, policy: scan.policy, deadline: performance.now() + (scanEnd - now()),
+            cwd: scan.cwd, base: scan.base, policy: scan.policy, workBudgetMs: 60, deadline: performance.now() + (scanEnd - now()),
             // Same existing oldest-first drain and one shared budget, never a new 32-file allowance per publication.
             onPublication: async () => { await replay(scanEnd, false); },
             onBackpressure: () => replay(scanEnd, false),

package/src/session-brief.ts

@@ -1,6 +1,7 @@
 import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { CaptureRow } from "./memory/capture.ts";
+import { parseRecordLines } from "./hook-record.ts";
 import { readSelector } from "./memory/generation.ts";
 import { memoryHome } from "./memory/home.ts";
 import { canonicalPath, realPath } from "./memory/platform.ts";
@@ -99,6 +100,14 @@ function captureDisplay(row: CaptureRow): { data: unknown; partial: boolean } {
     partial: excerpt.partial || event.partial || row.paths.length > paths.length || paths.some(path => path.partial) };
 }
 
+/** Keep the canonical Record whole; '-' is valid only for project-bound decisions/contracts. */
+function recordDisplay(row: CaptureRow): { data: unknown; partial: boolean } | undefined {
+  const parsed = parseRecordLines(row.excerpt), record = parsed.records[0];
+  if (!record || parsed.records.length !== 1 || Object.keys(parsed.drops).length || record.line !== row.excerpt
+    || JSON.stringify(record.anchors) !== JSON.stringify(row.paths)) return;
+  return { data: { event: "Record", paths: record.anchors, excerpt: record.line }, partial: false };
+}
+
 /** A short-lived, model-free projection. The hook host supplies the hard process deadline; this function owns no timer or child. */
 export async function sessionStartBrief(options: BriefOptions): Promise<BriefResult> {
   let result = unavailable();
@@ -204,6 +213,8 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
             if (section === "capture" && skipCaptureIds.has((row as { id: number }).id)) continue;
             // #173: subagent capture stays searchable but never enters the session brief.
             if (section === "capture" && (row as { subagent?: unknown }).subagent === true) continue;
+            // Records have their own five-row, whole-line selection before raw captures.
+            if (section === "capture" && (row as { event?: unknown }).event === "Record") continue;
             if (!await screen(row)) continue;
             if (selected++ >= SECTION_RECORDS) { coverage[section] = "partial"; return; }
             await add(section, display(row), section === "curated");
@@ -250,6 +261,16 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
         }
         const capture = new CaptureStore({ memoryDir: base, project, cwd, ...(options.nativeSession || options.measureOnly ? { readOnly: true, busyTimeoutMs: options.measureOnly ? 1000 : 0, maxReadRows: 128, recentReadRows: true } : {}) }); closers.push(() => capture.close());
         if (capture.recentReadTruncated) coverage.capture = "partial";
+        const records = capture.readBriefRecords();
+        if (records.partial) coverage.capture = "partial";
+        let selectedRecords = 0;
+        for (const row of records.rows) {
+          if (row.project !== project || row.subagent === true) continue;
+          if (selectedRecords >= 5) { coverage.capture = "partial"; break; }
+          if (!await screen(row)) continue;
+          const shown = recordDisplay(row);
+          if (shown && await add("capture", shown, false)) selectedRecords++;
+        }
         const summaries = capture.readBriefSummaries(), summaryIds = new Set<number>();
         if (summaries.partial) coverage.capture = "partial";
         let selectedSummaries = 0;

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);

package/src/sync-placement-writer-context.ts

@@ -1,15 +1,17 @@
-/** CLI adapter only. Expected locators are never returned as fresh writer facts. */
+/** CLI/host adapter. Expected locators are never returned as fresh writer facts. */
 import { types } from "node:util";
-import { realPath } from "./memory/platform.ts";
+import { fileURLToPath } from "node:url";
+import { canonicalPath, realPath } from "./memory/platform.ts";
 import { canonicalJSON } from "./memory/generation.ts";
 import { readSetupWriterRoots } from "./setup.ts";
 import { measureSyncPlacementWriters, extractSyncPlacementWriterFailure, type SyncPlacementWriterFailureDetail, type SyncPlacementWriterMeasurement } from "./memory/sync-placement-writers.ts";
 import { readEffectiveSyncPlacementWriters } from "./memory/sync-placement-effective-writers.ts";
-import { requirePlacementHomeFloor } from "./memory/sync-placement-prerequisites.ts";
+import { PlacementHomeFloorError, requirePlacementHomeFloor } from "./memory/sync-placement-prerequisites.ts";
+import { FormatFloorError } from "./memory/formats.ts";
 import type { PlacementCapturePort } from "./memory/sync-placement-capture.ts";
 import { SharedWriterRevisionError } from "./memory/sync-placement-writer-revision-format.ts";
 
-export type PlacementWriterRootCategory = "running CLI" | "setup receipt" | "declared writer" | "active locator" | "home floor" | "writer renewal";
+export type PlacementWriterRootCategory = "running CLI" | "host package" | "setup receipt" | "declared writer" | "active locator" | "home floor" | "writer renewal";
 export type PlacementWriterContextPhase = "initial" | "active";
 const failureDetails: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",
@@ -30,11 +32,12 @@ export class PlacementWriterContextError extends Error {
   }
 }
 function safeRefusal(error: unknown, category: PlacementWriterRootCategory,phase:PlacementWriterContextPhase="active"): PlacementWriterContextError {
+  if (error && typeof error === "object" && !types.isProxy(error) && (error instanceof PlacementHomeFloorError || error instanceof FormatFloorError)) return new PlacementWriterContextError("home floor","unavailable",phase);
   if(error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof SharedWriterRevisionError){const code=Object.getOwnPropertyDescriptor(error,"code")?.value;if(code==="pending"||code==="staging")return new PlacementWriterContextError("writer renewal","unavailable",phase,undefined,code);}
   if (error && typeof error === "object" && !types.isProxy(error) && error instanceof PlacementWriterContextError) {
     const fields=Object.getOwnPropertyDescriptors(error),root=fields.category,cause=fields.causeClass,detail=fields.detail;
     const category:unknown=root&&"value"in root?root.value:undefined,causeClass:unknown=cause&&"value"in cause?cause.value:undefined;
-    if (typeof category==="string" && ["running CLI","setup receipt","declared writer","active locator","home floor","writer renewal"].includes(category)
+    if (typeof category==="string" && ["running CLI","host package","setup receipt","declared writer","active locator","home floor","writer renewal"].includes(category)
       && typeof causeClass==="string" && ["missing","changed","unavailable"].includes(causeClass)) {
       const ownDetail=detail&&"value"in detail&&typeof detail.value==="string"&&Object.hasOwn(failureDetails,detail.value)?detail.value as SyncPlacementWriterFailureDetail:undefined;
       const state=fields.renewalState?.value;
@@ -93,8 +96,9 @@ export function initialPlacementWriterContext(home: string, roots: readonly stri
 /** Active callbacks re-read the bound locator AND measure every package anew. No activation or renewal occurs. */
 export function activePlacementWriterContext(home: string, ownRoot: string): PlacementWriterContext {
   const read = () => {
-    requirePlacementHomeFloor(home);
-    const effective=readEffectiveSyncPlacementWriters(home);
+    try { requirePlacementHomeFloor(home); } catch (error) { throw safeRefusal(error,"home floor"); }
+    let effective: ReturnType<typeof readEffectiveSyncPlacementWriters>;
+    try { effective=readEffectiveSyncPlacementWriters(home); } catch (error) { throw safeRefusal(error,"active locator"); }
     const roots=effective.roots;if(!roots)return fail("active locator","unavailable");
     const needed = required(home,ownRoot);
     if(!roots.includes(needed.own))return fail("running CLI","missing");
@@ -113,6 +117,26 @@ export function activePlacementWriterContext(home: string, ownRoot: string): Pla
   } }; return context;
 }
 
+/**
+ * Host sync port bound to this executing installation, never a caller-selected root.
+ * Legacy sync ignores the lazy port. Each invoked v3 check re-reads all expected
+ * inventory and measures every root again; the cached context is not fresh proof.
+ */
+export function createPlacementAttestation(home: string): PlacementCapturePort["attest"] {
+  const base = canonicalPath(home), ownRoot = fileURLToPath(new URL("..", import.meta.url));
+  let context: PlacementWriterContext | undefined;
+  return () => {
+    try {
+      context ??= activePlacementWriterContext(base, ownRoot);
+      return context.attest();
+    } catch (error) {
+      const refusal = safeRefusal(error, "active locator");
+      if (refusal.category === "running CLI") throw new PlacementWriterContextError("host package", refusal.causeClass, refusal.phase, refusal.detail, refusal.renewalState);
+      throw refusal;
+    }
+  };
+}
+
 /** Person preview only: incomplete measurements remain explicit and never become an attestation. */
 export function previewActivePlacementWriters(home: string, ownRoot: string, requested: readonly string[] = []) {
   const effective=readEffectiveSyncPlacementWriters(home),mapped=effective.roots;if(!mapped)return fail("active locator","unavailable");