opencode-self-improvement 0.2.2 → 0.3.0

package/README.md

@@ -10,7 +10,12 @@ LLMs waste a lot of tokens reading and re-reading your code and asking you for c
 - **`memory_*` tools** — remember facts, decisions, and commands the agent should
   keep across sessions (`memory_init`, `memory_remember`, `memory_recall`,
   `memory_update`, `memory_forget`, `memory_list`, `memory_undo`,
-  `memory_evidence`, `memory_export`, `memory_import`, `memory_decay`).
+  `memory_evidence`, `memory_export`, `memory_import`, `memory_decay`,
+  `memory_status`).
+- **Memory at a glance** — the terminal shows a footer badge (injected chars
+  vs budget + a cache-health dot) and a `/memory` panel; desktop/web/IDE get
+  the same report in-chat via `/memory-report`, including the *measured*
+  prompt-cache hit rate. See [Memory at a glance](#memory-at-a-glance).
 - **`/repo-init`** — for each repo: indexes the code graph and remembers the
   test/build commands, keyed to the git head. The command installs itself; no
   setup beyond the plugin.
@@ -47,6 +52,10 @@ prompt cache on every message. This one is built the other way around:
 - **Hard character budget.** The block is capped at 1200 characters by default
   (see Options) and trimmed at whole-memory boundaries — never cut mid-sentence.
 - **Evidence is never injected**, and the standing system digest is two lines.
+- **Receipts, not promises.** The plugin measures your session's actual
+  prompt-cache usage (from each turn's `tokens.cache` accounting) and shows it
+  next to the badge — so a cache hit rate you can watch, not just a byte-freeze
+  claim you have to trust.
 
 Measured on a deterministic workload (50 memories, 20 prompts, 3 mid-session
 store writes) using the plugin's real injection code:
@@ -130,7 +139,7 @@ Add a `plugins` entry to your opencode config —
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["opencode-self-improvement@0.2.1"]
+  "plugins": ["opencode-self-improvement@0.3.0"]
 }
 ```
 
@@ -144,7 +153,7 @@ bump the version in the config and restart. On Opencode v2 you can also manage
 it with the CLI:
 
 ```sh
-opencode plugin add opencode-self-improvement@0.2.1
+opencode plugin add opencode-self-improvement@0.3.0
 opencode plugin update opencode-self-improvement
 ```
 
@@ -187,6 +196,7 @@ the plugin entry in `opencode.json(c)` instead of the plain string:
 | `autoCapture` | `false` (off) | When on, each session-idle event makes one cheap model pass that proposes memory candidates. Every candidate still goes through the 4-gate write pipeline — capture can never bypass the gates. Off by default: the zero-token install stays zero-token. |
 | `captureModel` | — | `"provider/id"` model used for auto-capture. Required when `autoCapture` is on; a missing or invalid value disables capture with a startup warning. |
 | `captureMax` | `3` | Maximum candidates proposed per idle event. |
+| `notifyBlocked` | `true` (on) | Terminal (TUI) half only: toast when the write gate blocks a memory write. `false` keeps the panel quiet; blocks are always in `memory_evidence` regardless. |
 
 ## Code graph (optional)
 
@@ -251,6 +261,38 @@ and the tool reports a tally of four outcomes per line —
 so re-running the same import is a no-op (everything collapses). Copying an
 export to a fresh machine is how you seed a new laptop from an old one.
 
+## Memory at a glance
+
+"Wait, what did the memory plugin just do?" — answered differently per client,
+same data (`memory_status` tool under the hood; no model call):
+
+**Terminal (opencode CLI)** — the plugin ships a TUI half
+(`@opencode/plugin/tui`) that loads automatically:
+
+- a footer badge: `● mem 1157/1200c · cache 96%` — the injected block against
+  its budget, and the measured session prompt-cache hit rate. The dot is green
+  (stable + warm), yellow (a recent recompute, or 50–90% reads), or red (last
+  turn served almost nothing from cache). `—` until the first assistant turn.
+- **`/memory`** opens a session panel (every number is this session only):
+  - **CONTEXT** — exact chars + estimated tokens riding now, % of the budget,
+    requests the current epoch has ridden, session-lifetime totals, and how
+    many requests abstained (silence is a feature)
+  - **CACHE** — epoch invalidations this session with the last reason, server
+    recompute count, and the *measured* prompt-cache read rate of the last turn
+    — the receipt, not just the promise
+  - **INJECTED BLOCK** — the verbatim block riding your prompts, or an explicit
+    "abstained: no vocabulary overlap"
+  - **RECENT BLOCKED WRITES** — that `memory_remember` that didn't stick,
+    with its gate reason
+  - **STORE** — active / superseded / open / scopes
+  - keys: `r` refresh, `f` fullscreen
+- a warning toast when a write is blocked (opt out: `"notifyBlocked": false`)
+
+**Desktop / web / IDE** — no TUI slots there (they're terminal-only), so use
+the self-installed **`/memory-report`** chat command: the same four sections,
+rendered in the conversation. For editing, the browser admin (`bun memory-view`)
+works everywhere.
+
 ## Admin Tool
 
 Editing and deleting memories is easy!

package/command/memory-report.md

@@ -0,0 +1,7 @@
+---
+description: Memory status — what is injected right now, blocked writes, store stats, cost ledger
+---
+
+Call the `memory_status` tool and render its output verbatim inside a fenced
+code block. Do not summarize, reinterpret, or add commentary. If the report
+shows no epoch yet, say so in one sentence instead of guessing.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "opencode-self-improvement",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Durable memory for opencode: remember facts, decisions, and commands across sessions, plus a one-command per-repo setup (/repo-init).",
   "main": "index.ts",
   "exports": {
-    ".": "./index.ts"
+    ".": "./index.ts",
+    "./tui": "./src/tui.tsx"
   },
   "module": "index.ts",
   "type": "module",
@@ -27,6 +28,7 @@
   ],
   "files": [
     "index.ts",
+    "tui.ts",
     "src",
     "command",
     "vendor",
@@ -37,13 +39,20 @@
     "codebase-memory-mcp": "0.11.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.6.2",
     "@opencode/plugin": "^2.0.32",
+    "@opentui/core": ">=0.6.6",
+    "@opentui/solid": ">=0.6.6",
     "@semantic-release/git": "^11.0.1",
     "@types/bun": "latest",
     "semantic-release": "^25.0.9",
+    "solid-js": ">=1.9.0",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
+    "@opentui/core": ">=0.6.6",
+    "@opentui/solid": ">=0.6.6",
+    "solid-js": ">=1.9.0",
     "typescript": "^7.0.2"
   },
   "scripts": {
@@ -51,6 +60,7 @@
     "typecheck": "bunx tsc --noEmit -p tsconfig.json",
     "bench": "bun bench/inject-cost.ts",
     "bench:recall": "bun bench/recall-quality.ts",
-    "memory-view": "bun run src/viewer/server.ts"
+    "memory-view": "bun run src/viewer/server.ts",
+    "lint": "biome lint"
   }
 }

package/src/command.ts

@@ -1,25 +1,36 @@
-// Self-installs the /repo-init slash command as part of plugin load, so users
-// never run a terminal command to set up init. The command markdown ships in
-// the package (command/repo-init.md) and is mirrored idempotently
+// Self-installs the plugin's slash commands as part of plugin load, so users
+// never run a terminal command to set up. Command markdown ships in the
+// package (command/<name>.md) and is mirrored idempotently
 // (write-if-missing; never overwrites a user's edits). Failures are swallowed —
-// a missing command degrades to "ask the model to call memory_init".
+// a missing command degrades to "ask the model to call the tool".
 import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { commandsDir } from "./config.ts";
 
-const SOURCE = join(dirname(fileURLToPath(import.meta.url)), "..", "command", "repo-init.md");
+const PKG_COMMANDS = join(dirname(fileURLToPath(import.meta.url)), "..", "command");
 
-export async function ensureInitCommand(): Promise<string | null> {
+export async function ensureCommand(name: string): Promise<string | null> {
   try {
-    const target = join(commandsDir(), "repo-init.md");
+    const target = join(commandsDir(), `${name}.md`);
     if (existsSync(target)) return null;
-    const text = await Bun.file(SOURCE).text();
+    const text = await Bun.file(join(PKG_COMMANDS, `${name}.md`)).text();
     await mkdir(commandsDir(), { recursive: true });
     await Bun.write(target, text);
     return target;
   } catch {
     return null;
   }
-}
+}
+
+export async function ensureInitCommand(): Promise<string | null> {
+  return ensureCommand("repo-init");
+}
+
+// /memory-report: the chat-client parity for the terminal /memory panel
+// (drives the memory_status tool). Terminal users with the TUI half get the
+// live panel via /memory instead; both are documented in the README.
+export async function ensureMemoryReportCommand(): Promise<string | null> {
+  return ensureCommand("memory-report");
+}

package/src/index.ts

@@ -38,7 +38,16 @@ import {
   systemDigest,
 } from "./inject.ts";
 import { formatInit, runInit } from "./init.ts";
-import { ensureInitCommand } from "./command.ts";
+import { ensureInitCommand, ensureMemoryReportCommand } from "./command.ts";
+import {
+  blockedRecent,
+  emptyStats,
+  renderMemoryReport,
+  writeStatus,
+  type Measured,
+  type SessionStats,
+  type StatusPayload,
+} from "./status.ts";
 import {
   afterTool,
   checkNewSession,
@@ -163,6 +172,7 @@ const impl = {
     // (idempotent, write-if-missing). OpenCode 2.x loads `*.md` from
     // ~/.config/opencode/commands, so this is the canonical V2 install path.
     await ensureInitCommand();
+    await ensureMemoryReportCommand();
 
     // Fail-closed hook guard: the plugin's own bookkeeping can never take down a
     // tool call, the system transform, or compaction.
@@ -574,6 +584,30 @@ const impl = {
           };
         },
       });
+
+      editor.add({
+        name: "memory_status",
+        description:
+          "Plain-text memory report for chat clients (desktop/web/IDE), same sections as the terminal /memory panel: CONTEXT (this session's injected block, budget use, cumulative ride and abstentions), CACHE (epoch invalidations plus the measured session prompt-cache read rate), the block verbatim, recent blocked writes with gate reasons, and store stats. Reads only — no model call.",
+        options: direct,
+        input: obj({}),
+        async execute(): Promise<{ content: string }> {
+          // In-process truth: the live epoch + ledger, fresher than any file.
+          const sid = getCurrent().sid;
+          const status = sid === "?" ? null : await buildPayload(sid);
+          const all = await loadAll();
+          const act = all.filter(isActive);
+          const store = {
+            active: act.length,
+            superseded: all.length - act.length,
+            open: act.filter((m) => m.status === "open").length,
+            scopes: new Set(act.map((m) => m.scope)).size,
+          };
+          return {
+            content: renderMemoryReport({ status, store, blocked: await blockedRecent(6) }),
+          };
+        },
+      });
     });
 
     // Per-session frozen injection epochs: the relevance block plus the store
@@ -581,7 +615,53 @@ const impl = {
     // of a session, when the store changes, or after a compaction (see the
     // prompt/compaction hooks) — so the system prefix, and with it the
     // provider prompt cache, survives ordinary turns.
-    const epoch = new Map<string, { version: string; block: string }>();
+    const epoch = new Map<string, { version: string; block: string; at: string; reason: "first" | "store_changed" }>();
+    // Recomputes since server start: every one invalidated a prompt cache, so
+    // it is the honest cost number the surfaces show (status files / tools).
+    let epochRecomputes = 0;
+
+    // Per-session ledger, incremented at the injection decision below, and the
+    // last measured prompt-cache usage per session (message.updated). The
+    // surfaces read these through flushed status files (TUI) or directly
+    // (memory_status, in-process).
+    const sessionStats = new Map<string, SessionStats>();
+    const measuredTurns = new Map<string, Measured>();
+    const statsFor = (sid: string): SessionStats => {
+      let st = sessionStats.get(sid);
+      if (!st) {
+        st = emptyStats();
+        sessionStats.set(sid, st);
+      }
+      return st;
+    };
+
+    // Build the full status snapshot for one session, or null before its first
+    // epoch. Store counts are computed fresh so every flush is current.
+    const buildPayload = async (sid: string): Promise<StatusPayload | null> => {
+      const ep = epoch.get(sid);
+      if (!ep) return null;
+      const all = await loadAll();
+      const act = all.filter(isActive);
+      return {
+        at: ep.at,
+        sessionID: sid,
+        reason: ep.reason,
+        recomputes: epochRecomputes,
+        block: ep.block,
+        blockChars: ep.block.length,
+        budget,
+        store: {
+          active: act.length,
+          superseded: all.length - act.length,
+          open: act.filter((m) => m.status === "open").length,
+          scopes: new Set(act.map((m) => m.scope)).size,
+        },
+        stats: statsFor(sid),
+        measured: measuredTurns.get(sid) ?? null,
+      };
+    };
+    const flushStatus = (sid: string): Promise<void> =>
+      buildPayload(sid).then((p) => (p ? writeStatus(p) : undefined));
 
     // ---- hooks (all fail-closed) -------------------------------------------
     // Bookkeeping: track the active session/tool/call before a tool runs.
@@ -626,6 +706,16 @@ const impl = {
         const sid = event?.sessionID;
         const knowledge = typeof sid === "string" ? epoch.get(sid)?.block : undefined;
         if (knowledge) event?.system?.push?.({ type: "text", text: knowledge });
+        // Count AT THE INJECTION DECISION so badge/panel numbers match exactly
+        // what rode this request (a later abort still rode the bytes — known
+        // and documented). Abstained = the epoch exists but its block is empty.
+        if (typeof sid === "string") {
+          const st = statsFor(sid);
+          st.requests++;
+          st.epochRequests++;
+          if (knowledge) st.cumChars += knowledge.length;
+          else if (epoch.has(sid)) st.abstained++;
+        }
       }),
     );
 
@@ -647,16 +737,31 @@ const impl = {
             const text = event?.prompt?.text ?? "";
             const raw = await relevantKnowledge(text, 5); // widen candidate pool
             const block = raw ? capToBudget(raw, budget) : "";
-            epoch.set(sid, { version, block });
+            const at = new Date().toISOString();
+            const reason: "first" | "store_changed" = cached ? "store_changed" : "first";
+            epoch.set(sid, { version, block, at, reason });
             await record(
               "epoch_recompute",
               {
                 session: sid,
-                reason: cached ? "store_changed" : "first",
+                reason,
                 chars: block.length,
               },
               false,
             );
+            epochRecomputes++;
+            // Ledger: a store_changed recompute of a live epoch is an
+            // invalidation (the first epoch of a session busts nothing). The
+            // epoch request count restarts with the new block.
+            const st = statsFor(sid);
+            st.epochRequests = 0;
+            if (reason === "store_changed") {
+              st.invalidations++;
+              st.lastInvalidation = { at, reason };
+            }
+            // Status hand-off for the terminal panel (src/tui.tsx) and any
+            // out-of-process surface. Best-effort; never breaks injection.
+            await flushStatus(sid);
           }
         }
       }),
@@ -677,8 +782,46 @@ const impl = {
       }),
     );
 
+    // ---- measured prompt-cache health (message.updated usage) --------------
+    // Zero-model by design: assistant messages carry tokens {input, output,
+    // reasoning, cache.read/write}; the session-wide read/(read+input+write)
+    // share is the honest receipt behind the byte-stability proxy. Streaming
+    // updates for one message arrive repeatedly — overwriting with the latest
+    // is correct because the final update carries the complete usage. Flushes
+    // the per-session status file so the TUI badge refreshes once per turn
+    // instead of per step. Degrades to "not measured" when the host exposes
+    // no event stream.
+    const measuredController = new AbortController();
+    if (ctx.event?.subscribe) {
+      const eventApi = ctx.event;
+      void (async () => {
+        try {
+          for await (const raw of eventApi.subscribe({ signal: measuredController.signal })) {
+            const ev = raw as Record<string, any>;
+            if (ev?.type !== "message.updated") continue;
+            const info = ev.properties?.info ?? ev.info;
+            if (!info || info.role !== "assistant") continue;
+            const sid = info.sessionID;
+            const t = info.tokens;
+            if (typeof sid !== "string" || !t) continue;
+            measuredTurns.set(sid, {
+              at: new Date().toISOString(),
+              input: Number(t.input) || 0,
+              read: Number(t.cache?.read) || 0,
+              write: Number(t.cache?.write) || 0,
+            });
+            await guarded("status flush (measured)", () => flushStatus(sid));
+          }
+        } catch {
+          // the subscription ended (abort or host error); nothing to do
+        }
+      })();
+    }
+
     // ---- opt-in auto-capture on session idle --------------------------------
-    // Default OFF: zero-token installs never subscribe to anything. When
+    // Default OFF: capture never reads sessions and never calls a model. (The
+    // measured-cache listener above does subscribe to the event stream by
+    // default, but it is zero-model: pure bookkeeping of message usage.) When
     // enabled (options.autoCapture === true AND a valid captureModel), each
     // session.idle event runs ONE cheap ctx.generate.text call whose reply is
     // parsed into candidates that go through the SAME runWriteGate as
@@ -754,9 +897,12 @@ const impl = {
         captureCleanup = () => controller.abort();
       }
     }
-    // Single cleanup returned by setup: tears down the capture subscription.
-    // Future teardowns merge into this same function.
-    return captureCleanup;
+    // Single cleanup returned by setup: tears down the measured listener and,
+    // when enabled, the capture subscription. Future teardowns merge in here.
+    return () => {
+      measuredController.abort();
+      if (captureCleanup) return captureCleanup();
+    };
   },
 };
 

package/src/logfmt.ts

@@ -5,10 +5,17 @@ import { mkdir } from "node:fs/promises";
 
 export type Fields = Record<string, unknown>;
 
+// Escapes for quoted values. One record is one line, so a raw newline inside a
+// value would end the record early and the rest of the value would be read
+// back as a separate line of fields. Backslash is escaped too, so a value
+// ending in `\` cannot swallow its closing quote.
+const ESCAPE: Record<string, string> = { "\\": "\\\\", '"': '\\"', "\n": "\\n", "\r": "\\r", "\t": "\\t" };
+const UNESCAPE: Record<string, string> = { "\\": "\\", '"': '"', n: "\n", r: "\r", t: "\t" };
+
 export function quote(value: unknown): string {
   const s = String(value);
   if (s === "") return '""';
-  return /[\s"=]/.test(s) ? `"${s.replace(/"/g, '\\"')}"` : s;
+  return /[\s"=]/.test(s) ? `"${s.replace(/[\\"\n\r\t]/g, (c) => ESCAPE[c])}"` : s;
 }
 
 export function formatLine(fields: Fields): string {
@@ -20,9 +27,10 @@ export function formatLine(fields: Fields): string {
   return parts.join(" ");
 }
 
-// Unescape a quoted logfmt value and read it back.
+// Unescape a quoted logfmt value and read it back. Unknown sequences are kept
+// as written: older files stored backslashes unescaped (`C:\Program Files`).
 function unquote(s: string): string {
-  return s.replace(/\\"/g, '"');
+  return s.replace(/\\(.)/g, (seq, c: string) => UNESCAPE[c] ?? seq);
 }
 
 export function parseLine(line: string): Fields | null {
@@ -30,8 +38,9 @@ export function parseLine(line: string): Fields | null {
   if (!trimmed || !trimmed.includes("=")) return null;
   const fields: Fields = {};
   const re = /([A-Za-z0-9_.-]+)=("(?:[^"\\]|\\.)*"|[^\s]*)/g;
-  let m: RegExpExecArray | null;
-  while ((m = re.exec(trimmed)) !== null) {
+  for (;;) {
+    const m = re.exec(trimmed);
+    if (!m) break;
     const key = m[1];
     let raw = m[2];
     if (raw.startsWith('"') && raw.endsWith('"')) {

package/src/resolver.ts

@@ -85,8 +85,9 @@ function looksProseArgs(inner: string): boolean {
 export function extractCallForms(content: string): CallForm[] {
   const forms: CallForm[] = [];
   CALL_RE.lastIndex = 0;
-  let m: RegExpExecArray | null;
-  while ((m = CALL_RE.exec(content)) !== null) {
+  for (;;) {
+    const m = CALL_RE.exec(content);
+    if (!m) break;
     const symbol = m[1];
     const openIdx = content.indexOf("(", m.index + symbol.length);
     const paren = openIdx >= 0 ? balancedParen(content, openIdx) : null;

package/src/status.ts

@@ -0,0 +1,316 @@
+// The status hand-off between the two surface halves. The server plugin writes
+// one status file per session on every epoch recompute AND every measured
+// assistant turn (src/index.ts); the terminal plugin (src/tui.tsx) and the
+// memory_status tool consume them. Status files are deliberately NOT .logfmt
+// memory files — loadAll() must never ingest them.
+//
+// Why per-session: the epoch freeze is per-session, so a single global
+// last-writer-wins file let one session's badge show another session's epoch.
+// `status/<sessionID>.json` is the primary read; the global `status.json`
+// survives as a "latest" fallback for argument-free reads. Both are pruned /
+// written best-effort: a status failure degrades surfaces, never injection.
+//
+// Scope of v2: same-machine reads. Against a REMOTE server the terminal panel
+// sees no status files (it says so) — the RPC surface is the planned follow-up.
+import { readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { dateStr, evidenceDir, memoryRoot } from "./config.ts";
+import { parseLine, readLines } from "./logfmt.ts";
+
+export interface StoreCounts {
+  active: number;
+  superseded: number;
+  open: number;
+  scopes: number;
+}
+
+/**
+ * Per-session ledger, incremented at the session.context injection decision
+ * (so counts match exactly what was injected — an aborted turn still rode the
+ * bytes). Cumulative fields are session-lifetime; epochRequests resets when a
+ * new epoch freezes. An invalidation = a store_changed recompute that moved a
+ * live epoch (the first epoch of a session is not one).
+ */
+export interface SessionStats {
+  requests: number; // provider requests that injected through session.context
+  abstained: number; // requests where the epoch block was empty
+  cumChars: number; // lifetime sum of injected block chars
+  epochRequests: number; // requests the CURRENT epoch block has ridden
+  invalidations: number; // store_changed recomputes this session
+  lastInvalidation: { at: string; reason: string } | null;
+}
+
+export function emptyStats(): SessionStats {
+  return {
+    requests: 0,
+    abstained: 0,
+    cumChars: 0,
+    epochRequests: 0,
+    invalidations: 0,
+    lastInvalidation: null,
+  };
+}
+
+/**
+ * Measured prompt-cache usage from the last completed assistant message
+ * (message.updated -> tokens {input, cache.read, cache.write}). This is the
+ * SESSION-WIDE prompt cache — the honest receipt for "are we busting cache",
+ * never billed as our block's own rate.
+ */
+export interface Measured {
+  at: string;
+  input: number;
+  read: number;
+  write: number;
+}
+
+export interface StatusPayload {
+  /** ISO instant of the epoch recompute that produced this snapshot. */
+  at: string;
+  sessionID: string;
+  reason: "first" | "store_changed";
+  /** epoch recomputes since the server process started, ALL sessions. */
+  recomputes: number;
+  /** exact injected block ("" = abstained: no vocabulary overlap). */
+  block: string;
+  blockChars: number;
+  budget: number;
+  store: StoreCounts;
+  /** optional for backward-compatible reads of pre-v2 files. */
+  stats?: SessionStats;
+  measured?: Measured | null;
+}
+
+export interface BlockedRow {
+  ts: string;
+  sid: string;
+  reason: string;
+}
+
+export function statusFile(): string {
+  return join(memoryRoot(), "status.json");
+}
+
+export function statusDir(): string {
+  return join(memoryRoot(), "status");
+}
+
+// Session ids are host-generated (ses_…), but sanitize anyway: this string
+// becomes a file name.
+function safeName(sessionID: string): string {
+  return sessionID.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80);
+}
+
+export function sessionStatusFile(sessionID: string): string {
+  return join(statusDir(), `${safeName(sessionID)}.json`);
+}
+
+// LRU cap on per-session files: the badge only ever reads the active session,
+// so old ones are kept for post-hoc inspection up to this count, then pruned
+// by mtime (newest survive; a re-written session refreshes its mtime).
+const SESSION_FILE_CAP = 32;
+
+async function pruneStatusDir(): Promise<void> {
+  try {
+    const names = (await readdir(statusDir())).filter((n) => n.endsWith(".json"));
+    if (names.length <= SESSION_FILE_CAP) return;
+    const withMtime = await Promise.all(
+      names.map(async (n) => {
+        try {
+          return { n, m: (await stat(join(statusDir(), n))).mtimeMs };
+        } catch {
+          return { n, m: 0 }; // vanished mid-prune or unstatable: prune first
+        }
+      }),
+    );
+    withMtime.sort((a, b) => b.m - a.m);
+    for (const f of withMtime.slice(SESSION_FILE_CAP)) {
+      await rm(join(statusDir(), f.n), { force: true });
+    }
+  } catch {
+    // pruning is housekeeping; the surfaces tolerate a growing dir
+  }
+}
+
+async function writeJson(path: string, p: StatusPayload): Promise<boolean> {
+  try {
+    await Bun.write(path, JSON.stringify(p, null, 2) + "\n");
+    return true;
+  } catch {
+    return false; // swallow — surfaces degrade to "no data", the session does not
+  }
+}
+
+// Best-effort by design: a status write must never break injection. Writes the
+// per-session file (primary) AND the global latest file (fallback).
+export async function writeStatus(p: StatusPayload): Promise<void> {
+  await writeJson(statusFile(), p);
+  if (typeof p.sessionID === "string" && p.sessionID) {
+    await writeJson(sessionStatusFile(p.sessionID), p);
+    await pruneStatusDir();
+  }
+}
+
+async function readJson(path: string): Promise<StatusPayload | null> {
+  try {
+    const f = Bun.file(path);
+    if (!(await f.exists())) return null;
+    const v: unknown = await f.json();
+    if (!v || typeof v !== "object") return null;
+    const p = v as Partial<StatusPayload>;
+    if (typeof p.at !== "string" || typeof p.block !== "string") return null;
+    return p as StatusPayload;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the status for a session. With a sessionID: ONLY that session's file —
+ * a missing file returns null ("mem -") rather than another session's epoch.
+ * Without one: the global latest file.
+ */
+export async function readStatus(sessionID?: string): Promise<StatusPayload | null> {
+  if (sessionID) return readJson(sessionStatusFile(sessionID));
+  return readJson(statusFile());
+}
+
+// Newest-first last `limit` write_blocked evidence rows, scanning today and
+// yesterday so a block just before midnight stays visible.
+export async function blockedRecent(limit = 6): Promise<BlockedRow[]> {
+  const today = dateStr();
+  const yesterday = new Date(Date.now() - 86_400_000).toISOString().split("T")[0]!;
+  const rows: BlockedRow[] = [];
+  for (const day of [yesterday, today]) {
+    for (const line of await readLines(join(evidenceDir(), `${day}.logfmt`))) {
+      const f = parseLine(line);
+      if (!f || f.ev !== "write_blocked") continue;
+      rows.push({
+        ts: String(f.ts ?? day),
+        sid: String(f.sid ?? "?"),
+        reason: String(f.reason ?? "?"),
+      });
+    }
+  }
+  return rows.slice(-limit).reverse();
+}
+
+function ago(iso: string): string {
+  const ms = Date.now() - new Date(iso).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return "now";
+  const m = Math.floor(ms / 60_000);
+  if (m < 1) return "just now";
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  return `${Math.floor(h / 24)}d ago`;
+}
+
+// --- shared formatting (the /memory panel and memory_status render 1:1) ------
+
+/** Char counts are exact; tokens are an estimate, chars/4, shown only with "≈". */
+export function estTok(chars: number): number {
+  return Math.round(chars / 4);
+}
+
+/** 9999 -> "9999"; 10000 -> "10k"; 41234 -> "41.2k". */
+export function fmtCount(n: number): string {
+  if (n < 10_000) return String(n);
+  const k = n / 1000;
+  return `${k >= 100 ? Math.round(k) : Math.round(k * 10) / 10}k`;
+}
+
+/** Session-wide prompt-cache hit rate from measured usage; null = nothing measured. */
+export function cacheRate(m?: Measured | null): { read: number; prompt: number; pct: number } | null {
+  if (!m) return null;
+  const prompt = (m.input || 0) + (m.read || 0) + (m.write || 0);
+  if (prompt <= 0) return null;
+  return { read: m.read || 0, prompt, pct: Math.round(((m.read || 0) / prompt) * 100) };
+}
+
+/**
+ * Badge dot state: green = no invalidation since the last measured turn AND
+ * last measured reads >= 90%; recent = the epoch moved after the last
+ * measurement (a bust we have not yet seen re-warm); amber 50-89%; red < 50%;
+ * unknown = nothing measured yet (NEVER show 0% for "no data").
+ */
+export type CacheHealth = "green" | "recent" | "amber" | "red" | "unknown";
+
+export function cacheHealth(p: StatusPayload): CacheHealth {
+  const inv = p.stats?.lastInvalidation?.at;
+  if (inv && (!p.measured || inv > p.measured.at)) return "recent";
+  const rate = cacheRate(p.measured);
+  if (!rate) return "unknown";
+  if (rate.pct >= 90) return "green";
+  if (rate.pct >= 50) return "amber";
+  return "red";
+}
+
+export function contextLines(p: StatusPayload): string[] {
+  const st = p.stats ?? emptyStats();
+  const pct = p.budget > 0 ? Math.round((p.blockChars / p.budget) * 100) : 0;
+  return [
+    `  injected now   ${p.blockChars}c ≈ ${estTok(p.blockChars)} tok · ${pct}% of ${p.budget}c budget`,
+    `  this epoch     ${p.reason} epoch since ${p.at} (${ago(p.at)}) · rode ${st.epochRequests} request(s)`,
+    `  session        ${st.requests} request(s) · ${fmtCount(st.cumChars)}c ≈ ${fmtCount(estTok(st.cumChars))} tok rode · abstained ${st.abstained}`,
+  ];
+}
+
+export function cacheLines(p: StatusPayload): string[] {
+  const st = p.stats ?? emptyStats();
+  const inv =
+    st.invalidations === 0
+      ? "  invalidations  0 this session"
+      : `  invalidations  ${st.invalidations} this session · last ${
+          st.lastInvalidation ? `${st.lastInvalidation.at.slice(11, 19)} (${st.lastInvalidation.reason})` : "-"
+        }`;
+  const rate = cacheRate(p.measured);
+  const measured = rate
+    ? `  measured       last turn ${fmtCount(rate.read)}/${fmtCount(rate.prompt)} prompt tok cache-read (${rate.pct}%)`
+    : "  measured       not measured yet — no completed assistant turn";
+  return [inv, `  recomputes     ${p.recomputes} since server start (all sessions)`, measured];
+}
+
+/**
+ * Plain-text rendering shared by the memory_status tool (and any other chat
+ * client). Sections match the terminal /memory panel one-for-one.
+ */
+export function renderMemoryReport(input: {
+  status: StatusPayload | null;
+  store: StoreCounts;
+  blocked: BlockedRow[];
+}): string {
+  const { status, store, blocked } = input;
+  const out: string[] = ["MEMORY STATUS", ""];
+
+  if (!status) {
+    out.push(
+      "CONTEXT",
+      "  no epoch yet — memory has not injected this session (fresh server, or no prompt scored yet)",
+    );
+  } else {
+    out.push("CONTEXT", ...contextLines(status));
+    out.push("", "CACHE", ...cacheLines(status));
+    out.push("", "INJECTED BLOCK (verbatim)");
+    if (status.block) out.push(...status.block.split("\n").map((l) => `  ${l}`));
+    else
+      out.push(
+        "  abstained — your prompt shares no content vocabulary with any memory, so nothing was injected (by design, no noise).",
+      );
+  }
+
+  out.push("", "RECENT BLOCKED WRITES");
+  if (!blocked.length) out.push("  (none today or yesterday)");
+  for (const b of blocked) {
+    out.push(`  ${b.ts}  session ${b.sid}  ${b.reason}`);
+  }
+  out.push("  (reasons are logged via memory_evidence; the gate never deletes — it asks for a rephrase)");
+
+  out.push(
+    "",
+    "STORE",
+    `  ${store.active} active · ${store.superseded} superseded · ${store.open} open · ${store.scopes} scopes`,
+  );
+  out.push("", "Terminal (CLI/TUI) users: /memory opens this as a live panel; the footer shows a one-line badge.");
+  return out.join("\n");
+}

package/src/tui.tsx

@@ -0,0 +1,295 @@
+// Terminal surface for opencode-self-improvement (the CLI/TUI half of the
+// plugin). Runs in the terminal process, beside the host's OpenTUI renderer:
+// a one-line footer badge (what is in my context + is the cache healthy), a
+// /memory session panel, and toasts when a write gets blocked. All data comes
+// from the per-session status hand-off the server plugin writes (src/status.ts)
+// plus the evidence log — plain file reads, no model, no network. The badge
+// reads ONLY its own session's file: a missing file renders "mem -" rather
+// than another session's epoch. Against a REMOTE server the panel reports that
+// status is local-only (the RPC surface is the follow-up).
+import { watch, type FSWatcher } from "node:fs";
+import { For, Show, createSignal } from "solid-js";
+import { Plugin, usePlugin } from "@opencode/plugin/tui";
+import type { PanelInput } from "@opencode/plugin/tui/context";
+import { memoryRoot, evidenceDir } from "./config.ts";
+import {
+  blockedRecent,
+  cacheHealth,
+  cacheRate,
+  cacheLines,
+  contextLines,
+  readStatus,
+  statusDir,
+  type BlockedRow,
+  type CacheHealth,
+  type StatusPayload,
+} from "./status.ts";
+
+const PANEL = "self-improvement.memory";
+const POLL_MS = 5000;
+
+function age(iso?: string): string {
+  if (!iso) return "-";
+  const ms = Date.now() - new Date(iso).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return "now";
+  const m = Math.floor(ms / 60_000);
+  if (m < 1) return "just now";
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+function Section(props: { t: string }) {
+  const context = usePlugin();
+  return <text fg={context.theme.text.base}>{"\n▍ " + props.t}</text>;
+}
+
+export default Plugin.define({
+  id: "self-improvement.tui",
+  setup(context) {
+    const notifyBlocked = context.options?.notifyBlocked !== false;
+    const [status, setStatus] = createSignal<StatusPayload | null>(null);
+    const [blocked, setBlocked] = createSignal<BlockedRow[]>([]);
+    let seenBlockKeys: Set<string> | null = null; // null until first poll (no startup toast storm)
+    // The session whose status file we render. Fed by slot inputs (the
+    // prompt.footer receives the active session; the panel its own).
+    let activeSid: string | undefined;
+
+    // Dot colors: theme semantic colors when the host provides them, stable
+    // hex fallbacks otherwise. Resolved once per setup.
+    const th = context.theme as unknown as Record<string, any>;
+    const col = (v: unknown, fallback: string): string => (typeof v === "string" ? v : fallback);
+    const DOT: Record<CacheHealth, string> = {
+      green: col(th.success, "#4ade80"),
+      recent: col(th.warning, "#fbbf24"),
+      amber: col(th.warning, "#fbbf24"),
+      red: col(th.error, col(th.danger, "#f87171")),
+      unknown: col(th.text?.muted, col(th.text?.base, "#9ca3af")),
+    };
+
+    // Inline color inside <text> must be a <span> (a nested <text> crashes:
+    // add() only accepts strings / TextNodeRenderable / StyledText), and the
+    // reconciler's setProperty only honors `style` on text nodes — a direct
+    // fg attribute is silently dropped. SpanProps types style as {} (upstream
+    // gap), so pass a pre-typed object: assignment skips the excess-prop
+    // check, and runtime reads style.fg/style.bg.
+    const spanStyle = (fg: string): { fg?: string } => ({ fg });
+
+    const refresh = async (sid?: string): Promise<void> => {
+      if (sid !== undefined) activeSid = sid;
+      setStatus(await readStatus(activeSid));
+      const rows = await blockedRecent(8);
+      setBlocked(rows);
+      const keys = new Set(rows.map((r) => `${r.ts}|${r.reason}`));
+      if (notifyBlocked && seenBlockKeys) {
+        for (const r of rows) {
+          if (seenBlockKeys.has(`${r.ts}|${r.reason}`)) continue;
+          context.ui.toast.show({
+            title: "memory blocked",
+            message: `${r.reason} — run /memory for the reason list`,
+            variant: "warning",
+            duration: 6000,
+            sessionID: r.sid,
+          });
+        }
+      }
+      seenBlockKeys = keys;
+    };
+    void refresh();
+
+    // ---- live updates ---------------------------------------------------------
+    // The server rewrites the status files the moment an epoch recomputes or a
+    // measured turn lands; polling made the badge lag up to POLL_MS behind its
+    // own data. Directories watched (TUI and server share this machine by
+    // design; against a remote server there are no files and the badge shows
+    // "mem -" regardless). The poll survives as a fallback: it refreshes the
+    // age display, reattaches watchers after failures, and attaches the
+    // status/ watcher once the server's FIRST write creates the directory.
+    // Debounced because Bun.write can surface as several fs events per write
+    // and prune touches the directory too.
+    let pendingTimer: ReturnType<typeof setTimeout> | undefined;
+    const scheduleRefresh = () => {
+      if (pendingTimer) clearTimeout(pendingTimer);
+      pendingTimer = setTimeout(() => void refresh(), 150);
+    };
+    let rootWatcher: FSWatcher | null = null;
+    let dirWatcher: FSWatcher | null = null;
+    let evWatcher: FSWatcher | null = null;
+    const attach = (make: () => FSWatcher): FSWatcher | null => {
+      try {
+        const w = make();
+        w.on("error", () => {
+          try {
+            w.close();
+          } catch {}
+          if (rootWatcher === w) rootWatcher = null;
+          if (dirWatcher === w) dirWatcher = null;
+          if (evWatcher === w) evWatcher = null;
+        });
+        return w;
+      } catch {
+        return null; // path missing (fresh install) — the poll retries
+      }
+    };
+    const ensureWatchers = () => {
+      if (!rootWatcher) rootWatcher = attach(() => watch(memoryRoot(), scheduleRefresh));
+      if (!dirWatcher) dirWatcher = attach(() => watch(statusDir(), scheduleRefresh));
+      if (!evWatcher) evWatcher = attach(() => watch(evidenceDir(), scheduleRefresh));
+    };
+    ensureWatchers();
+    const timer = setInterval(() => {
+      ensureWatchers();
+      void refresh();
+    }, POLL_MS);
+
+    // ---- badge: budget use + cache health; home footer keeps store size ----
+    context.ui.slot({
+      append: "prompt.footer.status",
+      render: (input) => {
+        // Session switches re-render this slot: adopt the new sid and poll
+        // once immediately so the badge does not wait up to POLL_MS.
+        if (input.sessionID !== undefined && input.sessionID !== activeSid) {
+          activeSid = input.sessionID;
+          void refresh();
+        }
+        const s = status();
+        if (!s) return <text fg={context.theme.text.base}>mem -</text>;
+        const rate = cacheRate(s.measured);
+        return (
+          <text fg={context.theme.text.base}>
+            <span style={spanStyle(DOT[cacheHealth(s)])}>●</span>
+            {` mem ${s.blockChars}/${s.budget}c · cache ${rate ? `${rate.pct}%` : "—"}`}
+          </text>
+        );
+      },
+    });
+    context.ui.slot({
+      append: "home.footer.status",
+      render: () => {
+        const s = status();
+        return <text fg={context.theme.text.base}>{s ? `mem ${s.store.active}` : "mem -"}</text>;
+      },
+    });
+
+    // ---- /memory panel --------------------------------------------------------
+    context.ui.slot({
+      append: "session.panel",
+      render: (panel) => (
+        <Show when={panel.name === PANEL}>
+          <MemoryPanel panel={panel} refresh={refresh} status={status()} blocked={blocked()} />
+        </Show>
+      ),
+    });
+
+    // Command + slash registration on a persistent invisible slot so it exists
+    // while the panel is closed (docs pattern).
+    context.ui.slot({
+      append: "app",
+      render: () => {
+        context.keymap.layer(() => ({
+          mode: "global",
+          commands: [
+            {
+              id: "self-improvement.memory",
+              title: "Memory status panel",
+              group: "Memory",
+              palette: true,
+              slash: { name: "memory" },
+              run: () => {
+                if (!context.ui.panel.open(PANEL)) {
+                  context.ui.toast.show({ message: "the memory panel needs an open session", variant: "info" });
+                }
+              },
+            },
+          ],
+        }));
+        return null;
+      },
+    });
+
+    return () => {
+      clearInterval(timer);
+      if (pendingTimer) clearTimeout(pendingTimer);
+      for (const w of [rootWatcher, dirWatcher, evWatcher]) {
+        try {
+          w?.close();
+        } catch {}
+      }
+    };
+  },
+});
+
+function MemoryPanel(props: {
+  panel: PanelInput;
+  refresh: (sid?: string) => Promise<void>;
+  status: StatusPayload | null;
+  blocked: BlockedRow[];
+}) {
+  const context = usePlugin();
+  context.keymap.layer(() => ({
+    commands: [
+      {
+        id: "self-improvement.memory.refresh",
+        title: "Refresh",
+        bind: "r",
+        run: () => void props.refresh(props.panel.sessionID),
+      },
+      { id: "self-improvement.memory.fullscreen", title: "Fullscreen", bind: "f", run: props.panel.toggleFullscreen },
+    ],
+  }));
+
+  const s = () => props.status;
+  return (
+    <box flexDirection="column" paddingLeft={1} paddingRight={1}>
+      <text fg={context.theme.text.base}>
+        MEMORY — as of {s() ? age(s()!.at) : "never"}
+        {s() ? ` · ${s()!.sessionID}` : ""}
+      </text>
+
+      <Section t="CONTEXT" />
+      <Show
+        when={s()}
+        fallback={<text fg={context.theme.text.base}>  no epoch yet — nothing injected (fresh server, or no prompt scored)</text>}
+      >
+        <For each={contextLines(s()!)}>{(line) => <text fg={context.theme.text.base}>{line}</text>}</For>
+      </Show>
+
+      <Section t="CACHE" />
+      <Show when={s()} fallback={<text fg={context.theme.text.base}>  nothing to report before the first epoch</text>}>
+        <For each={cacheLines(s()!)}>{(line) => <text fg={context.theme.text.base}>{line}</text>}</For>
+      </Show>
+
+      <Section t="INJECTED BLOCK (VERBATIM)" />
+      <Show when={s()}>
+        <Show
+          when={s()!.block}
+          fallback={
+            <text fg={context.theme.text.base}>
+              {"  abstained — your prompt shares no content vocabulary with any memory, so nothing was injected (by design)"}
+            </text>
+          }
+        >
+          <For each={s()!.block.split("\n")}>{(line) => <text fg={context.theme.text.base}>{"  " + line}</text>}</For>
+        </Show>
+      </Show>
+
+      <Section t="RECENT BLOCKED WRITES" />
+      <Show when={props.blocked.length} fallback={<text fg={context.theme.text.base}>  (none today or yesterday)</text>}>
+        <For each={props.blocked}>
+          {(b) => <text fg={context.theme.text.base}>{"  " + b.ts.slice(11, 19) + "  " + b.reason + "  " + b.sid}</text>}
+        </For>
+      </Show>
+
+      <Section t="STORE" />
+      <Show when={s()}>
+        <text fg={context.theme.text.base}>
+          {"  " + (s()?.store.active ?? 0) + " active · " + (s()?.store.superseded ?? 0) + " superseded · " +
+            (s()?.store.open ?? 0) + " open · " + (s()?.store.scopes ?? 0) + " scopes"}
+        </text>
+      </Show>
+
+      <text fg={context.theme.text.base}>{"\n  r refresh · f fullscreen · esc close"}</text>
+    </box>
+  );
+}

package/src/viewer/page.html

@@ -125,20 +125,20 @@
     <textarea id="eContent" placeholder="content"></textarea>
     <input id="eReason" placeholder="reason (required, e.g. corrected after human review)" style="width:100%" title="Reason">
     <div class="btns">
-      <button id="eCancel" class="btn">Cancel</button>
-      <button id="eSave" class="btn primary" title="Saves a new entry and marks this one superseded">Save (snapshot + supersede)</button>
+      <button type="button" id="eCancel" class="btn">Cancel</button>
+      <button type="button" id="eSave" class="btn primary" title="Saves a new entry and marks this one superseded">Save (snapshot + supersede)</button>
     </div>
   </div>
 </div>
 
 <div id="promptModal" class="modal">
   <div class="box card">
-    <h2 id="promptTitle"></h2>
+    <h2 id="promptTitle">Confirm</h2>
     <p id="promptHint" class="muted"></p>
     <textarea id="promptReason" rows="2" placeholder="reason (required)" title="Reason"></textarea>
     <div class="btns">
-      <button id="promptCancel" class="btn">Cancel</button>
-      <button id="promptOk" class="btn primary"></button>
+      <button type="button" id="promptCancel" class="btn">Cancel</button>
+      <button type="button" id="promptOk" class="btn primary">OK</button>
     </div>
   </div>
 </div>

package/src/viewer/server.ts

@@ -28,6 +28,36 @@ function error(msg: string, status = 400): Response {
   return json({ error: msg }, status);
 }
 
+// Binding 127.0.0.1 keeps other machines out, but not other websites open in
+// the user's browser. Two checks close that:
+// - Host must name this viewer. A DNS-rebinding page reaches 127.0.0.1 under
+//   its own hostname, so its requests arrive with a foreign Host.
+// - Writes must be JSON from this viewer's own origin. A cross-site form or
+//   no-cors fetch can POST text/plain without a CORS preflight, and every
+//   memory edited here is injected into the agent's system prompt.
+// A viewer deliberately exposed under another name (OPENCODE_VIEWER_HOST set
+// to a LAN address, a hostname) can list it in OPENCODE_VIEWER_ALLOWED_HOSTS.
+function allowedHostnames(): Set<string> {
+  const extra = (process.env.OPENCODE_VIEWER_ALLOWED_HOSTS ?? "").split(",");
+  const names = ["127.0.0.1", "localhost", "::1", HOST, ...extra]
+    .map((n) => n.trim().toLowerCase())
+    .filter(Boolean)
+    .map((n) => (n.includes(":") && !n.startsWith("[") ? `[${n}]` : n));
+  return new Set(names);
+}
+
+function rejectRequest(req: Request, url: URL, port: number): Response | null {
+  if (!allowedHostnames().has(url.hostname) || (url.port || "80") !== String(port)) {
+    return error("unexpected Host header", 403);
+  }
+  if (req.method === "GET" || req.method === "HEAD") return null;
+  const origin = req.headers.get("origin");
+  if (origin !== null && origin !== url.origin) return error("cross-origin request refused", 403);
+  const type = (req.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+  if (type !== "application/json") return error("content-type must be application/json", 415);
+  return null;
+}
+
 interface Row {
   ts: string;
   type: string;
@@ -86,7 +116,10 @@ export async function startViewer(port: number = PORT): Promise<ViewerServer> {
     hostname: HOST,
     port,
     fetch(req, srv) {
+      // Bun builds req.url from the request's Host header.
       const url = new URL(req.url);
+      const rejected = rejectRequest(req, url, server.port ?? port);
+      if (rejected) return rejected;
       if (url.pathname === "/") {
         return new Response(page, {
           headers: { "content-type": "text/html; charset=utf-8" },

package/tui.ts

@@ -0,0 +1,4 @@
+// Convenience re-export for the loose plugin-discovery layout
+// (<config>/plugins/<name>/index.ts + tui.ts). Package installs resolve
+// "./tui" through package.json exports to src/tui.tsx directly.
+export { default } from "./src/tui.tsx";