@staix/agent-mem 0.20.2 → 0.21.0

package/src/setup.ts

@@ -39,6 +39,8 @@ export interface SetupContext {
   env?: Env; bun?: string; entry?: string; stdinTTY?: boolean; cwd?: string;
   /** `--root`: an absolute amem install root to register instead of the running one (#199). Ignored when `entry` is given. */
   root?: string;
+  /** `--adopt-current` (#241): with apply, set a stale receipt aside and adopt the live wiring as the new baseline. A receipt that is not stale is kept. */
+  adoptCurrent?: boolean;
   /** @deprecated Retained for source compatibility; explicit apply/undo modes do not prompt. */
   confirm?: (plan: SetupPlan) => Promise<boolean>;
   /** Host-only race fixture, called after temporary-file fsync and before the final comparison/rename. */
@@ -271,8 +273,14 @@ export function planSetup(target: string, mode: SetupPlan["mode"] = "preview", o
   if (target === "all") pluginNotes.push("Antigravity is repository-scoped and excluded from all; run amem setup agy explicitly inside its repository.");
   if (targets.includes("jcode")) pluginNotes.push("Launch Jcode with JCODE_DISABLE_CLAUDE_MCP=1 and without a same-name project override: imported Claude stdio entries can replace this private amem binding with a shared daemon-cwd server. Use a new workspace-bound session when changing projects.");
   return { targets, mode, ...(c.root ? { root: c.root } : {}), actions: targets.map(target => {
-    const prior = receipt(c, target, false), files = mode === "undo" && prior ? prior.changes.map(change => change.path) : c.paths[target];
+    const receipted = receipt(c, target, false), files = mode === "undo" && receipted ? receipted.changes.map(change => change.path) : c.paths[target];
     for (const file of files) read(file);
+    const stale = mode !== "undo" && !!receipted && staleReceipt(target, receipted);
+    if (stale) pluginNotes.push(options.adoptCurrent
+      ? `${target}: the setup receipt is stale (its managed entries were replaced at another amem install root outside setup). Apply keeps it as ${journal(c, target)}.stale-<UTC time> and adopts the current wiring; --undo then restores that wiring.`
+      : `${target}: the setup receipt is stale (its managed entries were replaced at another amem install root outside setup). Apply refuses; rerun with --apply --adopt-current to keep the receipt aside and adopt the current wiring, which --undo then restores.`);
+    // An adopted stale receipt plans like the receipt-less path that apply takes.
+    const prior = stale && options.adoptCurrent ? undefined : receipted;
     if (mode === "undo" && prior?.changes.some((change, index) => change.path !== c.paths[target][index])) {
       pluginNotes.push(`${target}: undo restores the historical receipt files, not the new personal source: ${prior.changes.map(change => change.path).join(", ")}`);
     }
@@ -295,7 +303,7 @@ export function planSetup(target: string, mode: SetupPlan["mode"] = "preview", o
     const add = command(target, c.bun, c.entry), remove = target === "gemini" ? [...GEMINI_REMOVE] : [target, "mcp", "remove", ...(target === "claude" || target === "qwen" ? ["--scope", "user"] : []), "amem"];
     const installed = available(c, target, options), version = installed && target !== "agy" && mode !== "undo" ? probeClientVersion(c, target, options) : undefined;
     if (version?.matches === false) pluginNotes.push(`WARNING: ${target} version ${version.output}; layout verified on ${version.verified}. Apply remains guarded by native configuration validation.`);
-    return { target, available: installed, ...(version ? { version } : {}), files, receipt: journal(c, target), ...(target === "agy" ? { cwd: c.workspace!.root } : {}), registration: mode === "undo" ? null : add, lifecycle: mode === "undo" ? "restore original MCP/hook files" : lifecycle(target), hooks: mode === "undo" || unchanged ? [] : plannedHooks(c, target), mcpChange: mode === "undo" ? prior ? "restore" : "unchanged" : unchanged ? "unchanged" : hasAmem ? "replace" : "add", commands: mode === "undo" || prior?.intent === intent(c, target) || !add || !installed ? [] : [...(hasAmem ? [remove] : []), add], state: prior && prior.intent !== intent(c, target) ? "runtime changed; managed entries will update" : prior?.phase ?? "not installed" };
+    return { target, available: installed, ...(version ? { version } : {}), files, receipt: journal(c, target), ...(target === "agy" ? { cwd: c.workspace!.root } : {}), registration: mode === "undo" ? null : add, lifecycle: mode === "undo" ? "restore original MCP/hook files" : lifecycle(target), hooks: mode === "undo" || unchanged ? [] : plannedHooks(c, target), mcpChange: mode === "undo" ? prior ? "restore" : "unchanged" : unchanged ? "unchanged" : hasAmem ? "replace" : "add", commands: mode === "undo" || prior?.intent === intent(c, target) || !add || !installed ? [] : [...(hasAmem ? [remove] : []), add], state: stale ? options.adoptCurrent ? "stale receipt; current wiring will be adopted" : "stale receipt; apply needs --adopt-current" : prior && prior.intent !== intent(c, target) ? "runtime changed; managed entries will update" : prior?.phase ?? "not installed" };
   }), notes: [...pluginNotes, ...(/\/[^/]*\d+\.\d+[^/]*\/(?:bin\/)?bun$/.test(c.bun) ? ["this bun path is version-specific; rerun setup --apply after changing Bun"] : []), "Preview only unless --apply or --undo is passed; explicit modes apply without a prompt.", "Native registration commands run in a private staging HOME; only the listed configuration files are published.", "Original file bytes restore exactly when untouched; otherwise undo preserves CLI-owned changes and restores only managed entries, refusing edits to those entries.", "No AGENTS.md, CLAUDE.md or rule files are edited.", `A private ${join(c.state, "setup.lock")} serializes mutations; temporary ${join(realPath(tmpdir()), "amem-setup-*")} staging homes are removed.`, "Codex requires its native /hooks review before newly registered hooks run; setup does not grant hook trust. Runtime registrations use the PATH-resolved absolute Bun path without resolving its stable symlink; setup all reports and skips missing clients."] };
 }
 /** Native probes and registration share one private HOME, cwd and configuration layout. */
@@ -393,16 +401,56 @@ function piExtension(bun: string, entry: string): string {
 function previousRuntimes(target: SetupTarget, images: readonly Image[], bun: string, entry: string): { bun: string; entry: string }[] {
   const found = new Map<string, { bun: string; entry: string }>();
   for (const image of images) {
-    const value = mcpRecord(target, image);
-    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
-    const server = value as Record<string, unknown>, args = server.args;
-    if (typeof server.command === "string" && isAbsolute(server.command) && Array.isArray(args) && args.length === 3
-      && args[0] === "--smol" && typeof args[1] === "string" && isAbsolute(args[1]) && args[2] === "mcp"
-      && (server.command !== bun || args[1] !== entry)) found.set(JSON.stringify([server.command, args[1]]), { bun: server.command, entry: args[1] });
+    const runtime = launcher(mcpRecord(target, image));
+    if (runtime && (runtime.bun !== bun || runtime.entry !== entry)) found.set(JSON.stringify([runtime.bun, runtime.entry]), runtime);
   }
   return [...found.values()];
 }
-interface Prepared { value: Receipt; expected: Image[]; unchanged: boolean }
+/** The runtime of a generated `<bun> --smol <entry> mcp` server record, if the record is exactly that shape. */
+function launcher(value: unknown): { bun: string; entry: string } | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return;
+  const server = value as Record<string, unknown>, args = server.args;
+  return typeof server.command === "string" && isAbsolute(server.command) && Array.isArray(args) && args.length === 3
+    && args[0] === "--smol" && typeof args[1] === "string" && isAbsolute(args[1]) && args[2] === "mcp" ? { bun: server.command, entry: args[1] } : undefined;
+}
+/** Generated capture commands of a prior runtime, current and pre-#145 (no `--json`) forms. */
+const priorCaptures = (launches: readonly string[], kind: string) => launches.flatMap(launch => [`${launch} ingest ${kind} --json`, `${launch} ingest ${kind}`]);
+const STALE_RECEIPT = "setup receipt is stale: its managed entries were replaced at another amem install root; rerun with --adopt-current to adopt the current wiring";
+/**
+ * #241: the receipt cannot restore, none of its runtime's entries remain in its files, and the live MCP entry launches another install root.
+ * The wiring was moved outside setup, so the receipt no longer owns anything live. Any trace of the receipt's runtime keeps it authoritative.
+ */
+function staleReceipt(target: SetupTarget, prior: Receipt): boolean {
+  let files: Image[];
+  try {
+    files = prior.changes.map(change => read(change.path));
+    const owned = launcher(mcpRecord(target, prior.changes[0]!.after)), live = launcher(mcpRecord(target, files[0]!));
+    if (!owned || !live || live.entry === owned.entry) return false;
+    // Raw and shell-quoted entry, searched in the raw text (with JSON escaping, for the Pi extension source)
+    // and in every decoded JSON/TOML string value, so escapes such as `\/` cannot hide a live entry.
+    const traces = [owned.entry, quote(owned.entry)], escaped = traces.map(value => JSON.stringify(value).slice(1, -1));
+    if (files.some(file => file.bytes !== null && decodedTexts(Buffer.from(file.bytes, "base64").toString("utf8"))
+      .some((value, index) => (index === 0 ? [...traces, ...escaped] : traces).some(trace => value.includes(trace))))) return false;
+  } catch { return false; }
+  try { prior.changes.forEach((change, index) => restoreChange(prior, change, index, files[index]!)); return false; } catch { return true; }
+}
+/** The raw text first, then every string value it decodes to as JSON, else as TOML. */
+function decodedTexts(raw: string): string[] {
+  const out = [raw], walk = (value: unknown): void => {
+    if (typeof value === "string") out.push(value);
+    else if (value && typeof value === "object") for (const item of Object.values(value)) walk(item);
+  };
+  try { walk(JSON.parse(raw)); } catch { try { walk(Bun.TOML.parse(raw)); } catch { /* Not JSON or TOML (the Pi extension): the raw text alone. */ } }
+  return out;
+}
+/** Keep a stale receipt beside the new one instead of deleting it; the person can inspect or restore it. */
+function setReceiptAside(file: string): void {
+  const aside = `${file}.stale-${new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+/, "")}`;
+  names(aside);
+  if (lstatSync(aside, { throwIfNoEntry: false })) throw Error("setup is busy; retry after the active setup exits");
+  renameSync(file, aside); const parent = openSync(dirname(file), constants.O_RDONLY); try { fsyncSync(parent); } finally { closeSync(parent); }
+}
+interface Prepared { value: Receipt; expected: Image[]; unchanged: boolean; setAside?: string }
 function restoreChange(value: Receipt, change: Change, index: number, live: Image): Image {
   const start = value.phase === "prepared" && change.start && !sameImage(change.start, change.before) ? change.start : undefined;
   if (start) {
@@ -417,7 +465,13 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
   if (target === "jcode") assertJcodeRuntime(c);
   if (target === "opencode") assertOpencodeLayout(c, "apply");
   if (target === "gemini") assertGeminiHome(c.env);
-  const prior = receipt(c, target, false), expected = c.paths[target].map(path => read(path));
+  let prior = receipt(c, target, false), setAside: string | undefined;
+  if (prior && staleReceipt(target, prior)) {
+    if (!options.adoptCurrent) throw Error(STALE_RECEIPT);
+    // Adopt the live wiring through the receipt-less path (#238); the receipt is set aside only when this target publishes.
+    setAside = journal(c, target); prior = undefined;
+  }
+  const expected = c.paths[target].map(path => read(path));
   // Only a same-file before-image can restore a target. A newly authoritative personal source owns its current bytes.
   // Mapped per current path: a pre-#203 jcode receipt covers mcp.json only, so config.toml starts from its live image.
   const restored = c.paths[target].map((path, index) => { const change = prior?.changes[index];
@@ -494,9 +548,9 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
     }
     const capture = (kind: string) => `${quote(c.bun)} --smol ${quote(c.entry)} ingest ${kind} --json`;
     if (target === "claude") changes[1]!.after = hookDocument(changes[1]!.before, HOOK_EVENTS, event => `${quote(c.bun)} --smol ${quote(c.entry)} hook ${event}`, 1, event => oldLaunches.map(launch => `${launch} hook ${event}`));
-    if (target === "codex") changes[1]!.after = hookDocument(changes[1]!.before, ["SessionEnd"], () => capture("codex"), 3, () => oldLaunches.map(launch => `${launch} ingest codex --json`));
+    if (target === "codex") changes[1]!.after = hookDocument(changes[1]!.before, ["SessionEnd"], () => capture("codex"), 3, () => priorCaptures(oldLaunches, "codex"));
     // Qwen's user MCP and hooks share settings.json: publish and journal one combined image.
-    if (target === "qwen") changes[0]!.after = hookDocument(changes[0]!.after, ["SessionEnd"], () => capture("qwen"), 3, () => oldLaunches.map(launch => `${launch} ingest qwen --json`));
+    if (target === "qwen") changes[0]!.after = hookDocument(changes[0]!.after, ["SessionEnd"], () => capture("qwen"), 3, () => priorCaptures(oldLaunches, "qwen"));
     if (target === "kimi") {
       const old = changes[1]!.before.bytes === null ? "" : Buffer.from(changes[1]!.before.bytes!, "base64").toString("utf8");
       const parsed = toml(old), rawHooks = parsed.hooks ?? [];
@@ -504,7 +558,7 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
       let hooks: unknown[] = rawHooks;
       if (oldLaunches.length) hooks = hooks.filter(h => {
         const row = record(h);
-        if (row.event !== "SessionEnd" || !oldLaunches.some(launch => row.command === `${launch} ingest kimi --json`)) return true;
+        if (row.event !== "SessionEnd" || !priorCaptures(oldLaunches, "kimi").includes(String(row.command))) return true;
         if (![undefined, "", "*"].includes(row.matcher as string | undefined) || row.timeout !== 3
           || Object.keys(row).some(key => !["event", "command", "matcher", "timeout"].includes(key)))
           throw Error("previous-runtime hook settings are customized; review hook configuration before retrying setup");
@@ -522,7 +576,7 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
     }
     // Never publish an image that this installer's own read/undo boundary cannot reopen.
     if (changes.some(change => change.after.bytes !== null && Buffer.from(change.after.bytes, "base64").byteLength > MAX)) throw Error("planned setup configuration exceeds the size bound; no configuration published");
-    return { value: { version: previous.length && changes.some((change, index) => retiresOriginalHook(target, index, change.before, change.after)) ? 2 : 1, target, intent: intent(c, target), phase: "prepared", changes, ...(prior?.createdDirectory ? { createdDirectory: prior.createdDirectory } : {}) }, expected, unchanged: false };
+    return { value: { version: previous.length && changes.some((change, index) => retiresOriginalHook(target, index, change.before, change.after)) ? 2 : 1, target, intent: intent(c, target), phase: "prepared", changes, ...(prior?.createdDirectory ? { createdDirectory: prior.createdDirectory } : {}) }, expected, unchanged: false, ...(setAside ? { setAside } : {}) };
   } finally { rmSync(staging, { recursive: true, force: true }); }
 }
 function save(c: ReturnType<typeof context>, value: Receipt): void { write(journal(c, value.target), image(JSON.stringify(value) + "\n")); }
@@ -570,6 +624,7 @@ function applyUnlocked(plan: SetupPlan, options: SetupContext = {}): SetupApplyR
     const value = item.value;
     if (value.target === "agy") c.workspace!.assertCurrent();
     if (item.unchanged) { unchanged.push(value.target); continue; }
+    if (item.setAside) setReceiptAside(item.setAside);
     save(c, value);
     prepareCreatedDirectory(c, value);
     for (let i = 0; i < value.changes.length; i++) { const change = value.changes[i]!; if (!sameImage(item.expected[i]!, change.after)) write(change.path, change.after, item.expected[i]!, publishGuard(c, value.target, options)); }

package/src/ui/inbox-cache.ts

@@ -0,0 +1,219 @@
+import { fork } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { configuredPolicy } from "../memory/config.ts";
+import { processGroupLiveness, processSignatureAsync, realPath, type Liveness } from "../memory/platform.ts";
+import { INBOX_MAX_BYTES, INBOX_MAX_ITEMS, boundedInboxRows, inboxPolicyDefaults, inboxPolicyVersion, inboxSourceChange, type CapacityMemo, type InboxComputation, type InboxItem, type InboxSources } from "./inbox.ts";
+import { inboxWorkerHash } from "./inbox-worker-version.ts";
+
+export const INBOX_WORKER_HASH = inboxWorkerHash();
+export interface InboxJobResult { computation: InboxComputation; sources: InboxSources }
+export interface InboxJob { result: Promise<InboxJobResult>; cancel(): Promise<void>; observeCleanup?(): Liveness }
+export type InboxRunner = (base: string, capacity?: CapacityMemo) => InboxJob;
+export interface InboxSnapshot { items: InboxItem[]; more: number; complete: boolean; refreshing: boolean; generatedAt?: string }
+const WORK_MS = 30_000, REAP_MS = 2000, MIN_START_MS = 30_000, MAX_BACKOFF_MS = 300_000;
+export class InboxCleanupError extends Error {
+  readonly group: number | undefined;
+  constructor(group?: number) {
+    const valid = group !== undefined && Number.isSafeInteger(group) && group > 0 ? group : undefined;
+    super(`inbox worker group ${valid ?? "unknown"} cleanup is unresolved`); this.name = "InboxCleanupError"; this.group = valid;
+  }
+}
+export class InboxDeadlineError extends InboxCleanupError { constructor(group?: number) { super(group); this.name = "InboxDeadlineError"; } }
+export class InboxChangedError extends Error { constructor() { super("inbox sources changed"); this.name = "InboxChangedError"; } }
+export class InboxRuntimeError extends Error { constructor(message: string) { super(message); this.name = "InboxRuntimeError"; } }
+async function waitForGroupGone(group: number | undefined): Promise<void> {
+  if (group === undefined) return;
+  const until = performance.now() + REAP_MS;
+  for (;;) {
+    const state = processGroupLiveness(group);
+    if (state === "gone") return;
+    if (state === "unknown" || performance.now() >= until) throw new InboxCleanupError(group);
+    await new Promise(resolve => setTimeout(resolve, 20));
+  }
+}
+/** Native child handle plus verified detached group: no retired group is ever signalled. */
+export const runInboxJob: InboxRunner = (base, capacity) => {
+  if (!existsSync(process.execPath)) throw new InboxRuntimeError("bun moved; restart acon serve");
+  if (!INBOX_WORKER_HASH || inboxWorkerHash() !== INBOX_WORKER_HASH) throw new InboxRuntimeError("inbox worker changed; restart acon serve");
+  const defaults = inboxPolicyDefaults();
+  const child = fork(fileURLToPath(new URL("./inbox-worker.ts", import.meta.url)), [], { execPath: process.execPath, execArgv: ["--smol"], detached: true,
+    stdio: ["ignore", "ignore", "ignore", "ipc"], serialization: "json", env: { ...process.env, AMEM_UI_WORKER_HASH: INBOX_WORKER_HASH } });
+  let exited = false, cleaned = false, ready = false, groupKnown = false, terminating = false, changed = false, workerMoved = false, payload: InboxJobResult | undefined;
+  let readyProbe: Promise<void> | undefined, force: ReturnType<typeof setTimeout> | undefined;
+  let fail!: (error: Error) => void, succeed!: (value: InboxJobResult) => void, endedResolve!: () => void, endedReject!: (error: Error) => void;
+  const ended = new Promise<void>((resolve, reject) => { endedResolve = resolve; endedReject = reject; }); void ended.catch(() => {});
+  const result = new Promise<InboxJobResult>((resolve, reject) => { succeed = resolve; fail = reject; });
+  const kill = (signal: NodeJS.Signals) => {
+    if (exited || child.exitCode !== null || child.signalCode !== null) return;
+    try { if (child.pid) process.kill(-child.pid, signal); } catch { child.kill(signal); }
+  };
+  const clear = () => { clearTimeout(deadline); if (force) clearTimeout(force); };
+  const clean = () => { cleaned = true; exited = true; clear(); endedResolve(); };
+  const observe = (): Liveness => {
+    if (cleaned) return "gone";
+    const state = child.pid === undefined ? "gone" : processGroupLiveness(child.pid);
+    if (state === "gone" && (groupKnown || exited || child.exitCode !== null || child.signalCode !== null || child.pid === undefined)) { clean(); return "gone"; }
+    return state === "gone" ? "unknown" : state;
+  };
+  const terminate = () => {
+    if (terminating || exited || cleaned) return;
+    terminating = true; kill("SIGTERM");
+    if (!exited) { force = setTimeout(() => kill("SIGKILL"), 250); force.unref(); }
+  };
+  const deadline = setTimeout(() => { terminate(); fail(new InboxDeadlineError(child.pid)); }, WORK_MS); deadline.unref();
+  child.on("message", (value: unknown) => {
+    const message = value as { type?: unknown; pid?: unknown; group?: unknown; signature?: unknown; workerHash?: unknown; computation?: InboxComputation; sources?: InboxSources };
+    if (message?.type === "ready" && !ready && !readyProbe) {
+      readyProbe = (async () => {
+        if (message.workerHash !== INBOX_WORKER_HASH) { workerMoved = true; terminate(); return; }
+        if (!child.pid || message.pid !== child.pid || message.group !== child.pid || typeof message.signature !== "string") { terminate(); return; }
+        groupKnown = true;
+        const signature = await processSignatureAsync(child.pid);
+        if (exited || terminating) return;
+        if (signature !== message.signature) { terminate(); return; }
+        ready = true; child.send({ type: "run", base, capacity, defaults });
+      })().catch(() => terminate());
+    } else if (ready && message?.type === "result" && message.computation && message.sources) payload = { computation: message.computation, sources: message.sources };
+    else if (ready && message?.type === "changed") changed = true;
+    else if (message?.type === "moved") workerMoved = true;
+  });
+  child.once("error", () => {
+    if (child.pid === undefined) { clean(); fail(Error("inbox worker unavailable")); } else terminate();
+  });
+  child.once("close", code => {
+    exited = true; clear();
+    if (cleaned) return;
+    // The proof budget starts here, not at TERM: unrelated event-loop work before close cannot consume it.
+    void waitForGroupGone(child.pid).then(() => {
+      clean();
+      if (code === 0 && payload && !terminating) succeed(payload);
+      else fail(workerMoved ? new InboxRuntimeError("inbox worker changed; restart acon serve") : changed ? new InboxChangedError() : Error("inbox worker unavailable"));
+    }).catch(() => { const error = new InboxCleanupError(child.pid); endedReject(error); fail(error); });
+  });
+  return { result, observeCleanup: observe, async cancel() {
+    if (observe() === "gone") { fail(Error("inbox worker cancelled")); return; }
+    terminate(); let timer: ReturnType<typeof setTimeout> | undefined;
+    try { await Promise.race([ended, new Promise<void>((resolve, reject) => { timer = setTimeout(() => {
+      if (observe() === "gone") { fail(Error("inbox worker cancelled")); resolve(); }
+      else { const error = new InboxCleanupError(child.pid); endedReject(error); fail(error); reject(error); }
+    }, REAP_MS + 1000); })]); fail(Error("inbox worker cancelled")); }
+    finally { if (timer) clearTimeout(timer); }
+  } };
+};
+
+export interface InboxInvalidation { hard?: boolean; capacity?: boolean; removeIds?: readonly string[]; added?: number }
+/** Request-driven refresh only. Cooldown/backoff survive source changes and actions. */
+export class InboxCache {
+  private readonly base: string; private readonly runner: InboxRunner; private readonly log: (line: string) => void;
+  private readonly now: () => number; private readonly clock: () => number;
+  private cache?: InboxJobResult; private capacity?: CapacityMemo; private observed?: InboxSources;
+  private task?: InboxJob; private blockedTask?: InboxJob; private blockedGroup?: number; private request?: Promise<InboxSnapshot>;
+  private generation = 0; private closed = false; private pending = true; private stale = false;
+  private failureCount = 0; private retryAt = 0; private lastStart?: number; private lastDuration = 0;
+  private error?: "failure" | "cleanup" | "runtime"; private errorDetail?: string;
+  private generatedAt?: string; private policy?: string; private capacityAt?: string; private overflowAt?: string;
+  private state = ""; private stateAt = 0;
+  constructor(base: string, options: { runner?: InboxRunner; log?: (line: string) => void; now?: () => number; monotonicNow?: () => number } = {}) {
+    const absolute = resolve(base); this.base = existsSync(absolute) ? realPath(absolute) : absolute;
+    this.runner = options.runner ?? runInboxJob; this.log = options.log ?? (() => {}); this.now = options.now ?? Date.now;
+    this.clock = options.monotonicNow ?? (options.now ? options.now : () => performance.now());
+  }
+  invalidate(input: boolean | InboxInvalidation = {}): void {
+    const change = typeof input === "boolean" ? { hard: input, capacity: input } : input;
+    this.generation++; this.pending = true; this.stale = true;
+    if (change.hard) { this.cache = undefined; this.observed = undefined; }
+    else if (this.cache && (change.removeIds?.length || change.added)) {
+      const old = this.cache.computation, actual = old.items.filter(item => item.id !== "inbox:more");
+      const removed = new Set(change.removeIds ?? []), shown = actual.filter(item => !removed.has(item.id));
+      const total = Math.max(shown.length, actual.length + old.more - removed.size + (change.added ?? 0));
+      const hint = old.items.find(item => item.id === "inbox:more");
+      Object.assign(old, boundedInboxRows(hint ? [...shown, hint] : shown, total));
+    }
+    if (change.capacity) this.capacity = undefined;
+  }
+  private allowed(): boolean {
+    return this.clock() >= Math.max(this.retryAt, this.lastStart === undefined ? 0 : this.lastStart + Math.max(MIN_START_MS, this.lastDuration));
+  }
+  private recover(): void {
+    if (!this.blockedTask) return;
+    const state = this.blockedTask.observeCleanup ? this.blockedTask.observeCleanup()
+      : this.blockedGroup === undefined ? "gone" : processGroupLiveness(this.blockedGroup);
+    if (state === "gone") { if (this.task === this.blockedTask) this.task = undefined; this.blockedTask = undefined; this.blockedGroup = undefined; this.error = undefined; }
+  }
+  private failed(error: unknown, job?: InboxJob): void {
+    if (error instanceof InboxChangedError) { this.pending = true; return; }
+    this.failureCount = Math.min(20, this.failureCount + 1);
+    this.retryAt = this.clock() + Math.min(MAX_BACKOFF_MS, 1000 * 2 ** Math.min(19, this.failureCount - 1));
+    this.pending = true; this.error = error instanceof InboxRuntimeError ? "runtime" : error instanceof InboxCleanupError ? "cleanup" : "failure";
+    if (error instanceof InboxCleanupError && job && error.group !== undefined) { this.blockedTask = job; this.blockedGroup = error.group; }
+    if (error instanceof InboxRuntimeError) { this.cache = undefined; this.errorDetail = error.message; }
+    if (!this.closed) try { this.log(error instanceof InboxRuntimeError ? error.message : this.error === "cleanup"
+      ? `amem: inbox group ${this.blockedGroup ?? "unknown"} cleanup unresolved; snapshots will observe recovery without signalling it.` : "amem: inbox refresh failed; bounded backoff applies"); } catch {}
+  }
+  private refresh(): void {
+    if (this.closed || this.task || this.blockedTask || !this.pending || !this.allowed()) return;
+    const generation = this.generation, started = this.clock(); this.lastStart = started; this.pending = false; this.error = undefined; this.errorDetail = undefined;
+    let job: InboxJob;
+    try { job = this.runner(this.base, this.capacity); } catch (error) { this.lastDuration = Math.max(0, this.clock() - started); this.failed(error); return; }
+    this.task = job;
+    void job.result.then(result => {
+      const revision = inboxPolicyVersion(this.base), computation = result.computation;
+      if (generation !== this.generation || computation.policy !== revision || inboxSourceChange(this.base, result.sources).changed) { this.pending = true; return; }
+      if (computation.expiresAt !== null && (!Number.isFinite(computation.expiresAt) || computation.expiresAt < 0)) throw Error("invalid inbox expiry");
+      if (computation.expiresAt !== null && this.now() >= computation.expiresAt) { this.invalidate({ hard: true }); return; }
+      if (computation.items.length > INBOX_MAX_ITEMS || Buffer.byteLength(JSON.stringify(computation.items)) > INBOX_MAX_BYTES || !Number.isSafeInteger(computation.more) || computation.more < 0) throw Error("invalid inbox result");
+      const screen = configuredPolicy(this.base);
+      if (computation.items.some(item => item.id !== "inbox:more" && !screen.screenStandalone(item))) throw Error("inbox result declined");
+      this.cache = structuredClone(result); this.observed = this.cache.sources; this.capacity = this.cache.computation.capacity;
+      const cap = this.cache.computation.items.find(item => item.id === "capacity:proposal");
+      if (cap) { this.capacityAt ??= cap.at; cap.at = this.capacityAt; } else this.capacityAt = undefined;
+      const overflow = this.cache.computation.items.find(item => item.id === "inbox:more");
+      if (overflow) { this.overflowAt ??= overflow.at; overflow.at = this.overflowAt; } else this.overflowAt = undefined;
+      this.policy = revision; this.generatedAt = new Date(this.now()).toISOString(); this.stale = false; this.pending = false;
+      this.failureCount = 0; this.retryAt = 0; this.error = undefined; this.errorDetail = undefined;
+    }).catch(error => this.failed(error, job)).finally(() => {
+      this.lastDuration = Math.max(0, this.clock() - started); if (this.task === job) this.task = undefined;
+      // No timer or completion callback spawns another process. A later snapshot services one pending rerun.
+    });
+  }
+  private status(): InboxSnapshot {
+    const kind = this.error || this.blockedTask ? "unavailable" : "refreshing";
+    if (this.state !== kind) { this.state = kind; this.stateAt = Math.max(this.now(), this.stateAt + 1); }
+    return { items: [{ id: `inbox:${kind}`, group: "alert", kind: "status", title: kind === "refreshing" ? "Memory inbox is refreshing" : "Memory inbox is unavailable",
+      detail: this.errorDetail ?? (kind === "refreshing" ? "Pending items will appear when the refresh finishes." : "Refresh is paused; it will retry after the cooldown."),
+      at: new Date(this.stateAt).toISOString(), verbs: [], link: { panel: "review" } }], more: 0, complete: false, refreshing: true };
+  }
+  snapshot(): Promise<InboxSnapshot> {
+    if (this.request) return this.request.then(value => structuredClone(value));
+    const request = Promise.resolve().then(() => {
+      if (this.closed) throw Error("inbox provider is closed");
+      try {
+        this.recover(); const revision = inboxPolicyVersion(this.base);
+        if (this.policy !== undefined && this.policy !== revision) this.invalidate({ hard: true, capacity: true });
+        this.policy = revision;
+        if (this.cache) {
+          const changed = inboxSourceChange(this.base, this.observed ?? this.cache.sources);
+          this.observed = changed.sources;
+          if (changed.changed) this.invalidate({ hard: changed.hard, capacity: changed.hard });
+          if (this.cache && this.cache.computation.expiresAt !== null && this.now() >= this.cache.computation.expiresAt) this.invalidate({ hard: true });
+          if (this.capacity && this.now() >= this.capacity.until && !this.stale) this.invalidate();
+        }
+        this.refresh();
+        if (this.cache && inboxPolicyVersion(this.base) !== revision) throw Error("inbox policy changed");
+        if (this.cache && (!this.stale || this.cache.computation.items.length)) {
+          this.state = this.stale ? "stale" : "ready";
+          return { items: structuredClone(this.cache.computation.items), more: this.cache.computation.more, complete: !this.stale, refreshing: this.stale, generatedAt: this.generatedAt };
+        }
+        return this.status();
+      } catch { this.invalidate({ hard: true, capacity: true }); this.error = "failure"; return this.status(); }
+    });
+    this.request = request; void request.finally(() => { if (this.request === request) this.request = undefined; }).catch(() => {});
+    return request.then(value => structuredClone(value));
+  }
+  async close(): Promise<void> {
+    this.closed = true; this.cache = undefined; this.capacity = undefined; this.generation++;
+    const job = this.task ?? this.blockedTask; if (job) await job.cancel(); this.blockedTask = undefined;
+  }
+}

package/src/ui/inbox-worker-version.ts

@@ -0,0 +1,14 @@
+/** Compatibility pin for the on-disk worker/control code, not an authentication credential. */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+// ponytail: this pins the worker/control/policy modules and package metadata. Same-version edits to other
+// dependencies retain the host's module-loader trust ceiling; a host-attested immutable package graph is the upgrade.
+export function inboxWorkerHash(): string | undefined {
+  try {
+    const files = ["./inbox-worker.ts", "./inbox-cache.ts", "./inbox.ts", "./inbox-worker-version.ts", "../memory/candidates.ts", "../memory/policy.ts", "../memory/config.ts", "../memory/platform.ts", "../../package.json"];
+    const hash = createHash("sha256");
+    for (const file of files) hash.update(JSON.stringify([file, createHash("sha256").update(readFileSync(new URL(file, import.meta.url))).digest("hex")]));
+    return hash.digest("hex");
+  } catch { return undefined; }
+}

package/src/ui/inbox-worker.ts

@@ -0,0 +1,32 @@
+/** One-shot, owned background process. Never imported by the console request handler. */
+import { DENY_NAMES, DENY_SEGMENTS, processSignatureAsync, processGroupIdAsync } from "../memory/platform.ts";
+import { inboxWorkerHash } from "./inbox-worker-version.ts";
+import { memoryPolicySnapshot } from "../memory/policy.ts";
+import { computeInbox, createInboxSourceTracker, type CapacityMemo, type InboxDefaults } from "./inbox.ts";
+
+process.once("disconnect", () => process.exit());
+// Keep the leader identity while synchronous owned children settle or the parent force-kills the group.
+process.on("SIGTERM", () => {});
+process.once("message", (message: unknown) => {
+  try {
+    const input = message as { type?: unknown; base?: unknown; capacity?: CapacityMemo; defaults?: InboxDefaults };
+    if (input.type !== "run" || typeof input.base !== "string") throw Error("invalid inbox job");
+    const defaults = memoryPolicySnapshot(input.defaults);
+    if (!defaults || !Array.isArray(defaults.names) || !Array.isArray(defaults.segments)
+      || !defaults.names.every(value => typeof value === "string") || !defaults.segments.every(value => typeof value === "string")) throw Error("invalid inbox policy");
+    DENY_NAMES.splice(0, DENY_NAMES.length, ...defaults.names); DENY_SEGMENTS.splice(0, DENY_SEGMENTS.length, ...defaults.segments);
+    const tracker = createInboxSourceTracker(input.base);
+    const computation = computeInbox(input.base, input.capacity, tracker.beforeProject), before = tracker.before(), after = tracker.after();
+    const result = before.version === after.version ? { type: "result", computation, sources: after } : { type: "changed" };
+    process.send?.(result, () => process.disconnect?.());
+  } catch {
+    // No source text, paths, literal patterns or caller error messages cross the error channel.
+    process.send?.({ type: "failed" }, () => process.disconnect?.());
+  }
+});
+const workerHash = inboxWorkerHash();
+if (!workerHash || workerHash !== process.env.AMEM_UI_WORKER_HASH) {
+  process.send?.({ type: "moved" }, () => process.disconnect?.());
+} else void Promise.all([processSignatureAsync(process.pid), processGroupIdAsync(process.pid)]).then(([signature, group]) => {
+  process.send?.({ type: "ready", pid: process.pid, signature, group, workerHash });
+});