kaizen-agent 1.0.0 → 1.2.0

package/README.md

@@ -5,6 +5,7 @@
 <p align="center"><i>Your AI agent shows you the plan before it does the work,<br>and a second agent checks what it did.</i></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">
@@ -13,6 +14,16 @@
 
 ---
 
+```bash
+# 1. Install Bun (prerequisite)
+curl -fsSL https://bun.sh/install | bash
+
+# 2. Install Kaizen
+bunx kaizen-agent
+```
+
+---
+
 ## The problem
 
 You ask an AI to do something real — write the launch email, draft the policy,
@@ -217,12 +228,28 @@ kaizen Done, and reviewed. Two things found:
 
 ## Install
 
+### Prerequisites: Bun
+
+Kaizen's installer and interactive dashboard require [Bun](https://bun.sh). If you don't have Bun installed yet:
+
+```bash
+# macOS, Linux, WSL
+curl -fsSL https://bun.sh/install | bash
+
+# or via Homebrew
+brew install oven-sh/bun/bun
+
+# or via npm
+npm install -g bun
+```
+
+### Install Kaizen
+
 ```bash
 bunx kaizen-agent
 ```
 
-It walks you through where to install, then tells you what to type next. Works with
-`npx` too. Restart your editor afterwards.
+It walks you through where to install, prompts for your workflow preset (`medium`, `low`, or `ultra`), then tells you what to type next. Restart your editor afterwards.
 
 Run from inside a project it asks whether to install globally or for that project
 alone; anywhere else — your home directory, a plain folder, a script — it installs

package/cli/dashboard.ts

@@ -1,6 +1,6 @@
 // What `kaizen` shows once it is installed: the state of this project's runs, and
 // the few things you would have opened a terminal to do.
-import { existsSync, readFileSync, readdirSync, appendFileSync, mkdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, appendFileSync, writeFileSync, mkdirSync, statSync, watch } from "node:fs";
 import { join, dirname, basename } from "node:path";
 import { homedir } from "node:os";
 
@@ -14,9 +14,11 @@ const c = {
   cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
   green: (s: string) => `\x1b[32m${s}\x1b[0m`,
   amber: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  // Red is spent on one thing only: a run that cannot move until the user acts.
+  red: (s: string) => rgb(232, 80, 80, s),
 };
 
-type Run = { id: string; stage: string; awaiting: string | null };
+type Run = { id: string; stage: string; awaiting: string | null; moved: number };
 
 // The mascot, rendered from assets/kaizen.jpg. Braille packs 2x4 dots into one
 // character, which is the only way outline art survives a downsample this far.
@@ -116,6 +118,56 @@ function findTerminal(cwd: string, fullCmd: string[]): { cmd: string[]; detached
   return null;
 }
 
+
+// ---------------------------------------------------------------- mouse
+
+// SGR reporting (1006), not X10: X10 encodes coordinates as single bytes and gives
+// up past column 223, which a five-column board reaches on any wide terminal.
+type MouseEv = { button: number; x: number; y: number; press: boolean };
+
+let mouseWanted = false;                           // what config.yml asked for
+let mouseArmed = false;                            // what the terminal is actually in
+
+function readMouse(rest: string): { ev: MouseEv; len: number } | null {
+  const m = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/.exec(rest);
+  if (!m) return null;
+  return {
+    ev: { button: +m[1]!, x: +m[2]!, y: +m[3]!, press: m[4] === "M" },
+    len: m[0].length,
+  };
+}
+
+const WHEEL_UP = 64, WHEEL_DOWN = 65;
+const isClick = (e: MouseEv) => e.press && e.button === 0;
+
+function mouseOn() {
+  if (!mouseWanted || mouseArmed) return;
+  process.stdout.write("\x1b[?1000h\x1b[?1006h");
+  mouseArmed = true;
+}
+
+function mouseOff() {
+  if (!mouseArmed) return;
+  process.stdout.write("\x1b[?1006l\x1b[?1000l");
+  mouseArmed = false;
+}
+
+// Ctrl-C calls process.exit, which unwinds no finally block anywhere. A terminal
+// left reporting spits escape junk at every click until `reset`, so this guard has
+// to survive an abrupt exit.
+process.on("exit", () => { if (mouseArmed) process.stdout.write("\x1b[?1006l\x1b[?1000l"); });
+
+// Off unless the config says otherwise: while reporting is on, the terminal cannot
+// select text with the mouse.
+function mouseFromConfig(state: string | null) {
+  for (const f of [state ? join(state, "config.yml") : null, join(home, ".kaizen", "config.yml")]) {
+    if (!f || !existsSync(f)) continue;
+    const m = /^\s*ui:\s*\n(?:\s*#.*\n)*\s*mouse:\s*(\S+)/m.exec(readFileSync(f, "utf8"));
+    if (m) return m[1] === "true";
+  }
+  return false;
+}
+
 export async function dashboard(
   repo: string,
   agents: string[],
@@ -123,6 +175,7 @@ export async function dashboard(
 ) {
   const { stdin, stdout } = process;
   const state = locate();
+  mouseWanted = mouseFromConfig(state);
   // Opening a project is what makes it known; nothing else asks the user to register.
   if (state && dirname(state) !== home) remember(dirname(state));
 
@@ -150,6 +203,7 @@ export async function dashboard(
       { key: "projects", label: "All projects", hint: "every project kaizen knows about" },
     ] : []),
     ...(state ? [
+      { key: "board", label: "Board", hint: "ideas and runs, by stage" },
       { key: "runs", label: "Runs", hint: "every run, and what each is waiting on" },
       { key: "backlog", label: "Backlog", hint: "what runs noticed and did not do" },
     ] : []),
@@ -162,15 +216,21 @@ export async function dashboard(
   ];
 
   let active = 0;
-  for (;;) {
-    const chosen = await menu();
-    if (chosen === "quit") return;
-    if (chosen === "projects") { await projectsView(); continue; }
-    if (chosen === "runs") { await runsView(); continue; }
-    if (chosen === "backlog") { await backlogView(); continue; }
-    const lines = await run(chosen);
-    if (lines?.length) await report(lines);
-    survey();                                   // an action may have changed what exists
+  mouseOn();
+  try {
+    for (;;) {
+      const chosen = await menu();
+      if (chosen === "quit") return;
+      if (chosen === "projects") { await projectsView(); continue; }
+      if (chosen === "board") { await boardView(); continue; }
+      if (chosen === "runs") { await runsView(); continue; }
+      if (chosen === "backlog") { await backlogView(); continue; }
+      const lines = await run(chosen);
+      if (lines?.length) await report(lines);
+      survey();                                 // an action may have changed what exists
+    }
+  } finally {
+    mouseOff();
   }
 
   // An action that has something to say says it here, on its own screen, rather
@@ -187,7 +247,11 @@ export async function dashboard(
       const once = (chunk: Buffer) => {
         const s = chunk.toString();
         if (s.includes("\x03")) process.exit(130);
-        key = s;
+        const mouse = readMouse(s);
+        // A click is a keypress on an any-key screen; the release that follows it
+        // must not dismiss the next screen too.
+        if (mouse && !isClick(mouse.ev)) return;
+        key = mouse ? "" : s;
         stdin.off("data", once);
         resolve();
       };
@@ -247,6 +311,26 @@ export async function dashboard(
         for (let i = 0; i < keys.length; i++) {
           const rest = keys.slice(i);
           if (rest.startsWith("\x03")) process.exit(130);
+          // Mouse reports are consumed here whether or not they mean anything, so
+          // an unexpected one is never read as a burst of keystrokes.
+          const mouse = readMouse(rest);
+          if (mouse) {
+            i += mouse.len - 1;
+            const { ev } = mouse;
+            if (ev.button === WHEEL_UP) move(-3);
+            else if (ev.button === WHEEL_DOWN) move(3);
+            else if (isClick(ev)) {
+              // Rows begin on the fourth line: blank, title, blank, then the list.
+              const real = top + (ev.y - 4);
+              const at = pickable.indexOf(real);
+              if (at < 0) continue;               // a heading, or empty space
+              // Click to select; click the selected one to act.
+              if (at === cursor) { chosen = real; stdin.off("data", onData); return resolve(); }
+              cursor = at;
+            } else continue;
+            draw();
+            continue;
+          }
           if (rest.startsWith("q") || rest === "\x1b" || rest.startsWith("\x7f") || rest.startsWith("\b")) {
             stdin.off("data", onData); return resolve();
           }
@@ -443,6 +527,466 @@ export async function dashboard(
     }
   }
 
+
+  // ------------------------------------------------------------------ board
+
+  // Ideas and runs on one screen, in stage columns. A run's stage belongs to
+  // kaizen and cannot be edited here -- a board that could drag one backwards
+  // would be lying about what happened. The one exception is abandoning a run,
+  // which is the user's decision either way.
+  async function boardView() {
+    let allProjects = false;
+    let cards: Card[] = [];
+    let col = 0, row = 0;
+    let top = 0;                                   // first visible line, board-wide
+    // Where each card actually landed on screen, rebuilt by whichever draw ran.
+    // Recording the frame beats recomputing its geometry: the two layouts place
+    // cards differently, and a stale guess after a resize clicks the wrong card.
+    type Hit = { y: number; x0: number; x1: number; col: number; row: number };
+    let hits: Hit[] = [];
+    // What each run was awaiting last time we looked, so a redraw can tell the
+    // difference between "still blocked" and "just became blocked".
+    const wasAwaiting = new Map<string, string | null>();
+    let first = true;
+
+    const states = () => (allProjects
+      ? [...knownProjects().map((d) => join(d, ".kaizen")), join(home, ".kaizen")]
+      : [state!]
+    ).filter((d, i, all) => all.indexOf(d) === i && existsSync(d));
+
+    const refresh = () => {
+      const now = Date.now();
+      const next: Card[] = [];
+      // Every project's requests, not just this state dir's: an idea in the global
+      // inbox becomes a run in whichever project the agent was started in.
+      const requests = [...knownProjects().map((d) => join(d, ".kaizen")), join(home, ".kaizen")]
+        .filter((d, i, all) => all.indexOf(d) === i && existsSync(d))
+        .flatMap(startedRuns);
+      for (const st of states()) {
+        const where = label(st);
+        for (const it of readInbox(st)) {
+          if (it.status !== "open" && it.status !== "started") continue;
+          // Retired once any run's request contains this text -- whoever started it.
+          // Checking `started` items only would leave every idea acted on outside the
+          // board sitting in IDEA forever, and typing `/kaizen ...` in a terminal is
+          // the common way a run begins.
+          if (requests.some((r) => r.includes(normalise(it.text)))) continue;
+          next.push(it.status === "started"
+            ? { kind: "idea", dot: c.dim("◌"), status: "starting", text: it.text, state: st, where, column: 1, awaiting: null, dim: true }
+            : { kind: "idea", dot: c.dim("·"), status: "idea", text: it.text, state: st, where, column: 0, awaiting: null, dim: false });
+        }
+        for (const r of readRuns(st)) {
+          const shown = dotFor(r, now);
+          const key = `${st}/${r.id}`;
+          const before = wasAwaiting.get(key);
+          if (!first && before === null && r.awaiting) {
+            notify("kaizen — waiting on you", `${short(r.id)} · ${r.awaiting}`);
+          }
+          wasAwaiting.set(key, r.awaiting);
+          next.push({
+            kind: "run", id: r.id, dot: shown.dot, status: shown.status, text: short(r.id), state: st, where, column: columnOf(r.stage),
+            awaiting: r.stage === "abandoned" ? null : r.awaiting,
+            dim: r.stage === "abandoned",
+          });
+        }
+      }
+      cards = next;
+      first = false;
+    };
+
+    const inColumn = (n: number) => cards.filter((k) => k.column === n);
+    const current = () => inColumn(col)[row];
+
+    const draw = () => {
+      const width = stdout.columns ?? 80;
+      // Five columns need room to say anything. Below that the board is worse
+      // than the list it replaces, so it becomes one.
+      if (width < 100) { drawNarrow(); return; }
+      const inner = Math.floor((width - 4) / COLUMNS.length) - 2;
+      const cols = COLUMNS.map((meta, n) => {
+        const lines: string[] = [];
+        const starts: number[] = [];
+        for (const k of inColumn(n)) {
+          starts.push(lines.length);
+          const chosen = n === col && inColumn(n)[row] === k;
+          const body = wrapTo(k.text, inner - 4);
+          for (const [i, line] of body.entries()) {
+            const marker = i === 0 ? (chosen ? c.cyan("›") : " ") : " ";
+            const dot = i === 0 ? k.dot : " ";
+            const painted = k.awaiting ? c.red(line) : k.dim ? c.dim(line) : line;
+            lines.push(`${marker} ${dot} ${painted}`);
+          }
+          if (allProjects && k.where !== "global") lines.push("    " + c.dim(cut(basename(k.where), inner - 4)));
+          lines.push("");
+        }
+        return { meta, lines, starts };
+      });
+
+      stdout.write("\x1b[H\x1b[2J");
+      const scope = allProjects ? "all projects" : label(state!);
+      stdout.write(`\n  ${c.bold("Board")}   ${c.dim(scope)}\n\n`);
+      stdout.write("  " + cols.map(({ meta }, n) =>
+        pad(n === col ? c.cyan(meta.title) : c.dim(meta.title), inner)).join("  ") + "\n");
+      stdout.write("  " + cols.map(() => c.dim("─".repeat(inner))).join("  ") + "\n");
+      const height = Math.max(4, (stdout.rows ?? 24) - 11);
+      const deep = Math.max(0, ...cols.map((x) => x.lines.length));
+      // The selected card drags the viewport with it; a cursor that can leave the
+      // screen is a cursor that deletes cards the user cannot see.
+      const sel = cols[col]!.starts[row] ?? 0;
+      if (sel < top) top = sel;
+      if (sel >= top + height) top = sel - height + 1;
+      top = Math.max(0, Math.min(top, Math.max(0, deep - height)));
+      hits = [];
+      for (let i = top; i < Math.min(deep, top + height); i++) {
+        // Cards begin on the sixth line: blank, title, blank, headings, rule.
+        const y = 6 + (i - top);
+        for (const [n, col_] of cols.entries()) {
+          const x0 = 3 + n * (inner + 2);
+          const owns = col_.starts.reduce((found, at, idx) => (at <= i ? idx : found), -1);
+          if (owns < 0) continue;
+          const ends = col_.starts[owns + 1] ?? col_.lines.length;
+          if (i >= ends || !(col_.lines[i] ?? "").trim()) continue;
+          hits.push({ y, x0, x1: x0 + inner - 1, col: n, row: owns });
+        }
+        stdout.write("  " + cols.map((x) => pad(x.lines[i] ?? "", inner)).join("  ") + "\n");
+      }
+      const above = top > 0, below = top + height < deep;
+      if (above || below) {
+        stdout.write(`  ${c.dim(`${above ? "↑" : " "} ${below ? "↓ more" : ""}`)}\n`);
+      }
+      stdout.write("\n" + footer(current()) + legend());
+    };
+
+    // Keys grouped by what they are for -- moving, acting, leaving -- separated by
+    // space rather than by middots, which made one long undifferentiated line.
+    const footer = (k?: Card) => {
+      const acts = k?.kind === "idea"
+        ? "n new  e edit  x reject  d delete  r run"
+        : k ? "n new idea  x abandon this run" : "n new idea";
+      const scope = allProjects ? "a this project" : "a all projects";
+      return `  ${c.dim("↑↓←→ move")}     ${c.dim(acts)}     ${c.dim(scope)}  ${c.dim("q back")}\n`;
+    };
+
+    // Only the states actually on the board: a legend for dots nothing is using is
+    // six items of noise under every screen.
+    const legend = () => {
+      const present = new Set(cards.map((k) => k.status));
+      const all: [string, string][] = [
+        ["running", `${c.cyan("●")} ${c.dim("running")}`],
+        ["stalled", c.dim("◐ stalled")],
+        ["starting", c.dim("◌ starting")],
+        ["waiting", `${c.amber("●")} ${c.red("waiting on you")}`],
+        ["done", c.dim("○ done")],
+        ["abandoned", c.dim("○ abandoned")],
+        ["idea", c.dim("· idea")],
+      ];
+      const parts = all.filter(([key]) => present.has(key)).map(([, text]) => text);
+      return parts.length ? "\n  " + parts.join("    ") + "\n" : "\n";
+    };
+
+    // Under 100 columns the board stacks: same cards, same keys, one list.
+    const drawNarrow = () => {
+      stdout.write("\x1b[H\x1b[2J");
+      stdout.write(`\n  ${c.bold("Board")}   ${c.dim("narrow terminal — stacked")}\n\n`);
+      hits = [];
+      // The header writes three newlines, so the first heading lands on line 4.
+      let y = 4;
+      for (const [n, meta] of COLUMNS.entries()) {
+        const items = inColumn(n);
+        if (!items.length) continue;
+        stdout.write(`  ${n === col ? c.cyan(meta.title) : c.dim(meta.title)}\n`);
+        y++;
+        for (const [idx, k] of items.entries()) {
+          const chosen = n === col && items[row] === k;
+          const text = k.awaiting ? c.red(k.text) : k.dim ? c.dim(k.text) : k.text;
+          stdout.write(`  ${chosen ? c.cyan("›") : " "} ${k.dot} ${cut(text, (stdout.columns ?? 80) - 8)}\n`);
+          hits.push({ y, x0: 1, x1: stdout.columns ?? 80, col: n, row: idx });
+          y++;
+        }
+        stdout.write("\n");
+        y++;
+      }
+      stdout.write("\n" + footer(current()) + legend());
+    };
+
+    const cardAt = (x: number, y: number) =>
+      hits.find((h) => h.y === y && x >= h.x0 && x <= h.x1) ?? null;
+
+    const clamp = () => {
+      col = Math.min(COLUMNS.length - 1, Math.max(0, col));
+      row = Math.min(Math.max(0, inColumn(col).length - 1), Math.max(0, row));
+    };
+
+    refresh();
+    stdout.write("\x1b[?1049h\x1b[?25l");
+    stdin.setRawMode(true);
+    stdin.resume();
+
+    // Kaizen writes these files from other processes; watching them is what makes
+    // the board move on its own.
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let watchers: ReturnType<typeof watch>[] = [];
+    const onChange = () => {
+      if (timer) clearTimeout(timer);
+      // A state.json being rewritten is briefly unparseable; readRuns already
+      // drops what it cannot parse, and the delay keeps that window off screen.
+      timer = setTimeout(() => { refresh(); clamp(); draw(); arm(); }, 150);
+    };
+
+    // fs.watch is not recursive here, and the file that actually changes is
+    // runs/<id>/state.json -- two levels down. Watching only the state dir and
+    // runs/ sees a new run appear and never sees an existing one move, so every
+    // run directory is watched too, and the set is rebuilt whenever anything
+    // fires in case the change was a run being created.
+    function arm() {
+      for (const w of watchers) { try { w.close(); } catch { /* already gone */ } }
+      watchers = [];
+      for (const st of states()) {
+        const runs = join(st, "runs");
+        const targets = [st, runs];
+        try { for (const id of readdirSync(runs)) targets.push(join(runs, id)); } catch { /* no runs yet */ }
+        for (const target of targets) {
+          try { if (existsSync(target)) watchers.push(watch(target, { persistent: false }, onChange)); }
+          catch { /* unwatchable path */ }
+        }
+      }
+    }
+    arm();
+
+    try {
+      draw();
+      for (;;) {
+        const key = await nextKey();
+        if (key === "quit") break;
+        if (key === "a") { allProjects = !allProjects; refresh(); clamp(); draw(); arm(); continue; }
+        if (key === "left") { col--; row = 0; clamp(); draw(); continue; }
+        if (key === "right") { col++; row = 0; clamp(); draw(); continue; }
+        if (key === "up") { row--; clamp(); draw(); continue; }
+        if (key === "down") { row++; clamp(); draw(); continue; }
+
+        const target = current();
+        if (key === "n") {
+          const text = await promptLine("New idea", "");
+          if (text) {
+            const st = target?.state ?? state!;
+            writeInbox(st, [...readInbox(st), { status: "open", text }]);
+          }
+          refresh(); col = 0; clamp(); draw(); continue;
+        }
+        if (!target) { draw(); continue; }
+        // Runs are otherwise read-only -- their stage belongs to kaizen -- but
+        // abandoning one is the user's decision to make, and /kaizen abort is the
+        // same single transition this writes.
+        if (target.kind === "run") {
+          if (key === "x" && target.id) {
+            const why = await promptLine(`Abandon ${target.text}? Reason`, "");
+            if (why) {
+              const failed = abandonRun(target.state, target.id, why);
+              if (failed) await outside(() => report([c.bold("Could not abandon"), "", c.dim(failed)]));
+            }
+            refresh(); clamp();
+          }
+          draw(); continue;
+        }
+        if (key === "e") {
+          const text = await promptLine("Edit idea", target.text);
+          if (text) replaceIdea(target, { status: "open", text });
+        } else if (key === "x") {
+          const why = await promptLine(`Reject: ${target.text}`, "");
+          // The spec requires a reason on a rejected item; no reason, no rejection.
+          if (why) replaceIdea(target, { status: "rejected", text: `${target.text} | ${why}` });
+        } else if (key === "d") {
+          if (await confirm(`Delete "${cut(target.text, 40)}"?`)) replaceIdea(target, null);
+        } else if (key === "r") {
+          const mode = await pickMode();
+          // "" is the default-mode choice, and must not leave a double space in
+          // the prompt the agent is launched with.
+          if (mode !== null) {
+            const request = `${mode} ${target.text}`.trim();
+            await outside(() => startBacklogItem(parseItem(request), target.state));
+            // Without this the idea stays open forever and the board shows the
+            // same work twice: once as an idea, once as the run it became.
+            replaceIdea(target, { status: "started", text: target.text });
+          }
+        }
+        refresh(); clamp(); draw();
+      }
+    } finally {
+      for (const w of watchers) { try { w.close(); } catch { /* already gone */ } }
+      watchers = [];
+      if (timer) clearTimeout(timer);
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdout.write("\x1b[?25h\x1b[?1049l");
+    }
+
+    // The only run state the board writes, and only this transition: stage becomes
+    // abandoned, awaiting clears. Every other field is preserved, so a run abandoned
+    // here still resumes and reads like one abandoned by /kaizen abort.
+    function abandonRun(st: string, id: string, why: string): string | null {
+      const file = join(st, "runs", id, "state.json");
+      try {
+        const run = JSON.parse(readFileSync(file, "utf8"));
+        if (run.stage === "abandoned") return "That run is already abandoned.";
+        run.stage = "abandoned";
+        run.awaiting = null;
+        run.updated = new Date().toISOString();
+        writeFileSync(file, JSON.stringify(run, null, 2) + "\n");
+        // The reason belongs in the record, not in state.json, whose shape is the
+        // resume contract every kaizen tool reads.
+        appendFileSync(join(st, "runs", id, "02-approval.md"),
+          `\n---\n\n## Abandoned\n\n${new Date().toISOString()} — abandoned from the board.\n\n${why}\n`);
+        return null;
+      } catch (err: any) {
+        return err?.message ?? String(err);
+      }
+    }
+
+    function replaceIdea(card: Card, next: InboxLine | null) {
+      const lines = readInbox(card.state);
+      const at = lines.findIndex((l) => (l.status === "open" || l.status === "started") && l.text === card.text);
+      if (at < 0) return;                            // changed underneath us; the redraw will show why
+      if (next) lines[at] = next; else lines.splice(at, 1);
+      writeInbox(card.state, lines);
+    }
+
+    // startBacklogItem paints its own screens, so the board steps out of the way
+    // and takes the terminal back afterwards.
+    async function outside(fn: () => Promise<void>) {
+      stdin.setRawMode(false);
+      stdout.write("\x1b[?25h\x1b[?1049l");
+      try {
+        await fn();
+      } finally {
+        // Without this the board's own finally restores a terminal that was never
+        // put back into raw mode, and the user is left with no echo.
+        stdout.write("\x1b[?1049h\x1b[?25l");
+        stdin.setRawMode(true);
+        stdin.resume();
+      }
+    }
+
+    // One chunk can carry several keys -- a held arrow, a paste, fast typing --
+    // so it is walked rather than compared whole.
+    function nextKey(): Promise<string> {
+      return new Promise((resolve) => {
+        const onData = (chunk: Buffer) => {
+          const keys = chunk.toString();
+          if (keys.includes("\x03")) process.exit(130);
+          const done = (v: string) => { stdin.off("data", onData); resolve(v); };
+          for (let i = 0; i < keys.length; i++) {
+            const rest = keys.slice(i);
+            const mouse = readMouse(rest);
+            if (mouse) {
+              i += mouse.len - 1;
+              const { ev } = mouse;
+              if (ev.button === WHEEL_UP) return done("up");
+              if (ev.button === WHEEL_DOWN) return done("down");
+              if (!isClick(ev)) continue;
+              const target = cardAt(ev.x, ev.y);
+              if (!target) continue;
+              // Click to select; click the selected card to act, which on an idea
+              // means the same thing r does.
+              if (target.col === col && target.row === row) return done("r");
+              col = target.col; row = target.row;
+              draw();
+              continue;
+            }
+            if (rest.startsWith("\x1b[D")) return done("left");
+            if (rest.startsWith("\x1b[C")) return done("right");
+            if (rest.startsWith("\x1b[A")) return done("up");
+            if (rest.startsWith("\x1b[B")) return done("down");
+            const ch = keys[i]!;
+            if (ch === "h") return done("left");
+            if (ch === "l") return done("right");
+            if (ch === "k") return done("up");
+            if (ch === "j") return done("down");
+            if (ch === "q" || ch === "\x1b" || ch === "\x7f" || ch === "\b") return done("quit");
+            if ("nexdra".includes(ch)) return done(ch);
+          }
+        };
+        stdin.on("data", onData);
+      });
+    }
+
+    async function promptLine(title: string, initial: string): Promise<string | null> {
+      let buf = initial;
+      const paint = () => {
+        stdout.write("\x1b[H\x1b[2J");
+        stdout.write(`\n  ${c.bold(title)}\n\n  ${buf}${c.cyan("█")}\n\n  ${c.dim("enter save · esc cancel")}\n`);
+      };
+      paint();
+      return new Promise((resolve) => {
+        const onData = (chunk: Buffer) => {
+          const keys = chunk.toString();
+          if (keys.includes("\x03")) process.exit(130);
+          const done = (v: string | null) => { stdin.off("data", onData); resolve(v); };
+          // Character by character: a held backspace or a paste arrives as one
+          // chunk, and comparing the whole chunk to "\x7f" writes the raw bytes
+          // into the file instead of deleting anything.
+          for (let i = 0; i < keys.length; i++) {
+            // Skipped whole, or its digits and semicolons land in the text.
+            const mouse = readMouse(keys.slice(i));
+            if (mouse) { i += mouse.len - 1; continue; }
+            const ch = keys[i]!;
+            if (ch === "\x1b") return done(null);
+            if (ch === "\r" || ch === "\n") return done(buf.trim() || null);
+            if (ch === "\x7f" || ch === "\b") { buf = buf.slice(0, -1); continue; }
+            // Anything else unprintable is dropped rather than stored: control
+            // bytes in an inbox line survive every later read of that file.
+            if (ch >= " " && ch !== "\x7f") buf += ch;
+          }
+          paint();
+        };
+        stdin.on("data", onData);
+      });
+    }
+
+    async function confirm(question: string): Promise<boolean> {
+      stdout.write("\x1b[H\x1b[2J");
+      stdout.write(`\n  ${c.bold(question)}\n\n  ${c.dim("y delete · any other key keep")}\n`);
+      const key = await nextRaw();
+      return key === "y" || key === "Y";
+    }
+
+    // full or lite, asked at the moment a run starts rather than fixed in config.
+    async function pickMode(): Promise<string | null> {
+      stdout.write("\x1b[H\x1b[2J");
+      stdout.write(`\n  ${c.bold("Start this run how?")}\n\n`);
+      stdout.write(`  ${c.cyan("f")}  full   ${c.dim("every stage its own cold agent — the reviewer starts blind")}\n`);
+      stdout.write(`  ${c.cyan("l")}  lite   ${c.dim("one session runs every stage — cheaper, review has seen the work")}\n`);
+      stdout.write(`  ${c.cyan("d")}  default${c.dim("  whatever config.yml says")}\n\n  ${c.dim("click a line, or any other key to cancel")}\n`);
+      // Options start on the fourth line: blank, title, blank, then f, l, d.
+      const key = await nextRaw((y) => ["f", "l", "d"][y - 4] ?? null);
+      return key === "f" ? "full" : key === "l" ? "lite" : key === "d" ? "" : null;
+    }
+
+    // A click arrives as two reports, press and release. The press is what opened
+    // this screen, so the release must not be read as its answer -- and a click on
+    // one of the offered lines answers it properly, via `clickable`.
+    function nextRaw(clickable?: (y: number) => string | null): Promise<string> {
+      return new Promise((resolve) => {
+        const onData = (chunk: Buffer) => {
+          const keys = chunk.toString();
+          if (keys.includes("\x03")) process.exit(130);
+          const done = (v: string) => { stdin.off("data", onData); resolve(v); };
+          for (let i = 0; i < keys.length; i++) {
+            const mouse = readMouse(keys.slice(i));
+            if (mouse) {
+              i += mouse.len - 1;
+              if (!clickable || !isClick(mouse.ev)) continue;
+              const answer = clickable(mouse.ev.y);
+              if (answer) return done(answer);
+              continue;
+            }
+            return done(keys.slice(i));
+          }
+        };
+        stdin.on("data", onData);
+      });
+    }
+  }
+
   async function startBacklogItem(it: Item, from: string) {
     const projectDir = from === join(home, ".kaizen")
       ? process.cwd()
@@ -511,9 +1055,13 @@ export async function dashboard(
   }
 
   async function menu() {
+  let actsTop = 0;                 // screen line of the first action row
+  let printed = 0;                 // lines this draw has written
+  const w = (text: string) => { printed += (text.match(/\n/g) ?? []).length; stdout.write(text); };
   const draw = () => {
+    printed = 0;
     const acts = actions();
-    stdout.write("\x1b[H\x1b[2J");
+    w("\x1b[H\x1b[2J");
 
     // The mascot sits beside the header rather than above it; stacked, it pushes
     // the runs -- the thing you opened this for -- below the fold on a short window.
@@ -552,7 +1100,7 @@ export async function dashboard(
       beside[at + 1] = c.dim(state ? tilde(dirname(state)) : "no project here");
       beside[at + 3] = c.dim(agents.join(", "));
     }
-    stdout.write("\n");
+    w("\n");
     if (wide) {
       // Cut what sits beside the mascot to the room left over. The agent list is
       // long and grows with every agent installed, and it wrapped here before the
@@ -562,11 +1110,11 @@ export async function dashboard(
         const r = Math.round(235 - t * 135);
         const g = Math.round(245 - t * 110);
         const b = Math.round(255 - t * 20);
-        stdout.write("  " + rgb(r, g, b, line.padEnd(gutter)) + cut(beside[i] ?? "", cols - gutter - 2) + "\n");
+        w("  " + rgb(r, g, b, line.padEnd(gutter)) + cut(beside[i] ?? "", cols - gutter - 2) + "\n");
       }
     } else {
-      stdout.write(`  ${c.bold("kaizen")} ${c.dim(version(repo))}   ${c.dim(state ? tilde(dirname(state)) : "no project here")}\n`);
-      stdout.write(`  ${c.dim(agents.join(", "))}\n`);
+      w(`  ${c.bold("kaizen")} ${c.dim(version(repo))}   ${c.dim(state ? tilde(dirname(state)) : "no project here")}\n`);
+      w(`  ${c.dim(agents.join(", "))}\n`);
     }
 
     if (state) {
@@ -606,28 +1154,31 @@ export async function dashboard(
         while (backLines.length < tall) backLines.push("");
         const left = panel("Runs", runLines, inner);
         const right = panel(`Backlog — ${items.length} open`, backLines, inner);
-        stdout.write("\n");
+        w("\n");
         for (let i = 0; i < Math.max(left.length, right.length); i++) {
-          stdout.write("  " + (left[i] ?? " ".repeat(inner + 2)) + " " + (right[i] ?? "") + "\n");
+          w("  " + (left[i] ?? " ".repeat(inner + 2)) + " " + (right[i] ?? "") + "\n");
         }
       } else {
-        stdout.write("\n");
-        for (const line of panel("Runs", runLines, cols - 8)) stdout.write("  " + line + "\n");
-        for (const line of panel(`Backlog — ${items.length} open`, backLines, cols - 8)) stdout.write("  " + line + "\n");
+        w("\n");
+        for (const line of panel("Runs", runLines, cols - 8)) w("  " + line + "\n");
+        for (const line of panel(`Backlog — ${items.length} open`, backLines, cols - 8)) w("  " + line + "\n");
       }
     } else {
-      stdout.write(`\n  ${c.dim("This folder has no .kaizen/. Set it up, or just ask your agent for something —")}\n`);
-      stdout.write(`  ${c.dim("the first run creates it.")}\n`);
+      w(`\n  ${c.dim("This folder has no .kaizen/. Set it up, or just ask your agent for something —")}\n`);
+      w(`  ${c.dim("the first run creates it.")}\n`);
     }
 
-    stdout.write("\n");
+    w("\n");
+    // Counted, not derived: the panels above change height with the terminal and
+    // with what exists, so nothing else can know where the actions start.
+    actsTop = printed + 1;
     for (const [i, a] of acts.entries()) {
       const on = i === active;
-      stdout.write(on
+      w(on
         ? `  ${c.cyan("›")} ${c.bold(a.label.padEnd(20))}${c.dim(a.hint)}\n`
         : `    ${c.dim(a.label)}\n`);
     }
-    stdout.write(`\n  ${c.dim("↑↓ move · enter choose · q or backspace quit")}\n`);
+    w(`\n  ${c.dim("↑↓ move · enter choose · q quit")}   ${c.dim("⭐ github.com/hfadhlullah/kaizen")}\n`);
   };
 
   stdout.write("\x1b[?1049h\x1b[?25l");
@@ -650,6 +1201,21 @@ export async function dashboard(
           chosen = acts[active]!.key;
           stdin.off("data", onData); return resolve();
         }
+        const mouse = readMouse(rest);
+        if (mouse) {
+          i += mouse.len - 1;
+          const { ev } = mouse;
+          if (ev.button === WHEEL_UP) active = (active - 1 + acts.length) % acts.length;
+          else if (ev.button === WHEEL_DOWN) active = (active + 1) % acts.length;
+          else if (isClick(ev)) {
+            const row = ev.y - actsTop;
+            if (row < 0 || row >= acts.length) continue;
+            if (row === active) { chosen = acts[active]!.key; stdin.off("data", onData); return resolve(); }
+            active = row;
+          } else continue;
+          draw();
+          continue;
+        }
         if (rest.startsWith("\x1b[A")) { active = (active - 1 + acts.length) % acts.length; i += 2; }
         else if (rest.startsWith("\x1b[B")) { active = (active + 1) % acts.length; i += 2; }
         else if (rest.startsWith("k")) active = (active - 1 + acts.length) % acts.length;
@@ -728,8 +1294,13 @@ function readRuns(state: string): Run[] {
   if (!existsSync(dir)) return [];
   return readdirSync(dir).flatMap((id) => {
     try {
-      const s = JSON.parse(readFileSync(join(dir, id, "state.json"), "utf8"));
-      return [{ id, stage: s.stage ?? "?", awaiting: s.awaiting ?? null }];
+      const file = join(dir, id, "state.json");
+      const s = JSON.parse(readFileSync(file, "utf8"));
+      // When the run last moved. Kaizen records no liveness signal, so the file's
+      // own mtime is the only evidence that anything is still working on it.
+      let moved = 0;
+      try { moved = statSync(file).mtimeMs; } catch { /* vanished mid-read */ }
+      return [{ id, stage: s.stage ?? "?", awaiting: s.awaiting ?? null, moved }];
     } catch { return []; }
   }).reverse();
 }
@@ -818,6 +1389,136 @@ function allBacklog(state: string) {
   return out;
 }
 
+
+// ---------------------------------------------------------------- board data
+
+type Card = {
+  kind: "idea" | "run";
+  id?: string;                                     // runs only: the directory name
+  dot: string;
+  status: string;                                  // what the legend calls this card
+  text: string;
+  state: string;
+  where: string;
+  column: number;
+  awaiting: string | null;
+  dim: boolean;
+};
+
+const COLUMNS = [
+  { key: "idea", title: "IDEA" },
+  { key: "plan", title: "PLANNING" },
+  { key: "build", title: "BUILDING" },
+  { key: "review", title: "REVIEW" },
+  { key: "done", title: "DONE" },
+];
+
+
+// A run is called running on the evidence that it moved recently; there is no PID
+// to ask. Anything in flight and older than this is stalled, not running -- the
+// difference the board exists to show.
+
+// The verbatim request of every run, normalised, so an idea that has become a run
+// can be retired from the board.
+// ponytail: reads each run's 00-request.md on every refresh; fine at tens of runs,
+// cache by mtime if a project ever has hundreds.
+function startedRuns(state: string): string[] {
+  const dir = join(state, "runs");
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const id of readdirSync(dir)) {
+    try { out.push(normalise(readFileSync(join(dir, id, "00-request.md"), "utf8"))); }
+    catch { /* no request file, or unreadable */ }
+  }
+  return out;
+}
+
+function normalise(text: string) {
+  return text.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+const RUNNING_WITHIN_MS = 30 * 60_000;
+
+// The status is what the legend lists; the dot is how it is drawn. Deriving one
+// from the other by comparing coloured strings breaks the moment a colour moves.
+function dotFor(r: Run, now: number): { dot: string; status: string } {
+  if (r.stage === "abandoned") return { dot: DIM + "○" + OFF, status: "abandoned" };
+  if (r.awaiting) return { dot: c.amber("●"), status: "waiting" };
+  if (r.stage === "done") return { dot: c.dim("○"), status: "done" };
+  return now - r.moved < RUNNING_WITHIN_MS
+    ? { dot: c.cyan("●"), status: "running" }
+    : { dot: c.dim("◐"), status: "stalled" };
+}
+
+// A stage this build has never heard of still belongs somewhere visible, and
+// PLANNING is the honest guess: the run has started and has not finished.
+function columnOf(stage: string) {
+  if (stage === "build") return 2;
+  if (stage === "review") return 3;
+  if (stage === "done" || stage === "abandoned") return 4;
+  return 1;
+}
+
+type InboxLine = { status: string; text: string };
+
+// Ideas with no run yet. Deliberately not backlog.md, which the spec defines as
+// an orphanage for items rescued from pruned runs, and not a run stub each.
+function readInbox(state: string): InboxLine[] {
+  const f = join(state, "inbox.md");
+  if (!existsSync(f)) return [];
+  return readFileSync(f, "utf8").split("\n")
+    .map((l) => /^-\s*(open|started|done|rejected):\s*(.+)$/.exec(l.trim()))
+    .filter((m): m is RegExpExecArray => !!m)
+    .map((m) => ({ status: m[1]!, text: m[2]!.trim() }));
+}
+
+// Whole-file rewrite. The board is the only writer today.
+// ponytail: single writer assumed; if a kaizen stage ever appends here too, this
+// needs a lock or an append-only journal.
+function writeInbox(state: string, lines: InboxLine[]) {
+  mkdirSync(state, { recursive: true });
+  const body = [
+    "# Inbox",
+    "",
+    "Ideas with no run yet. One line each, same format as a run's backlog.",
+    "",
+    ...lines.map((l) => `- ${l.status}: ${l.text}`),
+  ];
+  writeFileSync(join(state, "inbox.md"), body.join("\n") + "\n");
+}
+
+// Best effort: a machine without notify-send loses the notification, not the board.
+function notify(title: string, body: string) {
+  try {
+    if (!Bun.which("notify-send")) return;
+    Bun.spawn(["notify-send", title, body], {
+      stdin: "ignore", stdout: "ignore", stderr: "ignore", detached: true,
+    }).unref();
+  } catch { /* notifications are not worth an exception */ }
+}
+
+// wrap() above fills the terminal; a board column has its own width.
+function wrapTo(text: string, room: number) {
+  const out: string[] = [];
+  let line = "";
+  // A run id is a single word to any whitespace split, so without breaking on
+  // hyphens too it can never wrap and is always cut. Kept in the same order the
+  // text arrived, hyphen retained on the line it ends.
+  const words = text.split(/\s+/).flatMap((w) =>
+    w.length <= room ? [w] : w.split(/(?<=-)/));
+  for (const word of words) {
+    if (line && line.length + word.length + (line.endsWith("-") ? 0 : 1) > room) { out.push(line); line = word; }
+    else line = line ? (line.endsWith("-") ? line + word : `${line} ${word}`) : word;
+  }
+  if (line) out.push(line);
+  return out.length ? out.map((l) => cut(l, room)) : [""];
+}
+
+function pad(s: string, room: number) {
+  const body = cut(s, room);
+  return body + " ".repeat(Math.max(0, room - vis(body)));
+}
+
 // Printable width: a row is mostly colour codes by the time it is drawn, and they
 // occupy no columns.
 function vis(s: string) { return s.replace(/\x1b\[[0-9;]*m/g, "").length; }

package/cli/settings.ts

@@ -109,6 +109,7 @@ const SETTINGS: Setting[] = [
   { key: "state.keep_runs", values: ["5", "10", "20", "50"], help: "Completed runs kept before the oldest is pruned" },
   { key: "git.auto_commit", values: ["false", "true"], help: "Commit the work when a run finishes" },
   { key: "git.branch_before_implement", values: ["true", "false"], help: "Branch before building when on the default branch" },
+  { key: "ui.mouse", values: ["false", "true"], help: "Click to select, click again to act. While on, the terminal cannot select text with the mouse" },
   { key: "agent.default", values: ["auto", "claude", "codex", "agy", "opencode", "gemini"], help: "Default coding agent to launch from dashboard backlog" },
 ];
 
@@ -120,6 +121,12 @@ const c = {
   inv: (s: string) => `\x1b[7m${s}\x1b[0m`,
 };
 
+// Registered once at module scope, not per call: opening settings, going back and
+// opening it again would otherwise stack a listener each time, and Node starts
+// printing warnings into the alternate screen at eleven.
+let mouseArmed = false;
+process.on("exit", () => { if (mouseArmed) process.stdout.write("\x1b[?1006l\x1b[?1000l"); });
+
 export async function settings(repoRoot: string, standalone = true) {
   const file = locate();
   if (!existsSync(file)) {
@@ -155,15 +162,63 @@ export async function settings(repoRoot: string, standalone = true) {
   };
 
   stdout.write("\x1b[?1049h\x1b[?25l");      // alternate screen, hide cursor
+  const mouse = /^\s*ui:\s*\n(?:\s*#.*\n)*\s*mouse:\s*(\S+)/m.exec(readFileSync(file, "utf8"));
+  const mouseOn = mouse?.[1] === "true";
+  if (mouseOn) { stdout.write("\x1b[?1000h\x1b[?1006h"); mouseArmed = true; }
   stdin.setRawMode(true);
   stdin.resume();
   draw();
 
+  function cycle(step: number) {
+    const s = SETTINGS[active]!;
+    const text = readFileSync(file, "utf8");
+    if (s.key === "preset") {
+      const current = detectPreset(text, defaults);
+      const presets: PresetName[] = ["low", "medium", "ultra"];
+      const at = presets.indexOf(current as PresetName);
+      const next = presets[((at < 0 ? 0 : at) + step + presets.length) % presets.length]!;
+      const updated = applyPreset(text, next, defaults);
+      writeFileSync(file, updated);
+      saved = c.green(`applied preset: ${next}`);
+    } else {
+      const now = read(text, s.key) ?? s.values[0]!;
+      const at = s.values.indexOf(now);
+      const next = s.values[((at < 0 ? 0 : at) + step + s.values.length) % s.values.length]!;
+      let updated = write(text, s.key, next, defaults);
+      const detected = detectPreset(updated, defaults);
+      updated = write(updated, "preset", detected, defaults);
+      writeFileSync(file, updated);
+      // Only claim a save that happened. Reporting one that did not is worse
+      // than failing loudly: the setting reads back unchanged and nobody knows why.
+      saved = read(updated, s.key) === next
+        ? c.green(`saved ${s.key} = ${next || '""'} (preset: ${detected})`)
+        : `\x1b[33mcould not write ${s.key}\x1b[0m`;
+    }
+  }
+
   await new Promise<void>((resolve) => {
     const onData = (chunk: Buffer) => {
       const keys = chunk.toString();
       for (let i = 0; i < keys.length; i++) {
         const rest = keys.slice(i);
+        // Rows begin on the fourth line: blank, title, blank, then the settings.
+        const m = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/.exec(rest);
+        if (m) {
+          i += m[0].length - 1;
+          const button = +m[1]!, y = +m[3]!, press = m[4] === "M";
+          if (button === 64) active = (active - 1 + SETTINGS.length) % SETTINGS.length;
+          else if (button === 65) active = (active + 1) % SETTINGS.length;
+          else if (press && button === 0) {
+            const row = y - 4;
+            if (row < 0 || row >= SETTINGS.length) continue;
+            // Click to select; click the selected row to cycle it, which is what
+            // the right arrow already does.
+            if (row === active) { cycle(1); continue; }
+            active = row;
+          } else continue;
+          draw();
+          continue;
+        }
         // esc, q, backspace, and left-at-the-edge all mean "back to where I came
         // from" -- the settings screen is always something you opened from
         // somewhere else.
@@ -174,31 +229,7 @@ export async function settings(repoRoot: string, standalone = true) {
         if (rest.startsWith("\x1b[A")) { active = (active - 1 + SETTINGS.length) % SETTINGS.length; i += 2; }
         else if (rest.startsWith("\x1b[B")) { active = (active + 1) % SETTINGS.length; i += 2; }
         else if (rest.startsWith("\x1b[C") || rest.startsWith("\x1b[D") || rest.startsWith("\r")) {
-          const step = rest.startsWith("\x1b[D") ? -1 : 1;
-          const s = SETTINGS[active]!;
-          const text = readFileSync(file, "utf8");
-          if (s.key === "preset") {
-            const current = detectPreset(text, defaults);
-            const cycle: PresetName[] = ["low", "medium", "ultra"];
-            const at = cycle.indexOf(current as PresetName);
-            const next = cycle[((at < 0 ? 0 : at) + step + cycle.length) % cycle.length]!;
-            const updated = applyPreset(text, next, defaults);
-            writeFileSync(file, updated);
-            saved = c.green(`applied preset: ${next}`);
-          } else {
-            const now = read(text, s.key) ?? s.values[0]!;
-            const at = s.values.indexOf(now);
-            const next = s.values[((at < 0 ? 0 : at) + step + s.values.length) % s.values.length]!;
-            let updated = write(text, s.key, next, defaults);
-            const detected = detectPreset(updated, defaults);
-            updated = write(updated, "preset", detected, defaults);
-            writeFileSync(file, updated);
-            // Only claim a save that happened. Reporting one that did not is worse
-            // than failing loudly: the setting reads back unchanged and nobody knows why.
-            saved = read(updated, s.key) === next
-              ? c.green(`saved ${s.key} = ${next || '""'} (preset: ${detected})`)
-              : `\x1b[33mcould not write ${s.key}\x1b[0m`;
-          }
+          cycle(rest.startsWith("\x1b[D") ? -1 : 1);
           if (!rest.startsWith("\r")) i += 2;
         } else if (rest.startsWith("k")) active = (active - 1 + SETTINGS.length) % SETTINGS.length;
         else if (rest.startsWith("j")) active = (active + 1) % SETTINGS.length;
@@ -211,6 +242,7 @@ export async function settings(repoRoot: string, standalone = true) {
 
   stdin.setRawMode(false);
   stdin.pause();
+  if (mouseArmed) { stdout.write("\x1b[?1006l\x1b[?1000l"); mouseArmed = false; }
   stdout.write("\x1b[?25h\x1b[?1049l");      // restore cursor and screen
   // Returning to the dashboard means returning to its alternate screen, where a
   // line printed here would never be seen.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Staged workflow for AI agents \u2014 code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {

package/skills/kaizen/SKILL.md

@@ -94,6 +94,7 @@ whichever the user picks.
 | `review.write_memory` | `true`, `false` | Let the reviewer append lessons to `memory.md` |
 | `git.auto_commit` | `true`, `false` | Commit the work when a run finishes |
 | `git.branch_before_implement` | `true`, `false` | Branch before building when on the default branch |
+| `ui.mouse` | `false`, `true` | Click to select, click again to act; while on, the terminal cannot select text |
 | `agent.default` | `auto`, `claude`, `codex`, `agy`, `opencode`, `gemini` | Coding agent to launch from dashboard backlog |
 
 Rules for writing the file:

package/skills/kaizen/config.default.yml

@@ -129,6 +129,13 @@ git:
   # Ignored when the project is not a git repository.
   branch_before_implement: true
 
+ui:
+  # Mouse in the TUI: click a row or card to select it, click it again to open or
+  # run it, wheel to scroll. Off by default, and the reason is a real trade: while
+  # the TUI holds the mouse, the terminal cannot select text with it, so copying a
+  # run id out of the dashboard stops working until you leave.
+  mouse: false
+
 agent:
   # Default coding agent to launch from dashboard backlog (auto | claude | codex | agy | opencode | gemini).
   # auto picks Claude Code if installed, otherwise the first agent found on PATH.

package/skills/kaizen/spec-build.md

@@ -47,6 +47,15 @@ change works" into "nothing else broke". A check already failing before the chan
 not this run's finding; a check that passed before and fails after is, and it stops
 the stage.
 
+**Keep the working transcript small.** Everything the builder reads stays in its
+context and is re-read on every request that follows, so a full test-suite dump at the
+start of the stage is paid for again at every step after it. Pipe long output through
+a filter that keeps the decisive lines — the failure count, the failing test names, the
+first error — and read the full output only when a check actually fails. The same holds
+for reading material: open the manifest's paths at the ranges the plan names, not whole
+files, and never re-read a file this stage already changed. `03-impl.md` records the
+result, not the transcript.
+
 **Read the plan's File manifest instead of searching.** The planner already located
 every path this run touches. Search the material only for what the manifest does not
 cover, and note in `03-impl.md` what was missing from it.

package/skills/kaizen/spec-plan.md

@@ -66,11 +66,27 @@ The planner reads code but writes none. Its plan must contain:
    item; "every new query path has a covering test" is. A tier fixes the severity
    before the reviewer has an opinion, which is what stops the same class of problem
    being `high` in one run and `medium` in the next.
-7. **Risks** — what could break, what is irreversible, what needs a migration or a
+7. **Design direction, for any work with a visual surface** — a website, a landing
+   page, a UI, a deck, a printed piece. The direction is settled before the builder
+   starts, because it is the one decision that cannot be changed afterwards without
+   redoing the work: copy survives a re-skin, markup does not.
+
+   Look for it in the material first — a `design.md`, a design system, a brand or style
+   guide, an existing stylesheet with established tokens. Where one exists, the plan
+   names it and follows it, and asks nothing; the answer is already in the repository.
+
+   Where none exists, the direction is an *Open question* with 3-4 concrete options,
+   each named for what it signals rather than for its palette, so the user chooses a
+   positioning rather than a color. Bringing one direction and building it is the
+   failure this item exists to prevent: the planner has an opinion here as everywhere
+   else, but a visual direction chosen silently is a decision taken from the user, not
+   a proposal made to them.
+
+8. **Risks** — what could break, what is irreversible, what needs a migration or a
    backup taken first.
-8. **Open questions** — assumptions that survived the interview. If this list is
+9. **Open questions** — assumptions that survived the interview. If this list is
    non-empty, the approval must ask the user about it rather than defaulting.
-9. **Out of scope suggestions** — worthwhile things noticed but not asked for, each
+10. **Out of scope suggestions** — worthwhile things noticed but not asked for, each
    its own proposal. Never folded into a step.
 
 The plan is a proposal, not a decision. It never edits files, runs migrations, or
@@ -80,7 +96,7 @@ installs packages.
 fix loop reads it again per iteration, so a line written once is read five or six
 times. Sections 3 to 6 — the material to reuse, the file manifest, the steps, the
 verification — earn their length: they are what stop every later stage searching the
-material again, and cutting them costs more than it saves. Sections 0, 1, 7 and 9 are
+material again, and cutting them costs more than it saves. Sections 0, 1, 8 and 10 are
 read once by a human at the approval and should be as short as they can be and still
 be correct: a paragraph of framing, a paragraph of goal, the risks that are real, the
 questions that are open. An alternative rejected gets a line saying what and why, not

package/skills/kaizen/spec-review.md

@@ -48,6 +48,21 @@ operational work: missing prerequisites, absent rollback, steps that cannot be
 executed as written. The plan's Verification section says what was promised; the
 reviewer checks that promise was kept.
 
+**Keep the working transcript small.** Everything the reviewer reads stays in its
+context and is re-read on every request that follows, so the re-run suite dumped in
+full at check 4 is paid for again at every check after it. Pipe long output through a
+filter that keeps the decisive lines — the failure count, the failing test names, the
+first error — and read the full output only where a check actually fails, which is the
+only place the detail becomes a finding. The same holds for the work under review: open
+the manifest's paths at the ranges the plan names, and read the diff rather than the
+whole file wherever the finding would cite a changed line. `04-review.md` records the
+findings, not the transcript.
+
+This does not apply to check 3. Blast radius is the check whose whole point is what
+the diff does not contain, so it reads as widely as it needs to — every caller, every
+reader, whole files where that is what it takes. A cheaper blast-radius pass is not a
+cheaper review, it is the check not happening.
+
 Each finding is one line, numbered from 1 within the review:
 `<n>. <where>: <severity>: <problem>. <fix>. [G-nn]` Where is a `path:line` for code,
 and a section, page, or step reference otherwise. Severity is one of `critical`,