conductor-board 1.2.0 → 2.0.0

package/bin/cli.js

@@ -2,6 +2,7 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import readline from "node:readline";
 import { startServer } from "../server/server.js";
 
 const argv = process.argv.slice(2);
@@ -30,6 +31,21 @@ const HELP = `
     init                     Scaffold a new .conductor/conductor.yaml
     validate [path]          Check a conductor against the spec
     setup                    Write setup.conductor.yaml (the bootstrap conductor)
+    check <step-id>          Board-sync pre-gate check — fails if the board is
+                             stale for this step (use as a step's first gate)
+    ps                       List every conductor-board running on this machine
+    stop [--all]             Stop this project's board (or every board)
+    clean [--keep N]         Trim history to the last N runs; add
+          [--prune-heartbeats] to archive old beats (keeps finalBeats + insights)
+
+  Status-writer (for agents — keep status.json live as you work)
+    status-init <file>       Generate .conductor/status.json from a conductor
+    step <id> <state>        running | done | failed  (state)
+    gate <id> <state>        checking | passed | failed
+    heartbeat <id> "note"    Append a heartbeat (--iteration, --insight-type,
+                             --insight-seed, --final, --to <step>)
+    loop <loop> <item> <sub> <state>   Update a loop sub-step
+    complete <id> [--attest-soft]      Run hard gates independently, then advance
 
   Board options
     --path, -p <file>        Path to status.json   (default: .conductor/status.json)
@@ -73,6 +89,38 @@ if (command === "setup") {
   process.exit((await runSetup(rest)) ? 0 : 1);
 }
 
+if (command === "check") {
+  const { runCheck } = await import("../cli/check.js");
+  process.exit((await runCheck(rest)) ? 0 : 1);
+}
+
+if (command === "ps") {
+  const { runPs } = await import("../cli/ps.js");
+  process.exit((await runPs()) ? 0 : 1);
+}
+
+if (command === "stop") {
+  const { runStop } = await import("../cli/stop.js");
+  process.exit((await runStop(rest)) ? 0 : 1);
+}
+
+if (command === "clean") {
+  const { runClean } = await import("../cli/clean.js");
+  process.exit((await runClean(rest)) ? 0 : 1);
+}
+
+// status-writer commands (for agents — keep the board live as you work)
+if (["step", "gate", "heartbeat", "loop", "status-init"].includes(command)) {
+  const w = await import("../cli/writer.js");
+  const fn = { step: w.runStep, gate: w.runGate, heartbeat: w.runHeartbeat, loop: w.runLoop, "status-init": w.runStatusInit }[command];
+  process.exit((await fn(rest)) ? 0 : 1);
+}
+
+if (command === "complete") {
+  const { runComplete } = await import("../cli/complete.js");
+  process.exit((await runComplete(rest)) ? 0 : 1);
+}
+
 if (command && command !== "board") {
   console.error(`Unknown command "${command}". Run with --help to see usage.`);
   process.exit(1);
@@ -117,6 +165,123 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 const iris = (s) => `\x1b[38;5;141m${s}\x1b[0m`;
 const mint = (s) => `\x1b[38;5;78m${s}\x1b[0m`;
+const amber = (s) => `\x1b[38;5;214m${s}\x1b[0m`;
+
+function ago(iso) {
+  const t = new Date(iso).getTime();
+  if (Number.isNaN(t)) return "";
+  const s = Math.max(0, Math.floor((Date.now() - t) / 1000));
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  return `${Math.floor(h / 24)}d ago`;
+}
+
+function ask(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) return resolve(false); // non-interactive — never block
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+// A pid is "alive" if signalling it doesn't throw ESRCH (EPERM = alive, not ours).
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+
+/**
+ * Before binding a port, look for a board already serving this project.
+ *
+ *  - dead pid / no file → clear any stale server.json, start fresh (returns null)
+ *  - live board, non-interactive → REUSE it (returns its info). This is the key
+ *    guard against the tab flood: re-running `npx conductor-board` no longer
+ *    spawns a second server on the next port and opens another browser tab.
+ *  - live board, interactive → ask. "y" kills it and starts fresh (null);
+ *    anything else reuses the existing one (returns its info).
+ *
+ * One board per project — you should never end up with a pile of tabs.
+ */
+async function preflightStaleBoard(serverJsonPath) {
+  let info;
+  try {
+    info = JSON.parse(fs.readFileSync(serverJsonPath, "utf8"));
+  } catch {
+    return null; // no (readable) server.json — nothing to do
+  }
+  const pid = info && info.pid;
+  const clear = () => {
+    try {
+      fs.unlinkSync(serverJsonPath);
+    } catch {
+      /* already gone */
+    }
+  };
+
+  if (!pid || !pidAlive(pid)) {
+    if (pid) {
+      clear();
+      console.log(dim(`\n  cleared a stale server.json (pid ${pid} is no longer running).`));
+    }
+    return null;
+  }
+
+  const reuse = {
+    reuse: true,
+    pid,
+    url: info.url || `http://localhost:${info.port ?? "?"}`,
+    when: info.started_at ? ago(info.started_at) : "",
+  };
+
+  // Non-interactive (an agent, a script): never duplicate — reuse silently.
+  if (!process.stdin.isTTY) return reuse;
+
+  const port = info.port ?? "?";
+  const when = info.started_at ? `, started ${ago(info.started_at)}` : "";
+  console.log("");
+  console.log(`  ${amber("⚠")}  A board is already running on port ${bold(port)} (pid ${pid}${when}).`);
+  const yes = await ask(`     Kill it and start a fresh one? ${dim("[y/N]")} `);
+  if (yes) {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      /* it may have just exited */
+    }
+    await new Promise((r) => setTimeout(r, 600)); // let it release the port
+    clear();
+    console.log(dim(`     stopped pid ${pid}.`));
+    return null;
+  }
+  return reuse;
+}
+
+const preflightServerJson = path.join(
+  path.dirname(path.resolve(process.cwd(), statusPath)),
+  "server.json",
+);
+const existing = await preflightStaleBoard(preflightServerJson);
+if (existing) {
+  console.log("");
+  console.log(`  ${iris("🎼 conductor-board")}`);
+  console.log(
+    `  ${bold("Already live at")} ${mint(existing.url)} ${dim(
+      `— reusing it (pid ${existing.pid}${existing.when ? ", started " + existing.when : ""})`,
+    )}`,
+  );
+  console.log(`  ${dim("one board per project — not opening another tab. stop that process to restart.")}`);
+  console.log("");
+  process.exit(0);
+}
 
 const { conductorPath: resolvedConductor, absStatus, server, serverJsonPath } =
   await listenWithFallback(wantedPort);

package/cli/check.js

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+
+const STALE_MS = 5 * 60 * 1000; // 5 minutes of silence ⇒ the board is stale
+
+/**
+ * Board-sync pre-check (spec §8.1). Run as the FIRST gate criterion on every
+ * step — `check: "npx conductor-board check <step-id>"` — so an agent that does
+ * work without keeping the board current literally fails its own gate.
+ *
+ * Passes only when, for <step-id>:
+ *   1. status.json's current_step matches it (it's marked running);
+ *   2. it has at least one heartbeat;
+ *   3. its most recent heartbeat is within the last 5 minutes (not stale).
+ *
+ * (We check the latest heartbeat's age, not started_at — a legitimately long
+ * step that keeps beating is fine; only silence means the board has gone stale.)
+ */
+export async function runCheck(args) {
+  const flagIdx = (names) => {
+    for (const n of names) {
+      const i = args.indexOf(n);
+      if (i !== -1) return i;
+    }
+    return -1;
+  };
+  const pi = flagIdx(["--path", "-p"]);
+  const statusPath = path.resolve(
+    process.cwd(),
+    pi !== -1 && args[pi + 1] ? args[pi + 1] : ".conductor/status.json",
+  );
+  const stepId = args.find((a) => !a.startsWith("-"));
+
+  const fail = (msg) => {
+    console.error(`${red("✗ board-sync")} ${msg}`);
+    return false;
+  };
+
+  if (!stepId) return fail("usage: conductor-board check <step-id> [--path status.json]");
+
+  let status;
+  try {
+    status = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+  } catch {
+    return fail(
+      `could not read ${path.relative(process.cwd(), statusPath)} — start the board and write status.json first.`,
+    );
+  }
+
+  const step = status.steps?.[stepId];
+  if (!step) return fail(`status.json has no step "${stepId}". Write the step before gating it.`);
+
+  if (status.current_step !== stepId) {
+    return fail(
+      `current_step is "${status.current_step ?? "—"}", not "${stepId}". Mark this step running on the board before its gate.`,
+    );
+  }
+
+  const beats = Array.isArray(step.heartbeat) ? step.heartbeat : [];
+  if (beats.length === 0) {
+    return fail(`step "${stepId}" has no heartbeats. Heartbeat as you work — the gate can't pass on a silent step.`);
+  }
+
+  const lastAt = beats
+    .map((h) => (h && typeof h.at === "string" ? new Date(h.at).getTime() : NaN))
+    .filter((t) => Number.isFinite(t))
+    .sort((a, b) => b - a)[0];
+  if (!Number.isFinite(lastAt)) {
+    return fail(`step "${stepId}" has heartbeats but none with a valid timestamp.`);
+  }
+  const age = Date.now() - lastAt;
+  if (age > STALE_MS) {
+    return fail(
+      `step "${stepId}" last beat was ${Math.round(age / 60000)}m ago — the board is stale. ` +
+        `Re-sync status.json to reality and restart the step; don't back-fill (that's freeballing).`,
+    );
+  }
+
+  console.log(
+    `${green("✓ board-sync")} "${stepId}" ${dim(
+      `— current, ${beats.length} heartbeat(s), last ${Math.round(age / 1000)}s ago`,
+    )}`,
+  );
+  return true;
+}

package/cli/clean.js

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const amber = (s) => `\x1b[38;5;214m${s}\x1b[0m`;
+
+const flag = (args, names, def) => {
+  for (const n of names) {
+    const i = args.indexOf(n);
+    if (i !== -1) {
+      const v = args[i + 1];
+      return v && !v.startsWith("-") ? v : true;
+    }
+  }
+  return def;
+};
+
+/** Workflow directories under a .conductor root (flat + subdirs). */
+function workflowDirs(root) {
+  const dirs = [];
+  const has = (d) =>
+    fs.existsSync(path.join(d, "status.json")) || fs.existsSync(path.join(d, "history"));
+  if (has(root)) dirs.push(root);
+  try {
+    for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+      if (e.isDirectory() && e.name !== "history") {
+        const d = path.join(root, e.name);
+        if (has(d)) dirs.push(d);
+      }
+    }
+  } catch {
+    /* no root */
+  }
+  return dirs;
+}
+
+/** conductor-board clean [--keep N] [--prune-heartbeats [--keep-beats M]] [--dry-run] */
+export async function runClean(args) {
+  const root = path.resolve(process.cwd(), String(flag(args, ["--dir"], ".conductor")));
+  const keep = Number(flag(args, ["--keep"], 50)) || 50;
+  const keepBeats = Number(flag(args, ["--keep-beats"], 30)) || 30;
+  const pruneBeats = args.includes("--prune-heartbeats");
+  const dry = args.includes("--dry-run");
+
+  const dirs = workflowDirs(root);
+  if (dirs.length === 0) {
+    console.log(dim(`\n  nothing to clean under ${path.relative(process.cwd(), root) || root}\n`));
+    return true;
+  }
+
+  console.log("");
+  if (dry) console.log(amber("  DRY RUN — nothing will be deleted or written.\n"));
+  let runsDeleted = 0;
+  let beatsArchived = 0;
+
+  for (const dir of dirs) {
+    const name = path.basename(dir);
+
+    // 1 — trim history to the last `keep` runs
+    const histDir = path.join(dir, "history");
+    try {
+      const files = fs
+        .readdirSync(histDir)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => ({ f, t: fs.statSync(path.join(histDir, f)).mtimeMs }))
+        .sort((a, b) => b.t - a.t);
+      const old = files.slice(keep);
+      for (const { f } of old) {
+        if (!dry) fs.unlinkSync(path.join(histDir, f));
+        runsDeleted += 1;
+      }
+      if (old.length) console.log(`  ${name}: ${dry ? "would remove" : "removed"} ${old.length} old run(s) (keep ${keep})`);
+    } catch {
+      /* no history */
+    }
+
+    // 2 — prune heartbeats (opt-in), keeping finalBeats + insight beats
+    if (pruneBeats) {
+      const statusPath = path.join(dir, "status.json");
+      try {
+        const status = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+        const overflow = [];
+        for (const [stepId, step] of Object.entries(status.steps || {})) {
+          const hb = Array.isArray(step.heartbeat) ? step.heartbeat : [];
+          const protectedSet = new Set(hb.filter((b) => b.finalBeat || b.insight));
+          const regular = hb.filter((b) => !protectedSet.has(b));
+          if (regular.length <= keepBeats) continue;
+          const drop = new Set(regular.slice(0, regular.length - keepBeats));
+          for (const b of hb) if (drop.has(b)) overflow.push({ step: stepId, ...b });
+          step.heartbeat = hb.filter((b) => !drop.has(b));
+        }
+        if (overflow.length) {
+          beatsArchived += overflow.length;
+          if (!dry) {
+            fs.appendFileSync(
+              path.join(dir, "heartbeat-archive.jsonl"),
+              overflow.map((o) => JSON.stringify(o)).join("\n") + "\n",
+            );
+            fs.writeFileSync(statusPath, JSON.stringify(status, null, 2));
+          }
+          console.log(
+            `  ${name}: ${dry ? "would archive" : "archived"} ${overflow.length} heartbeat(s) (keep ${keepBeats}/step; finalBeats + insights kept)`,
+          );
+        }
+      } catch {
+        /* no status */
+      }
+    }
+  }
+
+  console.log("");
+  console.log(
+    green(
+      `  ${dry ? "would clean" : "cleaned"}: ${runsDeleted} run(s)` +
+        (pruneBeats ? `, ${beatsArchived} heartbeat(s) archived` : ""),
+    ),
+  );
+  console.log("");
+  return true;
+}

package/cli/complete.js

@@ -0,0 +1,139 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import yaml from "js-yaml";
+
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const amber = (s) => `\x1b[38;5;214m${s}\x1b[0m`;
+
+function flag(args, names) {
+  for (const n of names) {
+    const i = args.indexOf(n);
+    if (i !== -1) {
+      const v = args[i + 1];
+      return v && !v.startsWith("-") ? v : true;
+    }
+  }
+  return undefined;
+}
+
+function discoverConductor(statusPath, explicit) {
+  if (explicit) return path.resolve(process.cwd(), explicit);
+  const dir = path.dirname(statusPath);
+  for (const c of ["conductor.yaml", "conductor.yml"]) {
+    const p = path.join(dir, c);
+    if (fs.existsSync(p)) return p;
+  }
+  for (const c of ["conductor.yaml", "conductor.yml"]) {
+    const p = path.resolve(process.cwd(), c);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * conductor-board complete <step-id> [--attest-soft]
+ *
+ * Runs the step's HARD gates independently (the agent can't fake the result),
+ * then — if all hard gates pass and soft gates are attested — marks the step done
+ * with gate_detail tagging each criterion 🔒 verified (CLI ran it) or ✋ attested.
+ */
+export async function runComplete(args) {
+  const p = flag(args, ["--path", "-p"]);
+  const statusPath = path.resolve(process.cwd(), typeof p === "string" ? p : ".conductor/status.json");
+  const stepId = args.find((a) => !a.startsWith("-"));
+  const attestSoft = args.includes("--attest-soft");
+
+  if (!stepId) {
+    console.error(red("usage: conductor-board complete <step-id> [--attest-soft]"));
+    return false;
+  }
+
+  const conductorPath = discoverConductor(statusPath, flag(args, ["--conductor", "-c"]));
+  if (!conductorPath) {
+    console.error(red("✗ no conductor file found next to status.json or in cwd"));
+    return false;
+  }
+  let doc;
+  try {
+    doc = yaml.load(fs.readFileSync(conductorPath, "utf8"));
+  } catch (e) {
+    console.error(red(`✗ could not parse conductor: ${e.message}`));
+    return false;
+  }
+  const step = (doc.steps || []).find((s) => s && s.id === stepId);
+  if (!step) {
+    console.error(red(`✗ conductor has no step "${stepId}"`));
+    return false;
+  }
+
+  const soft = [];
+  const hard = [];
+  for (const g of step.gate || []) {
+    if (typeof g === "string") soft.push(g);
+    else if (g && typeof g.check === "string") hard.push({ name: g.name, check: g.check });
+    else if (g) soft.push(String(g));
+  }
+
+  console.log("");
+  const detail = [];
+  let allHardPass = true;
+
+  if (hard.length) {
+    console.log("  Hard gates:");
+    for (const h of hard) {
+      let passed = false;
+      let exitCode = 1;
+      try {
+        execSync(h.check, { stdio: "ignore", shell: "/bin/sh" });
+        passed = true;
+        exitCode = 0;
+      } catch (e) {
+        exitCode = typeof e.status === "number" ? e.status : 1;
+      }
+      allHardPass = allHardPass && passed;
+      console.log(
+        `    ${passed ? green("🔒 ✓") : red("🔒 ✕")} ${h.name || h.check} ${dim(`(exit ${exitCode})`)}`,
+      );
+      detail.push({ criterion: h.check, name: h.name, kind: "hard", passed, exit_code: exitCode, verified: true });
+    }
+  }
+
+  if (soft.length) {
+    console.log("  Soft gates:");
+    for (const s of soft) {
+      const attested = attestSoft;
+      console.log(`    ${attested ? amber("✋ attested") : dim("✋ not attested")}  "${s}"`);
+      detail.push({ criterion: s, kind: "soft", passed: attested ? true : null, verified: false });
+    }
+  }
+
+  const softOk = soft.length === 0 || attestSoft;
+  const ok = allHardPass && softOk;
+
+  console.log("");
+  if (ok) {
+    try {
+      const status = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+      const st = (status.steps[stepId] = status.steps[stepId] || { attempt: 1 });
+      st.status = "done";
+      st.gate = "passed";
+      st.gate_detail = detail;
+      st.completed_at = new Date().toISOString();
+      fs.writeFileSync(statusPath, JSON.stringify(status, null, 2));
+    } catch (e) {
+      console.error(red(`✗ gates passed but could not update status.json: ${e.message}`));
+      return false;
+    }
+    console.log(green(`  ✅ All gates passed. Step ${stepId} → done.`));
+    console.log("");
+    return true;
+  }
+
+  if (!allHardPass) console.log(red("  ✕ Hard gate(s) failed — fix and retry. Step not advanced."));
+  else console.log(amber("  ✋ Soft gates not attested — re-run with --attest-soft once you've verified them."));
+  console.log("");
+  return false;
+}

package/cli/discover.js

@@ -0,0 +1,42 @@
+import http from "node:http";
+
+/** GET /health on a local port; resolves the parsed health or null. */
+export function getHealth(port, timeout = 400) {
+  return new Promise((resolve) => {
+    const req = http.get(
+      { host: "127.0.0.1", port, path: "/health", timeout },
+      (res) => {
+        let data = "";
+        res.on("data", (c) => (data += c));
+        res.on("end", () => {
+          try {
+            const h = JSON.parse(data);
+            resolve(h && h.status === "ok" ? { port, ...h } : null);
+          } catch {
+            resolve(null);
+          }
+        });
+      },
+    );
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+/** Scan the conductor-board port range for live boards. */
+export async function scanBoards(from = 3042, to = 3099) {
+  const ports = [];
+  for (let p = from; p <= to; p++) ports.push(p);
+  const all = await Promise.all(ports.map((p) => getHealth(p)));
+  return all.filter(Boolean);
+}
+
+export function fmtUptime(s) {
+  if (!Number.isFinite(s)) return "—";
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  return `${h}h ${m}m`;
+}

package/cli/ps.js

@@ -0,0 +1,38 @@
+import { scanBoards, fmtUptime } from "./discover.js";
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const pad = (s, n) => String(s).padEnd(n);
+
+/** List every conductor-board server running on this machine. */
+export async function runPs() {
+  const boards = await scanBoards();
+  console.log("");
+  if (boards.length === 0) {
+    console.log(dim("  No conductor-board servers running."));
+    console.log("");
+    return true;
+  }
+
+  console.log("  " + bold(pad("PID", 7) + pad("PORT", 7) + pad("UPTIME", 10) + pad("MEM", 8) + "WORKFLOWS"));
+  let totalMem = 0;
+  for (const h of boards.sort((a, b) => a.port - b.port)) {
+    totalMem += h.memory_mb || 0;
+    const wfs = Object.entries(h.workflows || {})
+      .map(([n, s]) => `${n} (${s.status})`)
+      .join(", ");
+    console.log(
+      "  " +
+        pad(h.pid ?? "?", 7) +
+        pad(h.port, 7) +
+        pad(fmtUptime(h.uptime_seconds), 10) +
+        pad(`${h.memory_mb ?? "?"} MB`, 8) +
+        (wfs || dim("—")),
+    );
+  }
+  console.log("");
+  console.log(dim(`  ${boards.length} board${boards.length === 1 ? "" : "s"} running, ${totalMem} MB total`));
+  console.log(dim("  stop one with  conductor-board stop  ·  all with  conductor-board stop --all"));
+  console.log("");
+  return true;
+}

package/cli/setup.js

@@ -27,11 +27,14 @@ steps:
 
   - id: start-board
     instruction: |
-      Start the board server in the background. It opens the browser
-      automatically — do NOT pass --no-open here, that defeats the live view.
+      Start the board server ONCE in the background and leave it running for the
+      whole run. It opens the browser automatically — do NOT pass --no-open here,
+      that defeats the live view.
         npx conductor-board >/tmp/conductor-board.log 2>&1 &
       Wait ~3 seconds for it to initialize. It auto-detects a free port if 3042
-      is taken and records the chosen port in .conductor/server.json.
+      is taken and records the chosen port in .conductor/server.json. Do NOT run
+      this command again later — one board per run. Re-running just reuses the
+      live server, but repeatedly launching is how you end up with stray tabs.
     requires: [preflight]
     gate:
       - name: "Server config file exists"
@@ -77,16 +80,27 @@ steps:
       Create .conductor/status.json with all steps pending and a timestamp run_id.
       Set the top-level "goal" from the conductor's description, and refresh
       "current_step_goal" each time current_step changes.
-      Walk each step in order, updating status.json after every step and gate
-      change. Retry on gate failure — never skip.
+      Walk each step in order, updating status.json after EVERY transition
+      (pending -> running -> gate checking -> passed/failed -> done). The human is
+      watching the board to follow along — never do real work without updating the
+      board first. Doing work the board doesn't reflect ("freeballing") is not
+      allowed: if you drift, stop, re-sync the board, restart the step cleanly, and
+      apologize. The board shows a red "Freeballing?" banner after ~3 minutes
+      without a heartbeat. Retry on gate failure — never skip.
       At least once per minute, append a heartbeat {at, note} to the current
       step's heartbeat array (read prior entries first; orient against the gate
       AND the goal; use [text](url) links for any PRs or pages you produce).
+      Before marking each step done, append a finalBeat — {at, note, finalBeat:
+      true, handoff: {to, context, produced}} — summarizing the step and handing
+      off to the next; read the previous step's finalBeat before you start one.
       For loop steps, update "completed" and the "iterations" object as EACH
       iteration finishes — don't wait until the loop ends.
+      At the START of the run, read .conductor/insights.md (if it exists) to carry
+      forward what past runs learned — don't repeat insights already recorded there.
       Tag heartbeats with an "insight" object when you spot a way to improve the
       workflow. Before setting status to "done", review your insight-tagged
-      heartbeats and write 3-5 optimization "suggestions" to status.json.
+      heartbeats and write 3-5 optimization "suggestions" to status.json — the board
+      merges them into the persistent .conductor/insights.md ledger for next time.
       Set the top-level status to "done" when the last step completes.
     requires: [convert-to-conductor]
     gate: