@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/sequence.js

@@ -0,0 +1,597 @@
+#!/usr/bin/env node
+// /builder-sequence — walk a dependency chain end to end from one kickoff.
+//
+// Two-thirds of the open backlog is dependency-gated. Shipping a task
+// auto-promotes its dependents backlog→ready (the promote_dependents_on_ship
+// trigger, migrations 020/163) — but nothing picks the newly-unblocked task
+// up, so an N-task chain needs N separate kickoffs. This is the plumbing that
+// lets one session walk the whole chain: resolve scope → next → claim → build
+// → ship → next.
+//
+// Calling forms:
+//   node scripts/bongos/sequence.js --from 1002277          plan the chain below a task
+//   node scripts/bongos/sequence.js --goal 1000045          plan a goal's open tasks
+//   node scripts/bongos/sequence.js --from 1002277 --next   the one task to claim now
+//   node scripts/bongos/sequence.js --check 1002277         stop-reasons for one task
+//
+// Flags:
+//   --next         emit only the next claimable task (or a named stop reason)
+//   --check <id>   evaluate the halt matrix for one task
+//   --json         machine-readable output
+//   --limit N      cap the planned chain at N tasks (default 50)
+//
+// This script DECIDES NOTHING it cannot decide from facts. Every halt is a
+// named reason a human can act on — see HALT_REASONS. The judgement half of
+// the loop (actually building each task) lives in .claude/skills/builder-sequence.
+
+const { cliClient, requireSession, fmtMinutes, hallBase } = require('./cli-lib');
+const { matchProtected } = require('../../src/bongos/permission-path-check');
+
+// Rank → tier, mirroring REQUIRES_RANK_TIER. Imported shape would drag the
+// server's db.js (and its pool) into a CLI that only needs four integers.
+const RANK_TIER = { xenos: 1, thetes: 2, metic: 3, archon: 4 };
+
+// A task in one of these statuses is done as far as the chain is concerned —
+// 'completed'/'confirmed' are mid-ship states, so the chain must not re-claim
+// them, but they are also not yet 'shipped' so successors stay gated. The set
+// itself comes from the lifecycle's one declaration (task 1003588); that file
+// requires nothing, so reading it costs this CLI no server pool.
+const { TERMINAL_STATUS_SET: TERMINAL } = require('../../modules/lifecycle/task-status');
+const IN_FLIGHT = new Set(['active', 'completed', 'confirmed']);
+
+const DEFAULT_LIMIT = 50;
+
+// A description shorter than this can't carry acceptance criteria worth
+// verifying against, so the runner refuses to guess at what "done" means.
+const MIN_SPEC_CHARS = 120;
+
+// Kinds whose whole point is a judgement call the owner should see before it
+// lands: a decision needs an ADR, a spike's output is a recommendation.
+const JUDGEMENT_KINDS = new Set(['decision', 'spike']);
+
+const HALT_REASONS = {
+  needs_migration: 'wants a schema migration — needs a reserved number and human eyes',
+  security_sensitive: 'flagged security-sensitive',
+  protected_path: 'touches the permission/deploy core',
+  rank_floor: 'requires a rank above yours',
+  thin_spec: 'has no acceptance criteria to verify against',
+  judgement_kind: 'is a judgement call (decision/spike), not mechanical work',
+  not_claimable: 'is ready but the server will not hand it over',
+  deps_unmet: 'is still waiting on a predecessor',
+  in_flight: 'is already mid-ship',
+  cycle: 'sits in a dependency cycle',
+  chain_complete: 'nothing left in this chain',
+};
+
+// -------------------------------------------------------------------------
+// Argv
+// -------------------------------------------------------------------------
+
+function readArgv(argv) {
+  const out = { from: null, goal: null, check: null, next: false, json: false, limit: DEFAULT_LIMIT };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--next') { out.next = true; continue; }
+    if (a === '--json') { out.json = true; continue; }
+    if (a === '--from') { out.from = Number(argv[++i]); continue; }
+    if (a.startsWith('--from=')) { out.from = Number(a.slice(7)); continue; }
+    if (a === '--goal') { out.goal = Number(argv[++i]); continue; }
+    if (a.startsWith('--goal=')) { out.goal = Number(a.slice(7)); continue; }
+    if (a === '--check') { out.check = Number(argv[++i]); continue; }
+    if (a.startsWith('--check=')) { out.check = Number(a.slice(8)); continue; }
+    if (a === '--limit') { out.limit = Number(argv[++i]); continue; }
+    if (a.startsWith('--limit=')) { out.limit = Number(a.slice(8)); continue; }
+    if (!out.from && /^\d+$/.test(a)) { out.from = Number(a); continue; }
+  }
+  return out;
+}
+
+// -------------------------------------------------------------------------
+// Pure core (exported for tests)
+// -------------------------------------------------------------------------
+
+// Ids a task object points at, tolerating both the bare-number and the
+// {id,kind} row shapes GET /tasks/:id has returned across schema versions.
+// Ids must come out positive: Number(null) is 0, so a null edge would
+// otherwise enter the graph as task 0 and be chased as a real dependency.
+function edgeIds(list) {
+  return (list || [])
+    .map((d) => Number(d && typeof d === 'object' ? d.id : d))
+    .filter((n) => Number.isFinite(n) && n > 0);
+}
+
+// Kahn's algorithm over edges BETWEEN the given tasks. An out-of-scope
+// dependency doesn't block ordering the scope itself — it surfaces later as a
+// deps_unmet halt, which is the honest place for it. Ties break on the same
+// keys the claimable feed sorts by, so a plan reads in the order the board
+// would have offered the work.
+function topoOrder(tasks) {
+  const inScope = new Set(tasks.map((t) => Number(t.id)));
+  const byId = new Map(tasks.map((t) => [Number(t.id), t]));
+  const remaining = new Set(inScope);
+  const order = [];
+
+  const rank = (id) => {
+    const t = byId.get(id);
+    return [
+      t.priority == null ? 99 : Number(t.priority),
+      Number(t.est_minutes_calibrated ?? t.est_minutes ?? 0) || 0,
+      Number(t.id),
+    ];
+  };
+  const cmp = (a, b) => {
+    const [pa, ma, ia] = rank(a);
+    const [pb, mb, ib] = rank(b);
+    return pa - pb || ma - mb || ia - ib;
+  };
+
+  let progressed = true;
+  while (remaining.size && progressed) {
+    progressed = false;
+    const free = Array.from(remaining).filter((id) => {
+      const deps = edgeIds(byId.get(id).dependencies).filter((d) => remaining.has(d));
+      return deps.length === 0;
+    });
+    if (free.length === 0) break;
+    free.sort(cmp);
+    for (const id of free) {
+      order.push(byId.get(id));
+      remaining.delete(id);
+      progressed = true;
+    }
+  }
+
+  return { order, cycle: Array.from(remaining).sort((a, b) => a - b) };
+}
+
+// The chain below a head: the head plus every task transitively reachable
+// through dependents[]. Terminal tasks are walked THROUGH (a shipped task's
+// successors are exactly what we want) but not included in the plan.
+function chainFrom(headId, byId, { limit = DEFAULT_LIMIT } = {}) {
+  const seen = new Set();
+  const picked = [];
+  const queue = [Number(headId)];
+  while (queue.length) {
+    const id = queue.shift();
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const t = byId.get(id);
+    if (!t) continue;
+    if (!TERMINAL.has(t.status)) picked.push(t);
+    for (const d of edgeIds(t.dependents)) queue.push(d);
+    if (picked.length >= limit) break;
+  }
+  return picked;
+}
+
+// Does the task's OWN declared file surface rule a schema change out? (task 1003699)
+//
+// tasks.needs_migration is set server-side from a keyword scan of the title and
+// description (migration 081; detectsMigration in
+// modules/lifecycle/routes/task-route-helpers.js), so the flag means "this task
+// SAYS the word migration", not "this task changes the schema". Task 1003697
+// carried it while its description said, in capitals, not to change any
+// migration; the row for THIS task is flagged too, for the same reason. A false
+// halt is not free — it is a task the runner will never offer.
+//
+// So the flag alone no longer halts. It is overridden only by positive evidence
+// pointing the other way: a NON-EMPTY touches[] that names no path under
+// migrations/. That is the author stating the file surface and leaving
+// migrations/ out of it.
+//
+// The asymmetry is deliberate. An absent or empty touches[] tells us nothing, so
+// it keeps halting — and it must, because the rank floor cannot be leaned on
+// here: task 1003697 sat at requires_rank 'xenos' with the flag set, so ADR
+// 0270's needs_migration→floor coupling did not raise it and would not have
+// caught a real schema change either.
+//
+// Note this is NARROWER than what the task proposed. "touches[] hitting
+// migrations/, or a declared migration number" would have re-read the prose, and
+// 1003697's description contains a literal migrations/… path while its touches[]
+// contains none — so the number/path branch would have preserved the very false
+// halt the task was filed to remove, and failed its own acceptance criterion.
+// touches[] is the only signal here that is structural rather than vocabulary.
+// A `migrations` DIRECTORY anywhere in the path, not only at the repo root.
+// This codebase ships MODULE-OWNED schema migrations at
+// modules/<key>/migrations/NNN_*.sql (ADR 0083; docs/modules-contract.md §
+// "Module-owned migrations"), and ten such directories exist today — so an
+// anchored /^migrations\//  test would have called every one of them "not a
+// migration" and suppressed the halt on a real schema change.
+//
+// That mistake would have been worse than the bug this task fixes, because
+// nothing else catches it: permission-path-check's protected-surfaces registry
+// carries a `migrations/` glob that IS a second gate for root migrations, but it
+// is root-anchored too, so a module-owned migration has no other halt at all.
+//
+// Matching a whole path SEGMENT is what keeps docs/migrations-guide.md — a file
+// with the word in its name and no migrations directory — from counting.
+const MIGRATION_DIR_RE = /(?:^|\/)migrations\//i;
+
+function declaredSurfaceExcludesMigrations(task) {
+  const touches = Array.isArray(task.touches) ? task.touches : [];
+  if (!touches.length) return false;
+  return !touches.some((raw) => MIGRATION_DIR_RE.test(String(raw).trim().replace(/\\/g, '/')));
+}
+
+// The halt matrix. Facts only — every entry is something the runner can read
+// off the task row, never a judgement about the work itself.
+function haltReasons(task, { rank, claimableIds = null } = {}) {
+  const reasons = [];
+  if (!task) return [{ code: 'not_found', detail: 'no such task' }];
+
+  if (task.needs_migration && !declaredSurfaceExcludesMigrations(task)) {
+    reasons.push({ code: 'needs_migration', detail: HALT_REASONS.needs_migration });
+  }
+  if (task.security_sensitive) {
+    reasons.push({ code: 'security_sensitive', detail: HALT_REASONS.security_sensitive });
+  }
+
+  const hits = matchProtected(task.touches || []);
+  if (hits.length) {
+    reasons.push({
+      code: 'protected_path',
+      detail: `${HALT_REASONS.protected_path} (${hits.map((h) => h.glob).join(', ')})`,
+    });
+  }
+
+  const floor = RANK_TIER[task.requires_rank] ?? 0;
+  const mine = RANK_TIER[rank] ?? 0;
+  if (floor > mine) {
+    reasons.push({
+      code: 'rank_floor',
+      detail: `needs rank '${task.requires_rank}', you are '${rank || 'unknown'}'`,
+    });
+  }
+
+  if (JUDGEMENT_KINDS.has(task.kind)) {
+    reasons.push({ code: 'judgement_kind', detail: `kind '${task.kind}' ${HALT_REASONS.judgement_kind}` });
+  }
+
+  const spec = String(task.description || '').trim();
+  if (spec.length < MIN_SPEC_CHARS) {
+    reasons.push({
+      code: 'thin_spec',
+      detail: spec ? `description is ${spec.length} chars — too thin to verify against` : 'no description',
+    });
+  }
+
+  if (IN_FLIGHT.has(task.status)) {
+    reasons.push({ code: 'in_flight', detail: `status is '${task.status}'` });
+  } else if (task.status !== 'ready') {
+    reasons.push({ code: 'deps_unmet', detail: `status is '${task.status}', not 'ready'` });
+  } else if (claimableIds && !claimableIds.has(Number(task.id))) {
+    // 'ready' but absent from the server's own claimable feed means an open
+    // blocker, a touches collision with a live claim, or a rank filter. Rather
+    // than re-deriving that query client-side (and drifting from it), defer.
+    reasons.push({ code: 'not_claimable', detail: HALT_REASONS.not_claimable });
+  }
+
+  return reasons;
+}
+
+// Walk the plan in order and return the first task that clears the halt matrix,
+// plus the ones passed over on the way.
+//
+// Topological order is a DEPENDENCY ordering, not a runnability ordering: a
+// blocked task that sorts first used to hide every independent ready task
+// behind it, so --next reported "nothing runnable" on a goal with claimable
+// work (reproduced 2026-08-05 on goal 1000030 — a backlog perf task sat at
+// position 0 while two ready tasks sat at 1 and 2). Scanning past it does NOT
+// weaken any gate: a task is still only offered if it clears haltReasons() on
+// its own, and deps are part of that (an unmet dep leaves status != 'ready').
+//
+// Skipping is never silent — the caller reports `skipped` — because "here is
+// task 3" without "1 and 2 need a human" would quietly bury work.
+function pickNext(plan, { rank, claimableIds = null } = {}) {
+  const skipped = [];
+  for (const task of plan) {
+    const reasons = haltReasons(task, { rank, claimableIds });
+    if (!reasons.length) return { next: task, skipped };
+    skipped.push({ id: task.id, title: task.title, reasons });
+  }
+  // Nothing in the plan clears. The head's reasons are the ones worth printing
+  // (it is the task the chain actually wants next); the rest become the count.
+  return { next: null, skipped, head: plan[0] || null };
+}
+
+function summarize(tasks) {
+  return tasks.reduce(
+    (acc, t) => ({
+      count: acc.count + 1,
+      credits: acc.credits + (Number(t.credits_reward) || 0),
+      minutes: acc.minutes + (Number(t.est_minutes_calibrated ?? t.est_minutes) || 0),
+    }),
+    { count: 0, credits: 0, minutes: 0 },
+  );
+}
+
+// -------------------------------------------------------------------------
+// Fetching
+// -------------------------------------------------------------------------
+
+async function fetchTask(api, id) {
+  const r = await api.tasks.getTasksId({ id });
+  if (!r.ok) return null;
+  return r.data.task || r.data;
+}
+
+// Breadth-first over dependents[], fetching each task's detail once. The list
+// endpoint omits the edge arrays, so the detail route is the only source.
+async function fetchChain(api, headId, limit) {
+  const byId = new Map();
+  const queue = [Number(headId)];
+  const seen = new Set();
+  while (queue.length && byId.size < limit * 4) {
+    const wave = queue.splice(0, 12).filter((id) => !seen.has(id));
+    wave.forEach((id) => seen.add(id));
+    if (!wave.length) continue;
+    const rows = await Promise.all(wave.map((id) => fetchTask(api, id)));
+    for (const t of rows) {
+      if (!t) continue;
+      byId.set(Number(t.id), t);
+      for (const d of edgeIds(t.dependents)) if (!seen.has(d)) queue.push(d);
+    }
+  }
+  return byId;
+}
+
+// GOAL_PAGE is deliberately below the route's limit cap (1000): the cap is what
+// made the old single read look complete, and paging in smaller bites means the
+// "did I get everything?" question is answered by a short last page rather than
+// by trusting one number. GOAL_MAX_ROWS is a runaway guard, not a window — it is
+// far above any real goal, and hitting it throws rather than truncating.
+const GOAL_PAGE = 500;
+const GOAL_MAX_ROWS = 20000;
+
+// Every task row in one goal, paged until the server runs out (task 1003699).
+//
+// THE BUG THIS REPLACES. The old body asked for `?limit=1000` with NO goal
+// filter and matched goal_id in JS. Past a thousand rows in that ordering — this
+// instance crossed it long ago — a task in the goal simply fell outside the
+// window, and the planner printed "No open tasks in goal N". That is
+// indistinguishable from a finished chain, which is the dangerous part: the
+// runner concludes the goal is DONE and stops. Raising the limit only moves the
+// cliff, so the fix is to filter server-side (?goal_id=, ADR 0086 §3) and page.
+//
+// ANY unreadable page throws, for the same reason the bug was invisible: "I
+// could not look" and "there is nothing left" must never render as the same
+// sentence — and a dropped middle page would say the second while meaning the
+// first.
+async function fetchGoalTaskRows(api, goalId) {
+  const rows = [];
+  for (let offset = 0; ; offset += GOAL_PAGE) {
+    const query = { goal_id: Number(goalId), limit: GOAL_PAGE };
+    // The route rejects offset=0 as "must be a positive integer", so page one
+    // sends no offset at all.
+    if (offset) query.offset = offset;
+    const r = await api.tasks.getTasks({ query });
+    if (!r.ok) {
+      // ANY failed page throws, not just the first. Returning the rows read so
+      // far would hand back a short list that looks like a complete goal — the
+      // same "silent incompleteness reads as done" mistake this task exists to
+      // remove, just relocated from a fixed window to a transient failure. A
+      // caller that wants partial data can ask again; one that is told nothing
+      // cannot know to.
+      throw new Error(
+        `could not read the tasks in goal ${goalId} at offset ${offset} `
+        + `(HTTP ${r.status || '?'}) — refusing to report a partial goal as a complete one`,
+      );
+    }
+    const page = rowsOf(r.data) || [];
+    rows.push(...page);
+    if (page.length < GOAL_PAGE) break;
+    if (rows.length >= GOAL_MAX_ROWS) {
+      throw new Error(`goal ${goalId} returned ${rows.length}+ rows — refusing to page further`);
+    }
+  }
+  return rows;
+}
+
+async function fetchGoalTasks(api, goalId, limit) {
+  const rows = await fetchGoalTaskRows(api, goalId);
+  // The goal_id match stays even though the server filtered: a core pinned older
+  // than ADR 0086 §3 ignores an unknown query param instead of rejecting it, so
+  // without this line an un-upgraded instance would silently hand back the whole
+  // table and the planner would plan someone else's goal.
+  const mine = rows
+    .filter((t) => Number(t.goal_id) === Number(goalId) && !TERMINAL.has(t.status))
+    .slice(0, limit);
+  const byId = new Map();
+  for (let i = 0; i < mine.length; i += 12) {
+    const rowsD = await Promise.all(mine.slice(i, i + 12).map((t) => fetchTask(api, t.id)));
+    rowsD.forEach((t) => t && byId.set(Number(t.id), t));
+  }
+  return byId;
+}
+
+// GET /tasks/claimable returns its rows under `claimable`; GET /tasks under
+// `tasks`. Returning null (not an empty Set) on an unreadable response matters:
+// haltReasons treats null as "couldn't check" and stays quiet, where an empty
+// Set would mark every task not_claimable and halt the runner on its first step.
+function rowsOf(payload) {
+  if (Array.isArray(payload)) return payload;
+  if (!payload || typeof payload !== 'object') return null;
+  for (const key of ['claimable', 'tasks', 'rows', 'items']) {
+    if (Array.isArray(payload[key])) return payload[key];
+  }
+  return null;
+}
+
+async function fetchClaimableIds(api) {
+  const r = await api.tasks.getTasksClaimable({ query: { limit: 500 } });
+  if (!r.ok) return null;
+  const rows = rowsOf(r.data);
+  return rows ? new Set(rows.map((t) => Number(t.id))) : null;
+}
+
+// -------------------------------------------------------------------------
+// Output
+// -------------------------------------------------------------------------
+
+function taskLine(t, i) {
+  const est = t.est_minutes_calibrated ?? t.est_minutes;
+  return `  ${String(i + 1).padStart(2)}. task ${t.id} · ${t.status} · ${t.credits_reward ?? 0}c · ${est ? fmtMinutes(est) : '—'}\n      ${t.title}`;
+}
+
+function printPlan({ plan, cycle, scope, base }) {
+  if (!plan.length) {
+    console.log(`No open tasks in ${scope}. ${HALT_REASONS.chain_complete}.`);
+    return;
+  }
+  const tot = summarize(plan);
+  console.log(`Chain for ${scope} — ${tot.count} open task(s), ${tot.credits}c, ${fmtMinutes(tot.minutes)}\n`);
+  plan.forEach((t, i) => console.log(taskLine(t, i)));
+  if (cycle.length) {
+    console.log(`\n⚠ ${cycle.length} task(s) could not be ordered — dependency cycle: ${cycle.join(', ')}`);
+  }
+  console.log(`\nHall: ${base}#/task/${plan[0].id}`);
+  console.log(`Next: node scripts/bongos/sequence.js --from ${plan[0].id} --next`);
+}
+
+function printHalt(task, reasons) {
+  console.log(`HALT — task ${task.id}: ${task.title}\n`);
+  for (const r of reasons) console.log(`  • [${r.code}] ${r.detail}`);
+  console.log('\nThis one needs a human. Everything already shipped stays shipped.');
+}
+
+// The tasks --next walked past. Printed BEFORE the pick so the skip is the
+// first thing read, not a footnote under the answer.
+function printSkipped(skipped) {
+  if (!skipped.length) return;
+  const n = skipped.length;
+  console.log(`Skipped ${n} task${n === 1 ? '' : 's'} that can't run yet:`);
+  for (const s of skipped) {
+    const [first, ...rest] = s.reasons;
+    const also = rest.length ? ` (also: ${rest.map((r) => r.code).join(', ')})` : '';
+    console.log(`  • task ${s.id} — [${first.code}] ${first.detail}${also}`);
+    console.log(`      ${s.title}`);
+  }
+  console.log('');
+}
+
+// -------------------------------------------------------------------------
+// Main
+// -------------------------------------------------------------------------
+
+async function main() {
+  const opts = readArgv(process.argv.slice(2));
+  if (!opts.from && !opts.goal && !opts.check) {
+    console.error('usage: sequence.js --from <task-id> | --goal <goal-id> | --check <task-id> [--next] [--json]');
+    process.exit(2);
+  }
+
+  await requireSession();
+  const api = await cliClient();
+  const meR = await api.me.getMe();
+  const rank = meR.ok ? meR.data.builder?.rank : null;
+  const base = hallBase();
+
+  // --check: one task, halt matrix, non-zero exit if anything fires.
+  if (opts.check) {
+    const t = await fetchTask(api, opts.check);
+    const claimableIds = await fetchClaimableIds(api);
+    const reasons = haltReasons(t, { rank, claimableIds });
+    if (opts.json) {
+      console.log(JSON.stringify({ task_id: opts.check, ok: reasons.length === 0, reasons }, null, 2));
+    } else if (!reasons.length) {
+      console.log(`task ${opts.check} is clear to run.`);
+    } else {
+      printHalt(t || { id: opts.check, title: '(not found)' }, reasons);
+    }
+    process.exit(reasons.length ? 1 : 0);
+  }
+
+  const byId = opts.goal
+    ? await fetchGoalTasks(api, opts.goal, opts.limit)
+    : await fetchChain(api, opts.from, opts.limit);
+
+  const scope = opts.goal ? `goal ${opts.goal}` : `task ${opts.from}`;
+  const candidates = opts.goal
+    ? Array.from(byId.values()).filter((t) => !TERMINAL.has(t.status))
+    : chainFrom(opts.from, byId, { limit: opts.limit });
+
+  const { order, cycle } = topoOrder(candidates);
+  const plan = order.slice(0, opts.limit);
+
+  // --next: the first task in the plan that clears the halt matrix.
+  if (opts.next) {
+    const claimableIds = await fetchClaimableIds(api);
+    const head = plan[0];
+    if (!head) {
+      const payload = { next: null, stop: 'chain_complete', detail: HALT_REASONS.chain_complete };
+      console.log(opts.json ? JSON.stringify(payload, null, 2) : `${HALT_REASONS.chain_complete} in ${scope}.`);
+      process.exit(0);
+    }
+    // Scan the whole plan, not just the head — a blocked task at position 0
+    // must not hide runnable work behind it (see pickNext).
+    const { next: pick, skipped } = pickNext(plan, { rank, claimableIds });
+    if (!pick) {
+      // Everything was skipped, so skipped[0] IS the head — reuse its reasons
+      // rather than recomputing them and risking the two printouts diverging.
+      const reasons = skipped[0].reasons;
+      const payload = {
+        next: null,
+        stop: reasons[0].code,
+        reasons,
+        task: { id: head.id, title: head.title },
+        tried: plan.length,
+        skipped,
+      };
+      if (opts.json) console.log(JSON.stringify(payload, null, 2));
+      else {
+        printHalt(head, reasons);
+        if (plan.length > 1) {
+          console.log(`\nChecked all ${plan.length} open tasks in ${scope} — none can run right now.`);
+        }
+      }
+      process.exit(1);
+    }
+    const remaining = summarize(plan);
+    if (opts.json) {
+      console.log(JSON.stringify({ next: pick, remaining, scope, skipped }, null, 2));
+    } else {
+      printSkipped(skipped);
+      console.log(`Next in ${scope}: task ${pick.id} — ${pick.title}`);
+      console.log(`  ${pick.credits_reward ?? 0}c · ${fmtMinutes(pick.est_minutes_calibrated ?? pick.est_minutes ?? 0)} · ${remaining.count - 1} more open in this chain`);
+      console.log(`  node scripts/bongos/claim.js ${pick.id}`);
+    }
+    process.exit(0);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({ scope, plan, cycle, totals: summarize(plan) }, null, 2));
+    return;
+  }
+  printPlan({ plan, cycle, scope, base });
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err.message || err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  readArgv,
+  edgeIds,
+  rowsOf,
+  // exported for the Autobongos supervisor (task 1003902) so the claimable feed
+  // is read one way, not copied into a second place that can drift.
+  fetchClaimableIds,
+  fetchGoalTasks,
+  fetchGoalTaskRows,
+  declaredSurfaceExcludesMigrations,
+  GOAL_PAGE,
+  topoOrder,
+  chainFrom,
+  haltReasons,
+  pickNext,
+  summarize,
+  HALT_REASONS,
+  RANK_TIER,
+  MIN_SPEC_CHARS,
+  JUDGEMENT_KINDS,
+  TERMINAL,
+  IN_FLIGHT,
+};