kaizen-agent 1.48.0 → 1.49.0

package/README.md

@@ -28,7 +28,7 @@
 
 | | |
 |---|---|
-| **Any kind of work** | Each run works out what it is making (code, writing, communication, operations, research) and plans, builds and reviews it in those terms. Videos and decks go through the bundled `story-video`, `kaizen-video` (editing your own footage) and `story-deck` skills. |
+| **Any kind of work** | Each run works out what it is making (code, writing, communication, operations, research) and plans, builds and reviews it in those terms. Videos and decks go through the bundled `kaizen-video` (films from scratch, or editing your own footage) and `kaizen-deck` skills; books go through `kaizen-book` (interview, writing, proofreading, then an e-book reader plus colour and black-and-white print PDFs). |
 | **Plan first** | The agent writes what it will do, and what *wrong* would look like, then waits for your approve or change. |
 | **A reviewer that starts cold** | A second agent reviews from the request, the plan and the diff only. It never saw the work, so it has nothing to defend. |
 | **A fix loop that ends** | Serious findings are fixed and re-checked, at most twice. The rest come to you; what is left goes to a backlog. |
@@ -141,7 +141,7 @@ bun run cli/install.ts    # install from this checkout
 | Path | What it is |
 |---|---|
 | `cli/` | The installer and the runtime behind every `kaizen` command: `install.ts` (the CLI), `state.ts` (runs), `web.ts` (board server), `dashboard.ts` (terminal board), `sources.ts`, `settings.ts`, `notes.ts`. Tests beside them. |
-| `skills/` | The workflow as Agent Skills folders: `kaizen/` (`SKILL.md`, the `spec-*.md` stage contracts, `adapters.md`, `config.default.yml`), `kaizen-help/`, `story-deck/`, `story-video/`, `kaizen-video/`. |
+| `skills/` | The workflow as Agent Skills folders: `kaizen/` (`SKILL.md`, the `spec-*.md` stage contracts, `adapters.md`, `config.default.yml`), `kaizen-help/`, and `media/` with `kaizen-deck/`, `kaizen-video/`, `kaizen-book/`. |
 | `agents/` | The Claude Code subagents: `kaizen-planner`, `kaizen-builder`, `kaizen-reviewer`. |
 | `commands/` | The `/kaizen-*` slash commands, one file each. |
 | `web/` | The board and notebook front end: `board.html`, `notes.html`, `notebook.ts`. |

package/cli/build-web.ts

@@ -1,7 +1,7 @@
 // `bun run build:web`: bundles the notebook's script and CodeMirror into
 // web/notebook.js, the in-card terminal and xterm.js into web/term.js (+ its
 // stylesheet, web/term.css), the board's modules (web/board/) into web/board.js and
-// Kaizen Bot's page modules (bot/web/app/) into bot/web/app.js, all committed, so an install or a checkout serves it with no
+// Kaizen Bot's page modules (bot/web/app/) into bot/web/app.js, the Video page's script into web/video.js, all committed, so an install or a checkout serves it with no
 // install step and no network. The first line is a hash of what it was built from;
 // cli/notes.test.ts fails when a committed file no longer matches.
 import { createHash } from "node:crypto";
@@ -10,11 +10,12 @@ import { join, dirname } from "node:path";
 
 const root = dirname(import.meta.dir);
 const modules = (dir: string) => readdirSync(join(root, dir)).filter((f) => f.endsWith(".ts")).sort().map((f) => `${dir}/${f}`);
-const SOURCES = ["web/notebook.ts", "web/notes-lib.ts", "web/term.ts", ...modules("web/board"), ...modules("bot/web/app")];
+const SOURCES = ["web/notebook.ts", "web/notes-lib.ts", "web/term.ts", "web/video.ts", ...modules("web/board"), ...modules("bot/web/app")];
 export const OUT = join(root, "web", "notebook.js");
 export const TERM_OUT = join(root, "web", "term.js");
 export const BOARD_OUT = join(root, "web", "board.js");
 export const BOT_OUT = join(root, "bot", "web", "app.js");
+export const VIDEO_OUT = join(root, "web", "video.js");
 
 // The sources and the exact dependency versions: a CodeMirror bump is a rebuild too.
 export function sourceHash() {
@@ -31,6 +32,7 @@ if (import.meta.main) {
     ["web/term.ts", TERM_OUT, "terminal"],
     ["web/board/main.ts", BOARD_OUT, "board"],
     ["bot/web/app/main.ts", BOT_OUT, "bot page"],
+    ["web/video.ts", VIDEO_OUT, "video page"],
   ] as const;
   for (const [src, out, what] of bundles) {
     // The terminal, the board and the bot page are classic scripts: wrapped, or their

package/cli/hermes.ts

@@ -0,0 +1,65 @@
+// WhatsApp through Hermes (`hermes send`): the chats it knows, and one file with a
+// message to one of them. Always argv, never a shell line: the message is one argument.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export type Chat = { id: string; name: string; type: string };
+type Out = { code: number | string; out: string; err: string };
+
+// On PATH first (tests put a fake there), else where Hermes' installer puts it: a board
+// started from a desktop launcher often has no ~/.local/bin on its PATH.
+function bin() {
+  const p = Bun.which("hermes", { PATH: process.env.PATH ?? "" });
+  if (p) return p;
+  const home = join(process.env.HOME || process.env.USERPROFILE || "", ".local", "bin", "hermes");
+  return existsSync(home) ? home : null;
+}
+
+function run(args: string[], ms: number): Promise<Out> {
+  const exe = bin();
+  if (!exe) return Promise.resolve({ code: "Hermes is not installed (no hermes on PATH or in ~/.local/bin)", out: "", err: "" });
+  return new Promise((done) => {
+    const p = spawn(exe, args, { env: process.env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    let out = "", err = "";
+    p.stdout!.on("data", (c) => { out += c; });
+    p.stderr!.on("data", (c) => { err += c; });
+    const t = setTimeout(() => { p.kill("SIGKILL"); done({ code: `Hermes did not finish in ${Math.round(ms / 1000)} s`, out, err }); }, ms);
+    p.on("error", (e) => { clearTimeout(t); done({ code: `Hermes could not start: ${e.message}`, out, err }); });
+    p.on("close", (c) => { clearTimeout(t); done({ code: c ?? 1, out, err }); });
+  });
+}
+const lastLine = (s: string) => s.trim().split("\n").filter(Boolean).pop()?.replace(/^hermes send:\s*/, "") ?? "";
+
+export async function targets(): Promise<{ chats: Chat[] } | { error: string }> {
+  const r = await run(["send", "--list", "whatsapp", "--json"], 10_000);
+  if (typeof r.code === "string") return { error: r.code };
+  let j: any;
+  try { j = JSON.parse(r.out); } catch { return { error: lastLine(r.err) || "Hermes gave no chat list" }; }
+  const wa = j?.platforms?.whatsapp;
+  if (!Array.isArray(wa) || !wa.length) return { error: "WhatsApp is not set up in Hermes (hermes gateway setup)" };
+  return { chats: wa.filter((c: any) => typeof c?.id === "string" && c.id).map((c: any) => ({ id: `whatsapp:${c.id}`, name: String(c.name ?? c.id), type: String(c.type ?? "") })) };
+}
+
+// Hermes attaches every MEDIA:<path> it finds in the text, so the user's words may not
+// carry one: that would send a file the page never offered.
+export function message(text: string, file: string): string | { error: string } {
+  if (text.length > 1000) return { error: "the message is over 1,000 characters" };
+  if (/MEDIA:/i.test(text)) return { error: "the message may not contain MEDIA:" };
+  if (/[`\n\r]/.test(file)) return { error: "the file's path cannot be passed to Hermes" };
+  // The path in backticks: Hermes reads a quoted path whole, spaces and all.
+  return `${text.trim()}${text.trim() ? "\n" : ""}MEDIA:\`${file}\``;
+}
+
+// Sent only when Hermes exits 0 with {success: true}; anything else is its own error.
+export async function sendMedia(target: string, text: string, file: string): Promise<{ ok: true } | { ok: false; error: string }> {
+  const m = message(text, file);
+  if (typeof m !== "string") return { ok: false, error: m.error };
+  // "--" so a message starting with "-" is text, not an option.
+  const r = await run(["send", "-t", target, "--json", "--", m], 5 * 60_000);
+  if (typeof r.code === "string") return { ok: false, error: r.code };
+  let j: any = null;
+  try { j = JSON.parse(r.out); } catch { /* not JSON: fall through to stderr */ }
+  if (r.code === 0 && j?.success && !j.error) return { ok: true };
+  return { ok: false, error: String(j?.error ?? (lastLine(r.err) || `Hermes exited ${r.code}`)).slice(0, 400) };
+}

package/cli/install.ts

@@ -2,7 +2,7 @@
 import {
   symlinkSync, mkdirSync, readdirSync, lstatSync, unlinkSync,
   existsSync, copyFileSync, readFileSync, appendFileSync, rmSync, writeFileSync, renameSync,
-  statSync, cpSync, realpathSync, rmdirSync,
+  statSync, cpSync, realpathSync, rmdirSync, readlinkSync,
 } from "node:fs";
 import { join, dirname, basename, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
@@ -46,8 +46,12 @@ const c = {
   green: (s: string) => `\x1b[32m${s}\x1b[0m`,
 };
 
-// Skill folders shipped in skills/ and linked into every agent.
-const SKILLS = ["kaizen", "kaizen-help", "story-deck", "story-video", "kaizen-video"];
+// Skill folders shipped in skills/ and linked into every agent, by their last
+// path segment: media/kaizen-deck is linked as skills/kaizen-deck.
+const SKILLS = ["kaizen", "kaizen-help", "media/kaizen-deck", "media/kaizen-video", "media/kaizen-book"];
+// Skill names an older release linked; uninstall drops them and install
+// clears them when they are still our links.
+const RENAMED_SKILLS = ["story-deck", "story-video", "kaizen-motion"];
 
 // Where each agent reads skills from. The skill folders follow the open Agent
 // Skills standard, so every one of these can run the workflow; agents/ and
@@ -244,7 +248,9 @@ async function removeEverything() {
 
   for (const root of roots) {
     for (const a of AGENTS) {
-      for (const n of SKILLS) drop(join(root, a.dir, "skills", n));
+      for (const n of SKILLS) drop(join(root, a.dir, "skills", basename(n)));
+      // An old name is only ours while it is still a link; a real folder there is the user's.
+      for (const n of RENAMED_SKILLS) if (isLink(join(root, a.dir, "skills", n))) drop(join(root, a.dir, "skills", n));
       for (const sub of ["agents", "commands"]) {
         const dir = join(root, a.dir, sub);
         try {
@@ -524,7 +530,7 @@ if (interactive && !upgrade && Bun.argv.length === 2) {
   if (!stale) {
     const here = found(home);
     const linked = here.length > 0 && here.every((a) =>
-      SKILLS.every((n) => existsSync(join(home, a.dir, "skills", n))));
+      SKILLS.every((n) => existsSync(join(home, a.dir, "skills", basename(n)))));
     if (linked) {
       const { dashboard } = await import("./dashboard.ts");
       await dashboard(repoDir, here.map((a) => a.name), async (action) => {
@@ -900,6 +906,13 @@ for (const [src, sub] of links) {
   wrote++;
   if (verbose) console.log(c.dim(`  link  ${name}`));
 }
+if (!check) {
+  for (const a of targets) for (const n of RENAMED_SKILLS) {
+    const p = join(root, a.dir, "skills", n);
+    // Ours only: a dangling link to a folder of that same name, which kaizen has since renamed.
+    if (isLink(p) && !existsSync(p) && basename(readlinkSync(p).replace(/[\\/]+$/, "")) === n) removeLink(p);
+  }
+}
 
 // A project's spec copies are what a run there reads, and they are copied once.
 function specDrift() {

package/cli/localsend.test.ts

@@ -0,0 +1,84 @@
+// LocalSend's sending half against a fake device that speaks protocol v2: what it
+// receives, and what each of its refusals reads as on the page.
+import { test, expect } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomBytes, X509Certificate, createPrivateKey } from "node:crypto";
+import { identity, sendFile, type Device } from "./localsend.ts";
+
+// prepare: what prepare-upload answers (a status, or "hang" to never answer).
+function fakeDevice(prepare: number | "hang") {
+  const got: { prepare?: any; upload?: { query: Record<string, string>; bytes: Buffer } } = {};
+  const srv = Bun.serve({ port: 0, hostname: "127.0.0.1", async fetch(req) {
+    const u = new URL(req.url);
+    if (u.pathname === "/api/localsend/v2/prepare-upload") {
+      got.prepare = await req.json();
+      if (prepare === "hang") { await Bun.sleep(5000); return new Response(null, { status: 500 }); }
+      if (prepare !== 200) return new Response(null, { status: prepare });
+      return Response.json({ sessionId: "s-1", files: { f1: "tok-1" } });
+    }
+    if (u.pathname === "/api/localsend/v2/upload") {
+      const q = Object.fromEntries(u.searchParams);
+      if (q.sessionId !== "s-1" || q.token !== "tok-1" || q.fileId !== "f1") return new Response(null, { status: 403 });
+      got.upload = { query: q, bytes: Buffer.from(await req.arrayBuffer()) };
+      return new Response(null, { status: 200 });
+    }
+    return new Response(null, { status: 404 });
+  } });
+  const dev: Device = { alias: "Pixel 8", deviceModel: "Pixel", deviceType: "mobile", ip: "127.0.0.1", port: srv.port, protocol: "http", fingerprint: "fp" };
+  return { dev, got, stop: () => srv.stop(true) };
+}
+
+function file() {
+  const f = join(mkdtempSync(join(tmpdir(), "kaizen-ls-")), "demo-9x16.mp4");
+  writeFileSync(f, randomBytes(300_000));
+  return f;
+}
+
+test("a send carries the file's bytes with the session and token the device gave", async () => {
+  const d = fakeDevice(200), f = file(), steps: string[] = [];
+  try {
+    expect(await sendFile(d.dev, f, (p) => steps.push(p.phase))).toEqual({ ok: true });
+    expect(d.got.prepare.files.f1).toMatchObject({ id: "f1", fileName: "demo-9x16.mp4", size: 300_000, fileType: "video/mp4" });
+    expect(d.got.prepare.info.alias).toStartWith("kaizen");
+    expect(d.got.upload!.query).toEqual({ sessionId: "s-1", fileId: "f1", token: "tok-1" });
+    expect(d.got.upload!.bytes.equals(await Bun.file(f).bytes().then(Buffer.from))).toBe(true);
+    expect(steps[0]).toBe("waiting");
+    expect(steps.at(-1)).toBe("uploading");
+  } finally { d.stop(); }
+});
+
+test("a refusal, a busy device and no answer each say so, never sent", async () => {
+  const f = file();
+  for (const [status, words] of [[403, "Pixel 8 said no"], [409, "Pixel 8 is busy with another transfer"], [401, "PIN"], [500, "Pixel 8 answered 500"]] as const) {
+    const d = fakeDevice(status);
+    try {
+      const r = await sendFile(d.dev, f);
+      expect(r.ok).toBe(false);
+      expect((r as any).error).toContain(words);
+      expect(d.got.upload).toBeUndefined();
+    } finally { d.stop(); }
+  }
+  const d = fakeDevice("hang");
+  try {
+    const r = await sendFile(d.dev, f, () => {}, { acceptMs: 300 });
+    expect(r).toEqual({ ok: false, error: "No answer from Pixel 8 in 1 minute" });
+  } finally { d.stop(); }
+  // Nobody there at all.
+  const r = await sendFile({ ...d.dev, port: 1 }, f);
+  expect(r.ok).toBe(false);
+  expect((r as any).error).toStartWith("Could not reach Pixel 8");
+});
+
+// A real LocalSend in HTTPS mode refuses a sender without a client certificate
+// ("tlsv13 alert certificate required"), and reads the sender's fingerprint as its SHA-256.
+test("we carry a self-signed certificate whose SHA-256 is our fingerprint", () => {
+  const me = identity(), x = new X509Certificate(me.cert);
+  expect(x.subject).toBe("CN=kaizen");
+  expect(x.verify(x.publicKey)).toBe(true);
+  expect(x.checkPrivateKey(createPrivateKey(me.key))).toBe(true);
+  expect(x.fingerprint256.replace(/:/g, "")).toBe(me.fingerprint);
+  expect(new Date(x.validTo).getTime()).toBeGreaterThan(Date.now() + 365 * 86_400_000);
+  expect(identity()).toBe(me);
+});

package/cli/localsend.ts

@@ -0,0 +1,131 @@
+// LocalSend protocol v2, the sending half: find devices on this network the way the
+// LocalSend app does, and send one file to one of them. The person accepts on the
+// device. https://github.com/localsend/protocol — Bun's dgram, fetch and Bun.serve only.
+import { createSocket } from "node:dgram";
+import { createHash, generateKeyPairSync, randomBytes, sign } from "node:crypto";
+import { basename } from "node:path";
+import { hostname } from "node:os";
+
+export const GROUP = "224.0.0.167", PORT = 53317;
+export type Device = { alias: string; deviceModel: string | null; deviceType: string | null; ip: string; port: number; protocol: "http" | "https"; fingerprint: string };
+
+// A device in HTTPS mode (the app's default) asks the sender for a TLS client
+// certificate, and LocalSend's fingerprint is that certificate's SHA-256. So we carry a
+// self-signed one, made once per board on first use: an RSA key and a minimal X.509 v3
+// certificate in DER, signed with node:crypto, since Bun can sign but not issue one.
+const der = (tag: number, ...parts: Buffer[]) => {
+  const body = Buffer.concat(parts), n = body.length;
+  const len = n < 128 ? Buffer.from([n]) : n < 256 ? Buffer.from([0x81, n]) : Buffer.from([0x82, n >> 8, n & 255]);
+  return Buffer.concat([Buffer.from([tag]), len, body]);
+};
+const seq = (...p: Buffer[]) => der(0x30, ...p);
+const oid = (hex: string) => der(0x06, Buffer.from(hex, "hex"));
+const time = (d: Date) => der(0x18, Buffer.from(d.toISOString().replace(/[-:T]|\.\d+/g, "")));
+const pem = (label: string, b: Buffer) => `-----BEGIN ${label}-----\n${b.toString("base64").match(/.{1,64}/g)!.join("\n")}\n-----END ${label}-----\n`;
+let id: { cert: string; key: string; fingerprint: string } | null = null;
+export function identity() {
+  if (id) return id;
+  const { publicKey, privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+  const alg = seq(oid("2a864886f70d01010b"), Buffer.from([5, 0])); // sha256WithRSAEncryption
+  const name = seq(der(0x31, seq(oid("550403"), der(0x0c, Buffer.from("kaizen")))));
+  const now = Date.now();
+  const tbs = seq(der(0xa0, der(0x02, Buffer.from([2]))), der(0x02, Buffer.concat([Buffer.from([1]), randomBytes(8)])), alg, name,
+    seq(time(new Date(now - 86_400_000)), time(new Date(now + 10 * 365 * 86_400_000))), name, publicKey.export({ type: "spki", format: "der" }));
+  const cert = seq(tbs, alg, der(0x03, Buffer.from([0]), sign("sha256", tbs, privateKey)));
+  return id = { cert: pem("CERTIFICATE", cert), key: privateKey.export({ type: "pkcs8", format: "pem" }) as string, fingerprint: createHash("sha256").update(cert).digest("hex").toUpperCase() };
+}
+// Who we say we are; the fingerprint also lets discovery drop our own announce.
+const me = () => ({ alias: `kaizen (${hostname()})`, version: "2.0", deviceModel: "kaizen", deviceType: "desktop", fingerprint: identity().fingerprint, download: false });
+
+const device = (m: any, ip: string): Device | null => {
+  if (!m || typeof m.fingerprint !== "string" || !m.fingerprint || m.fingerprint === me().fingerprint || typeof m.alias !== "string") return null;
+  const port = Number(m.port ?? PORT);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+  return { alias: m.alias.slice(0, 80), deviceModel: typeof m.deviceModel === "string" ? m.deviceModel : null, deviceType: typeof m.deviceType === "string" ? m.deviceType : null,
+    ip: ip.replace(/^::ffff:/, ""), port, protocol: m.protocol === "https" ? "https" : "http", fingerprint: m.fingerprint };
+};
+
+// Announce on the multicast group and collect who answers for `ms`: devices reply by
+// POSTing /register to the port we announced, or by multicast. The LocalSend app on this
+// computer may hold UDP 53317 already; reuseAddr shares it on Linux and macOS, and where
+// binding still fails we announce from any port and rely on the HTTP replies.
+export async function discover(ms = 3000): Promise<{ devices: Device[]; note: string | null }> {
+  const found = new Map<string, Device>();
+  const add = (d: Device | null) => { if (d) found.set(d.fingerprint, d); };
+  const http = Bun.serve({ port: 0, hostname: "0.0.0.0", async fetch(req, srv) {
+    if (req.method === "POST" && new URL(req.url).pathname === "/api/localsend/v2/register") {
+      add(device(await req.json().catch(() => null), srv.requestIP(req)?.address ?? ""));
+      return Response.json({ ...me(), port: http.port, protocol: "http" });
+    }
+    return new Response("not found", { status: 404 });
+  } });
+  const sock = createSocket({ type: "udp4", reuseAddr: true });
+  let note: string | null = null;
+  try {
+    sock.on("message", (buf, r) => { try { add(device(JSON.parse(String(buf)), r.address)); } catch { /* not LocalSend */ } });
+    await new Promise<void>((ok) => {
+      sock.once("error", () => { note = "could not listen on UDP 53317; only devices that answer over HTTP are listed"; sock.bind(0, ok); });
+      sock.bind(PORT, () => { try { sock.addMembership(GROUP); } catch { /* no multicast route; replies still come over HTTP */ } ok(); });
+    });
+    const hello = Buffer.from(JSON.stringify({ ...me(), port: http.port, protocol: "http", announce: true }));
+    // Twice, as the app does: one datagram on a busy Wi-Fi is easy to lose.
+    for (const wait of [0, 600]) { await Bun.sleep(wait); sock.send(hello, PORT, GROUP); }
+    await Bun.sleep(Math.max(0, ms - 600));
+  } catch (e) { note = `discovery failed: ${e instanceof Error ? e.message : e}`; }
+  finally { try { sock.close(); } catch { /* closed */ } http.stop(true); }
+  return { devices: [...found.values()].sort((a, b) => a.alias.localeCompare(b.alias)), note };
+}
+
+export type Progress = { phase: "waiting" | "uploading"; pct: number };
+export type Result = { ok: true } | { ok: false; error: string };
+
+// One file to one device. The device shows its accept prompt during prepare-upload;
+// "sent" is only the upload's 200. Self-signed certificates are accepted: LocalSend
+// devices all use one, the same trust LocalSend itself gives a device on the LAN; ours goes
+// back as the client certificate.
+export async function sendFile(dev: Device, file: string, onProgress: (p: Progress) => void = () => {},
+  { acceptMs = 120_000, uploadMs = 30 * 60_000 } = {}): Promise<Result> {
+  const base = `${dev.protocol}://${dev.ip.includes(":") ? `[${dev.ip}]` : dev.ip}:${dev.port}/api/localsend/v2`;
+  const f = Bun.file(file), size = f.size, name = basename(file);
+  const type = name.endsWith(".mp4") ? "video/mp4" : name.endsWith(".jpg") ? "image/jpeg" : name.endsWith(".srt") ? "text/plain" : "application/octet-stream";
+  const { cert, key } = identity();
+  const tls = { rejectUnauthorized: false, cert, key };
+  onProgress({ phase: "waiting", pct: 0 });
+  let r: Response;
+  try {
+    r = await fetch(`${base}/prepare-upload`, { method: "POST", tls, signal: AbortSignal.timeout(acceptMs), headers: { "content-type": "application/json" },
+      body: JSON.stringify({ info: { ...me(), port: PORT, protocol: "http" }, files: { f1: { id: "f1", fileName: name, size, fileType: type } } }) } as RequestInit);
+  } catch (e) {
+    return { ok: false, error: e instanceof Error && e.name === "TimeoutError" ? `No answer from ${dev.alias} in ${Math.round(acceptMs / 60_000) || 1} minute${acceptMs > 60_000 ? "s" : ""}` : `Could not reach ${dev.alias}: ${e instanceof Error ? e.message : e}` };
+  }
+  if (r.status === 204) return { ok: false, error: `${dev.alias} needed nothing (it already has the file)` };
+  if (r.status === 403) return { ok: false, error: `${dev.alias} said no` };
+  if (r.status === 401) return { ok: false, error: `${dev.alias} asks for a PIN; turn the PIN off in its LocalSend settings` };
+  if (r.status === 409) return { ok: false, error: `${dev.alias} is busy with another transfer` };
+  if (r.status === 429) return { ok: false, error: `${dev.alias} says too many requests; try again in a minute` };
+  if (r.status !== 200) return { ok: false, error: `${dev.alias} answered ${r.status}` };
+  const s = await r.json().catch(() => null) as { sessionId?: string; files?: Record<string, string> } | null;
+  const token = s?.files?.f1;
+  if (!s?.sessionId || !token) return { ok: false, error: `${dev.alias} did not accept the file` };
+
+  // The bytes, streamed, counting as they go.
+  let sent = 0, last = -1;
+  const reader = f.stream().getReader();
+  const body = new ReadableStream<Uint8Array>({ async pull(c) {
+    const { done, value } = await reader.read();
+    if (done) return c.close();
+    sent += value.byteLength;
+    const pct = size ? Math.floor((sent / size) * 100) : 100;
+    if (pct !== last) { last = pct; onProgress({ phase: "uploading", pct }); }
+    c.enqueue(value);
+  } });
+  const q = new URLSearchParams({ sessionId: s.sessionId, fileId: "f1", token });
+  try {
+    const u = await fetch(`${base}/upload?${q}`, { method: "POST", tls, body, signal: AbortSignal.timeout(uploadMs),
+      headers: { "content-type": type, "content-length": String(size) } } as RequestInit);
+    if (u.status === 200) return { ok: true };
+    return { ok: false, error: u.status === 403 ? `${dev.alias} cancelled the transfer` : `${dev.alias} stopped the upload (${u.status})` };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error && e.name === "TimeoutError" ? `The upload to ${dev.alias} took over ${Math.round(uploadMs / 60_000)} minutes` : `The upload to ${dev.alias} broke off: ${e instanceof Error ? e.message : e}` };
+  }
+}

package/cli/notes.test.ts

@@ -6,7 +6,7 @@ import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { safeName, listNotes, saveNote, renameNote, deleteNote, boardIndex, linksTo } from "./notes.ts";
 import { wikilinks, tags, resolve, safeUrl, tree, uncode, freshName, parseTable, boardLink, resolveRun, anchorWords } from "../web/notes-lib.ts";
-import { sourceHash, OUT, TERM_OUT, BOARD_OUT, BOT_OUT } from "./build-web.ts";
+import { sourceHash, OUT, TERM_OUT, BOARD_OUT, BOT_OUT, VIDEO_OUT } from "./build-web.ts";
 
 let state = "";
 beforeEach(() => { state = join(mkdtempSync(join(tmpdir(), "kaizen-notes-")), ".kaizen"); mkdirSync(state); });
@@ -223,15 +223,17 @@ test("the side menu is the board's on the notebook, line for line", () => {
     return s.slice(at, s.indexOf(to, at) + to.length);
   };
   for (const [from, to] of [["/* side menu:", "/* end side menu */"], ['<nav class="rail"', "</script>"]] as const)
-    expect(between("notes.html", from, to)).toBe(between("board.html", from, to));
-  const syms = (f: string) => ["board", "note", "link", "gear", "side", "sun", "moon"].map((n) => readFileSync(join(root, "web", f), "utf8").split("\n").find((l) => l.startsWith(`<symbol id="i-${n}"`)));
+    for (const page of ["notes.html", "video.html"]) expect(between(page, from, to)).toBe(between("board.html", from, to));
+  const syms = (f: string) => ["board", "note", "video", "link", "gear", "side", "sun", "moon"].map((n) => readFileSync(join(root, "web", f), "utf8").split("\n").find((l) => l.startsWith(`<symbol id="i-${n}"`)));
   expect(syms("notes.html")).toEqual(syms("board.html"));
+  expect(syms("video.html")).toEqual(syms("board.html"));
   expect(syms("board.html").every(Boolean)).toBe(true);
 });
 
-test("web/notebook.js, web/term.js, web/board.js and bot/web/app.js were built from the sources as they are (bun run build:web)", () => {
+test("web/notebook.js, web/term.js, web/board.js, web/video.js and bot/web/app.js were built from the sources as they are (bun run build:web)", () => {
   expect(readFileSync(OUT, "utf8").split("\n", 1)[0]!).toContain(`kaizen notebook ${sourceHash()} `);
   expect(readFileSync(TERM_OUT, "utf8").split("\n", 1)[0]!).toContain(`kaizen terminal ${sourceHash()} `);
   expect(readFileSync(BOARD_OUT, "utf8").split("\n", 1)[0]!).toContain(`kaizen board ${sourceHash()} `);
   expect(readFileSync(BOT_OUT, "utf8").split("\n", 1)[0]!).toContain(`kaizen bot page ${sourceHash()} `);
+  expect(readFileSync(VIDEO_OUT, "utf8").split("\n", 1)[0]!).toContain(`kaizen video page ${sourceHash()} `);
 });

package/cli/settings.ts

@@ -125,6 +125,7 @@ const SETTINGS: Setting[] = [
   { key: "sources.model", label: "ChatGPT model for gathering", group: "Board", values: [], text: true, help: "Empty: plan default", when: ["sources.agent", "chatgpt"] },
   { key: "sources.effort", label: "ChatGPT effort for gathering", group: "Board", values: ["low", "medium", "high"], help: "", when: ["sources.agent", "chatgpt"] },
   { key: "board.projects_dir", label: "Projects folder", group: "Board", values: [], text: true, folder: true, help: "Empty: known projects only" },
+  { key: "board.video_dir", label: "Video library folder", group: "Board", values: [], text: true, folder: true, help: "Empty: ~/.kaizen" },
   { key: "board.open", label: "Open the board in", group: "Board", values: ["browser", "app"], help: "" },
   { key: "ui.mouse", label: "Enable mouse", group: "Terminal", values: ["false", "true"], help: "" },
 ];

package/cli/state.test.ts

@@ -854,6 +854,43 @@ test("ownerOf: a run that recorded the launch's session id owns it, however its
   expect(ownerOf(st, { ...rec, sessionId: "other" })).toBe(null);
 });
 
+test("ownerOf: a conversation that opens a follow-up run moves to it, even from a decision on its parent", () => {
+  const p = sessionProject(), st = join(p, ".kaizen");
+  const tag = (id: string, more: object = {}) => {
+    const f = join(st, "runs", id, "state.json");
+    writeFileSync(f, JSON.stringify({ ...JSON.parse(readFileSync(f, "utf8")), session: "abc", ...more }));
+  };
+  const rec = { key: "k", run: null, text: "tidy logs", cmd: "claude", sessionId: "abc", started: Date.now() - 2000 };
+  newRun(p, "2026-10-01-parent", "/kaizen tidy logs");
+  tag("2026-10-01-parent");
+  expect(ownerOf(st, rec)).toBe("2026-10-01-parent");
+  // A parent still in flight keeps its terminal.
+  newRun(p, "2026-10-02-child", "/kaizen rotate them too\nFollow-up of: 2026-10-01-parent");
+  tag("2026-10-02-child");
+  expect(ownerOf(st, rec)).toBe("2026-10-01-parent");
+  expect(ownerOf(st, { ...rec, run: "2026-10-01-parent" })).toBe("2026-10-01-parent");
+  tag("2026-10-01-parent", { stage: "done", awaiting: null });
+  expect(ownerOf(st, rec)).toBe("2026-10-02-child");
+  expect(ownerOf(st, { ...rec, run: "2026-10-01-parent" })).toBe("2026-10-02-child");
+  // A decision launched after both: the run it names, as before.
+  expect(ownerOf(st, { ...rec, run: "2026-10-01-parent", started: Date.now() + 5000 })).toBe("2026-10-01-parent");
+
+  // The parent's next decision still continues the conversation the child took over.
+  const saved = process.env.CLAUDE_CONFIG_DIR;
+  process.env.CLAUDE_CONFIG_DIR = mkdtempSync(join(tmpdir(), "kz-claude-"));
+  try {
+    mkdirSync(join(st, "sessions"), { recursive: true });
+    const { key, ...body } = rec;
+    writeFileSync(join(st, "sessions", key + ".json"), JSON.stringify(body) + "\n");
+    const t = join(process.env.CLAUDE_CONFIG_DIR, "projects", p.replace(/[^A-Za-z0-9]/g, "-"));
+    mkdirSync(t, { recursive: true });
+    writeFileSync(join(t, "abc.jsonl"), "{}\n");
+    expect(sessionLaunch(p, "claude", ["/bin/claude"], "/kaizen run x", "x", "2026-10-01-parent").fullCmd.slice(0, 3)).toEqual(["/bin/claude", "--resume", "abc"]);
+  } finally {
+    saved === undefined ? delete process.env.CLAUDE_CONFIG_DIR : (process.env.CLAUDE_CONFIG_DIR = saved);
+  }
+});
+
 test("findTerminal records the agent's PID: a POSIX wrapper that execs it, a PowerShell prefix on Windows", () => {
   const keys = ["PATH", "HERDR_ENV", "TMUX", "TERMINAL", "SystemRoot", "windir", "ComSpec"];
   const saved = keys.map((k) => process.env[k]);

package/cli/state.ts

@@ -1356,21 +1356,23 @@ export function readSessions(st: string): Session[] {
 }
 
 // What ownerOf matches a record against, read once: each conversation id a run recorded
-// at intake, to the first run (by id) that recorded it, and every run's request with
-// when it was written.
-type RunIndex = { bySession: Map<string, string>; requests: { id: string; born: number; text: string }[] };
+// at intake, to every run (by id) that recorded it with when its request was written,
+// and every run's request with that time.
+type RunIndex = { bySession: Map<string, { id: string; born: number; open: boolean }[]>; requests: { id: string; born: number; text: string }[] };
 export function runIndex(st: string): RunIndex {
-  const bySession = new Map<string, string>(), requests: RunIndex["requests"] = [];
+  const bySession: RunIndex["bySession"] = new Map(), requests: RunIndex["requests"] = [];
   try {
     for (const id of readdirSync(join(st, "runs")).sort()) {
-      try {
-        const sid = JSON.parse(readText(join(st, "runs", id, "state.json"))).session;
-        if (sid && !bySession.has(sid)) bySession.set(sid, id);
-      } catch { /* no state yet */ }
+      let born = 0;
       try {
         const f = join(st, "runs", id, "00-request.md"), st2 = statSync(f);
-        requests.push({ id, born: st2.birthtimeMs || st2.mtimeMs, text: normalise(readText(f)) });
+        born = st2.birthtimeMs || st2.mtimeMs;
+        requests.push({ id, born, text: normalise(readText(f)) });
       } catch { /* no request yet */ }
+      try {
+        const { session: sid, stage } = JSON.parse(readText(join(st, "runs", id, "state.json")));
+        if (sid) bySession.set(sid, [...(bySession.get(sid) ?? []), { id, born, open: stage !== "done" && stage !== "abandoned" }]);
+      } catch { /* no state yet */ }
     }
   } catch { /* no runs dir */ }
   return { bySession, requests };
@@ -1382,14 +1384,19 @@ export function runIndex(st: string): RunIndex {
 // A caller asking about many sessions passes runIndex(st) once: built per call, it
 // reads every run's state.json and request each time.
 export function ownerOf(st: string, s: Session, idx?: RunIndex): string | null {
-  if (s.run) return s.run;
   const { bySession, requests } = idx ?? runIndex(st);
   // The launch's own conversation id, recorded by the run at intake: holds however the
-  // request was worded. Text matching below is for tools that expose no id.
-  if (s.sessionId) {
-    const mine = bySession.get(s.sessionId);
-    if (mine) return mine;
-  }
+  // request was worded. A conversation that opened a run after this launch (a follow-up)
+  // has moved on to the newest such run, even from a decision on its parent: otherwise
+  // that run never gets the terminal or a Resume. A parent still in flight keeps it: its
+  // stage is not over, so the terminal is still its. Text matching below is for tools
+  // that expose no id.
+  const rec = s.sessionId ? bySession.get(s.sessionId) ?? [] : [];
+  const later = rec.filter((r) => r.born >= s.started - 1000).sort((a, b) => a.born - b.born);
+  const base = s.run ?? later[0]?.id ?? rec[0]?.id ?? null;
+  const newest = later.pop();
+  if (newest && !(base && base !== newest.id && rec.find((r) => r.id === base)?.open)) return newest.id;
+  if (base) return base;
   const t = normalise(s.text);
   let best: string | null = null, at = Infinity;
   // A second of slack: file times come from a coarser clock than Date.now().
@@ -1537,8 +1544,11 @@ export function firstSession(st: string, id: string, cmd: string, cwd: string):
   if (!f) return null;
   const all = readSessions(st);
   const taken = new Set(all.flatMap((s) => (s.sessionId ? [s.sessionId] : []))), idx = runIndex(st);
+  // Conversations this run recorded at intake: still its to continue after a follow-up
+  // run it opened took the session's ownership.
+  const mine = new Set([...idx.bySession].filter(([, rs]) => rs.some((r) => r.id === id)).map(([sid]) => sid));
   for (const s of all) {
-    if (s.cmd !== cmd || ownerOf(st, s, idx) !== id) continue;
+    if (s.cmd !== cmd || (ownerOf(st, s, idx) !== id && !(s.sessionId && mine.has(s.sessionId)))) continue;
     if (!s.sessionId && f.find) {
       // Before the tool's next launch here, any run's: from then on a conversation may be that launch's.
       const next = all.find((o) => o.cmd === cmd && o.started > s.started)?.started ?? Infinity;
@@ -1610,10 +1620,13 @@ export function trustFolder(dir: string, cfg = join(process.env.CLAUDE_CONFIG_DI
 // where a pseudo-terminal exists; onChange is told when that agent ends.
 const CHILD_ENV = /^(CLAUDECODE|CLAUDE_PID|CLAUDE_CODE_(SESSION_ID|CHILD_SESSION|SESSION_ATTENDED|MESSAGING_SOCKET|MESSAGING_TOKEN))$/;
 
-export function launchRun(it: Item, from: string, run?: string, pick: { agent?: string; model?: string; yolo?: boolean; card?: boolean; onChange?: () => void } = {}): Launch {
-  const projectDir = projectOf(from);
+// skill: start that skill instead of /kaizen (the Video page starts kaizen-video), in cwd:
+// a work folder that may not be a project, so it is not remembered as one. A session record is
+// written only where that folder has a .kaizen (a project place does; the library usually not).
+export function launchRun(it: Item, from: string, run?: string, pick: { agent?: string; model?: string; yolo?: boolean; card?: boolean; onChange?: () => void; skill?: "kaizen-video"; cwd?: string } = {}): Launch {
+  const projectDir = pick.cwd ?? projectOf(from);
   // The run will be born here; the board must know the dir or the idea never retires.
-  remember(projectDir);
+  if (!pick.cwd) remember(projectDir);
   const own = run && !pick.agent ? runAgent(join(projectDir, ".kaizen"), run) : null;
   const agent = detectDefaultAgent(projectDir, pick.agent ?? own?.cmd);
   if (agent.cmd === "claude") trustFolder(projectDir);
@@ -1623,7 +1636,9 @@ export function launchRun(it: Item, from: string, run?: string, pick: { agent?:
   // onPath, not Bun.which: the board may have taken a login shell's PATH after it started.
   const agentBin = winShim(onPath(agent.cmd) ?? agent.cmd);
   // No text: a run's conversation reopened as it was, with nothing sent to it.
-  const prompt = !it.text ? "" : requestOf(it.where ? `/kaizen ${it.text} (${it.where})` : `/kaizen ${it.text}`, it.notes, from);
+  // A skill other than kaizen: Claude Code takes it as a slash command; other agents are told to use it.
+  const lead = !pick.skill ? "/kaizen" : agent.cmd === "claude" ? `/${pick.skill}` : `Use the ${pick.skill} skill.`;
+  const prompt = !it.text ? "" : requestOf(it.where ? `${lead} ${it.text} (${it.where})` : `${lead} ${it.text}`, it.notes, from);
   const wanted = pick.model ?? (own?.cmd === agent.cmd ? own.model : null) ?? undefined;
   const model = wanted && plainModel(wanted) ? wanted : undefined;
   // Yolo was picked for one tool; a fallback to another opens in its normal mode.