kaizen-agent 1.34.2 → 1.34.4

package/cli/worktree.test.ts

@@ -0,0 +1,113 @@
+// A real bare remote, two clones and real git: the landing is only as good as git says.
+import { test, expect, beforeEach } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { startWorktree, landWorktree, codeDir, projectFromWorktree, run, type Run } from "./worktree.ts";
+
+const ID = "2026-10-17-demo";
+let remote: string, project: string, other: string;
+const g = (cwd: string, ...a: string[]) => { const r = run(["git", "-c", "user.email=a@b.c", "-c", "user.name=t", ...a], cwd); if (!r.ok) throw new Error(r.why); return r.out; };
+const commit = (cwd: string, f: string, text: string) => { writeFileSync(join(cwd, f), text); g(cwd, "add", f); g(cwd, "commit", "-qm", `feat: ${f}`); };
+const state = () => JSON.parse(readFileSync(join(project, ".kaizen/runs", ID, "state.json"), "utf8"));
+
+beforeEach(() => {
+  const root = mkdtempSync(join(tmpdir(), "wt-"));
+  remote = join(root, "remote.git"); project = join(root, "project"); other = join(root, "other");
+  g(root, "init", "-q", "--bare", "-b", "main", remote);
+  g(root, "clone", "-q", remote, project);
+  commit(project, "a.txt", "a"); g(project, "push", "-q", "origin", "HEAD:main");
+  g(root, "clone", "-q", remote, other);
+  mkdirSync(join(project, ".kaizen/runs", ID), { recursive: true });
+  writeFileSync(join(project, ".kaizen/runs", ID, "state.json"), JSON.stringify({ id: ID, stage: "build" }));
+  writeFileSync(join(project, ".gitignore"), ".kaizen/*\n");
+});
+
+test("G-01 start leaves the project folder alone and records the worktree", () => {
+  writeFileSync(join(project, "dirty.txt"), "someone else's edit");
+  const head = g(project, "rev-parse", "HEAD"), br = g(project, "branch", "--show-current");
+  const r = startWorktree(project, ID);
+  expect(r.ok).toBe(true);
+  expect(g(project, "rev-parse", "HEAD")).toBe(head);
+  expect(g(project, "branch", "--show-current")).toBe(br);
+  expect(readFileSync(join(project, "dirty.txt"), "utf8")).toBe("someone else's edit");
+  expect(state().branch).toBe(`kaizen/${ID}`);
+  expect(codeDir(project, ID)).toBe(state().worktree);
+  expect(startWorktree(project, ID).ok).toBe(true); // a resume
+});
+
+test("G-06 a run id is a slug before it reaches a path or a branch", () => {
+  expect(startWorktree(project, "../evil").ok).toBe(false);
+  expect(startWorktree(project, "x; rm -rf").ok).toBe(false);
+  expect(landWorktree(project, "../evil").ok).toBe(false);
+});
+
+test("G-02 lands by rebase and push after main moved on", () => {
+  const w = (startWorktree(project, ID) as { path: string }).path;
+  commit(w, "run.txt", "mine");
+  commit(other, "theirs.txt", "x"); g(other, "push", "-q", "origin", "HEAD:main"); // main moves ahead
+  const r = landWorktree(project, ID, run, false);
+  expect(r).toEqual({ ok: true, how: "push", url: undefined });
+  g(project, "fetch", "-q", "origin");
+  expect(g(project, "ls-tree", "--name-only", "origin/main").split("\n")).toEqual(["a.txt", "run.txt", "theirs.txt"]);
+  expect(existsSync(w)).toBe(false);                       // G-04: gone only after landing
+  expect(state().worktree).toBeUndefined();
+});
+
+test("G-02 lands by pull request when gh is there", () => {
+  const w = (startWorktree(project, ID) as { path: string }).path;
+  commit(w, "run.txt", "mine");
+  const calls: string[][] = [];
+  const sh: Run = (cmd, cwd) => {
+    if (cmd[0] !== "gh") return run(cmd, cwd);
+    calls.push(cmd);
+    if (cmd[2] === "create") return { ok: true, out: "https://github.com/x/y/pull/1", why: "" };
+    // gh's rebase-merge, done by hand: the work reaches main under new hashes
+    g(cwd, "fetch", "-q", "origin"); g(cwd, "rebase", "-q", "origin/main");
+    g(cwd, "push", "-q", "origin", "HEAD:main");
+    return { ok: true, out: "", why: "" };
+  };
+  commit(other, "theirs.txt", "x"); g(other, "push", "-q", "origin", "HEAD:main");
+  const r = landWorktree(project, ID, sh, true);
+  expect(r).toEqual({ ok: true, how: "pr", url: "https://github.com/x/y/pull/1" });
+  expect(calls.map((c) => c.slice(0, 4).join(" "))).toEqual(["gh pr create --base", "gh pr merge kaizen/" + ID]);
+  expect(existsSync(w)).toBe(false);
+});
+
+test("G-03 a conflict keeps the worktree and branch and says so", () => {
+  const w = (startWorktree(project, ID) as { path: string }).path;
+  commit(w, "a.txt", "mine");
+  commit(other, "a.txt", "theirs"); g(other, "push", "-q", "origin", "HEAD:main");
+  const r = landWorktree(project, ID, run, false);
+  expect(r.ok).toBe(false);
+  expect(existsSync(w)).toBe(true);
+  expect(g(project, "branch", "--list", `kaizen/${ID}`)).toContain(ID);
+  expect(g(w, "status", "--porcelain")).toBe("");          // rebase aborted, tree clean
+});
+
+test("G-03 a pull request that will not merge is left open", () => {
+  const w = (startWorktree(project, ID) as { path: string }).path;
+  commit(w, "run.txt", "mine");
+  const sh: Run = (cmd, cwd) => cmd[0] !== "gh" ? run(cmd, cwd)
+    : cmd[2] === "create" ? { ok: true, out: "url", why: "" } : { ok: false, out: "", why: "not mergeable" };
+  const r = landWorktree(project, ID, sh, true);
+  expect(r.ok).toBe(false);
+  expect(existsSync(w)).toBe(true);
+});
+
+test("G-03 uncommitted work in the worktree is never landed or removed", () => {
+  const w = (startWorktree(project, ID) as { path: string }).path;
+  writeFileSync(join(w, "wip.txt"), "unsaved");
+  expect(landWorktree(project, ID, run, false).ok).toBe(false);
+  expect(existsSync(join(w, "wip.txt"))).toBe(true);
+});
+
+test("G-05 a run with no worktree has none to land and codeDir is the project", () => {
+  expect(codeDir(project, ID)).toBe(project);
+  expect(landWorktree(project, ID, run, false)).toEqual({ ok: false, why: "this run has no worktree" });
+});
+
+test("projectFromWorktree finds the project from inside a run's folder", () => {
+  expect(projectFromWorktree("/p/.kaizen/wt/2026-10-17-x/cli")).toBe("/p");
+  expect(projectFromWorktree("/p/cli")).toBe("/p/cli");
+});

package/cli/worktree.ts

@@ -0,0 +1,128 @@
+// One branch and one git worktree per run, so agents building at the same time never
+// share a working folder. Run notes stay in the project's .kaizen/runs/<id>/; only the
+// code lives in the worktree. Every git call is an argv array, never a shell string.
+import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+export type Out = { ok: boolean; out: string; why: string };
+export type Run = (cmd: string[], cwd: string) => Out;
+
+const SLUG = /^\d{4}-\d{2}-\d{2}-[a-z0-9][a-z0-9-]*$/;
+const env = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+
+export const run: Run = (cmd, cwd) => {
+  try {
+    const r = Bun.spawnSync(cmd, { cwd, env, stdin: "ignore", timeout: 120_000, windowsHide: true });
+    const out = r.stdout.toString().trimEnd(), err = r.stderr.toString().trim();
+    return { ok: r.exitCode === 0, out, why: (err || out).split("\n").pop() || `${cmd[0]} did not finish` };
+  } catch { return { ok: false, out: "", why: `${cmd[0]} is not installed` }; }
+};
+
+const git = (cwd: string, ...a: string[]) => run(["git", ...a], cwd);
+
+export const branchOf = (id: string) => `kaizen/${id}`;
+export const worktreeOf = (project: string, id: string) => join(project, ".kaizen", "wt", id);
+
+const file = (project: string, id: string) => join(project, ".kaizen", "runs", id, "state.json");
+
+function patchState(project: string, id: string, set: Record<string, unknown>) {
+  const f = file(project, id), s = JSON.parse(readFileSync(f, "utf8"));
+  for (const [k, v] of Object.entries(set)) { if (v === null) delete s[k]; else s[k] = v; }
+  writeFileSync(f, JSON.stringify(s));
+}
+
+/** The folder a run's code is in: its worktree while it has one, else the project. */
+export function codeDir(project: string, id: string): string {
+  try {
+    const w = JSON.parse(readFileSync(file(project, id), "utf8")).worktree;
+    if (typeof w === "string" && existsSync(w)) return w;
+  } catch { /* no state, no worktree */ }
+  return project;
+}
+
+/** The project folder when `dir` is inside one of its run worktrees, else `dir`. */
+export const projectFromWorktree = (dir: string) => {
+  const m = /^(.*?)[\\/]\.kaizen[\\/]wt[\\/]/.exec(dir);
+  return m ? m[1]! : dir;
+};
+
+const baseOf = (project: string) => {
+  const head = git(project, "symbolic-ref", "--short", "refs/remotes/origin/HEAD");
+  return head.ok ? head.out.replace(/^origin\//, "") : "main";
+};
+
+/** Makes the run's worktree and branch off the remote default branch and records both. */
+export function startWorktree(project: string, id: string): { ok: true; path: string; branch: string } | { ok: false; why: string } {
+  if (!SLUG.test(id)) return { ok: false, why: `"${id}" is not a run id` };
+  if (!existsSync(file(project, id))) return { ok: false, why: "no such run" };
+  if (!git(project, "rev-parse", "--is-inside-work-tree").ok) return { ok: false, why: "not a git repository" };
+  const path = worktreeOf(project, id), branch = branchOf(id);
+  if (existsSync(path)) return { ok: true, path, branch }; // already made: a resume
+  if (!git(project, "remote").out) return { ok: false, why: "no git remote to branch from" };
+  const f = git(project, "fetch", "origin");
+  if (!f.ok) return { ok: false, why: `fetch failed: ${f.why}` };
+  const base = `origin/${baseOf(project)}`;
+  const exists = git(project, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`).ok;
+  const add = git(project, "worktree", "add", ...(exists ? [path, branch] : [path, "--no-track", "-b", branch, base]));
+  if (!add.ok) return { ok: false, why: add.why };
+  patchState(project, id, { worktree: path, branch });
+  return { ok: true, path, branch };
+}
+
+export type Landed = { ok: true; how: "pr" | "push"; url?: string } | { ok: false; why: string };
+
+// Whether every commit of the branch is on the base, by patch: a rebase-merge rewrites
+// the hashes, so "is an ancestor" would say not landed for work that is.
+const landed = (dir: string, base: string, branch: string) =>
+  git(dir, "cherry", `origin/${base}`, branch).out.split("\n").every((l) => !l.startsWith("+"));
+
+/**
+ * Pushes the run's branch and lands it on the base: a pull request rebase-merged when
+ * `gh` is there and the pull request is clean, else a rebase and push, retried once.
+ * The worktree and branch go only after the base holds the work; any failure leaves
+ * them where they are.
+ */
+export function landWorktree(project: string, id: string, sh: Run = run,
+  // gh only knows GitHub: any other remote lands by rebase and push.
+  hasGh = !!Bun.which("gh") && /github\.com/.test(git(project, "remote", "get-url", "origin").out)): Landed {
+  if (!SLUG.test(id)) return { ok: false, why: `"${id}" is not a run id` };
+  const dir = codeDir(project, id), branch = branchOf(id);
+  if (dir === project) return { ok: false, why: "this run has no worktree" };
+  const clean = (d: string) => !sh(["git", "status", "--porcelain"], d).out;
+  if (!clean(dir)) return { ok: false, why: "the worktree has uncommitted changes; commit them first" };
+  const base = baseOf(project);
+  const finish = (how: "pr" | "push", url?: string): Landed => {
+    git(project, "fetch", "origin");
+    if (!landed(dir, base, branch)) return { ok: false, why: `${how === "pr" ? "the pull request" : "the push"} went through but ${branch} is not on ${base} yet; worktree kept` };
+    // The worktree is clean (checked above); --force is only for the untracked node_modules link.
+    const rm = git(project, "worktree", "remove", "--force", dir);
+    if (!rm.ok) return { ok: false, why: `landed, but the worktree stays: ${rm.why}` };
+    git(project, "branch", "-D", branch);
+    git(project, "push", "origin", "--delete", branch);
+    patchState(project, id, { worktree: null, branch: null });
+    return { ok: true, how, url };
+  };
+
+  const push = sh(["git", "push", "-u", "origin", branch], dir);
+  if (!push.ok) return { ok: false, why: `push of ${branch} failed: ${push.why}` };
+
+  if (hasGh) {
+    const subject = git(dir, "log", "-1", "--format=%s").out;
+    const pr = sh(["gh", "pr", "create", "--base", base, "--head", branch, "--title", subject, "--body", `Run ${id}.`], dir);
+    // An existing pull request for the branch is fine: merge that one.
+    const url = pr.ok ? pr.out.split("\n").pop() : undefined;
+    if (!pr.ok && !/already exists/i.test(pr.why)) return { ok: false, why: `pull request failed: ${pr.why}; ${branch} is pushed` };
+    const merge = sh(["gh", "pr", "merge", branch, "--rebase"], dir);
+    if (!merge.ok) return { ok: false, why: `pull request not merged (${merge.why}); left open, worktree kept` };
+    return finish("pr", url);
+  }
+
+  for (let i = 0; i < 2; i++) {
+    const f = sh(["git", "fetch", "origin"], dir);
+    if (!f.ok) return { ok: false, why: `fetch failed: ${f.why}` };
+    const rb = sh(["git", "rebase", `origin/${base}`], dir);
+    if (!rb.ok) { sh(["git", "rebase", "--abort"], dir); return { ok: false, why: `rebase onto ${base} conflicts: ${rb.why}; worktree kept` }; }
+    if (sh(["git", "push", "origin", `HEAD:${base}`], dir).ok) return finish("push");
+  }
+  return { ok: false, why: `${base} kept moving; push rejected twice. Worktree kept` };
+}

package/cli/writeback.test.ts

@@ -0,0 +1,102 @@
+// Write-back against a throwaway .kaizen/: gh and Google are injected, nothing leaves the machine.
+import { test, expect, beforeEach, afterAll } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { readIcebox, writeIcebox, writeSources, sift } from "./sources.ts";
+import { writeBacks } from "./writeback.ts";
+
+const root = realpathSync(mkdtempSync(join(tmpdir(), "kaizen-wb-")));
+let state: string;
+let n = 0;
+beforeEach(() => { state = join(root, String(n++), ".kaizen"); mkdirSync(state, { recursive: true }); });
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+const GH = "https://github.com/acme/app/issues";
+const SHEET = "https://docs.google.com/spreadsheets/d/abc123/edit#gid=7";
+const item = (source: string, extra = {}) => ({ id: "a1", text: "Dark mode", source, at: "2026-10-17", status: "done" as const, run: "r1", ...extra });
+const source = (url: string, writeback = true) => writeSources(state, [{ url, added: "x", seen: [], ...(writeback ? { writeback } : {}) }]);
+
+test("github: a done item closes its issue once, with fixed text", async () => {
+  source(GH);
+  writeIcebox(state, [item(GH, { notes: "#12 · https://github.com/acme/app/issues/12" })]);
+  const calls: string[][] = [];
+  const gh = async (a: string[]) => { calls.push(a); return { code: 0, err: "" }; };
+  await writeBacks(state, { gh });
+  await writeBacks(state, { gh });
+  expect(calls).toEqual([["issue", "close", "12", "--repo", "acme/app", "--comment", "Done in kaizen run r1."]]);
+  expect(readIcebox(state)[0]!.written).toBeTruthy();
+});
+
+test("off by default: nothing is sent", async () => {
+  source(GH, false);
+  writeIcebox(state, [item(GH, { notes: "#12 · x" })]);
+  let sent = 0;
+  await writeBacks(state, { gh: async () => { sent++; return { code: 0, err: "" }; } });
+  expect(sent).toBe(0);
+});
+
+test("a failed write stays done, keeps the error and is tried again", async () => {
+  source(GH);
+  writeIcebox(state, [item(GH, { notes: "#12 · x" })]);
+  await writeBacks(state, { gh: async () => ({ code: 1, err: "boom\nHTTP 401" }) });
+  expect(readIcebox(state)[0]).toMatchObject({ status: "done", writeError: "HTTP 401" });
+  expect(readIcebox(state)[0]!.written).toBeUndefined();
+  await writeBacks(state, { gh: async () => ({ code: 0, err: "" }) });
+  expect(readIcebox(state)[0]!.written).toBeTruthy();
+  expect(readIcebox(state)[0]!.writeError).toBeUndefined();
+});
+
+function google(rows: string[][]) {
+  const puts: { url: string; body: any }[] = [];
+  const doFetch = (async (url: string, init: any = {}) => {
+    if (init.method === "PUT") { puts.push({ url: decodeURIComponent(url), body: JSON.parse(init.body) }); return Response.json({}); }
+    if (url.includes("fields=sheets")) return Response.json({ sheets: [{ properties: { sheetId: 7, title: "Req" } }] });
+    const range = /values\/([^?]+)/.exec(decodeURIComponent(url))![1]!;
+    const m = /!(\d+):(\d+)$/.exec(range)!;
+    return Response.json({ values: rows.slice(+m[1]! - 1, +m[2]!) });
+  }) as unknown as typeof fetch;
+  return { puts, doFetch };
+}
+
+test("sift records the sheet row an item came from", () => {
+  const { items } = sift("sheet", "Request\tStatus\nDark mode\topen\nFaster search\topen\n");
+  expect(items.map((i) => [i.text, i.row])).toEqual([["Dark mode", 2], ["Faster search", 3]]);
+});
+
+const token = async () => "t";
+
+test("sheet: adds a Status column when missing, then writes Done in the row", async () => {
+  source(SHEET);
+  writeIcebox(state, [item(SHEET, { row: 2 })]);
+  const g = google([["Request"], ["Dark mode"]]);
+  await writeBacks(state, { fetch: g.doFetch, token });
+  expect(g.puts.map((p) => [p.url.split("values/")[1]!.split("?")[0], p.body.values[0][0]])).toEqual([["'Req'!B1", "Status"], ["'Req'!B2", "Done in kaizen run r1."]]);
+  expect(readIcebox(state)[0]!.written).toBeTruthy();
+});
+
+test("sheet: a row that no longer holds the request is left alone", async () => {
+  source(SHEET);
+  writeIcebox(state, [item(SHEET, { row: 2 })]);
+  const g = google([["Request", "Status"], ["Something else", ""]]);
+  await writeBacks(state, { fetch: g.doFetch, token });
+  expect(g.puts).toEqual([]);
+  expect(readIcebox(state)[0]).toMatchObject({ writeError: "the row has changed since it was gathered" });
+});
+
+test("sheet: uses the existing Status column", async () => {
+  source(SHEET);
+  writeIcebox(state, [item(SHEET, { row: 2 })]);
+  const g = google([["Request", "Owner", "Status"], ["Dark mode", "x", ""]]);
+  await writeBacks(state, { fetch: g.doFetch, token });
+  expect(g.puts.map((p) => p.url.split("values/")[1]!.split("?")[0])).toEqual(["'Req'!C2"]);
+});
+
+test("sheet: a header below row 10 is still found", async () => {
+  source(SHEET);
+  const rows = [...Array.from({ length: 14 }, () => [""]), ["Request", "Status"], ["Dark mode", ""]];
+  writeIcebox(state, [item(SHEET, { row: 16 })]);
+  const g = google(rows);
+  await writeBacks(state, { fetch: g.doFetch, token });
+  expect(g.puts.map((p) => p.url.split("values/")[1]!.split("?")[0])).toEqual(["'Req'!B16"]);
+});

package/cli/writeback.ts

@@ -0,0 +1,79 @@
+// Closes the loop: when a promoted request's run is done, tell the place it came from.
+// A GitHub issue gets a comment and is closed (through the user's own `gh` login); a
+// sheet row gets "Done in <run>" in its Status column. Off unless the source says so.
+// The text sent is fixed: nothing the source said is ever sent back or put in a command.
+import { normalise } from "./state.ts";
+import { readIcebox, writeIcebox, readSources, type Signal, type Source } from "./sources.ts";
+import * as google from "./google.ts";
+
+type Gh = (args: string[]) => Promise<{ code: number; err: string }>;
+const runGh: Gh = async (args) => {
+  try {
+    const p = Bun.spawn(["gh", ...args], { stdout: "ignore", stderr: "pipe" });
+    const err = await new Response(p.stderr).text();
+    return { code: await p.exited, err };
+  } catch { return { code: 127, err: "The gh command was not found. Install GitHub's CLI and run `gh auth login`." }; }
+};
+
+const say = (run: string) => `Done in kaizen run ${run}.`;
+const col = (i: number) => { let s = ""; for (i++; i; i = Math.floor((i - 1) / 26)) s = String.fromCharCode(65 + ((i - 1) % 26)) + s; return s; };
+
+async function github(it: Signal, src: Source, gh: Gh): Promise<string | null> {
+  const repo = /^https:\/\/(?:www\.)?github\.com\/([\w.-]+\/[\w.-]+)\/issues\/?$/.exec(src.url.split(/[?#]/)[0]!)?.[1];
+  const n = /^#(\d+) /.exec(it.notes ?? "")?.[1];
+  if (!repo || !n) return "no issue number was kept for this item";
+  const r = await gh(["issue", "close", n, "--repo", repo, "--comment", say(it.run!)]);
+  return r.code ? (r.err.trim().split("\n").pop() || `gh exited ${r.code}`).slice(0, 200) : null;
+}
+
+// The row's own request cell is re-read first: if rows moved since the gather, the
+// status goes nowhere rather than onto the wrong request.
+async function sheet(it: Signal, src: Source, doFetch: typeof fetch, token?: () => Promise<string>): Promise<string | null> {
+  const id = /^https:\/\/docs\.google\.com\/spreadsheets\/d\/([\w-]+)/.exec(src.url)?.[1];
+  if (!id || !it.row) return "no row number was kept for this item";
+  const gid = /[#&?]gid=(\d+)/.exec(src.url)?.[1] ?? "0";
+  const meta = await google.sheets(`${id}?fields=sheets.properties(sheetId,title)`, {}, doFetch, token);
+  const title = meta.sheets?.find((s: any) => String(s.properties.sheetId) === gid)?.properties.title as string | undefined;
+  if (!title) return "the sheet's tab was not found";
+  const q = `'${title.replace(/'/g, "''")}'`;
+  const head = (await google.sheets(`${id}/values/${encodeURIComponent(`${q}!1:50`)}`, {}, doFetch, token)).values as string[][] | undefined ?? [];
+  const at = it.row <= 50 ? head[it.row - 1] : (await google.sheets(`${id}/values/${encodeURIComponent(`${q}!${it.row}:${it.row}`)}`, {}, doFetch, token)).values?.[0];
+  const want = normalise(it.text);
+  if (!at?.some((c) => { const t = normalise(c ?? ""); return t && (t.startsWith(want) || want.startsWith(t)); })) return "the row has changed since it was gathered";
+  // The Status column is the one headed so; with none, it is added after the last header cell.
+  let hr = head.findIndex((r) => r.some((c) => /^status$/i.test((c ?? "").trim())));
+  let c = hr >= 0 ? head[hr]!.findIndex((x) => /^status$/i.test((x ?? "").trim())) : -1;
+  if (c < 0) {
+    hr = head.findIndex((r) => r.some((x) => x?.trim()));
+    if (hr < 0) return "the sheet has no header row to add a Status column to";
+    c = head[hr]!.length;
+    await google.sheets(`${id}/values/${encodeURIComponent(`${q}!${col(c)}${hr + 1}`)}?valueInputOption=RAW`, { method: "PUT", body: { values: [["Status"]] } }, doFetch, token);
+  }
+  await google.sheets(`${id}/values/${encodeURIComponent(`${q}!${col(c)}${it.row}`)}?valueInputOption=RAW`, { method: "PUT", body: { values: [[say(it.run!)]] } }, doFetch, token);
+  return null;
+}
+
+const busy = new Set<string>();
+
+// Every done item whose source asks for it and that has not been written yet. A failure
+// is kept on the item and tried again on the next call; success is stamped and never repeated.
+export async function writeBacks(state: string, deps: { gh?: Gh; fetch?: typeof fetch; token?: () => Promise<string> } = {}): Promise<void> {
+  const sources = readSources(state);
+  for (const it of readIcebox(state)) {
+    const src = sources.find((s) => s.url === it.source);
+    const key = state + " " + it.id;
+    if (it.status !== "done" || !it.run || it.written || !src?.writeback || busy.has(key)) continue;
+    busy.add(key);
+    let err: string | null;
+    try {
+      err = /github\.com/.test(src.url) ? await github(it, src, deps.gh ?? runGh)
+        : /docs\.google\.com\/spreadsheets/.test(src.url) ? await sheet(it, src, deps.fetch ?? fetch, deps.token)
+        : "this kind of source cannot be written to";
+    } catch (e) { err = ((e as Error).message || String(e)).slice(0, 200); }
+    finally { busy.delete(key); }
+    const ice = readIcebox(state), now = ice.find((s) => s.id === it.id);
+    if (!now) continue;
+    if (err) { now.writeError = err; delete now.written; } else { now.written = new Date().toISOString(); delete now.writeError; }
+    writeIcebox(state, ice);
+  }
+}

package/package.json

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

@@ -111,21 +111,14 @@ worth two more stages to confirm a one-line message now reads correctly. A findi
 `high` or above pulls the run back onto the full path whatever its size, since that
 severity is the loop's whole reason for existing.
 
-**Trivial changes take the direct path.** Where the request is one obvious change with
-nothing to decide — a typo, a label, a one-line copy or config tweak — a plan is longer
-than the work and a review re-reads what the user is about to look at anyway. Write
-`00-request.md`, build straight away, write `03-impl.md`, and stop at
-`stage: "review"`, `awaiting: "approvals.review"`: the user checks the result and
-approves it or says what to change. No `01-plan.md`, no plan approval, no
-`04-review.md` — the user's check is the review. Never the direct path for money, data,
-a migration, security, anything hard to undo, or a request with an open question; in
-`plan-only`, `auto`, or `/kaizen full`; or when in doubt. Work that turns out bigger
-mid-build stops and goes back to a plan.
+**Short work still gets a run.** A one-line change is not skipped past the stages: the card on the board moves through plan, build and review like any other. Run it with `runner: lite` and the short path above — a brief plan, the build, a short review — so the cost stays small and the run stays visible.
 
 This is a judgement, not a threshold to enforce: fifty lines that change how money is
-rounded are not a small change. Say which path you took and why, in one line, when the
+rounded are not a small change. Say which path you took (short or full) and why, in one line, when the
 run starts.
 
+**Follow-ups are runs too.** Both runners record the same artifacts: `01-plan.md`, `03-impl.md`, `04-review.md`, and a final `state.json` — `lite` and `full` differ only in who executes the stages. A message the user sends later in the same session is judged by what it asks: a question, explanation or chat is answered, no run; a request to change or produce something is building, so it goes through the flow. While the previous run has not reached `done` (including awaiting its final approval), the change is a revise of that run, recorded in `02-approval.md`. After `done` or `abandoned`, open a new run whose `00-request.md` is the user's words verbatim, then a line `Follow-up of: <previous run id>`. Never reopen a finished run. When unsure whether a message asks for a change, ask once.
+
 ## Modes
 
 Set by `mode` in config, overridable per invocation.

package/skills/kaizen/config.default.yml

@@ -131,6 +131,11 @@ git:
   # Create a branch before the implement stage when on the default branch.
   # Ignored when the project is not a git repository.
   branch_before_implement: true
+  # Build each run on its own branch (kaizen/<run-id>) in its own git worktree under
+  # .kaizen/wt/, so runs and people working at the same time never share a folder. Done
+  # lands the branch by pull request (gh) or a rebase and push. Ignored when the
+  # project is not a git repository with a remote.
+  worktree_per_run: true
 
 ui:
   # Mouse in the TUI: click a row or card to select it, click it again to open or

package/skills/kaizen/settings.md

@@ -24,6 +24,7 @@ nearest first, so a change lands globally unless this project keeps its own conf
 | `review.write_memory` | `true`, `false` | Let the reviewer append lessons to `memory.md` |
 | `git.auto_commit` | `true`, `false` | Commit the work when a run finishes |
 | `git.branch_before_implement` | `true`, `false` | Branch before building when on the default branch |
+| `git.worktree_per_run` | `true`, `false` | Build each run on its own branch in its own worktree and land it by pull request |
 | `ui.mouse` | `false`, `true` | Click to select, click again to act; while on, the terminal cannot select text |
 | `subagents.model` | `inherit`, `opus`, `sonnet`, `haiku` | Model the stage subagents run on (Claude Code only) |
 | `subagents.effort` | `inherit`, `low`, `medium`, `high` | Reasoning effort for the stage subagents (Claude Code only) |

package/skills/kaizen/spec-build.md

@@ -9,11 +9,6 @@ builder's contract. The planner and reviewer do not read it.
 **Agent:** builder. **Input:** `01-plan.md`, `02-approval.md`, the track.
 **Output:** the deliverable itself, plus `03-impl.md`.
 
-On the direct path (see `spec.md`, Stage 0) there is no plan: the input is
-`00-request.md`, and the request is the scope. If the work turns out to need a
-decision, more than the one obvious change, or anything the direct path excludes,
-stop and send the run back to `stage: "plan"`.
-
 The builder produces whatever the track's deliverable is — code, a chapter, the
 campaign copy, the runbook — and nothing else.
 
@@ -44,6 +39,21 @@ Rules:
   folder there is no branch to make and no commit to skip, and that absence is not a
   finding.
 
+**Build on the run's own branch, where `git.worktree_per_run` is on** (the default, in a
+git repository with a remote). Right after `stage: "build"` is written and before the
+first edit, run `kaizen worktree start` with the run id from the project folder. It
+makes `.kaizen/wt/<id>` on the branch `kaizen/<id>`, cut from the remote default branch,
+and records `worktree` and `branch` in `state.json`. From then on every edit, test run
+and commit of the code happens inside that folder, and never in the project folder,
+which other sessions may be using. Everything the run *records* stays in the project's
+`.kaizen/runs/<id>/`: `03-impl.md`, `progress.md`, attachments and `state.json` are
+written there by absolute path. The docs vault is committed, so its notes are updated in
+the worktree with the code. The worktree has its own checkout: run `bun install` or the
+project's equivalent there before the baseline. Fix iterations and the reviewer read the
+code in the same folder. If `kaizen worktree start` fails, say why and stop; do not fall
+back to the project folder unasked. A run whose `state.json` has no `worktree` builds in
+place, exactly as before.
+
 **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
@@ -87,8 +97,7 @@ cover, and note in `03-impl.md` what was missing from it.
 deviations from the plan and why, verification carried out with its actual result,
 anything deliberately left undone, a `## Preview` section with its `### How to test`
 steps, and — in a git repository — a `## Commit` section, both described below. A
-report without `## Preview` leaves the board's Preview tab empty, in every runner and
-on the direct path alike. Write each changed path in backticks, relative
+report without `## Preview` leaves the board's Preview tab empty, in every runner. Write each changed path in backticks, relative
 to the repository, and no other path that way: the board commits a run by the changed
 files its report names, so a changed path written any other way is left out of the
 commit, and a backticked path the run did not change is taken into it. Report failures honestly; a false claim of
@@ -99,9 +108,14 @@ commands to start it locally and the URL to open, copied from the material's own
 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.
-Where the result can be seen, put screenshots of it here: save each under
+Where the result can be seen, put screenshots of it here. On a `code` track this is required, not optional: run the result and attach proof.
+A UI (a page, a board, a terminal screen, an app window) gets a screenshot of the changed
+screen; a CLI, library or API gets the real output of the command that exercises it, pasted
+in a code block. A code report with no proof is incomplete. Save each under
 `runs/<id>/attachments/` (letters, digits, `.`, `-`, `_` only) and embed it as
 `![what it shows](attachments/<name>.png)`; the board shows them in the Preview tab.
+A headless browser does it: `playwright screenshot <url> runs/<id>/attachments/<name>.png`.
+Where no proof can be produced, say why in one line under `## Preview`.
 
 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

package/skills/kaizen/spec-main.md

@@ -85,17 +85,23 @@ subagents at all.
 
 ## Final approval
 
-Controlled by `approvals.review`, skipped in `auto`. A direct-path run always stops here,
-whatever `approvals.review` says: the user's check is its only review.
+Controlled by `approvals.review`, skipped in `auto`.
 
-Report: what was built, verification results, findings fixed, findings still open,
+Report: what was built (for a code run, show its Preview proof), verification results, findings fixed, findings still open,
 every criterion the reviewer answered `CANNOT VERIFY` with the check it says a human
 must make, and anything the builder noted as out of scope. Where the run used `runner: lite`, say
 so in that report — the reviewer saw the work, and nobody should read a same-session
-review as an independent one because the output looked the same. Where the run took
-the direct path, say there was no plan and no review: the user's check is the review.
+review as an independent one because the output looked the same.
+Later build requests in the same session follow *Follow-ups are runs too* in [`spec.md`](spec.md): a revise of this run until it is `done`, then a new linked run.
 Then stop. Committing, pushing, or
-opening a pull request happens only if the user asks.
+opening a pull request happens only if the user asks; the board's Approve button is that ask for commit and push, and its prompt says so.
+For a run with a `worktree` in `state.json`, that ask means: commit in the worktree, then
+`kaizen worktree land` with the run id, from the project folder,. It pushes `kaizen/<id>`, opens a pull
+request and rebase-merges it when GitHub says it is clean (without `gh`: a rebase onto
+the default branch and a push, tried twice), and removes the worktree and branch only
+once the default branch holds the work. A conflict or an unmerged pull request leaves
+everything in place: report its message as printed and let the user decide. The run is
+`done` once approved; whether the work landed is reported, not hidden.
 
 **Open findings are offered by number.** List them with the reviewer's numbering
 intact and let the user name which to fix — "fix 2 and 5". A number not named is not

package/skills/kaizen/spec-review.md

@@ -43,7 +43,9 @@ Five checks are universal, in every track:
    now is a `high` finding at minimum, whatever else the work achieved. If the builder
    recorded no baseline, that absence is itself the finding. So is a `03-impl.md`
    without a `## Preview` section, or one without `### How to test` steps: `medium`,
-   since the user is left with no way to try the work.
+   since the user is left with no way to try the work. A `code` run whose
+   `## Preview` has no proof (screenshot for a UI, real command output otherwise) and gives
+   no reason is `high`.
 
 5. **Acceptance** — every criterion, `G-nn` and `R-nn`, answered against the work
    rather than against `03-impl.md`, by trying to falsify it: name the concrete check

package/skills/kaizen/spec.md

@@ -5,8 +5,7 @@ follow this document; only the way stages are dispatched differs per tool. If an
 adapter and this file disagree, this file wins.
 
 A stage may only start when the previous stage's artifact exists on disk and the approval
-between them, if enabled, has been resolved. The one exception is the direct path
-(see *Stage 0*), which skips the plan and the review on purpose.
+between them, if enabled, has been resolved.
 
 ---
 
@@ -144,16 +143,9 @@ the config said the day someone came back to it.
 If the request remains ambiguous enough that a plan would be guesswork, ask now. One
 round of questions here is cheaper than a rejected plan.
 
-**The direct path.** Where the request is one obvious change with nothing to decide —
-a typo, a label, a one-line copy or config tweak — and being wrong is cheap and
-visible, intake may skip the plan and the review: say so in one line, set
-`stage: "build"`, build against `00-request.md`, write `03-impl.md` — its `## Preview`
-included, since the user's check starts there — then set
-`stage: "review"`, `awaiting: "approvals.review"` and stop for the user to check the
-result. No `01-plan.md` or `04-review.md` is written, and no `02-approval.md` unless
-the user revises at that stop. Never for money, data, a migration, security, anything
-hard to undo, or a request with an open question; never in `plan-only` or `auto`
-mode or under `runner: full`; and when in doubt, not.
+**Short work is not skipped.** Even a one-line change gets `01-plan.md` and `04-review.md`, so the run moves through every stage. Keep them brief and run under `runner: lite`.
+
+**Follow-ups are runs too.** Both runners record the same artifacts: `01-plan.md`, `03-impl.md`, `04-review.md`, and a final `state.json` — `lite` and `full` differ only in who executes the stages. A message the user sends later in the same session is judged by what it asks: a question, explanation or chat is answered, no run; a request to change or produce something is building, so it goes through the flow. While the previous run has not reached `done` (including awaiting its final approval), the change is a revise of that run, recorded in `02-approval.md`. After `done` or `abandoned`, open a new run whose `00-request.md` is the user's words verbatim, then a line `Follow-up of: <previous run id>`. Never reopen a finished run. When unsure whether a message asks for a change, ask once.
 
 ---