kaizen-agent 1.34.2 → 1.34.3

package/cli/google.ts

@@ -0,0 +1,99 @@
+// Sign in with Google, for one thing: writing "done" back into the sheet a request was
+// gathered from. The user brings their own OAuth client (Desktop app type, Sheets API
+// on): a client secret shipped in an open-source app would be shared by every install.
+// Tokens stay in ~/.kaizen/google.json, owner-only, and go to Google hosts only.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { home } from "./state.ts";
+
+const AUTH = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN = "https://oauth2.googleapis.com/token";
+const SCOPE = "https://www.googleapis.com/auth/spreadsheets";
+const FILE = () => join(home, ".kaizen", "google.json");
+
+type Creds = { client_id?: string; client_secret?: string; refresh_token?: string; access_token?: string; expires_at?: number };
+
+const load = (): Creds => { try { return JSON.parse(readFileSync(FILE(), "utf8")); } catch { return {}; } };
+
+function save(c: Creds) {
+  mkdirSync(join(home, ".kaizen"), { recursive: true });
+  const tmp = FILE() + ".tmp";
+  writeFileSync(tmp, JSON.stringify(c, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, FILE());
+}
+
+export function status() {
+  const c = existsSync(FILE()) ? load() : {};
+  return { connected: !!c.refresh_token, hasClient: !!(c.client_id && c.client_secret) };
+}
+
+export function setClient(id: string, secret: string) {
+  save({ client_id: id.trim(), client_secret: secret.trim() });   // a new client voids the old sign-in
+}
+
+export function signOut() { const { client_id, client_secret } = load(); save({ client_id, client_secret }); }
+
+const b64url = (b: ArrayBuffer | Uint8Array) => Buffer.from(b instanceof Uint8Array ? b : new Uint8Array(b)).toString("base64url");
+const rand = () => b64url(crypto.getRandomValues(new Uint8Array(32)));
+
+let pending: { state: string; verifier: string; redirect: string } | null = null;
+
+export async function authorizeUrl(port: number): Promise<string> {
+  const c = load();
+  if (!c.client_id || !c.client_secret) throw new Error("Add the Google client id and secret first.");
+  const verifier = rand(), state = rand();
+  const redirect = `http://127.0.0.1:${port}/google-callback`;
+  pending = { state, verifier, redirect };
+  const challenge = b64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));
+  return `${AUTH}?${new URLSearchParams({ client_id: c.client_id, redirect_uri: redirect, response_type: "code", scope: SCOPE, access_type: "offline", prompt: "consent", state, code_challenge_method: "S256", code_challenge: challenge })}`;
+}
+
+async function token(form: Record<string, string>) {
+  const r = await fetch(TOKEN, { method: "POST", body: new URLSearchParams(form), signal: AbortSignal.timeout(30_000) });
+  const j: any = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(j.error_description || j.error || `sign-in failed (HTTP ${r.status})`);
+  return j;
+}
+
+// Null when signed in; otherwise why not.
+export async function callback(q: URLSearchParams): Promise<string | null> {
+  const p = pending, c = load();
+  if (!p || q.get("state") !== p.state) return "This sign-in is stale. Start it again from the Icebox.";
+  pending = null;
+  if (q.get("error")) return q.get("error");
+  if (!q.get("code") || !c.client_id || !c.client_secret) return "Google sent no sign-in code back.";
+  try {
+    const t = await token({ grant_type: "authorization_code", client_id: c.client_id, client_secret: c.client_secret, code: q.get("code")!, code_verifier: p.verifier, redirect_uri: p.redirect });
+    if (!t.refresh_token) return "Google gave no refresh token. Remove kaizen from your Google account's third-party access and connect again.";
+    if (!String(t.scope ?? "").split(" ").includes(SCOPE)) return "Google did not grant access to your sheets.";
+    save({ ...c, refresh_token: t.refresh_token, access_token: t.access_token, expires_at: Date.now() + (t.expires_in ?? 3600) * 1000 });
+    return null;
+  } catch (e) { return (e as Error).message; }
+}
+
+async function access(): Promise<string> {
+  const c = load();
+  if (!c.refresh_token || !c.client_id || !c.client_secret) throw new Error("Google is not connected.");
+  if (c.access_token && (c.expires_at ?? 0) > Date.now() + 60_000) return c.access_token;
+  try {
+    const t = await token({ grant_type: "refresh_token", client_id: c.client_id, client_secret: c.client_secret, refresh_token: c.refresh_token });
+    save({ ...c, access_token: t.access_token, expires_at: Date.now() + (t.expires_in ?? 3600) * 1000 });
+    return t.access_token;
+  } catch (e) {
+    if (/invalid_grant/.test((e as Error).message)) { signOut(); throw new Error("Google signed kaizen out. Connect again from the Icebox."); }
+    throw e;
+  }
+}
+
+// A Sheets API call. Only the Sheets host is ever sent the token.
+export async function sheets(path: string, init: { method?: string; body?: unknown } = {}, doFetch: typeof fetch = fetch, token: () => Promise<string> = access): Promise<any> {
+  const r = await doFetch(`https://sheets.googleapis.com/v4/spreadsheets/${path}`, {
+    method: init.method ?? "GET",
+    headers: { authorization: `Bearer ${await token()}`, ...(init.body ? { "content-type": "application/json" } : {}) },
+    ...(init.body ? { body: JSON.stringify(init.body) } : {}),
+    signal: AbortSignal.timeout(30_000),
+  });
+  const j: any = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(j.error?.message || `Google Sheets answered HTTP ${r.status}`);
+  return j;
+}

package/cli/install.ts

@@ -346,6 +346,20 @@ if (wantSettings) {
   process.exit(0);
 }
 
+// A run's own branch and worktree: `start` makes them before the build, `land` pushes
+// and merges them at the final approval. Run from the project folder.
+if (args.has("worktree")) {
+  const [, verb = "", id = ""] = Bun.argv.slice(2).filter((a) => !a.startsWith("-"));
+  const { locate } = await import("./state.ts");
+  const { startWorktree, landWorktree } = await import("./worktree.ts");
+  const state = locate();
+  if (!state || (verb !== "start" && verb !== "land")) { console.log("\n  usage: kaizen worktree start|land <run-id>, in a project with .kaizen\n"); process.exit(1); }
+  const project = dirname(state);
+  const r = verb === "start" ? startWorktree(project, id) : landWorktree(project, id);
+  console.log(r.ok ? `\n  ${verb === "start" ? `worktree ready: ${(r as { path: string }).path}` : `landed by ${(r as { how: string }).how}`}\n` : `\n  ${r.why}\n`);
+  process.exit(r.ok ? 0 : 1);
+}
+
 // Deleting runs is a job for code with a test, not for an agent with `rm`. Lists by
 // default; --yes is what deletes.
 if (args.has("prune")) {

package/cli/settings.ts

@@ -30,6 +30,7 @@ export const PRESETS: Record<PresetName, {
       "auto_fix.max_iterations": "1",
       "git.auto_commit": "false",
       "git.branch_before_implement": "false",
+      "git.worktree_per_run": "false",
     },
   },
   medium: {
@@ -47,6 +48,7 @@ export const PRESETS: Record<PresetName, {
       "auto_fix.max_iterations": "2",
       "git.auto_commit": "false",
       "git.branch_before_implement": "true",
+      "git.worktree_per_run": "true",
     },
   },
   ultra: {
@@ -64,6 +66,7 @@ export const PRESETS: Record<PresetName, {
       "auto_fix.max_iterations": "4",
       "git.auto_commit": "true",
       "git.branch_before_implement": "true",
+      "git.worktree_per_run": "true",
     },
   },
 };
@@ -111,6 +114,7 @@ const SETTINGS: Setting[] = [
   { key: "auto_fix.max_iterations", label: "Max fix rounds", group: "Auto-fix", values: ["1", "2", "3", "4", "5"], help: "Fix-then-recheck rounds before leftovers are handed to you. Each round is a full build plus a full review, the priciest knob here" },
   { key: "git.auto_commit", label: "Commit when done", group: "Git", values: ["false", "true"], help: "Commit the work when a run finishes. Never pushes" },
   { key: "git.branch_before_implement", label: "Branch before building", group: "Git", values: ["true", "false"], help: "Create a branch before building when you are on the default branch" },
+  { key: "git.worktree_per_run", label: "Branch and folder per run", group: "Git", values: ["true", "false"], help: "Build each run on its own branch in its own git worktree, then land it by pull request. false: every run builds in the project folder" },
   { key: "track.default", label: "Kind of work", group: "Project", values: ["auto", "software", "writing", "communication", "operations", "research"], help: "Pin what runs in this project are (a docs repo is always writing). auto: the planner infers it per run" },
   { key: "review.write_memory", label: "Remember lessons", group: "Project", values: ["true", "false"], help: "Let the reviewer save what it learned to .kaizen/memory.md, which every future run reads" },
   { key: "review.memory_max_lines", label: "Memory size cap", group: "Project", values: ["50", "100", "200", "400"], help: "Lines memory.md may hold before old lessons are pruned. Every run reads it, so bigger costs more" },

package/cli/sources.test.ts

@@ -8,7 +8,7 @@ import { readInbox, writeInbox, replaceIdea, parseItem } from "./state.ts";
 import {
   readSources, addSource, removeSource, ingest, checkUrl, resolvesPublic, exportUrl, fetchText, split, sift,
   gatherSource, freshImages, gatherAll, due, takeImages, sheetImages, docImages, imagesUrl, SIGN_IN, UNREADABLE, CAP, moveSource, gatherDirs, writeSources,
-  readIcebox, writeIcebox, promote, dismiss, markReplied, setCategory, socialUrl, socialOf, AGENT_ONLY, PLATFORMS,
+  readIcebox, writeIcebox, promote, markDone, dismiss, markReplied, setCategory, socialUrl, socialOf, AGENT_ONLY, PLATFORMS,
 } from "./sources.ts";
 
 const root = realpathSync(mkdtempSync(join(tmpdir(), "kaizen-src-")));   // macOS: tmpdir is a symlink into /private
@@ -145,7 +145,7 @@ test("split: a title row above the header is skipped; without a header one colum
 test("split: a header row holding a `#`, a year or a date cell is still the header", async () => {
   for (const head of ["#\tRequest\tStatus", "No\tRequest\tStatus\t2026", "No\tRequest\tStatus\t2026-09-30", "No\tRequest\tStatus\t17-Sep-2026", "\tRequest\tStatus"]) {
     const body = `${head}\n1\tFix login page\tOpen\n2\tAdd export\tDone\n`;
-    expect(sift("sheet", body)).toEqual({ items: [{ text: "Fix login page", notes: "1 · Open" }], done: 1 });
+    expect(sift("sheet", body)).toEqual({ items: [{ text: "Fix login page", notes: "1 · Open", row: 2 }], done: 1 });
   }
   // A numbered row is data even when one of its cells is a header word said once.
   expect(split("sheet", "1\tIssue\tLogin fails on Safari\n2\tBug\tExport drops rows\n3\tBug\tSearch is slow\n").map((i) => i.text))
@@ -347,15 +347,16 @@ test("a first word that is a kaizen command is prefixed", () => {
 
 // A one-cell header stays the header, whatever the rows under it hold. A title above
 // it is read as the header (backlog), as it always was.
+const noRow = (r: ReturnType<typeof sift>) => ({ ...r, items: r.items.map(({ row, ...i }) => i) });
 test("split: a one-cell header is the header over any rows below it", async () => {
   const feedback = "Feedback\nNO\tPIC\tDETAIL\tSTATUS\n1\tBudi\tTombol export tidak muncul\tOpen\n2\tSiti\tTambah opsi\tDone\n";
-  expect(sift("sheet", feedback)).toEqual({ items: [{ text: "NO", notes: "PIC · DETAIL · STATUS" }, { text: "1", notes: "Budi · Tombol export tidak muncul · Open" }, { text: "2", notes: "Siti · Tambah opsi · Done" }], done: 0 });
-  expect(sift("sheet", "Request\nFix login\nAdd export\n")).toEqual({ items: [{ text: "Fix login" }, { text: "Add export" }], done: 0 });
-  expect(sift("sheet", "Request\nFix login\nAdd export\tsee ticket 5\n")).toEqual({ items: [{ text: "Fix login" }, { text: "Add export", notes: "see ticket 5" }], done: 0 });
-  expect(sift("sheet", "Request\t\nFix login\tBudi\nAdd export\tSiti\n")).toEqual({ items: [{ text: "Fix login", notes: "Budi" }, { text: "Add export", notes: "Siti" }], done: 0 });
+  expect(sift("sheet", feedback)).toEqual({ items: [{ text: "NO", notes: "PIC · DETAIL · STATUS", row: 2 }, { text: "1", notes: "Budi · Tombol export tidak muncul · Open", row: 3 }, { text: "2", notes: "Siti · Tambah opsi · Done", row: 4 }], done: 0 });
+  expect(sift("sheet", "Request\nFix login\nAdd export\n")).toEqual({ items: [{ text: "Fix login", row: 2 }, { text: "Add export", row: 3 }], done: 0 });
+  expect(noRow(sift("sheet", "Request\nFix login\nAdd export\tsee ticket 5\n"))).toEqual({ items: [{ text: "Fix login" }, { text: "Add export", notes: "see ticket 5" }], done: 0 });
+  expect(noRow(sift("sheet", "Request\t\nFix login\tBudi\nAdd export\tSiti\n"))).toEqual({ items: [{ text: "Fix login", notes: "Budi" }, { text: "Add export", notes: "Siti" }], done: 0 });
   // A later row whose lone cell reads like a header word is still data.
-  expect(sift("sheet", "Request\nFix login\tBug\nRename page heading\tTitle\nAdd export\tFeature\n")).toEqual({ items: [{ text: "Fix login", notes: "Bug" }, { text: "Rename page heading", notes: "Title" }, { text: "Add export", notes: "Feature" }], done: 0 });
-  expect(sift("sheet", "Request\nFix login\tStatus\nAdd export\tdone\n")).toEqual({ items: [{ text: "Fix login", notes: "Status" }, { text: "Add export", notes: "done" }], done: 0 });
+  expect(noRow(sift("sheet", "Request\nFix login\tBug\nRename page heading\tTitle\nAdd export\tFeature\n"))).toEqual({ items: [{ text: "Fix login", notes: "Bug" }, { text: "Rename page heading", notes: "Title" }, { text: "Add export", notes: "Feature" }], done: 0 });
+  expect(noRow(sift("sheet", "Request\nFix login\tStatus\nAdd export\tdone\n"))).toEqual({ items: [{ text: "Fix login", notes: "Status" }, { text: "Add export", notes: "done" }], done: 0 });
   const guessed = "1\tOpen\tTombol export tidak muncul\n2\tOpen\tTambah opsi ingat saya\n";
   addSource(state, SHEET);
   expect(await gatherSource(state, SHEET, text(guessed), pub)).toMatchObject({ added: 2, note: "2 new" });
@@ -643,7 +644,7 @@ test("the board refuses to add a source without a project, and moves one between
     expect(readIcebox(a).map((s) => s.status)).toEqual(["promoted", "new"]);
     expect(await ice({ op: "dismiss", dir: a, ids: [y!.id] })).toMatchObject({ status: 200 });
     const listedIce = ((await (await fetch(at + "/sources")).json()) as any).icebox;
-    expect(listedIce).toEqual([]);
+    expect(listedIce.map((s: any) => s.status)).toEqual(["promoted"]);   // promoted stays; dismissed comes apart
   } finally { proc.kill(); await proc.exited; }
 }, 30_000);   // a cold board start is slow on Windows
 
@@ -733,7 +734,7 @@ test("sheet and doc images land on their row and line", async () => {
 <tr><th id="0R2"><div>3</div></th><td>Dark mode</td></tr></table>`;
   expect(sheetImages(sheetHtml)).toEqual(new Map([[2, ["https://lh3.googleusercontent.com/x?a=1&b=2"]]]));
   expect(sift("sheet", "Request\nFix login\nDark mode\n", sheetImages(sheetHtml) as any).items).toEqual([
-    { text: "Fix login", images: ["https://lh3.googleusercontent.com/x?a=1&b=2"] }, { text: "Dark mode" }]);
+    { text: "Fix login", row: 2, images: ["https://lh3.googleusercontent.com/x?a=1&b=2"] }, { text: "Dark mode", row: 3 }]);
   const docHtml = `<html><body><p><span>Export is slow</span></p><p><img src="https://lh7.example/p.png"></p><li>Add &amp; remove tags</li></body></html>`;
   expect(sift("doc", "Export is slow\n\n* Add & remove tags\n", docImages(docHtml) as any).items).toEqual([
     { text: "Export is slow", images: ["https://lh7.example/p.png"] }, { text: "* Add & remove tags" }]);
@@ -789,3 +790,31 @@ test("a fresh image link on a host the item never used is not taken", async () =
     : new Response("Request\nFix login\n", { headers: { "content-type": "text/plain" } });
   expect(await freshImages(state, id, page, pub)).toEqual(["https://docs.google.com/sheets-images-rt/OLD=s2048"]);
 });
+
+test("a promoted item stays promoted until its run is done, then reads done", () => {
+  writeIcebox(state, [{ id: "a1", text: "Dark mode", source: "s", at: "2026-10-17", status: "new" }]);
+  expect(promote(state, ["a1"])).toBeNull();
+  const run = join(state, "runs", "r1");
+  mkdirSync(run, { recursive: true });
+  writeFileSync(join(run, "00-request.md"), "Dark mode");
+  writeFileSync(join(run, "state.json"), JSON.stringify({ stage: "build" }));
+  markDone(state);
+  expect(readIcebox(state)[0]!.status).toBe("promoted");
+  writeFileSync(join(run, "state.json"), JSON.stringify({ stage: "done" }));
+  markDone(state);
+  expect(readIcebox(state)[0]!.status).toBe("done");
+});
+
+test("a done run that only mentions the idea does not finish it", () => {
+  writeIcebox(state, [{ id: "a1", text: "Test", source: "s", at: "2026-10-17", status: "new" }]);
+  expect(promote(state, ["a1"])).toBeNull();
+  const run = join(state, "runs", "r1");
+  mkdirSync(run, { recursive: true });
+  writeFileSync(join(run, "00-request.md"), "lite fix the test runner on Windows");
+  writeFileSync(join(run, "state.json"), JSON.stringify({ stage: "done" }));
+  markDone(state);
+  expect(readIcebox(state)[0]!.status).toBe("promoted");
+  writeFileSync(join(run, "00-request.md"), "lite Test");
+  markDone(state);
+  expect(readIcebox(state)[0]).toMatchObject({ status: "done", run: "r1" });
+});

package/cli/sources.ts

@@ -7,10 +7,10 @@ import { join } from "node:path";
 import { isIP } from "node:net";
 import { createHash } from "node:crypto";
 import { lookup as dnsLookup } from "node:dns/promises";
-import { readInbox, writeInbox, normalise, formatNote, parseItem } from "./state.ts";
+import { readInbox, writeInbox, normalise, formatNote, parseItem, readRuns, readText } from "./state.ts";
 
 export type Last = { at: string; ok: boolean; added: number; note: string };
-export type Source = { url: string; label?: string; category?: string; added: string; last?: Last; seen: string[] };
+export type Source = { url: string; label?: string; category?: string; added: string; last?: Last; seen: string[]; writeback?: boolean };
 export type Result = { url: string } & Last;
 
 const file = (state: string) => join(state, "sources.json");
@@ -84,6 +84,16 @@ export function setCategory(state: string, url: string, category: string): strin
   return null;
 }
 
+// Whether a done item is reported back to this source (see writeback.ts). Off by default.
+export function setWriteback(state: string, url: string, on: boolean): string | null {
+  const list = readSources(state);
+  const src = list.find((s) => s.url === url);
+  if (!src) return "no such source";
+  if (on) src.writeback = true; else delete src.writeback;
+  writeSources(state, list);
+  return null;
+}
+
 // Drops the entry and its seen list. Items already gathered stay in the icebox.
 export function removeSource(state: string, url: string): string | null {
   const list = readSources(state);
@@ -134,7 +144,7 @@ function clean(raw: string, extra = ""): { text: string; lines: string[] } | nul
 // The icebox: everything gathered, held per project until a person or an agent
 // promotes it to an idea or dismisses it. Promoted and dismissed items stay, so the
 // same request never comes back.
-export type Signal = { id: string; text: string; notes?: string; source: string; category?: string; at: string; status: "new" | "promoted" | "dismissed"; idea?: string; replied?: string; images?: string[] };
+export type Signal = { id: string; text: string; notes?: string; source: string; category?: string; at: string; status: "new" | "promoted" | "dismissed" | "done"; idea?: string; replied?: string; images?: string[]; row?: number; run?: string; written?: string; writeError?: string };
 
 const iceFile = (state: string) => join(state, "icebox.json");
 
@@ -188,7 +198,7 @@ function shape(it: Item) {
   const c = clean(it.text, got.notes);
   if (!c) return null;
   const notes = c.lines.join("\n").slice(0, 2000);
-  return { c, notes, images: pics([...(it.images ?? []), ...got.images]), key: rowKey(c.text, notes) };
+  return { c, notes, row: it.row, images: pics([...(it.images ?? []), ...got.images]), key: rowKey(c.text, notes) };
 }
 
 export function ingest(state: string, url: string, items: Item[]): { added: number; held: number } {
@@ -203,9 +213,12 @@ export function ingest(state: string, url: string, items: Item[]): { added: numb
   for (const it of items) {
     const s = shape(it);
     if (!s) continue;
-    const { c, notes, images, key } = s;
+    const { c, notes, images, key, row } = s;
     if (known.has(key)) {
       seen.push(key);
+      // The row can move; the newest read is the one a write-back trusts.
+      const at = row && ice.find((s) => s.source === url && rowKey(s.text, s.notes) === key);
+      if (at && at.row !== row) { at.row = row; refreshed = true; }
       // Image links expire (social CDNs) or arrive late (items gathered before images
       // were read): an item still waiting takes the ones read now.
       const old = images.length && ice.find((s) => s.status === "new" && s.source === url && rowKey(s.text, s.notes) === key);
@@ -215,7 +228,7 @@ export function ingest(state: string, url: string, items: Item[]): { added: numb
     if (fresh.length >= CAP) { held++; continue; }   // not marked seen: the next gather takes it
     known.add(key);
     seen.push(key);
-    fresh.push({ id: idOf(key), text: c.text, ...(notes ? { notes } : {}), source: url, ...(src.category ? { category: src.category } : {}), at: new Date().toISOString(), status: "new", ...(images.length ? { images } : {}) });
+    fresh.push({ id: idOf(key), text: c.text, ...(notes ? { notes } : {}), source: url, ...(src.category ? { category: src.category } : {}), at: new Date().toISOString(), status: "new", ...(images.length ? { images } : {}), ...(row ? { row } : {}) });
   }
   if (fresh.length || refreshed) writeIcebox(state, [...ice, ...fresh]);
   // ponytail: seen only grows; trim to the newest few thousand if a source ever gets that long.
@@ -254,6 +267,21 @@ export function promote(state: string, ids: string[], text?: string, details?: s
   return null;
 }
 
+// A promoted item stays in the icebox until the run its idea became is done; then it
+// is marked done. Matched the way the board retires an idea: some line of the run's
+// request is the idea (after any `/kaizen lite` prefix), never merely contains it.
+export function markDone(state: string): void {
+  const ice = readIcebox(state);
+  const waiting = ice.filter((s) => s.status === "promoted" && s.idea);
+  if (!waiting.length) return;
+  const done = readRuns(state).filter((r) => r.stage === "done").flatMap((r) => {
+    try { return [{ id: r.id, lines: readText(join(state, "runs", r.id, "00-request.md")).split("\n").map((l) => normalise(l.replace(/^[\s>*"'`-]+|[\s"'`.]+$/g, ""))) }]; } catch { return []; }
+  });
+  let changed = false;
+  for (const s of waiting) { const t = normalise(s.idea!), r = done.find((d) => d.lines.some((l) => l === t || l.endsWith(" " + t))); if (r) { s.status = "done"; s.run = r.id; changed = true; } }
+  if (changed) writeIcebox(state, ice);
+}
+
 // A dismissed item back to waiting.
 export function restore(state: string, ids: string[]): string | null {
   const ice = readIcebox(state);
@@ -451,9 +479,9 @@ const wordy = (c: string) => c.length >= 3 && !datum(c);
 const STATUS = /^status$/i;
 const DONE = /^(done|finish|finished)$/i;
 
-type Item = { text: string; notes?: string; images?: string[] };
+type Item = { text: string; notes?: string; images?: string[]; row?: number };
 
-export const split = (kind: Kind, body: string): Item[] => sift(kind, body).items;
+export const split = (kind: Kind, body: string): Item[] => sift(kind, body).items.map(({ row, ...it }) => it);   // the row number is write-back's, not what a read says
 
 // The requests, and how many rows were left out for their status. A row left out is
 // never handed to ingest, so it is not marked seen: reopened, it is gathered then.
@@ -499,7 +527,7 @@ export function sift(kind: Kind, body: string, pics?: Map<number | string, strin
     if (status >= 0 && DONE.test(row[status] ?? "")) { done++; return []; }
     const rest = row.filter((c, i) => c && i !== col).join(" · ");
     // The export keeps every row from the top, so a row's index is its number less one.
-    return [with_({ text, ...(rest ? { notes: rest } : {}) }, cells.indexOf(row) + 1)];
+    return [with_({ text, ...(rest ? { notes: rest } : {}), row: cells.indexOf(row) + 1 }, cells.indexOf(row) + 1)];
   });
   return { items, done };
 }

package/cli/state.test.ts

@@ -8,7 +8,7 @@ import { issueUrl, systemInfo, scrubHome, REPO_URL, home as realHome, trustFolde
 import * as stateModule from "./state.ts";
 import {
   readRuns, readInbox, writeInbox, replaceIdea, moveIdea, abandonRun, allBacklog, backlog,
-  statusOf, columnOf, parseItem, startedRuns, boardCards, readArchive, setArchived,
+  requestTitle, statusOf, columnOf, parseItem, startedRuns, boardCards, readArchive, setArchived,
   requestOf, agentFlags, plainModel, readNotes, writeNotes, manualCommand, parseNotes, formatNote, appendNote, saveAttachment,
   reviewFindings, pickFindings, fixPrompt, approvalPrompt, sessionLaunch, closeSessions, sweepSessions, readSessions, ownerOf, CLOSE_GRACE_MS, gitStatus, runGit, cardsGit, commitPush, readCommit, findTerminal, nativePath, pruneRuns, unrechecked, notice, notifier, notifyArgs, LOGO, type Card,
 } from "./state.ts";
@@ -138,6 +138,11 @@ test("approvalPrompt: approve or revise, the comment kept on one line", () => {
   expect(p).toContain('to revise: "drop step 3, keep "the rest"".');
   expect(p).toContain("revise 01-plan.md");
   expect(p).not.toContain("\n");
+  expect(approvalPrompt("r", "approvals.review")).toContain("commit and push this run's changed files only");
+  expect(approvalPrompt("r", "findings")).toContain("commit and push");
+  expect(approvalPrompt("r", "approvals.review")).toContain("kaizen worktree land");
+  expect(approvalPrompt("r", "approvals.review", "rename it")).not.toContain("push");
+  expect(approvalPrompt("r", "approvals.plan")).not.toContain("push");
   expect(approvalPrompt("r", "approvals.review", "rename it")).toContain('final approval: "rename it". Record it in 02-approval.md, change the work');
 });
 
@@ -1029,3 +1034,8 @@ test("the board answers only the hosts listed in KAIZEN_WEB_HOSTS", async () =>
     expect((await m.json()).display).toBe("standalone");
   } finally { proc.kill(); await proc.exited; rmSync(homeDir, { recursive: true, force: true }); }
 });
+
+test("requestTitle: drops the launch command, keeps the first sentence, caps at 90", () => {
+  expect(requestTitle("/kaizen lite simplify the card. Then more words")).toBe("simplify the card.");
+  expect(requestTitle("x".repeat(200)).length).toBe(90);
+});

package/cli/state.ts

@@ -6,12 +6,13 @@ import { Database } from "bun:sqlite";
 import { join, dirname, win32, posix } from "node:path";
 import { homedir, arch, cpus, release, totalmem, version as osVersion } from "node:os";
 import { startPty, ptySupported } from "./pty.ts";
+import { codeDir, projectFromWorktree } from "./worktree.ts";
 
 // The real path: process.cwd() is always physical, so a raw $HOME that crosses a
 // symlink (/home -> var/home) would never compare equal to it.
 export const home = (() => { try { return realpathSync(homedir()); } catch { return homedir(); } })();
 
-export type Run = { id: string; stage: string; awaiting: string | null; moved: number; runner?: string; agent?: string };
+export type Run = { id: string; stage: string; awaiting: string | null; moved: number; runner?: string; agent?: string; branch?: string };
 
 export const KNOWN_AGENTS = [
   { name: "Claude Code", dir: ".claude", cmd: "claude" },
@@ -356,7 +357,8 @@ export function findProjects(root: string, depth = 4): string[] {
 // The same spelling knownProjects() gives: a terminal handing out c:\... (lower-case
 // drive) would otherwise make every POST from the board fail "unknown state dir".
 export function locate() {
-  let dir = nativePath(process.cwd());
+  // A run's worktree holds a partial .kaizen of its own (the committed notes); the runs are the project's.
+  let dir = projectFromWorktree(nativePath(process.cwd()));
   for (;;) {
     if (existsSync(join(dir, ".kaizen"))) return join(dir, ".kaizen");
     if (existsSync(join(dir, ".git"))) return null;
@@ -379,7 +381,7 @@ export function readRuns(state: string): Run[] {
       // own mtime is the only evidence that anything is still working on it.
       let moved = 0;
       try { moved = statSync(file).mtimeMs; } catch { /* vanished mid-read */ }
-      return [{ id, stage: s.stage ?? "?", awaiting: s.awaiting ?? null, moved, runner: s.runner, agent: s.agent }];
+      return [{ id, stage: s.stage ?? "?", awaiting: s.awaiting ?? null, moved, runner: s.runner, agent: s.agent, branch: typeof s.branch === "string" ? s.branch : undefined }];
     } catch { return []; }
   }).reverse();
 }
@@ -511,16 +513,22 @@ export function canApproveAwaiting(awaiting: unknown): awaiting is "approvals.pl
 // The board's answer to an approval the run is waiting on. The comment is collapsed to
 // one line: where the prompt is typed into a shell (herdr), a newline sends it early.
 // Answers are the plan's open questions answered at the approval, one per question.
+// Approving a run to done also asks for its commit and push. A run with its own worktree
+// is landed by `kaizen worktree land`, which pushes the branch and merges it; any other
+// run pushes where it is, and a failed push is reported, not retried.
+const COMMIT_PUSH = " Then commit and push this run's changed files only, with the ## Commit message from 03-impl.md (if already committed and nothing changed, only push); if the push fails, say so and stop."
+  + " If state.json names a `worktree`, commit there instead and then run `kaizen worktree land` with this run's id from the project folder in place of the push; report its result as it prints it.";
+
 export function approvalPrompt(id: string, awaiting: string, why?: string, answers?: string[]) {
   const plan = awaiting === "approvals.plan";
   const one = (t: string) => t.replace(/\s+/g, " ").trim();
   const note = why === undefined ? undefined : one(why);
-  if (awaiting === "findings" && !note) return `run ${id}: the user approved the run as-is at the findings gate. Record approval in 02-approval.md, leave every remaining finding open in 06-backlog.md, do not fix or mark findings closed, and finish the run.`;
+  if (awaiting === "findings" && !note) return `run ${id}: the user approved the run as-is at the findings gate. Record approval in 02-approval.md, leave every remaining finding open in 06-backlog.md, do not fix or mark findings closed, and finish the run.${COMMIT_PUSH}`;
   if (plan && !note && answers?.length) return `run ${id}: the plan is approved from the board, with answers to its open questions: `
     + answers.map((a, i) => `${i + 1}) ${one(a).replace(/[.;]$/, "")}`).join("; ") + `. Record them in 02-approval.md and build the plan with them.`;
   if (!note) return plan
     ? `run ${id}: the plan is approved from the board. Record it in 02-approval.md and build it, first asking any of its open questions still unanswered.`
-    : `run ${id}: the work is approved from the board at the final approval. Record it, write the backlog and finish the run.`;
+    : `run ${id}: the work is approved from the board at the final approval. Record it, write the backlog and finish the run.${COMMIT_PUSH}`;
   return plan
     ? `run ${id}: the plan is sent back from the board to revise: "${note}". Record it in 02-approval.md, revise 01-plan.md with it, and stop at the plan approval again.`
     : `run ${id}: the work is sent back from the board at the final approval: "${note}". Record it in 02-approval.md, change the work to address it, recheck, and stop at the final approval again.`;
@@ -588,6 +596,7 @@ export type Card = {
   moved?: number;                                  // runs only: state.json mtime
   title?: string;                                  // runs only: first line of the request
   archived: boolean;                               // hidden from the board unless asked for
+  branch?: string;                                 // runs only: the run's own branch while it has a worktree
   tags?: string[];                                 // runs only: runner, agent, "yolo", "unrechecked"
   notes?: string;                                  // inbox notes, or runs/<id>/notes.md
 };
@@ -894,7 +903,9 @@ export function requestTitle(text: string) {
     .filter((l) => l && !l.startsWith("#"))
     .slice(0, 6)
     .find((l) => l && !l.endsWith(":") && !/^---/.test(l)) ?? "";
-  return line.length > 140 ? line.slice(0, 139) + "…" : line;
+  // Drop the command that launched it, keep the first sentence: a card reads, it does not quote.
+  const first = line.replace(/^\/kaizen(?:-\w+)?\s+(?:(?:lite|full|auto|plan)\s+)?/i, "").split(/(?<=[.!?])\s/)[0];
+  return first.length > 90 ? first.slice(0, 89).trimEnd() + "…" : first;
 }
 
 // Every card on the board, for the state dirs asked for. Retirement of an idea is
@@ -952,6 +963,7 @@ export function boardCards(states: string[], now: number): Card[] {
         awaiting: r.stage === "abandoned" ? null : r.awaiting,
         dim: r.stage === "abandoned",
         archived: archive.has(r.id),
+        branch: r.branch,
         tags: [r.runner, r.agent, yolos.has(r.id) ? "yolo" : undefined, unrechecked(st, r.id) ? "unrechecked" : undefined].filter((t): t is string => !!t),
         notes: readNotes(st, r.id) || undefined,
       });
@@ -1467,7 +1479,7 @@ const runFiles = (changed: string[], mine: Report, rest: Report[]) => changed.fi
 // ponytail: runs in the same file are named, not separated; that takes a worktree
 // per run or a saved patch per run.
 export function runGit(state: string, id: string): GitStatus {
-  const dir = dirname(state), s = gitStatus(dir);
+  const dir = codeDir(dirname(state), id), s = gitStatus(dir);
   if (!s.repo) return s;
   const all = runReports(state), mine = all.find((r) => r.id === id) ?? { id, text: "", at: 0 };
   const rest = all.filter((o) => o.id !== id);
@@ -1517,7 +1529,7 @@ const COMMIT_TYPE = new RegExp(`^(${COMMIT_TYPES.join("|")})(\\([^)\\n]+\\))?!?:
 // as committed and not pushed. `shown` is the file list the user confirmed: anything
 // that changed since is refused, not swept in unseen.
 export async function commitPush(state: string, id: string, message: string, shown: string[]): Promise<{ ok: true; sha: string } | { ok: false; why: string }> {
-  const dir = dirname(state);
+  const dir = codeDir(dirname(state), id);
   const s = runGit(state, id);
   if (!s.repo) return { ok: false, why: "This project has no git remote." };
   if (s.files.join("\n") !== shown.join("\n")) return { ok: false, why: "The changed files are no longer the ones shown. Look at the list again." };

package/cli/web.ts

@@ -10,8 +10,10 @@ import {
   launchMode, readSessions, ownerOf, resumePrompt, runAgent, firstSession,
 } from "./state.ts";
 import { attachPty, writePty, resizePty, ptyState, ptyKeys, adoptLoginEnv } from "./pty.ts";
-import { readSources, addSource, removeSource, moveSource, setCategory, readIcebox, promote, dismiss, restore, markReplied, gatherSource, freshImages, gatherAll, gatherDirs, due, socialUrl, socialOf } from "./sources.ts";
+import { readSources, addSource, removeSource, moveSource, setCategory, setWriteback, readIcebox, promote, dismiss, restore, markDone, markReplied, gatherSource, freshImages, gatherAll, gatherDirs, due, socialUrl, socialOf } from "./sources.ts";
 import * as chatgpt from "./chatgpt.ts";
+import * as google from "./google.ts";
+import { writeBacks } from "./writeback.ts";
 import { postLink, sendReply } from "./browser.ts";
 import { listNotes, saveNote, renameNote, deleteNote, boardIndex, linksTo } from "./notes.ts";
 
@@ -234,6 +236,12 @@ export async function web(repoDir: string, opts: Opts = {}) {
     busy = false;
   }, 60_000);
 
+  // Done requests are reported back to their sources here, on the board's own clock: a
+  // page load only reads, so opening the Icebox never closes an issue.
+  const loop = setInterval(async () => {
+    for (const dir of states(true)) { try { markDone(dir); await writeBacks(dir); } catch { /* the next tick tries again */ } }
+  }, 60_000);
+
   const BOOT = Date.now().toString(36);
   const ping = setInterval(() => { for (const c of clients) { try { c.enqueue(": ping\n\n"); } catch { clients.delete(c); } } }, 8000);
   // A launcher clicked while a board is already up should show that board, not die.
@@ -439,16 +447,17 @@ export async function web(repoDir: string, opts: Opts = {}) {
           // The seen list is bookkeeping, not something the page shows.
           try { sources.push(...readSources(d).map(({ seen, ...s }) => ({ ...s, social: socialOf(s.url), dir: d, project: label(d) }))); }
           catch { failed.push(label(d)); }
-          // Only what still waits for a decision; promoted and dismissed items are record.
-          // Dismissed ones come apart, for the Dismissed category, where they can be restored.
+          // Waiting and promoted items stay in the list; dismissed and done ones come apart,
+          // for their own categories.
           try {
+            markDone(d);
             const all = readIcebox(d).map((s) => ({ ...s, post: postLink(s.notes), dir: d, project: label(d) }));
-            icebox.push(...all.filter((s) => s.status === "new"));
-            dismissed.push(...all.filter((s) => s.status === "dismissed"));
+            icebox.push(...all.filter((s) => s.status === "new" || s.status === "promoted"));
+            dismissed.push(...all.filter((s) => s.status === "dismissed" || s.status === "done"));
           }
           catch { failed.push(label(d) + " (icebox)"); }
         }
-        return json({ sources, icebox, dismissed, failed, every: await every(), gatherer: { use: await setting("sources.agent"), ...chatgpt.status() } });
+        return json({ sources, icebox, dismissed, failed, every: await every(), gatherer: { use: await setting("sources.agent"), ...chatgpt.status() }, google: google.status() });
       }
 
       // The Run form's choices for one project: installed tools and their models.
@@ -490,6 +499,14 @@ export async function web(repoDir: string, opts: Opts = {}) {
         return new Response(`<!doctype html><meta charset="utf-8"><title>kaizen</title><body style="font:15px system-ui;padding:40px;max-width:560px;margin:auto">${msg.replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`)}</body>`, { headers: { "content-type": "text/html; charset=utf-8" } });
       }
 
+      // Sign in with Google comes back here, for writing a done request into its sheet.
+      if (req.method === "GET" && path === "/google-callback") {
+        const why = await google.callback(url.searchParams);
+        if (!why) changed();
+        const msg = why ? `Could not connect Google: ${why}` : "Google connected. Done requests are written back to sheets that have Write back on. You can close this tab.";
+        return new Response(`<!doctype html><meta charset="utf-8"><title>kaizen</title><body style="font:15px system-ui;padding:40px;max-width:560px;margin:auto">${msg.replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`)}</body>`, { headers: { "content-type": "text/html; charset=utf-8" } });
+      }
+
       // What this board runs and what npm has: the page shows an Update button on a newer one.
       if (req.method === "GET" && path === "/version") {
         const v = await npmLatest(url.searchParams.has("fresh"));
@@ -520,6 +537,22 @@ export async function web(repoDir: string, opts: Opts = {}) {
         } finally { upgrading = false; }
       }
 
+      if (req.method === "GET" && path === "/google") return json(google.status());
+
+      // The Google client the user created, and connecting or disconnecting Google.
+      if (req.method === "POST" && path === "/google") {
+        if (!local(req)) return bad("cross-origin write refused", 403);
+        let body: any;
+        try { body = await req.json(); } catch { return bad("json body expected"); }
+        if (body.op === "client") {
+          if (typeof body.id !== "string" || typeof body.secret !== "string" || !body.id.trim() || !body.secret.trim()) return bad("client id and secret expected");
+          google.setClient(body.id, body.secret); changed(); return json({ ok: true });
+        }
+        if (body.op === "connect") { try { return json({ ok: true, url: await google.authorizeUrl(Number(url.port)) }); } catch (e) { return bad((e as Error).message); } }
+        if (body.op === "disconnect") { google.signOut(); changed(); return json({ ok: true }); }
+        return bad("unknown op");
+      }
+
       // Connect or disconnect the ChatGPT plan. The page opens the URL it is handed.
       if (req.method === "POST" && path === "/chatgpt") {
         if (!local(req)) return bad("cross-origin write refused", 403);
@@ -682,6 +715,9 @@ export async function web(repoDir: string, opts: Opts = {}) {
             } else if (body.op === "category") {
               const why = setCategory(dir, link, String(body.category ?? ""));
               if (why) return bad(why, 404);
+            } else if (body.op === "writeback") {
+              const why = setWriteback(dir, link, body.on === true);
+              if (why) return bad(why, 404);
             } else if (body.op === "remove") {
               const why = removeSource(dir, link);
               if (why) return bad(why, 404);
@@ -955,7 +991,7 @@ export async function web(repoDir: string, opts: Opts = {}) {
   if (opts.open !== false) await openApp(url);
 
   await new Promise<void>((resolve) => {
-    const stop = () => { clearInterval(poll); clearInterval(ping); clearInterval(gather); for (const w of watchers) { try { w.close(); } catch { /* gone */ } } server.stop(true); resolve(); };
+    const stop = () => { clearInterval(poll); clearInterval(ping); clearInterval(gather); clearInterval(loop); for (const w of watchers) { try { w.close(); } catch { /* gone */ } } server.stop(true); resolve(); };
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
   });