@staix/agent-mem 0.20.3 → 0.22.0

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

@@ -0,0 +1,136 @@
+/** CLI adapter only. Expected locators are never returned as fresh writer facts. */
+import { types } from "node:util";
+import { 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 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 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",
+  "invalid-version":"package version is not a supported plain release", "invalid-inventory":"root inventory is invalid or duplicated", "unsafe-runtime":"runtime files have unsafe types or symlinks",
+  "missing-runtime":"required bin/amem.js or src/index.ts is missing",bound:"inventory exceeds a supported bound",changed:"install changed during measurement",
+};
+function writerContextMessage(category:PlacementWriterRootCategory,causeClass:"missing"|"changed"|"unavailable",phase:PlacementWriterContextPhase,detail?:SyncPlacementWriterFailureDetail,renewalState?:"pending"|"staging"):string {
+  if(category==="writer renewal")return new SharedWriterRevisionError(renewalState==="staging"?"staging":"pending").message;
+  if(category==="active locator") return `Sync placement initial root locator is ${causeClass} (active locator category); have the person inspect sync-placement-writer-roots.json and the matching activation metadata with a compatible recovery release, then run amem migrate --sync-placement --dry-run.`;
+  if(category==="home floor") return `Sync placement reader-floor proof is ${causeClass} (home floor category); have the person inspect formats.json and use a reader compatible with its recorded floor, then run amem migrate --sync-placement --dry-run.`;
+  const cause=detail?`; ${failureDetails[detail]}`:"";
+  if(phase==="initial")return `Sync placement initial writer proof is ${causeClass} (${category} category${cause}); ${category==="setup receipt"?"upgrade or repair the managed amem install and its host exact pin, then rerun amem setup <target> --apply":"upgrade or repair the amem install and its host exact pin"}. Declare the complete writer roots and rerun amem migrate --sync-placement --dry-run.`;
+  return `Sync placement writer proof is ${causeClass} (${category} category${cause}); restore the inventoried install, or have the person run amem migrate --sync-placement --dry-run and --apply with the complete --writer-root inventory after installing the required 0.22.0 home floor.`;
+}
+export class PlacementWriterContextError extends Error {
+  constructor(readonly category: PlacementWriterRootCategory, readonly causeClass: "missing" | "changed" | "unavailable",readonly phase:PlacementWriterContextPhase="active",readonly detail?:SyncPlacementWriterFailureDetail,readonly renewalState?:"pending"|"staging") {
+    super(writerContextMessage(category,causeClass,phase,detail,renewalState)); this.name = "PlacementWriterContextError";
+  }
+}
+function safeRefusal(error: unknown, category: PlacementWriterRootCategory,phase:PlacementWriterContextPhase="active"): PlacementWriterContextError {
+  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)
+      && 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;
+      return new PlacementWriterContextError(category as PlacementWriterRootCategory,causeClass as PlacementWriterContextError["causeClass"],phase,ownDetail,state==="staging"||state==="pending"?state:undefined);
+    }
+  }
+  return new PlacementWriterContextError(category,"unavailable",phase);
+}
+const fail = (category: PlacementWriterRootCategory, cause: PlacementWriterContextError["causeClass"],phase:PlacementWriterContextPhase="active",detail?:SyncPlacementWriterFailureDetail): never => { throw new PlacementWriterContextError(category,cause,phase,detail); };
+function required(home: string, ownRoot: string,phase:PlacementWriterContextPhase="active") {
+  let own: string, receipt: string[];
+  try { own = realPath(ownRoot); } catch { return fail("running CLI","unavailable",phase,"unreadable"); }
+  try { receipt = readSetupWriterRoots(home); } catch { return fail("setup receipt","unavailable",phase,"unreadable"); }
+  return { own, receipt, roots: [...new Set([own,...receipt])].sort() };
+}
+function rootCategory(root:string|undefined,needed:ReturnType<typeof required>):PlacementWriterRootCategory {
+  if(root===needed.own)return "running CLI";return root&&needed.receipt.includes(root)?"setup receipt":"declared writer";
+}
+function measurementRefusal(error:unknown,roots:readonly string[],needed:ReturnType<typeof required>,phase:PlacementWriterContextPhase):PlacementWriterContextError {
+  const detail=extractSyncPlacementWriterFailure(error);let root:string|undefined;
+  if(detail?.rootIndex!==undefined){try{root=realPath(roots[detail.rootIndex]!);}catch{/* Missing noncanonical declared path is still unavailable, never fresh evidence. */}}
+  return new PlacementWriterContextError(rootCategory(root,needed),detail?.code==="changed"?"changed":"unavailable",phase,detail?.detail??"unreadable");
+}
+function measureComplete(home: string, roots: readonly string[], ownRoot: string,phase:PlacementWriterContextPhase="active"): SyncPlacementWriterMeasurement {
+  const before = required(home,ownRoot,phase);let result: SyncPlacementWriterMeasurement;
+  try { result = measureSyncPlacementWriters(roots); } catch(error) { throw measurementRefusal(error,roots,before,phase); }
+  if (!result.roots.some(row => row.root === before.own)) fail("running CLI","missing",phase);
+  if (before.receipt.some(root => !result.roots.some(row => row.root === root))) fail("setup receipt","missing",phase);
+  const after = required(home,ownRoot,phase);
+  if (after.own !== before.own) fail("running CLI","changed",phase,"changed");
+  if (canonicalJSON(after.receipt) !== canonicalJSON(before.receipt)) fail("setup receipt","changed",phase,"changed");
+  return result;
+}
+export interface PlacementWriterContext {
+  measurement: SyncPlacementWriterMeasurement;
+  attest: PlacementCapturePort["attest"];
+  lastRefusal?: PlacementWriterContextError;
+}
+/** Preview creates no quiescence claim. The coordinator invokes attest only while its live apply fences are held. */
+export function initialPlacementWriterContext(home: string, roots: readonly string[], ownRoot: string): PlacementWriterContext {
+  const selected = roots.length ? [...roots] : required(home,ownRoot,"initial").roots;
+  const measurement = measureComplete(home,selected,ownRoot,"initial"), canonical = measurement.roots.map(row=>row.root);
+  const floor = requirePlacementHomeFloor(home);
+  const context: PlacementWriterContext = { measurement, attest: () => {
+    try {
+      if (requirePlacementHomeFloor(home) !== floor) return fail("home floor","changed","initial");
+      const current = measureComplete(home,canonical,ownRoot,"initial");
+      if (canonicalJSON(current.writers) !== canonicalJSON(measurement.writers)) {
+        const changed=current.roots.find(row=>!measurement.writers.some(old=>old.writerId===row.writerId&&old.version===row.version&&old.pin===row.pin));
+        return fail(rootCategory(changed?.root,required(home,ownRoot,"initial")),"changed","initial","changed");
+      }
+      return { writers: current.writers, legacySyncQuiesced: true };
+    } catch (error) { context.lastRefusal = safeRefusal(error,"declared writer","initial"); throw context.lastRefusal; }
+  } }; return context;
+}
+/** 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);
+    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");
+    if(needed.receipt.some(root=>!roots.includes(root)))return fail("setup receipt","missing");
+    const measurement = measureComplete(home,roots,ownRoot);
+    if (canonicalJSON(measurement.writers) !== canonicalJSON(effective.writers)) {
+      const changed=measurement.roots.find(row=>!effective.writers.some(old=>old.writerId===row.writerId&&old.version===row.version&&old.pin===row.pin));
+      return fail(rootCategory(changed?.root,needed),"changed","active","changed");
+    }
+    effective.assertCurrent();
+    return measurement;
+  };
+  const measurement = read(), context: PlacementWriterContext = { measurement, attest: () => {
+    try { return { writers: read().writers, legacySyncQuiesced: true }; }
+    catch (error) { context.lastRefusal = safeRefusal(error,"active locator"); throw context.lastRefusal; }
+  } }; return context;
+}
+
+/** 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");
+  const selected = requested.length ? [...requested] : mapped;
+  const expected = effective.writers;
+  let measurement: SyncPlacementWriterMeasurement;
+  try { measurement = measureSyncPlacementWriters(selected); }
+  catch { return { complete:false, matches:false, roots:[] as SyncPlacementWriterMeasurement["roots"], expected, missingCategories:["declared writer"] as PlacementWriterRootCategory[], differences:expected.map(row=>({writerId:row.writerId,state:"unverified" as const})),refusalCategory:"declared writer" as PlacementWriterRootCategory }; }
+  const needed = required(home,ownRoot), missingCategories: PlacementWriterRootCategory[] = [];
+  if (!measurement.roots.some(row=>row.root===needed.own)) missingCategories.push("running CLI");
+  if (needed.receipt.some(root=>!measurement.roots.some(row=>row.root===root))) missingCategories.push("setup receipt");
+  const differences = expected.map(row=>{
+    const actual = measurement.writers.find(value=>value.writerId===row.writerId);
+    return {writerId:row.writerId,state:!actual?"missing":canonicalJSON(row)===canonicalJSON(actual)?"unchanged":"changed"};
+  });
+  for (const row of measurement.writers) if (!expected.some(value=>value.writerId===row.writerId)) differences.push({writerId:row.writerId,state:"added"});
+  const matches=missingCategories.length===0&&differences.every(row=>row.state==="unchanged");
+  const changed=measurement.roots.find(row=>{const old=expected.find(value=>value.writerId===row.writerId);return !old||old.pin!==row.pin||old.version!==row.version;});
+  const refusalCategory:PlacementWriterRootCategory=missingCategories[0]??(changed?.root===needed.own?"running CLI":changed&&needed.receipt.includes(changed.root)?"setup receipt":"declared writer");
+  return {complete:true,matches,roots:measurement.roots,expected,missingCategories,differences,refusalCategory};
+}

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