kaizen-agent 1.9.4 → 1.11.0

package/cli/web.ts

@@ -1,12 +1,12 @@
 // `kaizen web`: the board in a browser. A loopback HTTP server over state.ts and
 // one HTML page; the page never sees the filesystem, only JSON.
 import { existsSync, readdirSync, statSync, watch, appendFileSync, mkdirSync, type FSWatcher } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, resolve, sep } from "node:path";
 import {
   home, type Item, type Card, boardCards, knownProjects, remember, locate, label, tilde, searchRoots, findProjects,
-  readInbox, writeInbox, replaceIdea, abandonRun, launchRun, parseItem, short, setArchived, writeNotes,
+  readInbox, writeInbox, replaceIdea, abandonRun, launchRun, parseItem, agentChoices, projectOf, KNOWN_AGENTS, plainModel, short, setArchived, writeNotes,
   appendNote, saveAttachment, pidOnPort, readText, cmdExe, sysExe, powershellExe, runGit, cardsGit, readCommit, commitPush, notice, notifier, LOGO,
-  reviewFindings, pickFindings, fixPrompt,
+  reviewFindings, pickFindings, fixPrompt, approvalPrompt, nativePath, closeSessions, sweepSessions, issueUrl,
 } from "./state.ts";
 import { readSources, addSource, removeSource, moveSource, gatherSource, gatherAll, gatherDirs, due } from "./sources.ts";
 import { listNotes, saveNote, renameNote, deleteNote, boardIndex, linksTo } from "./notes.ts";
@@ -48,14 +48,24 @@ export async function web(repoDir: string, opts: Opts = {}) {
   let state = locate();
   if (state && dirname(state) !== home) remember(dirname(state));
   let project = state ? label(state) : null;
+  // The "Projects folder" setting, resolved; empty when unset.
+  const projectsRoot = async () => {
+    const { listSettings } = await import("./settings.ts");
+    let root = listSettings(repoDir).rows.find((r) => r.key === "board.projects_dir")?.value ?? "";
+    if (root.startsWith("~")) root = home + root.slice(1);
+    // Typed on Windows as d:\work, D:/work or Git Bash /d/work: one spelling, the one
+    // remember() and the known-project check use, or /d/work reads as C:\d\work.
+    return root ? resolve(nativePath(root)) : "";
+  };
+  // .kaizen is not a sign of one: a group folder that was chosen once has it, and
+  // must keep showing what is inside.
+  const isProject = (d: string) => [".git", "package.json"].some((m) => existsSync(join(d, m)));
   // Folders under the "Projects folder" setting that have no .kaizen yet, offered in
   // the project list so one can be chosen without a terminal. A folder that does not
   // look like a project itself (no .git, no package.json) is taken for a group of
-  // them, and its own folders are offered too: ~/Projects/<client>/<project>.
+  // them, and its own folders are offered instead: ~/Projects/<client>/<project>.
   const fresh = async () => {
-    const { listSettings } = await import("./settings.ts");
-    let root = listSettings(repoDir).rows.find((r) => r.key === "board.projects_dir")?.value ?? "";
-    if (root.startsWith("~")) root = home + root.slice(1);
+    const root = await projectsRoot();
     if (!root) return [];
     const dirs = (d: string) => {
       try {
@@ -63,11 +73,8 @@ export async function web(repoDir: string, opts: Opts = {}) {
           .map((n) => join(d, n)).filter((p) => { try { return statSync(p).isDirectory(); } catch { return false; } });
       } catch { return []; }
     };
-    // .kaizen is not a sign of one: a group folder that was chosen once has it, and
-    // must keep showing what is inside.
-    const isProject = (d: string) => [".git", "package.json"].some((m) => existsSync(join(d, m)));
     // One already set up but never opened joins the known projects instead.
-    return dirs(root).flatMap((d) => isProject(d) ? [d] : [d, ...dirs(d)])
+    return dirs(root).flatMap((d) => isProject(d) ? [d] : dirs(d))
       .filter((d) => existsSync(join(d, ".kaizen")) ? (remember(d), false) : true).sort();
   };
 
@@ -129,7 +136,10 @@ export async function web(repoDir: string, opts: Opts = {}) {
   };
   let last = fingerprint();
   let seen = states(true).join("\n");
+  let ticks = 0;
   const poll = setInterval(() => {
+    // Once a minute: windows of runs finished or abandoned past the grace are closed.
+    if (++ticks % 30 === 0) for (const dir of states(true)) sweepSessions(dir, Date.now());
     // 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(); }
@@ -239,6 +249,22 @@ export async function web(repoDir: string, opts: Opts = {}) {
         // Before the project list: it registers folders that turn out to be set up.
         const unset = await fresh();
         const dirs = states(all);
+        // With a projects folder set, the picker offers only real projects inside it,
+        // and always the one open now so it never hides where the board is.
+        const root = await projectsRoot();
+        // Windows paths compare without case: c:\users\me\projects holds C:\Users\me\Projects\app.
+        // A group folder is what fresh() takes for one, a folder right inside the projects
+        // folder with no .git or package.json; with an empty .kaizen it was chosen once and
+        // is hidden. Anything else is a project, a writing one included, even before its
+        // first run. A drive or filesystem root already ends in a separator.
+        const fold = (p: string) => process.platform === "win32" ? p.toLowerCase() : p;
+        const filled = (d: string) => { try { return readdirSync(d).length > 0; } catch { return false; } };
+        const inside = fold(root.endsWith(sep) ? root : root + sep);
+        const picker = states(true).filter((d) => {
+          const p = dirname(d);
+          return !root || d === state || (fold(p).startsWith(inside)
+            && (isProject(p) || filled(d) || fold(dirname(p)) !== fold(root)));
+        });
         const cards = boardCards(dirs, Date.now());
         // The git mark, for the cards whose panel offers commit and push: one status per project.
         const marks = new Map<string, Record<string, string>>();
@@ -247,7 +273,7 @@ export async function web(repoDir: string, opts: Opts = {}) {
           marks.set(d, cardsGit(d, cards.filter((c) => markable(c) && c.state === d).map((c) => c.id!)));
         return json({
           project, all, dir: state,
-          projects: states(true).map((d) => ({ dir: d, label: label(d) })),
+          projects: picker.map((d) => ({ dir: d, label: label(d) })),
           fresh: unset.map((d) => ({ dir: join(d, ".kaizen"), label: tilde(d) })),
           cards: cards.map((c) => ({ ...c, notice: notice(c), git: markable(c) ? marks.get(c.state)?.[c.id!] : undefined })),
           now: Date.now(),
@@ -265,7 +291,7 @@ 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"),
+          notes: read("notes.md"), progress: read("progress.md"),
           // Notebook notes whose [[run:…]] links name this run.
           linkedFrom: linksTo(dir, id),
           // Nothing to pick in the global state dir: /fix refuses it.
@@ -283,12 +309,25 @@ export async function web(repoDir: string, opts: Opts = {}) {
         const sources = [], failed = [];
         for (const d of dir ? [dir] : states(true)) {
           // The seen list is bookkeeping, not something the page shows.
-          try { sources.push(...readSources(d).map(({ seen, ...s }) => ({ ...s, dir: d }))); }
+          try { sources.push(...readSources(d).map(({ seen, ...s }) => ({ ...s, dir: d, project: label(d) }))); }
           catch { failed.push(label(d)); }
         }
         return json({ sources, failed, every: await every() });
       }
 
+      // The Run form's choices for one project: installed tools and their models.
+      // A prefilled GitHub bug form. A redirect, so a plain link opens it with no script
+      // and no popup blocker in the way.
+      if (req.method === "GET" && path === "/issue") {
+        return Response.redirect(issueUrl({ title: url.searchParams.get("title") ?? "", what: url.searchParams.get("what") ?? "" }), 302);
+      }
+
+      if (req.method === "GET" && path === "/agents") {
+        const dir = url.searchParams.get("dir");
+        if (!dir || !states(true).includes(dir)) return bad("unknown state dir", 404);
+        return json(agentChoices(projectOf(dir)));
+      }
+
       if (req.method === "GET" && path === "/settings") {
         const { listSettings } = await import("./settings.ts");
         return json(listSettings(repoDir));
@@ -303,6 +342,28 @@ export async function web(repoDir: string, opts: Opts = {}) {
         return "error" in r ? bad(r.error) : json(r);
       }
 
+      // A page cannot learn a real path from a file input, so the board, which runs
+      // on the user's machine, opens the system's own folder dialog and answers it.
+      if (req.method === "POST" && path === "/pick-folder") {
+        if (!local(req)) return bad("cross-origin write refused", 403);
+        if (picking) return bad("a folder dialog is already open", 409);
+        const cmd = folderDialog();
+        if (!cmd) return bad("No folder dialog found: install zenity or kdialog, or type the path");
+        picking = true;
+        try {
+          const p = Bun.spawn(cmd, { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+          const [out, err, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited]);
+          // osascript ends a folder with "/"; a bare root (/, C:\) keeps its own.
+          const picked = /^([A-Za-z]:)?[\\/]$/.test(out.trim()) ? out.trim() : out.trim().replace(/[\\/]+$/, "");
+          if (code === 0 && picked) return json({ path: picked });
+          // Cancel: exit 1 with nothing said (zenity, kdialog), -128 (osascript), or exit 0 with no path (PowerShell).
+          if (code === 0 || !err.trim() || err.includes("-128")) return json({ cancelled: true });
+          return bad(err.trim().split("\n")[0]);
+        } catch (e) {
+          return bad(e instanceof Error ? e.message : String(e));
+        } finally { picking = false; }
+      }
+
       // 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") {
@@ -426,11 +487,15 @@ export async function web(repoDir: string, opts: Opts = {}) {
           const text = String(body.text ?? "").trim();
           const kind = body.kind === "full" || body.kind === "lite" ? body.kind : "";
           if (!text) return bad("empty idea");
+          const agent = typeof body.agent === "string" && body.agent ? body.agent : undefined;
+          if (agent && !KNOWN_AGENTS.some((a) => a.cmd === agent)) return bad("unknown agent");
+          const model = typeof body.model === "string" ? body.model.trim() : "";
+          if (model && !plainModel(model)) return bad("A model name is letters, digits and . : / @ _ - only");
           const it: Item = parseItem(`${kind} ${text}`.trim());
           // A `started` idea may be run again: the terminal the first launch opened
           // can come up empty, and nothing else tells the board a run never began.
           it.notes = readInbox(dir).find((l) => (l.status === "open" || l.status === "started") && l.text === text)?.notes;
-          const r = launchRun(it, dir);
+          const r = launchRun(it, dir, undefined, { agent, model: model || undefined, yolo: body.yolo === true });
           if (r.ok) replaceIdea(dir, text, { status: "started", text });
           changed();
           return json(r.ok
@@ -528,7 +593,37 @@ export async function web(repoDir: string, opts: Opts = {}) {
           const nums = pickFindings(dir, id, body.nums);
           if (!nums) return bad("pick open findings of this review");
           const text = fixPrompt(id, nums);
-          const r = launchRun({ severity: null, where: null, text, raw: text }, dir);
+          // The run's conversation picks the fix up, and once that window is open the
+          // waiting one ends. A failed launch leaves it: the decision has nowhere else.
+          const before = Date.now();
+          const r = launchRun({ severity: null, where: null, text, raw: text }, dir, id);
+          if (r.ok) closeSessions(dir, id, { before });
+          changed();
+          return json(r.ok
+            ? { ok: true, agent: r.agent }
+            : { ok: false, why: r.why, manual: r.manual, agent: r.agent }, r.ok ? 200 : 500);
+        }
+
+        // Approve or send back what a run is waiting on, from its panel. The page names
+        // the approval it saw: one already answered elsewhere is not answered twice.
+        if (path === "/decide") {
+          const id = String(body.id ?? "");
+          if (!/^[\w.-]+$/.test(id)) return bad("bad run id");
+          if (dir === join(home, ".kaizen")) return bad("no project to run in", 409);
+          let run: any;
+          try { run = JSON.parse(readText(join(dir, "runs", id, "state.json"))); } catch { return bad("no such run", 404); }
+          if (run.awaiting !== "approvals.plan" && run.awaiting !== "approvals.review" || run.awaiting !== body.awaiting) return bad("this run is not waiting on that approval", 409);
+          if (body.why !== undefined && !String(body.why).trim()) return bad("a revise needs a comment");
+          const answers = body.answers;
+          if (answers !== undefined && (run.awaiting !== "approvals.plan" || body.why !== undefined || !Array.isArray(answers)
+            || !answers.length || answers.length > 20 || answers.some((a: unknown) => typeof a !== "string" || !a.trim()))) return bad("bad answers");
+          const text = approvalPrompt(id, run.awaiting, body.why === undefined ? undefined : String(body.why), answers);
+          // The run is stopped at this approval, so its window is idle: the same
+          // conversation continues in one new window, and then the idle one ends. A
+          // failed launch leaves it open, since the decision went nowhere.
+          const before = Date.now();
+          const r = launchRun({ severity: null, where: null, text, raw: text }, dir, id);
+          if (r.ok) closeSessions(dir, id, { before });
           changed();
           return json(r.ok
             ? { ok: true, agent: r.agent }
@@ -595,6 +690,29 @@ export async function openApp(url: string) {
 }
 
 // Windows keeps browsers out of PATH; the usual install roots are the next best guess.
+// One dialog at a time: a second click while one is open would stack another.
+let picking = false;
+
+// The system folder picker for this platform, printing the chosen path on stdout.
+// macOS and Windows always have one; on Linux it is whichever desktop tool exists.
+export function folderDialog(platform: string = process.platform): string[] | null {
+  const prompt = "Choose your projects folder";
+  // osascript is a background process: without `activate` its dialog can open behind
+  // the browser. Plain `activate` targets osascript itself, so no Automation prompt.
+  if (platform === "darwin") return ["osascript", "-e", "activate", "-e", `POSIX path of (choose folder with prompt "${prompt}")`];
+  if (platform === "win32") {
+    // An owner form kept on top, or the dialog opens behind the browser.
+    const ps = `[Console]::OutputEncoding=[Text.Encoding]::UTF8;Add-Type -AssemblyName System.Windows.Forms;`
+      + `$o=New-Object System.Windows.Forms.Form -Property @{TopMost=$true};$d=New-Object System.Windows.Forms.FolderBrowserDialog;`
+      + `$d.Description='${prompt}';if($d.ShowDialog($o) -eq 'OK'){[Console]::Out.Write($d.SelectedPath)}`;
+    return [powershellExe(), "-NoProfile", "-STA", "-Command", ps];
+  }
+  const zenity = Bun.which("zenity", { PATH: process.env.PATH });
+  if (zenity) return [zenity, "--file-selection", "--directory", `--title=${prompt}`];
+  const kdialog = Bun.which("kdialog", { PATH: process.env.PATH });
+  return kdialog ? [kdialog, "--getexistingdirectory", home, "--title", prompt] : null;
+}
+
 function winChrome(exe: string) {
   const roots = [process.env["ProgramFiles"], process.env["ProgramFiles(x86)"], process.env["LOCALAPPDATA"]].filter(Boolean) as string[];
   const sub: Record<string, string> = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.9.4",
+  "version": "1.11.0",
   "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

@@ -62,7 +62,10 @@ If the user typed `/kaizen` with no argument and a run is in progress, treat it
 ## Before doing anything
 
 1. Locate the state directory: `.kaizen/` in the project folder's root, else
-   `~/.kaizen/` keyed by working directory. If neither exists and the user is starting
+   `~/.kaizen/` keyed by working directory. The project folder is the working
+   directory this session started in — never the folder this skill was read from, nor
+   the repository it lives in, even when that has a `.kaizen/` of its own. A run
+   written there is invisible to the board the user launched it from. 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)). Also append the project folder's absolute path
@@ -299,6 +302,7 @@ shown automatically.
         01-recheck.md
       06-backlog.md             # what this run deliberately did not do
       notes.md                  # context attached from the board; the planner reads it
+      progress.md               # the Work list as todo/doing/done, kept by the builder
       state.json
 ```
 

package/skills/kaizen/config.default.yml

@@ -155,6 +155,11 @@ 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.
   default: auto
+  # on: a board decision ends the run's waiting session before continuing its
+  # conversation, and abandoned or done runs (after 2 minutes) have theirs ended.
+  # Only sessions the board or dashboard launched are touched. off: nothing is
+  # ended, and a resumed conversation opens beside the window still waiting.
+  close: on
   # Per-tool model and effort for the session the board launches, passed as that
   # tool's own flags (claude --model/--effort, agy --model/--effort, codex -m and
   # model_reasoning_effort, gemini -m, opencode -m). Model names are the tool's own:
@@ -167,10 +172,11 @@ agent:
   # gemini: { model: gemini-2.5-pro }
 
 board:
-  # A folder your projects live in, e.g. ~/Projects. Every folder inside it is
-  # offered in the web board's project list; choosing one creates its .kaizen and
-  # moves the board there. A folder that is not itself a project (no .git, no
-  # package.json) is read as a group, and the folders inside it are offered too.
+  # A folder your projects live in, e.g. ~/Projects, or C:\Users\you\Projects on
+  # Windows. Every folder inside it is offered in the web board's project list;
+  # choosing one creates its .kaizen and moves the board there. A folder that is
+  # not itself a project (no .git, no package.json) is read as a group, and the
+  # folders inside it are offered too.
   projects_dir: ""
 
 sources:

package/skills/kaizen/spec-build.md

@@ -39,6 +39,14 @@ Rules:
   folder there is no branch to make and no commit to skip, and that absence is not a
   finding.
 
+**Keep `progress.md` while you work.** Before the first change, write
+`runs/<id>/progress.md` with one line per bullet of the plan's Work list, in order:
+`- todo: <bullet text>`. Change a line's prefix to `- doing:` when you start that item
+and to `- done:` when it is finished, with exactly one `doing` at a time. Rewrite the
+prefix only, never the text or the order. The board shows this file live on a building
+run, so it is how a person sees where the build is. It is a progress report, not the
+record — `03-impl.md` still is — and fix iterations do not touch it.
+
 **Baseline first, in any track with an existing suite of checks.** Before changing
 anything, run whatever already proves the existing material correct — the test suite,
 the linter, the link checker, the fact-check pass — and record the result in
@@ -74,6 +82,15 @@ where one exists. For anything else — a document, copy, a runbook, a memo —
 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.
 
+It also says how to test the result, under a `### How to test` subhead: numbered steps a
+person follows to check the run did what was asked, each an action and what they should
+see — "open Settings → Board, clear the field: it shows `not set`". Derive the steps
+from the plan's gate, covering what the request asked for rather than every internal
+check. An automated check goes in too, as its command and the result it should give,
+but never alone: a test command tells a person the code passes, not that the work does
+what they wanted. Use `###` subheads inside the section, never `##`: the board ends the
+section at the next `##`.
+
 **A `## Commit` section is the commit message for the work**, where the work sits in a
 git repository. The first line is a Conventional Commits subject,
 `<type>(<scope>): <what changed>`, with the type one of `feat`, `fix`, `refactor`,

package/skills/kaizen/spec-plan.md

@@ -99,7 +99,12 @@ The planner reads code but writes none. Its plan must contain:
 8. **Risks** — what could break, what is irreversible, what needs a migration or a
    backup taken first.
 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.
+   non-empty, the approval must ask the user about it rather than defaulting. The
+   board shows a waiting plan's questions as a pick list and sends the answers with
+   its approval, so keep this shape: each question on its own line as
+   `Q: <question>`, its options beneath as `- <label> (recommended) — <why>`, the
+   label short since it is what is sent back, `(multi-select)` in the question when
+   several may be picked, and `None.` when there are none.
 10. **Out of scope suggestions** — worthwhile things noticed but not asked for, each
    its own proposal. Never folded into a step.