kaizen-agent 1.42.2 → 1.43.1

package/agents/kaizen-reviewer.md

@@ -142,7 +142,7 @@ open human check never reads as a clean pass.
 
 ## Memory
 
-When memory writing is enabled, append to `.kaizen/memory.md` any durable lesson
+When `review.write_memory` is true (the default), append to `.kaizen/memory.md` any durable lesson
 about this codebase: a recurring bug pattern, a non-obvious constraint, a convention
 worth preserving. One line each. Nothing run-specific, nothing already obvious from
 reading the code.

package/cli/backlog.test.ts

@@ -0,0 +1,133 @@
+// Backlog items as cards in the board's Ideas column: numbering, hiding while a run
+// started from one lives, closing in place, and the board routes that drive them.
+import { test, expect } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { backlogLines, backlogCards, startedBacklog, closeBacklog, markBacklogDone, backlogItem } from "./state.ts";
+import { boardIndex } from "./notes.ts";
+
+const scratch = () => {
+  const state = join(mkdtempSync(join(tmpdir(), "kz-bl-")), ".kaizen");
+  const run = (id: string, stage: string, files: Record<string, string> = {}) => {
+    const dir = join(state, "runs", id);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "state.json"), JSON.stringify({ id, stage, awaiting: null }));
+    for (const [f, t] of Object.entries(files)) writeFileSync(join(dir, f), t);
+    return dir;
+  };
+  return { state, run };
+};
+
+const BACKLOG = "# Backlog\n\n- open: `cli/x.ts:12`: low: first thing. Fix: do it.\n- done: closed one | run y\n- open: high: urgent thing\n  a note under it\n- rejected: no | why\n- open: plain item\n";
+
+test("backlogLines numbers every open, done and rejected line as boardIndex does", () => {
+  const { state, run } = scratch();
+  run("2026-10-01-src", "done", { "06-backlog.md": BACKLOG });
+  const lines = backlogLines(join(state, "runs", "2026-10-01-src", "06-backlog.md"));
+  expect(lines.map((l) => [l.n, l.status])).toEqual([[1, "open"], [2, "done"], [3, "open"], [4, "rejected"], [5, "open"]]);
+  const idx = boardIndex(state).runs.find((r) => r.id === "2026-10-01-src")!.backlog;
+  expect(idx).toEqual(lines.map(({ n, status, text }) => ({ n, status, text })));
+  expect(backlogLines(join(state, "nope.md"))).toEqual([]);
+});
+
+test("backlogCards: open items of live runs and the orphanage, most severe first; abandoned runs skipped", () => {
+  const { state, run } = scratch();
+  run("2026-10-01-src", "done", { "06-backlog.md": BACKLOG });
+  run("2026-10-02-gone", "abandoned", { "06-backlog.md": "- open: critical: from an abandoned run\n" });
+  writeFileSync(join(state, "backlog.md"), "- open: rescued item | from 2026-09-01-old\n");
+  const cards = backlogCards([state]);
+  expect(cards.map((c) => [c.source, c.n, c.severity])).toEqual([
+    ["2026-10-01-src", 3, "high"], ["2026-10-01-src", 1, "low"], ["2026-10-01-src", 5, null], ["orphan", 1, null],
+  ]);
+  expect(cards[1]).toMatchObject({ text: "first thing.", at: "x.ts:12", raw: "`cli/x.ts:12`: low: first thing. Fix: do it." });
+});
+
+test("a run started from an item hides its card; an abandoned one gives it back", () => {
+  const { state, run } = scratch();
+  run("2026-10-01-src", "done", { "06-backlog.md": BACKLOG });
+  const kid = run("2026-10-03-kid", "plan", { "00-request.md": "/kaizen urgent thing\n\nParent: 2026-10-01-src\nBacklog: 2026-10-01-src#3\n" });
+  expect(startedBacklog(state).get("2026-10-01-src#3")).toEqual([{ id: "2026-10-03-kid", stage: "plan" }]);
+  expect(backlogCards([state]).some((c) => c.n === 3)).toBe(false);
+  writeFileSync(join(kid, "state.json"), JSON.stringify({ stage: "abandoned" }));
+  expect(backlogCards([state]).some((c) => c.n === 3)).toBe(true);
+});
+
+test("markBacklogDone closes only the line its done run names, once, and touches no state.json", () => {
+  const { state, run } = scratch();
+  const src = run("2026-10-01-src", "done", { "06-backlog.md": BACKLOG });
+  run("2026-10-03-kid", "build", { "00-request.md": "x\n\nBacklog: 2026-10-01-src#3\n" });
+  run("2026-10-04-orph", "done", { "00-request.md": "y\n\nBacklog: orphan#1\n" });
+  writeFileSync(join(state, "backlog.md"), "- open: rescued item | from 2026-09-01-old\n");
+  markBacklogDone(state);
+  expect(readFileSync(join(src, "06-backlog.md"), "utf8")).toBe(BACKLOG);   // still building
+  expect(readFileSync(join(state, "backlog.md"), "utf8")).toBe("- open: rescued item | from 2026-09-01-old | 2026-10-04-orph\n".replace("open", "done"));
+  const kidState = join(state, "runs", "2026-10-03-kid", "state.json");
+  writeFileSync(kidState, JSON.stringify({ stage: "done" }));
+  const before = statSync(kidState).mtimeMs;
+  markBacklogDone(state);
+  markBacklogDone(state);
+  expect(readFileSync(join(src, "06-backlog.md"), "utf8")).toBe(BACKLOG.replace("- open: high: urgent thing", "- done: high: urgent thing | 2026-10-03-kid"));
+  expect(statSync(kidState).mtimeMs).toBe(before);
+  expect(backlogCards([state]).map((c) => c.n)).toEqual([1, 5]);
+});
+
+test("closeBacklog rewrites one open line in place and keeps CRLF; refuses closed or missing lines", () => {
+  const { state, run } = scratch();
+  const src = run("2026-10-01-src", "done", { "06-backlog.md": BACKLOG.replace(/\n/g, "\r\n") });
+  expect(closeBacklog(state, "2026-10-01-src", 5, "rejected", "not worth it")).toBeNull();
+  expect(readFileSync(join(src, "06-backlog.md"), "utf8")).toBe(BACKLOG.replace("- open: plain item", "- rejected: plain item | not worth it").replace(/\n/g, "\r\n"));
+  expect(closeBacklog(state, "2026-10-01-src", 2, "rejected", "x")).toBe("that item is already closed");
+  expect(closeBacklog(state, "2026-10-01-src", 9, "rejected", "x")).toBe("no such backlog item");
+  expect(closeBacklog(state, "../../etc", 1, "rejected", "x")).toBe("no such backlog");
+  expect(backlogItem(state, "2026-10-01-src", 5)?.status).toBe("rejected");
+});
+
+// The real server in a scratch home. Linux only: launching is made to fail before any
+// terminal or agent opens (no display, no terminal on PATH, terminal launch mode), and
+// the manual command it hands back is the request a run would have been given.
+test.skipIf(process.platform !== "linux")("board routes: /state lists backlog cards, /backlog rejects, /run carries the item's source", async () => {
+  const homeDir = mkdtempSync(join(tmpdir(), "kz-bl-home-")), proj = join(homeDir, "p"), state = join(proj, ".kaizen");
+  for (const d of [state, join(homeDir, ".kaizen"), join(homeDir, ".claude")]) mkdirSync(d, { recursive: true });
+  writeFileSync(join(homeDir, ".kaizen", "projects"), proj + "\n");
+  writeFileSync(join(homeDir, ".kaizen", "config.yml"), "agent:\n  launch: terminal\n");
+  const src = join(state, "runs", "2026-10-01-src");
+  mkdirSync(src, { recursive: true });
+  writeFileSync(join(src, "state.json"), JSON.stringify({ stage: "done", awaiting: null }));
+  writeFileSync(join(src, "06-backlog.md"), BACKLOG);
+  const port = 20000 + Math.floor(Math.random() * 20000);
+  const repo = join(import.meta.dir, "..");
+  const env: Record<string, string> = { HOME: homeDir, USERPROFILE: homeDir, KAIZEN_HOME: repo, PATH: dirname(process.execPath), DISPLAY: "", WAYLAND_DISPLAY: "", TERMINAL: "", TMUX: "" };
+  const proc = Bun.spawn([process.execPath, join(repo, "cli", "install.ts"), "web", "--port", String(port), "--no-open", "--foreground"], { cwd: proj, env, stdout: "ignore", stderr: "ignore" });
+  try {
+    const at = `http://127.0.0.1:${port}`;
+    for (let i = 0; ; i++) { try { await fetch(at + "/state"); break; } catch { if (i > 100) throw new Error("board did not start"); await Bun.sleep(50); } }
+    const post = async (path: string, body: object) => { const r = await fetch(at + path, { method: "POST", body: JSON.stringify({ dir: state, ...body }) }); return { status: r.status, ...(await r.json() as any) }; };
+    const listed = async () => ((await (await fetch(at + "/state?all=1")).json()) as any).backlog.map((b: any) => [b.source, b.n]);
+    expect(await listed()).toEqual([["2026-10-01-src", 3], ["2026-10-01-src", 1], ["2026-10-01-src", 5]]);
+
+    expect(await post("/backlog", { op: "reject", source: "2026-10-01-src", n: 5, reason: "" })).toMatchObject({ status: 400 });
+    expect(await post("/backlog", { op: "reject", source: "2026-10-01-src", n: 5, reason: "not now" })).toMatchObject({ status: 200 });
+    expect(await post("/backlog", { op: "reject", source: "2026-10-01-src", n: 5, reason: "again" })).toMatchObject({ status: 409 });
+    expect(await post("/backlog", { op: "reject", source: "2026-10-01-src", n: 42, reason: "x" })).toMatchObject({ status: 404 });
+    expect(readFileSync(join(src, "06-backlog.md"), "utf8")).toContain("- rejected: plain item | not now\n");
+    expect(await listed()).toEqual([["2026-10-01-src", 3], ["2026-10-01-src", 1]]);
+
+    expect(await post("/run", { backlog: { source: "2026-10-01-src", n: 2 } })).toMatchObject({ status: 409 });
+    expect(await post("/run", { backlog: { source: "2026-10-01-src", n: 42 } })).toMatchObject({ status: 404 });
+    const r = await post("/run", { kind: "lite", backlog: { source: "2026-10-01-src", n: 1 } });
+    expect(r).toMatchObject({ status: 500, ok: false });
+    expect(r.manual).toContain("/kaizen lite first thing. (x.ts:12)");
+    expect(r.manual).toContain("Parent: 2026-10-01-src");
+    expect(r.manual).toContain("Backlog: 2026-10-01-src#1");
+    expect(r.manual).toContain("Backlog item: `cli/x.ts:12`: low: first thing. Fix: do it.");
+
+    // Once a run carries the line, a second start is refused and the card is gone.
+    const kid = join(state, "runs", "2026-10-05-kid");
+    mkdirSync(kid, { recursive: true });
+    writeFileSync(join(kid, "state.json"), JSON.stringify({ stage: "plan", awaiting: null }));
+    writeFileSync(join(kid, "00-request.md"), "first thing\n\nParent: 2026-10-01-src\nBacklog: 2026-10-01-src#1\n");
+    expect(await post("/run", { backlog: { source: "2026-10-01-src", n: 1 } })).toMatchObject({ status: 409 });
+    expect(await listed()).toEqual([["2026-10-01-src", 3]]);
+  } finally { proc.kill(); await proc.exited; }
+}, 30_000);

package/cli/board.test.ts

@@ -22,7 +22,8 @@ test("Settings rechecks an existing update alert and clears or refreshes it", as
     getElementById: (id: string) => id === "pbody" ? body : elements.get(id),
     createElement: () => ({
       isConnected: false,
-      set innerHTML(html: string) {
+      set innerHTML(v: unknown) {
+        const html = String(v);
         this.html = html;
         elements.clear();
         for (const [, id] of html.matchAll(/id="([^"]+)"/g)) elements.set(id, { textContent: "", disabled: false, focus() {} });
@@ -154,7 +155,7 @@ test("card menu items: appropriate actions and distinct icons across phases", ()
 
   const ico = (n: string) => `<svg><use href="#i-${n}"/></svg>`;
   const from = cards.indexOf("if (k === store.menuKey) {");
-  const menuSnippet = (cards.slice(from, cards.indexOf('el.innerHTML += `<div class="menu-pop"', from)) + "}").replace("const items = [];", "items = [];");
+  const menuSnippet = (cards.slice(from, cards.indexOf('el.innerHTML += html`<div class="menu-pop"', from)) + "}").replace("const items = [];", "items = [];");
   const a0 = cards.indexOf("const actionOf =");
   const actionOf = cards.slice(a0, cards.indexOf("\n\n", a0));
   const getItems = new Function("c", "archive", "S", `const ico = ${ico.toString()};\nconst decided = new Set(), answer = () => "";\n${actionOf}\nconst store = { S, menuKey: 1 };\nlet k = 1, items = [];\n${menuSnippet}\nreturn items;`);
@@ -178,13 +179,18 @@ test("card menu items: appropriate actions and distinct icons across phases", ()
   const startItems = getItems(startingIdea, false);
   expect(startItems.map((i: any) => i ? i[1] : null)).toEqual(["Open", "Run again", "Archive", null, "Remove"]);
 
+  // Ideas column, Backlog tab: a run's leftover, run like an idea, rejected with a reason.
+  expect(getItems({ kind: "backlog", status: "idea", column: 0 }, false).map((i: any) => i ? i[1] : null)).toEqual(["Run", "Open its run", null, "Reject"]);
+  expect(getItems({ kind: "backlog", status: "starting", column: 0 }, false)[0][1]).toBe("Run again");
+
   // Phase 1: Planning (run waiting for plan approval)
   const planWaiting = { kind: "run", status: "waiting", awaiting: "approvals.plan", column: 1 };
   const planItems = getItems(planWaiting, false);
-  expect(planItems.map((i: any) => i ? i[1] : null)).toEqual(["Review plan", "Archive", null, "Abandon"]);
+  expect(planItems.map((i: any) => i ? i[1] : null)).toEqual(["Review plan", "Archive", "Back to idea", null, "Abandon"]);
   expect(planItems[0][2]).toBe(ico("open"));
   expect(planItems[1][2]).toBe(ico("archive"));
-  expect(planItems[3][2]).toBe(ico("x"));
+  expect(planItems[2][2]).toBe(ico("restore"));
+  expect(planItems[4][2]).toBe(ico("x"));
 
   // Phase 2: Building (running run)
   const buildingRun = { kind: "run", status: "running", column: 2 };

package/cli/browser.test.ts

@@ -18,7 +18,7 @@ const run = async (code: string, env: Record<string, string> = {}) => {
   const script = `import * as br from ${JSON.stringify(join(repo, "cli/browser.ts"))};
 Object.assign(process.env, ${JSON.stringify({ HOME: process.env.HOME ?? "", USERPROFILE: process.env.USERPROFILE ?? "" })});
 console.log(JSON.stringify(await (async () => { ${code} })()));`;
-  const p = Bun.spawn(["bun", "-e", script], { cwd: home, env: { ...process.env, HOME: home, USERPROFILE: home, ...env }, stdout: "pipe", stderr: "pipe" });
+  const p = Bun.spawn(["bun", "-e", script], { cwd: home, env: { ...process.env, HOME: home, USERPROFILE: home, KAIZEN_BROWSER_PACE: "0.1", ...env }, stdout: "pipe", stderr: "pipe" });
   const [out, err, code_] = [await new Response(p.stdout).text(), await new Response(p.stderr).text(), await p.exited];
   if (code_ !== 0) throw new Error(err);
   return JSON.parse(out.trim().split("\n").at(-1)!);

package/cli/browser.ts

@@ -30,6 +30,8 @@ export const POST: Record<string, RegExp> = {
 };
 // Grids show thumbnails, not text: each post page is opened for its caption.
 const GRID = new Set(["instagram"]);
+// The fixed waits below are sized for real platforms; KAIZEN_BROWSER_PACE scales them (the tests run at 0.1).
+const nap = (ms: number) => Bun.sleep(ms * (Number(process.env.KAIZEN_BROWSER_PACE) || 1));
 
 // KAIZEN_BROWSER, else the usual names on PATH, else the usual install paths.
 export function findBrowser(): string | null {
@@ -97,9 +99,9 @@ export class Page {
   async go(url: string) {
     await this.call("Page.navigate", { url });
     const end = Date.now() + 20_000;
-    await Bun.sleep(1500);
-    while (Date.now() < end && (await this.js("document.readyState")) !== "complete") await Bun.sleep(250);
-    await Bun.sleep(2000);   // the posts arrive after the page itself
+    await nap(1500);
+    while (Date.now() < end && (await this.js("document.readyState")) !== "complete") await nap(250);
+    await nap(2000);   // the posts arrive after the page itself
   }
   close() { try { this.ws.close(); } catch { /* already gone */ } }
 }
@@ -200,7 +202,10 @@ export async function browse<T>(use: (page: Page) => Promise<T>): Promise<T | {
   } finally {
     page?.close();
     proc.kill();
-    await Promise.race([proc.exited, Bun.sleep(5000)]);
+    // A cleared timer, not Bun.sleep: a pending sleep keeps the process alive 5 s after Chrome is gone.
+    let t: Timer | undefined;
+    await Promise.race([proc.exited, new Promise((r) => { t = setTimeout(r, 5000); })]);
+    clearTimeout(t);
     if (proc.exitCode === null) proc.kill(9);
   }
 }
@@ -230,7 +235,7 @@ export async function readPage(page: Page, url: string, platform: string, max =
     // A page that renders its posts late is not empty: stop early only once some arrived.
     still = seen.size && seen.size === before ? still + 1 : 0;
     await page.js("window.scrollBy(0, window.innerHeight * 1.5)");
-    await Bun.sleep(1500);
+    await nap(1500);
   }
   let found = [...seen.values()].slice(0, max);
   if (GRID.has(platform)) {
@@ -310,12 +315,12 @@ export async function replyOn(page: Page, link: string, platform: string, text:
   if (!(await page.js<boolean>(FIND(how.box, "focus"))))
     return { ok: false, note: (await page.js<boolean>(OFFERS)) ? signInNote(platform) : `Could not find the reply box on ${name}. Nothing was posted.` };
   await page.call("Input.insertText", { text });
-  await Bun.sleep(800);
+  await nap(800);
   if (!(await here())) return { ok: false, note: `The page left ${name}. Nothing was posted.` };
   if (!(await page.js<boolean>(FIND(how.send, "click")))) return { ok: false, note: `Could not find ${name}'s send button. Nothing was posted.` };
   // Sent once the box is gone or emptied; still holding the text means it did not go.
   for (let i = 0; i < 20; i++) {
-    await Bun.sleep(500);
+    await nap(500);
     const left = await page.js<string | null>(BOX);
     if (left === null || !left.trim()) return { ok: true };
   }

package/cli/html.test.ts

@@ -0,0 +1,19 @@
+import { expect, test } from "bun:test";
+import { html, ico, raw } from "../web/board/dom.ts";
+
+test("html escapes interpolations once and keeps trusted markup", () => {
+  const bad = '<img src=x onerror=1> & "q"';
+  const out = String(html`<b title="${bad}">${bad}</b>`);
+  expect(out).not.toContain("<img");
+  expect(out).toContain("&lt;img src=x onerror=1&gt; &amp; &quot;q&quot;");
+  expect(String(html`${"a&b"}`)).toBe("a&amp;b");
+  expect(String(html`${raw("<i>")}${ico("x")}`)).toBe('<i><svg><use href="#i-x"/></svg>');
+  expect(String(html`<ul>${[1, 2].map((n) => html`<li>${n}</li>`)}</ul>`)).toBe("<ul><li>1</li><li>2</li></ul>");
+  expect(String(html`${["<a>"]}`)).toBe("&lt;a&gt;");
+  expect(String(html`[${null}${undefined}${false}]`)).toBe("[]");
+  expect(String(html`${html`<u>${"&"}</u>`}`)).toBe("<u>&amp;</u>");
+});
+
+test("aria states render false explicitly when stringified", () => {
+  expect(String(html`<b aria-pressed="${String(false)}" aria-checked="${String(true)}">`)).toBe('<b aria-pressed="false" aria-checked="true">');
+});

package/cli/notes.ts

@@ -3,7 +3,7 @@
 // the page goes through safeName before it becomes a path.
 import { existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmdirSync, statSync, writeFileSync } from "node:fs";
 import { join, dirname, resolve, sep } from "node:path";
-import { boardCards, reviewFindings, readText } from "./state.ts";
+import { backlogLines, boardCards, reviewFindings, readText } from "./state.ts";
 import { wikilinks, boardLink, resolveRun } from "../web/notes-lib.ts";
 
 export type Note = { name: string; mtime: number; text: string };
@@ -114,11 +114,7 @@ function prune(state: string, dir: string) {
 // project keeps hundreds of runs.
 export function boardIndex(state: string) {
   const cards = boardCards([state], Date.now());
-  const backlog = (id: string) => {
-    let text = "";
-    try { text = readText(join(state, "runs", id, "06-backlog.md")); } catch { /* none */ }
-    return [...text.matchAll(/^\s*-\s*(open|done|rejected):\s*(.*)$/gm)].map((m, i) => ({ n: i + 1, status: m[1]!, text: m[2]!.trim() }));
-  };
+  const backlog = (id: string) => backlogLines(join(state, "runs", id, "06-backlog.md")).map(({ n, status, text }) => ({ n, status, text }));
   return {
     runs: cards.filter((c) => c.kind === "run").map((c) => ({
       id: c.id!, short: c.id!.replace(/^\d{4}-\d{2}-\d{2}-/, ""), title: c.title ?? c.text, status: c.status,

package/cli/pty.ts

@@ -81,7 +81,8 @@ export function startPty(key: string, cmd: string[], cwd: string, pidFile?: stri
     for (const f of p.listeners) f(null);
     p.listeners.clear();
     try { p.proc.terminal?.close(); } catch { /* already closed */ }
-    setTimeout(() => { if (ptys.get(key) === p) ptys.delete(key); }, KEEP_MS).unref();
+    // Dropped: pages showing it (the Terminal page) refresh, or its tile lingers until some other change.
+    setTimeout(() => { if (ptys.get(key) === p) { ptys.delete(key); onChange?.(); } }, KEEP_MS).unref();
     onChange?.();
   });
   return p.proc.pid;

package/cli/settings.test.ts

@@ -6,6 +6,7 @@ import { test, expect, beforeAll, afterAll } from "bun:test";
 import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, rmSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
+import { applyPreset, detectPreset } from "./settings.ts";
 
 const repo = join(dirname(import.meta.path), "..");
 const defaults = join(repo, "skills/kaizen/config.default.yml");
@@ -48,3 +49,40 @@ test("board settings save to the global config, project settings to the project"
   expect(inProject(`return setSetting(repo, "git.auto_commit", "true")`)).toEqual({ ok: true });
   expect(readFileSync(join(project, ".kaizen", "config.yml"), "utf8")).toMatch(/auto_commit: true/);
 });
+
+test("every row is a key in config.default.yml, and every `when` names a row and one of its values", () => {
+  const rows = inProject(`return listSettings(repo).rows`);
+  const text = readFileSync(defaults, "utf8");
+  for (const r of rows) {
+    const [top, leaf] = r.key.split(".");
+    const block = leaf ? new RegExp(`^${top}:\\n(?:(?:  .*|\\s*)\\n)*?  ${leaf}:`, "m") : new RegExp(`^${top}:`, "m");
+    expect(block.test(text) ? r.key : `${r.key} missing`).toBe(r.key);
+    if (!r.when) continue;
+    const dep = rows.find((x) => x.key === r.when[0]);
+    expect(dep?.values).toContain(r.when[1]);
+  }
+});
+
+test("a row dims while the setting it depends on has it switched off, and a leftover dead key changes nothing", () => {
+  const conf = join(project, ".kaizen", "config.yml");
+  // The low preset as an older config holds it, with keys kaizen no longer reads.
+  writeFileSync(conf, readFileSync(defaults, "utf8")
+    .replace("enabled: true\n  # critical", "enabled: false\n  # critical")
+    .replace("git:\n", "git:\n  branch_before_implement: false\n")
+    + "\ntrack:\n  default: software\n");
+  const idle = (k: string) => inProject(`return listSettings(repo).rows.find((r) => r.key === ${JSON.stringify(k)}).idle`);
+  expect(idle("auto_fix.min_severity")).toBe("No effect unless Fix findings automatically is on");
+  expect(idle("auto_fix.enabled")).toBe("");
+  expect(inProject(`return setSetting(repo, "auto_fix.max_iterations", "3")`)).toEqual({ ok: true });
+  expect(inProject(`return setSetting(repo, "auto_fix.enabled", "true")`)).toEqual({ ok: true });
+  expect(idle("auto_fix.min_severity")).toBe("");
+  expect(inProject(`return value("auto_fix.max_iterations")`)).toBe("3");
+  copyFileSync(defaults, conf);
+});
+
+test("a config still holding git.branch_before_implement keeps its preset", () => {
+  const text = readFileSync(defaults, "utf8");
+  const low = applyPreset(text, "low", text).replace("git:\n", "git:\n  branch_before_implement: true\n");
+  expect(detectPreset(low, text)).toBe("low");
+  expect(detectPreset(text, text)).toBe("medium");
+});

package/cli/settings.ts

@@ -6,7 +6,10 @@ import { homedir } from "node:os";
 import { readText } from "./state.ts";
 
 // `text` is a value typed rather than chosen: a path. It has no values to cycle.
-type Setting = { key: string; label: string; group: string; values: string[]; help: string; text?: boolean; folder?: boolean };
+// `when`: the row only has an effect while that other key holds that value; both
+// settings screens dim it otherwise, and it stays editable (`/kaizen full` overrides
+// the runner for one run, so a subagent model still matters under `runner: lite`).
+type Setting = { key: string; label: string; group: string; values: string[]; help: string; text?: boolean; folder?: boolean; when?: [string, string] };
 
 export type PresetName = "low" | "medium" | "ultra";
 
@@ -29,7 +32,6 @@ export const PRESETS: Record<PresetName, {
       "auto_fix.min_severity": "high",
       "auto_fix.max_iterations": "1",
       "git.auto_commit": "false",
-      "git.branch_before_implement": "false",
       "git.worktree_per_run": "false",
     },
   },
@@ -47,7 +49,6 @@ export const PRESETS: Record<PresetName, {
       "auto_fix.min_severity": "high",
       "auto_fix.max_iterations": "2",
       "git.auto_commit": "false",
-      "git.branch_before_implement": "true",
       "git.worktree_per_run": "true",
     },
   },
@@ -65,7 +66,6 @@ export const PRESETS: Record<PresetName, {
       "auto_fix.min_severity": "low",
       "auto_fix.max_iterations": "4",
       "git.auto_commit": "true",
-      "git.branch_before_implement": "true",
       "git.worktree_per_run": "true",
     },
   },
@@ -99,31 +99,29 @@ export function applyPreset(text: string, preset: PresetName, defaults: string):
 
 const SETTINGS: Setting[] = [
   { key: "preset", label: "Preset", group: "Preset", values: ["low", "medium", "ultra", "custom"], help: "" },
-  { key: "mode", label: "Stop for approval", group: "Approvals", values: ["approve", "auto", "plan-only", "review-only"], help: "" },
-  { key: "approvals.plan", label: "Approve the plan first", group: "Approvals", values: ["true", "false"], help: "" },
-  { key: "approvals.review", label: "Approve after review", group: "Approvals", values: ["true", "false"], help: "" },
-  { key: "approvals.each_file", label: "Confirm every file edit", group: "Approvals", values: ["true", "false"], help: "" },
+  { key: "mode", label: "Run mode", group: "Approvals", values: ["approve", "auto", "plan-only", "review-only"], help: "" },
+  { key: "approvals.plan", label: "Approve the plan first", group: "Approvals", values: ["true", "false"], help: "", when: ["mode", "approve"] },
+  { key: "approvals.review", label: "Approve after review", group: "Approvals", values: ["true", "false"], help: "", when: ["mode", "approve"] },
+  { key: "approvals.each_file", label: "Confirm every file edit", group: "Approvals", values: ["true", "false"], help: "", when: ["mode", "approve"] },
   { key: "runner", label: "Stage isolation", group: "Agents", values: ["full", "lite"], help: "full: separate agent per stage. lite: one session" },
-  { key: "build.executor", label: "Who builds", group: "Agents", values: ["subagent", "inline", "ask"], help: "" },
+  { key: "build.executor", label: "Who builds", group: "Agents", values: ["subagent", "inline", "ask"], help: "subagent: its own agent · inline: this session · ask: pick at plan approval", when: ["runner", "full"] },
   { key: "agent.default", label: "Tool the board launches", group: "Agents", values: ["auto", "claude", "codex", "agy", "opencode", "gemini"], help: "" },
   { key: "agent.launch", label: "Where the board runs agents", group: "Agents", values: ["card", "terminal"], help: "" },
-  { key: "subagents.model", label: "Model for stage agents", group: "Agents", values: ["inherit", "opus", "sonnet", "haiku"], help: "" },
-  { key: "subagents.effort", label: "Effort for stage agents", group: "Agents", values: ["inherit", "low", "medium", "high"], help: "" },
+  { key: "subagents.model", label: "Model for subagents", group: "Agents", values: ["inherit", "opus", "sonnet", "haiku"], help: "Planner, builder, reviewer", when: ["runner", "full"] },
+  { key: "subagents.effort", label: "Effort for subagents", group: "Agents", values: ["inherit", "low", "medium", "high"], help: "Planner, builder, reviewer", when: ["runner", "full"] },
   { key: "auto_fix.enabled", label: "Fix findings automatically", group: "Auto-fix", values: ["true", "false"], help: "" },
-  { key: "auto_fix.min_severity", label: "Auto-fix from severity", group: "Auto-fix", values: ["critical", "high", "medium", "low"], help: "" },
-  { key: "auto_fix.max_iterations", label: "Max fix rounds", group: "Auto-fix", values: ["1", "2", "3", "4", "5"], help: "" },
+  { key: "auto_fix.min_severity", label: "Lowest severity to fix", group: "Auto-fix", values: ["critical", "high", "medium", "low"], help: "", when: ["auto_fix.enabled", "true"] },
+  { key: "auto_fix.max_iterations", label: "Max fix rounds", group: "Auto-fix", values: ["1", "2", "3", "4", "5"], help: "", when: ["auto_fix.enabled", "true"] },
   { key: "git.auto_commit", label: "Commit when done", group: "Git", values: ["false", "true"], help: "Never pushes" },
-  { key: "git.branch_before_implement", label: "Branch before building", group: "Git", values: ["true", "false"], help: "" },
   { key: "git.worktree_per_run", label: "Branch and folder per run", group: "Git", values: ["true", "false"], help: "" },
-  { key: "track.default", label: "Kind of work", group: "Project", values: ["auto", "software", "writing", "communication", "operations", "research"], help: "" },
   { key: "review.write_memory", label: "Remember lessons", group: "Project", values: ["true", "false"], help: "" },
   { key: "review.memory_max_lines", label: "Memory size cap", group: "Project", values: ["50", "100", "200", "400"], help: "" },
   { key: "state.keep_runs", label: "Runs to keep", group: "Project", values: ["5", "10", "20", "50"], help: "" },
   { key: "dictation.model", label: "Dictation model", group: "Board", values: ["tiny", "base", "small", "large-v3-turbo"], help: "" },
   { key: "sources.every", label: "Gather requests", group: "Board", values: ["off", "1h", "6h", "24h"], help: "" },
-  { key: "sources.agent", label: "Who reads social sources", group: "Board", values: ["ask", "chatgpt", "agent"], help: "" },
-  { key: "sources.model", label: "ChatGPT model for gathering", group: "Board", values: [], text: true, help: "Empty: plan default" },
-  { key: "sources.effort", label: "ChatGPT effort for gathering", group: "Board", values: ["low", "medium", "high"], help: "" },
+  { key: "sources.agent", label: "Who picks social posts", group: "Board", values: ["ask", "chatgpt", "agent"], help: "X, TikTok, Instagram, Threads" },
+  { key: "sources.model", label: "ChatGPT model for gathering", group: "Board", values: [], text: true, help: "Empty: plan default", when: ["sources.agent", "chatgpt"] },
+  { key: "sources.effort", label: "ChatGPT effort for gathering", group: "Board", values: ["low", "medium", "high"], help: "", when: ["sources.agent", "chatgpt"] },
   { key: "board.projects_dir", label: "Projects folder", group: "Board", values: [], text: true, folder: true, help: "Empty: known projects only" },
   { key: "board.open", label: "Open the board in", group: "Board", values: ["browser", "app"], help: "" },
   { key: "ui.mouse", label: "Enable mouse", group: "Terminal", values: ["false", "true"], help: "" },
@@ -137,13 +135,18 @@ export function listSettings(repoRoot: string) {
   const load = (f: string) => existsSync(f) ? readText(f) : "";
   const text = load(file), board = load(globalFile());
   const preset = detectPreset(text, defaults);
-  return {
-    file: tilde(file),
-    rows: SETTINGS.map((s) => ({
-      ...s,
-      value: s.key === "preset" ? preset : (read(s.group === "Board" ? board : text, s.key) || read(defaults, s.key)) ?? s.values[0] ?? "",
-    })),
-  };
+  const rows = SETTINGS.map((s) => ({
+    ...s,
+    value: s.key === "preset" ? preset : (read(s.group === "Board" ? board : text, s.key) || read(defaults, s.key)) ?? s.values[0] ?? "",
+  }));
+  const valueOf = (k: string) => rows.find((r) => r.key === k)?.value ?? null;
+  return { file: tilde(file), rows: rows.map((r) => ({ ...r, idle: idle(r, valueOf) })) };
+}
+
+// Why a row has no effect right now, or "" while it has one: its `when` is not met.
+function idle(s: Setting, valueOf: (key: string) => string | null) {
+  if (!s.when || valueOf(s.when[0]) === s.when[1]) return "";
+  return `No effect unless ${SETTINGS.find((x) => x.key === s.when![0])!.label} is ${s.when[1] === "true" ? "on" : s.when[1]}`;
 }
 
 export function setSetting(repoRoot: string, key: string, value: string) {
@@ -217,13 +220,17 @@ export async function settings(repoRoot: string, standalone = true) {
       }
       return v;
     };
+    const valueOf = (k: string) => {
+      const d = SETTINGS.find((x) => x.key === k)!;
+      return read(fileFor(d) === file ? text : readText(fileFor(d)), k) || read(defaults, k);
+    };
     const rows = SETTINGS.map((s) => ({
       s,
-      // Older configs spell "infer the track" as an empty string; show what it means.
+      idle: idle(s, valueOf),
       // The preset as a game's quick preset: arrows either side, the tier lit after it. No colour codes: the selected row wraps this in inverse, which a reset would end.
       value: s.key === "preset"
         ? `◁ ${currentPreset.padEnd(6)} ▷ ${(["low", "medium", "ultra"] as const).map((p) => p === currentPreset ? "━" : "─").join("")}`
-        : show(s, (read(fileFor(s) === file ? text : readText(fileFor(s)), s.key) || (s.key === "track.default" ? "auto" : undefined)) ?? c.dim("(default)")),
+        : show(s, read(fileFor(s) === file ? text : readText(fileFor(s)), s.key) ?? c.dim("(default)")),
     }));
     const width = Math.max(...SETTINGS.map((s) => s.label.length)) + 4;
 
@@ -234,7 +241,7 @@ export async function settings(repoRoot: string, standalone = true) {
     rowAt = [];
     let line = 2, group = "";
     const list = shown();
-    for (const [i, { s, value }] of rows.entries()) {
+    for (const [i, { s, value, idle: off }] of rows.entries()) {
       if (!list.includes(i)) continue;
       if (s.group !== group) {
         group = s.group;
@@ -245,14 +252,14 @@ export async function settings(repoRoot: string, standalone = true) {
       const name = s.label.padEnd(width);
       stdout.write(on
         ? `  ${c.cyan("›")} ${c.bold(name)}${c.inv(` ${value} `)}\n`
-        : `    ${c.dim(name)}${value}\n`);
+        : `    ${c.dim(name)}${off ? c.dim(value) : value}\n`);
       rowAt[line++] = i;
     }
     const cur = SETTINGS[active]!;
     if (!list.length) stdout.write(`\n  ${c.dim(`no setting matches "${query}"`)}\n\n`);
     else {
       stdout.write(`\n  ${c.dim(cur.key)}  ${c.dim("options:")} ${cur.values.map((v) => v || '""').join(c.dim(" / "))}\n`);
-      stdout.write(`  ${cur.help}\n`);
+      stdout.write(`  ${[cur.help, rows[active]!.idle].filter(Boolean).join(" · ")}\n`);
     }
     stdout.write(`\n  ${c.dim(typing
       ? "type to filter · enter or ↑↓ keep it · esc clear"