@staix/agent-mem 0.20.3 → 0.21.0

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

package/src/ui/inbox.ts

@@ -0,0 +1,281 @@
+/** Compact inbox computation. Run in the background worker, never on the console request loop. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, opendirSync, readSync } from "node:fs";
+import { join, relative } from "node:path";
+import { withPendingCandidates, type Candidate, type CandidateInput } from "../memory/candidates.ts";
+import { capacityReport } from "../memory/capacity.ts";
+import { configuredPolicy, configuredPolicyOptions } from "../memory/config.ts";
+import { openCuratedForRead } from "../memory/curated-read.ts";
+import { lifecycleResolver } from "../memory/lifecycle.ts";
+import { memoryPolicySnapshot, type StandalonePolicy } from "../memory/policy.ts";
+import { DENY_NAMES, DENY_SEGMENTS } from "../memory/platform.ts";
+import { aliasedKeys, effectiveAliases } from "../memory/shard.ts";
+import type { MemoryStore } from "../memory/store.ts";
+import { checkedEntry } from "../memory/bridge.ts";
+import { readProfileJSON, readSelector, generationDir } from "../memory/generation.ts";
+import { shardDir } from "../memory/shard.ts";
+import { readPublicPruneViewForActivation } from "../memory/public-prune-view.ts";
+
+export interface InboxItem {
+  id: string; group: "candidate" | "alert"; kind: string; title: string; detail?: string; project?: string; at: string;
+  chip?: { text: string; tone: "ok" | "warn" | "err" | "neutral" };
+  verbs: { id: string; label: string; primary?: boolean; reason?: "optional" | "required" }[];
+  link: { panel: string; params?: Record<string, string> };
+}
+export interface InboxDefaults { names: string[]; segments: string[] }
+export function inboxPolicyDefaults(): InboxDefaults {
+  const defaults = memoryPolicySnapshot({ names: DENY_NAMES, segments: DENY_SEGMENTS });
+  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("inbox policy is unavailable");
+  return defaults;
+}
+export function inboxPolicyVersion(base: string): string {
+  return createHash("sha256").update(JSON.stringify({ options: configuredPolicyOptions(base), defaults: inboxPolicyDefaults() })).digest("hex");
+}
+export const INBOX_MAX_ITEMS = 50, INBOX_MAX_BYTES = 64 * 1024;
+export const CAPACITY_CACHE_MS = 5 * 60_000;
+const oneLine = (text: string, max = 120) => { const flat = text.replace(/\s+/g, " ").trim(); return flat.length > max ? `${flat.slice(0, max - 3)}...` : flat; };
+export function candidateText(input: CandidateInput): string {
+  switch (input.kind) {
+    case "memory": return input.title ? `${input.title}: ${input.text}` : input.text;
+    case "fail": return `Approach: ${input.approach}\nSymptom: ${input.symptom}\nCause: ${input.cause}\nRetry when: ${input.retryWhen}`;
+    case "correction": return `${input.proposedText}\n\nReason: ${input.reason}`;
+    case "decay": return input.reason;
+    case "promotion": return `Promote mem:${input.target.id} to long-term for goal:${input.goalId}`;
+    case "consolidation": return `${input.action}: ${input.text}`;
+    case "model-answer": return input.text;
+  }
+}
+export const candidateTargets = (input: CandidateInput) => "targets" in input ? input.targets : "target" in input && input.target ? [input.target] : [];
+/** Shared with Review: the candidate, every target, and the promotion goal must pass current policy. */
+export function visibleCandidate(candidate: Candidate, project: string, store: MemoryStore | undefined, policy: StandalonePolicy, onExpiry?: (at: number) => void): boolean {
+  if (!policy.screenStandalone(candidate)) return false;
+  const input = candidate.input, targets = candidateTargets(input);
+  if (!targets.length && input.kind !== "promotion") return true;
+  if (!store) return false;
+  let expiresAt: number | undefined;
+  for (const target of targets) {
+    const view = store.get(target.id, project);
+    if (!view || view.project !== project || !policy.screenStandalone(view)) return false;
+    const at = view.expiresAt ? Date.parse(view.expiresAt) : Number.NaN;
+    if (Number.isFinite(at) && at > Date.now()) expiresAt = expiresAt === undefined ? at : Math.min(expiresAt, at);
+  }
+  if (input.kind === "promotion") { const goal = store.goalOf(input.goalId, project); if (!goal || !policy.screenStandalone(goal)) return false; }
+  if (expiresAt !== undefined) onExpiry?.(expiresAt);
+  return true;
+}
+export interface CapacityMemo { policy: string; until: number; item: InboxItem | null; captureConfig: string }
+export function inboxCaptureConfigVersion(base: string): string { return JSON.stringify(state(base, "capture-config.json")); }
+export interface InboxComputation { items: InboxItem[]; more: number; policy: string; capacity: CapacityMemo; expiresAt: number | null }
+const order = (a: InboxItem, b: InboxItem) => Number(b.group === "alert") - Number(a.group === "alert") || b.at.localeCompare(a.at) || a.id.localeCompare(b.id);
+/** Only row-rendered fields cross the worker boundary; details stay in the item's panel. */
+export function computeInbox(base: string, previous?: CapacityMemo, beforeProject?: (project: string) => void): InboxComputation {
+  const revision = inboxPolicyVersion(base), policy = configuredPolicy(base), active = lifecycleResolver(base), aliases = effectiveAliases(base);
+  const items: InboxItem[] = []; let count = 0, expiresAt: number | null = null;
+  const add = (item: InboxItem) => {
+    if (!policy.screenStandalone(item)) return;
+    count++; items.push(item); items.sort(order); if (items.length > INBOX_MAX_ITEMS) items.pop();
+  };
+  withPendingCandidates(base, reader => {
+    expiresAt = reader.nextExpiry();
+    const projects = [...new Set(reader.projects().map(project => aliases.get(project) ?? project))].filter(project => active(project) === "active").sort();
+    const reuseShared = !existsSync(join(base, "shards.json")) && aliases.size === 0;
+    let shared: MemoryStore | undefined, sharedOpened = false;
+    try {
+      for (const project of projects) {
+        let store: MemoryStore | undefined, opened = false;
+        try {
+          for (const candidate of reader.list([project, ...aliasedKeys(base, project)])) {
+            if (!policy.screenStandalone(candidate)) continue;
+            if (!opened && (candidateTargets(candidate.input).length || candidate.input.kind === "promotion")) {
+              beforeProject?.(project);
+              if (reuseShared) {
+                if (!sharedOpened) { shared = openCuratedForRead(base, project); sharedOpened = true; }
+                store = shared;
+              } else store = openCuratedForRead(base, project);
+              opened = true;
+            }
+            if (!visibleCandidate(candidate, project, store, policy, at => { expiresAt = expiresAt === null ? at : Math.min(expiresAt, at); })) continue;
+            const kind = candidate.input.kind;
+            add({ id: candidate.id, group: "candidate", kind, title: oneLine(candidateText(candidate.input)), project, at: candidate.createdAt,
+              verbs: [...kind !== "decay" && kind !== "model-answer" ? [{ id: "accept", label: "Accept", primary: true }] : [], { id: "reject", label: "Reject", reason: "optional" }],
+              link: { panel: "review", params: { project, id: candidate.id } } });
+          }
+        } finally { if (!reuseShared) store?.close(); }
+      }
+    } finally { shared?.close(); }
+  });
+  let capacity = previous;
+  const captureConfig = inboxCaptureConfigVersion(base);
+  // ponytail: resource advice is cached for at most five minutes. The Capacity panel/action still computes fresh
+  // advice; incremental capture counters and bounded asynchronous native readings are the upgrade path.
+  if (!capacity || capacity.policy !== revision || capacity.captureConfig !== captureConfig || Date.now() >= capacity.until) {
+    let item: InboxItem | null = null;
+    if (existsSync(base)) {
+      const report = capacityReport({ memoryDir: base });
+      if (policy.screenStandalone(report) && (report.current.capMb !== report.proposal.capMb || report.current.retentionDays !== report.proposal.retentionDays)) {
+        item = { id: "capacity:proposal", group: "alert", kind: "capacity", title: oneLine(`Capture capacity: ${report.current.capMb} MB / ${report.current.retentionDays} d, proposed ${report.proposal.capMb} MB / ${report.proposal.retentionDays} d`),
+          detail: oneLine(report.proposal.reason, 160), at: new Date().toISOString(), chip: { text: "proposal", tone: "warn" },
+          verbs: [{ id: "capacity_apply", label: "Apply..." }], link: { panel: "capacity" } };
+      }
+    }
+    capacity = { policy: revision, until: Date.now() + CAPACITY_CACHE_MS, item, captureConfig };
+  }
+  if (capacity.item) add(capacity.item);
+  const bounded = boundedInboxRows(items, count);
+  if (inboxPolicyVersion(base) !== revision) throw Error("inbox policy changed");
+  return { ...bounded, policy: revision, capacity, expiresAt };
+}
+
+/** totalCount counts real visible capacity/candidate rows, never the synthetic overflow hint. */
+export function boundedInboxRows(input: readonly InboxItem[], totalCount: number): { items: InboxItem[]; more: number } {
+  const previous = input.find(item => item.id === "inbox:more"), real = input.filter(item => item.id !== "inbox:more").sort(order);
+  if (!Number.isSafeInteger(totalCount) || totalCount < real.length) throw Error("inbox overflow count is invalid");
+  const at = previous?.at ?? new Date().toISOString();
+  const make = () => {
+    const more = totalCount - real.length;
+    const hint: InboxItem = { id: "inbox:more", group: "alert", kind: "overflow", title: `${more} more in Review`, at, verbs: [], link: { panel: "review" } };
+    const capacity = real.filter(item => item.id === "capacity:proposal"), other = real.filter(item => item.id !== "capacity:proposal");
+    return { items: [...capacity, ...(more ? [hint] : []), ...other], more };
+  };
+  while (real.length > INBOX_MAX_ITEMS || totalCount > real.length && real.length >= INBOX_MAX_ITEMS) real.pop();
+  let result = make();
+  while ((result.items.length > INBOX_MAX_ITEMS || Buffer.byteLength(JSON.stringify(result)) > INBOX_MAX_BYTES - 512) && real.length) { real.pop(); result = make(); }
+  if (result.items.length > INBOX_MAX_ITEMS || Buffer.byteLength(JSON.stringify(result)) > INBOX_MAX_BYTES - 512) throw Error("inbox rows exceed their bound");
+  return result;
+}
+
+export interface InboxSourceState {
+  kind: "missing" | "file" | "directory";
+  category: "fixed" | "candidate" | "log" | "metadata";
+  dev?: string; ino?: string; mode?: string; size?: number; mtimeNs?: string; ctimeNs?: string; names?: string[];
+}
+export interface InboxSources { paths: string[]; roots: string[]; states: Record<string, InboxSourceState>; version: string }
+const MAX_SOURCES = 16_384, MAX_TAIL_BYTES = 256 * 1024;
+const fixedFiles = ["amem.config.json", "capture-config.json", "formats.json", "profile.json", "shards.json", "aliases.jsonl", "lifecycle.jsonl", "profile.lock", "public-prune-view.intent.json", "candidates.db", "candidates.db-wal"];
+const logDirectory = (value: string) => /(?:^|\/)(?:log|local)$/.test(value);
+const evidenceDirectory = (value: string) => /(?:^|\/)(?:public-prune-objects|public-prune-inputs|public-prune-input-sets|bridge-snapshots)(?:\/|$)/.test(value);
+function validPath(value: string): void {
+  if (typeof value !== "string" || value.startsWith("/") || Buffer.byteLength(value) > 4096 || value !== "" && value.split("/").some(part => !part || part === "." || part === "..")) throw Error("inbox source inventory is invalid");
+}
+function category(value: string): InboxSourceState["category"] {
+  return value === "candidates.db" || value === "candidates.db-wal" ? "candidate" : fixedFiles.includes(value) || value === "" ? "fixed"
+    : evidenceDirectory(value) ? "metadata" : /(?:^|\/)(?:log|local)\/[^/]+[.]jsonl$/.test(value) ? "log" : "metadata";
+}
+function state(base: string, path: string): InboxSourceState {
+  validPath(path); const stat = lstatSync(join(base, path), { bigint: true, throwIfNoEntry: false }), type = category(path);
+  if (!stat || path === "candidates.db-wal" && stat.size === 0n) return { kind: "missing", category: type };
+  if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile()) throw Error("inbox source is unavailable");
+  return { kind: stat.isDirectory() ? "directory" : "file", category: type, dev: String(stat.dev), ino: String(stat.ino), mode: String(stat.mode),
+    ...(stat.isFile() ? { size: Number(stat.size), mtimeNs: String(stat.mtimeNs), ctimeNs: String(stat.ctimeNs) } : {}) };
+}
+function snapshotSources(base: string, roots: readonly string[], budget = { left: MAX_SOURCES }): InboxSources {
+  if (roots.length > MAX_SOURCES || new Set(roots).size !== roots.length) throw Error("inbox source inventory exceeds its bound");
+  const states: Record<string, InboxSourceState> = Object.create(null), traversed = new Set<string>(); let visited = 0;
+  const record = (path: string) => {
+    if (!Object.hasOwn(states, path)) { if (++visited > MAX_SOURCES) throw Error("inbox source inventory exceeds its bound"); states[path] = state(base, path); }
+    return states[path]!;
+  };
+  const visit = (path: string, recursive = false) => {
+    validPath(path); const parts = path.split("/"); for (let index = 1; index < parts.length; index++) record(parts.slice(0, index).join("/"));
+    const current = record(path);
+    if (current.kind !== "directory" || traversed.has(path) || !logDirectory(path) && !evidenceDirectory(path) && !recursive) return;
+    traversed.add(path);
+    const iterator = opendirSync(join(base, path)), names: string[] = [];
+    try { for (;;) { const entry = iterator.readSync(); if (!entry) break; if (--budget.left < 0) throw Error("inbox source inventory exceeds its bound");
+      if (!recursive && logDirectory(path) && !entry.name.endsWith(".jsonl")) continue;
+      names.push(entry.name); visit(path ? `${path}/${entry.name}` : entry.name, recursive || evidenceDirectory(path));
+    } } finally { iterator.closeSync(); }
+    current.names = names.sort();
+  };
+  visit(""); for (const file of fixedFiles) visit(file); for (const root of roots) { validPath(root); visit(root); }
+  const paths = Object.keys(states).sort(), ordered: Record<string, InboxSourceState> = Object.create(null); for (const path of paths) ordered[path] = states[path]!;
+  return { paths, roots: [...roots].sort(), states: ordered, version: createHash("sha256").update(JSON.stringify(ordered)).digest("hex") };
+}
+export function inboxSources(base: string, roots: readonly string[] = []): InboxSources { return snapshotSources(base, roots); }
+/** Compatibility helper for existing metadata-only fixtures; production uses inboxSourceChange with the complete frame. */
+export function inboxSourceVersion(base: string, paths: readonly string[]): string {
+  return snapshotSources(base, paths.filter(path => path !== "" && !fixedFiles.includes(path))).version;
+}
+function plainNoteTail(base: string, path: string, before: InboxSourceState | undefined, after: InboxSourceState, budget: { left: number }): boolean {
+  const offset = before?.kind === "file" ? before.size! : 0;
+  if (after.kind !== "file" || before && before.kind !== "missing" && (before.kind !== "file" || before.dev !== after.dev || before.ino !== after.ino || before.mode !== after.mode)
+    || !Number.isSafeInteger(offset) || !Number.isSafeInteger(after.size) || after.size! <= offset || after.size! - offset > budget.left) return false;
+  const length = after.size! - offset, file = join(base, path), fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd, { bigint: true });
+    if (String(opened.dev) !== after.dev || String(opened.ino) !== after.ino || Number(opened.size) !== after.size || String(opened.mtimeNs) !== after.mtimeNs || String(opened.ctimeNs) !== after.ctimeNs) return false;
+    const bytes = Buffer.alloc(length); let at = 0; while (at < length) { const count = readSync(fd, bytes, at, length - at, offset + at); if (!count) return false; at += count; }
+    budget.left -= length;
+    const current = fstatSync(fd, { bigint: true }); if (String(current.ctimeNs) !== after.ctimeNs || Number(current.size) !== after.size || bytes.at(-1) !== 10) return false;
+    for (const line of new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes).split("\n").slice(0, -1)) {
+      const row = checkedEntry(JSON.parse(line));
+      if (row.op !== "note" || row.supersedes !== undefined || row.promotedFrom !== undefined) return false;
+    }
+    return true;
+  } catch { return false; } finally { closeSync(fd); }
+}
+/** Classifies only prior screened data for stale serving, never admits a new body.
+ * ponytail: large-file append classification trusts the repository's append-only writer invariant. A same-user
+ * raw prefix rewrite plus plain-note suffix is outside that ceiling; a core append-revision proof is the upgrade.
+ * Only the complete new tail (256KiB total) is read on the request loop; the worker fully revalidates sources. */
+export function inboxSourceChange(base: string, previous: InboxSources): { sources: InboxSources; changed: boolean; hard: boolean } {
+  const sources = snapshotSources(base, previous.roots); if (sources.version === previous.version) return { sources, changed: false, hard: false };
+  let hard = false; const budget = { left: MAX_TAIL_BYTES }, changes = new Set([...previous.paths, ...sources.paths]);
+  for (const path of changes) {
+    const before = previous.states[path], after = sources.states[path]; if (JSON.stringify(before) === JSON.stringify(after)) continue;
+    if (after?.category === "candidate" && (path === "candidates.db-wal" && (after.kind === "missing" || after.kind === "file") && (!before || before.kind === "missing" || before.kind === "file")
+      || (!before || before.kind === "missing") && after.kind === "file"
+      || before?.kind === "file" && after.kind === "file" && before.dev === after.dev && before.ino === after.ino && before.mode === after.mode && after.size! >= before.size!)) continue;
+    if (after?.category === "log" && plainNoteTail(base, path, before, after, budget)) continue;
+    // A log namespace may grow only when every added file is itself a verified plain-note tail.
+    if (before?.kind === "directory" && after?.kind === "directory" && logDirectory(path) && before.dev === after.dev && before.ino === after.ino && before.mode === after.mode
+      && (before.names ?? []).every(name => after.names?.includes(name))) continue;
+    hard = true;
+  }
+  return { sources, changed: true, hard };
+}
+function projectRoots(base: string, project: string): string[] {
+  const roots = new Set<string>(), selected = readSelector(base).selector;
+  const view = selected?.schema === "agent-mem.profile/v2" || selected?.schema === "agent-mem.profile/v3"
+    ? readPublicPruneViewForActivation(base, selected.pruneInputSetHash, selected.generation) : undefined;
+  const add = (value: string) => { const path = relative(base, value); validPath(path); roots.add(path); };
+  add(join(base, "machine.json"));
+  const raw = (dir: string) => { add(dir); for (const folder of ["log", "local"]) add(join(dir, folder)); };
+  const metadata = (dir: string) => { for (const name of ["project.json", "generation.json", "generation-seal.json", "migration-sources.json", "machine.json", "prune-translations.jsonl"]) add(join(dir, name)); };
+  const bridge = (dir: string, generation: string) => {
+    const pointer = join(dir, "generations", generation, "bridge-snapshot.json"); add(pointer);
+    const value = readProfileJSON(pointer, 4096) as { commit?: unknown } | undefined;
+    if (value?.commit !== undefined) { if (typeof value.commit !== "string" || value.commit.length !== 40 || !/^[a-f0-9]+$/.test(value.commit)) throw Error("inbox bridge source is invalid"); add(join(dir, "generations", generation, "bridge-snapshots", value.commit)); }
+  };
+  if (existsSync(join(base, "shards.json"))) {
+    const keys = [project, ...aliasedKeys(base, project)];
+    for (const { dir, key } of [{ dir: join(base, "user"), key: "user" }, ...keys.map(key => ({ dir: shardDir(base, key), key: `project:${key}` }))]) {
+      raw(dir); metadata(dir);
+      for (const legacy of [join(dir, "legacy"), join(dir, "legacy-main")]) { raw(legacy); add(join(legacy, "machine.json")); }
+      if (view?.realms[key]) for (const folder of ["public-prune-objects", "public-prune-inputs", "public-prune-input-sets"]) add(join(dir, folder));
+    }
+  } else {
+    raw(base);
+    if (selected?.kind === "generation" && selected.generation) { const dir = generationDir(base, selected.generation); raw(dir); metadata(dir); bridge(base, selected.generation); }
+  }
+  if (selected?.schema === "agent-mem.profile/v2" || selected?.schema === "agent-mem.profile/v3") add(join(base, "public-prune-input-sets", `${selected.pruneInputSetHash}.json`));
+  if (selected?.schema === "agent-mem.profile/v3") {
+    add(join(base, "sync-placement", "active.json"));
+    for (const name of ["epoch.json", "activation.json"]) add(join(base, "sync-placement", "epochs", selected.placementHead, name));
+  }
+  return [...roots].sort();
+}
+export function createInboxSourceTracker(base: string) {
+  const initial = snapshotSources(base, []), frames: InboxSources[] = [], roots = new Set<string>(), projects = new Set<string>(), budget = { left: MAX_SOURCES };
+  return { beforeProject(project: string) {
+    if (projects.has(project)) return; projects.add(project); const added = projectRoots(base, project).filter(path => !roots.has(path));
+    for (const path of added) roots.add(path); if (added.length) frames.push(snapshotSources(base, added, budget));
+  }, before(): InboxSources {
+    const states: Record<string, InboxSourceState> = Object.assign(Object.create(null), initial.states);
+    for (const frame of frames) for (const path of frame.paths) if (!Object.hasOwn(states, path)) states[path] = frame.states[path]!;
+    const paths = Object.keys(states).sort(); if (paths.length > MAX_SOURCES) throw Error("inbox source inventory exceeds its bound");
+    const ordered: Record<string, InboxSourceState> = Object.create(null); for (const path of paths) ordered[path] = states[path]!;
+    return { paths, roots: [...roots].sort(), states: ordered, version: createHash("sha256").update(JSON.stringify(ordered)).digest("hex") };
+  }, after() { return snapshotSources(base, [...roots]); } };
+}

package/src/ui/panel.js

@@ -6,16 +6,17 @@ export default (host) => {
   host.mount.append(root);
   let panel = "review", params = {}, project = null;
   const go = (p, extra = {}) => host.navigate(host.tool, p, { ...(project ? { project } : {}), ...extra });
-  const btn = (text, onclick, cls = "btn") => h("button", { type: "button", class: cls, text, onclick });
+  const btn = (text, onclick, cls = "btn") => ui.button(text, onclick, { ...(cls.includes("primary") ? { tone: "primary" } : cls.includes("danger") ? { tone: "danger" } : {}) });
   const day = (iso) => (typeof iso === "string" ? iso.slice(0, 16).replace("T", " ") : "");
   const line = (text, max = 120) => { const flat = String(text ?? "").replace(/\s+/g, " ").trim(); return flat.length > max ? `${flat.slice(0, max - 3)}...` : flat; };
   const act = (input) => host.action({ ...input, ...(project ? { project } : {}) });
 
   const picker = (s) => {
     const list = s.projects ?? [];
+    if (s.error && !s.project && list.length === 1) return btn(`Choose project ${list[0]}`, () => go(panel, { project: list[0] }));
     if (list.length < 2) return list.length ? h("p", { class: "amem-sub", text: `Project ${list[0]}` }) : null;
     const select = h("select", { name: "project", class: "amem-input", "aria-label": "Project", onchange: () => { project = select.value; go(panel); } },
-      list.map((key) => { const o = h("option", { value: key, text: key }); if (key === s.project) o.selected = true; return o; }));
+      [...(!s.project ? [h("option", { value: "", text: "Choose an active project", disabled: true, selected: true })] : []), ...list.map((key) => { const o = h("option", { value: key, text: key }); if (key === s.project) o.selected = true; return o; })]);
     return h("label", { class: "amem-bar" }, h("span", { text: "Project" }), select);
   };
 
@@ -33,7 +34,10 @@ export default (host) => {
       h("p", { class: "amem-sub", text: `Reason: ${r.diff.reason}` })) });
     const evidence = [...(r.evidence ?? []).map((ref) => ({ title: ref, sub: "evidence reference" })),
       ...(r.targets ?? []).map((t) => ({ title: t.text ? line(t.title ?? t.text) : `mem:${t.id} (not visible)`, sub: t.at ? `mem:${t.id.slice(0, 8)} · ${t.kind} · ${day(t.at)}` : "" }))];
-    sections.push({ title: `Evidence (${evidence.length})`, open: evidence.length > 0, body: ui.rows(evidence, (e) => ui.row(e)) ?? ui.empty("No evidence attached", "This kind of candidate carries no references.") });
+    sections.push({ title: `Evidence (${evidence.length})`, open: evidence.length > 0, body: h("div", {},
+      ui.rows(evidence, (e) => ui.row(e)) ?? ui.empty("No evidence attached", "This kind of candidate carries no references."),
+      ...(r.targets ?? []).filter((t) => typeof t.text === "string").map((t) => h("blockquote", {}, h("pre", { class: "amem-pre", text: t.text }))),
+      h("p", { class: "amem-sub", text: "Source session, proposing agent and times seen are not recorded in the candidate store." })) });
     sections.push({ title: `Similar memories (${r.overlaps.length})`, open: r.overlaps.length > 0,
       body: ui.rows(r.overlaps, (o) => ui.row({ title: o.title ?? "Untitled note", sub: `mem:${o.id.slice(0, 8)} · overlap ${o.score.toFixed(2)}` })) ?? ui.empty("No similar memories") });
     if (r.edit !== null) {