acuvo-code 0.2.0

package/lib/best-of.mjs

@@ -0,0 +1,334 @@
+/**
+ * ── ⭐⭐ BEST-OF-N — COST TURNED INTO CAPABILITY ─────────────────────────────
+ *
+ * Run the same task several times independently, then keep the attempt that
+ * actually PASSED. This is not a trick; it is the one thing our price makes
+ * possible and a competitor's price does not. A run here costs ~$0.001, so
+ * three attempts cost a third of a cent. An agent billing a hundred times that
+ * cannot offer this at all — not because they lack the idea, because the
+ * arithmetic forbids it.
+ *
+ * ── ⚠️⚠️ THE SELECTION MUST NOT BE THE MODEL'S OPINION ─────────────────────
+ *
+ * The obvious design is to generate N answers and ask a model which is best.
+ * That is N chances to be confidently wrong, aggregated by a judge with the
+ * same blind spots — and this codebase has measured exactly that failure: a
+ * critic scored five of six different pages identically, and an agent declared
+ * a page "clean and balanced" that it had never rendered.
+ *
+ * ⭐ SO THE WINNER IS CHOSEN BY WHAT RAN. `sessionFailed()` already encodes the
+ * honest verdict — did the verification command pass, did a declared acceptance
+ * criterion hold. Selection is that verdict first, and taste never.
+ *
+ * ── ⚠️ IT MUST NEVER BE WORSE THAN N=1 ──────────────────────────────────────
+ *
+ * A single run that fails verification still leaves its files on disk; the user
+ * gets something to look at. So when NO attempt verifies, this applies one
+ * anyway and says plainly that none passed. Applying nothing would make asking
+ * for three attempts worse than asking for one, which is the kind of surprise
+ * that makes a feature untrustworthy.
+ */
+
+import { cpSync, mkdtempSync, rmSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+
+import { changedPaths } from './changed-paths.mjs';
+
+/**
+ * ⚠️ THE SAME SKIP SET THE REST OF THE PACKAGE USES. Copying `node_modules` for
+ * each of three attempts turns a 40MB workspace into 1.2GB of I/O on a laptop
+ * that may be on battery — and none of it is read by the agent, which reaches
+ * dependencies through the executor, not by walking them.
+ */
+export const COPY_SKIP_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', '.vercel', 'coverage', '.turbo', '.acuvo',
+]);
+
+export const MIN_ATTEMPTS = 2;
+export const MAX_ATTEMPTS = 5;
+
+/**
+ * ⚠️ A CEILING ON WHAT WILL BE COPIED, because the alternative is discovering
+ * mid-run that a workspace contained a 4GB dataset. Refusing with the number is
+ * a decision the user can act on; silently copying it is a hang they cannot.
+ */
+export const MAX_COPY_BYTES = 256 * 1024 * 1024;
+
+export function measureWorkspace(root, { limit = MAX_COPY_BYTES } = {}) {
+  let bytes = 0;
+  let files = 0;
+  const walk = (dir) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (bytes > limit) return;
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (COPY_SKIP_DIRS.has(e.name)) continue;
+        walk(full);
+      } else if (e.isFile()) {
+        try { bytes += statSync(full).size; files += 1; } catch { /* vanished mid-walk */ }
+      }
+    }
+  };
+  walk(root);
+  return { bytes, files, overLimit: bytes > limit };
+}
+
+/**
+ * Score one finished attempt. Lower is better.
+ *
+ * ⚠️ THE FIRST DIGIT IS THE ONLY ONE THAT DECIDES CORRECTNESS. Rounds and cost
+ * break ties BETWEEN VERIFIED ATTEMPTS — they can never promote a failing
+ * attempt above a passing one, however cheap or fast it was. An agent that
+ * picked the cheapest answer would learn to do nothing.
+ */
+export function scoreAttempt(attempt, { failed }) {
+  if (!attempt || attempt.error) return { rank: 3, why: 'the attempt crashed' };
+  const outcome = attempt.outcome;
+  if (!outcome) return { rank: 3, why: 'the attempt produced no result' };
+
+  const mutations = (outcome.executed ?? []).filter((e) => e?.mutated).length;
+
+  if (!failed(outcome)) {
+    const v = outcome.verification;
+    /**
+     * ── ⚠️⚠️ DOING NOTHING IS NOT SUCCEEDING ─────────────────────────────
+     *
+     * CAUGHT BY A REAL RUN, not by reasoning. An attempt that wrote no files
+     * and ran no verification came back `ok: true`, so `failed()` said false,
+     * so it ranked as a WIN — and then beat the attempt that actually did the
+     * work, because the tie-break prefers fewer rounds and doing nothing takes
+     * the fewest rounds of all.
+     *
+     * ⭐ That is the same trap the cheap-failure test was written to close, one
+     * level deeper: I guarded against a cheap FAILURE outranking an expensive
+     * success and missed that a cheap NO-OP outranks everything. An agent
+     * rewarded for this learns that the optimal move is to do nothing quickly.
+     *
+     * `failed()` cannot see it — a run with no verification is not a run that
+     * failed verification, and that distinction is correct everywhere else.
+     * So the emptiness is judged here, where the alternatives are visible.
+     */
+    if (!v?.ran && mutations === 0) {
+      return {
+        rank: 2,
+        why: 'changed nothing and verified nothing',
+        rounds: outcome.roundsUsed ?? 0,
+        cost: outcome.usage?.cost ?? 0,
+      };
+    }
+    return {
+      rank: 0,
+      why: v?.ran
+        ? `verified: ${v.command} passed`
+        : `changed ${mutations} file${mutations === 1 ? '' : 's'}, nothing left failing`,
+      rounds: outcome.roundsUsed ?? 0,
+      cost: outcome.usage?.cost ?? 0,
+    };
+  }
+
+  // Ran something and it failed — still more informative than never running.
+  if (outcome.verification?.ran) {
+    return { rank: 1, why: `ran ${outcome.verification.command} and it failed`, rounds: outcome.roundsUsed ?? 0, cost: outcome.usage?.cost ?? 0 };
+  }
+  return { rank: 2, why: outcome.stoppedBecause ? `stopped: ${outcome.stoppedBecause}` : 'nothing was verified', rounds: outcome.roundsUsed ?? 0, cost: outcome.usage?.cost ?? 0 };
+}
+
+export function pickWinner(attempts, { failed }) {
+  const scored = attempts.map((a, i) => ({ index: i, attempt: a, score: scoreAttempt(a, { failed }) }));
+  const ordered = [...scored].sort((a, b) => (
+    a.score.rank - b.score.rank
+    || (a.score.rounds ?? 99) - (b.score.rounds ?? 99)
+    || (a.score.cost ?? 0) - (b.score.cost ?? 0)
+    || a.index - b.index
+  ));
+  const winner = ordered[0];
+  return {
+    winner,
+    scored,
+    anyVerified: scored.some((s) => s.score.rank === 0),
+  };
+}
+
+/**
+ * Copy the files an attempt changed back into the real workspace.
+ *
+ * ⚠️ ONLY THE FILES THE ATTEMPT ITSELF REPORTED WRITING. Mirroring the whole
+ * directory would also delete anything the user created while the attempts ran,
+ * and would resurrect files an attempt deliberately deleted in a way the
+ * report never mentioned. The change list is the attempt's own account of what
+ * it did, and applying exactly that keeps the summary and the disk in agreement.
+ */
+export function applyAttempt(fromRoot, toRoot, outcome, { copy = cpSync, remove = rmSync } = {}) {
+  const applied = [];
+  const problems = [];
+  for (const record of outcome?.executed ?? []) {
+    /**
+     * ── ⚠️⚠️ THIS READ `record.args?.path`, AND THAT SILENTLY DROPPED FILES ──
+     *
+     * Measured by reading `write-many.mjs:128`: a `write_files` call carries
+     * `files[]` in its ARGUMENTS and reports `written[{path,…}]` in its
+     * RESULT. There is no top-level `args.path`, so a winning attempt that
+     * created its whole feature in one bulk call had every file skipped
+     * here — and `formatBestOf` still printed "kept attempt 2" over an empty
+     * change list. ⭐ `changedPaths` is now the one place that knows the
+     * shapes, and it also carries a delegated builder's files.
+     */
+    for (const path of changedPaths(record)) {
+      // ⚠️ Refuse anything that climbs out — the attempt ran in a copy, but the
+      // path it reports is still a string from a model.
+      if (path.includes('..') || path.startsWith('/') || path.startsWith('\\') || /^[A-Za-z]:/.test(path)) {
+        problems.push(`refused to apply a path that leaves the workspace: ${path}`);
+        continue;
+      }
+      const src = join(fromRoot, path);
+      const dest = join(toRoot, path);
+      try {
+        if (existsSync(src)) {
+          copy(src, dest, { recursive: true, force: true });
+          applied.push(path);
+        } else if (existsSync(dest)) {
+          // The attempt deleted it. Deleting it here is what "apply" means.
+          remove(dest, { recursive: true, force: true });
+          applied.push(path);
+        }
+      } catch (err) {
+        problems.push(`${path}: ${String(err?.message ?? err)}`);
+      }
+    }
+  }
+  return { applied, problems };
+}
+
+/**
+ * Run one task N times in isolated copies and apply the best result.
+ *
+ * `runOne({ root, label })` must resolve to a SessionDone-shaped outcome.
+ * Injected so this module never imports the turn loop — it is a strategy, not
+ * a second engine.
+ */
+export async function runBestOf({
+  root,
+  attempts = 3,
+  runOne,
+  failed,
+  pool,
+  concurrency = 2,
+  onEvent = () => {},
+  makeTempDir = () => mkdtempSync(join(tmpdir(), 'acuvo-bestof-')),
+  copyDir = cpSync,
+  removeDir = rmSync,
+  /**
+   * ⚠️ INJECTABLE SO THE GUARD CAN BE TESTED AT ALL. With the limit hardcoded,
+   * the only way to exercise the refusal is to actually build a 256MB workspace
+   * in a test — so nobody does, and the one branch that protects a laptop from
+   * copying a dataset three times is the one branch never run.
+   */
+  maxBytes = MAX_COPY_BYTES,
+}) {
+  const n = Math.max(MIN_ATTEMPTS, Math.min(MAX_ATTEMPTS, Number(attempts) || MIN_ATTEMPTS));
+
+  const size = measureWorkspace(root, { limit: maxBytes });
+  if (size.overLimit) {
+    return {
+      ok: false,
+      error: `this workspace holds more than ${Math.round(maxBytes / 1024 / 1024)}MB of files that would have to be copied ${n} times. `
+        + 'Run without --best-of here, or point --dir at the subdirectory the task actually touches.',
+    };
+  }
+
+  const roots = [];
+  try {
+    for (let i = 0; i < n; i += 1) {
+      const dir = makeTempDir();
+      /**
+       * ⚠️ `dereference: false` — a symlink copied as its target silently
+       * doubles a workspace and breaks any code that checks `isSymbolicLink`.
+       */
+      copyDir(root, dir, {
+        recursive: true,
+        dereference: false,
+        force: true,
+        filter: (src) => {
+          const rel = relative(root, src);
+          if (rel === '') return true;
+          return !rel.split(sep).some((part) => COPY_SKIP_DIRS.has(part));
+        },
+      });
+      roots.push(dir);
+    }
+
+    onEvent({ type: 'best-of-start', attempts: n, files: size.files, bytes: size.bytes });
+
+    const jobs = roots.map((dir, i) => () => runOne({ root: dir, label: `attempt ${i + 1}/${n}` })
+      .then((outcome) => ({ outcome }))
+      .catch((err) => ({ error: String(err?.message ?? err) })));
+
+    const results = pool
+      ? await pool(jobs, { concurrency })
+      : await Promise.all(jobs.map((j) => j()));
+
+    const { winner, scored, anyVerified } = pickWinner(results, { failed });
+
+    const { applied, problems } = applyAttempt(roots[winner.index], root, winner.attempt?.outcome, {
+      copy: copyDir,
+      remove: removeDir,
+    });
+
+    return {
+      ok: true,
+      attempts: n,
+      anyVerified,
+      winnerIndex: winner.index,
+      winner: winner.attempt?.outcome ?? null,
+      applied,
+      problems,
+      scored: scored.map((s) => ({
+        index: s.index,
+        rank: s.score.rank,
+        why: s.score.why,
+        rounds: s.score.rounds ?? null,
+        cost: s.score.cost ?? null,
+      })),
+      totalCost: results.reduce((sum, r) => sum + (r?.outcome?.usage?.cost ?? 0), 0),
+    };
+  } finally {
+    // ⚠️ ALWAYS, even when an attempt threw. Three abandoned copies of a
+    // workspace per invocation is how a temp directory becomes a disk problem
+    // nobody connects back to this feature.
+    for (const dir of roots) {
+      try { removeDir(dir, { recursive: true, force: true }); } catch { /* best effort */ }
+    }
+  }
+}
+
+/** Render the outcome for a human. */
+export function formatBestOf(result) {
+  if (!result?.ok) return String(result?.error ?? 'best-of failed');
+  const lines = [];
+  const verifiedCount = result.scored.filter((s) => s.rank === 0).length;
+
+  lines.push(`best of ${result.attempts}: ${verifiedCount} verified, kept attempt ${result.winnerIndex + 1}`);
+  for (const s of result.scored) {
+    const mark = s.index === result.winnerIndex ? '→' : ' ';
+    const cost = s.cost ? ` · $${s.cost.toFixed(4)}` : '';
+    const rounds = s.rounds ? ` · ${s.rounds}r` : '';
+    lines.push(`${mark} attempt ${s.index + 1}: ${s.why}${rounds}${cost}`);
+  }
+
+  /**
+   * ⚠️ THE ALL-FAILED CASE SAYS SO IN THOSE WORDS. "kept attempt 2" on its own
+   * reads like a success, and a user who asked for three attempts precisely
+   * because the task was hard is the last person who should have to infer that
+   * none of them worked.
+   */
+  if (!result.anyVerified) {
+    lines.push('⚠ NONE of the attempts verified. The files from the least-bad one were applied so you have something to look at, but nothing here is proven.');
+  }
+  if (result.applied.length > 0) lines.push(`applied ${result.applied.length} file${result.applied.length === 1 ? '' : 's'} from the winner`);
+  for (const p of result.problems) lines.push(`⚠ ${p}`);
+  lines.push(`total spend across all attempts: $${result.totalCost.toFixed(4)}`);
+  return lines.join('\n');
+}

package/lib/board.mjs

@@ -0,0 +1,232 @@
+/**
+ * ── ⭐⭐ THE TASK BOARD — SEVEN TERMINALS, SEVEN JOBS, NOBODY DOING THE SAME ONE ─
+ *
+ * The stated direction for this tool is *"open seven terminals and have seven AI
+ * workers building your software in the same brain, and they are cheap"*. Nearly
+ * all of that already worked and was measured: seven terminals run today, they
+ * are $0.001–0.003 a task, `lease.mjs` stops two of them writing one file,
+ * `auto-lease.mjs` made that automatic, `fleet-budget.mjs` caps the whole
+ * workspace for the day, and the plan ledger is now per worker.
+ *
+ * The one missing piece was never a lock. It is that **nothing said what the
+ * work WAS**. Seven terminals meant seven people typing seven prompts, and
+ * nothing stopped two of them typing the same one.
+ *
+ * ── ⭐⭐ AND THE DESIGN IS: THERE IS NO NEW LOCKING HERE ─────────────────────
+ *
+ * A task board looks like it needs a queue with a mutex. It does not, and the
+ * reason is worth stating because it is the whole reason this file is short:
+ *
+ *     a task IS a file, and claiming one IS taking a lease on that file.
+ *
+ * `.acuvo/board/<id>.json` is a real path inside the workspace, so
+ * `lease.mjs` — 786 lines of proven, raced-by-eight-real-processes,
+ * TTL-reclaiming, takeover-capped exclusive claim — works on it UNMODIFIED.
+ * Measured before this file was written: a lease on `.acuvo/board/t3.json` is
+ * granted, a second terminal is refused with `heldBy`, and `acuvo leases`
+ * already renders it. Nothing here re-invents any of that.
+ *
+ * ⭐ Which also means every property already argued for leases comes free: a
+ * worker that dies mid-task has its claim reclaimed after the TTL rather than
+ * blocking the board forever, and `acuvo leases` is already the answer to "who
+ * is doing what".
+ *
+ * ── ⚠️ WHAT THIS DELIBERATELY IS NOT ────────────────────────────────────────
+ *
+ * There are no `board_*` TOOLS. The model cannot add, claim or complete a task,
+ * and that is a decision rather than an omission: agent-callable claiming is a
+ * second unproven behaviour riding on a board that has not yet been used once.
+ * The workflow that actually exists is a person opening seven windows and
+ * typing, so the board is a CLI surface for that person. Give it a week of real
+ * use before letting the thing being scheduled do the scheduling.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { resolveInWorkspace } from './workspace.mjs';
+import { acquire, release, inspect } from './lease.mjs';
+
+export const BOARD_DIR = '.acuvo/board';
+/** A task longer than this is a project, and a project is not a board entry. */
+export const MAX_TASK_CHARS = 400;
+/** Enough for any real fleet; a bound so a runaway script cannot fill a disk. */
+export const MAX_TASKS = 200;
+
+const nowIso = () => new Date().toISOString();
+
+/**
+ * ⚠️ SORTABLE AND COLLISION-RESISTANT, in that order of importance. Two
+ * terminals can add a task in the same millisecond, so the timestamp alone is
+ * not an id — but the timestamp PREFIX is what makes `readdirSync` return the
+ * board in the order it was written without anybody sorting by a parsed field.
+ */
+function newId(clock = Date.now, rand = () => Math.random()) {
+  const stamp = new Date(clock()).toISOString().replace(/[-:.TZ]/g, '').slice(0, 14);
+  const salt = Math.floor(rand() * 46_656).toString(36).padStart(3, '0');
+  return `${stamp}-${salt}`;
+}
+
+function boardPathFor(root, id) {
+  return resolveInWorkspace(root, `${BOARD_DIR}/${id}.json`, 'write');
+}
+
+/**
+ * Add one task. Returns the id, which is what a person needs to talk about it.
+ */
+export function boardAdd(root, text, { clock = Date.now, rand = () => Math.random() } = {}) {
+  const task = String(text ?? '').trim().replace(/\s+/g, ' ');
+  if (!task) return { ok: false, error: 'a board task needs some text — an empty one cannot be picked up' };
+  if (task.length > MAX_TASK_CHARS) {
+    return { ok: false, error: `that task is ${task.length} characters, over the ${MAX_TASK_CHARS} limit. Put the detail in the repo, not on the board.` };
+  }
+
+  const existing = boardList(root);
+  if (existing.ok && existing.tasks.length >= MAX_TASKS) {
+    return { ok: false, error: `the board already holds ${existing.tasks.length} tasks (limit ${MAX_TASKS}) — finish or remove some before adding more` };
+  }
+
+  const id = newId(clock, rand);
+  const target = boardPathFor(root, id);
+  if (!target.ok) return { ok: false, error: target.reason };
+
+  try {
+    mkdirSync(join(root, BOARD_DIR), { recursive: true });
+    /**
+     * ⚠️ `wx` — EXCLUSIVE CREATE. Two terminals adding in the same millisecond
+     * would otherwise silently overwrite one another's task, and a board that
+     * loses work is worse than no board. The id has a random salt, so a
+     * collision is already unlikely; refusing outright is what makes it
+     * impossible rather than unlikely.
+     */
+    writeFileSync(target.absolute, `${JSON.stringify({ id, task, addedAt: nowIso(), state: 'todo' }, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+  } catch (err) {
+    return { ok: false, error: `could not add the task: ${err?.message ?? err}` };
+  }
+  return { ok: true, id, task };
+}
+
+/** Every task, with who holds it, oldest first. */
+export function boardList(root) {
+  const dir = join(root, BOARD_DIR);
+  if (!existsSync(dir)) return { ok: true, tasks: [] };
+
+  let names;
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith('.json')).sort();
+  } catch (err) {
+    return { ok: false, error: `could not read the board: ${err?.message ?? err}`, tasks: [] };
+  }
+
+  /**
+   * ⭐ WHO HOLDS WHAT COMES FROM `lease.mjs`, NOT FROM THE TASK FILE. A holder
+   * written into the task itself would be a second copy of a fact the lease
+   * layer already owns — and it would go stale the moment a worker died,
+   * because a dead process cannot come back to correct its own file. The lease
+   * expires on its own; a field would not.
+   */
+  const held = new Map();
+  try {
+    for (const l of inspect(root)?.leases ?? []) held.set(l.path, l);
+  } catch { /* an unreadable lease dir means we cannot say who holds what, not that the board is gone */ }
+
+  const tasks = [];
+  for (const name of names) {
+    let rec;
+    try {
+      rec = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+    } catch {
+      // ⚠️ Counted, not skipped silently — a task nobody can read is still work
+      // somebody wrote down, and pretending it is absent is how it gets lost.
+      tasks.push({ id: name.replace(/\.json$/, ''), task: '(unreadable — the file is not valid JSON)', state: 'damaged', heldBy: null });
+      continue;
+    }
+    const lease = held.get(`${BOARD_DIR}/${rec.id}.json`);
+    tasks.push({ ...rec, heldBy: lease?.holder ?? null, heldSince: lease?.acquiredAt ?? null });
+  }
+  return { ok: true, tasks };
+}
+
+/**
+ * Claim the oldest task nobody else holds.
+ *
+ * ⚠️ THE LEASE IS THE CLAIM, AND THE RACE IS ALREADY SOLVED. Two terminals
+ * calling this in the same instant both see the same "first free" task; exactly
+ * one wins the `acquire`, and the loser simply moves to the next one. That is
+ * `lease.mjs`'s exclusive-create doing the work, which is precisely why this
+ * function has no lock of its own.
+ */
+export function boardClaim(root, { holder, ttlMs, acquireImpl = acquire } = {}) {
+  const who = String(holder ?? '').trim();
+  if (!who) return { ok: false, error: 'claiming a task needs a --holder, so the board can say who is doing what' };
+
+  const listed = boardList(root);
+  if (!listed.ok) return listed;
+
+  const open = listed.tasks.filter((t) => t.state === 'todo' && !t.heldBy);
+  if (open.length === 0) {
+    const total = listed.tasks.length;
+    return {
+      ok: false,
+      empty: true,
+      error: total === 0
+        ? `the board is empty — add work with \`acuvo board add "…"\``
+        : `every task on the board is either done or already held by another terminal (${total} total). \`acuvo board\` shows who has what.`,
+    };
+  }
+
+  for (const t of open) {
+    const got = acquireImpl(root, { path: `${BOARD_DIR}/${t.id}.json`, holder: who, pid: process.pid, ...(ttlMs ? { ttlMs } : {}) });
+    if (got?.ok) return { ok: true, id: t.id, task: t.task, lease: got.lease };
+    // Somebody won it between the list and the acquire. Try the next one —
+    // that is the race resolving itself, not an error worth reporting.
+  }
+  return { ok: false, empty: true, error: 'every open task was claimed by another terminal while this one was looking' };
+}
+
+/** Mark a task finished and let go of it. */
+export function boardDone(root, id, { lease = null, releaseImpl = release } = {}) {
+  const target = boardPathFor(root, String(id ?? '').trim());
+  if (!target.ok) return { ok: false, error: target.reason };
+  if (!existsSync(target.absolute)) return { ok: false, error: `no task on the board has the id "${id}"` };
+
+  let rec;
+  try {
+    rec = JSON.parse(readFileSync(target.absolute, 'utf8'));
+  } catch (err) {
+    return { ok: false, error: `that task file could not be read: ${err?.message ?? err}` };
+  }
+  try {
+    writeFileSync(target.absolute, `${JSON.stringify({ ...rec, state: 'done', doneAt: nowIso() }, null, 2)}\n`, 'utf8');
+  } catch (err) {
+    return { ok: false, error: `could not mark the task done: ${err?.message ?? err}` };
+  }
+  if (lease) { try { releaseImpl(lease); } catch { /* the TTL clears it */ } }
+  return { ok: true, id: rec.id, task: rec.task };
+}
+
+/** The human view. Same shape as every other report in this package. */
+export function formatBoard(listed) {
+  if (!listed?.ok) return `board: ${listed?.error ?? 'unavailable'}`;
+  if (listed.tasks.length === 0) {
+    return 'The board is empty.\n\n  Add work with:  acuvo board add "make the failing suite pass"\n  Then claim it:  acuvo --holder t1 --claim';
+  }
+  const lines = [];
+  const todo = listed.tasks.filter((t) => t.state === 'todo');
+  const done = listed.tasks.filter((t) => t.state === 'done');
+  lines.push(`${listed.tasks.length} task${listed.tasks.length === 1 ? '' : 's'} — ${todo.filter((t) => !t.heldBy).length} open, ${todo.filter((t) => t.heldBy).length} in progress, ${done.length} done`);
+  lines.push('');
+  for (const t of listed.tasks) {
+    const mark = t.state === 'done' ? '✔' : t.heldBy ? '▶' : '·';
+    /**
+     * ⚠️ A FINISHED TASK SHOWS NO HOLDER. Its lease often outlives it — a
+     * worker that finished and exited without releasing leaves the record until
+     * the TTL clears it — and "✔ done ← t1" reads as *t1 is working on this*,
+     * which is the opposite of what it means. The holder is only interesting
+     * while the work is in flight.
+     */
+    const who = t.heldBy && t.state !== 'done' ? `  ← ${t.heldBy}` : '';
+    lines.push(`  ${mark} ${t.id}  ${t.task}${who}`);
+  }
+  return lines.join('\n');
+}

package/lib/breaker.mjs

@@ -0,0 +1,93 @@
+/**
+ * ── ⚠️⭐ ONE DEAD SERVICE MUST NOT EAT THE WHOLE SESSION ─────────────────────
+ *
+ * Measured 2026-08-10 on a real multi-page website build. `generate_image` was
+ * unreachable. Each attempt waited the full 180-second timeout; the model tried
+ * twice in one round, then — following our own error text, which said "try once
+ * more" — retried in the next. Six minutes of a run spent on a service that was
+ * never going to answer, and the user saw a session that appeared to hang and
+ * produced nothing.
+ *
+ * ⭐ THE ASYMMETRY IS THE WHOLE ARGUMENT. Being wrong about a service being dead
+ * costs one missing image. Being wrong about it being alive costs three minutes
+ * PER ATTEMPT out of a budget measured in minutes. So: one unreachable answer,
+ * and this endpoint is dead for the rest of the process.
+ *
+ * ⚠️ IT TRIPS ON UNREACHABLE, NEVER ON A REFUSAL. An HTTP 400 means the request
+ * was wrong and the next one may well be right — tripping on that would disable
+ * a working service because the model sent a bad prompt once. Only "no response"
+ * counts: a timeout, a DNS failure, a refused connection.
+ *
+ * ⚠️ AND IT IS PER-PROCESS, DELIBERATELY. A CLI run is minutes long, so there is
+ * no half-life worth modelling and no reason to make a dead service recoverable
+ * mid-run — the next invocation gets a clean slate for free, which is exactly
+ * the retry policy a human would apply.
+ */
+
+/** endpoint URL → the reason it was declared dead. */
+const dead = new Map();
+
+/** Reset between tests. Never called in normal operation — a run is short. */
+export function resetBreakers() {
+  dead.clear();
+}
+
+/**
+ * Is this endpoint already known to be unreachable this run?
+ * Returns the recorded reason, or null.
+ */
+export function deadReason(url) {
+  return dead.get(String(url)) ?? null;
+}
+
+/**
+ * Record that an endpoint did not answer.
+ *
+ * ⚠️ The CALLER decides whether the failure was "no response" or merely "no",
+ * because only the caller can tell an AbortError apart from an HTTP 422. Passing
+ * an application-level refusal here would be the bug this module exists to
+ * avoid.
+ */
+export function markUnreachable(url, reason) {
+  dead.set(String(url), String(reason ?? 'no response'));
+}
+
+/**
+ * The message a later caller gets. It must NOT invite another attempt.
+ *
+ * ⚠️ THE ORIGINAL TEXT SAID "try once more" AND THE MODEL DID, twice. An error
+ * string is an instruction to whatever reads it, and a model reads it literally.
+ * This one closes the door and names the alternative, so the round is spent on
+ * work instead of on waiting.
+ */
+export function skipMessage(label, url) {
+  const why = deadReason(url);
+  return `${label} is not responding this session (${why}). Skipping it rather than waiting again — `
+    + 'earlier attempts already spent the full timeout. Carry on without it and say so in your summary; '
+    + 'do not call this tool again in this run.';
+}
+
+/**
+ * Wrap a fetch so the breaker is consulted first and tripped on a network-level
+ * failure. Returns `{ ok: false, skipped: true, error }` when already dead.
+ *
+ * ⭐ Kept as a wrapper rather than a rule each call site reimplements: the two
+ * existing callers already disagreed about what an unreachable service should
+ * say, which is how "try once more" survived in one of them.
+ */
+export async function throughBreaker(url, label, run) {
+  const already = deadReason(url);
+  if (already) return { ok: false, skipped: true, error: skipMessage(label, url) };
+  try {
+    return await run();
+  } catch (err) {
+    const networkLevel = err?.name === 'TimeoutError'
+      || err?.name === 'AbortError'
+      || Boolean(err?.cause?.code);
+    if (networkLevel) {
+      const why = err?.name === 'TimeoutError' ? 'timed out' : (err?.cause?.code ?? err?.name ?? 'no response');
+      markUnreachable(url, why);
+    }
+    throw err;
+  }
+}