@staix/agent-mem 0.16.0 → 0.17.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Bounded project memory tools and seven deterministic capture hooks, without a resident worker.",
   "mcpServers": {
     "agent-mem": {

package/README.md

@@ -2,7 +2,7 @@
 
 Curated memory with append-only JSONL logs, a derived SQLite index, short- and long-term tiers, a typed graph, goals with leases, and git sync between machines. Extracted from [agent-hub](https://github.com/STAIxBWLB/agent-hub), with compatible storage and entry IDs.
 
-Version: 0.16.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.17.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 
@@ -151,6 +151,23 @@ Open a review-only `MemoryStore` with `deferPromotions: true` to prevent unrelat
 
 Acceptance normalizes its note once, including timestamp, content ID and short-term expiry, then screens and appends that exact body. The final target-revision check and correction appends hold the same machine-local `mutation-lock.db` writer transaction used by this version's ordinary memory, import and sync writers. This lock is independent of the derived index, so an ordinary write still persists when SQLite is busy. External or older writers that edit segments without this lock do not participate in serialization. The logs remain authoritative after an interrupted acceptance; the next read refreshes the derived index.
 
+## Console (acon)
+
+`@staix/agent-mem/ui-plugin` is a plugin for the local agent console `acon` (STAIxBWLB/agent-console, contract api 1). It adds a Memory area with the panels Review, Search, Timeline, Work lists, Goals and Capacity, puts pending candidates (group `candidate`) and a capture capacity proposal (group `alert`) in the console inbox, and answers the console palette with memory search hits.
+
+```sh
+amem setup console           # preview
+amem setup console --apply   # write $AGENTHUB_HOME/console/plugins/amem.json
+amem setup console --undo    # remove it (only when it points at this install)
+```
+
+The manifest holds the absolute path and sha256 of `src/ui/plugin.ts`, in a 0700 directory and a 0600 file, as acon requires. acon refuses a module whose hash changed, so run `amem setup console --apply` again after upgrading amem. `setup all` does not include it.
+
+- Reads are screened. Search, Timeline and Work lists call the in-process `amem_search`, `amem_timeline` and `amem_work_state_read` handlers for the chosen project and forward every option the tool declares, so console search returns exactly the `amem_search` set for the same query. Goals and the review queue pass the configured policy; a candidate that fails it, or whose target fails it, is not shown (the panel counts it and points to `amem review walk`). The console never shows unscreened content, also not to the person. It runs in no repository, so a repository's `.amem/config` narrowing does not apply; the machine's `amem.config.json` does.
+- Review actions are the CLI's. Accept runs the same acceptance as `amem review accept` and writes the same note, edit-then-accept is `review walk`'s edit (the person's own note, then the candidate closed), reject is `review reject`. The console stamps the person as the actor (peer `person`). A privacy-screen hit refuses with a named reason and writes nothing. agent-mem keeps no reject reason, so a reason typed in the console is not recorded, and the reply says so.
+- Undo is offered for 10 seconds and stays bound to what that console just did: undoing an accept forgets the accepted note (an append-only forget op; a note a correction replaced shows again), undoing a reject makes the candidate pending again. A promotion has no undo. `merge_into` is not offered: the library has no merge operation.
+- Destructive forms (`gc`, `capacity_apply`, `project_forget`, `decay_apply`, `prune`) answer `needsConfirm` with the preview and `changes[]` and never write on the first call. The console's single-use confirm token carries the fingerprint back; the plugin recomputes the preview and writes only when it still matches. `prune` needs a generation home, as `amem prune` does.
+
 ## Shell completion
 
 Generate completion for `zsh`, `bash`, or `fish` with `amem completion <shell>`. Generation prints a script to stdout; it does not install files or edit shell configuration. The following commands configure shell completion.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,7 @@
     "bun": ">=1.4.2"
   },
   "devDependencies": {
+    "@staix/agent-console": "github:STAIxBWLB/agent-console#952e962",
     "@types/bun": "^1.3.0",
     "typescript": "^5.8.0",
     "@staix/agent-mem-v1": "npm:@staix/agent-mem@0.1.1",
@@ -24,7 +25,8 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./platform": "./src/memory/platform.ts"
+    "./platform": "./src/memory/platform.ts",
+    "./ui-plugin": "./src/ui/plugin.ts"
   },
   "bin": {
     "amem": "bin/amem.js"

package/src/cli.ts

@@ -271,7 +271,12 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   const { definition, options, rawArgs: args } = parsed;
   const identity = cliAttribution() ?? { actor: "person" as const, peer: "person" }, actor = identity.actor;
   if (parsed.path[0] === "setup") {
-    if (parsed.positionals.length !== 1 || options["--apply"] === true && options["--undo"] === true) throw new Error("usage: amem setup claude|codex|kimi|pi|qwen|jcode|opencode|gemini|agy|all [--apply|--undo]");
+    if (parsed.positionals.length !== 1 || options["--apply"] === true && options["--undo"] === true) throw new Error("usage: amem setup claude|codex|kimi|pi|qwen|jcode|opencode|gemini|agy|all|console [--apply|--undo]");
+    if (parsed.positionals[0] === "console") {
+      const { consoleSetup, consoleSetupText } = await import("./setup-console.ts");
+      const mode = options["--apply"] === true ? "apply" : options["--undo"] === true ? "undo" : "preview", result = consoleSetup(mode, context.env ?? process.env);
+      return options["--json"] === true ? JSON.stringify(result, null, 2) : consoleSetupText(result, mode);
+    }
     const { runSetup } = await import("./setup.ts");
     return runSetup(parsed.positionals[0]!, options["--apply"] === true ? "apply" : options["--undo"] === true ? "undo" : "preview", {
       env: context.env ?? process.env, stdinTTY: context.stdinTTY ?? process.stdin.isTTY, cwd: context.cwd ?? process.cwd(),

package/src/commands-table.ts

@@ -25,7 +25,7 @@ export const GLOBAL_OPTIONS = { "--help": flag("Show help") };
 export const ROOT_OPTIONS = { "--version": flag("Show version"), ...json };
 export const COMMANDS: Record<string, CommandDefinition> = {
   consolidate: { description: "Queue deterministic project-local consolidation candidates; curated notes change only after explicit acceptance", mutates: true, options: { ...json, "--project": text("The current project's key; another project is refused (run from its directory)") } },
-  setup: { description: "Preview reversible MCP setup and supported capture hooks for native coding CLIs; apply and undo use explicit flags", options: { ...json, "--apply": flag("Apply the previewed setup"), "--undo": flag("Restore the original configuration") }, args: [{ name: "target", values: ["claude", "codex", "kimi", "pi", "qwen", "jcode", "opencode", "gemini", "agy", "all"] }] },
+  setup: { description: "Preview reversible MCP setup and supported capture hooks for native coding CLIs, or the acon console plugin manifest (console); apply and undo use explicit flags", options: { ...json, "--apply": flag("Apply the previewed setup"), "--undo": flag("Restore the original configuration") }, args: [{ name: "target", values: ["claude", "codex", "kimi", "pi", "qwen", "jcode", "opencode", "gemini", "agy", "all", "console"] }] },
   mcp: { description: "Run the project-bound MCP stdio server for this session" },
   hook: { description: "Run a fail-open, context-only Claude Code hook", args: [{ name: "event", values: [...HOOK_EVENTS] }] },
   ingest: { description: "Incrementally capture native session transcripts without a watcher", options: { ...json, "--since": text("ISO date or time") }, args: [{ name: "kind", values: ["codex", "kimi", "pi", "qwen"] }] },

package/src/memory/candidates.ts

@@ -264,6 +264,38 @@ export class CandidateStore {
       if (candidate.input.kind === "consolidation") this.retainConsolidationReviews();
     }).immediate();
   }
+  /**
+   * Undo of a reject: the rejected candidate is pending again. Only a rejected one; an accepted one is undone by forgetting its note.
+   * Retention deletes a decided candidate older than 30 days on the next open, so a caller offering undo passes the candidate it rejected as
+   * `restore`: when the row is already gone it is written back as pending with its original time, after the same identity and hash checks as a read.
+   */
+  reopen(id: string, context: { project: string; actor: "person" | "agent"; restore?: Candidate }): void {
+    validActor(context.actor);
+    if (!candidateId(id) || !text(context.project, 400)) throw new Error("invalid candidate identity");
+    this.db.transaction(() => {
+      // No prune here: it would delete the very row this undoes.
+      const row = this.db.query("SELECT * FROM candidates WHERE id = ? AND project IN (SELECT value FROM json_each(?))").get(id, this.scope(context.project)) as Parameters<CandidateStore["decode"]>[0] | null;
+      const candidate = row ? this.decode(row) : undefined, restore = context.restore;
+      if (candidate) {
+        if (candidate.status !== "rejected") throw new Error("only a rejected candidate can be reopened");
+        this.db.query("UPDATE candidates SET status = 'pending' WHERE id = ? AND status = 'rejected'").run(id);
+      } else {
+        if (!restore || restore.id !== id || !(JSON.parse(this.scope(context.project)) as string[]).includes(restore.input.project)) throw new Error("candidate unavailable");
+        validate(restore.input);
+        if (hash({ schema: "agent-mem.candidate/v1", input: restore.input }) !== id) throw new Error("candidate content hash mismatch");
+        const at = Date.parse(restore.createdAt);
+        if (!Number.isFinite(at)) throw new Error("invalid candidate time");
+        this.db.query("INSERT INTO candidates (id, project, kind, payload, at, status) VALUES (?, ?, ?, ?, ?, 'pending')").run(id, restore.input.project, restore.input.kind, canonical(restore.input), at);
+      }
+      const input = candidate?.input ?? restore!.input;
+      // The lasting review identity would make a later proposal of the same consolidation a no-op; the decision is withdrawn.
+      if (input.kind === "consolidation") this.db.query("DELETE FROM consolidation_reviews WHERE id = ?").run(id);
+    }).immediate();
+  }
+  /** Projects with candidates waiting for review, as stored (an alias key is not resolved here). */
+  projects(): string[] {
+    return (this.db.query("SELECT DISTINCT project FROM candidates WHERE status IN ('pending', 'accepting') ORDER BY project").all() as { project: string }[]).map(row => row.project);
+  }
   accept(id: string, context: CandidateAcceptance): CandidateAcceptanceResult {
     validActor(context.actor); publicOnly(context.verdict);
     if (realPath(context.store.profile.home) !== realPath(this.dir) || typeof context.policy !== "function") throw new Error("candidate acceptance requires its memory store and a current host policy");

package/src/memory/gc.ts

@@ -14,7 +14,8 @@ import { lifecycleResolver } from "./lifecycle.ts";
  * or rewritten (#13 AC5, #15 D7). An archived project is still bounded (cold shards shrink first); a forgotten one is skipped, never opened.
  */
 
-export interface GcShardPlan { key: string; state: "active" | "archived"; rows: number; bytes: number; capMb: number; retentionDays: number; expiredRows: number; overCap: boolean }
+/** `trimRows`: unexpired rows, oldest first, that must go for the shard to fit its cap once the expired ones are gone. `evict()` removes them in whole batches. */
+export interface GcShardPlan { key: string; state: "active" | "archived"; rows: number; bytes: number; capMb: number; retentionDays: number; expiredRows: number; overCap: boolean; trimRows: number }
 export interface GcShardResult { key: string; expired: number; trimmed: number; batches: number; remainingOverCap: boolean }
 export interface GcSkip { key: string; reason: string }
 export interface GcResult { dryRun: boolean; shards: GcShardResult[]; skipped: GcSkip[] }
@@ -26,15 +27,16 @@ export function planGc(base: string, opts: { now?: () => number } = {}): GcShard
   for (const shard of walkShards(base)) {
     const state = stateOf(shard.key);
     if (state === "forgotten") continue;
-    let rows = 0, bytes = 0, expiredRows = 0, capMb = 0, retentionDays = 0;
+    let rows = 0, bytes = 0, expiredRows = 0, capMb = 0, retentionDays = 0, trimRows = 0;
     for (const dir of shard.machineDirs) {
       const config = readCaptureConfig(dir, base);
       capMb = config.capMb; retentionDays = config.retentionDays;
-      const stats = captureShardStats(dir);
+      const stats = captureShardStats(dir), cutoff = new Date(now() - config.retentionDays * 24 * 3600_000).toISOString();
       rows += stats.rows; bytes += stats.bytes;
-      expiredRows += expiredIn(dir, new Date(now() - config.retentionDays * 24 * 3600_000).toISOString());
+      expiredRows += expiredIn(dir, cutoff);
+      trimRows += trimIn(dir, cutoff, config.capMb * 1024 * 1024);
     }
-    out.push({ key: shard.key, state, rows, bytes, capMb, retentionDays, expiredRows, overCap: capMb > 0 && bytes > capMb * 1024 * 1024 });
+    out.push({ key: shard.key, state, rows, bytes, capMb, retentionDays, expiredRows, overCap: capMb > 0 && bytes > capMb * 1024 * 1024, trimRows });
   }
   return out.sort((a, b) => a.key.localeCompare(b.key));
 }
@@ -48,6 +50,21 @@ function expiredIn(dir: string, cutoff: string): number {
   } catch { return 0; }
 }
 
+/** Each machine directory has its own cap (evict() runs per store): the unexpired rows, oldest first, that must go to fit it. Read-only. */
+function trimIn(dir: string, cutoff: string, capBytes: number): number {
+  if (capBytes <= 0 || !existsSync(join(dir, "capture.db"))) return 0;
+  try {
+    const db = new Database(join(dir, "capture.db"), { readonly: true });
+    try {
+      db.run("PRAGMA busy_timeout = 3000");
+      const kept = db.query("SELECT bytes FROM rows WHERE at >= ? ORDER BY at, id").all(cutoff) as { bytes: number }[];
+      let left = kept.reduce((sum, row) => sum + row.bytes, 0), n = 0;
+      for (const row of kept) { if (left <= capBytes) break; left -= row.bytes; n++; }
+      return n;
+    } finally { db.close(); }
+  } catch { return 0; }
+}
+
 export function runGc(base: string, opts: GcOptions = {}): GcResult {
   const maxBatches = opts.maxBatchesPerShard ?? 1;
   if (!Number.isSafeInteger(maxBatches) || maxBatches < 1 || maxBatches > 1000) throw new Error("maxBatchesPerShard takes a number from 1 to 1000");

package/src/setup-console.ts

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { chmodSync, lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+
+export interface ConsoleSetup { file: string; module: string; change: "add" | "replace" | "unchanged" | "remove" | "none"; reason?: string }
+
+/**
+ * `amem setup console`: the acon plugin manifest `{api, tool, module, sha256}` at `$AGENTHUB_HOME/console/plugins/amem.json`, in a 0700 directory
+ * and a 0600 file, which is what agent-console's scanPlugins accepts. Preview writes nothing; undo removes only a manifest that points at this install.
+ */
+export function consoleSetup(mode: "preview" | "apply" | "undo", env: Readonly<Record<string, string | undefined>> = process.env,
+  module = fileURLToPath(new URL("./ui/plugin.ts", import.meta.url))): ConsoleSetup {
+  const family = env.AGENTHUB_HOME?.trim() ? resolve(env.AGENTHUB_HOME) : join(env.HOME?.trim() || homedir(), ".agenthub");
+  const dir = join(family, "console", "plugins"), file = join(dir, "amem.json");
+  // acon refuses a manifest directory or file that is a link, another kind of entry or another user's; so does setup, before writing anything.
+  for (const [path, kind] of [[dir, "directory"], [file, "file"]] as const) {
+    const info = lstatSync(path, { throwIfNoEntry: false });
+    if (!info) continue;
+    if (kind === "directory" ? !info.isDirectory() : !info.isFile()) throw Error(`${path}: acon needs a real ${kind}, not a link or another entry`);
+    if (typeof process.getuid === "function" && info.uid !== process.getuid()) throw Error(`${path} is owned by another user; acon would refuse it`);
+  }
+  const before = lstatSync(file, { throwIfNoEntry: false }) ? JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown> : undefined;
+  if (mode === "undo") {
+    if (!before) return { file, module, change: "none", reason: "no console manifest" };
+    if (before.module !== module) throw Error(`${file} points at another amem install (${String(before.module)}); left as is`);
+    unlinkSync(file);
+    return { file, module, change: "remove" };
+  }
+  const next = { api: 1, tool: "amem", module, sha256: createHash("sha256").update(readFileSync(module)).digest("hex") };
+  const mode7 = (path: string, want: number) => (lstatSync(path, { throwIfNoEntry: false })?.mode ?? want) & 0o777;
+  const modesOk = mode7(dir, 0o700) === 0o700 && mode7(file, 0o600) === 0o600;
+  if (isDeepStrictEqual(before, next) && modesOk) return { file, module, change: "unchanged" };
+  const change = before ? "replace" : "add";
+  if (mode === "apply") {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, file);
+    chmodSync(file, 0o600);
+  }
+  return { file, module, change, ...(modesOk ? {} : { reason: "permissions: plugin directory 0700, manifest 0600" }) };
+}
+
+export const consoleSetupText = (result: ConsoleSetup, mode: "preview" | "apply" | "undo"): string =>
+  `console plugin: ${mode === "preview" && result.change !== "unchanged" && result.change !== "none" ? `would ${result.change}` : result.change} ${result.file}${result.change === "remove" || result.change === "none" ? "" : ` -> ${result.module}`}${result.reason ? ` (${result.reason})` : ""}`
+  + (mode === "preview" && result.change !== "unchanged" ? "\nPreview only; add --apply to write it, --undo to remove it. Re-run after upgrading amem: acon refuses a module whose hash changed." : "");

package/src/ui/panel.css

@@ -0,0 +1,15 @@
+.amem { display: flex; flex-direction: column; gap: var(--acon-space-3); min-width: 0; }
+.amem > .btn, .amem-card > .btn { align-self: flex-start; }
+.amem-bar { display: flex; flex-wrap: wrap; align-items: center; gap: var(--acon-space-2); }
+.amem-bar input[type="search"] { flex: 1; min-width: 0; max-width: 480px; }
+.amem-inline { display: inline-flex; flex-wrap: wrap; gap: var(--acon-space-2); }
+.amem-input { min-height: 32px; min-width: 0; max-width: 100%; padding: 0 10px; border: 1px solid var(--acon-line-2); border-radius: var(--acon-radius-2); background: var(--acon-surface); color: var(--acon-text); font: inherit; }
+.amem-text { width: 100%; min-height: 10em; padding: var(--acon-space-2) 10px; font: var(--acon-text-sm)/1.5 var(--acon-font-mono); resize: vertical; }
+.amem-form { display: flex; flex-direction: column; gap: var(--acon-space-2); }
+.amem-form .btn { align-self: flex-start; }
+.amem-sub { margin: 0; color: var(--acon-text-2); overflow-wrap: anywhere; }
+.amem-card { display: flex; flex-direction: column; gap: var(--acon-space-2); }
+.amem-card h3 { margin: 0; font-size: var(--acon-text-lg); }
+.amem-diff { display: flex; flex-direction: column; gap: var(--acon-space-1); }
+.amem-pre { margin: 0 0 var(--acon-space-2); padding: var(--acon-space-3); max-height: 40vh; overflow: auto; white-space: pre-wrap; overflow-wrap: anywhere; background: var(--acon-surface-2); border: 1px solid var(--acon-line); border-radius: var(--acon-radius-2); font: var(--acon-text-sm)/1.5 var(--acon-font-mono); }
+@media (max-width: 600px) { .amem-inline { width: 100%; } .amem-inline .amem-input { flex: 1; } }

package/src/ui/panel.js

@@ -0,0 +1,129 @@
+// amem console panels (acon api 1). Runs under the shell's strict CSP and renders data as text through host.ui only.
+export default (host) => {
+  const { ui } = host;
+  const { h } = ui;
+  const root = h("div", { class: "amem" });
+  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 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 (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; }));
+    return h("label", { class: "amem-bar" }, h("span", { text: "Project" }), select);
+  };
+
+  const reviewDetail = (r) => {
+    const reason = h("input", { type: "text", name: "reason", class: "amem-input", placeholder: "Reason (optional)", "aria-label": "Reject reason (optional)" });
+    const actions = [
+      r.acceptable ? btn("Accept", () => act({ action: "accept", id: r.id }), "btn primary") : null,
+      h("form", { class: "amem-inline", onsubmit: (e) => { e.preventDefault(); act({ action: "reject", id: r.id, ...(reason.value.trim() ? { reason: reason.value.trim() } : {}) }); } },
+        reason, h("button", { type: "submit", class: "btn", text: "Reject" })),
+    ].filter(Boolean);
+    const sections = [];
+    if (r.diff) sections.push({ title: "Now and proposed", open: true, body: h("div", { class: "amem-diff" },
+      h("strong", { text: "Now" }), h("pre", { class: "amem-pre", text: r.diff.now ?? "(the current note is not visible)" }),
+      h("strong", { text: "Proposed" }), h("pre", { class: "amem-pre", text: r.diff.proposed }),
+      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: `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) {
+      const text = h("textarea", { name: "edit", class: "amem-input amem-text", "aria-label": "Edited text" });
+      text.value = r.edit;
+      sections.push({ title: "Edit, then accept", body: h("form", { class: "amem-form", onsubmit: (e) => { e.preventDefault(); act({ action: "edit_accept", id: r.id, text: text.value }); } },
+        text, h("button", { type: "submit", class: "btn", text: "Save edit and accept" })) });
+    }
+    return ui.detail({ kind: `${r.kind} candidate`, title: line(r.text, 90), state: { text: "pending", tone: "warn" }, whoseMove: "you", actions, summary: r.text,
+      provenance: [{ label: "Proposed", value: day(r.createdAt), at: r.createdAt }, { label: "Project", value: project ?? "" }, ...(r.noteKind ? [{ label: "Note kind", value: r.noteKind }] : [])],
+      sections, footer: [r.id] });
+  };
+
+  const views = {
+    review(s) {
+      const rows = s.rows ?? [], picked = rows.find((r) => r.id === s.selected);
+      const hidden = s.hidden ? ui.notice(`${s.hidden} candidate${s.hidden === 1 ? " is" : "s are"} withheld by the privacy screen; review ${s.hidden === 1 ? "it" : "them"} with amem review walk.`, "warn") : null;
+      if (picked) return [btn("Back to the queue", () => go("review")), reviewDetail(picked)];
+      return [hidden, ui.rows(rows, (r) => ui.row({ title: line(r.text), sub: `${r.kind} · ${day(r.createdAt)}${r.overlaps.length ? ` · ${r.overlaps.length} similar` : ""}`,
+        onOpen: () => go("review", { id: r.id }),
+        verbs: [r.acceptable ? btn("Accept", () => act({ action: "accept", id: r.id }), "btn primary") : null, btn("Reject", () => act({ action: "reject", id: r.id }))].filter(Boolean) }))
+        ?? ui.empty("No candidates waiting", "Agents propose memories with amem_remember; they wait here for your decision.")];
+    },
+    find(s) {
+      const q = h("input", { type: "search", name: "q", class: "amem-input", value: s.q ?? "", placeholder: "Search memory", "aria-label": "Search memory" });
+      q.value = s.q ?? "";
+      const form = h("form", { class: "amem-bar", role: "search", onsubmit: (e) => { e.preventDefault(); go("find", q.value.trim() ? { q: q.value.trim() } : {}); } }, q, h("button", { type: "submit", class: "btn", text: "Search" }));
+      const hits = s.hits ?? [];
+      return [form, s.q ? ui.rows(hits, (x) => {
+        const v = x.view, c = x.capture;
+        return ui.row({ title: line(v ? v.title ?? v.text : c?.excerpt), sub: [x.source, v?.kind ?? c?.event, day(v?.at ?? c?.at), v?.stale ? "stale" : ""].filter(Boolean).join(" · ") });
+      }) ?? ui.empty("Nothing found", "Search uses the same screened index as amem_search.") : ui.empty("Search this project's memory", "Results are screened exactly like amem_search.")];
+    },
+    timeline(s) {
+      return [ui.rows(s.entries ?? [], (x) => {
+        const c = x.capture;
+        return c ? ui.row({ title: line(c.excerpt), sub: `capture · ${c.event} · ${day(c.at)}` }) : ui.row({ title: line(x.title ?? x.text), sub: `${x.kind} · ${x.tier} · ${x.peer} · ${day(x.at)}` });
+      }) ?? ui.empty("Nothing on the timeline yet")];
+    },
+    work(s) {
+      const lists = s.lists ?? [];
+      return lists.length ? lists.map((l) => h("section", { class: "card amem-card" }, h("h3", { text: l.list }),
+        h("p", { class: "amem-sub", text: Object.entries(l.fields ?? {}).map(([k, v]) => `${k}: ${v}`).join(" · ") }),
+        ui.rows(l.items ?? [], (i) => ui.row({ title: i.task, sub: Object.entries(i.fields ?? {}).map(([k, v]) => `${k}: ${v}`).join(" · ") })) ?? ui.empty("No open items")))
+        : [ui.empty("No open work lists", "Agents write them with amem_work_state_write.")];
+    },
+    goals(s) {
+      return [ui.rows(s.goals ?? [], (g) => ui.row({ title: g.title, sub: [g.milestones.length ? `${g.milestones.length} milestones` : "", g.links.length ? `${g.links.length} linked tasks` : "", day(g.at)].filter(Boolean).join(" · "),
+        chip: { text: g.state, tone: g.state === "done" ? "ok" : g.state === "blocked" ? "err" : "neutral" } })) ?? ui.empty("No goals", "Create one with amem goal add.")];
+    },
+    capacity(s) {
+      if (s.withheld) return [ui.notice("The capacity report is withheld by the privacy screen.", "warn")];
+      const r = s.report;
+      const out = [];
+      if (r) {
+        out.push(h("section", { class: "card amem-card" }, h("h3", { text: "Capture" }),
+          h("dl", { class: "ui-provenance" },
+            h("dt", { text: "Rows" }), h("dd", { text: `${r.capture.rows} in ${r.capture.shards} shards, ${(r.capture.bytes / 1048576).toFixed(1)} MB` }),
+            h("dt", { text: "Growth" }), h("dd", { text: `${Math.round(r.capture.rowsPerDay)} rows/day` }),
+            h("dt", { text: "Disk free" }), h("dd", { text: `${(r.disk.freeBytes / 1073741824).toFixed(1)} GB` }),
+            h("dt", { text: "Current" }), h("dd", { text: `${r.current.capMb} MB, ${r.current.retentionDays} days` }),
+            h("dt", { text: "Proposed" }), h("dd", { text: `${r.proposal.capMb} MB, ${r.proposal.retentionDays} days` })),
+          h("p", { class: "amem-sub", text: r.proposal.reason }),
+          s.applyNeeded ? btn("Apply proposal...", () => host.action({ action: "capacity_apply" }), "btn primary") : ui.chip("current settings match the proposal", "ok")));
+      } else out.push(ui.empty("No memory home yet"));
+      const cutoff = () => new Date().toISOString().replace(/\.\d{3}Z$/, ".000Z");
+      out.push(h("section", { class: "card amem-card" }, h("h3", { text: "Maintenance" }),
+        h("p", { class: "amem-sub", text: "Each action shows what it will change and runs only after you confirm." }),
+        h("div", { class: "amem-bar" },
+          btn("Evict expired capture...", () => host.action({ action: "gc" })),
+          project ? btn("Demote old notes...", () => act({ action: "decay_apply" })) : null,
+          project ? btn("Prune expired notes...", () => act({ action: "prune", cutoff: cutoff() })) : null,
+          project ? btn("Forget this project...", () => act({ action: "project_forget" }), "btn danger") : null)));
+      return out;
+    },
+  };
+
+  host.onSnapshot((s) => {
+    project = s.project ?? null;
+    // A poll re-renders the view: carry typed values and focus over by field name.
+    const values = new Map([...root.querySelectorAll("input[name], textarea[name]")].map((el) => [el.name, el.value]));
+    const focused = root.contains(document.activeElement) ? document.activeElement.getAttribute("name") : null;
+    const body = s.error ? [ui.notice(s.error, "err")] : !s.projects?.length && panel !== "capacity" ? [ui.empty("No memory yet", "Projects appear once an agent captures or proposes memory.")] : views[panel]?.(s) ?? [ui.empty("Unknown panel")];
+    root.replaceChildren(...[picker(s), ...body].filter(Boolean));
+    for (const el of root.querySelectorAll("input[name], textarea[name]")) if (values.has(el.name) && el.name !== "q") el.value = values.get(el.name);
+    if (focused) root.querySelector(`[name="${focused}"]`)?.focus();
+  });
+  return {
+    show(id, p = {}) { panel = id; params = p; root.replaceChildren(); },
+    hide() {},
+    destroy() { root.remove(); },
+  };
+};

package/src/ui/plugin.ts

@@ -0,0 +1,495 @@
+/**
+ * Console plugin for acon (STAIxBWLB/agent-console contract api 1; UX per STAIxBWLB/vault-mem#48), agent-mem#158.
+ * Reads go through the screened MCP read handlers in process, so the console sees what an MCP client of that project sees.
+ * Review writes run the same library calls as `amem review accept|reject` and `review walk`'s edit, stamped as the person.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createMemoryMcp } from "../mcp-memory.ts";
+import { MCP_TOOLS } from "../mcp.ts";
+import { CandidateStore, type Candidate, type CandidateInput } from "../memory/candidates.ts";
+import { candidateOverlapsBatch } from "../memory/candidate-overlaps.ts";
+import { capacityReport } from "../memory/capacity.ts";
+import { readCaptureConfigFile, writeCaptureConfigFile } from "../memory/capture.ts";
+import { readCatalogFresh } from "../memory/catalog.ts";
+import { configuredPolicy, configuredPolicyOptions } from "../memory/config.ts";
+import { openCuratedForRead, requireShard } from "../memory/curated-read.ts";
+import { applyDecay, assertExactDecayForget, decayPreview, DECAY_DEFAULT_DAYS, readDecayCounters } from "../memory/decay-review.ts";
+import { gcText, planGc, runGc } from "../memory/gc.ts";
+import { memoryHome } from "../memory/home.ts";
+import { appendLifecycle, assertProjectActive, projectState } from "../memory/lifecycle.ts";
+import { hasFailLabel, noteAdd, parseFailTemplate } from "../memory/note-add.ts";
+import type { StandalonePolicy } from "../memory/policy.ts";
+import { applyPrune, planPrune, pruneText } from "../memory/prune.ts";
+import { aliasedKeys, readShardedSelection, resolveAlias } from "../memory/shard.ts";
+import { machineId, MemoryStore, openShardStore, type StoreOptions, type View } from "../memory/store.ts";
+
+// The contract types this module uses, copied from agent-console src/contract.ts (api 1, additive only): src/ takes no
+// package imports. test/ui-plugin.test.ts type-checks the plugin against the real contract and runs its conformance suite.
+type Args = Record<string, unknown>;
+interface Change { op: "create" | "modify" | "delete" | "log"; target: string; note?: string }
+type ActionResult =
+  | ({ ok: true; message?: string; undo?: { action: string } & Args } & Args)
+  | { ok: false; error: string }
+  | { ok: false; needsConfirm: true; preview: string[]; fingerprint: string; verb?: string; changes?: Change[]; warnings?: string[] };
+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> };
+}
+interface Provider {
+  assets: { js: string; css?: string };
+  snapshot(input: { after: number; panel: string } & Args): Promise<Args>;
+  action(input: { action: string; confirmed?: true; fingerprint?: string } & Args): Promise<ActionResult>;
+}
+type Preview = { verb: string; preview: string[]; changes: Change[]; warnings?: string[] };
+type Found = { id: string; project: string; candidate: Candidate };
+
+const asset = (name: string) => readFileSync(new URL(name, import.meta.url), "utf8");
+const VERSION = (JSON.parse(asset("../../package.json")) as { version: string }).version;
+/** agent-mem#143: actions from the console are the person's; the console is never an agent session's surface. */
+const ACTOR = "person" as const;
+const UNDO_MS = 60_000, PLAN_MS = 120_000, PLAN_MAX = 16;
+const ACTIONS = ["accept", "reject", "edit_accept", "accept_undo", "reject_undo", "gc", "capacity_apply", "project_forget", "decay_apply", "prune"];
+const str = (v: unknown): string | undefined => typeof v === "string" && v.trim() ? v : undefined;
+const sha = (v: unknown) => createHash("sha256").update(JSON.stringify(v)).digest("hex");
+const errorText = (e: unknown) => (e instanceof Error ? e.message : String(e)).split("\n")[0]!;
+const oneLine = (text: string, max = 160) => { const flat = text.replace(/\s+/g, " ").trim(); return flat.length > max ? `${flat.slice(0, max - 3)}...` : flat; };
+
+/** What a candidate proposes, as text. */
+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;
+  }
+}
+/** The text `review walk`'s edit opens for a memory or fail candidate. */
+function editText(input: CandidateInput): string | null {
+  if (input.kind === "fail") return `Approach: ${input.approach}\nSymptom: ${input.symptom}\nCause: ${input.cause}\nEvidence: ${input.evidenceRefs.join(", ")}\nRetry when: ${input.retryWhen}\n`;
+  if (input.kind !== "memory") return null;
+  return input.noteKind === "fail" && !hasFailLabel(input.text) ? `Approach: ${input.text}\nSymptom: \nCause: \nEvidence: \nRetry when: \n` : input.text;
+}
+const targetsOf = (input: CandidateInput) => "targets" in input ? input.targets : "target" in input && input.target ? [input.target] : [];
+
+/** The CLI's curatedStore on an explicit home (src/cli.ts keeps its own copy; cli.ts is not a library module). */
+function openCurated(base: string, project: string, opts: StoreOptions, reconciled = true): MemoryStore {
+  assertProjectActive(base, project);
+  const aliases = reconciled ? aliasedKeys(base, project) : [];
+  const withAliases: StoreOptions = aliases.length ? { ...opts, reconcile: { canonical: project, aliases } } : opts;
+  if (existsSync(join(base, "shards.json"))) { readShardedSelection(base); return openShardStore({ ...withAliases, memoryDir: base, project }); }
+  return new MemoryStore({ ...withAliases, memoryDir: base });
+}
+
+/** A refusal that names which part of the screen declined, never the text. */
+function refusal(value: unknown, policy: StandalonePolicy): ActionResult {
+  let personal = false;
+  try { personal = policy.declinesPersonal(JSON.stringify(value)); } catch { /* unreadable: reported as unscreenable */ }
+  return { ok: false, error: `Refused by the privacy screen: ${personal ? "personal data, a configured PII pattern or a deny path" : "a likely secret, or a value the screen cannot read"}. Nothing was written.` };
+}
+
+export const plugin = {
+  manifest: {
+    api: 1 as const, tool: "amem", version: VERSION, title: "Memory", icon: "memory", pollMs: 15_000,
+    panels: [
+      { id: "review", title: "Review", order: 1 },
+      { id: "find", title: "Search", order: 2 },
+      { id: "timeline", title: "Timeline", order: 3 },
+      { id: "work", title: "Work lists", order: 4 },
+      { id: "goals", title: "Goals", order: 5 },
+      { id: "capacity", title: "Capacity", order: 6 },
+    ],
+    commands: [
+      { id: "gc", title: "Evict expired capture rows", hint: "amem gc", action: "gc" },
+      { id: "capacity-apply", title: "Apply the capture capacity proposal", hint: "amem capacity apply", action: "capacity_apply" },
+    ],
+    capabilities: { actions: ACTIONS, confirm: true, multiProject: true, inbox: true, search: true },
+  },
+  async open(ctx: { home: string; log(line: string): void }): Promise<Provider> {
+    const base = memoryHome({ ...process.env, AGENTHUB_HOME: ctx.home });
+    // The machine policy of this home. The console runs in no repository, so a repository's `.amem/config` narrowing does not apply here.
+    const policy = () => configuredPolicy(base);
+    const policyVersion = () => JSON.stringify(configuredPolicyOptions(base));
+    const hasCandidates = () => existsSync(join(base, "candidates.db"));
+    const withCandidates = <T>(project: string | undefined, run: (store: CandidateStore) => T): T => {
+      const aliases = project ? aliasedKeys(base, project) : [];
+      const store = new CandidateStore({ memoryDir: base, ...(project && aliases.length ? { reconcile: { canonical: project, aliases } } : {}) });
+      try { return run(store); } finally { store.close(); }
+    };
+
+    /** Projects with notes in an unsplit (shared-v1 or generation) home: that store is one file set for every project, with no shard per project. */
+    function sharedStoreProjects(): string[] {
+      if (existsSync(join(base, "shards.json")) || !["log", "local", "generations"].some(dir => existsSync(join(base, dir)))) return [];
+      const store = new MemoryStore({ memoryDir: base, deferPromotions: true });
+      // ponytail: reads every live note on each snapshot; keep a per-index-revision cache if a large shared home makes polls slow.
+      try { return [...new Set(store.list({ limit: Number.MAX_SAFE_INTEGER }).map(view => view.project))]; } finally { store.close(); }
+    }
+    // ponytail: the catalog scan walks every shard on each snapshot; cache it by shard mtimes if polls get slow on a large home.
+    function projects(): string[] {
+      if (!existsSync(base)) return [];
+      const keys = new Set<string>(), waiting = new Set<string>();
+      try { for (const p of readCatalogFresh(base)) keys.add(p.key); } catch (e) { ctx.log(`amem: project catalog unavailable: ${errorText(e)}`); }
+      try { for (const key of sharedStoreProjects()) keys.add(resolveAlias(base, key)); } catch (e) { ctx.log(`amem: shared store projects unavailable: ${errorText(e)}`); }
+      if (hasCandidates()) for (const key of withCandidates(undefined, store => store.projects())) { const canonical = resolveAlias(base, key); keys.add(canonical); waiting.add(canonical); }
+      return [...keys].filter(key => projectState(base, key) === "active").sort((a, b) => Number(waiting.has(b)) - Number(waiting.has(a)) || a.localeCompare(b));
+    }
+    // The shell's tabs navigate without params, so the project chosen on one panel is kept for the others and the palette.
+    // ponytail: one choice per provider; fine for H0's single person, per session once a console serves several.
+    let chosen: string | undefined;
+    /** An active project whose curated store holds a note of its own, also when no listing source named it. */
+    const exists = (key: string) => {
+      if (projectState(base, key) !== "active") return false;
+      const store = openCuratedForRead(base, key);
+      try { return !!store?.list({ project: key, limit: 1 }).some(view => view.project === key); } finally { store?.close(); }
+    };
+    const pick = (args: Args, list: string[]) => {
+      const asked = str(args.project), key = asked ? resolveAlias(base, asked) : undefined;
+      if (key && !list.includes(key) && existsSync(base) && exists(key)) list.push(key);
+      if (key && list.includes(key)) chosen = key;
+      return chosen && list.includes(chosen) ? chosen : list[0];
+    };
+
+    /** Every option the MCP tool declares is forwarded; nothing is hand-picked. The handler validates and refuses as it does for MCP. */
+    const forward = (tool: "amem_search" | "amem_timeline" | "amem_work_state_read", args: Args): Args => {
+      const schema = MCP_TOOLS.find(t => t.name === tool)!.inputSchema as { properties: Record<string, { type?: string }> };
+      const out: Args = {};
+      for (const [key, spec] of Object.entries(schema.properties)) {
+        let value = args[key];
+        if (value === undefined || value === "") continue;
+        if (spec.type === "integer" && typeof value === "string" && /^[0-9]+$/.test(value)) value = Number(value);
+        if (spec.type === "boolean" && (value === "true" || value === "false")) value = value === "true";
+        out[key] = value;
+      }
+      return out;
+    };
+    async function read(project: string, tool: "amem_search" | "amem_timeline" | "amem_work_state_read", args: Args): Promise<unknown> {
+      const mcp = createMemoryMcp({ cwd: base, base, project });
+      try { return await mcp.tools[tool](forward(tool, args)); } finally { mcp.close(); }
+    }
+
+    /** The CLI's rule for agent-marked review, applied to the person here: the console shows only what passes the screen, targets included. */
+    const visible = (candidate: Candidate, project: string, store: MemoryStore | undefined, p: StandalonePolicy): boolean => {
+      if (!p.screenStandalone(candidate)) return false;
+      const input = candidate.input, targets = targetsOf(input);
+      if (!targets.length && input.kind !== "promotion") return true;
+      if (!store) return false;
+      if (targets.some(t => { const view = store.get(t.id, project); return !view || view.project !== project || !p.screenStandalone(view); })) return false;
+      if (input.kind === "promotion") { const goal = store.goalOf(input.goalId, project); if (!goal || !p.screenStandalone(goal)) return false; }
+      return true;
+    };
+    const projectOf = new Map<string, string>();
+    async function pending(project: string, detail: boolean) {
+      if (!hasCandidates()) return { rows: [], hidden: 0 };
+      const p = policy(), store = openCuratedForRead(base, project);
+      try {
+        const all = withCandidates(project, c => c.list({ project, status: "pending" }));
+        const shown = all.filter(c => visible(c, project, store, p));
+        for (const c of shown) projectOf.set(c.id, project);
+        const overlaps = detail && store ? await candidateOverlapsBatch(shown, store, { project, policy, policyVersion }) : [];
+        const rows = shown.map((c, index) => {
+          const input = c.input;
+          const targets = targetsOf(input).map(t => { const v = store?.get(t.id, project); return v ? { id: v.id, at: v.at, kind: v.kind, title: v.title, text: v.text } : { id: t.id }; });
+          return {
+            id: c.id, kind: input.kind, createdAt: c.createdAt, text: candidateText(input),
+            noteKind: "noteKind" in input ? input.noteKind ?? null : null,
+            diff: input.kind === "correction" ? { now: (targets[0] as { text?: string } | undefined)?.text ?? null, proposed: input.proposedText, reason: input.reason } : null,
+            evidence: input.kind === "fail" ? input.evidenceRefs : [],
+            targets, overlaps: overlaps[index] ?? [],
+            acceptable: input.kind !== "decay" && input.kind !== "model-answer",
+            edit: editText(input),
+          };
+        });
+        return { rows, hidden: all.length - shown.length };
+      } finally { store?.close(); }
+    }
+
+    async function capacity() {
+      if (!existsSync(base)) return undefined;
+      const report = capacityReport({ memoryDir: base });
+      if (!await policy().screen(report)) return { withheld: true as const };
+      return { report, applyNeeded: report.current.capMb !== report.proposal.capMb || report.current.retentionDays !== report.proposal.retentionDays };
+    }
+    // The shell keys snooze and oldest-first order on `at`: an alert keeps the time it was first seen.
+    const firstSeen = new Map<string, string>();
+    const since = (id: string) => { const at = firstSeen.get(id) ?? new Date().toISOString(); firstSeen.set(id, at); return at; };
+    async function inbox(): Promise<InboxItem[]> {
+      const items: InboxItem[] = [];
+      for (const project of projects()) {
+        for (const row of (await pending(project, false)).rows) items.push({
+          id: row.id, group: "candidate", kind: row.kind, title: oneLine(row.text, 120), detail: `${row.kind} candidate in ${project}`, project, at: row.createdAt,
+          verbs: [...row.acceptable ? [{ id: "accept", label: "Accept", primary: true }] : [], { id: "reject", label: "Reject", reason: "optional" as const }],
+          link: { panel: "review", params: { project, id: row.id } },
+        });
+      }
+      const cap = await capacity();
+      if (cap && "report" in cap && cap.applyNeeded) {
+        const { current, proposal } = cap.report;
+        items.push({ id: "capacity:proposal", group: "alert", kind: "capacity", title: `Capture capacity: ${current.capMb} MB / ${current.retentionDays} d, proposed ${proposal.capMb} MB / ${proposal.retentionDays} d`,
+          detail: proposal.reason, at: since("capacity:proposal"), chip: { text: "proposal", tone: "warn" }, verbs: [{ id: "capacity_apply", label: "Apply..." }], link: { panel: "capacity" } });
+      } else firstSeen.delete("capacity:proposal");
+      return items;
+    }
+
+    function searchHit(hit: Args, project: string, q: string) {
+      const view = hit.view as View | undefined;
+      const capture = hit.capture as { id: number; at: string; event: string; excerpt: string } | undefined;
+      const id = view ? (hit.source === "repo" ? `repo:${view.id}` : view.id) : `capture:${capture?.id}`;
+      return { id, kind: view ? `${String(hit.source)} ${view.kind}` : `capture ${capture?.event ?? ""}`, title: oneLine(view ? view.title ?? view.text : capture?.excerpt ?? "", 100),
+        ...(view?.title ? { detail: oneLine(view.text, 120) } : {}), ...(view?.at ?? capture?.at ? { at: view?.at ?? capture?.at } : {}), link: { panel: "find", params: { project, q } } };
+    }
+
+    async function panel(name: string, args: Args, project: string): Promise<Args> {
+      switch (name) {
+        case "review": return { ...(await pending(project, true)), selected: str(args.id) ?? null };
+        case "find": {
+          const q = str(args.q);
+          if (!q) return { q: "", hits: [] };
+          return { q, ...(await read(project, "amem_search", { ...args, query: q }) as Args) };
+        }
+        case "timeline": return { entries: await read(project, "amem_timeline", args) };
+        case "work": return { lists: await read(project, "amem_work_state_read", args) };
+        case "goals": {
+          const store = openCuratedForRead(base, project), p = policy();
+          try {
+            return { goals: (store?.goals(project) ?? []).filter(goal => p.screenStandalone(goal))
+              .map(g => ({ id: g.id, at: g.at, title: g.title, state: g.state, milestones: g.milestones, dependsOn: g.dependsOn, links: g.links.map(l => l.task) })) };
+          } finally { store?.close(); }
+        }
+        default: return {};
+      }
+    }
+
+    // Undo stays bound to what this console just did: an accepted or edited note to forget, a rejection to withdraw.
+    // A rejected candidate is held here too: retention may delete it before the undo arrives, and reopen() writes it back from this copy.
+    const undo = new Map<string, { kind: "accept" | "reject"; project: string; noteId?: string; reopen?: boolean; candidate?: Candidate; until: number }>();
+    // Previewed prune plans by seal, for the console's confirm window (60 s) plus slack; bounded by the console's own confirm limit.
+    const prunePlans = new Map<string, { plan: ReturnType<typeof planPrune>; project: string; cutoff: string; until: number }>();
+    function candidateFor(args: Args): Found | string {
+      const id = str(args.id);
+      if (!id || !/^[a-f0-9]{64}$/.test(id)) return "a full 64-character candidate id is required";
+      if (!hasCandidates()) return "candidate unavailable";
+      const asked = str(args.project);
+      const project = asked ? resolveAlias(base, asked) : projectOf.get(id) ?? projects().find(p => withCandidates(p, c => c.get(id, p)));
+      const candidate = project ? withCandidates(project, c => c.get(id, project)) : undefined;
+      return project && candidate ? { id, project, candidate } : "candidate unavailable";
+    }
+    /** The console never acts on a candidate it would not show. */
+    function hiddenReason(found: Found): string | undefined {
+      if (found.candidate.status !== "pending") return `candidate is ${found.candidate.status}, not pending`;
+      const store = openCuratedForRead(base, found.project);
+      try { return visible(found.candidate, found.project, store, policy()) ? undefined : "this candidate is withheld by the privacy screen; review it with amem review walk"; }
+      finally { store?.close(); }
+    }
+
+    async function accept({ id, project, candidate }: Found): Promise<ActionResult> {
+      const p = policy();
+      if (candidate.input.kind === "decay") return { ok: false, error: "decay candidates are listing-only; use amem demote or amem forget after review" };
+      // `amem review accept`: the current policy screens the proposal, then acceptance screens the note it writes with its target and goal.
+      if (!await p.screen(candidate.input)) return refusal(candidate.input, p);
+      let declined: unknown;
+      const store = openCurated(base, project, { deferPromotions: true, screen: note => policy().screenStandalone(note) ? "promote" : "keep" });
+      try {
+        const result = withCandidates(project, c => c.accept(id, { project, actor: ACTOR, verdict: "public", store, policyVersion,
+          policy: (proposal, target, note, goal) => {
+            const value = { ...proposal.input, ...(target ? { targetView: target } : {}), note, ...(goal ? { goalView: goal } : {}) };
+            if (policy().screenStandalone(value)) return true;
+            declined = value; return false;
+          } }));
+        // A promotion hides its short-term source; forgetting the copy would not bring that back, so it gets no undo.
+        const reversible = candidate.input.kind !== "promotion" && !result.alreadyAccepted;
+        if (reversible) undo.set(id, { kind: "accept", project, noteId: result.noteId, until: Date.now() + UNDO_MS });
+        return { ok: true, message: `Accepted as note ${result.noteId.slice(0, 8)}`, noteId: result.noteId, ...(reversible ? { undo: { action: "accept_undo", id, project } } : {}) };
+      } catch (e) {
+        if (declined !== undefined) return refusal(declined, p);
+        return { ok: false, error: errorText(e) };
+      } finally { store.close(); }
+    }
+    function editAccept({ id, project, candidate }: Found, text: string | undefined): ActionResult {
+      const input = candidate.input;
+      if (input.kind !== "memory" && input.kind !== "fail") return { ok: false, error: "edit is for memory and fail candidates; accept or reject this one" };
+      if (!text) return { ok: false, error: "the edited text is required" };
+      const p = policy(), asFail = input.kind === "fail" || input.noteKind === "fail";
+      const title = input.kind === "memory" && input.title ? { title: input.title } : {};
+      const store = openCurated(base, project, { deferPromotions: true, screen: note => p.screenStandalone(note) ? "promote" : "keep" });
+      let noteId: string;
+      try {
+        // `review walk`'s edit: the person's own long-term note, then the candidate is closed.
+        noteId = noteAdd(store, project, asFail ? { kind: "fail", tier: "long", scope: "project", fail: parseFailTemplate(text), ...title }
+          : { kind: input.kind === "memory" ? input.noteKind ?? "finding" : "finding", tier: "long", scope: "project", text, ...title }, p).id;
+      } catch (e) {
+        return /privacy policy/.test(errorText(e)) ? refusal({ text, ...title }, p) : { ok: false, error: errorText(e) };
+      } finally { store.close(); }
+      withCandidates(project, c => c.reject(id, { project, actor: ACTOR, verdict: "public" }));
+      undo.set(id, { kind: "accept", project, noteId, reopen: true, candidate, until: Date.now() + UNDO_MS });
+      return { ok: true, message: `Saved your edit as note ${noteId.slice(0, 8)}; the candidate is closed`, noteId, undo: { action: "accept_undo", id, project } };
+    }
+    function undoFor(args: Args, kind: "accept" | "reject") {
+      const id = str(args.id) ?? "", entry = undo.get(id);
+      if (!entry || entry.kind !== kind) return undefined;
+      undo.delete(id);
+      return entry.until >= Date.now() ? { id, ...entry } : undefined;
+    }
+
+    /** Destructive forms: the first call previews; a write needs the console's confirmation with the same fingerprint, recomputed here. */
+    const gate = (input: Args, fingerprint: string, view: Preview): ActionResult | undefined =>
+      input.confirmed === true && input.fingerprint === fingerprint ? undefined : { ok: false, needsConfirm: true, fingerprint, ...view };
+    function projectArg(args: Args): string {
+      const asked = str(args.project);
+      if (!asked) throw new Error("project is required");
+      const key = resolveAlias(base, asked);
+      assertProjectActive(base, key);
+      return key;
+    }
+    async function destructive(input: Args): Promise<ActionResult> {
+      if (!existsSync(base)) return { ok: false, error: "no memory home yet" };
+      switch (input.action) {
+        case "gc": {
+          // gc both expires rows and trims the oldest unexpired rows of a shard over its cap: the preview names both.
+          const plan = planGc(base), acting = plan.filter(s => s.expiredRows > 0 || s.trimRows > 0);
+          const blocked = gate(input, sha(plan), { verb: "Evict capture rows",
+            preview: acting.length ? acting.map(s => `${s.key}: ${s.expiredRows} expired row(s)${s.trimRows ? `, ${s.trimRows} oldest unexpired row(s) over the ${s.capMb} MB cap` : ""}`) : ["nothing to evict"],
+            changes: acting.map(s => ({ op: "delete", target: `capture rows of ${s.key}`, note: [s.expiredRows ? `${s.expiredRows} expired` : "", s.trimRows ? `${s.trimRows} trimmed to fit ${s.capMb} MB` : ""].filter(Boolean).join(", ") })),
+            ...(acting.some(s => s.trimRows) ? { warnings: ["Trimming removes unexpired capture rows, oldest first, in whole batches of 256; one run may stop before the shard fits."] } : {}) });
+          return blocked ?? { ok: true, message: gcText(runGc(base)).split("\n").slice(0, 3).join("; ") };
+        }
+        case "capacity_apply": {
+          const report = capacityReport({ memoryDir: base });
+          if (!await policy().screen(report)) return refusal(report, policy());
+          const file = join(base, "capture-config.json"), current = readCaptureConfigFile(file);
+          const target = { capMb: report.proposal.capMb, retentionDays: report.proposal.retentionDays };
+          // `amem capacity apply`: the CLI's preview file is replaced by the console's confirm token, bound to the same values.
+          const blocked = gate(input, sha({ file, current, target }), { verb: "Apply capacity", changes: [{ op: existsSync(file) ? "modify" : "create", target: file }],
+            preview: [`cap_mb: ${current.capMb ?? "default"} -> ${target.capMb}`, `retention_days: ${current.retentionDays ?? "default"} -> ${target.retentionDays}`, `reason: ${report.proposal.reason}`] });
+          if (blocked) return blocked;
+          const written = writeCaptureConfigFile(file, target);
+          return { ok: true, message: `Capture capacity set to ${written.capMb} MB, ${written.retentionDays} days` };
+        }
+        case "project_forget": {
+          const key = requireShard(base, projectArg(input)), state = projectState(base, key), shard = readCatalogFresh(base).find(p => p.key === key);
+          const blocked = gate(input, sha({ key, state }), { verb: "Forget project", changes: [{ op: "log", target: "lifecycle.jsonl", note: `forget ${key}` }],
+            preview: [`forget ${key} (now ${state}; capture ${shard?.captureRows ?? 0} rows)`, "Forget is an append-only record that takes the project out of recall and every listing for good. Nothing is erased."],
+            warnings: ["This cannot be undone."] });
+          if (blocked) return blocked;
+          appendLifecycle(base, { op: "forget", key, actor: ACTOR, machine: machineId(base).id });
+          return { ok: true, message: `Forgot ${key}` };
+        }
+        case "decay_apply": {
+          const project = projectArg(input), forget = input.forget === true || input.forget === "true";
+          const days = input.days === undefined ? DECAY_DEFAULT_DAYS : Number(input.days);
+          if (!Number.isSafeInteger(days) || days < 1) return { ok: false, error: "days must be a positive whole number" };
+          const aliases = aliasedKeys(base, project);
+          const store = openCurated(base, project, { deferPromotions: true, screen: note => policy().screenStandalone(note) ? "promote" : "keep" });
+          try {
+            const current = { days, aliases, counters: () => readDecayCounters(base, [project, ...aliases]), screen: (view: View) => policy().screenStandalone(view) };
+            const plan = decayPreview(store, project, current), action = forget ? "forget" : "demote";
+            const blocked = gate(input, sha({ project, action, days, targets: plan.entries.map(e => e.target) }), {
+              verb: forget ? "Forget old notes" : "Demote old notes",
+              preview: [`${action}: ${plan.entries.length} notes older than ${days} days in ${project}${plan.truncated ? " (truncated)" : ""}; citation history unknown`,
+                ...plan.entries.map(e => `mem:${e.target.id}  ${e.view.at.slice(0, 10)}  ${e.view.kind}: ${oneLine(e.view.title ?? e.view.text, 80)}`)],
+              changes: plan.entries.map(e => ({ op: forget ? "delete" : "modify", target: `mem:${e.target.id}`, note: forget ? "forget" : `short-term, expires ${plan.demoteExpiresAt}` })),
+              ...(plan.withheld ? { warnings: [`${plan.withheld} notes withheld by the privacy screen are left alone`] } : {}) });
+            if (blocked) return blocked;
+            if (!plan.entries.length) return { ok: true, message: "No eligible notes" };
+            if (forget) assertExactDecayForget(store, plan.entries.map(e => e.target.id), project);
+            const result = applyDecay(store, plan, { ...current, actor: ACTOR, confirmed: true, forget });
+            return { ok: true, message: `${result.action}: ${result.ids.length} notes` };
+          } finally { store.close(); }
+        }
+        case "prune": {
+          const project = projectArg(input), cutoff = str(input.cutoff);
+          if (!cutoff) return { ok: false, error: "cutoff is required (UTC time)" };
+          const store = openCurated(base, project, { deferPromotions: true }, false);
+          try {
+            const auth = { project, actor: ACTOR, authorize: () => true }, port = store.prunePort();
+            // A plan carries its authoring time inside the seal, so a new plan never matches the previewed one. The confirmed call applies
+            // the very plan the person saw; applyPrune rechecks it against the current home and refuses a stale one.
+            const kept = typeof input.fingerprint === "string" ? prunePlans.get(input.fingerprint) : undefined;
+            for (const [seal, entry] of prunePlans) if (entry.until < Date.now()) prunePlans.delete(seal);
+            if (input.confirmed === true && kept && kept.until >= Date.now() && kept.project === project && kept.cutoff === cutoff) {
+              prunePlans.delete(kept.plan.seal);
+              return { ok: true, message: `Pruned: ${applyPrune(port, JSON.stringify(kept.plan), auth).completed.length} rows` };
+            }
+            const plan = planPrune(port, { cutoff }, auth);
+            if (prunePlans.size >= PLAN_MAX) prunePlans.delete(prunePlans.keys().next().value!);
+            prunePlans.set(plan.seal, { plan, project, cutoff, until: Date.now() + PLAN_MS });
+            return { ok: false, needsConfirm: true, fingerprint: plan.seal, verb: "Prune expired notes", preview: pruneText(plan).split("\n"),
+              changes: plan.rows.map(r => ({ op: "log", target: `${r.placement} prune row`, note: `${r.payload.targets.length} targets` })) };
+          } finally { store.close(); }
+        }
+      }
+      return { ok: false, error: `unknown action ${String(input.action)}` };
+    }
+
+    return {
+      assets: { js: asset("./panel.js"), css: asset("./panel.css") },
+      async snapshot(input) {
+        const args = input as Args;
+        if (input.panel === "inbox") return { items: await inbox() };
+        const list = projects(), project = pick(args, list);
+        if (input.panel === "search") {
+          const q = str(args.q);
+          if (!q || !project) return { hits: [], total: 0 };
+          const limit = Math.min(10, Math.max(1, Number(args.limit) || 10));
+          const result = await read(project, "amem_search", { query: q, limit }) as { hits: Args[] };
+          const hits = result.hits.map(hit => searchHit(hit, project, q));
+          return { hits, total: hits.length };
+        }
+        if (input.panel === "capacity") return { projects: list, project: project ?? null, ...(await capacity() ?? { report: null }) };
+        if (!project) return { projects: list, project: null };
+        try { return { projects: list, project, ...(await panel(input.panel, args, project)) }; }
+        catch (e) {
+          ctx.log(`amem: ${input.panel} for ${project} failed: ${errorText(e)}`);
+          return { projects: list, project, error: "Memory is unavailable for this project right now; details are in the terminal." };
+        }
+      },
+      async action(input) {
+        const args = input as Args;
+        try {
+          switch (input.action) {
+            case "accept": case "reject": case "edit_accept": {
+              const found = candidateFor(args);
+              if (typeof found === "string") return { ok: false, error: found };
+              const hidden = hiddenReason(found);
+              if (hidden) return { ok: false, error: hidden };
+              if (input.action === "accept") return await accept(found);
+              if (input.action === "edit_accept") return editAccept(found, str(args.text));
+              withCandidates(found.project, c => c.reject(found.id, { project: found.project, actor: ACTOR, verdict: "public" }));
+              undo.set(found.id, { kind: "reject", project: found.project, candidate: found.candidate, until: Date.now() + UNDO_MS });
+              // agent-mem stores no reject reason (no new storage, #158 non-goals); the reply says so instead of dropping it silently.
+              return { ok: true, message: str(args.reason) ? "Rejected; agent-mem keeps no reject reason, so it was not recorded" : "Rejected", undo: { action: "reject_undo", id: found.id, project: found.project } };
+            }
+            case "reject_undo": {
+              const entry = undoFor(args, "reject");
+              if (!entry) return { ok: false, error: "nothing to undo for this candidate" };
+              withCandidates(entry.project, c => c.reopen(entry.id, { project: entry.project, actor: ACTOR, ...(entry.candidate ? { restore: entry.candidate } : {}) }));
+              return { ok: true, message: "Reject undone; the candidate is pending again" };
+            }
+            case "accept_undo": {
+              const entry = undoFor(args, "accept");
+              if (!entry?.noteId) return { ok: false, error: "nothing to undo for this candidate" };
+              // Append-only: a forget op hides the note, and a note it replaced shows again. Nothing is deleted.
+              const store = openCurated(base, entry.project, { deferPromotions: true });
+              try { if (!store.forget(entry.noteId, ACTOR, entry.project, true)) return { ok: false, error: "the accepted note is no longer available" }; }
+              finally { store.close(); }
+              if (entry.reopen) withCandidates(entry.project, c => c.reopen(entry.id, { project: entry.project, actor: ACTOR, ...(entry.candidate ? { restore: entry.candidate } : {}) }));
+              return { ok: true, message: entry.reopen ? "Undone; the note is forgotten and the candidate is pending again" : "Undone; the accepted note is forgotten" };
+            }
+            case "gc": case "capacity_apply": case "project_forget": case "decay_apply": case "prune": return await destructive(args);
+            default: return { ok: false, error: `unknown action ${input.action}` };
+          }
+        } catch (e) {
+          ctx.log(`amem: ${input.action} failed: ${errorText(e)}`);
+          return { ok: false, error: errorText(e) };
+        }
+      },
+    };
+  },
+};
+
+export default plugin;