@staix/agent-mem 0.5.0 → 0.7.0

package/src/memory/lifecycle.ts

@@ -0,0 +1,61 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { SHARD_SCHEMA, effectiveAliases, resolveAlias } from "./aliases.ts";
+import { lifecyclePath, lifecycleStates, listLifecycle, type LifecycleKind, type LifecycleOp, type LifecycleState } from "./lifecycle-log.ts";
+import { readShardDescriptor, shardKeyHash } from "./shard.ts";
+
+export { lifecyclePath, lifecycleStates, listLifecycle, type LifecycleKind, type LifecycleOp, type LifecycleState };
+const KINDS: readonly string[] = ["archive", "unarchive", "forget"];
+
+/**
+ * #15 T5 / D3: the per-project lifecycle. `archive`, `unarchive` and `forget` are append-only ops in `lifecycle.jsonl` of the memory home, in the same
+ * local, never-synced form as `aliases.jsonl` (no shared-v1 segment sees a new op kind). Nothing rewrites a line and nothing deletes a shard: the op
+ * is the whole effect, and every reader consults it. The latest op wins, except that `forgotten` is terminal.
+ *
+ * - archived: the shard stays on disk, but a writable capture store, recall and the brief refuse it, and the catalog lists it as archived.
+ * - forgotten: the project is out of recall and the default listing for good. Its bytes are not erased here (that is what `amem project export`
+ *   and a person's own file deletion are for); the op is the record that the person asked for it.
+ */
+
+const SEVERITY: Record<LifecycleState, number> = { active: 0, archived: 1, forgotten: 2 };
+const worse = (a: LifecycleState, b: LifecycleState): LifecycleState => SEVERITY[a] >= SEVERITY[b] ? a : b;
+
+/**
+ * The state of `key`, alias-aware in both directions: the worse of the key's own state and its canonical key's. An op is recorded on the canonical key, so
+ * an alias to an archived or forgotten project is that state, and a key forgotten before it became an alias of an active project stays forgotten (its own
+ * op is not erased by a later alias line). Terminal: after one `forget`, no later line moves a key back.
+ */
+export function projectState(base: string, key: string): LifecycleState {
+  return lifecycleResolver(base)(key);
+}
+
+/** One pass over both logs, then a lookup per key for a walk of many shards: `state(key)` is exactly `projectState(base, key)`. */
+export function lifecycleResolver(base: string): (key: string) => LifecycleState {
+  const states = lifecycleStates(base), aliases = effectiveAliases(base);
+  return key => worse(states.get(key) ?? "active", states.get(aliases.get(key) ?? key) ?? "active");
+}
+
+/** Refuses a project the person archived or forgot; the one check every writable capture open, recall and brief shares. */
+export function assertProjectActive(base: string, key: string): void {
+  const state = projectState(base, key);
+  if (state !== "active") throw new Error(`project ${resolveAlias(base, key)} is ${state}: ${state === "archived" ? "amem project unarchive brings it back" : "it is out of recall for good"}`);
+}
+
+/**
+ * One person-authorized op. The key resolves through the alias table to the one canonical project, and the transition is checked first so a typo or a
+ * repeat never records an op that means nothing: archive needs an active project, unarchive an archived one, and nothing follows a forget.
+ */
+export function appendLifecycle(base: string, input: { op: LifecycleKind; key: string; actor: string; machine: string; at?: string }): LifecycleOp {
+  if (!KINDS.includes(input.op)) throw new Error("unknown lifecycle op");
+  const requested = input.key.trim();
+  if (!requested || requested.length > 1000) throw new Error("a lifecycle op needs one project key");
+  const key = resolveAlias(base, requested);
+  if (!readShardDescriptor(base, shardKeyHash(key))) throw new Error(`no project shard for ${key}`);
+  const state = projectState(base, key);
+  if (state === "forgotten") throw new Error(`project ${key} is forgotten: nothing follows a forget`);
+  if (input.op === "archive" && state === "archived") throw new Error(`project ${key} is already archived`);
+  if (input.op === "unarchive" && state !== "archived") throw new Error(`project ${key} is not archived`);
+  const op: LifecycleOp = { schema: SHARD_SCHEMA, op: input.op, at: input.at ?? new Date().toISOString(), machine: input.machine, key, actor: input.actor };
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  appendFileSync(lifecyclePath(base), JSON.stringify(op) + "\n", { mode: 0o600 });
+  return op;
+}

package/src/memory/machine.ts

@@ -0,0 +1,31 @@
+import { randomBytes } from "node:crypto";
+import { linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface Machine { id: string; label: string }
+/** Random per `~/.agenthub`, with a person-given label; created on first use. */
+export function machineId(dir: string): Machine {
+  const file = join(dir, "machine.json");
+  const read = (): Machine | undefined => {
+    try {
+      const m = JSON.parse(readFileSync(file, "utf8")) as Machine;
+      if (/^[0-9a-f]{16}$/.test(m?.id)) return { id: m.id, label: typeof m.label === "string" ? m.label : m.id };
+    } catch { /* none, or unreadable */ }
+    return undefined;
+  };
+  const found = read();
+  if (found) return found;
+  // Hubs of several projects can start at once on a fresh home: each writes its own temp file and links it into place,
+  // which fails if another got there first; then everyone reads the one identity that won.
+  const id = randomBytes(8).toString("hex");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ id, label: id }) + "\n", { mode: 0o600 });
+  try { linkSync(tmp, file); } catch { /* another process created it: its identity wins */ } finally { rmSync(tmp, { force: true }); }
+  // A file that is there but holds no valid id is never overwritten (another process may be reading it): the store
+  // fails to open, so the hub says hub memory is unavailable instead of filing notes under no machine.
+  const won = read();
+  if (!won) throw new Error(`${file} holds no valid machine id; remove it and a new one is made`);
+  return won;
+}
+

package/src/memory/metrics.ts

@@ -0,0 +1,63 @@
+import { closeSync, constants, fstatSync, openSync, readSync, appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+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; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
+const METRICS_MAX_BYTES = 64 * 1024, METRICS_KEEP = 200;
+
+export function metricsPath(base: string): string {
+  return join(base, "metrics.jsonl");
+}
+
+/** Append samples, trimming the rolling file when it outgrows its bound (newest samples win). */
+export function appendMetrics(base: string, samples: MetricSample[]): void {
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  const file = metricsPath(base);
+  appendFileSync(file, samples.map((s) => JSON.stringify(s)).join("\n") + "\n", { mode: 0o600 });
+  try {
+    if (statSync(file).size <= METRICS_MAX_BYTES) return;
+    const lines = readFileSync(file, "utf8").split("\n").filter(Boolean).slice(-METRICS_KEEP);
+    writeFileSync(file, lines.join("\n") + "\n", { mode: 0o600 });
+  } catch { /* a trim failure loses nothing: the file simply stays larger */ }
+}
+
+/** The newest samples first-preserved order (oldest to newest); malformed lines are skipped. */
+export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[] {
+  let lines: string[] = [];
+  try { lines = readFileSync(metricsPath(base), "utf8").split("\n").filter(Boolean); } catch { return []; }
+  const out: MetricSample[] = [];
+  for (const line of lines.slice(-limit)) {
+    try {
+      const s = JSON.parse(line) as MetricSample;
+      if ((s?.kind === "hook" || s?.kind === "search") && typeof s.at === "string") out.push(s);
+    } catch { /* a malformed line is skipped */ }
+  }
+  return out;
+}
+
+
+export type CaptureDropReason = "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten";
+const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten"];
+/** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. */
+export function captureDropSummary(base: string): Partial<Record<CaptureDropReason, number>> {
+  const counts: Partial<Record<CaptureDropReason, number>> = {};
+  let fd: number | undefined;
+  try {
+    fd = openSync(metricsPath(base), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd); if (!stat.isFile()) return counts;
+    const start = Math.max(0, stat.size - METRICS_MAX_BYTES), bytes = Buffer.alloc(stat.size - start);
+    const length = readSync(fd, bytes, 0, bytes.length, start);
+    let text = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length));
+    if (start) text = text.slice(text.indexOf("\n") + 1);
+    for (const line of text.split("\n").filter(Boolean).slice(-METRICS_KEEP)) {
+      try {
+        const sample = JSON.parse(line) as MetricSample;
+        if (sample.kind !== "hook" || !DROP_REASONS.includes(sample.captureDropReason!) || !Number.isSafeInteger(sample.captureDrops) || sample.captureDrops! <= 0) continue;
+        const reason = sample.captureDropReason!;
+        counts[reason] = (counts[reason] ?? 0) + sample.captureDrops!;
+      } catch { /* A malformed metric is never a notice. */ }
+    }
+  } catch { /* Metric availability never denies the native call. */ }
+  finally { if (fd !== undefined) closeSync(fd); }
+  return counts;
+}

package/src/memory/mutation.ts

@@ -6,10 +6,11 @@ export const MUTATION_BUSY_TIMEOUT_MS = 3000;
 // ponytail: older hubs (before consuming this agent-mem), raw/legacy log writers and any segment editor
 // that bypasses this lock are not serialized. Require every writer to take it, or make segment appends API-only.
 /** An empty, machine-local SQLite file used only for crash-safe writer exclusion, never for memory data. */
-export function mutationDatabase(dir: string): Database {
+export function mutationDatabase(dir: string, busyTimeoutMs = MUTATION_BUSY_TIMEOUT_MS): Database {
+  if (!Number.isSafeInteger(busyTimeoutMs) || busyTimeoutMs < 0 || busyTimeoutMs > MUTATION_BUSY_TIMEOUT_MS) throw new Error("invalid mutation busy timeout");
   const file = join(dir, "mutation-lock.db"), db = new Database(file, { create: true });
   chmodSync(file, 0o600);
-  db.run(`PRAGMA busy_timeout = ${MUTATION_BUSY_TIMEOUT_MS}`);
+  db.run(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
   return db;
 }
 
@@ -22,13 +23,14 @@ export function acquireMutation(dir: string): (() => void) | undefined {
 }
 
 /** Short local admission fence, never held across sync/network or data mutations. */
-export function readerAdmissionDatabase(dir: string): Database {
+export function readerAdmissionDatabase(dir: string, busyTimeoutMs = MUTATION_BUSY_TIMEOUT_MS): Database {
+  if (!Number.isSafeInteger(busyTimeoutMs) || busyTimeoutMs < 0 || busyTimeoutMs > MUTATION_BUSY_TIMEOUT_MS) throw new Error("invalid reader admission busy timeout");
   const file = join(dir, "reader-admission.db");
   for (const suffix of ["", "-wal", "-shm", "-journal"]) {
     const stat = lstatSync(file + suffix, { throwIfNoEntry: false });
     if (stat && (stat.isSymbolicLink() || !stat.isFile())) throw new Error("reader admission fence is not a regular file");
   }
   const db = new Database(file, { create: true });
-  try { chmodSync(file, 0o600); db.run(`PRAGMA busy_timeout = ${MUTATION_BUSY_TIMEOUT_MS}`); return db; }
+  try { chmodSync(file, 0o600); db.run(`PRAGMA busy_timeout = ${busyTimeoutMs}`); return db; }
   catch (error) { db.close(); throw error; }
 }

package/src/memory/note-add.ts

@@ -0,0 +1,100 @@
+import { KINDS, type Kind, type MemoryStore, type NoteInput, type Scope, type Tier } from "./store.ts";
+import type { StandalonePolicy } from "./policy.ts";
+
+/**
+ * F6 (agent-mem#40): person note authoring. `amem note add` writes one curated note the person typed, through the configured policy. The note is authored by the
+ * person (`peer: "person"`, `source: "person"`), which is why the command is person-only like every ordinary command (an agent marker is refused before it runs).
+ *
+ * A `fail` note carries structured fields. Its body uses the same labelled lines an accepted `fail` candidate produces, so a note written here and one accepted
+ * from `amem_remember` read alike and `fail` search and the plan guard see one shape.
+ */
+export const NOTE_MAX_CHARS = 4000, NOTE_TITLE_MAX = 200, FAIL_FIELD_MAX = 1000, FAIL_EVIDENCE_MAX = 16;
+
+export interface FailFields { approach: string; symptom: string; cause: string; evidence: string[]; retryWhen: string }
+export interface NoteAddInput { kind: Kind; tier: Tier; scope: Scope; text?: string; title?: string; fail?: Partial<FailFields> }
+export interface NoteAddResult { id: string }
+
+const refuse = (message: string): never => { throw new Error(message); };
+const clean = (value: string | undefined): string => (value ?? "").replace(/\r\n?/g, "\n").trim();
+/** Every character a reader may treat as a line break: LF, CR, VT, FF, NEL and the Unicode line and paragraph separators. A field with any of them could forge a labelled line. */
+export const LINE_BREAKS = /[\n\r\v\f\u0085\u2028\u2029]/;
+export const oneLine = (value: string): string => value.replace(/\s*[\n\r\v\f\u0085\u2028\u2029]+\s*/g, " ");
+
+/** The labelled body of a `fail` note: the exact lines an accepted fail candidate has, without the "Accepted candidate" provenance header. */
+export function failBody(fields: FailFields): string {
+  return `Approach: ${oneLine(fields.approach)}\nSymptom: ${oneLine(fields.symptom)}\nCause: ${oneLine(fields.cause)}\nEvidence: ${fields.evidence.map(oneLine).join(", ")}\nRetry when: ${oneLine(fields.retryWhen)}`;
+}
+
+/** Validate the structured fields and say which are missing, so the person can fix the command rather than guess. */
+function failFields(raw: Partial<FailFields> | undefined): FailFields {
+  const missing = ["approach", "symptom", "cause", "retryWhen"].filter(key => !clean(raw?.[key as keyof FailFields] as string | undefined));
+  const evidence = (raw?.evidence ?? []).map(clean).filter(Boolean);
+  const flags = { approach: "--approach", symptom: "--symptom", cause: "--cause", retryWhen: "--retry-when" } as Record<string, string>;
+  if (missing.length || !evidence.length) refuse(`a fail note needs ${[...missing.map(key => flags[key]!), ...(evidence.length ? [] : ["--evidence"])].join(", ")} (approach, symptom, cause, evidence and retry-when are all required, so the next reader knows when the approach is worth retrying)`);
+  if (evidence.length > FAIL_EVIDENCE_MAX) refuse(`a fail note takes at most ${FAIL_EVIDENCE_MAX} --evidence values`);
+  const out: FailFields = { approach: clean(raw!.approach), symptom: clean(raw!.symptom), cause: clean(raw!.cause), evidence, retryWhen: clean(raw!.retryWhen) };
+  for (const [key, value] of Object.entries(out)) for (const item of Array.isArray(value) ? value : [value]) {
+    if (item.length > FAIL_FIELD_MAX) refuse(`a fail note's ${key} is over ${FAIL_FIELD_MAX} characters`);
+    if (item.includes("\0")) refuse(`a fail note's ${key} holds a NUL byte`);
+  }
+  return out;
+}
+
+/** Build the note a command would write, without writing it (the preview and the write share this). */
+export function buildNote(input: NoteAddInput, project: string): NoteInput {
+  if (!(KINDS as readonly string[]).includes(input.kind)) refuse(`--kind takes ${KINDS.join(", ")}`);
+  if (input.tier !== "short" && input.tier !== "long") refuse("--tier takes short or long");
+  if (input.scope !== "project" && input.scope !== "shared") refuse("--scope takes project or shared");
+  const title = input.title === undefined ? undefined : clean(input.title);
+  if (title !== undefined && (!title || title.length > NOTE_TITLE_MAX || title.includes("\0") || LINE_BREAKS.test(title))) refuse(`--title must be one line of 1 to ${NOTE_TITLE_MAX} characters`);
+  let text: string;
+  if (input.kind === "fail") {
+    // The structured fields ARE the body. A free text is refused with them so there is one answer to "what does this fail note say".
+    if (clean(input.text)) refuse("a fail note takes --approach, --symptom, --cause, --evidence and --retry-when, not free text");
+    text = failBody(failFields(input.fail));
+  } else {
+    if (input.fail && Object.values(input.fail).some(value => (Array.isArray(value) ? value.length : clean(value as string | undefined)))) refuse("--approach, --symptom, --cause, --evidence and --retry-when belong to --kind fail");
+    text = clean(input.text);
+    if (!text) refuse("a note needs text: pass it as an argument, `-` for stdin, or run in a terminal to use $EDITOR");
+    if (text.includes("\0")) refuse("the note text holds a NUL byte");
+  }
+  if (text.length > NOTE_MAX_CHARS) refuse(`the note is ${text.length} characters; the limit is ${NOTE_MAX_CHARS}`);
+  return { op: "note", project, scope: input.scope, tier: input.tier, kind: input.kind, peer: "person", source: "person", ...(title ? { title } : {}), text, about: [] };
+}
+
+/**
+ * Write one note. The configured policy screens the whole note (title and text) first and a decline names no text; a long-term note the policy declines would not
+ * sync, so it is refused here instead of silently staying local. Nothing is written when anything fails.
+ */
+export function noteAdd(store: MemoryStore, project: string, input: NoteAddInput, policy: StandalonePolicy): NoteAddResult {
+  const note = buildNote(input, project);
+  if (!policy.screenStandalone({ ...(note.title ? { title: note.title } : {}), text: note.text, about: note.about })   /* no undefined field: the screen refuses one */) refuse("the note is refused by the configured privacy policy (secrets, personal data, deny paths and the patterns in amem.config.json); edit it or the policy and try again");
+  return { id: store.note(note, input.tier === "short") };
+}
+
+/** What `$EDITOR` opens for a `fail` note given no field flags: five labelled lines the person fills in. */
+export const FAIL_TEMPLATE = "Approach: \nSymptom: \nCause: \nEvidence: \nRetry when: \n";
+const LABELS = [["approach", "Approach"], ["symptom", "Symptom"], ["cause", "Cause"], ["evidence", "Evidence"], ["retryWhen", "Retry when"]] as const;
+/** Whether any line of `text` starts with one of the five labels (case-insensitive). Text that already carries a label is the person's own structure, so it opens as written. */
+export function hasFailLabel(text: string): boolean {
+  return text.replace(/\r\n?|\u0085|\u2028|\u2029|\v|\f/g, "\n").split("\n").some(line => LABELS.some(([, label]) => line.toLowerCase().startsWith(`${label.toLowerCase()}:`)));
+}
+/** Read the labelled template back. A label's value runs to the next label (so it may span lines); evidence splits on commas and newlines. */
+export function parseFailTemplate(raw: string): Partial<FailFields> {
+  const out: Record<string, string> = {};
+  let current: string | undefined;
+  for (const line of raw.replace(/\r\n?|\u0085|\u2028|\u2029|\v|\f/g, "\n").split("\n")) {
+    const hit = LABELS.find(([, label]) => line.toLowerCase().startsWith(`${label.toLowerCase()}:`));
+    if (hit) {
+      // A label given twice would silently keep only the last: refuse it, so no text the person typed is dropped without a word.
+      if (hit[0] in out) throw new Error(`the template repeats the "${hit[1]}:" label; each of the five labels takes one entry`);
+      current = hit[0]; out[current] = line.slice(hit[1].length + 1).trim();
+    }
+    else if (current) out[current] = `${out[current]}\n${line}`;
+  }
+  // Trim first, then test: a blank template line is "" after the trim, never a truthy "\n".
+  const value = (key: string) => (out[key] ?? "").trim();
+  const evidence = value("evidence").split(/[,\n]/).map(item => item.trim()).filter(Boolean);
+  return { ...(value("approach") ? { approach: value("approach") } : {}), ...(value("symptom") ? { symptom: value("symptom") } : {}), ...(value("cause") ? { cause: value("cause") } : {}),
+    ...(evidence.length ? { evidence } : {}), ...(value("retryWhen") ? { retryWhen: value("retryWhen") } : {}) };
+}

package/src/memory/path-glob.ts

@@ -0,0 +1,94 @@
+/**
+ * `pii.paths` matching, ported from agent-hub (`src/hub/path-policy.ts`: `policyPaths`, `patternScope`, `matchesPolicyLexically`; `src/hub/memory-policy.ts`:
+ * `mentionsPrivatePath`) so the repo scope screens with the semantics the project's own config was written for: exact paths and subtrees, `*`, `?` and
+ * whole-segment `**` globs, case and Unicode folded like a case-insensitive disk. amem imports no agent-hub code, so this is a port, and
+ * `test/path-policy-parity.test.ts` pins it to values produced by the hub's real matcher (`scripts/gen-path-policy-parity.ts`).
+ *
+ * Lexical only. The hub's `matchesPolicy` also resolves real paths and symlink aliases against the filesystem; a note merely names a path, so nothing here
+ * reads the disk. The port keeps the hub's `includeParents` stance (a directory that could hold a protected descendant counts), the over-protective side:
+ * for a file that exists the hub is narrower, never broader.
+ * ponytail: no symlink alias discovery. Upgrade: ask the host (agent-hub) for the verdict through the library API once amem has a host policy port for paths.
+ */
+import { posix } from "node:path";
+import { nodePath, pathCandidates } from "./project.ts";
+
+/** One spelling per name, as a case-insensitive disk sees it (agent-hub `foldSegment`). */
+const foldSegment = (segment: string): string => segment.normalize("NFKC").replace(/\p{Default_Ignorable_Code_Point}/gu, "").toLowerCase().toUpperCase().toLowerCase();
+
+/** Bounded project-relative exact paths/subtrees or `*`, `?` and whole-segment `**` globs (agent-hub `policyPaths`). Throws on anything the hub would refuse. */
+export function policyEntries(raw: unknown, field: string): string[] {
+  const bad = raw === undefined ? false : !Array.isArray(raw) || raw.length > 64 || raw.some(p => typeof p !== "string" || !p || p.length > 200 || posix.isAbsolute(p) || /^[A-Za-z]:/.test(p) || /[\[\]{}!]/.test(p) || /[\x00-\x1f\x7f]/.test(p) || p.split(/[\\/]/).includes("..")
+    || (/[?*]/.test(p) && (p.includes("\\") || (p.match(/[?*]/g)?.length ?? 0) > 16 || p.split("/").some(s => s.includes("**") && s !== "**"))));
+  if (bad) throw new Error(`${field} takes up to 64 bounded project-relative paths or *, ? and whole-segment ** patterns of at most 200 characters (no absolute paths, .., brackets, braces or !)`);
+  if (raw === undefined) return [];
+  return [...new Set((raw as string[]).map(p => p.replace(/\/+/g, "/").replace(/\/$/, "") || "."))];
+}
+
+const within = (path: string, root: string) => path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`);
+const beneath = (path: string, root: string) => within(path.toLowerCase(), root.toLowerCase()) || within(foldSegment(path), foldSegment(root));
+
+/** Either spelling protects: the lowercase comparison keeps `?` matching one code point whose fold expands, the folded one catches NFD/NFC and compatibility aliases. */
+const segmentMatches = (pattern: string, name: string): boolean => wildcard(pattern.toLowerCase(), name.toLowerCase()) || wildcard(foldSegment(pattern), foldSegment(name));
+/** Linear-space wildcard DP, no regex backtracking on untrusted paths. */
+function wildcard(pattern: string, name: string): boolean {
+  const chars = [...name];
+  let previous = new Array<boolean>(chars.length + 1).fill(false); previous[0] = true;
+  for (const char of pattern) {
+    const next = new Array<boolean>(chars.length + 1).fill(false);
+    next[0] = char === "*" && previous[0]!;
+    for (let i = 1; i <= chars.length; i++) next[i] = char === "*" ? previous[i]! || next[i - 1]! : previous[i - 1]! && (char === "?" || char === chars[i - 1]);
+    previous = next;
+  }
+  return previous[chars.length]!;
+}
+function closure(pattern: string[], states: Set<number>): Set<number> {
+  const out = new Set(states);
+  for (const i of out) if (pattern[i] === "**") out.add(i + 1);
+  return out;
+}
+function advance(pattern: string[], states: Set<number>, name: string): Set<number> {
+  const next = new Set<number>();
+  for (const i of closure(pattern, states)) {
+    if (pattern[i] === "**") next.add(i);
+    else if (pattern[i] !== undefined && segmentMatches(pattern[i]!, name)) next.add(i + 1);
+  }
+  return closure(pattern, next);
+}
+function patternScope(pattern: string[], path: string, includeParents: boolean): boolean {
+  if (posix.isAbsolute(path) || path === ".." || path.startsWith("../")) return false;
+  let states = closure(pattern, new Set([0]));
+  if (states.has(pattern.length)) return true;
+  for (const name of path.split("/").filter(p => p && p !== ".")) {
+    states = advance(pattern, states, name);
+    if (states.has(pattern.length)) return true; // a matched directory protects its entire subtree
+    if (!states.size) return false;
+  }
+  return includeParents && states.size > 0; // this scope can contain a future protected descendant
+}
+
+const ROOT = "/project";
+const segments = (entry: string) => entry.split("/").filter(p => p && p !== ".");
+
+/** Whether `path` (project-relative as written in a note) falls under any entry: the hub's `matchesPolicy` without the filesystem. */
+export function matchesEntries(path: string, entries: readonly string[], includeParents = true): boolean {
+  if (!entries.length) return false;
+  try {
+    if (path.length > 4096) return true;
+    const lexical = posix.resolve(ROOT, path), relative = posix.relative(ROOT, lexical);
+    return entries.some(entry => {
+      if (/[?*]/.test(entry)) return patternScope(segments(entry), relative, includeParents);
+      const target = posix.resolve(ROOT, entry);
+      return beneath(lexical, target) || includeParents && beneath(target, lexical) || patternScope([...segments(entry), "**"], relative, includeParents);
+    });
+  } catch { return true; }
+}
+
+/** Whether a note's text or its path links name a private path (agent-hub `mentionsPrivatePath`): written paths, and an entry's literal part written out. */
+export function mentionsPrivatePath(text: string, about: readonly string[], entries: readonly string[]): boolean {
+  if (!entries.length) return false;
+  const nfc = (value: string) => value.normalize("NFC"), body = nfc(text), policy = entries.map(nfc);
+  const paths = [...about.map(nodePath), ...pathCandidates(body)].filter((p): p is string => p !== undefined).map(nfc);
+  if (paths.some(path => matchesEntries(path, policy, true))) return true;
+  // The entry's literal part (up to its first glob character) written out: catches a path a word split breaks (a space).
+  return policy.some(entry => { const literal = entry.replace(/^\.\//, "").split(/[*?[\]{}]/)[0]!.replace(/\/+$/, ""); return /[/\s]/.test(literal) && body.includes(literal); });
+}

package/src/memory/plan-guard.ts

@@ -0,0 +1,47 @@
+import { extractNodes, type View } from "./store.ts";
+import { nodePath } from "./project.ts";
+
+export interface PlanGuardContext { cwd: string; project: string; repo: string; deny?: string[]; now?: () => number }
+/** Structural input accepts host task adapters without importing a host or a task board. */
+export interface PlanGuardInput {
+  paths?: readonly string[]; symbols?: readonly string[];
+  refs?: { paths?: readonly string[] };
+  plan?: { paths?: readonly string[]; symbols?: readonly string[] };
+}
+export function normalizeMemorySymbolInput(value: string): string {
+  const at = value.lastIndexOf("@"), name = at < 0 ? value : value.slice(0, at);
+  const normalized = name.startsWith("section ") || name.startsWith("source ") ? name : name.replace(/\s*\(.*$/, "").trim();
+  return at < 0 ? normalized : `${normalized}@${value.slice(at + 1)}`;
+}
+/** Explicit inputs only. Per-input extraction retains more than v1's 64-node extraction cap. */
+export function planGuardNodes(input: PlanGuardInput, context: PlanGuardContext): string[] {
+  const nodes = new Set<string>();
+  for (const path of [...input.paths ?? [], ...input.refs?.paths ?? [], ...input.plan?.paths ?? []]) {
+    for (const node of extractNodes("", { ...context, paths: [path], checkExists: false })) nodes.add(node);
+  }
+  const only = nodes.size === 1 ? nodePath([...nodes][0]!) : undefined;
+  for (const symbol of [...input.symbols ?? [], ...input.plan?.symbols ?? []]) {
+    if (typeof symbol !== "string") continue;
+    const at = symbol.lastIndexOf("@");
+    const explicitPath = at < 0 ? undefined : extractNodes("", { ...context, paths: [symbol.slice(at + 1)], checkExists: false })[0];
+    if (at >= 0 && !explicitPath) continue;
+    const qualified = explicitPath ? `${symbol.slice(0, at)}@${nodePath(explicitPath)}` : symbol;
+    for (const form of new Set([qualified, normalizeMemorySymbolInput(qualified)])) {
+      for (const node of extractNodes("", { ...context, paths: only ? [only] : [], symbols: [form], checkExists: false })) nodes.add(node);
+    }
+  }
+  return [...nodes].sort();
+}
+const samePath = (a: string, b: string) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+/** Symbols require name and file identity; path scopes intersect only on whole components. */
+export function planNodesIntersect(left: string, right: string): boolean {
+  if (left === right) return true;
+  if (left.startsWith("symbol:") && right.startsWith("symbol:")) return normalizeMemorySymbolInput(left.slice(7)) === normalizeMemorySymbolInput(right.slice(7));
+  const a = nodePath(left), b = nodePath(right);
+  return !!a && !!b && samePath(a, b);
+}
+/** Callers screen complete live notes first; this pure matcher performs no I/O or writes. */
+export function matchingPlanFails<T extends Pick<View, "kind" | "about" | "supersededBy"> & Partial<Pick<View, "expiresAt">>>(input: PlanGuardInput, notes: readonly T[], context: PlanGuardContext): T[] {
+  const nodes = planGuardNodes(input, context), now = (context.now ?? Date.now)();
+  return nodes.length && Number.isFinite(now) ? notes.filter(note => note.kind === "fail" && !note.supersededBy && (note.expiresAt == null || Number.isFinite(Date.parse(note.expiresAt)) && Date.parse(note.expiresAt) > now) && note.about.some(about => nodes.some(node => planNodesIntersect(node, about)))) : [];
+}

package/src/memory/platform.ts

@@ -1,7 +1,12 @@
 // Single-source platform helpers. Hub, local and Pi modules re-export these functions unchanged.
 import { realpathSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
-import { spawnSync, execFileSync, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from "node:child_process";
+import type { SpawnSyncOptionsWithStringEncoding, SpawnSyncReturns } from "node:child_process";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+let processes: typeof import("node:child_process") | undefined;
+// Path/policy-only hook parents never need a process module. Node-safe synchronous users load it on demand.
+const childProcess = () => processes ??= require("node:child_process") as typeof import("node:child_process");
 import { createHash } from "node:crypto";
 
 const canonical = (path: string): string => {
@@ -33,7 +38,7 @@ export function realPath(path: string): string {
     // The path as given: resolve() would fold a `..` after a symlink by text. GNU realpath accepts a dangling last
     // component unless told -e; the BSD one on macOS refuses it by default.
     const argv = process.platform === "darwin" ? ["/bin/realpath", "--", path] : ["realpath", "-e", "--", path];
-    const r = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8" });
+    const r = childProcess().spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8" });
     if (r.status !== 0 || !r.stdout.endsWith("\n")) throw error;
     return r.stdout.slice(0, -1);
   }
@@ -94,7 +99,7 @@ export function memoryGitEnv(env: NodeJS.ProcessEnv = process.env, options: { re
 /** spawnSync form of the same call: the env option is merged with memoryGitEnv, everything else passes through. */
 export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {
   const argv = memoryGitArgv(args);
-  return spawnSync(argv[0]!, argv.slice(1), { ...options, env: memoryGitEnv(options.env ?? process.env) });
+  return childProcess().spawnSync(argv[0]!, argv.slice(1), { ...options, env: memoryGitEnv(options.env ?? process.env) });
 }
 
 /**
@@ -109,7 +114,7 @@ export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStrin
  */
 export function processSignature(pid: number): string | undefined {
   try {
-    const text = execFileSync("ps", ["-p", String(pid), "-o", "lstart=,comm="], { encoding: "utf8", env: { ...process.env, LC_ALL: "C", TZ: "UTC" } }).trim();
+    const text = childProcess().execFileSync("ps", ["-p", String(pid), "-o", "lstart=,comm="], { encoding: "utf8", env: { ...process.env, LC_ALL: "C", TZ: "UTC" } }).trim();
     return text ? createHash("sha256").update(text).digest("hex") : undefined;
   } catch { return undefined; }
 }

package/src/memory/policy.ts

@@ -6,6 +6,18 @@ import { nodePath, pathCandidates } from "./project.ts";
 
 /** True means the complete value is public. Hosts may narrow, never replace, standalone policy. */
 export interface MemoryPolicy { screen(value: unknown): Promise<boolean> }
+/**
+ * The standalone policy. `screenStandalone` is its own part only (secrets, default PII, configured PII patterns and deny paths) as a synchronous
+ * answer, for callers that cannot await (the store's promotion screen); it never asks the host, so a caller with a host uses `screen`.
+ */
+export interface StandalonePolicy extends MemoryPolicy {
+  screenStandalone(value: unknown): boolean;
+  /**
+   * Only the personal-data and configured-pattern and deny-path part of `screenStandalone`, without the secret screen, for a caller that counts secrets
+   * separately (the claude-mem import reports `pii` and `secret` skips as two numbers). True means the value names personal data or something configured.
+   */
+  declinesPersonal(text: string): boolean;
+}
 export interface StandalonePolicyOptions {
   denyPaths?: readonly string[];
   /** Case-insensitive literal substrings, not executable regular expressions. */
@@ -14,7 +26,7 @@ export interface StandalonePolicyOptions {
 }
 
 const MAX_DEPTH = 16, MAX_NODES = 4096, MAX_BYTES = 256 * 1024, MAX_STRING_BYTES = 16 * 1024;
-const fold = (text: string) => text.normalize("NFKC").replace(/\p{Default_Ignorable_Code_Point}/gu, "").toLowerCase().replace(/\\/g, "/");
+export const fold = (text: string) => text.normalize("NFKC").replace(/\p{Default_Ignorable_Code_Point}/gu, "").toLowerCase().replace(/\\/g, "/");
 const flags = new Set(["private", "pii", "privateturn", "isprivate", "ispii"]);
 
 /** Inspect descriptors, not getters/toJSON, and build the only value a host is allowed to see. */
@@ -67,6 +79,9 @@ function snapshot(value: unknown): { value: unknown; texts: string[] } | undefin
   catch { return undefined; }
 }
 
+/** Safe structural data copy for optional readers, before any getters/toJSON can run. It is not a public verdict. */
+export function memoryPolicySnapshot<T>(value: T): T | undefined { return snapshot(value)?.value as T | undefined; }
+
 function literals(value: unknown, label: string): string[] {
   if (value === undefined) return [];
   if (types.isProxy(value) || !Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || value.length > 64 || Object.getOwnPropertySymbols(value).length) throw new Error(`invalid ${label}`);
@@ -92,7 +107,7 @@ function defaultPii(text: string): boolean {
 }
 
 /** No filesystem, model, network or storage work occurs while constructing or screening this policy. */
-export function createStandalonePolicy(options: StandalonePolicyOptions = {}): MemoryPolicy {
+export function createStandalonePolicy(options: StandalonePolicyOptions = {}): StandalonePolicy {
   if (!options || typeof options !== "object" || types.isProxy(options) || Object.getPrototypeOf(options) !== Object.prototype || Object.getOwnPropertySymbols(options).length) throw new Error("invalid standalone policy options");
   const descriptors = Object.getOwnPropertyDescriptors(options);
   for (const [key, descriptor] of Object.entries(descriptors)) if (!["denyPaths", "piiPatterns", "host"].includes(key) || !("value" in descriptor)) throw new Error("invalid standalone policy options");
@@ -100,20 +115,36 @@ export function createStandalonePolicy(options: StandalonePolicyOptions = {}): M
   const pii = literals(descriptors.piiPatterns?.value, "PII patterns");
   const host = descriptors.host?.value as MemoryPolicy | undefined;
   if (host !== undefined && (!host || typeof host.screen !== "function")) throw new Error("invalid host policy");
+  const standalone = (value: unknown): { ok: boolean; value?: unknown } => {
+    try {
+      const complete = snapshot(value);
+      if (!complete) return { ok: false };
+      for (const text of complete.texts) {
+        if (looksSecret(text) || looksSecret(text.replace(/["']/g, ""))) return { ok: false };
+        const normalized = fold(text);
+        if (defaultPii(normalized) || pii.some(pattern => normalized.includes(pattern))) return { ok: false };
+        const candidates = normalized.includes("/") || /\.[a-z]/.test(normalized) ? pathCandidates(normalized) : [];
+        const paths = [normalized, nodePath(normalized), ...candidates, ...normalized.split(/[\s"'`(){}\[\],;:=<>]+/)];
+        for (const path of paths) if (path && isDenied(posix.normalize(path), deny)) return { ok: false };
+      }
+      return { ok: true, value: complete.value };
+    } catch { return { ok: false }; }
+  };
+  const personal = (text: string): boolean => {
+    const normalized = fold(text);
+    if (defaultPii(normalized) || pii.some(pattern => normalized.includes(pattern))) return true;
+    const candidates = normalized.includes("/") || /\.[a-z]/.test(normalized) ? pathCandidates(normalized) : [];
+    const paths = [normalized, nodePath(normalized), ...candidates, ...normalized.split(/[\s"'`(){}\[\],;:=<>]+/)];
+    return paths.some(path => path && isDenied(posix.normalize(path), deny));
+  };
   return {
+    screenStandalone: value => standalone(value).ok,
+    declinesPersonal: text => personal(text),
     async screen(value: unknown): Promise<boolean> {
       try {
-        const complete = snapshot(value);
-        if (!complete) return false;
-        for (const text of complete.texts) {
-          if (looksSecret(text) || looksSecret(text.replace(/["']/g, ""))) return false;
-          const normalized = fold(text);
-          if (defaultPii(normalized) || pii.some(pattern => normalized.includes(pattern))) return false;
-          const candidates = normalized.includes("/") || /\.[a-z]/.test(normalized) ? pathCandidates(normalized) : [];
-          const paths = [normalized, nodePath(normalized), ...candidates, ...normalized.split(/[\s"'`(){}\[\],;:=<>]+/)];
-          for (const path of paths) if (path && isDenied(posix.normalize(path), deny)) return false;
-        }
-        return host === undefined || await host.screen(complete.value) === true;
+        const own = standalone(value);
+        if (!own.ok) return false;
+        return host === undefined || await host.screen(own.value) === true;
       } catch { return false; }
     },
   };

package/src/memory/private-spans.ts

@@ -0,0 +1,32 @@
+/**
+ * `<private>...</private>` spans (the claude-mem convention) are dropped before anything else reads the text, so they are never screened, counted or
+ * stored. A leaf module with no imports: capture shaping, the candidate and work-list boundaries, notes, goals and imports all use it.
+ *
+ * Tags match the way an HTML reader would, so a variant cannot slip a span through: the name is case-insensitive, an opening tag may carry attributes
+ * (`<private class="x">`), whitespace before the name (`< private>`) and a self-closing slash (`<private/>`, which opens a span like any other opening
+ * tag, since a person who typed it meant what follows to stay private). A closing tag is `</private>` with the same latitude. Nested spans close from the
+ * inside out. An unclosed span drops everything to the end of the text. A stray closing tag is kept as plain text. `<privateer>` is not a tag.
+ */
+const TAG = /<\s*(\/?)\s*private(?=[\s/>])[^<>]*>/gi;
+
+export function stripPrivateSpans(text: string): string {
+  if (!/<\s*\/?\s*private(?=[\s/>])/i.test(text)) return text;
+  let out = "", depth = 0, last = 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++;
+    last = match.index + match[0].length;
+  }
+  if (depth === 0) out += text.slice(last);
+  return out;
+}
+
+/** The same strip over every string inside a plain value (one level of arrays and objects, as the callers' inputs are), leaving other values as they are. */
+export function stripPrivateDeep<T>(value: T, depth = 0): T {
+  if (typeof value === "string") return stripPrivateSpans(value) as T;
+  if (depth > 4 || value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(item => stripPrivateDeep(item, depth + 1)) as T;
+  return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, item]) => [key, stripPrivateDeep(item, depth + 1)])) as T;
+}