kaizen-agent 1.32.0 → 1.33.1

package/README.md

@@ -2,11 +2,41 @@
 <img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/banner.png" alt="kaizen" width="760">
 </div>
 
-<p align="center"><b>See the plan before your AI starts. Get a second opinion when it is done.</b></p>
+<p align="center"><b>One tool to build and maintain your product with AI agents.</b><br>Requests in, a plan you approve, the work, an independent review, done.</p>
 
-**The problem:** an AI agent starts writing before you agree on what it should do, then grades its own work.
+<p align="center"><img src="assets/hero.gif" alt="Animated walkthrough of the real kaizen board with sample data. 1: a request gathered from a support sheet waits in the Icebox and is promoted. 2: it is an idea on the board, and Run opens Claude Code. 3: the agent works in the card's own terminal and writes a plan. 4: the plan panel shows what done and wrong mean, and it is approved. 5: it builds, then a reviewer that never saw the work reports a high finding, a double charge. 6: only that finding is ticked and fixed. 7: the reviewer re-checks it. 8: the run lands in Done, with the low finding left in the backlog." width="760"></p>
 
-**Kaizen:** it plans first and waits for your approval, then an agent that never saw the work reviews it.
+## The problem
+
+You ask an AI coding agent to retry a payment webhook when the bank times out. It starts editing at once, then says *"Done, tests pass."* The tests do pass. They were written by the same agent, from the same assumption: that a timeout means the charge failed. Sometimes the bank said yes and the reply got lost. Now a retry charges the customer twice, and nothing in the agent's report would make you look.
+
+None of this is a lack of intelligence. It is a missing workflow:
+
+| What goes wrong | What kaizen does |
+| :--- | :--- |
+| The agent decides what "done" means on its own, and you find out from the diff | It writes a plan first, including what *wrong* would look like, and waits for your approve or change |
+| The author grades its own work, so its blind spot is in the code *and* in the check | A second agent that never saw the work reviews it, from the request, the plan and the diff only |
+| Findings get fixed in an endless loop, or silently dropped | Serious findings are fixed and re-checked, at most twice; the rest come to you, and what is left goes to a backlog |
+| Requests live in sheets, docs and social posts; the plan in one chat, the review in another, the commit somewhere else | One board, from an icebox that gathers those requests to an idea, a plan, the build, the review, the fix loop and the commit, every step on file |
+
+Many assistants now ask for approval before they act, and some run a checker on their own draft. The difference here is *who* checks: a reviewer that shares the author's context shares its blind spots. Kaizen's reviewer starts cold, on purpose.
+
+Every stage is a file in `.kaizen/runs/<id>/`, so a run can be resumed later, by another session or another tool (Claude Code, Codex, Antigravity), and read back when someone asks why the code is the way it is.
+
+## Who it is for
+
+**Good fit if you:**
+
+- Build and maintain a product, and want one place for it: requests gathered from where they live, then plan, build, review and commit, without switching tools.
+- Already use an AI coding agent, and have caught it confidently wrong more than once.
+- Change things where a mistake is expensive: money, data, migrations, anything a customer sees.
+- Want to see and steer the plan before code is written, not reverse-engineer it from a diff.
+
+**Not for you if:**
+
+- Your changes are typos and one-liners. A run costs several times one prompt; kaizen takes a short path for small work, but it is not free.
+- You want the agent to ship without you. Kaizen is built to stop and ask.
+- You do not use an AI coding agent. Kaizen runs inside one; it is not one.
 
 ## Install
 
@@ -42,6 +72,58 @@ The board opens in your browser. The side menu holds the board, notes, the icebo
 
 To add a launcher (Spotlight on macOS, the app menu on Linux, a Desktop shortcut on Windows), run `kaizen web --shortcut` once.
 
+## Development
+
+TypeScript on [Bun](https://bun.sh) 1.1 or newer, zero runtime dependencies. No build step for the CLI — `cli/*.ts` runs as-is — and the web front end ships prebuilt.
+
+```bash
+git clone https://github.com/hfadhlullah/kaizen.git && cd kaizen
+bun install               # dev dependencies only
+bun test                  # the suite; what CI runs
+```
+
+To work on kaizen, install from your checkout so every link points at it:
+
+```bash
+bun run cli/install.ts
+```
+
+Skills, agents and commands are symlinked into every AI agent it finds; re-running is safe. From a checkout the workflow updates on any run, and `kaizen upgrade` leaves your local edits alone — update them with git.
+
+After editing `web/notebook.ts` or `web/notes-lib.ts`, rebuild the committed bundle:
+
+```bash
+bun run build:web         # rewrites web/notebook.js; a test fails if it goes stale
+```
+
+### Layout
+
+| Path | What it is |
+|---|---|
+| `cli/` | The installer and the runtime behind every `kaizen` command: `install.ts` (the CLI), `state.ts` (runs), `web.ts` (board server), `dashboard.ts` (terminal board), `sources.ts`, `settings.ts`, `notes.ts`. Tests beside them. |
+| `skills/` | The workflow as Agent Skills folders: `kaizen/` (`SKILL.md`, the `spec-*.md` stage contracts, `adapters.md`, `config.default.yml`), `kaizen-help/`, `story-deck/`, `story-video/`. |
+| `agents/` | The Claude Code subagents: `kaizen-planner`, `kaizen-builder`, `kaizen-reviewer`. |
+| `commands/` | The `/kaizen-*` slash commands, one file each. |
+| `web/` | The board and notebook front end: `board.html`, `notes.html`, `notebook.ts`. |
+| `bot/` | Kaizen Bot — a separate private package with its own tests and build. See [its README](bot/README.md). |
+| `docs/` | The guide and internal notes, indexed in [`docs/README.md`](docs/README.md). |
+| `design.md` | Design notes for the repo. |
+| `.kaizen/` | This repo's own runs — kaizen is built with kaizen. Gitignored: a fresh clone gets it on its first run. |
+
+### Kaizen Bot
+
+```bash
+cd bot
+cp .env.example .env      # PROVIDER, MODEL, that provider's key
+bun start                 # http://127.0.0.1:7430 — run `kaizen web` first
+bun test
+bun run build             # the desktop app, into dist/
+```
+
+### Contributing
+
+Pull requests; CI runs `bun test` on Ubuntu and Windows and it must pass. For non-trivial work, dogfood: `/kaizen <change>` in this repo plans, builds and reviews it — [`skills/kaizen/spec.md`](skills/kaizen/spec.md) is the contract the stages follow.
+
 ## License
 
 MIT

package/cli/board.test.ts

@@ -1,12 +1,12 @@
-// The board's markdown renderer, lifted out of web/board.html and run as it ships.
+// The board's markdown renderer and helpers, imported from the board's modules as they ship.
 import { test, expect } from "bun:test";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { md, progress, planQuestions, brief } from "../web/board/markdown.ts";
+import { draft, undraft } from "../web/board/drafts.ts";
 
 const html = readFileSync(join(dirname(import.meta.dir), "web", "board.html"), "utf8");
-const esc = html.match(/^const esc=.*$/m)![0];
-const at = html.indexOf("function md(");
-const md = new Function(`${esc}\n${html.slice(at, html.indexOf("\n\n", at))}\nreturn md`)() as (src: string, tick?: boolean) => string;
+const cards = readFileSync(join(dirname(import.meta.dir), "web", "board", "cards.ts"), "utf8");
 
 test("backlog items: a checkbox each, ticked only when done", () => {
   const out = md('- open: one | why\n- done: two <b>x</b> | fixed\n- rejected: three | no\n- plain\n', true);
@@ -23,16 +23,16 @@ test("without the flag a backlog line is an ordinary list item", () => {
   expect(md("- done: two\n")).toBe("<ul><li>done: two</li></ul>");
 });
 
-// draft()/undraft() lifted the same way, against a stub sessionStorage whose keys are its own properties.
+// draft()/undraft(), against a stub sessionStorage whose keys are its own properties.
 const store = () => Object.defineProperties({} as Record<string, string>, {
   getItem: { value(k: string) { return k in this ? this[k] : null; } },
   setItem: { value(k: string, v: string) { this[k] = String(v); } },
   removeItem: { value(k: string) { delete this[k]; } },
 });
-const line = (re: RegExp) => html.match(re)![0];
-const drafts = (ss: object) => new Function("sessionStorage",
-  `${line(/^const DK=.*$/m)}\n${line(/^function draft\(.*$/m)}\n${line(/^function undraft\(.*$/m)}\nreturn {draft,undraft}`)(ss) as
-  { draft: (el: any, k: string) => void; undraft: (p: string) => void };
+const drafts = (ss: object) => {
+  (globalThis as any).sessionStorage = ss;
+  return { draft, undraft } as { draft: (el: any, k: string) => void; undraft: (p: string) => void };
+};
 const field = (value = "") => ({ value, on: () => {}, addEventListener(_: string, f: () => void) { this.on = f; } });
 
 test("a draft is saved on input and restored into a rebuilt field", () => {
@@ -54,9 +54,7 @@ test("undraft removes by prefix and leaves the rest", () => {
   expect(Object.keys(ss).sort()).toEqual(["kz-d:n:x", "kz-form"]);
 });
 
-// A building run's progress list, lifted the same way.
-const pat = html.indexOf("function progress(");
-const progress = new Function(`${esc}\n${html.slice(pat, html.indexOf("\n\n", pat))}\nreturn progress`)() as (src: string, prev?: string[]) => string;
+// A building run's progress list.
 
 test("progress: each item marked done, working on or to do, with the count", () => {
   const out = progress("# Progress\n- done: one\n- doing: two <b>x</b>\n- todo: `three`\n- open: not an item\n");
@@ -77,10 +75,7 @@ test("progress: a file with no items draws nothing", () => {
   expect(progress("# Progress\n\nnothing yet\n")).toBe("");
 });
 
-// A plan's open questions, lifted the same way: the function ends at the first line not indented.
-const pq = html.indexOf("function planQuestions(");
-type Q = { q: string; multi: boolean; options: { text: string; label: string; rec: boolean }[] };
-const planQuestions = new Function(`${html.slice(pq).split(/\n(?! )/)[0]}\nreturn planQuestions`)() as (src: string) => Q[] | null;
+// A plan's open questions.
 
 test("planQuestions: Q lines with options, recommended and multi-select read", () => {
   const qs = planQuestions(`# Plan\n## 9. Open questions\n\nQ: Which improvements to build? (multi-select)\n   - Own project in row (recommended) — fixes Move; XS\n   - Gather on add — instant result\nQ: Where the progress shows\n   - Top of the Backlog tab (recommended): what you asked for.\n   - Its own tab: adds an eighth tab\n\n- Note: not an option\n## 10. Out of scope suggestions\n- not a question\n`);
@@ -108,8 +103,9 @@ test("card menu items: appropriate actions and distinct icons across phases", ()
   expect(html).toContain('<symbol id="i-restore"');
 
   const ico = (n: string) => `<svg><use href="#i-${n}"/></svg>`;
-  const menuSnippet = (html.slice(html.indexOf("if(k===menuKey){"), html.indexOf("el.innerHTML+=`<div class=\"menu-pop\"", html.indexOf("if(k===menuKey){"))) + "}").replace("const items=[];", "items=[];");
-  const getItems = new Function("c", "archive", "S", `const ico = ${ico.toString()};\nlet k = 1, menuKey = 1, items = [];\n${menuSnippet}\nreturn items;`);
+  const from = cards.indexOf("if (k === store.menuKey) {");
+  const menuSnippet = (cards.slice(from, cards.indexOf('el.innerHTML += `<div class="menu-pop"', from)) + "}").replace("const items = [];", "items = [];");
+  const getItems = new Function("c", "archive", "S", `const ico = ${ico.toString()};\nconst store = { S, menuKey: 1 };\nlet k = 1, items = [];\n${menuSnippet}\nreturn items;`);
 
   // Phase 0: Ideas (idea card)
   const idea = { kind: "idea", status: "idea", column: 0 };
@@ -173,9 +169,7 @@ test("card menu items: appropriate actions and distinct icons across phases", ()
   expect(archIdea.map((i: any) => i ? i[1] : null)).toEqual(["Restore", "Open", null, "Delete"]);
 });
 
-// brief() lifted the same way: a one-line structured idea split for display only.
-const bat = html.indexOf("function brief(");
-const brief = new Function(`${html.slice(bat, html.indexOf("\n\n", bat))}\nreturn brief`)() as (t: string) => { head: string; parts: { label: string; body: string }[] };
+// brief(): a one-line structured idea split for display only.
 
 test("a labelled idea splits into a head and one part per label", () => {
   const b = brief("Improve previews Problem: one dense block. Non-goals: no rewrites. Acceptance criteria: (1) scannable. (2) full text kept.");

package/cli/browser.test.ts

@@ -13,7 +13,10 @@ afterAll(() => rmSync(home, { recursive: true, force: true }));
 
 // Async, so the pages this process serves can answer the browser meanwhile.
 const run = async (code: string, env: Record<string, string> = {}) => {
+  // The profile lands in the throwaway HOME, but Chrome itself gets the real one: under
+  // a scratch HOME it cannot reach the keychain (macOS) or start at all (Windows).
   const script = `import * as br from ${JSON.stringify(join(repo, "cli/browser.ts"))};
+Object.assign(process.env, ${JSON.stringify({ HOME: process.env.HOME ?? "", USERPROFILE: process.env.USERPROFILE ?? "" })});
 console.log(JSON.stringify(await (async () => { ${code} })()));`;
   const p = Bun.spawn(["bun", "-e", script], { cwd: home, env: { ...process.env, HOME: home, USERPROFILE: home, ...env }, stdout: "pipe", stderr: "pipe" });
   const [out, err, code_] = [await new Response(p.stdout).text(), await new Response(p.stderr).text(), await p.exited];

package/cli/browser.ts

@@ -169,12 +169,14 @@ export async function browse<T>(use: (page: Page) => Promise<T>): Promise<T | {
   if (!exe) return { ok: false, note: NO_BROWSER };
   const dir = profile();
   rmSync(join(dir, "DevToolsActivePort"), { force: true });
+  // env passed explicitly: without it Bun hands the child its startup env, not process.env as it is now.
   const proc = Bun.spawn([exe, "--headless=new", `--user-data-dir=${dir}`, "--remote-debugging-address=127.0.0.1", "--remote-debugging-port=0",
-    "--no-first-run", "--no-default-browser-check", "--window-size=1280,2000", "about:blank"], { stdout: "ignore", stderr: "ignore" });
+    "--no-first-run", "--no-default-browser-check", "--window-size=1280,2000", "about:blank"], { env: process.env, stdout: "ignore", stderr: "ignore" });
   let page: Page | null = null;
   try {
     let port = "";
-    for (let i = 0; i < 100 && !port; i++) {
+    // A first start on a fresh profile took over 10 s on Windows.
+    for (let i = 0; i < 300 && !port; i++) {
       await Bun.sleep(100);
       try { port = readFileSync(join(dir, "DevToolsActivePort"), "utf8").split("\n")[0]!.trim(); } catch { /* not yet */ }
       if (proc.exitCode !== null) break;

package/cli/build-web.ts

@@ -1,16 +1,20 @@
 // `bun run build:web`: bundles the notebook's script and CodeMirror into
-// web/notebook.js, and the in-card terminal and xterm.js into web/term.js (+ its
-// stylesheet, web/term.css), all committed, so an install or a checkout serves it with no
+// web/notebook.js, the in-card terminal and xterm.js into web/term.js (+ its
+// stylesheet, web/term.css), the board's modules (web/board/) into web/board.js and
+// Kaizen Bot's page modules (bot/web/app/) into bot/web/app.js, all 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 a committed file no longer matches.
 import { createHash } from "node:crypto";
-import { copyFileSync, readFileSync, writeFileSync } from "node:fs";
+import { copyFileSync, readdirSync, 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", "web/term.ts"];
+const modules = (dir: string) => readdirSync(join(root, dir)).filter((f) => f.endsWith(".ts")).sort().map((f) => `${dir}/${f}`);
+const SOURCES = ["web/notebook.ts", "web/notes-lib.ts", "web/term.ts", ...modules("web/board"), ...modules("bot/web/app")];
 export const OUT = join(root, "web", "notebook.js");
 export const TERM_OUT = join(root, "web", "term.js");
+export const BOARD_OUT = join(root, "web", "board.js");
+export const BOT_OUT = join(root, "bot", "web", "app.js");
 
 // The sources and the exact dependency versions: a CodeMirror bump is a rebuild too.
 export function sourceHash() {
@@ -22,13 +26,19 @@ export function sourceHash() {
 export const banner = (what = "notebook", from = "web/notebook.ts") => `/* kaizen ${what} ${sourceHash()} -- generated by bun run build:web from ${from}; do not edit */`;
 
 if (import.meta.main) {
-  for (const [src, out, what] of [["web/notebook.ts", OUT, "notebook"], ["web/term.ts", TERM_OUT, "terminal"]] as const) {
-    // The terminal is a classic script on the board's page: wrapped, or its top-level
-    // names collide with the board's own globals and the whole file is refused.
-    const r = await Bun.build({ entrypoints: [join(root, src)], target: "browser", minify: true, format: what === "terminal" ? "iife" : "esm" });
+  const bundles = [
+    ["web/notebook.ts", OUT, "notebook"],
+    ["web/term.ts", TERM_OUT, "terminal"],
+    ["web/board/main.ts", BOARD_OUT, "board"],
+    ["bot/web/app/main.ts", BOT_OUT, "bot page"],
+  ] as const;
+  for (const [src, out, what] of bundles) {
+    // The terminal, the board and the bot page are classic scripts: wrapped, or their
+    // top-level names collide with each other's globals and the whole file is refused.
+    const r = await Bun.build({ entrypoints: [join(root, src)], target: "browser", minify: true, format: what === "notebook" ? "esm" : "iife" });
     if (!r.success) { for (const l of r.logs) console.error(l); process.exit(1); }
     writeFileSync(out, banner(what, src) + "\n" + await r.outputs[0]!.text());
-    console.log(`  ${src.replace(".ts", ".js")}  ${(Bun.file(out).size / 1024).toFixed(0)} KB`);
+    console.log(`  ${out.slice(root.length + 1)}  ${(Bun.file(out).size / 1024).toFixed(0)} KB`);
   }
   copyFileSync(join(root, "node_modules", "@xterm", "xterm", "css", "xterm.css"), join(root, "web", "term.css"));
 }

package/cli/notes.test.ts

@@ -6,7 +6,7 @@ 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, TERM_OUT } from "./build-web.ts";
+import { sourceHash, OUT, TERM_OUT, BOARD_OUT, BOT_OUT } from "./build-web.ts";
 
 let state = "";
 beforeEach(() => { state = join(mkdtempSync(join(tmpdir(), "kaizen-notes-")), ".kaizen"); mkdirSync(state); });
@@ -229,7 +229,9 @@ test("the side menu is the board's on the notebook, line for line", () => {
   expect(syms("board.html").every(Boolean)).toBe(true);
 });
 
-test("web/notebook.js and web/term.js were built from the sources as they are (bun run build:web)", () => {
+test("web/notebook.js, web/term.js, web/board.js and bot/web/app.js were built from the sources as they are (bun run build:web)", () => {
   expect(readFileSync(OUT, "utf8").split("\n", 1)[0]!).toContain(`kaizen notebook ${sourceHash()} `);
   expect(readFileSync(TERM_OUT, "utf8").split("\n", 1)[0]!).toContain(`kaizen terminal ${sourceHash()} `);
+  expect(readFileSync(BOARD_OUT, "utf8").split("\n", 1)[0]!).toContain(`kaizen board ${sourceHash()} `);
+  expect(readFileSync(BOT_OUT, "utf8").split("\n", 1)[0]!).toContain(`kaizen bot page ${sourceHash()} `);
 });

package/cli/sources.test.ts

@@ -1,7 +1,7 @@
 // Request sources against a throwaway .kaizen/. No network: the fetch and the DNS
 // lookup are both injected. Nothing here launches an agent or a terminal.
 import { test, expect, beforeEach, afterAll } from "bun:test";
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, chmodSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, chmodSync, realpathSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { readInbox, writeInbox, replaceIdea, parseItem } from "./state.ts";
@@ -11,7 +11,7 @@ import {
   readIcebox, writeIcebox, promote, dismiss, markReplied, setCategory, socialUrl, socialOf, AGENT_ONLY, PLATFORMS,
 } from "./sources.ts";
 
-const root = mkdtempSync(join(tmpdir(), "kaizen-src-"));
+const root = realpathSync(mkdtempSync(join(tmpdir(), "kaizen-src-")));   // macOS: tmpdir is a symlink into /private
 let state: string;
 let n = 0;
 beforeEach(() => { state = join(root, String(n++), ".kaizen"); mkdirSync(state, { recursive: true }); });
@@ -101,6 +101,9 @@ test("a sheet row whose status is Done or Finish is skipped, not marked seen, an
   expect(split("sheet", "no\tdetail\tnotes\n1\tDark mode\tDone\n2\tExport\tfinish\n").map((i) => i.text)).toEqual(["Dark mode", "Export"]);
   // The whole cell names the column, not a word inside it.
   expect(split("sheet", "detail\tstatus notes\nDark mode\tDone\n")).toEqual([{ text: "Dark mode", notes: "Done" }]);
+  // A named column of page names loses to the column holding the requests.
+  expect(split("sheet", "NO\tPAGE\tDETAIL\tSTATUS\tNOTES\n1\tDash\tList\tDone\tAdd a chart to the list\n2\tPlan\tTimeline\t\tDropdown closes before an item can be picked\n3\tPlan\t\t\tRename the statuses to proposal and tender\n").map((i) => i.text))
+    .toEqual(["Dropdown closes before an item can be picked", "Rename the statuses to proposal and tender"]);
 
   addSource(state, SHEET);
   expect(await gatherSource(state, SHEET, text(sheet17(statuses)), pub)).toMatchObject({ ok: true, added: 5, note: "5 new, 4 done skipped" });

package/cli/sources.ts

@@ -385,14 +385,19 @@ export function sift(kind: Kind, body: string): { items: Item[]; done: number }
   const head = filled.slice(0, 5).find((row) => !/^\d{1,3}[.)]?$/.test(row.find(Boolean) ?? "") && (named(row, HEADER) >= 0 || named(row, STATUS) >= 0));
   const data = head ? filled.slice(filled.indexOf(head) + 1) : filled;
   const status = head ? named(head, STATUS) : -1;
-  const known = head ? named(head, HEADER) : -1;
-  // No request column named: one column for the whole sheet, the one holding the most
-  // text that reads like a request. Never a cell per row, which takes `Open` or a name.
-  let col = known;
-  if (col < 0) for (let i = 0, most = 0; i < Math.max(0, ...data.map((row) => row.length)); i++) {
-    const n = i === status ? 0 : data.reduce((sum, row) => sum + (wordy(row[i] ?? "") ? row[i]!.length : 0), 0);
-    if (n > most) { most = n; col = i; }
-  }
+  // One column for the whole sheet, the one holding the most text that reads like a
+  // request. Never a cell per row, which takes `Open` or a name.
+  // Finished rows do not vote: their replies outweigh the requests still open.
+  const open = data.filter((row) => status < 0 || !DONE.test(row[status] ?? ""));
+  const text = (i: number) => i === status ? 0 : open.reduce((sum, row) => sum + (wordy(row[i] ?? "") ? row[i]!.length : 0), 0);
+  let wordiest = -1;
+  for (let i = 0, most = 0; i < Math.max(0, ...data.map((row) => row.length)); i++) if (text(i) > most) { most = text(i); wordiest = i; }
+  // A named column loses to one holding far more text: `DETAIL` naming the page while
+  // `NOTES` holds the request.
+  let known = head ? named(head, HEADER) : -1;
+  // ponytail: a named column with no wordy text at all keeps it (one-cell title rows, pinned by test).
+  if (known >= 0 && wordiest >= 0 && text(known) > 0 && text(wordiest) > 3 * text(known)) known = -1;
+  const col = known >= 0 ? known : wordiest;
   let done = 0;
   const items = data.flatMap((row) => {
     const text = row[col] ?? "";

package/cli/state.ts

@@ -1481,7 +1481,7 @@ export function readCommit(state: string, id: string): { sha: string; pushed: bo
 }
 
 // The card's git mark for each run asked about, by the rules of the panel's button
-// (`gitBtn` in web/board.html): one project status and one read of the reports for
+// (`gitBtn` in web/board/git.ts): one project status and one read of the reports for
 // the lot. A run with nothing to say either way gets no entry.
 export function cardsGit(state: string, ids: string[]): Record<string, "pending" | "pushed"> {
   const s = gitStatus(dirname(state)), out: Record<string, "pending" | "pushed"> = {};

package/cli/web.ts

@@ -16,6 +16,8 @@ import { postLink, sendReply } from "./browser.ts";
 import { listNotes, saveNote, renameNote, deleteNote, boardIndex, linksTo } from "./notes.ts";
 
 const PAGE = join(dirname(import.meta.dir), "web", "board.html");
+// The board's script: web/board/*.ts, bundled into one file by `bun run build:web`.
+const BOARD_JS = join(dirname(import.meta.dir), "web", "board.js");
 // 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 ICO = join(dirname(import.meta.dir), "assets", "kaizen.ico");
@@ -38,7 +40,7 @@ const VERSION = installed();
 // page newer than its server sends ops the server does not know ("unknown op").
 // So the pages are kept as they were at start, and read live (dev edits) only while
 // the installed version is still the one this board runs.
-const AT_START = new Map([PAGE, NOTES_PAGE, NOTES_JS, TERM_JS, TERM_CSS].map((f) => [f, existsSync(f) ? readText(f) : null]));
+const AT_START = new Map([PAGE, BOARD_JS, NOTES_PAGE, NOTES_JS, TERM_JS, TERM_CSS].map((f) => [f, existsSync(f) ? readText(f) : null]));
 const served = (f: string) => installed() === VERSION && existsSync(f) ? readText(f) : AT_START.get(f) ?? null;
 
 // A board answers at url and runs the installed version. A board from before the
@@ -167,9 +169,9 @@ export async function web(repoDir: string, opts: Opts = {}) {
       : ideaPty.get(`${c.state}\0${c.text}`);
     return key && live.has(key) ? { key, alive: ptyState(key)!.alive } : undefined;
   };
-  // Dev: the page reloads itself when board.html is saved. Server code needs
+  // Dev: the page reloads itself when board.html or its bundle is saved. Server code needs
   // `bun --watch cli/install.ts web`; the page reconnects and reloads on hello.
-  try { watch(PAGE, () => { for (const c of clients) { try { c.enqueue("data: reload\n\n"); } catch { clients.delete(c); } } }); } catch { /* no dev reload */ }
+  for (const f of [PAGE, BOARD_JS]) try { watch(f, () => { for (const c of clients) { try { c.enqueue("data: reload\n\n"); } catch { clients.delete(c); } } }); } catch { /* no dev reload */ }
   const watchers: FSWatcher[] = [];
   const watchAll = () => {
     for (const w of watchers) { try { w.close(); } catch { /* gone */ } }
@@ -293,6 +295,12 @@ export async function web(repoDir: string, opts: Opts = {}) {
         });
       }
 
+      if (req.method === "GET" && path === "/board.js") {
+        const body = served(BOARD_JS);
+        if (body === null) return new Response(`${path} missing; run bun run build:web`, { status: 500 });
+        return new Response(body, { headers: { "content-type": "application/javascript; charset=utf-8", "cache-control": "no-store" } });
+      }
+
       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"];
         const body = served(f);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.32.0",
+  "version": "1.33.1",
   "description": "Staged workflow for AI agents — code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {
@@ -22,6 +22,8 @@
     "install-links": "bun run cli/install.ts",
     "check": "bun run cli/install.ts --check",
     "build:web": "bun run cli/build-web.ts",
+    "format": "prettier --write web/*.ts web/board bot/web/app",
+    "format:check": "prettier --check web/*.ts web/board bot/web/app",
     "test": "bun test",
     "prepublishOnly": "bun test",
     "postpublish": "sh cli/release.sh",
@@ -53,6 +55,7 @@
     "@codemirror/view": "6.43.13",
     "@lezer/highlight": "1.2.5",
     "@xterm/addon-fit": "0.11.0",
-    "@xterm/xterm": "6.0.0"
+    "@xterm/xterm": "6.0.0",
+    "prettier": "3.9.10"
   }
 }

package/skills/kaizen/spec.md

@@ -68,6 +68,11 @@ Common shapes, as illustration only — never as a menu to force a request into:
 A run may be a mix. Record it as a mix — the honest description beats the nearest
 label.
 
+Evidence about software whose source is not at hand — a shipped binary, an app
+bundle, an APK, a package — comes from REA (`rea-agents`) when its tools are
+connected in the session: cite what it returns, limitations included. When they are
+not connected, say the claim is unverified rather than guess at internals.
+
 Record the track in `state.json` as `track`, with the three answers written into
 `00-request.md`. Every subsequent stage reads them before starting, and the words
 *build*, *verify*, and *finding* below are always to be read in the track's terms.

package/web/board/agent-term.ts

@@ -0,0 +1,51 @@
+import { load } from "./api.ts";
+import { $ } from "./dom.ts";
+
+// again: something changed on the server, so the doc is read afresh: a note sent, a plan
+// written or a commit made elsewhere shows in nothing the page already holds. One /run
+// fetch per change while a run panel is open; a tab switch reuses the doc.
+// ---- the in-card agent (agent.launch: card). xterm.js is loaded the first time a
+// terminal is shown. One terminal is mounted at a time, in #pbody; a refresh that
+// finds it already showing this session leaves it alone, so it never reconnects.
+let termKey = null,
+  termOff = null,
+  termLib = null;
+export const where = (r) => (r.pty ? "running in its card" : "opened in your terminal");
+const termLoad = () =>
+  (termLib ||= new Promise((ok, no) => {
+    const l = document.createElement("link");
+    l.rel = "stylesheet";
+    l.href = "/term.css";
+    document.head.append(l);
+    const sc = document.createElement("script");
+    sc.src = "/term.js";
+    sc.onload = () => ok(window.kzTerm);
+    sc.onerror = () => {
+      termLib = null;
+      no();
+    };
+    document.head.append(sc);
+  }));
+export function termStop() {
+  if (termOff) termOff();
+  termOff = null;
+  termKey = null;
+  $("panel").classList.remove("wide");
+}
+export async function showTerm(c) {
+  const k = c.pty.key;
+  if (termKey === k && $("pbody").querySelector(".term")) return;
+  termStop();
+  termKey = k;
+  $("panel").classList.add("wide");
+  $("pbody").innerHTML = `<div class="term" aria-label="Agent terminal"></div>`;
+  let mount;
+  try {
+    mount = await termLoad();
+  } catch {
+    $("pbody").innerHTML = `<p style="color:var(--dim)">The terminal could not load.</p>`;
+    return;
+  }
+  if (termKey !== k) return;
+  termOff = mount($("pbody").querySelector(".term"), k, () => load(true));
+}

package/web/board/api.ts

@@ -0,0 +1,102 @@
+import { store } from "./store.ts";
+import { key, render } from "./cards.ts";
+import { $ } from "./dom.ts";
+import { close, ideaBody, open, openRun } from "./panel.ts";
+import { notifyUser, toast } from "./toast.ts";
+
+// The server writes notifier() from state.ts over a marker in board.html: one rule for both UIs.
+declare const due: (key: string, say: string | null, done: boolean, now: number) => boolean;
+
+// quiet: the server said something changed, nobody asked for a redraw.
+export async function load(quiet) {
+  let r;
+  try {
+    r = await fetch("/state" + (store.all ? "?all=1" : ""));
+  } catch {
+    toast(GONE);
+    return;
+  }
+  const was = store.openKey && store.S.cards.find((x) => key(x) === store.openKey);
+  store.S = await r.json();
+  {
+    const seen = new Map();
+    for (const c of store.S.cards) {
+      const b = key(c),
+        n = seen.get(b) || 0;
+      seen.set(b, n + 1);
+      c._k = n ? b + "#" + n : b;
+    }
+  }
+  for (const c of store.S.cards) {
+    if (c.kind !== "run" || c.archived) continue;
+    if (due(key(c), c.notice, c.status === "done", store.S.now)) notifyUser(c.notice);
+  }
+  // A redraw under a form being typed in would reset its fields and its focus.
+  if (!(quiet && store.mode && $("board").querySelector(".inl input"))) render();
+  // Run on an idea closed the panel: open the card on its agent once the board knows the session.
+  if (store.wantTerm && !store.openKey && !store.mode) {
+    const n = store.S.cards.find((x) => key(x) === store.wantTerm && x.pty);
+    if (n) {
+      store.wantTerm = null;
+      open(n);
+      return;
+    }
+  }
+  if (store.openKey) {
+    const c = store.S.cards.find((x) => key(x) === store.openKey),
+      ta = $("pbody").querySelector(".notes textarea");
+    if (ta && document.activeElement === ta) return;
+    if (!c) {
+      if (was && was.kind === "idea") follow(was);
+      return;
+    }
+    if (store.runDoc) openRun(c, true, true);
+    else if (c.kind === "idea") ideaBody(c);
+  }
+}
+// An idea's card goes when its run starts. Follow it to that run rather than keep
+// offering "Run again": the newest run in its project whose request holds the idea's
+// text, the rule boardCards() retires it by. No such run: close the panel.
+// ponytail: checks the five newest runs, one /run fetch each; a run that took the idea
+// further back than that closes the panel instead.
+async function follow(idea) {
+  const k = key(idea),
+    norm = (s) => s.toLowerCase().replace(/\s+/g, " ").trim(),
+    t = norm(idea.text);
+  for (const r of store.S.cards
+    .filter((x) => x.kind === "run" && x.state === idea.state)
+    .sort((a, b) => (b.moved ?? 0) - (a.moved ?? 0))
+    .slice(0, 5)) {
+    const d = await fetch(`/run/${encodeURIComponent(r.id)}?dir=${encodeURIComponent(r.state)}`)
+      .then((x) => x.json())
+      .catch(() => null);
+    if (store.openKey !== k) return;
+    if (norm(d?.request || "").includes(t)) {
+      open(r);
+      return;
+    }
+  }
+  if (store.openKey === k) close();
+}
+// A tab outliving its server would otherwise swallow every click: say so.
+const GONE = "The board server is not running — start it with kaizen web (or the shortcut), then reload.";
+export async function post(path, body) {
+  let r;
+  try {
+    r = await fetch(path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  } catch {
+    toast(GONE);
+    return { ok: false };
+  }
+  const j = await r.json().catch(() => ({}));
+  if (!r.ok) {
+    const m = j.error || j.why || "That did not work";
+    toast(m, { title: m.slice(0, 80), what: `POST ${path} failed (HTTP ${r.status}): ${m}` });
+    if (j.manual) console.log("run manually:", j.manual);
+  }
+  return j;
+}