kaizen-agent 1.31.3 → 1.33.0

package/README.md

@@ -42,6 +42,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 }); });

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
@@ -49,10 +51,11 @@ export async function current(url: string) {
 }
 
 // The newest kaizen on npm, asked at most every six hours; a failed ask is retried
-// on the next one. Same registry call as npmLatest() in install.ts, which exports nothing.
+// on the next one; fresh (Settings' Check for updates) skips the cache. Same registry
+// call as npmLatest() in install.ts, which exports nothing.
 let latest: { v: string | null; at: number } = { v: null, at: 0 };
-async function npmLatest() {
-  if (latest.v && Date.now() - latest.at < 6 * 3600_000) return latest.v;
+async function npmLatest(fresh = false) {
+  if (!fresh && latest.v && Date.now() - latest.at < 6 * 3600_000) return latest.v;
   try {
     const r = await fetch("https://registry.npmjs.org/kaizen-agent/latest", { signal: AbortSignal.timeout(10000) });
     const v = ((await r.json()) as { version?: string }).version ?? null;
@@ -166,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 */ } }
@@ -292,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);
@@ -461,7 +470,7 @@ export async function web(repoDir: string, opts: Opts = {}) {
 
       // What this board runs and what npm has: the page shows an Update button on a newer one.
       if (req.method === "GET" && path === "/version") {
-        const v = await npmLatest();
+        const v = await npmLatest(url.searchParams.has("fresh"));
         return json({ version: VERSION, latest: v, update: !!v && newer(v, VERSION) });
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.31.3",
+  "version": "1.33.0",
   "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;
+}

package/web/board/approvals.ts

@@ -0,0 +1,100 @@
+import { store } from "./store.ts";
+import { where } from "./agent-term.ts";
+import { post } from "./api.ts";
+import { key, via } from "./cards.ts";
+import { $, esc } from "./dom.ts";
+import { openRun } from "./panel.ts";
+import { askNotify, toast } from "./toast.ts";
+
+// Resume: a run whose in-card agent ended, or one stalled with no progress, gets its agent
+// back on the run (its conversation, where the tool can resume one), in its card.
+export const resumable = (c) => c.status === "stalled" || !!(c.pty && !c.pty.alive);
+export async function resume(c, b) {
+  b.disabled = true;
+  askNotify();
+  const r = await post("/resume", { dir: c.state, id: c.id });
+  if (!r.ok) {
+    b.disabled = false;
+    return;
+  }
+  toast("Resumed, " + where(r) + ": " + via(r.agent));
+  if (r.pty) store.wantTerm = key(c);
+  if (store.openKey === key(c)) {
+    $("pfoot").innerHTML = "";
+    openRun(c, true);
+  }
+}
+export const APPROVAL = {
+    "approvals.plan": "The plan is ready. Read it in the Plan tab, then approve or send it back.",
+    "approvals.review": "The work is ready to check. Approve to finish it, or revise with what to change.",
+    findings: "The review has open findings. Approve as-is to accept them and finish, or fix selected findings first.",
+  },
+  decided = new Set(),
+  answer = (c) => key(c) + ":" + c.awaiting + ":" + c.moved;
+export async function decide(c, b, why, answers) {
+  b.disabled = true;
+  askNotify();
+  const r = await post("/decide", {
+    dir: c.state,
+    id: c.id,
+    awaiting: c.awaiting,
+    ...(why === undefined ? {} : { why }),
+    ...(answers ? { answers } : {}),
+  });
+  // A failed send keeps the footer, and with it a typed comment.
+  if (!r.ok) {
+    b.disabled = false;
+    return;
+  }
+  decided.add(answer(c));
+  toast((why === undefined ? "Approved" : "Sent back") + ", " + where(r) + ": " + via(r.agent));
+  if (r.pty) store.wantTerm = key(c);
+  if (store.openKey === key(c)) {
+    $("pfoot").innerHTML = "";
+    openRun(c, true);
+  }
+}
+export function confirmRevise(c) {
+  const foot = $("pfoot"),
+    plan = c.awaiting === "approvals.plan";
+  foot.innerHTML = `<div class="inl" style="flex:1"><div class="q">${plan ? "What should the plan do differently?" : "What should change in the work?"}</div><div class="q dim">Opens your agent on this run with your comment.${plan ? " It revises the plan and comes back here for approval." : " It changes the work, rechecks it and comes back here."}</div><textarea aria-label="Revise comment"></textarea><div class="row"><button class="btn ghost" data-a="c">Cancel</button><button class="btn pri" data-a="s">Send back</button></div></div>`;
+  const inp = foot.querySelector("textarea");
+  inp.focus();
+  foot.querySelector("[data-a=c]").onclick = () => {
+    foot.innerHTML = "";
+    openRun(c, true);
+  };
+  foot.querySelector("[data-a=s]").onclick = (e) => {
+    const why = inp.value.trim();
+    if (!why) {
+      toast("Say what should change");
+      inp.focus();
+      return;
+    }
+    decide(c, e.target, why);
+  };
+}
+// The plan's questions, answered with the approval: the recommended option preselected,
+// a note for what the options miss. Each answer reaches the agent as one line.
+export function confirmAnswers(c, qs) {
+  const foot = $("pfoot");
+  foot.innerHTML = `<div class="inl qa" style="flex:1"><div class="q">The plan asks ${qs.length === 1 ? "one question" : qs.length + " questions"}.</div><div class="q dim">Your answers go to your agent with the approval. It records them and builds the plan.</div>${qs.map((x, i) => `<fieldset><legend>${esc(x.q)}</legend>${x.options.map((o, j) => `<label><input type="${x.multi ? "checkbox" : "radio"}" name="q${i}" value="${j}"${o.rec || (!x.multi && !j && !x.options.some((p) => p.rec)) ? " checked" : ""}> ${esc(o.text)}</label>`).join("")}<input type="text" data-n="${i}" placeholder="Note (optional)" aria-label="Note: ${esc(x.q)}"></fieldset>`).join("")}<div class="row"><button class="btn ghost" data-a="c">Cancel</button><button class="btn pri" data-a="s">Approve with these answers</button></div></div>`;
+  foot.querySelector("[data-a=c]").onclick = () => {
+    foot.innerHTML = "";
+    openRun(c, true);
+  };
+  foot.querySelector("[data-a=s]").onclick = (e) =>
+    decide(
+      c,
+      e.target,
+      undefined,
+      qs.map((x, i) => {
+        const picked =
+            [...foot.querySelectorAll(`[name=q${i}]:checked`)]
+              .map((n) => `"${x.options[+n.value].label}"`)
+              .join(", ") || "none of the options",
+          note = foot.querySelector(`[data-n="${i}"]`).value.trim();
+        return `${x.q} — ${picked}${note ? "; " + note : ""}`;
+      }),
+    );
+}