kaizen-agent 1.5.3 → 1.5.5

package/README.md

@@ -288,14 +288,18 @@ serves the same board on `http://127.0.0.1:7420/` — loopback only, no account
 opens it in a Chromium-family browser as an app window when one is installed, otherwise
 in a tab.
 
-<img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/web-board.png" alt="kaizen web board" width="760">
+<img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/board-web.png" alt="kaizen web board" width="760">
 
 Same columns, same files: an idea added here lands in `inbox.md`, a run
 started here opens your agent in a new terminal exactly as `r` does, and the board
 redraws as your agents write to disk. Mouse first; the TUI's keys still work. Click a card for its plan, review and
-backlog; `⋯` on a card runs, edits, rejects or abandons. Theme lives in its settings;
-everything else is still `kaizen settings`. `--port N` picks a port, `--no-open` just
-serves, `?all=1` in the URL opens on every project.
+backlog; `⋯` on a card runs, edits, rejects, abandons or archives. `Clear` on Done sends
+every finished run to the archive (`.kaizen/archive.md`, a list, nothing moves), and
+`Archive` in the strip shows what is there, with `Restore` on each card. The gear at the top right holds the browser's theme
+and every `kaizen settings` knob, same rows, same `config.yml`. `--port N` picks a port, `--no-open` just
+serves, `?all=1` in the URL opens on every project. `--daemon` starts the server
+detached so it outlives the terminal (pid kept in `~/.kaizen/web.pid`); `--stop` ends it. `kaizen web --shortcut` adds a launcher
+the OS can find — Spotlight on macOS, the app menu on Linux, a Desktop shortcut on Windows.
 
 ### Mouse
 

package/agents/kaizen-builder.md

@@ -67,6 +67,8 @@ change — do not refactor around it. Write what you changed to
 - **Baseline / after** — the checks run before and after, with both results verbatim.
 - **Verification** — each check carried out, with its actual result. Quote failures.
 - **Not done** — steps skipped, out-of-scope observations, known gaps.
+- **Preview** — how to see the result: commands to run it locally and the URL for an
+  app; the path to open, or the result itself, for anything else. The board shows it.
 
 ## Report back
 

package/agents/kaizen-planner.md

@@ -14,8 +14,9 @@ execute without you present, so anything you leave implicit will be guessed at.
 You will be given a run directory path. Your plan carries a **File manifest**: every
 path this run will read or change, flat. The builder and the reviewer read that list
 instead of searching the material a second and third time, so a path you leave out is
-work done twice. Read `00-request.md` from it, and
-`.kaizen/memory.md` if it exists, before touching the codebase.
+work done twice. Read `00-request.md` from it, `notes.md`
+beside it if it exists (context the user attached from the board; treat it as part of
+the request), and `.kaizen/memory.md` if it exists, before touching the codebase.
 
 **You do not write code.** No source edits, no installs, no migrations, no
 `git` state changes. The only file you write is `01-plan.md` in the run directory.
@@ -139,6 +140,12 @@ absorb.
 Assumptions that do not change the shape of the plan go in *Open questions* and are
 resolved at the approval, alongside everything else. Do not stop the run for them.
 
+**Except when building from nothing.** A new app or product has no material to
+answer platform, users and scale, stack, distribution, access, data, and hosting — and
+a wrong answer there is a rebuild, not a finding. Decide each one in the plan: from
+the request, by proposal with a reason, or as an *Open question* with options where
+the builds differ. Ask them together, once, before any step is written.
+
 ## Method
 
 1. Read the request verbatim. Note what is asked and what is merely implied.

package/cli/dashboard.ts

@@ -8,7 +8,7 @@ import {
   searchRoots, knownProjects, remember, findProjects, locate,
   readRuns, backlog, version, label, tilde, section, readFindings, parseItem, tidy, readBacklog, allBacklog,
   startedRuns, normalise, statusOf, columnOf, readInbox, writeInbox, notify, short,
-  abandonRun, replaceIdea, boardCards, launchRun,
+  abandonRun, replaceIdea, boardCards, launchRun, appendNote, parseNotes,
 } from "./state.ts";
 const rgb = (r: number, g: number, b: number, s: string) =>
   `\x1b[38;2;${r};${g};${b}m${s}\x1b[0m`;
@@ -502,6 +502,7 @@ export async function dashboard(
       const now = Date.now();
       const next: Drawn[] = [];
       for (const k of boardCards(states(), now)) {
+        if (k.archived) continue;                    // cleared from the board; kaizen web shows the archive
         if (k.kind === "run") {
           const key = `${k.state}/${k.id}`;
           const before = wasAwaiting.get(key);
@@ -539,6 +540,8 @@ export async function dashboard(
             lines.push(`${marker} ${dot} ${painted}`);
           }
           if (allProjects && k.where !== "global") lines.push("    " + c.dim(cut(basename(k.where), inner - 4)));
+          // First note line only; the rest is for the web board's detail panel.
+          if (k.notes) { const n = parseNotes(k.notes); const l = n[n.length - 1]?.text.split("\n")[0]; if (l) lines.push("    " + c.dim(cut(l, inner - 4))); }
           lines.push("");
         }
         return { meta, lines, starts };
@@ -586,8 +589,8 @@ export async function dashboard(
     // space rather than by middots, which made one long undifferentiated line.
     const footer = (k?: Card) => {
       const acts = k?.kind === "idea"
-        ? "n new  e edit  x reject  d delete  r run"
-        : k ? "n new idea  x abandon this run" : "n new idea";
+        ? "n new  e edit  t note  x reject  d delete  r run"
+        : k ? "n new idea  t note  x abandon this run" : "n new idea";
       const scope = allProjects ? "a this project" : "a all projects";
       return `  ${c.dim("↑↓←→ move")}     ${c.dim(acts)}     ${c.dim(scope)}  ${c.dim("q back")}\n`;
     };
@@ -703,6 +706,11 @@ export async function dashboard(
         // abandoning one is the user's decision to make, and /kaizen abort is the
         // same single transition this writes.
         if (target.kind === "run") {
+          if (key === "t" && target.id && target.column < 4) {
+            const line = await promptLine("Add a note", "");
+            if (line) appendNote(target.state, { id: target.id }, line);
+            refresh();
+          }
           if (key === "x" && target.id) {
             const why = await promptLine(`Abandon ${target.text}? Reason`, "");
             if (why) {
@@ -716,6 +724,9 @@ export async function dashboard(
         if (key === "e") {
           const text = await promptLine("Edit idea", target.text);
           if (text) replaceIdea(target.state, target.text, { status: "open", text });
+        } else if (key === "t" && target.status === "idea") {
+          const line = await promptLine("Add a note", "");
+          if (line) appendNote(target.state, { text: target.text }, line);
         } else if (key === "x") {
           const why = await promptLine(`Reject: ${target.text}`, "");
           // The spec requires a reason on a rejected item; no reason, no rejection.
@@ -728,7 +739,7 @@ export async function dashboard(
           // the prompt the agent is launched with.
           if (mode !== null) {
             const request = `${mode} ${target.text}`.trim();
-            await outside(() => startBacklogItem(parseItem(request), target.state));
+            await outside(() => startBacklogItem({ ...parseItem(request), notes: target.notes }, target.state));
             // Without this the idea stays open forever and the board shows the
             // same work twice: once as an idea, once as the run it became.
             replaceIdea(target.state, target.text, { status: "started", text: target.text });

package/cli/install.ts

@@ -210,9 +210,45 @@ if (wantSettings) {
 }
 
 if (wantWeb) {
-  const { web } = await import("./web.ts");
+  if (args.has("--shortcut")) { const { shortcut } = await import("./web.ts"); console.log(`\n  kaizen web shortcut  ${await shortcut()}\n`); process.exit(0); }
   const at = Bun.argv.indexOf("--port");
   const port = at !== -1 ? Number(Bun.argv[at + 1]) || undefined : undefined;
+  const url = `http://127.0.0.1:${port ?? 7420}/`;
+  const pidFile = join(home, ".kaizen", "web.pid");
+  const alive = async () => { try { await fetch(url); return true; } catch { return false; } };
+
+  if (args.has("--stop")) {
+    const pid = existsSync(pidFile) ? Number(readFileSync(pidFile, "utf8")) : NaN;
+    if (!pid) { console.log("  no kaizen web daemon recorded"); process.exit(0); }
+    try { process.kill(pid, "SIGTERM"); console.log(`  stopped kaizen web (pid ${pid})`); }
+    catch { console.log(`  pid ${pid} already gone; cleared the stale record`); }
+    rmSync(pidFile, { force: true });
+    process.exit(0);
+  }
+
+  if (args.has("--daemon")) {
+    // The daemon is this same command, detached, with the browser left to us:
+    // ignored stdio is what lets it outlive the terminal.
+    if (await alive()) {
+      console.log(`  kaizen web already running at ${url}`);
+    } else {
+      const argv = Bun.argv.slice(2).filter((a) => a !== "--daemon" && a !== "--no-open");
+      const child = Bun.spawn([process.execPath, Bun.main, ...argv, "--no-open"], {
+        detached: true, stdio: ["ignore", "ignore", "ignore"],
+      });
+      child.unref();
+      mkdirSync(dirname(pidFile), { recursive: true });
+      writeFileSync(pidFile, String(child.pid));
+      for (let i = 0; i < 30 && !(await alive()); i++) await Bun.sleep(100);
+      if (!(await alive())) { console.log(`  kaizen web did not come up on ${url}`); process.exit(1); }
+      console.log(`\n  kaizen web  ${url}  (pid ${child.pid}, detached)`);
+      console.log(`  kaizen web --stop to stop it\n`);
+    }
+    if (!args.has("--no-open")) await openUrl(url);
+    process.exit(0);
+  }
+
+  const { web } = await import("./web.ts");
   await web(await resolveRepoQuietly(), { port, open: !args.has("--no-open") });
   process.exit(0);
 }

package/cli/settings.ts

@@ -113,6 +113,43 @@ const SETTINGS: Setting[] = [
   { key: "agent.default", values: ["auto", "claude", "codex", "agy", "opencode", "gemini"], help: "Default coding agent to launch from dashboard backlog" },
 ];
 
+// The same rows and the same write the TUI uses, for `kaizen web`'s settings panel:
+// one place decides what a setting is called, what it may be, and how it is saved.
+export function listSettings(repoRoot: string) {
+  const file = locate();
+  const defaults = readFileSync(join(repoRoot, "skills/kaizen/config.default.yml"), "utf8");
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const preset = detectPreset(text, defaults);
+  return {
+    file: tilde(file),
+    rows: SETTINGS.map((s) => ({
+      ...s,
+      value: s.key === "preset" ? preset : read(text, s.key) ?? read(defaults, s.key) ?? s.values[0]!,
+    })),
+  };
+}
+
+export function setSetting(repoRoot: string, key: string, value: string) {
+  const s = SETTINGS.find((x) => x.key === key);
+  if (!s || !s.values.includes(value)) return { error: "unknown setting or value" };
+  const file = locate();
+  const defaultsPath = join(repoRoot, "skills/kaizen/config.default.yml");
+  if (!existsSync(file)) { mkdirSync(dirname(file), { recursive: true }); copyFileSync(defaultsPath, file); }
+  const defaults = readFileSync(defaultsPath, "utf8");
+  const text = readFileSync(file, "utf8");
+  let updated: string;
+  if (key === "preset") {
+    if (value === "custom") return { error: "custom is what any other change makes" };
+    updated = applyPreset(text, value as PresetName, defaults);
+  } else {
+    updated = write(text, key, value, defaults);
+    updated = write(updated, "preset", detectPreset(updated, defaults), defaults);
+    if (read(updated, key) !== value) return { error: `${key} did not save; edit ${tilde(file)} by hand` };
+  }
+  writeFileSync(file, updated);
+  return { ok: true };
+}
+
 const c = {
   dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
   bold: (s: string) => `\x1b[1m${s}\x1b[0m`,

package/cli/state.test.ts

@@ -6,7 +6,8 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import {
   readRuns, readInbox, writeInbox, replaceIdea, abandonRun, allBacklog, backlog,
-  statusOf, columnOf, parseItem, startedRuns, boardCards,
+  statusOf, columnOf, parseItem, startedRuns, boardCards, readArchive, setArchived,
+  requestOf, readNotes, writeNotes, manualCommand, parseNotes, formatNote, appendNote, saveAttachment,
 } from "./state.ts";
 
 let state: string;
@@ -104,3 +105,80 @@ test("parseItem: finding line splits into where, severity, text", () => {
 test("startedRuns: normalised request bodies", () => {
   expect(startedRuns(state).sort()).toEqual(["# request add oauth login", "# request rename cli flags"]);
 });
+
+test("archive: a run is listed, hidden by flag, never moved", () => {
+  setArchived(state, "2026-09-02-done", true);
+  expect([...readArchive(state)]).toEqual(["2026-09-02-done"]);
+  const card = boardCards([state], Date.now()).find((k) => k.id === "2026-09-02-done")!;
+  expect([card.archived, card.column]).toEqual([true, 4]);
+  setArchived(state, "2026-09-02-done", false);
+  expect(readArchive(state).size).toBe(0);
+  expect(boardCards([state], Date.now()).find((k) => k.id === "2026-09-02-done")!.archived).toBe(false);
+});
+
+test("archive: an idea keeps its line with status archived", () => {
+  writeInbox(state, [{ status: "open", text: "park this", notes: "kept" }, { status: "archived", text: "parked zq7" }]);
+  const ideas = boardCards([state], Date.now()).filter((k) => k.kind === "idea");
+  expect(ideas.map((k) => [k.text, k.archived])).toEqual([["park this", false], ["parked zq7", true]]);
+});
+
+test("notes: indented lines under a bullet round-trip; a legacy file is untouched", () => {
+  const legacy = "# Inbox\n\nIdeas with no run yet. One line each, same format as a run's backlog.\n\n- open: a\n- rejected: b | why\n";
+  writeFileSync(join(state, "inbox.md"), legacy);
+  writeInbox(state, readInbox(state));
+  expect(readFileSync(join(state, "inbox.md"), "utf8")).toBe(legacy);
+  writeInbox(state, [{ status: "open", text: "with notes", notes: "see https://x.y/z\ncli/state.ts:12 | not a reason" }, { status: "open", text: "plain zq8" }]);
+  const [a, b] = readInbox(state);
+  expect(a).toEqual({ status: "open", text: "with notes", notes: "see https://x.y/z\ncli/state.ts:12 | not a reason" });
+  expect(b).toEqual({ status: "open", text: "plain zq8" });
+});
+
+test("notes: survive reject and started; edit can replace or clear them", () => {
+  replaceIdea(state, "with notes", { status: "started", text: "with notes" });
+  expect(readInbox(state)[0]!.notes).toContain("https://x.y/z");
+  replaceIdea(state, "with notes", { status: "rejected", text: "with notes | no" });
+  expect(readInbox(state)[0]!.notes).toContain("https://x.y/z");
+  replaceIdea(state, "plain zq8", { status: "open", text: "plain zq8", notes: "" });
+  expect(readInbox(state)[1]!.notes).toBeUndefined();
+  expect(boardCards([state], Date.now()).find((k) => k.text === "plain zq8")!.notes).toBeUndefined();
+});
+
+test("notes: the prompt is text, blank line, notes; still one quoted argument", () => {
+  expect(requestOf("/kaizen do x")).toBe("/kaizen do x");
+  expect(requestOf("/kaizen do x", "l1\nl2\n")).toBe("/kaizen do x\n\nl1\nl2");
+  const cmd = manualCommand("/p", "claude", requestOf("/kaizen do x", "l1"));
+  if (process.platform !== "win32") expect(cmd).toBe('cd "/p" && claude "/kaizen do x\n\nl1"');
+});
+
+test("notes: a run's notes.md is read beside it, written only for a real run", () => {
+  expect(writeNotes(state, "2026-09-09-nope", "x")).toBe("no such run");
+  expect(writeNotes(state, "2026-09-01-waiting", "  ref: docs/a.md  ")).toBeNull();
+  expect(readNotes(state, "2026-09-01-waiting")).toBe("ref: docs/a.md\n");
+  expect(boardCards([state], Date.now()).find((k) => k.id === "2026-09-01-waiting")!.notes).toBe("ref: docs/a.md\n");
+  writeNotes(state, "2026-09-01-waiting", "");
+  expect(readNotes(state, "2026-09-01-waiting")).toBe("");
+});
+
+test("notes log: stamped entries, continuation lines, unstamped preamble", () => {
+  const src = "hand written\n[2026-09-14 10:00] first\n  more\n[2026-09-14 10:05] ![shot](attachments/a.png)\n";
+  expect(parseNotes(src)).toEqual([
+    { at: "", text: "hand written" },
+    { at: "2026-09-14 10:00", text: "first\nmore" },
+    { at: "2026-09-14 10:05", text: "![shot](attachments/a.png)" },
+  ]);
+  expect(formatNote("a\nb", "2026-09-14 10:00")).toBe("[2026-09-14 10:00] a\n  b");
+});
+
+test("notes log: append to a run and to an idea; attachments saved and made absolute in the prompt", () => {
+  expect(appendNote(state, { id: "2026-09-01-waiting" }, "run note")).toBeNull();
+  expect(parseNotes(readNotes(state, "2026-09-01-waiting")).map((n) => n.text)).toEqual(["run note"]);
+  writeInbox(state, [{ status: "open", text: "chatty zq6" }]);
+  expect(appendNote(state, { text: "chatty zq6" }, "one")).toBeNull();
+  expect(appendNote(state, { text: "chatty zq6" }, "two\nlines")).toBeNull();
+  expect(appendNote(state, { text: "nope zq6" }, "x")).toBe("no such idea");
+  expect(parseNotes(readInbox(state)[0]!.notes!).map((n) => n.text)).toEqual(["one", "two\nlines"]);
+  const rel = saveAttachment(state, null, "../evil name.png", new Uint8Array([1]));
+  expect(rel).toMatch(/^attachments\/\w+-_evil_name\.png$/);
+  expect(requestOf("x", `![s](${rel})`, state)).toBe(`x\n\n![s](${join(state, rel)})`);
+  expect(saveAttachment(state, "2026-09-01-waiting", "b.txt", new Uint8Array([2]))).toMatch(/^runs\/2026-09-01-waiting\/attachments\//);
+});

package/cli/state.ts

@@ -7,7 +7,7 @@ import { homedir } from "node:os";
 
 export const home = homedir();
 
-export type Run = { id: string; stage: string; awaiting: string | null; moved: number };
+export type Run = { id: string; stage: string; awaiting: string | null; moved: number; runner?: string; agent?: string };
 
 export const KNOWN_AGENTS = [
   { name: "Claude Code", dir: ".claude", cmd: "claude" },
@@ -202,7 +202,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 }];
+      return [{ id, stage: s.stage ?? "?", awaiting: s.awaiting ?? null, moved, runner: s.runner, agent: s.agent }];
     } catch { return []; }
   }).reverse();
 }
@@ -249,7 +249,7 @@ export function readFindings(file: string) {
 // Backlog items are often a reviewer's finding pasted verbatim -- a backticked
 // path, a severity, then the sentence. Split those apart so a list can show the
 // severity and the place as columns and leave the prose to speak for itself.
-export type Item = { severity: string | null; where: string | null; text: string; raw: string };
+export type Item = { severity: string | null; where: string | null; text: string; raw: string; notes?: string };
 
 export function parseItem(raw: string): Item {
   const m = /^`?([^`:]+(?::\d+)?)`?\s*[:—-]\s*(critical|high|medium|low)\s*[:—-]\s*(.+)$/i.exec(raw);
@@ -307,6 +307,9 @@ export type Card = {
   dim: boolean;
   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
+  tags?: string[];                                 // runs only: runner and agent, when recorded
+  notes?: string;                                  // inbox notes, or runs/<id>/notes.md
 };
 
 // A run is called running on the evidence that it moved recently; there is no PID
@@ -354,17 +357,24 @@ export function columnOf(stage: string) {
   return 1;
 }
 
-export type InboxLine = { status: string; text: string };
+// notes: free text under the bullet -- links, path:line refs, background. Kept as
+// indented continuation lines so a one-line inbox from before notes reads unchanged.
+export type InboxLine = { status: string; text: string; notes?: string };
 
 // Ideas with no run yet. Deliberately not backlog.md, which the spec defines as
 // an orphanage for items rescued from pruned runs, and not a run stub each.
 export function readInbox(state: string): InboxLine[] {
   const f = join(state, "inbox.md");
   if (!existsSync(f)) return [];
-  return readFileSync(f, "utf8").split("\n")
-    .map((l) => /^-\s*(open|started|done|rejected):\s*(.+)$/.exec(l.trim()))
-    .filter((m): m is RegExpExecArray => !!m)
-    .map((m) => ({ status: m[1]!, text: m[2]!.trim() }));
+  const out: InboxLine[] = [];
+  for (const raw of readFileSync(f, "utf8").split("\n")) {
+    const m = /^-\s*(open|started|done|rejected|archived):\s*(.+)$/.exec(raw.trim());
+    if (m) { out.push({ status: m[1]!, text: m[2]!.trim() }); continue; }
+    // An indented line belongs to the bullet above it; anything else is noise.
+    const last = out[out.length - 1];
+    if (last && /^\s{2,}\S/.test(raw)) last.notes = (last.notes ? last.notes + "\n" : "") + raw.trim();
+  }
+  return out;
 }
 
 // Whole-file rewrite. The board is the only writer today.
@@ -377,11 +387,93 @@ export function writeInbox(state: string, lines: InboxLine[]) {
     "",
     "Ideas with no run yet. One line each, same format as a run's backlog.",
     "",
-    ...lines.map((l) => `- ${l.status}: ${l.text}`),
+    ...lines.flatMap((l) => [`- ${l.status}: ${l.text}`, ...noteLines(l.notes)]),
   ];
   writeFileSync(join(state, "inbox.md"), body.join("\n") + "\n");
 }
 
+function noteLines(notes?: string) {
+  return (notes ?? "").split("\n").map((n) => n.trim()).filter(Boolean).map((n) => "  " + n);
+}
+
+// The request the agent is launched with: the text, then the notes as the rest of the
+// request, so they land verbatim in 00-request.md and the planner reads them.
+export function requestOf(text: string, notes?: string, state?: string) {
+  let n = (notes ?? "").trim();
+  if (state) n = n.replace(/\]\((attachments\/[^)]+)\)/g, (_, p) => `](${join(state, p)})`);
+  return n ? `${text}\n\n${n}` : text;
+}
+
+// Free text beside a run -- what the user learned after the idea became a run.
+// Its own file, never state.json: that shape is the resume contract.
+export function readNotes(state: string, id: string) {
+  try { return readFileSync(join(state, "runs", id, "notes.md"), "utf8"); } catch { return ""; }
+}
+
+export function writeNotes(state: string, id: string, text: string): string | null {
+  const dir = join(state, "runs", id);
+  if (!existsSync(join(dir, "state.json"))) return "no such run";
+  writeFileSync(join(dir, "notes.md"), text.trim() ? text.trim() + "\n" : "");
+  return null;
+}
+
+// Notes are a log, one entry per message: `[2026-09-14 15:34] text`, continuation
+// lines indented. Text before the first stamp is one unstamped entry, so notes
+// written by hand still read.
+export type Note = { at: string; text: string };
+
+export function parseNotes(src: string): Note[] {
+  const out: Note[] = [];
+  for (const raw of src.split("\n")) {
+    const m = /^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2})\]\s?(.*)$/.exec(raw);
+    if (m) { out.push({ at: m[1]!, text: m[2]! }); continue; }
+    const last = out[out.length - 1];
+    if (last) last.text += "\n" + raw.replace(/^\s{2}/, "");
+    else if (raw.trim()) out.push({ at: "", text: raw });
+  }
+  return out.map((n) => ({ ...n, text: n.text.trim() })).filter((n) => n.text);
+}
+
+export function stamp(now = new Date()) {
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())} ${p(now.getHours())}:${p(now.getMinutes())}`;
+}
+
+export function formatNote(text: string, at = stamp()) {
+  return `[${at}] ${text.trim().replace(/\n/g, "\n  ")}`;
+}
+
+// Append one entry: to runs/<id>/notes.md for a run, or under the idea's inbox
+// bullet. Attachments arrive as markdown links already written into text.
+export function appendNote(state: string, target: { id: string } | { text: string }, text: string): string | null {
+  if (!text.trim()) return "empty note";
+  if ("id" in target) {
+    if (!existsSync(join(state, "runs", target.id, "state.json"))) return "no such run";
+    appendFileSync(join(state, "runs", target.id, "notes.md"), formatNote(text) + "\n");
+    return null;
+  }
+  const lines = readInbox(state);
+  const at = lines.findIndex((l) => l.status === "open" && l.text === target.text);
+  if (at < 0) return "no such idea";
+  const prev = lines[at]!.notes;
+  lines[at] = { ...lines[at]!, notes: (prev ? prev + "\n" : "") + formatNote(text) };
+  writeInbox(state, lines);
+  return null;
+}
+
+// A file beside the notes it belongs to: runs/<id>/attachments/ for a run,
+// <state>/attachments/ for an idea. Returns the path relative to the state dir,
+// which is what the note links and what /file serves.
+// ponytail: no dedupe, no size accounting beyond the request cap in web.ts.
+export function saveAttachment(state: string, id: string | null, name: string, bytes: Uint8Array) {
+  const safe = name.replace(/[^\w.-]+/g, "_").replace(/^\.+/, "") || "file";
+  const rel = id ? join("runs", id, "attachments") : "attachments";
+  mkdirSync(join(state, rel), { recursive: true });
+  const file = `${Date.now().toString(36)}-${safe}`;
+  writeFileSync(join(state, rel, file), bytes);
+  return join(rel, file);
+}
+
 // Best effort: a machine without notify-send loses the notification, not the board.
 export function notify(title: string, body: string) {
   try {
@@ -421,10 +513,34 @@ export function replaceIdea(state: string, text: string, next: InboxLine | null)
   const lines = readInbox(state);
   const at = lines.findIndex((l) => (l.status === "open" || l.status === "started") && l.text === text);
   if (at < 0) return;                            // changed underneath us; the redraw will show why
-  if (next) lines[at] = next; else lines.splice(at, 1);
+  if (next) lines[at] = { notes: lines[at]!.notes, ...next }; else lines.splice(at, 1);
   writeInbox(state, lines);
 }
 
+// Archived runs stay exactly where they are on disk -- run directories are never
+// moved or renamed, that is the resume contract -- and are listed here instead.
+// One id per line; the board hides them unless asked for the archive.
+export function readArchive(state: string): Set<string> {
+  const f = join(state, "archive.md");
+  if (!existsSync(f)) return new Set();
+  return new Set(readFileSync(f, "utf8").split("\n")
+    .map((l) => /^-\s*(\S+)/.exec(l.trim())?.[1])
+    .filter((x): x is string => !!x));
+}
+
+export function writeArchive(state: string, ids: Set<string>) {
+  mkdirSync(state, { recursive: true });
+  const body = ["# Archive", "", "Runs cleared from the board. One id per line; delete a line to bring it back.", "",
+    ...[...ids].sort().map((id) => `- ${id}`)];
+  writeFileSync(join(state, "archive.md"), body.join("\n") + "\n");
+}
+
+export function setArchived(state: string, id: string, archived: boolean) {
+  const ids = readArchive(state);
+  if (archived) ids.add(id); else ids.delete(id);
+  writeArchive(state, ids);
+}
+
 // The request's first real line: not a heading, not a label ending in a colon,
 // quote marker dropped. Long enough to recognise the run, short enough for a card.
 export function requestTitle(text: string) {
@@ -458,16 +574,17 @@ export function boardCards(states: string[], now: number): Card[] {
   }
   for (const st of states) {
     const where = label(st);
+    const archive = readArchive(st);
     for (const it of readInbox(st)) {
-      if (it.status !== "open" && it.status !== "started") continue;
+      if (it.status !== "open" && it.status !== "started" && it.status !== "archived") continue;
       // Retired once any run's request contains this text -- whoever started it.
       // Checking `started` items only would leave every idea acted on outside the
       // board sitting in IDEA forever, and typing `/kaizen ...` in a terminal is
       // the common way a run begins.
       if (requests.some((r) => r.includes(normalise(it.text)))) continue;
       next.push(it.status === "started"
-        ? { kind: "idea", status: "starting", text: it.text, state: st, where, column: 1, awaiting: null, dim: true }
-        : { kind: "idea", status: "idea", text: it.text, state: st, where, column: 0, awaiting: null, dim: false });
+        ? { kind: "idea", status: "starting", text: it.text, state: st, where, column: 1, awaiting: null, dim: true, archived: false, notes: it.notes }
+        : { kind: "idea", status: "idea", text: it.text, state: st, where, column: 0, awaiting: null, dim: false, archived: it.status === "archived", notes: it.notes });
     }
     for (const r of readRuns(st)) {
       next.push({
@@ -475,6 +592,9 @@ export function boardCards(states: string[], now: number): Card[] {
         title: requestTitle(body(st, r.id)),
         awaiting: r.stage === "abandoned" ? null : r.awaiting,
         dim: r.stage === "abandoned",
+        archived: archive.has(r.id),
+        tags: [r.runner, r.agent].filter((t): t is string => !!t),
+        notes: readNotes(st, r.id) || undefined,
       });
     }
   }
@@ -501,9 +621,11 @@ export function manualCommand(projectDir: string, agentCmd: string, prompt: stri
 
 export function launchRun(it: Item, from: string): Launch {
   const projectDir = projectOf(from);
+  // The run will be born here; the board must know the dir or the idea never retires.
+  remember(projectDir);
   const agent = detectDefaultAgent(projectDir);
   const agentBin = Bun.which(agent.cmd) ?? agent.cmd;
-  const prompt = it.where ? `/kaizen ${it.text} (${it.where})` : `/kaizen ${it.text}`;
+  const prompt = requestOf(it.where ? `/kaizen ${it.text} (${it.where})` : `/kaizen ${it.text}`, it.notes, from);
   const fullCmd = [agentBin, prompt];
   const manual = manualCommand(projectDir, agent.cmd, prompt);