opencode-self-improvement 0.2.0 → 0.2.2

package/README.md

@@ -26,6 +26,11 @@ LLMs waste a lot of tokens reading and re-reading your code and asking you for c
   cheap model pass that proposes memory candidates; every candidate still faces
   the same write gates. Off by default, so the install stays zero-token.
 - Automatically de-dupes similar memories and avoids contradictions by searching for existing memories before saving new ones.
+- **Write gates** — every memory passes 4 checks before it sticks: code references are
+  verified against your actual repo, near-duplicates are collapsed, contradictions with
+  superseded memories are rejected. Blocked writes are logged with a reason
+  (`memory_evidence`), and nothing is ever deleted — updates supersede the old row and
+  `memory_undo` rolls back.
 - Automatically looks for insights when you complete the verification gates (tests, linting, etc)
 - Always defaults to memories first before sending a prompt to the LLM, which saves tokens! 
 
@@ -60,6 +65,52 @@ output):
 bun bench/inject-cost.ts
 ```
 
+## Recall quality — no models required
+
+Memory plugins get told "keyword matching isn't good enough," and the usual
+prescription is a vector database or a local embedding model. This plugin ships
+neither — no model, no download, no API key, ever. The question is what that
+actually costs you, so we measured it:
+
+```sh
+bun bench:recall
+```
+
+A deterministic, auditable eval of the **shipped** matcher against classic
+BM25, on query classes assigned by *measured* vocabulary overlap with the
+right memory (store of 200; k=3 = the production injection limit):
+
+| Query, vs. the stored memory | share | R@1 | R@3 |
+| --- | ---: | ---: | ---: |
+| lexical — reuses your project's words | 46% | 100% | 100% |
+| near — reworded, one overlap | 17% | 44% | 83% |
+| strict — zero shared words | 37% | 0% | 0% |
+
+What the benchmark bought us:
+
+- **In-project prompts are overwhelmingly lexical** — you keep saying
+  `bun test`, "the rate limiter", "staging deploys". The shipped matcher
+  nails those: 100% R@3, flat from store size 50 to 500.
+- **It caught a real bug.** Function words ("the", "what", "how") counted as
+  matches, so nearly half the time the top memory was the wrong one. The
+  matcher now ignores them on the query side: wrong-first rate fell 49% → 34%,
+  and classic BM25 — a tuned scoring algorithm — no longer beats the shipped
+  matcher on any class except the hopeless one.
+- **Strict paraphrase is the real lexical wall**, and we won't pretend
+  otherwise. Nothing keyword-side crosses it. So instead of confident noise the
+  matcher now goes *silent* when the vocabulary shares nothing (a third of
+  strict queries inject nothing at all), and the agent's `memory_recall` loop
+  remains as the pull path. Embeddings are the only known crossing — the bench
+  exposes a scorer seam if you want to measure them — but requiring an
+  inference engine just to remember things is a non-starter for a zero-dependency
+  plugin.
+- Caveats, honestly: the dataset is synthetic (52 memories / 105 queries, a
+  fictional project), its class mix is deliberately adversarial (far richer in
+  zero-overlap paraphrases than real prompts), and scoring is single-gold.
+
+Full methodology, all store sizes: `bench/recall-results.md`
+(regenerate with `bun bench:recall`).
+
 ## Quick start
 
 1. Add the plugin to your Opencode config (see install below) and restart Opencode.
@@ -73,13 +124,13 @@ That's it. Rerun `/repo-init force` after a refactor to refresh.
 
 ## How to install
 
-Add a `plugin` entry to your opencode config —
-`~/.config/opencode/opencode.json` (global) or any project `opencode.json`:
+Add a `plugins` entry to your opencode config —
+`~/.config/opencode/opencode.jsonc` (global) or any project `opencode.jsonc`:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-self-improvement@0.1.1"]
+  "plugins": ["opencode-self-improvement@0.2.1"]
 }
 ```
 
@@ -93,7 +144,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.1.1
+opencode plugin add opencode-self-improvement@0.2.1
 opencode plugin update opencode-self-improvement
 ```
 
@@ -106,12 +157,12 @@ cd opencode-self-improvement
 bun install
 ```
 
-Then point the `plugin` entry at the local file instead:
+Then point the `plugins` entry at the local file instead:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["/full/path/to/opencode-self-improvement/index.ts"]
+  "plugins": ["/full/path/to/opencode-self-improvement/index.ts"]
 }
 ```
 
@@ -170,6 +221,36 @@ as `00:11:25.867`, or a unique substring of its text. Omit it to update the newe
 entry of that scope and type. A `query` matching nothing, or matching several rows,
 writes nothing and says so rather than updating the wrong memory.
 
+## Backup & move between machines
+
+`memory_export` writes the live store as JSONL — one JSON object per line
+(`{ts,type,scope,content,status,tags,issue}`), active rows only (superseded
+history stays in the store). `memory_import` reads such a file back. Defaults
+to `<memory-root>/exports/<timestamp>.jsonl`; pass `file` to choose the path
+and `scope` to export just one scope.
+
+In practice you just ask the agent:
+
+```
+Export my memories to ~/memories.jsonl        # memory_export
+# …copy the file to the other machine…
+Import ~/memories.jsonl                       # memory_import
+```
+
+Import is safe by construction: every row re-enters through the same 4-gate
+write pipeline as `memory_remember` (tagged `import`, original tags preserved),
+and the tool reports a tally of four outcomes per line —
+
+| Outcome | Meaning |
+| --- | --- |
+| `promoted` | passed the gates and was stored |
+| `collapsed` | near-duplicate of an existing memory; nothing written |
+| `blocked` | rejected by a gate; reason is in `memory_evidence` |
+| `skipped` | malformed line; never reaches the gates |
+
+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.
+
 ## Admin Tool
 
 Editing and deleting memories is easy!
@@ -180,7 +261,8 @@ Run `bun memory-view` in your terminal and visit  http://127.0.0.1:8787 in your
 
 | Problem | Fix |
 | --- | --- |
-| `memory_*` tools not available | The plugin didn't load. Restart opencode and check the `plugin` entry in your config. |
+| `memory_*` tools not available | The plugin didn't load. Restart opencode and check the `plugins` entry in your config. |
+| `memory_remember` says blocked | A gate rejected the write (stale code reference, a cited `path/to/file.ts` that doesn't exist in the repo, overlap with a superseded memory, or an ambiguous claim). The reason is logged — check `memory_evidence`, then rephrase against current code and retry. |
 | `/repo-init` missing from the command list | The self-install couldn't write to `~/.config/opencode/commands/` (e.g. read-only config dir). Create it, restart, or just ask the model to "init memory for this repo" — it calls the same tool. |
 | Init says `Graph: unavailable` | `codebase-memory-mcp` couldn't start (not installed, or its once-only download is blocked). Install pinned `0.11.0` via the one-liner above, or point `OPENCODE_CBM_BIN` at the binary. Scripts are still remembered without it. |
 | Stale plugin after an update | Bump the pinned version in the `plugin` entry (or `opencode plugin update opencode-self-improvement` on v2) and restart opencode. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-self-improvement",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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": {
@@ -50,6 +50,7 @@
     "test": "bun test",
     "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"
   }
 }

package/src/gates.ts

@@ -440,6 +440,14 @@ export async function runWriteGate(
   if (g1.candidateStale) {
     blockReason = "drift_ref_stale_incoming";
     blockFlags = ["incoming_embeds_pre_drift_ref"];
+  } else if (g1.missingPaths.length && !planningObject) {
+    // A settled claim about code must point at files that exist. Live demo
+    // 2026-10-20: a memory citing src/ghost_pipeline_removed.ts (never existed)
+    // was promoted on trust. Open planning threads are exempt — plans routinely
+    // cite files not yet created.
+    blockReason = "ref_path_missing";
+    blockFlags = [`missing=${g1.missingPaths.join(",")}`];
+    hint = `Path ref(s) not found in the repo: ${g1.missingPaths.join(", ")}. Rephrase against the current tree (drop the path or fix it) and retry; use status="open" if the file is planned, not existing.`;
   } else if (canon && !canon.aligns) {
     blockReason = "conflicts_with_canonical";
     blockFlags = [

package/src/index.ts

@@ -11,7 +11,7 @@
 // the note on `plugin` below). All business logic still lives in the decoupled
 // helper modules.
 import type { Cleanup, Plugin } from "@opencode/plugin/promise/plugin";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { evidenceDir, injectBudget, memoryRoot, dateStr } from "./config.ts";
 import { STATUSES, TYPES } from "./types.ts";
 import {
@@ -375,16 +375,34 @@ const impl = {
 
       editor.add({
         name: "memory_undo",
-        description: "List memory snapshots, or restore one by name (rollback).",
+        description:
+          "List memory snapshots, or restore one (rollback). SAFE BY DEFAULT: daily store files are shared across sessions, so if the current file has rows added or edited since the snapshot, restore REFUSES and lists them — re-run with merge=true to restore AND keep those rows, or force=true for the exact rollback. `snapshot` accepts a bare name from the list or a full path.",
         options: direct,
         input: obj({
           list: withDesc(bool(), "List snapshots"),
-          snapshot: withDesc(str(), "Snapshot file to restore"),
+          snapshot: withDesc(str(), "Snapshot to restore (bare name from list, or a full path)"),
+          merge: withDesc(bool(), "With snapshot: keep rows written after the snapshot instead of refusing"),
+          force: withDesc(bool(), "With snapshot: exact rollback even if the file changed since"),
         }),
         async execute(args: any): Promise<{ content: string }> {
           if (args.snapshot) {
-            const target = await restoreSnapshot(args.snapshot, memoryRoot());
-            return { content: `Restored ${args.snapshot} -> ${target}` };
+            const mode = args.force ? "force" : args.merge ? "merge" : "check";
+            const res = await restoreSnapshot(args.snapshot, memoryRoot(), mode);
+            if (!res.restored) {
+              const parts = [...res.concurrentAdded, ...res.concurrentChanged];
+              return {
+                content:
+                  `Undo refused: ${res.concurrentAdded.length} row(s) added and ` +
+                  `${res.concurrentChanged.length} changed since this snapshot — restoring it ` +
+                  `would clobber them. Divergent rows (ts): ${parts.join(", ")}. ` +
+                  `If those belong to another session, re-run with merge=true (restore the file ` +
+                  `AND keep them); if they are the writes you are undoing, use force=true.`,
+              };
+            }
+            const kept = res.mode === "merge" && (res.concurrentAdded.length || res.concurrentChanged.length)
+              ? ` Kept ${res.concurrentAdded.length} added / ${res.concurrentChanged.length} changed row(s) written after the snapshot.`
+              : "";
+            return { content: `Restored ${basename(res.target)} from ${res.mode} snapshot -> ${res.target}.${kept}` };
           }
           const snaps = await listSnapshots();
           if (!snaps.length) return { content: "No snapshots" };

package/src/inject.ts

@@ -43,15 +43,29 @@ function argText(args: unknown): string {
   return "";
 }
 
-function words(text: string): string[] {
+export function words(text: string): string[] {
   return text
     .toLowerCase()
     .split(/[^a-z0-9_]+/)
     .filter((t) => t.length > 2);
 }
 
-function scoreMemories(term: string, mems: Memory[], limit: number): Memory[] {
-  const query = new Set(words(term));
+// Query-side stopwords: bag-of-words scoring has no IDF, so "the/what/how"
+// match a large share of every memory and let a query with ZERO content
+// overlap rank (recall bench 2026-10-20 measured 49% wrong-top-1). Dropping
+// them makes the matcher abstain — inject nothing — when the vocabulary
+// genuinely has nothing in common, instead of injecting confident noise.
+// Memory-side tokens are never filtered: a memory stating "the" must not
+// gain or lose rank from it, only queries drive matching.
+const QUERY_STOPWORDS = new Set(
+  "a an and are at be but by can did do does for from had has have how i in into is it its me my no not of on or our so than that the their them then there these they this to us was we were what when where which who why will with you your run runs getting want needs right back yet also just still ever".split(" "),
+);
+
+// Production relevance ranking: score = number of distinct query tokens the
+// memory's (scope+type+content) token set contains. Exported for
+// bench/recall-quality.ts — the benchmark must measure the shipped matcher.
+export function scoreMemories(term: string, mems: Memory[], limit: number): Memory[] {
+  const query = new Set(words(term).filter((t) => !QUERY_STOPWORDS.has(t)));
   if (!query.size) return [];
   return mems
     .map((m) => {
@@ -147,18 +161,23 @@ export async function storeVersion(): Promise<string> {
 }
 
 // Trim an injection block to `budget` characters at WHOLE-line boundaries:
-// keep lines while the joined length stays <= budget, drop the rest, never cut
-// mid-line. Returns "" when even the header line exceeds the budget (the block
-// is not worth injecting).
+// keep every line that still fits (skipping over-long ones), never cut
+// mid-line. Returns "" when even the header line exceeds the budget, and ""
+// when NOTHING but header lines survived — a dangling "## Relevant durable
+// memory" over zero memories is noise, not memory (bug seen live: a store
+// whose top matches all exceed the budget injected exactly the 26-char header).
 export function capToBudget(block: string, budget: number): string {
-  const kept: string[] = [];
-  let len = 0;
-  for (const line of block.split("\n")) {
-    const add = kept.length ? line.length + 1 : line.length;
-    if (len + add > budget) break;
+  const lines = block.split("\n");
+  // The header gives the block its meaning; if it does not fit, nothing does.
+  if (lines[0].length > budget) return "";
+  const kept: string[] = [lines[0]];
+  let len = lines[0].length;
+  for (const line of lines.slice(1)) {
+    if (len + line.length + 1 > budget) continue; // skip over-long lines, keep scanning
     kept.push(line);
-    len += add;
+    len += line.length + 1;
   }
+  if (kept.every((l) => l.startsWith("## "))) return "";
   return kept.join("\n");
 }
 

package/src/memory.ts

@@ -263,12 +263,20 @@ export interface DeletedMemory {
 // restore it. Returns the snapshot paths keyed by original file.
 export async function snapshotFiles(files: string[]): Promise<string[]> {
   await ensureDir(snapshotDir());
-  const stamp = Date.now();
+  let stamp = Date.now();
   const snaps: string[] = [];
   for (const file of files) {
     const f = Bun.file(file);
     if (!(await f.exists())) continue;
-    const snap = join(snapshotDir(), `${stamp}-${basename(file)}`);
+    // Names must be unique. A `${Date.now()}-` stamp collides whenever two
+    // mutations happen in the same millisecond — live CI proved a viewer
+    // restore's backup overwrote the very snapshot it was about to read,
+    // restoring post-edit content. Bump until free; never clobber a snapshot.
+    let snap = join(snapshotDir(), `${stamp}-${basename(file)}`);
+    while (await Bun.file(snap).exists()) {
+      stamp++;
+      snap = join(snapshotDir(), `${stamp}-${basename(file)}`);
+    }
     await Bun.write(snap, await f.text());
     snaps.push(snap);
   }

package/src/resolver.ts

@@ -26,6 +26,10 @@ export interface Gate1Result {
   resolved: string[];
   drift: DriftInfo | null;
   candidateStale: boolean;
+  // Directory-qualified path refs that do NOT exist under liveRoot. A settled
+  // claim citing one is hallucinated or machine-specific data (live demo
+  // 2026-10-20: src/ghost_pipeline_removed.ts passed on trust).
+  missingPaths: string[];
 }
 
 export function balancedParen(text: string, openIdx: number): { inner: string; end: number } | null {
@@ -54,6 +58,30 @@ export function balancedParen(text: string, openIdx: number): { inner: string; e
 
 const CALL_RE = /([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+)\s*\(/g;
 
+// Last dotted segment is a known file extension: `package.json(committed by…)`
+// is a file reference followed by parenthetical prose, not a call to a method
+// named `json`. This class produced 9 false drift_ref_stale_incoming blocks in
+// live use before the guard existed.
+const FILE_EXT = new Set([
+  "json", "jsonc", "jsonl", "logfmt", "md", "mdx", "ts", "tsx", "js", "jsx",
+  "mjs", "cjs", "py", "go", "rs", "rb", "java", "kt", "sh", "bash", "zsh",
+  "yaml", "yml", "toml", "ini", "conf", "cfg", "txt", "csv", "html", "htm",
+  "css", "scss", "xml", "sql", "tf", "lock", "log", "env",
+]);
+
+// Parenthetical PROSE is not a code call signature. A code-like arg list is
+// empty or contains code punctuation ({ } ( ) : = , . < > quotes); the markers
+// [ ] @ / never appear in the arg snippets drift detection cares about, and
+// bare multi-word English with no code punctuation ("main-agent review fix")
+// is prose.
+function looksProseArgs(inner: string): boolean {
+  const s = inner.trim();
+  if (!s) return false;
+  if (/[[\]@/]/.test(s)) return true;
+  if (/[{}():=",.<>'"`]/.test(s)) return false;
+  return s.split(/\s+/).length >= 2;
+}
+
 export function extractCallForms(content: string): CallForm[] {
   const forms: CallForm[] = [];
   CALL_RE.lastIndex = 0;
@@ -65,6 +93,8 @@ export function extractCallForms(content: string): CallForm[] {
     if (!paren) continue;
     const parts = symbol.split(".");
     const name = parts[parts.length - 1];
+    if (FILE_EXT.has(name.toLowerCase())) continue;
+    if (looksProseArgs(paren.inner)) continue;
     const ownerPath = parts.slice(0, -1).join(".");
     forms.push({
       symbol,
@@ -83,6 +113,43 @@ export function extractPathRefs(content: string): string[] {
   return [...content.matchAll(PATH_RE)].map((m) => m[0]);
 }
 
+// Directory-qualified, repo-relative path refs whose existence gate1 can check
+// against liveRoot. Skipped: bare names (`undo.ts` may live anywhere),
+// absolute paths and `..` (another checkout's truth), URLs (`//`), and refs
+// whose match starts just after `$` or `~` — env vars and home paths describe
+// another machine, e.g. in `$BUILD_ROOT/src/a.ts` the regex match is
+// `BUILD_ROOT/src/a.ts`, which the preceding-char check drops.
+export function checkablePathRefs(content: string): string[] {
+  const out: string[] = [];
+  for (const m of content.matchAll(PATH_RE)) {
+    const ref = m[0].replace(/:\d+$/, "");
+    const prev = m.index && m.index > 0 ? content[m.index - 1] : "";
+    if (prev === "$" || prev === "~" || prev === "/") continue;
+    if (!ref.includes("/")) continue;
+    if (ref.includes("//") || ref.startsWith("/") || ref.split("/").includes("..")) continue;
+    // A dotted first segment reads as a hostname (opencode.ai/x/index.ts), not
+    // a repo directory. `.` itself is the legitimate relative root prefix.
+    const first = ref.split("/")[0];
+    if (first.includes(".") && first !== ".") continue;
+    if (!out.includes(ref)) out.push(ref);
+  }
+  return out;
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    // A listing that yields even one entry proves liveRoot is a real tree;
+    // a missing path throws ENOENT/ENOTDIR and fails open (nothing verifiable).
+    for (const _ of new Bun.Glob("*").scanSync({ onlyFiles: false, cwd: path })) {
+      void _;
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 function splitTopLevel(argsText: string): string[] {
   const parts: string[] = [];
   let depth = 0;
@@ -258,11 +325,21 @@ export async function gate1(input: ResolveInput): Promise<Gate1Result> {
   const forms = extractCallForms(input.content);
   const pathRefs = extractPathRefs(input.content);
   const refs = forms.length + pathRefs.length;
-  if (refs === 0) return { refs: 0, resolved: [], drift: null, candidateStale: false };
+  if (refs === 0) return { refs: 0, resolved: [], drift: null, candidateStale: false, missingPaths: [] };
 
   let drift: DriftInfo | null = null;
   const resolved: string[] = [];
 
+  // Existence check for repo-relative path refs. When liveRoot is not a real
+  // tree (unit tests, deleted worktree) nothing is verifiable, so report no
+  // missing paths rather than flagging everything.
+  const missingPaths: string[] = [];
+  if (await isDirectory(input.liveRoot)) {
+    for (const ref of checkablePathRefs(input.content)) {
+      if (!(await Bun.file(join(input.liveRoot, ref)).exists())) missingPaths.push(ref);
+    }
+  }
+
   for (const form of forms) {
     resolved.push(form.symbol);
     const live = await findLiveCall(form.name, form.fileHint, input.liveRoot);
@@ -294,5 +371,6 @@ export async function gate1(input: ResolveInput): Promise<Gate1Result> {
     resolved,
     drift,
     candidateStale: drift?.source === "candidate",
+    missingPaths,
   };
 }

package/src/undo.ts

@@ -1,5 +1,14 @@
 // Snapshot/rollback (/undo analog). Snapshots are written by memory.ts before
 // any mutation; restore copies one back over its original file.
+//
+// Daily logfmt files are SHARED across concurrent sessions, so a naive
+// whole-file write can silently clobber rows another session appended after
+// the snapshot (live data loss observed 2026-10-20). Restore is therefore
+// conflict-aware. The snapshot cannot tell "rows I added since the snapshot,
+// which undo should remove" apart from "rows another session added, which
+// must survive" — that call belongs to the caller, so the default mode CHECK
+// refuses and lists the divergent rows; MERGE replays them on top of the
+// snapshot; FORCE is the old exact rollback.
 import { join, basename } from "node:path";
 import { snapshotDir } from "./config.ts";
 import { ensureDir } from "./logfmt.ts";
@@ -30,15 +39,78 @@ export async function listSnapshots(): Promise<SnapshotInfo[]> {
   return out.sort((a, b) => b.mtime - a.mtime);
 }
 
+export type RestoreMode = "check" | "merge" | "force";
+
+export interface RestoreResult {
+  target: string;
+  restored: boolean;
+  mode: RestoreMode;
+  // ts of rows present in the CURRENT file but absent from the snapshot
+  // (added after it — or in-place edits, listed under their original ts).
+  concurrentAdded: string[];
+  concurrentChanged: string[];
+}
+
+// Rows are keyed by their ts= field; unparseable lines key on the whole line.
+function rowKey(line: string): string {
+  return line.match(/^ts=(\S+)/)?.[1] ?? line;
+}
+
+function rows(text: string): string[] {
+  return text.split("\n").filter((l) => l.trim());
+}
+
 // Restore `snapshot` over its original file. The snapshot name is
-// `<stamp>-<original>.logfmt`; strip the stamp to recover the target.
-export async function restoreSnapshot(snapshot: string, memoryRootDir: string): Promise<string> {
-  const f = Bun.file(snapshot);
-  if (!(await f.exists())) throw new Error(`snapshot not found: ${snapshot}`);
+// `<stamp>-<original>.logfmt`; strip the stamp to recover the target. A bare
+// name (as printed by the list) resolves against <memory-root>/snapshots/.
+export async function restoreSnapshot(
+  snapshot: string,
+  memoryRootDir: string,
+  mode: RestoreMode = "check",
+): Promise<RestoreResult> {
   const name = basename(snapshot);
+  let snapPath = snapshot;
+  if (!(await Bun.file(snapPath).exists())) {
+    const candidate = join(memoryRootDir, "snapshots", name);
+    if (await Bun.file(candidate).exists()) snapPath = candidate;
+  }
+  const f = Bun.file(snapPath);
+  if (!(await f.exists())) throw new Error(`snapshot not found: ${snapshot}`);
+
   const original = name.replace(/^\d+-/, "");
   const target = join(memoryRootDir, original);
+  const snapLines = rows(await f.text());
+  const cur = Bun.file(target);
+  const curLines = (await cur.exists()) ? rows(await cur.text()) : [];
+
+  const snapByKey = new Map(snapLines.map((l) => [rowKey(l), l]));
+  const concurrentAdded: string[] = [];
+  const concurrentChanged: string[] = [];
+  const curByKey = new Map<string, string>();
+  for (const l of curLines) {
+    const k = rowKey(l);
+    curByKey.set(k, l);
+    const s = snapByKey.get(k);
+    if (s === undefined) concurrentAdded.push(k);
+    else if (s !== l) concurrentChanged.push(k);
+  }
+
+  if (mode === "check" && (concurrentAdded.length || concurrentChanged.length)) {
+    return { target, restored: false, mode, concurrentAdded, concurrentChanged };
+  }
+
+  let out = snapLines;
+  if (mode === "merge") {
+    // Keep the CURRENT version of rows the snapshot also has (in-place edits —
+    // e.g. a supersede stamp — made after the snapshot win), then append the
+    // rows the snapshot never saw. Merge is a deliberate superset: rows the
+    // snapshotter wrote after the snapshot are NOT dropped here; choose FORCE
+    // for that.
+    out = snapLines.map((l) => curByKey.get(rowKey(l)) ?? l).concat(
+      curLines.filter((l) => !snapByKey.has(rowKey(l))),
+    );
+  }
   await ensureDir(memoryRootDir);
-  await Bun.write(target, await f.text());
-  return target;
+  await Bun.write(target, out.length ? out.join("\n") + "\n" : "");
+  return { target, restored: true, mode, concurrentAdded, concurrentChanged };
 }

package/src/viewer/server.ts

@@ -9,7 +9,7 @@ import { serve, type Server } from "bun";
 import { deletionsFile, memoryRoot, snapshotDir } from "../config.ts";
 import { blockedEntries } from "../blocklist.ts";
 import { listSnapshots, restoreSnapshot } from "../undo.ts";
-import { appendMemory, loadAll, memoryFiles } from "../memory.ts";
+import { appendMemory, loadAll, memoryFiles, snapshotFiles } from "../memory.ts";
 import { parseLine, readLines } from "../logfmt.ts";
 import { deleteMemory, editMemory, addBlock, removeBlock, type MutationResult } from "./mutate.ts";
 
@@ -180,8 +180,17 @@ async function restoreEntryRoute(body: Record<string, unknown>): Promise<Respons
 }
 
 async function restoreRoute(body: Record<string, unknown>): Promise<Response> {
-  const target = await restoreSnapshot(join(snapshotDir(), String(body.name ?? "")), memoryRoot());
-  return json({ restored: target });
+  const name = String(body.name ?? "");
+  const original = name.replace(/^\d+-/, "");
+  // Explicit human admin action: exact rollback — but the rollback is itself
+  // rollback-able. Snapshot the current file first so concurrent-session rows
+  // lost here stay recoverable, and report how many rows were rolled back.
+  await snapshotFiles([join(memoryRoot(), original)]);
+  const res = await restoreSnapshot(join(snapshotDir(), name), memoryRoot(), "force");
+  return json({
+    restored: res.target,
+    rolledBack: res.concurrentAdded.length + res.concurrentChanged.length,
+  });
 }
 
 if (import.meta.main) {