kaizen-agent 1.8.1 → 1.9.1

package/README.md

@@ -302,6 +302,16 @@ serves, the board opens on every project, or on the one picked last time in that
 detached so it outlives the terminal (pid kept in `~/.kaizen/web.pid`); `--stop` ends it. `kaizen web --shortcut` adds a launcher
 the OS can find — Spotlight on macOS, the app menu on Linux, a Desktop shortcut on Windows. Each one starts the board in the background (`--daemon`) and opens it; `kaizen web --stop` ends it.
 
+**A notebook beside the board.** The note icon in the board's header opens
+`/notebook`: markdown notes for the project, kept as plain files in `.kaizen/notes/`
+(folders included, so Obsidian can open the same folder). Notes are edited in place —
+the line you are on shows its markdown, the rest reads typeset, and `/` at the start of a line offers checkboxes, dividers, headings and the other blocks. `[[Other note]]` links
+notes and creates the one that does not exist yet, every note lists what links to it,
+`#tags` filter the list, and a `/` in a note's name puts it in a folder. Notes save as
+you type; a note changed elsewhere since you opened it is never overwritten without
+asking, and a deleted one goes to `.kaizen/notes/.trash/`. Notes link to the board too: `[[run:<id>#finding-2]]`, a tab (`#review`, `#backlog`), a backlog item (`#backlog-3`) or `[[idea:…]]` show as chips that open the board on that item, and a run's Notes tab lists the notes that link to it. The editor is CodeMirror,
+bundled into the package, so the notebook works offline.
+
 **Dictate instead of type.** Every text field on the board — a new idea, its notes, an
 edit, a reject reason, a note on a run — has a mic. Press it, talk, press it again; the
 words land at the caret next to whatever you had typed. Recognition is Whisper running

package/cli/build-web.ts

@@ -0,0 +1,27 @@
+// `bun run build:web`: bundles the notebook's script and CodeMirror into
+// web/notebook.js, which is committed, so an install or a checkout serves it with no
+// install step and no network. The first line is a hash of what it was built from;
+// cli/notes.test.ts fails when the committed file no longer matches.
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+const root = dirname(import.meta.dir);
+const SOURCES = ["web/notebook.ts", "web/notes-lib.ts"];
+export const OUT = join(root, "web", "notebook.js");
+
+// The sources and the exact dependency versions: a CodeMirror bump is a rebuild too.
+export function sourceHash() {
+  const h = createHash("sha256");
+  for (const f of SOURCES) h.update(readFileSync(join(root, f), "utf8").replace(/\r\n/g, "\n"));
+  h.update(JSON.stringify(JSON.parse(readFileSync(join(root, "package.json"), "utf8")).devDependencies ?? {}));
+  return h.digest("hex").slice(0, 16);
+}
+export const banner = () => `/* kaizen notebook ${sourceHash()} -- generated by bun run build:web from web/notebook.ts; do not edit */`;
+
+if (import.meta.main) {
+  const r = await Bun.build({ entrypoints: [join(root, "web", "notebook.ts")], target: "browser", minify: true });
+  if (!r.success) { for (const l of r.logs) console.error(l); process.exit(1); }
+  writeFileSync(OUT, banner() + "\n" + await r.outputs[0]!.text());
+  console.log(`  web/notebook.js  ${(Bun.file(OUT).size / 1024).toFixed(0)} KB`);
+}

package/cli/install.ts

@@ -279,7 +279,6 @@ if (wantWeb) {
   const port = at !== -1 ? Number(Bun.argv[at + 1]) || undefined : undefined;
   const url = `http://127.0.0.1:${port ?? 7420}/`;
   const pidFile = join(home, ".kaizen", "web.pid");
-  const alive = async () => { try { await fetch(url); return true; } catch { return false; } };
 
   if (args.has("--stop")) {
     // The pid file only knows a --daemon; a board started from the shortcut or a
@@ -300,7 +299,10 @@ if (wantWeb) {
   if (args.has("--daemon")) {
     // The daemon is this same command, detached, with the browser left to us:
     // ignored stdio is what lets it outlive the terminal.
-    if (await alive()) {
+    // A board running an older kaizen is not "already running": the child finds
+    // it on the port and replaces it (web() in web.ts).
+    const { current } = await import("./web.ts");
+    if (await current(url)) {
       console.log(`  kaizen web already running at ${url}`);
     } else {
       const argv = Bun.argv.slice(2).filter((a) => a !== "--daemon" && a !== "--no-open");
@@ -310,8 +312,8 @@ if (wantWeb) {
       child.unref();
       mkdirSync(dirname(pidFile), { recursive: true });
       writeFileSync(pidFile, String(child.pid));
-      for (let i = 0; i < 30 && !(await alive()); i++) await Bun.sleep(100);
-      if (!(await alive())) { console.log(`  kaizen web did not come up on ${url}`); process.exit(1); }
+      for (let i = 0; i < 30 && !(await current(url)); i++) await Bun.sleep(100);
+      if (!(await current(url))) { console.log(`  kaizen web did not come up on ${url}`); process.exit(1); }
       console.log(`\n  kaizen web  ${url}  (pid ${child.pid}, detached)`);
       console.log(`  kaizen web --stop to stop it\n`);
     }

package/cli/notes.test.ts

@@ -0,0 +1,221 @@
+// The notebook: file safety in cli/notes.ts, the text rules in web/notes-lib.ts, and
+// the two things that drift silently — the copied design tokens and the committed bundle.
+import { test, expect, beforeEach } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, utimesSync, symlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { safeName, listNotes, saveNote, renameNote, deleteNote, boardIndex, linksTo } from "./notes.ts";
+import { wikilinks, tags, resolve, safeUrl, tree, uncode, freshName, parseTable, boardLink, resolveRun, anchorWords } from "../web/notes-lib.ts";
+import { sourceHash, OUT } from "./build-web.ts";
+
+let state = "";
+beforeEach(() => { state = join(mkdtempSync(join(tmpdir(), "kaizen-notes-")), ".kaizen"); mkdirSync(state); });
+const root = dirname(import.meta.dir);
+
+test("safeName: folders allowed, nothing that leaves notes/", () => {
+  expect(safeName("Work/Standup")).toBe("Work/Standup");
+  expect(safeName("  Idea.md ")).toBe("Idea");
+  expect(safeName(" a / b ")).toBe("a/b");
+  for (const bad of ["", "../x", "a/../../b", ".hidden", "a/.b", "/etc/passwd", "a\\b", "C:x", "a//b", "a/", "x\ny", "1/2/3/4/5/6/7", "x".repeat(121), 7, null])
+    expect(safeName(bad as string)).toBeNull();
+});
+
+test("every write route refuses a name outside notes/, and writes nothing", () => {
+  for (const bad of ["../escape", "a/../../escape", "/tmp/escape"]) {
+    expect(saveNote(state, bad, "x", 0)).toEqual({ ok: false, why: "bad name" });
+    expect(renameNote(state, bad, "ok")).toBe("bad name");
+    expect(deleteNote(state, bad)).toBe("bad name");
+  }
+  saveNote(state, "ok", "x", 0);
+  expect(renameNote(state, "ok", "../../escape")).toBe("bad name");
+  expect(readdirSync(dirname(state)).sort()).toEqual([".kaizen"]);
+  expect(readdirSync(state)).toEqual(["notes"]);
+});
+
+test("save: creates folders, then refuses a stale base and returns what is on disk", () => {
+  const a = saveNote(state, "Work/Standup", "one", 0);
+  expect(a.ok).toBe(true);
+  if (!a.ok) return;
+  expect(readFileSync(join(state, "notes", "Work", "Standup.md"), "utf8")).toBe("one");
+  // Created twice: the second is a conflict, not an overwrite.
+  expect(saveNote(state, "Work/Standup", "again", 0).ok).toBe(false);
+  // Someone else writes it.
+  const f = join(state, "notes", "Work", "Standup.md");
+  writeFileSync(f, "theirs"); utimesSync(f, new Date(), new Date(Date.now() + 5000));
+  const c = saveNote(state, "Work/Standup", "mine", a.mtime);
+  expect(c).toMatchObject({ ok: false, why: "conflict", text: "theirs" });
+  expect(readFileSync(f, "utf8")).toBe("theirs");
+  // Saving over what is there now works.
+  if (!c.ok && c.mtime) expect(saveNote(state, "Work/Standup", "mine", c.mtime).ok).toBe(true);
+  expect(readFileSync(f, "utf8")).toBe("mine");
+  // A note deleted elsewhere, saved with an old base: a conflict with nothing there.
+  expect(saveNote(state, "Gone", "x", 123)).toMatchObject({ ok: false, why: "conflict", text: "" });
+});
+
+test("save keeps the text byte for byte, CRLF included", () => {
+  const text = "# T\r\n\r\n- [ ] a\r\n\ttab  \r\n";
+  saveNote(state, "crlf", text, 0);
+  expect(readFileSync(join(state, "notes", "crlf.md"), "utf8")).toBe(text);
+});
+
+test("list: recursive, newest first, dot folders skipped", () => {
+  saveNote(state, "a", "A", 0);
+  saveNote(state, "Work/b", "B", 0);
+  const later = join(state, "notes", "Work", "b.md"); utimesSync(later, new Date(), new Date(Date.now() + 5000));
+  mkdirSync(join(state, "notes", ".obsidian")); writeFileSync(join(state, "notes", ".obsidian", "x.md"), "no");
+  writeFileSync(join(state, "notes", "skip.txt"), "no");
+  expect(listNotes(state).map((n) => n.name)).toEqual(["Work/b", "a"]);
+  expect(listNotes(join(state, "nothing"))).toEqual([]);
+});
+
+test("list: only names the notebook can save back; a symlinked folder once, never a loop", () => {
+  const n = join(state, "notes");
+  saveNote(state, "ok", "x", 0);
+  writeFileSync(join(n, "What?.md"), "x");
+  writeFileSync(join(n, "a: b.md"), "x");
+  mkdirSync(join(n, "1/2/3/4/5/6"), { recursive: true }); writeFileSync(join(n, "1/2/3/4/5/6/deep.md"), "x");
+  mkdirSync(join(n, "trail ")); writeFileSync(join(n, "trail ", "x.md"), "x");
+  symlinkSync("..", join(n, "up"));
+  expect(listNotes(state).map((x) => x.name)).toEqual(["ok"]);
+});
+
+test("rename moves between folders, refuses to clobber, prunes the emptied folder", () => {
+  saveNote(state, "Old/x", "X", 0);
+  saveNote(state, "y", "Y", 0);
+  expect(renameNote(state, "Old/x", "y")).toBe("a note with that name exists");
+  expect(renameNote(state, "nope", "z")).toBe("no such note");
+  expect(renameNote(state, "Old/x", "New/Deep/x")).toBeNull();
+  expect(existsSync(join(state, "notes", "Old"))).toBe(false);
+  expect(readFileSync(join(state, "notes", "New", "Deep", "x.md"), "utf8")).toBe("X");
+});
+
+test("delete moves to .trash, never unlinks", () => {
+  saveNote(state, "F/gone", "keep me", 0);
+  expect(deleteNote(state, "F/gone")).toBeNull();
+  expect(deleteNote(state, "F/gone")).toBe("no such note");
+  const trash = readdirSync(join(state, "notes", ".trash"));
+  expect(trash.length).toBe(1);
+  expect(trash[0]).toEndWith("-F~gone.md");
+  expect(readFileSync(join(state, "notes", ".trash", trash[0]!), "utf8")).toBe("keep me");
+  expect(existsSync(join(state, "notes", "F"))).toBe(false);
+  expect(listNotes(state)).toEqual([]);
+});
+
+test("wikilinks: plain, labelled, anchored; none inside code", () => {
+  const t = "See [[Alpha]] and [[Work/Beta|the beta]] and [[Gamma#Part]].\n`[[not]]`\n```\n[[nor]]\n```\n";
+  const w = wikilinks(t);
+  expect(w.map((x) => [x.name, x.label])).toEqual([["Alpha", "Alpha"], ["Work/Beta", "the beta"], ["Gamma", "Gamma#Part"]]);
+  expect(t.slice(w[1]!.from, w[1]!.to)).toBe("[[Work/Beta|the beta]]");
+  // uncode keeps offsets: blanked text is the same length.
+  expect(uncode(t).length).toBe(t.length);
+});
+
+test("tags: words after a space or at line start; not headings, numbers, urls or code", () => {
+  const t = "#plan and #Work/Q3 here\n# Heading\nissue #12 x#y http://a.b/#frag\n`#code`\n(#paren)";
+  expect(tags(t).map((x) => x.tag)).toEqual(["plan", "work/q3", "paren"]);
+});
+
+test("indented code is code: no tags or wikilinks in it; list continuations still count", () => {
+  const t = "Para #one\n\n    #include <x>\n    [[inCode]]\n\n\tmore #nottag\n\nback #two\n- item\n    #three [[Cont]]\n";
+  expect(tags(t).map((x) => x.tag)).toEqual(["one", "two", "three"]);
+  expect(wikilinks(t).map((x) => x.name)).toEqual(["Cont"]);
+  expect(uncode(t).length).toBe(t.length);
+});
+
+test("resolve: exact name first, then by last segment, ignoring case", () => {
+  const names = ["Work/Standup", "Home/Standup", "Alpha"];
+  expect(resolve("alpha", names)).toBe("Alpha");
+  expect(resolve("Work/Standup", names)).toBe("Work/Standup");
+  expect(resolve("standup", names)).toBe("Home/Standup");
+  expect(resolve("Nope", names)).toBeNull();
+});
+
+test("safeUrl: web, mail and relative only", () => {
+  for (const ok of ["https://x.dev", "http://x", "mailto:a@b.c", "Other note.md", "img/a.png", "#part"]) expect(safeUrl(ok)).toBe(ok);
+  for (const bad of ["javascript:alert(1)", " JavaScript:alert(1)", "data:text/html,x", "vbscript:x", "file:///etc/passwd", "//evil.com/x", "java\tscript:x", ""])
+    expect(safeUrl(bad)).toBeNull();
+});
+
+test("parseTable: header, alignment, rows padded, escaped pipes kept", () => {
+  expect(parseTable("| A | B | C |\n|:--|:-:|--:|\n| 1 | a \\| b |\n|2|3|4|5|\n")).toEqual({
+    head: ["A", "B", "C"], align: ["left", "center", "right"], rows: [["1", "a | b", ""], ["2", "3", "4"]],
+  });
+  expect(parseTable("A | B\r\n--- | ---\r\nx | y").rows).toEqual([["x", "y"]]);
+});
+
+test("board links: kinds, tabs, items; a note link is not one", () => {
+  const w = (t: string) => wikilinks(t)[0]!;
+  expect(boardLink(w("[[run:2026-10-01-notebook]]"))).toEqual({ kind: "run", id: "2026-10-01-notebook" });
+  expect(boardLink(w("[[run:notebook#Review|see]]"))).toEqual({ kind: "run", id: "notebook", tab: "review" });
+  expect(boardLink(w("[[run:notebook#finding-2]]"))).toEqual({ kind: "run", id: "notebook", tab: "review", item: { type: "finding", n: 2 } });
+  expect(boardLink(w("[[run:notebook#backlog-13]]"))).toEqual({ kind: "run", id: "notebook", tab: "backlog", item: { type: "backlog", n: 13 } });
+  expect(boardLink(w("[[run:notebook#nonsense]]"))).toEqual({ kind: "run", id: "notebook" });
+  expect(boardLink(w("[[idea:fix #12 in the FAQ]]"))).toEqual({ kind: "idea", text: "fix #12 in the FAQ" });
+  expect(boardLink(w("[[Standup]]"))).toBeNull();
+  expect(boardLink(w("[[run:../../x]]"))).toBeNull();
+  expect(w("[[Note#Part|p]]")).toMatchObject({ name: "Note", anchor: "Part", target: "Note#Part", label: "p" });
+  expect(anchorWords({ kind: "run", id: "x", tab: "review", item: { type: "finding", n: 2 } })).toBe("finding 2");
+});
+
+test("resolveRun: exact id, else the newest run of that name", () => {
+  const ids = ["2026-09-01-notebook", "2026-10-01-notebook", "2026-10-01-notebook-board-links"];
+  expect(resolveRun("2026-09-01-notebook", ids)).toBe("2026-09-01-notebook");
+  expect(resolveRun("notebook", ids)).toBe("2026-10-01-notebook");
+  expect(resolveRun("board-links", ids)).toBeNull();
+  expect(resolveRun("nope", ids)).toBeNull();
+});
+
+test("boardIndex and linksTo: runs with findings and every backlog line numbered; notes that link a run", () => {
+  const run = (id: string, files: Record<string, string>) => {
+    mkdirSync(join(state, "runs", id), { recursive: true });
+    writeFileSync(join(state, "runs", id, "state.json"), JSON.stringify({ id, stage: "done", awaiting: null }));
+    for (const [f, t] of Object.entries(files)) writeFileSync(join(state, "runs", id, f), t);
+  };
+  run("2026-10-01-notes", {
+    "00-request.md": "# Request\n\n> make notes\n",
+    "04-review.md": "# Review\n\n## Findings\n\n1. a.ts:1: high: first. fix.\n2. b.ts:2: low: second. fix.\n",
+    "06-backlog.md": "# Backlog\n\n- done: one | x\n- open: two | y\n- rejected: three | z\n",
+  });
+  run("2026-10-02-other", {});
+  writeFileSync(join(state, "inbox.md"), "- open: an idea here\n");
+  const ix = boardIndex(state);
+  const r = ix.runs.find((x) => x.id === "2026-10-01-notes")!;
+  expect(r.short).toBe("notes");
+  expect(r.findings.map((f) => f.n)).toEqual([1, 2]);
+  expect(r.backlog).toEqual([{ n: 1, status: "done", text: "one | x" }, { n: 2, status: "open", text: "two | y" }, { n: 3, status: "rejected", text: "three | z" }]);
+  expect(ix.ideas.map((i) => i.text)).toEqual(["an idea here"]);
+  saveNote(state, "A", "see [[run:notes#finding-1]]", 0);
+  saveNote(state, "B", "see [[run:2026-10-02-other]] and [[notes]]", 0);
+  saveNote(state, "C", "`[[run:notes]]` in code", 0);
+  expect(linksTo(state, "2026-10-01-notes")).toEqual(["A"]);
+  expect(linksTo(state, "2026-10-02-other")).toEqual(["B"]);
+});
+
+test("tree and freshName", () => {
+  const tr = tree(["b", "Z/c", "A/x", "A/B/y", "a2"]);
+  expect([...tr.folders.keys()]).toEqual(["A", "Z"]);
+  expect(tr.notes).toEqual(["a2", "b"]);
+  expect([...tr.folders.get("A")!.folders.keys()]).toEqual(["B"]);
+  expect(freshName(["Untitled", "untitled 2"])).toBe("Untitled 3");
+  expect(freshName(["Untitled"], "Work")).toBe("Work/Untitled");
+});
+
+test("the notebook's design tokens are the board's, line for line", () => {
+  const block = (f: string) => {
+    const s = readFileSync(join(root, "web", f), "utf8").split("\n");
+    const at = s.findIndex((l) => l.startsWith(":root{--bg:"));
+    return s.slice(at, at + 8).join("\n");
+  };
+  expect(block("notes.html")).toBe(block("board.html"));
+  expect(block("board.html")).toContain("data-theme=dark]{--shade");
+  const syms = (f: string) => readFileSync(join(root, "web", f), "utf8").split("\n").filter((l) => l.startsWith('<symbol id="s-')).join("\n");
+  expect(syms("notes.html")).toBe(syms("board.html"));
+  expect(syms("board.html").split("\n").length).toBe(6);
+  const mascot = (f: string) => readFileSync(join(root, "web", f), "utf8").split("\n").find((l) => l.startsWith(".mascot{"));
+  expect(mascot("notes.html")).toBe(mascot("board.html")!);
+});
+
+test("web/notebook.js was built from the sources as they are (bun run build:web)", () => {
+  const first = readFileSync(OUT, "utf8").split("\n", 1)[0]!;
+  expect(first).toContain(`kaizen notebook ${sourceHash()} `);
+});

package/cli/notes.ts

@@ -0,0 +1,139 @@
+// The notebook's files: plain markdown under <state>/notes/, folders and all, so any
+// editor (Obsidian included) can open the same folder. Every name that arrives from
+// the page goes through safeName before it becomes a path.
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, statSync, writeFileSync } from "node:fs";
+import { join, dirname, resolve, sep } from "node:path";
+import { boardCards, reviewFindings } from "./state.ts";
+import { wikilinks, boardLink, resolveRun } from "../web/notes-lib.ts";
+
+export type Note = { name: string; mtime: number; text: string };
+
+export const notesDir = (state: string) => join(state, "notes");
+
+// A note name is its path under notes/ without `.md`: `Work/Standup`. At most six
+// folders deep; no segment that is empty, dotted, or holds a character some
+// filesystem refuses. Returns the tidied name, or null.
+export function safeName(name: unknown): string | null {
+  if (typeof name !== "string") return null;
+  const parts = name.trim().replace(/\.md$/i, "").split("/").map((p) => p.trim());
+  if (parts.length > 6) return null;
+  for (const p of parts) {
+    if (!p || p.length > 120 || p.startsWith(".") || /[\\:*?"<>|\x00-\x1f]/.test(p)) return null;
+  }
+  return parts.join("/");
+}
+
+// The file for a name, or null when the name is unsafe or would land outside notes/.
+function fileOf(state: string, name: unknown) {
+  const n = safeName(name);
+  if (!n) return null;
+  const root = resolve(notesDir(state));
+  const f = resolve(root, n + ".md");
+  return f.startsWith(root + sep) ? { name: n, file: f } : null;
+}
+
+// ponytail: the whole vault is read on every list; fine for hundreds of notes, send
+// names and mtimes only (and text on open) if a vault reaches thousands.
+// Only names safeName keeps as they are: a file the notebook could not save back
+// (`What?.md`, seven folders deep) is left to the editor that made it.
+export function listNotes(state: string): Note[] {
+  const root = notesDir(state), out: Note[] = [], seen = new Set<string>();
+  const walk = (dir: string, prefix: string) => {
+    let names: string[];
+    // A symlinked folder is followed once: `ln -s .. notes/up` is not a loop.
+    try { const real = realpathSync(dir); if (seen.has(real)) return; seen.add(real); names = readdirSync(dir); } catch { return; }
+    for (const n of names) {
+      if (n.startsWith(".")) continue;                     // .trash, .obsidian
+      const p = join(dir, n);
+      let st;
+      try { st = statSync(p); } catch { continue; }
+      if (st.isDirectory()) walk(p, prefix + n + "/");
+      else if (n.toLowerCase().endsWith(".md") && safeName(prefix + n) === prefix + n.slice(0, -3)) {
+        try { out.push({ name: prefix + n.slice(0, -3), mtime: st.mtimeMs, text: readFileSync(p, "utf8") }); } catch { /* vanished */ }
+      }
+    }
+  };
+  walk(root, "");
+  return out.sort((a, b) => b.mtime - a.mtime);
+}
+
+// `base` is the mtime the page loaded the note at, 0 for a note it is creating. Any
+// other mtime on disk means someone else wrote it since: refuse, and say what is there.
+export function saveNote(state: string, name: unknown, text: string, base: number):
+  { ok: true; name: string; mtime: number } | { ok: false; why: string; text?: string; mtime?: number } {
+  const t = fileOf(state, name);
+  if (!t) return { ok: false, why: "bad name" };
+  if (existsSync(t.file)) {
+    const now = statSync(t.file).mtimeMs;
+    if (now !== base) return { ok: false, why: "conflict", text: readFileSync(t.file, "utf8"), mtime: now };
+  } else if (base) return { ok: false, why: "conflict", text: "", mtime: 0 };
+  mkdirSync(dirname(t.file), { recursive: true });
+  writeFileSync(t.file, text);
+  return { ok: true, name: t.name, mtime: statSync(t.file).mtimeMs };
+}
+
+// Also how a note moves between folders: `Standup` to `Work/Standup`.
+export function renameNote(state: string, from: unknown, to: unknown): string | null {
+  const a = fileOf(state, from), b = fileOf(state, to);
+  if (!a || !b) return "bad name";
+  if (!existsSync(a.file)) return "no such note";
+  if (a.file === b.file) return null;
+  // A case-only rename on a case-insensitive disk finds `to` already there: it is `from`.
+  if (existsSync(b.file) && a.file.toLowerCase() !== b.file.toLowerCase()) return "a note with that name exists";
+  mkdirSync(dirname(b.file), { recursive: true });
+  renameSync(a.file, b.file);
+  prune(state, dirname(a.file));
+  return null;
+}
+
+// Never unlinked: moved to notes/.trash/, where Obsidian keeps its own too.
+export function deleteNote(state: string, name: unknown): string | null {
+  const t = fileOf(state, name);
+  if (!t) return "bad name";
+  if (!existsSync(t.file)) return "no such note";
+  const trash = join(notesDir(state), ".trash");
+  mkdirSync(trash, { recursive: true });
+  renameSync(t.file, join(trash, `${Date.now().toString(36)}-${t.name.replace(/\//g, "~")}.md`));
+  prune(state, dirname(t.file));
+  return null;
+}
+
+// A folder exists while it holds something; remove the ones a move or delete emptied.
+function prune(state: string, dir: string) {
+  const root = resolve(notesDir(state));
+  for (let d = resolve(dir); d.startsWith(root + sep); d = dirname(d)) {
+    try { if (readdirSync(d).length) return; rmdirSync(d); } catch { return; }
+  }
+}
+
+// What a note can link to on the board, for the notebook's chips and completion: the
+// project's runs, each with its review findings and its backlog items numbered from 1
+// in file order (items are never deleted, so a number keeps pointing at its item),
+// and its ideas. Archived and abandoned ones too: a link outlives the card.
+// ponytail: every run's review and backlog read per request; cache by mtime if a
+// project keeps hundreds of runs.
+export function boardIndex(state: string) {
+  const cards = boardCards([state], Date.now());
+  const backlog = (id: string) => {
+    let text = "";
+    try { text = readFileSync(join(state, "runs", id, "06-backlog.md"), "utf8"); } catch { /* none */ }
+    return [...text.matchAll(/^\s*-\s*(open|done|rejected):\s*(.*)$/gm)].map((m, i) => ({ n: i + 1, status: m[1]!, text: m[2]!.trim() }));
+  };
+  return {
+    runs: cards.filter((c) => c.kind === "run").map((c) => ({
+      id: c.id!, short: c.id!.replace(/^\d{4}-\d{2}-\d{2}-/, ""), title: c.title ?? c.text, status: c.status,
+      findings: reviewFindings(state, c.id!), backlog: backlog(c.id!),
+    })),
+    ideas: cards.filter((c) => c.kind === "idea").map((c) => ({ text: c.text, status: c.status })),
+  };
+}
+
+// The notes whose board links name this run, for the board's "Linked from notes".
+export function linksTo(state: string, id: string) {
+  let ids: string[] = [];
+  try { ids = readdirSync(join(state, "runs")); } catch { return []; }
+  return listNotes(state).filter((n) => wikilinks(n.text).some((w) => {
+    const l = boardLink(w);
+    return l?.kind === "run" && resolveRun(l.id, ids) === id;
+  })).map((n) => n.name);
+}

package/cli/web.ts

@@ -9,9 +9,26 @@ import {
   reviewFindings, pickFindings, fixPrompt,
 } from "./state.ts";
 import { readSources, addSource, removeSource, moveSource, gatherSource, gatherAll, gatherDirs, due } from "./sources.ts";
+import { listNotes, saveNote, renameNote, deleteNote, boardIndex, linksTo } from "./notes.ts";
 
 const PAGE = join(dirname(import.meta.dir), "web", "board.html");
+// The notebook: its page, and the CodeMirror bundle `bun run build:web` commits beside it.
+const NOTES_PAGE = join(dirname(import.meta.dir), "web", "notes.html");
+const NOTES_JS = join(dirname(import.meta.dir), "web", "notebook.js");
 const DEFAULT_PORT = 7420;
+// Read once at start: a board keeps the code it started with, so this is what it
+// runs, not what is installed now. `/` sends it; `current()` compares the two.
+const VERSION = (() => {
+  try { return JSON.parse(readFileSync(join(dirname(import.meta.dir), "package.json"), "utf8")).version as string; }
+  catch { return "unknown"; }
+})();
+
+// A board answers at url and runs the installed version. A board from before the
+// version header sends none, so it counts as stale too.
+export async function current(url: string) {
+  const r = await fetch(url, { signal: AbortSignal.timeout(1500) }).catch(() => null);
+  return !!r?.ok && r.headers.get("x-kaizen-version") === VERSION;
+}
 
 type Opts = { port?: number; open?: boolean };
 
@@ -154,11 +171,12 @@ export async function web(repoDir: string, opts: Opts = {}) {
       if (!["EADDRINUSE", "EACCES"].includes((e as { code?: string }).code ?? "")) throw e;
       const url = `http://127.0.0.1:${port}/`;
       const up = await fetch(url, { signal: AbortSignal.timeout(1500) }).then((r) => r.ok, () => false);
-      if (up) { console.log(`\n  kaizen web already at ${url}\n`); if (opts.open !== false) await openApp(url); return; }
-      // A listener that does not answer is a board that hung; it is ours to stop.
+      if (up && await current(url)) { console.log(`\n  kaizen web already at ${url}\n`); if (opts.open !== false) await openApp(url); return; }
+      // A listener that does not answer is a board that hung, and one running an
+      // older kaizen serves 404 for whatever came since; both are ours to stop.
       const pid = await pidOnPort(port);
       if (pid && pid !== process.pid) {
-        try { process.kill(pid, "SIGTERM"); console.log(`  stopped a hung board on ${port} (pid ${pid})`); } catch { /* not ours to kill */ }
+        try { process.kill(pid, "SIGTERM"); console.log(`  stopped a ${up ? "stale" : "hung"} board on ${port} (pid ${pid})`); } catch { /* not ours to kill */ }
         await Bun.sleep(300);
         try { server = serve(port); continue; } catch { /* still held */ }
       }
@@ -182,10 +200,30 @@ export async function web(repoDir: string, opts: Opts = {}) {
         if (!existsSync(PAGE)) return new Response("web/board.html missing", { status: 500 });
         // The page gets the notify rule from state.ts rather than keeping its own copy.
         return new Response(readFileSync(PAGE, "utf8").replace("/*notifier*/", () => notifier.toString()), {
-          headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+          headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "x-kaizen-version": VERSION },
         });
       }
 
+      if (req.method === "GET" && (path === "/notebook" || path === "/notebook.js")) {
+        const [f, type] = path === "/notebook" ? [NOTES_PAGE, "text/html; charset=utf-8"] : [NOTES_JS, "application/javascript; charset=utf-8"];
+        if (!existsSync(f)) return new Response(`${path} missing; run bun run build:web`, { status: 500 });
+        return new Response(Bun.file(f), { headers: { "content-type": type, "cache-control": "no-store" } });
+      }
+
+      // Every note of one project, text included: search, tags and backlinks are the page's.
+      if (req.method === "GET" && path === "/vault") {
+        const dir = url.searchParams.get("dir") ?? state ?? join(home, ".kaizen");
+        if (!states(true).includes(dir)) return bad("unknown state dir", 404);
+        return json({ dir, notes: listNotes(dir) });
+      }
+
+      // What a note can link to on this project's board: runs, findings, backlog, ideas.
+      if (req.method === "GET" && path === "/links") {
+        const dir = url.searchParams.get("dir") ?? state ?? join(home, ".kaizen");
+        if (!states(true).includes(dir)) return bad("unknown state dir", 404);
+        return json(boardIndex(dir));
+      }
+
       // The icon on a web notification; this one file and nothing beside it.
       if (req.method === "GET" && path === "/logo.png") {
         if (!existsSync(LOGO)) return bad("no logo", 404);
@@ -224,6 +262,8 @@ export async function web(repoDir: string, opts: Opts = {}) {
           request: read("00-request.md"), plan: read("01-plan.md"), approval: read("02-approval.md"),
           impl: read("03-impl.md"), review: read("04-review.md"), backlog: read("06-backlog.md"),
           notes: read("notes.md"),
+          // Notebook notes whose [[run:…]] links name this run.
+          linkedFrom: linksTo(dir, id),
           // Nothing to pick in the global state dir: /fix refuses it.
           findings: dir === join(home, ".kaizen") ? [] : reviewFindings(dir, id),
           // The global state dir sits in $HOME, which is not a project to commit.
@@ -442,6 +482,21 @@ export async function web(repoDir: string, opts: Opts = {}) {
           return failed ? bad(failed, 404) : json({ ok: true });
         }
 
+        // A save names the mtime it loaded; a different one on disk is a 409 carrying
+        // what is there, so the page can keep the typed text and let the user choose.
+        if (path === "/vault") {
+          if (body.op === "save") {
+            if (typeof body.text !== "string") return bad("text required");
+            const r = saveNote(dir, body.name, body.text, Number(body.base) || 0);
+            changed();
+            return r.ok ? json(r) : r.why === "conflict" ? json(r, 409) : bad(r.why);
+          }
+          const why = body.op === "rename" ? renameNote(dir, body.name, body.to)
+            : body.op === "delete" ? deleteNote(dir, body.name) : "unknown op";
+          changed();
+          return why ? bad(why, why === "no such note" ? 404 : why === "a note with that name exists" ? 409 : 400) : json({ ok: true });
+        }
+
         // Only a finished run, or one waiting at the final approval, and never the
         // global state dir: $HOME may be a repository, and it is not the run's project.
         if (path === "/commit") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.8.1",
+  "version": "1.9.1",
   "description": "Staged workflow for AI agents — code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
   "scripts": {
     "install-links": "bun run cli/install.ts",
     "check": "bun run cli/install.ts --check",
+    "build:web": "bun run cli/build-web.ts",
     "test": "bun test",
     "prepublishOnly": "bun test",
     "postpublish": "sh cli/release.sh",
@@ -42,5 +43,14 @@
     "code-review",
     "writing",
     "research"
-  ]
+  ],
+  "devDependencies": {
+    "@codemirror/autocomplete": "6.20.3",
+    "@codemirror/commands": "6.11.1",
+    "@codemirror/lang-markdown": "6.5.2",
+    "@codemirror/language": "6.12.4",
+    "@codemirror/state": "6.7.6",
+    "@codemirror/view": "6.43.13",
+    "@lezer/highlight": "1.2.5"
+  }
 }