kaizen-agent 1.23.0 → 1.25.0

package/README.md

@@ -2,269 +2,46 @@
 <img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/banner.png" alt="kaizen" width="760">
 </div>
 
-<p align="center"><b>Stop finding your AI's mistakes next week.</b><br><i>See the plan before it starts. Get a second opinion when it is done.</i></p>
+<p align="center"><b>See the plan before your AI starts. Get a second opinion when it is done.</b></p>
 
-<p align="center">
-  <a href="https://github.com/hfadhlullah/kaizen/stargazers"><img alt="stars" src="https://img.shields.io/github/stars/hfadhlullah/kaizen?style=social"></a>
-  <a href="https://www.npmjs.com/package/kaizen-agent"><img alt="npm" src="https://img.shields.io/npm/v/kaizen-agent?color=2d50a5&label=npm"></a>
-  <a href="https://github.com/hfadhlullah/kaizen/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/kaizen-agent?color=2d50a5"></a>
-  <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-2d50a5">
-  <img alt="works with" src="https://img.shields.io/badge/Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Antigravity%20%C2%B7%20OpenCode%20%C2%B7%20Cursor%20%C2%B7%20Gemini%20CLI-2d50a5">
-</p>
+**The problem:** an AI agent starts writing before you agree on what it should do, then grades its own work.
 
----
-
-You ask an AI for something real: a feature, a launch email, a migration plan. It goes
-quiet, then hands you a finished thing. Did it understand you? What did it change? What
-is wrong that you won't notice until next week?
-
-**kaizen adds two checkpoints:**
-
-1. **Before:** you see the plan and say yes or no. Nothing is built until you approve.
-2. **After:** a *second* agent reviews the work. It never saw the first one's reasoning, so it has nothing to defend. It tells you what's wrong, numbered and graded.
-
-You decide what gets fixed.
-
-<p align="center"><img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/demo.gif" alt="kaizen shows a plan, you approve, a second agent reports two findings" width="760"></p>
+**Kaizen:** it plans first and waits for your approval, then an agent that never saw the work reviews it.
 
 ## Install
 
+### macOS and Linux
+
 ```bash
-# macOS · Linux · WSL
 curl -fsSL https://bun.sh/install | bash && ~/.bun/bin/bunx kaizen-agent
 ```
 
-```powershell
-# Windows PowerShell
-irm bun.sh/install.ps1 | iex; & "$env:USERPROFILE\.bun\bin\bunx.exe" kaizen-agent
-```
-
-Already have Bun? `bunx kaizen-agent`. It sets itself up for every agent you already use.
-
-Then, in any project:
-
-```
-/kaizen <what you want done>
-```
-
-That's it. No init and no config.
-
-kaizen needs an AI coding agent to run it, such as [Claude Code](https://docs.claude.com/en/docs/claude-code); install one first. Git is needed for the board's commit and push.
-
-## Use it
-
-There are three ways in, all on the same runs:
-
-| | How | What you do there |
-|---|---|---|
-| **Your agent** | `/kaizen <request>` in Claude Code, Codex, Cursor, … | Start a run and answer it in the chat. All commands are under [Commands](#commands). |
-| **The board** | `kaizen web` opens it in the browser; `kaizen` in a terminal. `kaizen web --shortcut` once adds a launcher: Spotlight on macOS, the app menu on Linux, a Desktop shortcut on Windows | Every project's ideas and runs. Start a run, approve or revise a plan, answer its questions, pick findings to fix, then commit and push. |
-| **Kaizen Bot** | The [desktop app](#download-the-app), or `bun start` in `bot/` | Chat with the board: ask what's waiting on you, hand teammates their asks. The app starts the board itself; from `bot/`, run `kaizen web` first. See [Kaizen Bot](#kaizen-bot). |
-
-Settings for a project or for all of them: `kaizen settings`. New version: `kaizen upgrade`.
-
-## See it
-
-```
-you    /kaizen rewrite the onboarding email — the new pricing starts on the 1st
-
-kaizen Here is the plan.
-
-       This is a customer email, not a policy page.
-       Done means: a customer knows what changes, when, and what to do — in one read.
-       Wrong means: a claim we cannot stand behind, or someone thinks they are being
-       charged more than they are.
-
-       What I will do:
-         1. Rewrite the opening so the date and the amount come first
-         2. Add one line on what happens if they do nothing
-         3. Keep the existing sign-off and legal footer untouched
-
-       Approve this plan?                    [ approve ]  [ change something ]
-
-you    approve
-
-kaizen Done, and reviewed. Two things found:
-
-       1. paragraph 2  high    "Your price will not change" is not true for annual
-                               plans renewing after the 1st. Fix: name both cases.
-       2. subject line low     14 words, cut off on mobile. Fix: lead with the date.
-
-       Fix them?                             [ both ]  [ just 1 ]  [ leave it ]
-```
-
-Nobody told the reviewer to hunt for untrue claims. It worked out that this was a customer
-email and reviewed it as one.
-
-<details>
-<summary><b>Code</b>: a bug in checkout</summary>
-
-```
-you    /kaizen the discount field lets you enter more than 100%
-
-kaizen Done, and reviewed.
-       Verified: ran the suite — 47 passed, 0 failed. Before the change: 44 passed.
-
-       1. cart.py:12  medium  A discount of exactly 100 now returns 0 instead of
-                              being rejected. Fix: use > not >=.
-```
-
-"It should work" is never accepted. The builder has to show the run and the numbers.
-
-</details>
-
-<details>
-<summary><b>Marketing</b>: a landing page for a launch</summary>
-
-```
-you    /kaizen landing page copy for the Pro tier launch
-
-kaizen Done, and reviewed. Three things found:
-
-       1. benefits 3   high    "Unlimited exports" — the shipped limit is 500/month.
-       2. headline     medium  Names a competitor. Legal reviews those; flagging, not fixing.
-       3. CTA          low     "Get started" appears on the free signup too. Ambiguous.
-```
+Already have Bun? Run `bunx kaizen-agent`.
 
-Every claim is checked against what actually ships.
+You also need an AI coding agent such as [Claude Code](https://docs.claude.com/en/docs/claude-code), and Git for the board's commit and push.
 
-</details>
+### Windows
 
-<details>
-<summary><b>Research</b>: a decision memo</summary>
-
-```
-you    /kaizen should we move from per-seat to usage-based pricing? write it up
-
-kaizen Done, and reviewed. Two things found:
-
-       1. section 3  high    The recommendation rests on 4 accounts out of 60. That
-                             is not stated where the conclusion is.
-       2. section 2  medium  Churned accounts were excluded with no reason given —
-                             they are the ones the model treats worst.
-```
+Windows support is still in beta. In PowerShell:
 
-No tests, no tone check. It looked for unsupported leaps and cherry-picked data.
-
-</details>
-
-<details>
-<summary><b>Operations</b>: a migration runbook</summary>
-
-```
-you    /kaizen runbook for moving the database to the new region on Saturday
-
-kaizen Done, and reviewed. Two things found:
-
-       1. step 7   critical  No rollback after the DNS cutover, and it is not marked
-                             as the point of no return. Fix: mark it, add the TTL wait.
-       2. step 3   high      Says "restore the backup" but never says which backup or
-                             how to confirm it is the right one.
+```powershell
+irm bun.sh/install.ps1 | iex; & "$env:USERPROFILE\.bun\bin\bunx.exe" kaizen-agent
 ```
 
-</details>
-
-## How it works
-
-| | Stage | |
-|---|---|---|
-| 1 | **Plan** | Reads your request, writes a plan. Changes nothing. |
-| 2 | **You approve** | Say yes, or say what to change. |
-| 3 | **Build** | Does the work, then *proves* it: runs the tests, checks each claim, walks each step. |
-| 4 | **Review** | A fresh agent checks the work and lists what's wrong. |
-| 5 | **Fix** | Serious findings get fixed and rechecked. The rest comes to you, never silently dropped. |
+Already have Bun? Run `bunx kaizen-agent`. As on macOS and Linux you need an AI coding agent; Git is only needed for the board's commit and push.
 
-## Why people use it
+## Use the board
 
-- **It isn't just for code.** Emails, docs, runbooks, research. kaizen works out what *done* and *wrong* mean for each request, so a book chapter is never reviewed for race conditions.
-- **The reviewer has nothing to defend.** It starts cold, sees only your request, the plan and the result, and finds what the builder talked itself past.
-- **A board for all your work.** Run `kaizen` in a terminal, or `kaizen web` in the browser. Ideas, plans, builds and reviews across every project, updating live. Start a run, approve or revise a plan, answer its questions, pick which findings to fix, then commit and push, all without opening a terminal.
-- **Requests come to you.** Paste a Google Sheet or Doc link and every request in it lands on the board as an idea.
-- **Notes and voice, offline.** A markdown notebook beside the board, plus dictation on every field. Whisper runs in the page, so audio never leaves your machine.
-- **Plain files, any agent.** Every run is a folder of markdown in `.kaizen/`. Start in Claude Code, finish in Codex, Antigravity, OpenCode, Cursor or Gemini CLI.
-
-<img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/c858bb6d666a65780d09c06032c8819489b87da5/assets/board.png" alt="kaizen web board" width="760">
-
-## Kaizen Bot
-
-A chat front end for your board, with AI teammates for every division. Ask **Chief** what's
-waiting on you, what's running, and what a plan or review says. Hand Sales Outbound,
-Marketing, Customer Service or Account Manager their team's asks, and they turn them into board ideas
-and runs. The board still does the real work: plan, approval, build, review.
-
-- **Nothing happens behind your back.** An agent may read the board, add an idea or a note, remember a fact and draft a message. Starting a run, approving a plan or fixing findings waits on a card until you click Approve. It never turns on Yolo and never commits.
-- **Nothing is ever sent.** Emails, posts and replies are drafts: approve one, then copy it or export them all as Markdown.
-- **Teammates and routines.** One agent can ask another, and any agent can run a task on a schedule: *every weekday at 7, brief me on the board*.
-
-<img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/bot.png" alt="Kaizen Bot: Account Manager holds a drafted email on a card until you approve it" width="760">
-
-Kaizen Bot lives in the repo's `bot/` folder, not the npm package. With the board running (`kaizen web`):
-
-```sh
-git clone https://github.com/hfadhlullah/kaizen && cd kaizen/bot
-cp .env.example .env      # set PROVIDER, MODEL and that provider's key
-bun start                 # http://127.0.0.1:7430
+```bash
+kaizen web
 ```
 
-### Download the app
-
-Kaizen Bot also comes as a desktop app, with no Bun or repo needed. Download yours from the
-[latest release](https://github.com/hfadhlullah/kaizen/releases/latest):
-
-| OS | File | Install |
-|---|---|---|
-| macOS | `Kaizen-Bot-macos-arm64.dmg` (Apple Silicon), `Kaizen-Bot-macos-x64.dmg` (Intel) | Open it, drag Kaizen Bot to Applications |
-| Windows | `Kaizen-Bot-Setup-windows-x64.exe` | Run the setup; it asks for your provider and API key |
-| Linux | `kaizen-bot-linux-x64`, `kaizen-bot-linux-arm64` | `chmod +x`, then run it |
-
-The first time, it creates `~/.kaizen-bot/.env` for your provider and key. After that it
-starts the board if `kaizen` is installed, and opens the chat in its own window; quit it from
-Settings. The app is unsigned, so macOS and Windows warn on first open. How to get past that,
-and how to uninstall, is in
-[Download the app](https://github.com/hfadhlullah/kaizen/blob/main/bot/README.md#download-the-app).
-
-Anthropic, OpenAI and Requesty are supported. Setup, privacy and settings are in the [Kaizen Bot README](https://github.com/hfadhlullah/kaizen/blob/main/bot/README.md).
-
-## Commands
-
-| Command | |
-|---|---|
-| `/kaizen <request>` | Start a run |
-| `/kaizen-plan <request>` | Plan only |
-| `/kaizen-auto <request>` | No stops; report at the end |
-| `/kaizen-lite <request>` | Every stage in this session: cheaper |
-| `/kaizen-full <request>` | Every stage its own cold agent: the independent review |
-| `/kaizen-review [target]` | Review something that already exists |
-| `/kaizen-approve` · `/kaizen-reject <reason>` | Answer whatever the run is waiting on |
-| `/kaizen-run` · `/kaizen-abort` | Carry on with an approved plan, or drop the run |
-| `/kaizen-status` · `/kaizen-backlog` | What's waiting, in flight, done, or left over |
-| `/kaizen-gather` | Pull new requests from your sources onto the board |
-| `/kaizen-config` | Change this project's settings |
-| `/kaizen-help` | The full card |
-
-In a terminal: `kaizen` (dashboard), `kaizen web` (board), `kaizen settings`, `kaizen upgrade`.
-
-Stuck on 1.18.0 or older? If `kaizen upgrade` says *could not pull* and stays on the old version, run this once: `bunx kaizen-agent@latest`. Your old install is kept as `~/kaizen.old`; from then on `kaizen upgrade` works by itself.
-
-## Bundled skills
-
-Installed alongside kaizen; your agent uses them when a request fits. Everything they make lives in `~/.kaizen/`.
-
-| Skill | What it makes |
-|---|---|
-| `story-deck` | A cinematic storytelling pitch deck (A5 `.pptx`): story first, the product last. Output in `~/.kaizen/decks/`. |
-| `story-video` | A publish-ready video from a prompt, photos, screenshots, a deck or footage: narration, captions, sound design, music, mastering, 16:9 and 9:16, revisable. Output in `~/.kaizen/videos/`. Works with no accounts (free voice, synthesized sounds); an ElevenLabs key unlocks natural voices. |
-
-Each skill has a `scripts/check.sh` that lists what it needs (Node, Python, ffmpeg, LibreOffice).
+<img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/board-v2.png" alt="kaizen board" width="760">
 
-## Learn more
+The board opens in your browser. The side menu holds the board, notes, the icebox of gathered requests and settings, with a light and dark switch. From there you can start a run, approve or revise its plan, pick which review findings to fix, then commit and push.
 
-- **[The guide](https://github.com/hfadhlullah/kaizen/blob/main/docs/guide.md)**: the board, request sources, notebook, settings, installer flags, uninstall
-- [Kaizen Bot](https://github.com/hfadhlullah/kaizen/blob/main/bot/README.md): the chat front end, its agents, routines and privacy
-- [`spec.md`](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/spec.md): the contract every stage follows
-- [`adapters.md`](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/adapters.md): running outside Claude Code, with Codex and Antigravity as the worked examples. OpenCode, Cursor and Gemini CLI load the same skill folder
-- Found a bug? `kaizen issue`, or *Report an issue* on the board, opens a GitHub bug form with your system details filled in. Nothing is sent until you press Submit on GitHub.
+To add a launcher (Spotlight on macOS, the app menu on Linux, a Desktop shortcut on Windows), run `kaizen web --shortcut` once.
 
 ## License
 
-MIT. *Kaizen (改善) is Japanese for continuous improvement: small changes, checked as you go.*
+MIT

package/agents/kaizen-reviewer.md

@@ -77,7 +77,9 @@ Two checks are universal:
    trust the report. A check that passed at that baseline and fails now is `high` at
    minimum, whatever else the work achieved. If the builder recorded no baseline, that
    absence is the finding: `03-impl.md: high: no baseline recorded, regression
-   unprovable. Run the existing suite and compare.`
+   unprovable. Run the existing suite and compare.` A `03-impl.md` with no
+   `## Preview` section, or none of its `### How to test` steps, is `medium`: the
+   user has no way to try the work.
 
 Then the track's own checks:
 

package/cli/build-web.ts

@@ -1,14 +1,16 @@
 // `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
+// 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
 // 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.
+// cli/notes.test.ts fails when a committed file no longer matches.
 import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
+import { copyFileSync, 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"];
+const SOURCES = ["web/notebook.ts", "web/notes-lib.ts", "web/term.ts"];
 export const OUT = join(root, "web", "notebook.js");
+export const TERM_OUT = join(root, "web", "term.js");
 
 // The sources and the exact dependency versions: a CodeMirror bump is a rebuild too.
 export function sourceHash() {
@@ -17,11 +19,16 @@ export function sourceHash() {
   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 */`;
+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) {
-  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`);
+  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" });
+    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`);
+  }
+  copyFileSync(join(root, "node_modules", "@xterm", "xterm", "css", "xterm.css"), join(root, "web", "term.css"));
 }

package/cli/install.ts

@@ -79,7 +79,7 @@ const found = (r: string) =>
 // Request sources. Dispatched on the first word alone and ahead of every flag
 // check below, so a label or a link that happens to read `web` or `uninstall` is
 // only ever a label.
-if (Bun.argv[2] === "sources" || Bun.argv[2] === "gather") {
+if (Bun.argv[2] === "sources" || Bun.argv[2] === "gather" || Bun.argv[2] === "icebox") {
   const { locate, label } = await import("./state.ts");
   const src = await import("./sources.ts");
   const state = locate() ?? join(home, ".kaizen");
@@ -87,8 +87,27 @@ if (Bun.argv[2] === "sources" || Bun.argv[2] === "gather") {
   const where = c.dim(`project  ${label(state)}`);
   const [, , cmd, op, url = "", ...rest] = Bun.argv;
   const line = (r: { url: string; ok: boolean; note: string }) => `  ${r.ok ? c.green("ok  ") : "fail"}  ${r.url}  ${c.dim(r.note)}`;
+  const waiting = c.dim("  new requests wait in the icebox — kaizen icebox");
   try {
-    if (cmd === "gather" && op === "--stdin") {
+    if (cmd === "icebox" && (op === "promote" || op === "dismiss")) {
+      // Ids only on the command line. The idea's text, which an agent may have written
+      // from outside text, comes from a file and never through a shell.
+      const ids = url.split(",").map((i) => i.trim()).filter(Boolean);
+      const at = rest.indexOf("--text-file");
+      if (at >= 0 && !rest[at + 1]) { console.log("\n  --text-file needs a path\n"); process.exit(1); }
+      const text = at >= 0 ? readFileSync(rest[at + 1]!, "utf8") : undefined;
+      const why = op === "promote" ? src.promote(state, ids, text) : src.dismiss(state, ids);
+      if (why) { console.log(`\n  ${why}\n`); process.exit(1); }
+      console.log(`\n  ${op === "promote" ? "promoted to Ideas" : "dismissed"}: ${ids.join(", ")}\n  ${where}\n`);
+    } else if (cmd === "icebox") {
+      const all = src.readIcebox(state);
+      const fresh = all.filter((s) => s.status === "new");
+      const names = new Map(src.readSources(state).map((s) => [s.url, s.label || s.url]));
+      console.log(`\n  ${where}  ${c.dim(`${fresh.length} waiting, ${all.length - fresh.length} promoted or dismissed`)}`);
+      console.log(fresh.length
+        ? "\n" + fresh.map((s) => `  ${s.id}  [${s.category || "Uncategorised"}]  ${s.text}  ${c.dim(`(${names.get(s.source) ?? s.source})`)}${s.notes ? "\n            " + c.dim(s.notes.replace(/\n/g, " · ")) : ""}`).join("\n") + "\n"
+        : `\n  the icebox is empty ${c.dim("— kaizen gather")}\n`);
+    } else if (cmd === "gather" && op === "--stdin") {
       // What an agent read from a link kaizen could not: one request per line, an
       // optional tab, then notes. Only for a link already listed.
       if (!src.readSources(state).some((s) => s.url === url)) { console.log(`
@@ -98,20 +117,22 @@ if (Bun.argv[2] === "sources" || Bun.argv[2] === "gather") {
         const [text = "", ...notes] = l.split("\t");
         return { text, notes: notes.join(" ") };
       });
-      console.log(line(src.record(state, url, src.ingest(state, url, items))));
+      console.log(line(src.record(state, url, src.ingest(state, url, items))) + "\n" + waiting);
     } else if (cmd === "gather") {
       const results = await src.gatherAll(state);
-      console.log(results.length ? results.map(line).join("\n") : `\n  no sources yet ${c.dim("— kaizen sources add <link>")}\n`);
+      console.log(results.length ? results.map(line).join("\n") + "\n" + waiting : `\n  no sources yet ${c.dim("— kaizen sources add <link>")}\n`);
       if (results.some((r) => !r.ok)) process.exit(1);
     } else if (op === "add" || op === "rm") {
-      const why = op === "add" ? src.addSource(state, url, rest.join(" ")) : src.removeSource(state, url);
+      const at = rest.indexOf("--category");
+      const category = at >= 0 ? rest.splice(at, 2)[1] : undefined;
+      const why = op === "add" ? src.addSource(state, url, rest.join(" "), category) : src.removeSource(state, url);
       if (why) { console.log(`\n  ${why}\n`); process.exit(1); }
       console.log(`\n  ${op === "add" ? "added" : "removed"} ${url}\n  ${where}\n`);
     } else {
       const list = src.readSources(state);
       console.log(`\n  ${where}`);
       console.log(list.length
-        ? "\n" + list.map((s) => `  ${s.url}${s.label ? `  ${s.label}` : ""}\n    ${c.dim(s.last ? `${s.last.at.slice(0, 16).replace("T", " ")}  ${s.last.note}` : "not gathered yet")}`).join("\n") + "\n"
+        ? "\n" + list.map((s) => `  ${s.url}${s.label ? `  ${s.label}` : ""}${s.category ? c.dim(`  [${s.category}]`) : ""}\n    ${c.dim(s.last ? `${s.last.at.slice(0, 16).replace("T", " ")}  ${s.last.note}` : "not gathered yet")}`).join("\n") + "\n"
         : `\n  no sources yet ${c.dim("— kaizen sources add <link>")}\n`);
     }
   } catch (e) { console.log(`\n  ${(e as Error).message}\n`); process.exit(1); }

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 } from "./build-web.ts";
+import { sourceHash, OUT, TERM_OUT } from "./build-web.ts";
 
 let state = "";
 beforeEach(() => { state = join(mkdtempSync(join(tmpdir(), "kaizen-notes-")), ".kaizen"); mkdirSync(state); });
@@ -215,7 +215,21 @@ test("the notebook's design tokens are the board's, line for line", () => {
   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()} `);
+test("the side menu is the board's on the notebook, line for line", () => {
+  const between = (f: string, from: string, to: string) => {
+    const s = readFileSync(join(root, "web", f), "utf8");
+    const at = s.indexOf(from);
+    expect(at).toBeGreaterThan(-1);
+    return s.slice(at, s.indexOf(to, at) + to.length);
+  };
+  for (const [from, to] of [["/* side menu:", "/* end side menu */"], ['<nav class="rail"', "</script>"]] as const)
+    expect(between("notes.html", from, to)).toBe(between("board.html", from, to));
+  const syms = (f: string) => ["board", "note", "link", "gear", "side", "sun", "moon"].map((n) => readFileSync(join(root, "web", f), "utf8").split("\n").find((l) => l.startsWith(`<symbol id="i-${n}"`)));
+  expect(syms("notes.html")).toEqual(syms("board.html"));
+  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)", () => {
+  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()} `);
 });

package/cli/pty.test.ts

@@ -0,0 +1,133 @@
+// The in-card agent (agent.launch: card): the setting, and the real board running a
+// fake agent in a pseudo-terminal, reached only from its own origin.
+import { test, expect } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { launchMode, closeSessions, readSessions } from "./state.ts";
+import { loginEnv } from "./pty.ts";
+
+const root = realpathSync(mkdtempSync(join(tmpdir(), "kaizen-pty-")));
+
+test("agent.launch: card unless the config chain says terminal, comments between keys allowed", () => {
+  const p = join(root, "mode");
+  mkdirSync(join(p, ".kaizen"), { recursive: true });
+  // The global file is the real one, so only the project file is varied here.
+  writeFileSync(join(p, ".kaizen", "config.yml"), "agent:\n  # where\n  default: auto\n  # the board\n  launch: terminal\n");
+  expect(launchMode(p)).toBe("terminal");
+  writeFileSync(join(p, ".kaizen", "config.yml"), "agent:\n  launch: card\n");
+  expect(launchMode(p)).toBe("card");
+  writeFileSync(join(p, ".kaizen", "config.yml"), "agent.launch: terminal\n");
+  expect(launchMode(p)).toBe("terminal");
+});
+
+test.skipIf(process.platform === "win32")("the board runs the agent in the card: output, input, origin check, and closing", async () => {
+  const homeDir = join(root, "home"), proj = join(homeDir, "a"), st = join(proj, ".kaizen"), bin = join(root, "bin");
+  for (const d of [st, join(homeDir, ".kaizen"), join(homeDir, ".claude"), bin]) mkdirSync(d, { recursive: true });
+  writeFileSync(join(homeDir, ".kaizen", "projects"), proj + "\n");
+  writeFileSync(join(st, "config.yml"), "agent:\n  default: claude\n  launch: card\n");
+  writeFileSync(join(st, "inbox.md"), "# Inbox\n\n- open: say hello\n");
+  // A stand-in for Claude Code: says how it was called, then echoes each line it is sent.
+  writeFileSync(join(bin, "claude"), '#!/bin/sh\necho "args:$*"\nwhile read x; do echo "got:$x"; done\n', { mode: 0o755 });
+  // Started as a launcher starts it: a bare PATH, the agent reachable only through
+  // the PATH the user's login shell builds.
+  const sh = join(root, "loginsh");
+  writeFileSync(sh, `#!/bin/sh\nPATH=${bin}:$PATH exec /bin/sh -c "$4"\n`, { mode: 0o755 });
+  const port = 20000 + Math.floor(Math.random() * 20000);
+  const repo = join(import.meta.dir, "..");
+  const proc = Bun.spawn([process.execPath, join(repo, "cli", "install.ts"), "web", "--port", String(port), "--no-open", "--foreground"], {
+    cwd: proj, stdout: "ignore", stderr: "ignore",
+    env: { ...process.env, HOME: homeDir, USERPROFILE: homeDir, KAIZEN_HOME: repo, CLAUDE_CONFIG_DIR: join(homeDir, ".claude"),
+      PATH: "/usr/bin:/bin", SHELL: sh, DISPLAY: "", WAYLAND_DISPLAY: "", TERMINAL: "", TMUX: "" },
+  });
+  try {
+    const at = `http://127.0.0.1:${port}`;
+    for (let i = 0; ; i++) { try { await fetch(at + "/state"); break; } catch { if (i > 100) throw new Error("board did not start"); await Bun.sleep(50); } }
+
+    // G-02: no terminal window anywhere (none could be found), yet the launch worked.
+    const r = await (await fetch(at + "/run", { method: "POST", body: JSON.stringify({ dir: st, text: "say hello" }) })).json() as any;
+    expect(r.ok).toBe(true);
+    expect(r.pty).toMatch(/^[\w-]+$/);
+    const card = ((await (await fetch(at + "/state")).json()) as any).cards.find((c: any) => c.text === "say hello");
+    expect(card.pty).toEqual({ key: r.pty, alive: true });
+
+    // G-01: no Origin, a foreign one, and another local port are all refused.
+    const url = `${at}/pty?key=${r.pty}`, up = { upgrade: "websocket", connection: "Upgrade", "sec-websocket-version": "13", "sec-websocket-key": "dGhlIHNhbXBsZSBub25jZQ==" };
+    expect((await fetch(url, { headers: up })).status).toBe(403);
+    expect((await fetch(url, { headers: { ...up, origin: "https://evil.example" } })).status).toBe(403);
+    expect((await fetch(url, { headers: { ...up, origin: `http://127.0.0.1:${port + 1}` } })).status).toBe(403);
+    expect((await fetch(`${at}/pty?key=nope`, { headers: { ...up, origin: at } })).status).toBe(404);
+
+    // The board's own origin: the screen so far, then typing goes through.
+    let seen = "";
+    const ws = new WebSocket(url.replace("http", "ws"), { headers: { origin: at } } as any);
+    const closed = new Promise((ok) => { ws.onclose = ok; });
+    ws.onmessage = (e) => { seen += String(e.data); };
+    await new Promise((ok, no) => { ws.onopen = ok; ws.onerror = no; });
+    const until = async (re: RegExp) => { for (let i = 0; i < 100 && !re.test(seen); i++) await Bun.sleep(30); expect(seen).toMatch(re); };
+    await until(/args:.*--session-id [\w-]+ .*\/kaizen say hello/);
+    ws.send(JSON.stringify({ t: "r", c: 100, r: 30 }));
+    ws.send(JSON.stringify({ t: "i", d: "ping\r" }));
+    await until(/got:ping/);
+
+    // G-03: the session record is the usual one, its PID file the agent's own, so a
+    // run that owns it closes it like a terminal launch.
+    const [s] = readSessions(st);
+    expect(s!.cmd).toBe("claude");
+    const pid = Number(readFileSync(join(st, "sessions", s!.key + ".pid"), "utf8"));
+    expect(process.kill(pid, 0)).toBe(true);
+    mkdirSync(join(st, "runs", "r1"), { recursive: true });
+    writeFileSync(join(st, "runs", "r1", "00-request.md"), "say hello\n");
+    expect(closeSessions(st, "r1")).toBe(1);
+    // The page tells an agent that ended from a board that went away by this reason.
+    expect(((await closed) as CloseEvent).reason).toBe("ended");
+    expect(existsSync(join(st, "sessions", s!.key + ".pid"))).toBe(false);
+    let gone = false;
+    for (let i = 0; i < 50 && !gone; i++) { try { process.kill(pid, 0); await Bun.sleep(30); } catch { gone = true; } }
+    expect(gone).toBe(true);
+
+    // Resume: refused while the run waits on a decision, then the run's own conversation
+    // continues in a new in-card session, and a second press is refused while it lives.
+    const resume = async () => { const x = await fetch(at + "/resume", { method: "POST", body: JSON.stringify({ dir: st, id: "r1" }) }); return { status: x.status, ...(await x.json() as any) }; };
+    writeFileSync(join(st, "runs", "r1", "state.json"), JSON.stringify({ id: "r1", stage: "plan", awaiting: "approvals.plan" }));
+    expect((await resume()).status).toBe(409);
+    writeFileSync(join(st, "runs", "r1", "state.json"), JSON.stringify({ id: "r1", stage: "build", awaiting: null }));
+    // Claude resumes by id only when the conversation's transcript is on disk.
+    const tr = join(homeDir, ".claude", "projects", proj.replace(/[^A-Za-z0-9]/g, "-"));
+    mkdirSync(tr, { recursive: true });
+    writeFileSync(join(tr, s!.sessionId + ".jsonl"), "{}\n");
+    const again = await resume();
+    expect(again).toMatchObject({ status: 200, ok: true });
+    seen = "";
+    const ws2 = new WebSocket(`${at}/pty?key=${again.pty}`.replace("http", "ws"), { headers: { origin: at } } as any);
+    ws2.onmessage = (e) => { seen += String(e.data); };
+    await new Promise((ok, no) => { ws2.onopen = ok; ws2.onerror = no; });
+    await until(new RegExp(`args:.*--resume ${s!.sessionId} .*/kaizen run r1: continue`));
+    expect((await resume()).status).toBe(409);
+    ws2.close();
+  } finally { proc.kill(); await proc.exited; }
+}, 30_000);
+
+test.skipIf(process.platform === "win32")("a board started from a launcher takes the login shell's PATH and exports, not its own bare ones", () => {
+  const bin = join(root, "shells");
+  mkdirSync(bin, { recursive: true });
+  // A profile that greets on stdout before the environment, as many do.
+  writeFileSync(join(bin, "fakesh"), '#!/bin/sh\necho "welcome back"\n[ "$1 $2 $3" = "-l -i -c" ] || exit 9\nFROM_PROFILE=yes PATH=/opt/brew/bin:$PATH PWD=/elsewhere exec /bin/sh -c "$4"\n', { mode: 0o755 });
+  writeFileSync(join(bin, "badsh"), "#!/bin/sh\nexit 1\n", { mode: 0o755 });
+  const e = loginEnv(join(bin, "fakesh"))!;
+  expect(e.FROM_PROFILE).toBe("yes");
+  expect(e.PATH.split(":")[0]).toBe("/opt/brew/bin");
+  expect(loginEnv(join(bin, "badsh"))).toBeNull();
+  expect(loginEnv(join(bin, "missing"))).toBeNull();
+  // Into a process started with a launcher's bare PATH and its own setting: the
+  // board's PATH first, the profile's added after it, the board's own variable not overridden,
+  // the shell's PWD not taken.
+  const pty = JSON.stringify(join(import.meta.dir, "pty.ts"));
+  const out = Bun.spawnSync([process.execPath, "-e", `import { adoptLoginEnv } from ${pty}; adoptLoginEnv(); console.log(JSON.stringify([process.env.PATH, process.env.FROM_PROFILE, process.env.KEEP, process.env.PWD]))`], {
+    env: { SHELL: join(bin, "fakesh"), PATH: "/usr/bin:/bin", KEEP: "mine", FROM_PROFILE: undefined as any, HOME: root },
+  }).stdout.toString();
+  const [path, from, keep, pwd] = JSON.parse(out);
+  expect(path.split(":").slice(0, 3)).toEqual(["/usr/bin", "/bin", "/opt/brew/bin"]);
+  expect([from, keep]).toEqual(["yes", "mine"]);
+  expect(pwd).not.toBe("/elsewhere");
+});