kaizen-agent 1.5.3 → 1.5.5

package/cli/web.ts

@@ -4,7 +4,8 @@ import { existsSync, readFileSync, readdirSync, statSync, watch, type FSWatcher
 import { join, dirname } from "node:path";
 import {
   home, type Item, boardCards, knownProjects, remember, locate, label, tilde,
-  readInbox, writeInbox, replaceIdea, abandonRun, launchRun, parseItem, short,
+  readInbox, writeInbox, replaceIdea, abandonRun, launchRun, parseItem, short, setArchived, writeNotes,
+  appendNote, saveAttachment,
 } from "./state.ts";
 
 const PAGE = join(dirname(import.meta.dir), "web", "board.html");
@@ -47,6 +48,9 @@ export async function web(repoDir: string, opts: Opts = {}) {
       for (const c of clients) { try { c.enqueue("data: changed\n\n"); } catch { clients.delete(c); } }
     }, 200);
   };
+  // Dev: the page reloads itself when board.html 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 */ }
   const watchers: FSWatcher[] = [];
   const watchAll = () => {
     for (const w of watchers) { try { w.close(); } catch { /* gone */ } }
@@ -61,7 +65,7 @@ export async function web(repoDir: string, opts: Opts = {}) {
   const fingerprint = () => {
     let sum = 0;
     for (const dir of states(true)) {
-      for (const f of ["inbox.md", "backlog.md"]) { try { sum += statSync(join(dir, f)).mtimeMs; } catch { /* absent */ } }
+      for (const f of ["inbox.md", "backlog.md", "archive.md"]) { try { sum += statSync(join(dir, f)).mtimeMs; } catch { /* absent */ } }
       const runs = join(dir, "runs");
       if (!existsSync(runs)) continue;
       for (const id of readdirSync(runs)) { try { sum += statSync(join(runs, id, "state.json")).mtimeMs; } catch { /* absent */ } }
@@ -69,11 +73,26 @@ export async function web(repoDir: string, opts: Opts = {}) {
     return sum;
   };
   let last = fingerprint();
-  const poll = setInterval(() => { const now = fingerprint(); if (now !== last) { last = now; changed(); } }, 2000);
+  let seen = states(true).join("\n");
+  const poll = setInterval(() => {
+    // A project registered since start (a run launched into a fresh dir) gets a watcher too.
+    const now = states(true).join("\n"); if (now !== seen) { seen = now; watchAll(); }
+    const fp = fingerprint(); if (fp !== last) { last = fp; changed(); }
+  }, 2000);
 
-  const server = Bun.serve({
+  const BOOT = Date.now().toString(36);
+  const ping = setInterval(() => { for (const c of clients) { try { c.enqueue(": ping\n\n"); } catch { clients.delete(c); } } }, 8000);
+  // A launcher clicked while a board is already up should show that board, not die.
+  const port = opts.port ?? DEFAULT_PORT;
+  const server = (() => { try { return serve(); } catch (e) {
+    if ((e as { code?: string }).code !== "EADDRINUSE") throw e;
+    return null;
+  } })();
+  if (!server) { const url = `http://127.0.0.1:${port}/`; console.log(`\n  kaizen web already at ${url}\n`); if (opts.open !== false) await openApp(url); return; }
+
+  function serve() { return Bun.serve({
     hostname: "127.0.0.1",
-    port: opts.port ?? DEFAULT_PORT,
+    port,
     async fetch(req) {
       // Host first: a hostname rebound to 127.0.0.1 by an attacker's DNS still
       // arrives with that hostname in Host, and gets nothing.
@@ -111,13 +130,43 @@ export async function web(repoDir: string, opts: Opts = {}) {
           id, short: short(id), state: read("state.json"),
           request: read("00-request.md"), plan: read("01-plan.md"), approval: read("02-approval.md"),
           impl: read("03-impl.md"), review: read("04-review.md"), backlog: read("06-backlog.md"),
+          notes: read("notes.md"),
         });
       }
 
+      if (req.method === "GET" && path === "/settings") {
+        const { listSettings } = await import("./settings.ts");
+        return json(listSettings(repoDir));
+      }
+
+      if (req.method === "POST" && path === "/settings") {
+        if (!local(req)) return bad("cross-origin write refused", 403);
+        let body: any;
+        try { body = await req.json(); } catch { return bad("json body expected"); }
+        const { setSetting } = await import("./settings.ts");
+        const r = setSetting(repoDir, String(body.key ?? ""), String(body.value ?? ""));
+        return "error" in r ? bad(r.error) : json(r);
+      }
+
+      // Attachments only, never a run's own files: the path must sit under an
+      // attachments/ directory of a known state dir, with no way back up.
+      if (req.method === "GET" && path === "/file") {
+        const dir = url.searchParams.get("dir") ?? state;
+        const p = url.searchParams.get("p") ?? "";
+        if (!dir || !states(true).includes(dir)) return bad("unknown state dir", 404);
+        if (!/^(runs\/[\w.-]+\/)?attachments\/[\w.-]+$/.test(p)) return bad("bad path");
+        const f = join(dir, p);
+        if (!existsSync(f)) return bad("no such file", 404);
+        return new Response(Bun.file(f), { headers: { "cache-control": "private, max-age=3600" } });
+      }
+
       if (req.method === "GET" && path === "/events") {
         let ctrl: ReadableStreamDefaultController;
         const stream = new ReadableStream({
-          start(c) { ctrl = c; clients.add(c); c.enqueue("data: hello\n\n"); },
+          // The boot id lets the page tell a server restart from a dropped
+          // connection; only the former means new code. The ping keeps Bun's
+          // idle timeout from closing the stream every ten seconds.
+          start(c) { ctrl = c; clients.add(c); c.enqueue(`data: hello ${BOOT}\n\n`); },
           cancel() { clients.delete(ctrl); },
         });
         return new Response(stream, {
@@ -135,13 +184,16 @@ export async function web(repoDir: string, opts: Opts = {}) {
 
         if (path === "/inbox") {
           const text = String(body.text ?? "").trim();
+          // Absent means untouched; an empty string clears. replaceIdea keeps the
+          // old notes for any op that does not send them.
+          const notes = typeof body.notes === "string" ? body.notes.trim() : undefined;
           if (body.op === "add") {
             if (!text) return bad("empty idea");
-            writeInbox(dir, [...readInbox(dir), { status: "open", text }]);
+            writeInbox(dir, [...readInbox(dir), { status: "open", text, notes }]);
           } else if (body.op === "edit") {
             const next = String(body.next ?? "").trim();
             if (!text || !next) return bad("empty idea");
-            replaceIdea(dir, text, { status: "open", text: next });
+            replaceIdea(dir, text, notes === undefined ? { status: "open", text: next } : { status: "open", text: next, notes });
           } else if (body.op === "reject") {
             const why = String(body.reason ?? "").trim();
             if (!why) return bad("a rejection needs a reason");
@@ -158,6 +210,7 @@ export async function web(repoDir: string, opts: Opts = {}) {
           const kind = body.kind === "full" || body.kind === "lite" ? body.kind : "";
           if (!text) return bad("empty idea");
           const it: Item = parseItem(`${kind} ${text}`.trim());
+          it.notes = readInbox(dir).find((l) => l.status === "open" && l.text === text)?.notes;
           const r = launchRun(it, dir);
           if (r.ok) replaceIdea(dir, text, { status: "started", text });
           changed();
@@ -166,6 +219,54 @@ export async function web(repoDir: string, opts: Opts = {}) {
             : { ok: false, why: r.why, manual: r.manual, agent: r.agent }, r.ok ? 200 : 500);
         }
 
+        // Archive is a list beside the runs, never a move: a run keeps its directory
+        // and its state, and the board simply stops showing it.
+        if (path === "/archive") {
+          const archived = body.archived !== false;
+          if (typeof body.id === "string") {
+            if (!/^[\w.-]+$/.test(body.id)) return bad("bad run id");
+            setArchived(dir, body.id, archived);
+          } else if (typeof body.text === "string") {
+            const text = body.text.trim();
+            const lines = readInbox(dir);
+            const at = lines.findIndex((l) => l.text === text && (archived ? l.status === "open" : l.status === "archived"));
+            if (at < 0) return bad("no such idea", 404);
+            lines[at] = { ...lines[at]!, status: archived ? "archived" : "open" };
+            writeInbox(dir, lines);
+          } else return bad("id or text required");
+          changed();
+          return json({ ok: true });
+        }
+
+        // One chat message: text plus files (base64), each file saved and linked
+        // from the message so the note carries its own attachments.
+        if (path === "/note") {
+          const id = typeof body.id === "string" ? body.id : null;
+          if (id !== null && !/^[\w.-]+$/.test(id)) return bad("bad run id");
+          const text = typeof body.text === "string" ? body.text.trim() : "";
+          const files: { name: string; data: string }[] = Array.isArray(body.files) ? body.files : [];
+          let total = 0;
+          for (const f of files) total += (f.data?.length ?? 0);
+          if (total > 20_000_000) return bad("attachments over 15MB");
+          const links = files.map((f) => {
+            const bytes = Buffer.from(String(f.data).replace(/^data:[^,]*,/, ""), "base64");
+            const rel = saveAttachment(dir, id, String(f.name ?? "file"), bytes).replace(/\\/g, "/");
+            return (/\.(png|jpe?g|gif|webp|svg)$/i.test(rel) ? "!" : "") + `[${String(f.name ?? "file")}](${rel.replace(/^runs\/[^/]+\//, "")})`;
+          });
+          const note = [text, ...links].filter(Boolean).join("\n");
+          const failed = appendNote(dir, id !== null ? { id } : { text: String(body.for ?? "").trim() }, note);
+          changed();
+          return failed ? bad(failed, 404) : json({ ok: true });
+        }
+
+        if (path === "/notes") {
+          const id = String(body.id ?? "");
+          if (!/^[\w.-]+$/.test(id)) return bad("bad run id");
+          const failed = writeNotes(dir, id, String(body.text ?? ""));
+          changed();
+          return failed ? bad(failed, 404) : json({ ok: true });
+        }
+
         if (path === "/abort") {
           const id = String(body.id ?? "");
           const why = String(body.why ?? "").trim() || "abandoned from the web board";
@@ -178,7 +279,7 @@ export async function web(repoDir: string, opts: Opts = {}) {
 
       return new Response("not found", { status: 404 });
     },
-  });
+  }); }
 
   const url = `http://127.0.0.1:${server.port}/`;
   console.log(`\n  kaizen web  ${url}`);
@@ -187,7 +288,7 @@ export async function web(repoDir: string, opts: Opts = {}) {
   if (opts.open !== false) await openApp(url);
 
   await new Promise<void>((resolve) => {
-    const stop = () => { clearInterval(poll); for (const w of watchers) { try { w.close(); } catch { /* gone */ } } server.stop(true); resolve(); };
+    const stop = () => { clearInterval(poll); clearInterval(ping); for (const w of watchers) { try { w.close(); } catch { /* gone */ } } server.stop(true); resolve(); };
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
   });
@@ -233,3 +334,55 @@ function winChrome(exe: string) {
   for (const r of roots) { const p = join(r, sub[exe] ?? exe); if (existsSync(p)) return p; }
   return null;
 }
+
+// `kaizen web --shortcut`: a launcher the OS can find — Spotlight on macOS, the app
+// menu / super-space on Linux, the Desktop on Windows. Each one runs `kaizen web` with
+// the bun and script that ran this command, so it works for a git checkout and a
+// bunx install alike.
+export async function shortcut() {
+  const bun = process.execPath;
+  const script = Bun.argv[1]!;
+  const icon = join(dirname(import.meta.dir), "assets", "kaizen-logo.png");
+  const hasIcon = existsSync(icon);
+  const { mkdirSync, writeFileSync, chmodSync } = await import("node:fs");
+
+  if (process.platform === "darwin") {
+    const app = join(home, "Applications", "Kaizen.app", "Contents");
+    mkdirSync(join(app, "MacOS"), { recursive: true });
+    writeFileSync(join(app, "MacOS", "kaizen"), `#!/bin/sh\nexec ${q(bun)} ${q(script)} web --daemon\n`);
+    chmodSync(join(app, "MacOS", "kaizen"), 0o755);
+    writeFileSync(join(app, "Info.plist"), `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>CFBundleName</key><string>Kaizen</string>
+  <key>CFBundleIdentifier</key><string>dev.kaizen.web</string>
+  <key>CFBundleExecutable</key><string>kaizen</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>LSUIElement</key><true/>
+</dict></plist>
+`);
+    return `${tilde(join(home, "Applications", "Kaizen.app"))} — Spotlight finds it once indexed`;
+  }
+
+  if (process.platform === "win32") {
+    const lnk = join(home, "Desktop", "Kaizen.lnk");
+    const ps = `$s=(New-Object -ComObject WScript.Shell).CreateShortcut('${lnk}');$s.TargetPath='${bun}';$s.Arguments='"${script}" web --daemon';$s.WorkingDirectory='${home}';${hasIcon ? `$s.IconLocation='${icon}';` : ""}$s.Save()`;
+    await Bun.$`powershell -NoProfile -Command ${ps}`.quiet();
+    return lnk;
+  }
+
+  const dir = join(process.env["XDG_DATA_HOME"] ?? join(home, ".local", "share"), "applications");
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, "kaizen.desktop");
+  writeFileSync(file, `[Desktop Entry]
+Type=Application
+Name=Kaizen
+Comment=Kaizen board
+Exec=${q(bun)} ${q(script)} web --daemon
+${hasIcon ? `Icon=${icon}\n` : ""}Terminal=false
+Categories=Development;
+`);
+  return tilde(file);
+}
+
+const q = (s: string) => (/[\s"']/.test(s) ? `"${s.replace(/"/g, '\\"')}"` : s);

package/package.json

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

package/skills/kaizen/SKILL.md

@@ -61,7 +61,9 @@ If the user typed `/kaizen` with no argument and a run is in progress, treat it
    `~/.kaizen/` keyed by working directory. If neither exists and the user is starting
    work, run `/kaizen init` first: it creates `.kaizen/` with a copy of the `spec*.md`
    files and — where the folder is a git repository — the gitignore entry
-   (see [`adapters.md`](adapters.md)).
+   (see [`adapters.md`](adapters.md)). Also append the project folder's absolute path
+   to `~/.kaizen/projects` if not already listed: the board only retires an idea when
+   it can see the run, and it only looks in projects it knows.
 2. Read the config in this order, each file filling in the keys the one before it
    does not set: `.kaizen/config.yml`, then `~/.kaizen/config.yml`, then
    `config.default.yml` in this skill. A project usually has no `config.yml` of its
@@ -359,10 +361,11 @@ shown automatically.
         01-fix.md
         01-recheck.md
       06-backlog.md             # what this run deliberately did not do
+      notes.md                  # context attached from the board; the planner reads it
       state.json
 ```
 
-`state.json` is the resume point, and records the runner the run started with, so a
+`state.json` is the resume point, and records the runner and the agent the run started with, so a
 run picked up later keeps the shape it was reviewed under rather than silently
 changing because a setting moved:
 
@@ -371,6 +374,7 @@ changing because a setting moved:
   "id": "2026-09-02-add-oauth",
   "mode": "approve",
   "runner": "full",
+  "agent": "claude",
   "stage": "review",
   "awaiting": "approvals.review",
   "iteration": 1,

package/skills/kaizen/spec-build.md

@@ -65,6 +65,12 @@ deviations from the plan and why, verification carried out with its actual resul
 and anything deliberately left undone. Report failures honestly; a false claim of
 success poisons the review stage, which trusts this report.
 
+**A `## Preview` section says how to see the result.** For an app or service: the
+commands to start it locally and the URL to open, copied from the material's own README
+where one exists. For anything else — a document, copy, a runbook, a memo — the path
+to open, or the result itself when it fits in a screen. The board shows this section on
+the run's card, so a person can try the work without reading the rest of the report.
+
 **The gate block closes the stage.** `03-impl.md` ends with one line per gate item
 from the plan's Verification section:
 

package/skills/kaizen/spec-plan.md

@@ -6,9 +6,11 @@ planner's and the plan approval's contract. The builder and reviewer do not read
 ---
 ## Stage 1 — Plan
 
-**Agent:** planner. **Input:** `00-request.md` (including the track), `memory.md`, and
-the existing material — the codebase, the manuscript, the current campaign, whatever
-this run builds on. **Output:** `01-plan.md`.
+**Agent:** planner. **Input:** `00-request.md` (including the track), `notes.md` in
+the run directory when present — links, paths, and background the user attached from
+the board, binding like the request itself — `memory.md`, and the existing material —
+the codebase, the manuscript, the current campaign, whatever this run builds on.
+**Output:** `01-plan.md`.
 
 The request is usually one sentence. The planner's first job is to expand it — but by
 proposing, not by interrogating. It restates the problem, brings the nearest good
@@ -23,6 +25,18 @@ different work behind each, nothing available to break the tie — and even then
 its recommendation with the question. Questions the existing material can answer are
 never asked; that is the planner's own work.
 
+**Building from nothing is the exception: settle the foundation first.** When the
+track is a new product or app, there is no material to answer the questions that
+decide everything after them, and "wrong" for this track is a wrong foundation — the
+one thing a review cannot fix, because fixing it is a rebuild. Before the steps are
+written, the plan states a decision for each of: platform (web, mobile, PWA, native,
+CLI), who and how many will use it, stack, how it is distributed and reached, access
+(open, invite, accounts), what data is kept and where, and hosting. Each is either
+read from the request, proposed with its reason, or — where two answers lead to
+materially different builds — put to the user as an *Open question* with options,
+all in one round, before anything is built. Three quick questions and a default for
+the rest is how a run ends up writing the second app instead of the first.
+
 The goals stay the user's. The planner may propose a better solution to what was
 asked, or argue that the request as stated will not achieve what the user wants, but
 it may not widen the goal on its own. Anything beyond the request goes in *Out of

package/skills/kaizen/spec.md

@@ -101,9 +101,14 @@ sentence and either nods or says "no, this is a blog post". They are never asked
 categorize their own request up front.
 
 Write into `00-request.md`: the verbatim request, the deliverable, what done means,
-and what wrong means. Record in `state.json`: `id`, `mode`, `runner`, `track`,
+and what wrong means. Record in `state.json`: `id`, `mode`, `runner`, `agent`, `track`,
 `stage: "plan"`, `awaiting: null`.
 
+`agent` is the tool this run is happening in — `claude`, `codex`, `agy`, `opencode`,
+`gemini`, or `cursor` — written once at intake and never changed, so a board can say
+which agent to look for when a run is waiting. The tool running this stage knows what
+it is; no detection is needed.
+
 `runner` is read from config at intake and written down here, because it decides
 whether the stages that follow are separate agents or this one. A run resumed later
 keeps the runner it started with: a review done in the same session as the work is a