kaizen-agent 1.9.3 → 1.10.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,
   appendNote, saveAttachment, pidOnPort, readText, cmdExe, sysExe, powershellExe, runGit, cardsGit, readCommit, commitPush, notice, notifier, LOGO,
-  reviewFindings, pickFindings, fixPrompt,
+  reviewFindings, pickFindings, fixPrompt, approvalPrompt, nativePath, closeSessions, sweepSessions,
 } 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,7 +309,7 @@ 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() });
@@ -528,7 +554,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 }

package/package.json

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

@@ -299,6 +299,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.