@staix/vault-mem 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.2.4] - 2026-11-01
+
+- Report names (`graph-report-YYMMDD.md`, `lint-report-YYMMDD.md`), graph trend rows, L11 staleness, `promoted_at` (agent-mem and org promotion) and the skill-candidate report date now use the local calendar date, the same clock as the log lines, instead of UTC. A run early in the morning in a timezone ahead of UTC is no longer dated the previous day. `options.today` and `now` overrides still apply. Skill mining's `unique_days` keeps the UTC day of each record's `...Z` timestamp, as Python's `.date()` does.
+- Console plugin for `acon` (agent-console api 1), exported as `@staix/vault-mem/ui-plugin`: Overview, Search, Note, Promote, Lint and Log panels, inbox items for promotion candidates and lint alerts, palette search, and two-step `delete`, `move`, `promote` and `promote-from-amem` behind the console's confirm dialog.
+- `vmem setup` writes, reports and undoes the console plugin manifest `$AGENTHUB_HOME/console/plugins/vmem.json`.
+
 ## [0.2.3] - 2026-10-31
 
 - Graph communities use a deterministic, dependency-free Leiden (modularity, resolution 1.0) instead of label propagation, which collapsed most of a real vault into one community. Every community is connected, ids are numbered by size then smallest member, and `vault-graph.json` and the report Overview record the partitioner, resolution and modularity. The vault graph, the workspace graph and skill mining share it.

package/README.md

@@ -2,7 +2,7 @@
 
 An Obsidian-compatible knowledge vault tool for agents and people. Requires Bun >=1.4.2. The full check (`bun run check`) needs Bun, git and tar; it includes a package dry-run and clean installed CLI/MCP smoke. Node/npm are used by the separate release workflow, not required for the ordinary Bun gate. CI runs on Ubuntu and macOS for pull requests and for pushes to `main`.
 
-Implemented: configuration, vault registration, lossless frontmatter parsing/emission, wiki-link resolution and derived SQLite FTS5 indexing with bounded read commands. Validated note writes, the append-only log, the `vmem mcp` stdio server, reversible `vmem setup` host registration and promotion from agent-mem (`promote-from-amem`) are also implemented below. Lint/graph analysis, promotion to org vaults (`vmem promote`) and explicit `vmem sync` are implemented below. The `acon` console remains planned under issues [#1](https://github.com/STAIxBWLB/vault-mem/issues/1) and [#2](https://github.com/STAIxBWLB/vault-mem/issues/2). Do not use this increment to replace an existing vault writer.
+Implemented: configuration, vault registration, lossless frontmatter parsing/emission, wiki-link resolution and derived SQLite FTS5 indexing with bounded read commands. Validated note writes, the append-only log, the `vmem mcp` stdio server, reversible `vmem setup` host registration and promotion from agent-mem (`promote-from-amem`) are also implemented below. Lint/graph analysis, promotion to org vaults (`vmem promote`) and explicit `vmem sync` are implemented below. The vmem plugin for the `acon` console ([agent-console](https://github.com/STAIxBWLB/agent-console)) is described under "Console plugin"; vault-mem ships no console bin. Do not use this increment to replace an existing vault writer.
 
 ```sh
 bun install
@@ -187,7 +187,7 @@ vmem setup all --undo
 
 Setup registers one server entry named `vmem` (`<bun> --smol <package>/bin/vmem.js mcp`) by editing the host's own MCP configuration: `~/.claude.json` (`mcpServers`; `$CLAUDE_CONFIG_DIR/.claude.json` when set), `$CODEX_HOME/config.toml` (`[mcp_servers.vmem]`), `$KIMI_CODE_HOME/mcp.json`, `$PI_CODING_AGENT_DIR/mcp.json`, `$QWEN_HOME/settings.json` (all `mcpServers`), `$JCODE_HOME/mcp.json` (`servers`) and the workspace's `.agents/mcp_config.json` for Antigravity. Defaults are `~/.codex`, `~/.kimi-code`, `~/.pi/agent`, `~/.qwen` and `~/.jcode`; overrides must be absolute. It does not call host CLIs and does not need a TTY. Run it while the host is closed: Claude Code in particular rewrites `.claude.json` while it runs and can overwrite a concurrent change.
 
-Apply is idempotent and touches only the `vmem` entry: other servers and settings are preserved (TOML is edited textually, so comments and other tables stay byte-identical; JSON is re-serialized with its indentation). Configuration files must be plain strict JSON or TOML; links, JSONC and unparsable files are refused per host without writing, and the command exits 1. Apply records the prior `vmem` value in a receipt, `$VMEM_HOME/setup/<host>-<hash of the config path>.json`, so separate host profiles (for example two `CODEX_HOME`s) sharing one `VMEM_HOME` keep separate receipts. The receipt is written before the host file; if the host write fails, the receipt is rolled back. In TOML, every `[mcp_servers.vmem]` and `[mcp_servers.vmem.*]` table belongs to the entry, even when other tables sit between them. Undo restores that prior value (or removes the entry, and the file if setup created it and nothing else was added) only while the entry is still the one setup installed; an entry edited later is left alone and reported as `refused`. No console plugin manifest is written because vmem ships no console plugin yet.
+Apply is idempotent and touches only the `vmem` entry: other servers and settings are preserved (TOML is edited textually, so comments and other tables stay byte-identical; JSON is re-serialized with its indentation). Configuration files must be plain strict JSON or TOML; links, JSONC and unparsable files are refused per host without writing, and the command exits 1. Apply records the prior `vmem` value in a receipt, `$VMEM_HOME/setup/<host>-<hash of the config path>.json`, so separate host profiles (for example two `CODEX_HOME`s) sharing one `VMEM_HOME` keep separate receipts. The receipt is written before the host file; if the host write fails, the receipt is rolled back. In TOML, every `[mcp_servers.vmem]` and `[mcp_servers.vmem.*]` table belongs to the entry, even when other tables sit between them. Undo restores that prior value (or removes the entry, and the file if setup created it and nothing else was added) only while the entry is still the one setup installed; an entry edited later is left alone and reported as `refused`. Every mode also handles the console plugin manifest (see "Console plugin"): apply writes it, undo removes it while it still points at this install.
 
 `vmem completion bash|zsh|fish` prints a completion script generated from the same command table as `--help`.
 
@@ -209,6 +209,16 @@ vmem promote-from-amem personal mem:<id> --link-to existing-note  # link an exis
 - If the final link fails, the note stays, the result reports `LINK` and `link-only notes/<stem>.md`, and the entry stays a candidate. A rerun finds the note through `promoted_from` and offers link-only, never a second note or a second LEARN event.
 - `vmem_promote_from_amem` is the same two steps over MCP and needs a vault with `write: mcp`.
 
+## Console plugin
+
+`vmem setup <target> --apply` also writes `$AGENTHUB_HOME/console/plugins/vmem.json` (default `~/.agenthub`; directory 0700, file 0600) with the absolute path and sha256 of `src/ui/plugin.ts`. `acon ui` then shows a Vault area. Re-run setup after upgrading vmem: acon refuses a module whose hash changed.
+
+- Panels: Overview (vaults, maps, recent log), Search, Note (body, links, actions), Promote (agent-mem candidates), Lint (typed findings linked to notes) and Log (parsed rows).
+- Inbox: promotion candidates (group `candidate`), lint errors and a stale graph report (group `alert`). The palette searches notes.
+- Actions: `delete`, `move`, `promote` (to an org vault) and `promote-from-amem` reuse the two-step MCP tools. Each first answers a preview with the planned changes; the write happens only after the console's confirm dialog, and only while the fingerprint still matches.
+- The provider calls the `vmem mcp` handlers in process, so the console has exactly the MCP rights: writes need a vault with `write: mcp`, and log lines carry the agent attribution.
+- The module is exported as `@staix/vault-mem/ui-plugin`. Lint results are cached for 60 seconds per vault.
+
 ## Lint and graph analysis
 
 `vmem lint <vault>` checks L01/L02/L03/L09/L10/L11/L12 and L13 (lowercase ASCII kebab-case filenames). `--note notes/example.md` limits note findings. Section names and `SUMMARY errors=N warnings=N` follow the Python reference. `--write` writes a screened lint report and LINT event; `--dry-run` previews without persistence. Findings may identify paths, link targets and malformed log prefixes. Note bodies are never included in analysis results.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/vault-mem",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Validated Obsidian-compatible knowledge vaults for agents and people",
   "license": "MIT",
   "type": "module",
@@ -15,11 +15,13 @@
     "@staix/agent-mem": "0.11.0"
   },
   "devDependencies": {
+    "@staix/agent-console": "github:STAIxBWLB/agent-console#bd7234f",
     "@types/bun": "^1.3.0",
     "typescript": "^5.8.0"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./ui-plugin": "./src/ui/plugin.ts"
   },
   "bin": {
     "vmem": "bin/vmem.js"

package/src/analysis-input.ts

@@ -1,3 +1,4 @@
+import { localDate } from "./local-date.ts";
 import { MAX_REPORT_BYTES } from "./write-validation.ts";
 import { parseFrontmatter } from "./frontmatter.ts";
 import { sourceWorkspaceRoot, missingSourceWarnings, sourceReferences } from "./source.ts";
@@ -35,7 +36,7 @@ export function analysisInput(home: string, id: string, options: { today?: strin
   if (!vault) throw new Error("analysis: unknown vault id");
   if (options.expectedVault && JSON.stringify(options.expectedVault) !== JSON.stringify(vault)) throw new Error("analysis: startup vault binding changed; restart MCP");
   const identity = lstatSync(vault.path);
-  const today = options.today ?? new Date().toISOString().slice(0,10);
+  const today = options.today ?? localDate();
   if (!/^\d{4}-\d{2}-\d{2}$/.test(today) || !Number.isFinite(Date.parse(today)) || new Date(today).toISOString().slice(0,10) !== today) throw new Error("analysis: invalid date");
   permitted(vault.path, config);
   // Check denied paths before opening the index or reading note sources.

package/src/cli.ts

@@ -33,7 +33,7 @@ export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { tex
     if (positional.length !== 1 || flags.some(f => !["--apply", "--undo", "--json"].includes(f)) || new Set(flags).size !== flags.length || (flags.includes("--apply") && flags.includes("--undo"))) throw new Error("setup: requires one target and at most one of --apply/--undo");
     const mode: SetupMode = flags.includes("--apply") ? "apply" : flags.includes("--undo") ? "undo" : "dry-run";
     const report = runSetup(positional[0]!, mode, { home: resolveHome(env).home, env });
-    return { text: JSON.stringify(report, null, flags.includes("--json") ? undefined : 2), code: report.actions.some(a => a.change === "refused") ? 1 : 0 };
+    return { text: JSON.stringify(report, null, flags.includes("--json") ? undefined : 2), code: [...report.actions, report.console].some(a => a?.change === "refused") ? 1 : 0 };
   }
   if (args[0] === "completion") {
     if (args.length !== 2) throw new Error("completion: requires bash, zsh or fish");

package/src/local-date.ts

@@ -0,0 +1,9 @@
+/**
+ * The local calendar date as YYYY-MM-DD, from the same local clock the vault log lines use (`log-format.ts`).
+ * Every user-facing calendar date (report names, trend rows, L11 staleness, `promoted_at`, skill reports) comes from here,
+ * so an early-morning run in a timezone ahead of UTC is not dated the previous day.
+ */
+export function localDate(now: Date = new Date()): string {
+  const pad = (value: number, size = 2) => String(value).padStart(size, "0");
+  return `${pad(now.getFullYear(), 4)}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}

package/src/log-format.ts

@@ -1,3 +1,4 @@
+import { localDate } from "./local-date.ts";
 import { screenContent } from "./write-validation.ts";
 import { parsePii } from "./config.ts";
 function validPii(value: unknown): boolean { try { parsePii(value); return true; } catch { return false; } }
@@ -49,7 +50,7 @@ export function formatLogEvent(event: LogEvent, context: LogContext): { line?: s
     return { issues: [error("L09", "invalid log timestamp")] };
   }
   const pad = (value: number, size = 2) => String(value).padStart(size, "0");
-  const timestamp = `${pad(now.getFullYear(), 4)}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+  const timestamp = `${localDate(now)} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
   const env = context.env ?? process.env;
   const agent = context.channel === "mcp" || AGENT_MARKERS.some(marker => typeof env[marker] === "string" && env[marker]!.length > 0);
   const line = `${timestamp}  ${event.type}  ${event.project}  ${event.source}${event.dest === undefined ? "" : ` → ${event.dest}`}  — ${event.note}${agent ? " (vmem:agent)" : ""}\n`;

package/src/org-promote.ts

@@ -1,3 +1,4 @@
+import { localDate } from "./local-date.ts";
 import { createHash } from "node:crypto";
 import { closeSync, constants, fstatSync, openSync, readSync, realpathSync } from "node:fs";
 import { join } from "node:path";
@@ -225,7 +226,7 @@ export function promoteToOrg(home: string, request: OrgPromoteRequest, options:
   const transformed = dropUnresolvedLinks(parsed.body, value => targetNotes.resolved.has(linkKey(value)));
   // Body Topics section follows the target topics.
   const body = replaceTopicsSection(transformed.body, topics);
-  const day = (options.now ?? new Date()).toISOString().slice(0, 10);
+  const day = localDate(options.now ?? new Date());
   const frontmatter: Record<string, unknown> = { topics, promoted_from: result.source, promoted_at: day, promoted_to: undefined };
   // Wiki-valued fields that point outside the target vault are dropped as well.
   for (const key of ["project", "superseded_by", "supersedes", "source_ref"]) {

package/src/promote.ts

@@ -1,3 +1,4 @@
+import { localDate } from "./local-date.ts";
 import { createHash } from "node:crypto";
 import type { VaultSpec } from "./config.ts";
 import { emitFrontmatter, parseFrontmatter } from "./frontmatter.ts";
@@ -63,7 +64,7 @@ export function draftNote(entry: AmemCandidate, meta: PromoteMetadata, now = new
   const topics = (meta.topics ?? []).map(value => value.startsWith("[[") ? value : `[[${value}]]`);
   const frontmatter: Record<string, unknown> = {
     title, description: meta.description ?? firstSentence(entry.text), type: meta.type ?? (entry.kind === "decision" ? "decision" : entry.kind === "fail" ? "method" : "insight"),
-    ...(meta.domain ? { domain: meta.domain } : {}), topics, promoted_from: `mem:${entry.id}`, promoted_at: now.toISOString().slice(0, 10),
+    ...(meta.domain ? { domain: meta.domain } : {}), topics, promoted_from: `mem:${entry.id}`, promoted_at: localDate(now),
   };
   const hints = entry.about.length ? `${entry.about.slice(0, 20).map(node => `- ${node.replace(/[\r\n[\]]/g, " ")}`).join("\n")}\n` : "";
   const body = meta.body ?? `# ${title}\n\n${entry.text.trim()}\n\n## Relevant Notes\n\n${hints}\n## Topics\n\n${topics.map(topic => `- ${topic}`).join("\n")}\n`;

package/src/setup.ts

@@ -1,4 +1,4 @@
-import { closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -14,7 +14,8 @@ const MAX_HOST_CONFIG = 4 * 1024 * 1024;
 export interface McpEntry { command: string; args: string[] }
 interface HostFile { target: SetupTarget; file: string; format: "json" | "toml"; key: string }
 export interface SetupAction { target: SetupTarget; file: string; change: "add" | "replace" | "unchanged" | "restore" | "remove" | "refused" | "none"; reason?: string }
-export interface SetupReport { mode: SetupMode; applied: boolean; entry: McpEntry; actions: SetupAction[]; notes: string[] }
+export interface ConsoleAction { file: string; module: string; change: "add" | "replace" | "unchanged" | "remove" | "none" | "refused"; reason?: string }
+export interface SetupReport { mode: SetupMode; applied: boolean; entry: McpEntry; actions: SetupAction[]; console?: ConsoleAction; notes: string[] }
 interface Receipt { version: 1; target: SetupTarget; file: string; existed: boolean; keyExisted?: boolean; prior: unknown; priorToml?: string[]; installed: McpEntry }
 
 function hosts(env: NodeJS.ProcessEnv, cwd: string): Record<SetupTarget, HostFile> {
@@ -170,7 +171,7 @@ export function runSetup(target: string, mode: SetupMode, options: { home: strin
   const targets = target === "all" ? SETUP_TARGETS.filter(t => t !== "agy") : [target as SetupTarget];
   const report: SetupReport = { mode, applied: false, entry, actions: [], notes: [
     "Registers the stdio server `vmem mcp`; restart the host session to load it.",
-    "No console plugin manifest is written: vmem ships no console plugin yet.",
+    "Writes the acon console plugin manifest ($AGENTHUB_HOME/console/plugins/vmem.json); re-run setup after upgrading vmem.",
   ] };
   if (target === "all") report.notes.push("`all` covers user-level hosts; run `vmem setup agy` inside a workspace for Antigravity.");
   for (const name of targets) {
@@ -214,6 +215,47 @@ export function runSetup(target: string, mode: SetupMode, options: { home: strin
       action.change = "refused"; action.reason = error instanceof Error ? error.message : "setup failed";
     }
   }
-  report.applied = mode !== "dry-run" && report.actions.some(a => !["none", "unchanged", "refused"].includes(a.change));
+  report.console = consoleManifest(mode, env);
+  report.applied = mode !== "dry-run" && [...report.actions, report.console].some(a => !["none", "unchanged", "refused"].includes(a.change));
   return report;
 }
+
+/** The acon plugin manifest: `{api, tool, module, sha256}` in the family home, dir 0700 and file 0600 as acon requires. */
+export function consoleManifest(mode: SetupMode, env: NodeJS.ProcessEnv = process.env): ConsoleAction {
+  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, "vmem.json");
+  const module = fileURLToPath(new URL("./ui/plugin.ts", import.meta.url));
+  const action: ConsoleAction = { file, module, change: "none" };
+  try {
+    const next = { api: 1, tool: "vmem", module, sha256: createHash("sha256").update(readFileSync(module)).digest("hex") };
+    // Apply acon's own loader rules (agent-console scanPlugins): the directory and manifest must be real, owned by you
+    // and not writable by others. Kinds and owners are refused here; modes are fixed on apply.
+    for (const [path, kind] of [[dir, "directory"], [file, "file"]] as const) {
+      let info;
+      try { info = lstatSync(path); } catch { continue; }
+      if (kind === "directory" ? !info.isDirectory() : !info.isFile()) throw new Error(`${path}: acon needs a real ${kind}, not a link or other entry`);
+      if (typeof process.getuid === "function" && info.uid !== process.getuid()) throw new Error(`${path}: owned by another user; acon refuses it`);
+    }
+    const text = readText(file);
+    const current = text === null ? undefined : JSON.parse(text) as Record<string, unknown>;
+    if (mode === "undo") {
+      if (!current) { action.reason = "no manifest"; return action; }
+      if (current.module !== module) { action.change = "refused"; action.reason = "manifest points at another vmem install; left as is"; return action; }
+      unlinkSync(file); action.change = "remove"; return action;
+    }
+    const loose = (path: string, want: number) => { try { return (lstatSync(path).mode & 0o777) !== want; } catch { return false; } };
+    const modesOk = !loose(dir, 0o700) && !loose(file, 0o600);
+    if (isDeepStrictEqual(current, next) && modesOk) { action.change = "unchanged"; return action; }
+    action.change = current ? "replace" : "add";
+    if (!modesOk) action.reason = "permissions: plugin directory 0700, manifest 0600";
+    if (mode === "apply") {
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      chmodSync(dir, 0o700);
+      atomicWrite(file, JSON.stringify(next, null, 2) + "\n");
+      chmodSync(file, 0o600);
+    }
+  } catch (error) {
+    action.change = "refused"; action.reason = error instanceof Error ? error.message : "manifest write failed";
+  }
+  return action;
+}

package/src/skills-mine.ts

@@ -1,3 +1,4 @@
+import { localDate } from "./local-date.ts";
 import { createHash } from "node:crypto";
 import { lstatSync, readdirSync } from "node:fs";
 import { join } from "node:path";
@@ -183,6 +184,7 @@ export function communityToCandidate(cid: number, members: readonly string[], gr
   let daySpan = 1, uniqueDays = 1;
   if (times.length >= 2) {
     daySpan = Math.max(1, Math.floor((times.at(-1)! - times[0]!) / DAY));
+    // Python `.date()` on an aware datetime keeps its own offset, so amem/vault `...Z` times count UTC days, as here.
     uniqueDays = new Set(times.map(t => new Date(t).toISOString().slice(0, 10))).size;
   }
   const membership = new Set(members), counts = new Map<string, number>();
@@ -446,7 +448,7 @@ export async function mineSkills(home: string, options: MineOptions): Promise<Mi
   const amem = await readAmemForMining({ env: options.env, since, ...(options.project ? { project: options.project } : {}), piiPatterns: local.config.piiPatterns ?? [] });
   return mineRecords({
     vault: options.vault, days, since, projects: amem.projects, records: [...amem.records, ...local.records], vocab, registry, skills, minSize, minNovelty, piiPatterns: local.config.piiPatterns ?? [],
-    today: now.toISOString().slice(0, 10), dropped: { policy: amem.screened, unreadable: amem.unreadable + local.unreadable, truncatedCapture: amem.truncatedCapture },
+    today: localDate(now), dropped: { policy: amem.screened, unreadable: amem.unreadable + local.unreadable, truncatedCapture: amem.truncatedCapture },
   });
 }
 

package/src/ui/panel.css

@@ -0,0 +1,16 @@
+.vmem { display: flex; flex-direction: column; gap: var(--acon-space-3); word-break: keep-all; }
+.vmem-bar { display: flex; flex-wrap: wrap; align-items: center; gap: var(--acon-space-2); }
+.vmem-inline { display: inline-flex; gap: var(--acon-space-2); }
+.vmem-input { min-height: 32px; min-width: 0; 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; }
+.vmem-bar input[type="search"] { flex: 1; max-width: 480px; }
+.vmem-head { display: flex; flex-wrap: wrap; align-items: center; gap: var(--acon-space-2); }
+.vmem-head h2 { margin: 0; font-size: 17px; }
+.vmem-sub { margin: 0; color: var(--acon-text-2); }
+.vmem-body { margin: var(--acon-space-2) 0 0; padding: var(--acon-space-3); max-height: 60vh; overflow: auto; white-space: pre-wrap; word-break: break-word; background: var(--acon-surface); border: 1px solid var(--acon-line); border-radius: var(--acon-radius-2); font: 13px/1.5 var(--acon-font-mono); }
+.vmem-mono { margin: 0; color: var(--acon-text-2); font: 12px var(--acon-font-mono); word-break: break-all; }
+.vmem details > summary { cursor: pointer; font-weight: 600; padding: var(--acon-space-1) 0; }
+@media (max-width: 600px) { .vmem-inline { width: 100%; } .vmem-inline .vmem-input { flex: 1; } }
+.vmem-form { display: flex; flex-direction: column; gap: var(--acon-space-2); max-width: 560px; }
+.vmem-form h2 { margin: 0; font-size: 15px; }
+.vmem-form .btn { align-self: flex-start; }
+.vmem-check { display: inline-flex; align-items: center; gap: 4px; color: var(--acon-text-2); }

package/src/ui/panel.js

@@ -0,0 +1,137 @@
+// vmem console panels (acon api 1). Runs under the shell's strict CSP: data is rendered as text only.
+const h = (tag, props = {}, ...kids) => {
+  const el = document.createElement(tag);
+  for (const [k, v] of Object.entries(props)) {
+    if (v === undefined || v === null || v === false) continue;
+    if (k === "text") el.textContent = String(v);
+    else if (k.startsWith("on")) el.addEventListener(k.slice(2), v);
+    else el.setAttribute(k, v === true ? "" : String(v));
+  }
+  el.append(...kids.flat().filter((k) => k !== null && k !== undefined && k !== false));
+  return el;
+};
+const empty = (title, hint) => h("div", { class: "empty" }, h("strong", { text: title }), hint ? h("span", { text: hint }) : null);
+const err = (text) => h("p", { class: "notice", role: "alert", text });
+const rows = (items, row) => (items.length ? h("ul", { class: "rows" }, items.map(row)) : null);
+const row = (title, sub, onOpen, ...verbs) => h("li", { class: "row" },
+  h("button", { type: "button", class: "row-main", onclick: onOpen },
+    h("span", { class: "row-text" }, h("span", { class: "row-title", text: title }), sub ? h("span", { class: "row-sub", text: sub }) : null)),
+  verbs.length ? h("span", { class: "row-verbs" }, verbs) : null);
+const btn = (label, onclick, cls = "btn") => h("button", { type: "button", class: cls, onclick, text: label });
+const chip = (text, tone) => h("span", { class: `chip${tone ? ` ${tone}` : ""}`, text });
+
+export default (host) => {
+  const root = h("div", { class: "vmem" });
+  host.mount.append(root);
+  let panel = "overview", params = {};
+  const go = (p, extra = {}) => host.navigate(host.tool, p, { ...(params.vault ? { vault: params.vault } : {}), ...extra });
+  const openNote = (path) => go("note", { path });
+
+  const searchForm = (q) => {
+    const input = h("input", { type: "search", name: "q", value: q ?? "", placeholder: "Search notes", "aria-label": "Search notes", class: "vmem-input" });
+    return h("form", { class: "vmem-bar", role: "search", onsubmit: (e) => { e.preventDefault(); go("notes", input.value.trim() ? { q: input.value.trim() } : {}); } },
+      input, h("button", { type: "submit", class: "btn", text: "Search" }));
+  };
+
+  const views = {
+    overview(s) {
+      const vaults = s.status?.vaults ?? [];
+      if (!vaults.length) return [empty("No vault registered", "Run `vmem vaults add <id> <path>` to register one.")];
+      return [
+        searchForm(""),
+        h("div", { class: "cards" },
+          h("section", { class: "card" }, h("h2", { text: "Vaults" }),
+            rows(vaults, (v) => row(v.id, `${v.kind} · write ${v.write}${v.health && v.health !== "ok" ? ` · ${v.health}` : ""}`, () => go("overview", { vault: v.id }), v.id === s.vault ? chip("shown", "accent") : null))),
+          h("section", { class: "card" }, h("h2", { text: `${s.noteCount ?? 0}${s.noteCountCapped ? "+" : ""} notes · maps` }),
+            rows((s.mocs ?? []).slice(0, 8), (m) => row(m.title || m.path, `${m.count} links`, () => openNote(m.path))) ?? empty("No maps yet")),
+          h("section", { class: "card" }, h("h2", { text: "Recent log" }),
+            rows(s.log ?? [], (r) => row(r.raw ?? `${r.type} ${r.source}${r.dest ? ` → ${r.dest}` : ""}`, r.raw ? "" : `${r.at} · ${r.project}${r.agent ? " · agent" : ""}`, () => go("log"))) ?? empty("Log is empty"))),
+      ];
+    },
+    notes(s) {
+      const list = s.notes ?? [];
+      return [searchForm(s.q), s.error ? err(s.error) : null,
+        rows(list, (n) => row(n.title || n.path, [n.type, n.domain, n.description].filter(Boolean).join(" · "), () => openNote(n.path)))
+          ?? empty(s.q ? "No notes match" : "No notes", s.q ? "Try fewer words; terms are combined with AND." : null)];
+    },
+    note(s) {
+      if (s.error) return [err(s.error)];
+      const n = s.note;
+      if (!n) return [empty("No note selected", "Open a note from Search or the palette.")];
+      const fm = n.frontmatter ?? {};
+      const title = fm.title || n.path;
+      const moveInput = h("input", { type: "text", name: "to", class: "vmem-input", "aria-label": "New stem", placeholder: "new-stem" });
+      const orgs = s.orgVaults ?? [];
+      const orgSelect = orgs.length ? h("select", { name: "org", class: "vmem-input", "aria-label": "Org vault" }, orgs.map((o) => h("option", { value: o, text: o }))) : null;
+      const out = s.links?.out ?? [], back = s.links?.in ?? [], dead = s.links?.dead ?? [];
+      return [
+        h("header", { class: "vmem-head" }, chip(fm.type || "note"), h("h2", { text: title }), fm.status ? chip(fm.status, fm.status === "superseded" ? "warn" : null) : null),
+        fm.description ? h("p", { class: "vmem-sub", text: fm.description }) : null,
+        h("div", { class: "vmem-bar" },
+          btn("Delete…", () => host.action({ action: "delete", path: n.path, ...(params.vault ? { vault: params.vault } : {}) }), "btn danger"),
+          h("form", { class: "vmem-inline", onsubmit: (e) => { e.preventDefault(); if (moveInput.value.trim()) host.action({ action: "move", from: n.path, to: moveInput.value.trim(), ...(params.vault ? { vault: params.vault } : {}) }); } },
+            moveInput, h("button", { type: "submit", class: "btn", text: "Move…" })),
+          orgSelect ? (() => {
+            const topics = h("input", { type: "text", name: "orgTopics", class: "vmem-input", "aria-label": "Org topics (comma separated, optional)", placeholder: "org topics (optional)" });
+            const again = h("input", { type: "checkbox", name: "again", "aria-label": "Promote again to another org" });
+            return h("form", { class: "vmem-inline", onsubmit: (e) => { e.preventDefault(); host.action({ action: "promote", path: n.path, to: orgSelect.value, ...(topics.value.trim() ? { topics: topics.value.trim() } : {}), ...(again.checked ? { again: true } : {}) }); } },
+              orgSelect, topics, h("label", { class: "vmem-check" }, again, h("span", { text: "again" })), h("button", { type: "submit", class: "btn", text: "Promote to org…" }));
+          })() : null),
+        h("details", { open: true }, h("summary", { text: "Body" }), h("pre", { class: "vmem-body", text: n.body ?? "" }), n.truncated ? err("Truncated; open the file for the rest.") : null),
+        h("details", {}, h("summary", { text: `Links (${out.length} out, ${back.length} in${dead.length ? `, ${dead.length} dead` : ""})` }),
+          rows([...out.map((l) => ({ path: l.resolved, label: `→ ${l.resolved}` })), ...back.map((l) => ({ path: l.source, label: `← ${l.source}` })), ...dead.map((l) => ({ label: `✕ ${l.target}` }))],
+            (l) => row(l.label, "", () => l.path && openNote(l.path))) ?? empty("No links")),
+        h("p", { class: "vmem-mono", text: `${n.path} · sha256 ${String(n.sha256 ?? "").slice(0, 12)}` }),
+      ];
+    },
+    promote(s) {
+      const projects = s.projects ?? [];
+      const all = projects.flatMap((p) => p.candidates);
+      const picked = all.find((c) => c.id === s.selected);
+      const field = (name, label, required) => h("input", { type: "text", name, class: "vmem-input", "aria-label": label, placeholder: label, required });
+      const form = picked ? (() => {
+        const domain = field("domain", "domain (required)", true), topics = field("topics", "topics, comma separated (required)", true), type = field("type", "type (optional)"), description = field("description", "description (optional)"), stem = field("stem", "file stem (needed when the title has no ASCII letters)");
+        return h("form", { class: "card vmem-form", onsubmit: (e) => {
+          e.preventDefault();
+          const meta = Object.fromEntries([["domain", domain], ["topics", topics], ["type", type], ["description", description], ["stem", stem]].filter(([, el]) => el.value.trim()).map(([k, el]) => [k, el.value.trim()]));
+          host.action({ action: "promote-from-amem", id: picked.id, project: picked.project, ...meta, ...(params.vault ? { vault: params.vault } : {}) });
+        } }, h("h2", { text: `Promote: ${picked.title || picked.kind}` }), domain, topics, type, description, stem, h("button", { type: "submit", class: "btn primary", text: "Preview promotion…" }));
+      })() : null;
+      return [s.unavailable ? err(s.unavailable) : null, form,
+        rows(all, (c) => row(c.title || c.kind, `${c.kind} · ${c.project} · ${new Date(c.at).toLocaleString()}`, () => go("promote", { id: c.id, project: c.project }),
+          s.selected === c.id ? chip("selected", "accent") : btn("Select", () => go("promote", { id: c.id, project: c.project }))))
+          ?? empty("No promotion candidates", "Durable agent memories appear here when agent-mem marks them for the vault.")];
+    },
+    lint(s) {
+      const f = s.findings ?? [];
+      return [h("p", { class: "vmem-sub", text: s.summary ?? "" }),
+        rows(f, (x) => row(x.message, `${x.code}${x.path ? ` · ${x.path}` : ""}`, () => x.path && openNote(x.path), chip(x.severity, x.severity === "error" ? "err" : "warn")))
+          ?? empty("No lint findings", "The vault passes every check.")];
+    },
+    log(s) {
+      const r = s.rows ?? [];
+      return [s.error ? err(s.error) : null,
+        rows(r, (x) => row(x.raw ?? `${x.type}  ${x.source}${x.dest ? ` → ${x.dest}` : ""}`, x.raw ? "unparsed line" : `${x.at} · ${x.project} · ${x.note}${x.agent ? " · agent" : ""}`,
+          () => { const p = x.dest ?? x.source; if (typeof p === "string" && p.startsWith("notes/")) openNote(p); })) ?? empty("Log is empty")];
+    },
+  };
+
+  let last = "";
+  host.onSnapshot((snap) => {
+    const sig = JSON.stringify([panel, snap]);
+    if (sig === last) return; // unchanged poll: keep focus and scroll
+    last = sig;
+    // A poll re-renders the view: carry every typed value and the focus over by field name.
+    // Rule: every form control in this file has a stable name, or its state is lost on the next poll.
+    const values = new Map([...root.querySelectorAll("input[name], select[name]")].map((el) => [el.name, el.type === "checkbox" ? el.checked : el.value]));
+    const focused = root.contains(document.activeElement) ? document.activeElement.getAttribute("name") : null;
+    root.replaceChildren(...(views[panel]?.(snap) ?? [empty("Unknown panel")]).filter(Boolean));
+    for (const el of root.querySelectorAll("input[name], select[name]")) if (values.has(el.name)) el[el.type === "checkbox" ? "checked" : "value"] = values.get(el.name);
+    if (focused) root.querySelector(`[name="${focused}"]`)?.focus();
+  });
+  return {
+    show(id, p = {}) { panel = id; params = p; last = ""; root.replaceChildren(); },
+    hide() {},
+    destroy() { root.remove(); },
+  };
+};

package/src/ui/plugin.ts

@@ -0,0 +1,292 @@
+/**
+ * Console plugin (api 1) for acon: STAIxBWLB/agent-console contract, UX per vault-mem#48.
+ * The provider reuses the `vmem mcp` handlers in process, so the console acts with exactly the MCP rights and checks.
+ */
+import { readFileSync } from "node:fs";
+import type { ActionResult, Change, ConsolePlugin, ConsoleProvider, InboxItem } from "@staix/agent-console/contract";
+import { analysisInput } from "../analysis-input.ts";
+import { resolveHome } from "../home.ts";
+import { createVaultMcp } from "../mcp-vault.ts";
+import { validArguments } from "../mcp.ts";
+import { listPromotionCandidates } from "../promote.ts";
+import { loadRegistry } from "../registry.ts";
+import { lintVault } from "../vault-lint.ts";
+import type { LintCode } from "../analysis-types.ts";
+
+const asset = (name: string) => readFileSync(new URL(name, import.meta.url), "utf8");
+const VERSION = (JSON.parse(asset("../../package.json")) as { version: string }).version;
+const LINT_ERRORS: LintCode[] = ["L01", "L02", "L13"];
+const CACHE_MS = 60_000;
+
+type Args = Record<string, unknown>;
+const str = (v: unknown): string | undefined => typeof v === "string" && v.length > 0 ? v : undefined;
+const rec = (v: unknown): Record<string, unknown> => (v && typeof v === "object" ? v as Record<string, unknown> : {});
+/**
+ * The console's answer to a confirmed write. An applied write is done, together with any later step that failed
+ * (a log line, the agent-mem link, SYNC lines). A successful no-op (already linked, nothing to change, a retried
+ * confirmation) is success too, never a refusal. Anything else is refused with its first issue.
+ */
+export function confirmedOutcome(done: Args, verb: string): ActionResult {
+  if (done.applied === true) {
+    const missing = followUpProblems(done);
+    return { ok: true, message: missing.length ? `${verb}: applied, but ${missing.join("; ")}` : `${verb}: done` };
+  }
+  const issues = Array.isArray(done.issues) ? done.issues as { severity?: string }[] : [];
+  if (done.ok === true && !issues.some(i => i.severity !== "warning")) return { ok: true, message: `${verb}: already done, nothing changed` };
+  return { ok: false, error: firstIssue(done) };
+}
+const firstIssue = (r: Args): string => {
+  const issues = Array.isArray(r.issues) ? r.issues as { message?: string; severity?: string }[] : [];
+  return (issues.find(i => i.severity !== "warning") ?? issues[0])?.message ?? "refused";
+};
+
+/** `- 2026-10-31 09:12  LEARN  proj  src → dest  — note (vmem:agent)` as a row; unparsable lines keep their text. */
+export function parseLogLine(line: string): { at: string; type: string; project: string; source: string; dest?: string; note: string; agent: boolean } | { raw: string } {
+  const m = /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2})  (\S+)  (\S+)  (.+?)(?: → (.+?))?  — (.*?)( \(vmem:agent\))?$/.exec(line.replace(/\n$/, ""));
+  if (!m) return { raw: line };
+  return { at: m[1]!, type: m[2]!, project: m[3]!, source: m[4]!, ...(m[5] ? { dest: m[5] } : {}), note: m[6]!, agent: m[7] !== undefined };
+}
+
+/** Lint strings carry the note path in the first backtick span; this turns them into typed findings. */
+export function typedFindings(findings: Record<string, string[]>): { code: string; severity: "error" | "warning"; path?: string; message: string }[] {
+  return Object.entries(findings).flatMap(([code, list]) => list.map(message => {
+    const path = /`(notes\/[^`]+\.md)`/.exec(message)?.[1];
+    return { code, severity: LINT_ERRORS.includes(code as LintCode) ? "error" as const : "warning" as const, ...(path ? { path } : {}), message };
+  }));
+}
+
+/** Failed steps after an applied write: the log receipt(s) of a write, a promotion or an org promotion, and the result's own issues. */
+export function followUpProblems(r: Args): string[] {
+  const out: string[] = [];
+  const failed = (x: unknown) => { const l = rec(x); if (l.ok === false) out.push(firstIssue(l)); };
+  const logs = rec(r.logs);
+  for (const receipt of [r.log, rec(r.note).log, logs.source, logs.target, r.provenance]) failed(receipt);
+  if (r.ok === false) out.push(firstIssue(r));
+  return [...new Set(out)];
+}
+
+/** Planned file changes of a vmem preview, as the shell's "What will change" list. */
+function changesOf(receipt: Args): Change[] {
+  const list = Array.isArray(receipt.changes) ? receipt.changes as { path: string; beforeSha: string | null; sha256: string | null }[] : [];
+  return list.map(c => ({ op: c.beforeSha === null ? "create" : c.sha256 === null ? "delete" : "modify", target: c.path }));
+}
+
+export const plugin: ConsolePlugin = {
+  manifest: {
+    api: 1, tool: "vmem", version: VERSION, title: "Vault", icon: "vault", pollMs: 15_000,
+    panels: [
+      { id: "overview", title: "Overview", order: 1 },
+      { id: "notes", title: "Search", order: 2 },
+      { id: "note", title: "Note", order: 3 },
+      { id: "promote", title: "Promote", order: 4 },
+      { id: "lint", title: "Lint", order: 5 },
+      { id: "log", title: "Log", order: 6 },
+    ],
+    capabilities: { actions: ["delete", "move", "promote", "promote-from-amem"], confirm: true, inbox: true, search: true },
+  },
+  async open(ctx): Promise<ConsoleProvider> {
+    const home = resolveHome().home;
+    const mcp = createVaultMcp(home);
+    const call = async (name: string, args: Args): Promise<Args> => rec(await mcp.handlers[name]!(args));
+    // The shell's tabs navigate without params, so the vault chosen on one panel is kept for the others.
+    // ponytail: one choice per provider; fine for H0's single person, per session once H1 serves several.
+    let chosen: string | undefined;
+    // An explicit vault must exist (undefined otherwise, like MCP's own check); only an omitted one falls back.
+    const vaultOf = (args: Args) => {
+      const asked = str(args.vault);
+      if (asked) { const spec = mcp.vaults.find(v => v.id === asked); if (spec) chosen = spec.id; return spec; }
+      return mcp.vaults.find(v => v.id === (chosen ?? mcp.defaultVault));
+    };
+    // The vault argument for an MCP call: an explicit id goes through unchanged so the handler refuses an unknown one.
+    const vaultArg = (args: Args) => str(args.vault) ?? vaultOf(args)?.id;
+    const pass = (args: Args) => { vaultOf(args); const v = vaultArg(args); return v ? { vault: v } : {}; };
+    /**
+     * Every option the MCP tool declares reaches it: the console never hand-picks arguments, so a supported
+     * operation cannot be lost on the way. Form text for array options is split on commas; the result is checked
+     * against the tool's own schema before anything runs.
+     */
+    const forward = (tool: string, args: Args, fixed: Args = {}): Args | string => {
+      const schema = mcp.tools.find(t => t.name === tool)?.inputSchema as { properties?: Record<string, { type?: unknown }> } | undefined;
+      const out: Args = {};
+      for (const [key, spec] of Object.entries(schema?.properties ?? {})) {
+        if (key === "confirm" || key === "fingerprint") continue;
+        let value = key in fixed ? fixed[key] : key === "vault" ? vaultArg(args) : args[key];
+        if (value === undefined || value === "") continue;
+        const types = Array.isArray(spec.type) ? spec.type : [spec.type];
+        if (typeof value === "string" && types.includes("array") && !types.includes("string")) value = value.split(",").map(v => v.trim()).filter(Boolean);
+        if (value === "true" && types.includes("boolean")) value = true;
+        out[key] = value;
+      }
+      return validArguments(out, schema ?? { type: "object" }) ? out : `invalid input for ${tool}`;
+    };
+
+    // ponytail: lint reads every note, so inbox polls reuse one result per vault for 60 s; invalidate on writes if it lags.
+    const lintCache = new Map<string, { at: number; report: ReturnType<typeof lintVault> }>();
+    const lint = (id: string) => {
+      const hit = lintCache.get(id);
+      if (hit && Date.now() - hit.at < CACHE_MS) return hit.report;
+      const spec = mcp.vaults.find(v => v.id === id)!;
+      const report = lintVault(analysisInput(home, id, { expectedVault: spec }).snapshot);
+      lintCache.set(id, { at: Date.now(), report });
+      return report;
+    };
+    const projectOf = new Map<string, string>();
+    const candidates = async () => {
+      try {
+        const { projects } = await listPromotionCandidates({ allProjects: true, limit: 50, piiPatterns: loadRegistry(home).piiPatterns });
+        for (const p of projects) for (const c of p.candidates) projectOf.set(c.id, c.project);
+        return { projects };
+      }
+      catch (error) { ctx.log(`vmem: promotion candidates unavailable: ${error instanceof Error ? error.message : String(error)}`); return { projects: [], unavailable: "agent-mem candidates are unavailable; see System" }; }
+    };
+
+    // The shell keys snooze and oldest-first order on `at`, so an item 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 p of (await candidates()).projects) for (const c of p.candidates) items.push({
+        id: `mem:${c.id}`, group: "candidate", kind: "promotion", title: c.title ?? c.kind, detail: `${c.kind} memory to promote into a vault note`,
+        project: c.project, at: new Date(c.at).toISOString(),
+        // Promotion needs a domain and topics, so the item opens the Promote panel instead of offering a one-key verb.
+        verbs: [],
+        link: { panel: "promote", params: { id: c.id, project: c.project } },
+      });
+      for (const v of mcp.vaults.filter(x => x.kind === "personal")) {
+        let report;
+        try { report = lint(v.id); } catch (error) { ctx.log(`vmem: lint ${v.id} failed: ${error instanceof Error ? error.message : String(error)}`); continue; }
+        if (report.errors > 0) items.push({ id: `lint:${v.id}`, group: "alert", kind: "lint", title: `${report.errors} lint errors in ${v.id}`, detail: report.summary, at: since(`lint:${v.id}`),
+          chip: { text: `${report.errors} errors`, tone: "err" }, verbs: [], link: { panel: "lint", params: { vault: v.id } } });
+        const stale = report.findings.L11 ?? [];
+        if (stale.length) items.push({ id: `stale:${v.id}`, group: "alert", kind: "lint", title: `Graph report is stale in ${v.id}`, detail: stale[0]!, at: since(`stale:${v.id}`),
+          chip: { text: "stale", tone: "warn" }, verbs: [], link: { panel: "lint", params: { vault: v.id } } });
+      }
+      for (const id of firstSeen.keys()) if (!items.some(i => i.id === id)) firstSeen.delete(id);
+      return items;
+    }
+
+    /** One two-step operation: preview, and with the console's confirmation recompute and write only on the same fingerprint. */
+    async function twoStep(tool: string, args: Args | string, confirmed: boolean, fingerprint: string | undefined, describe: (preview: Args) => { verb: string; preview: string[]; changes: Change[]; warnings: string[] }): Promise<ActionResult> {
+      if (typeof args === "string") return { ok: false, error: args };
+      const preview = await call(tool, args);
+      if (preview.refused || preview.ok === false || typeof preview.fingerprint !== "string") return { ok: false, error: firstIssue(preview) };
+      if (!confirmed || fingerprint !== preview.fingerprint) {
+        const d = describe(preview);
+        return { ok: false, needsConfirm: true, fingerprint: preview.fingerprint, verb: d.verb, preview: d.preview, changes: d.changes, ...(d.warnings.length ? { warnings: d.warnings } : {}) };
+      }
+      const done = await call(tool, { ...args, confirm: true, fingerprint });
+      if (done.applied === true) lintCache.clear();
+      return confirmedOutcome(done, describe(preview).verb);
+    }
+
+    return {
+      assets: { js: asset("./panel.js"), css: asset("./panel.css") },
+      async snapshot(input) {
+        const args = input as Args;
+        switch (input.panel) {
+          case "inbox": return { items: await inbox() };
+          case "search": {
+            const q = str(args.q);
+            if (!q) return { hits: [], total: 0 };
+            const limit = Math.min(10, Math.max(1, Number(args.limit) || 10));
+            const r = await call("vmem_search", { query: q, limit, ...pass(args) });
+            const hits = (Array.isArray(r.hits) ? r.hits as { path: string; title: string; description: string }[] : []).map(h => ({
+              id: h.path, kind: "note", title: h.title, detail: h.description, link: { panel: "note", params: { path: h.path } } }));
+            return { hits, total: hits.length };
+          }
+          case "overview": {
+            const status = await call("vmem_status", {});
+            const vault = vaultOf(args);
+            if (!vault) return { status, vault: null };
+            const [notes, mocs, log] = await Promise.all([call("vmem_list", { vault: vault.id, limit: 500 }), call("vmem_mocs", { vault: vault.id }), call("vmem_log_tail", { vault: vault.id, n: 8 })]);
+            const count = Array.isArray(notes.notes) ? notes.notes.length : 0;
+            return { status, vault: vault.id, noteCount: count, noteCountCapped: count >= 500, mocs: mocs.mocs ?? [], log: (Array.isArray(log.lines) ? log.lines as string[] : []).map(parseLogLine) };
+          }
+          case "notes": {
+            const q = str(args.q);
+            const r = q ? await call("vmem_search", { query: q, limit: 50, ...pass(args) }) : await call("vmem_list", { limit: 100, ...pass(args) });
+            return { q: q ?? "", notes: r.hits ?? r.notes ?? [], ...(r.refused ? { error: firstIssue(r) } : {}) };
+          }
+          case "note": {
+            const path = str(args.path);
+            if (!path) return { note: null };
+            const note = await call("vmem_read", { path, ...pass(args) });
+            if (note.refused) return { note: null, error: firstIssue(note) };
+            const links = await call("vmem_links", { path, ...pass(args) });
+            // vmem_promote always reads from the default personal vault, so offer it only there.
+            const promotable = vaultOf(args)?.id === mcp.defaultVault && vaultOf(args)?.kind === "personal";
+            return { note, links, orgVaults: promotable ? mcp.vaults.filter(v => v.kind === "org").map(v => v.id) : [] };
+          }
+          case "promote": return { ...(await candidates()), selected: str(args.id) ?? null };
+          case "lint": {
+            const vault = vaultOf(args);
+            if (!vault) return { findings: [] };
+            const report = lint(vault.id);
+            return { vault: vault.id, errors: report.errors, warnings: report.warnings, summary: report.summary, findings: typedFindings(report.findings) };
+          }
+          case "log": {
+            const vault = vaultOf(args);
+            if (!vault) return { rows: [] };
+            const r = await call("vmem_log_tail", { vault: vault.id, n: 100, ...(str(args.type) ? { type: args.type } : {}) });
+            return { vault: vault.id, rows: (Array.isArray(r.lines) ? r.lines as string[] : []).map(parseLogLine).reverse(), ...(r.ok === false ? { error: firstIssue(r) } : {}) };
+          }
+          default: return { error: `unknown panel ${input.panel}` };
+        }
+      },
+      async action(input) {
+        const args = input as Args, confirmed = input.confirmed === true, fingerprint = str(input.fingerprint);
+        switch (input.action) {
+          case "delete": {
+            const path = str(args.path) ?? str(args.id);
+            if (!path) return { ok: false, error: "path is required" };
+            return twoStep("vmem_delete", forward("vmem_delete", args, { path }), confirmed, fingerprint, p => {
+              const backlinks = Array.isArray(p.backlinks) ? p.backlinks as { source: string }[] : [];
+              return { verb: "Delete note", preview: [`delete ${path}`], changes: changesOf(p),
+                warnings: backlinks.length ? [`${backlinks.length} links point here: ${[...new Set(backlinks.map(b => b.source))].slice(0, 5).join(", ")}`] : [] };
+            });
+          }
+          case "move": {
+            const from = str(args.from), to = str(args.to);
+            if (!from || !to) return { ok: false, error: "from and to are required" };
+            return twoStep("vmem_move", forward("vmem_move", args), confirmed, fingerprint, p => ({ verb: "Move note", preview: [`move ${from} → ${to}`], changes: changesOf(p), warnings: [] }));
+          }
+          case "promote": {
+            const path = str(args.path), to = str(args.to);
+            if (!path || !to) return { ok: false, error: "path and to are required" };
+            if (vaultOf(args)?.id !== mcp.defaultVault) return { ok: false, error: `promotion to an org vault reads from ${mcp.defaultVault}; open the note there` };
+            return twoStep("vmem_promote", forward("vmem_promote", args), confirmed, fingerprint, p => {
+              const screen = rec(p.screen), dropped = Array.isArray(p.droppedLinks) ? p.droppedLinks as string[] : [];
+              const target = String(p.target ?? `${to}:${path}`);
+              // A rerun after an interrupted promotion only restores the source provenance.
+              const changes: Change[] = p.recovery === "provenance-only"
+                ? [{ op: "modify", target: path, note: `provenance → ${target}` }]
+                : [{ op: "create", target }, { op: "modify", target: path, note: "provenance" }, { op: "log", target: "log", note: "SYNC lines in both vaults" }];
+              return { verb: p.recovery === "provenance-only" ? "Restore provenance" : "Promote note", preview: String(p.text ?? "").split("\n"),
+                changes,
+                warnings: [...(dropped.length ? [`${dropped.length} links become plain text: ${dropped.slice(0, 5).join(", ")}`] : []), ...(screen.passed === false ? ["screen reported issues"] : [])] };
+            });
+          }
+          case "promote-from-amem": {
+            const id = (str(args.id) ?? "").replace(/^mem:/, "");
+            if (!/^[0-9a-f-]{32,36}$/i.test(id)) return { ok: false, error: "a memory id is required" };
+            if (!projectOf.has(id)) await candidates();
+            const project = str(args.project) ?? projectOf.get(id);
+            return twoStep("vmem_promote_from_amem", forward("vmem_promote_from_amem", args, { id, ...(project ? { project } : {}) }), confirmed, fingerprint, p => {
+              const dupes = Array.isArray(p.possibleDuplicates) ? p.possibleDuplicates as string[] : [];
+              // Linking an existing note writes no vault file; it records the link in agent-mem only.
+              const changes: Change[] = p.action === "link"
+                ? [{ op: "modify", target: `agent-mem mem:${id}`, note: `vault link → ${String(p.path)}` }]
+                : [{ op: "create", target: String(p.path ?? "note") }, { op: "log", target: "log", note: "LEARN line" }, { op: "modify", target: `agent-mem mem:${id}`, note: "vault link" }];
+              return { verb: p.action === "link" ? "Link memory" : "Promote memory", preview: String(p.text ?? `link mem:${id} → ${String(p.path)}`).split("\n"),
+                changes,
+                warnings: dupes.length ? [`possible duplicates: ${dupes.slice(0, 5).join(", ")}`] : [] };
+            });
+          }
+          default: return { ok: false, error: `unknown action ${input.action}` };
+        }
+      },
+    };
+  },
+};
+
+export default plugin;