@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/autonomy-gate.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// scripts/bongos/autonomy-gate.js — System 3 (task 1351): the $0 deterministic
+// autonomy precheck. Before any model boots, a nightly routine runs this as
+// Step 0; on NO-GO it exits cleanly and NOTHING spawns. Three skips it can make:
+//   - no claimable autonomous work AND origin/main unchanged since the last run
+//     (overnight-builder on a no-signal night),
+//   - no open ideas to triage (triage routines),
+//   - the autonomous month-to-date spend has hit its ceiling (hard spend-brake).
+//
+// BUILT DISABLED (owner directive — hard rule 6). The gate is INERT until
+// OTB_AUTONOMY_ENABLED=1: while off, decide() always returns GO, so wiring a
+// routine's Step 0 to this changes nothing. Arm it only alongside the grader
+// rework. Every decision (especially a SKIP) is recorded to autonomy_runs.
+//
+// Usage (on the droplet, with DB + git in context):
+//   node scripts/bongos/autonomy-gate.js <routine>     # exit 0 = GO, 1 = NO-GO
+//   node scripts/bongos/autonomy-gate.js <routine> --json
+
+'use strict';
+
+const AUTONOMY_FLAG = 'OTB_AUTONOMY_ENABLED';
+const DEFAULT_CEILING_USD = 30; // conservative autonomous-fleet MTD ceiling; override via env
+
+function isEnabled(env = process.env) {
+  return env[AUTONOMY_FLAG] === '1';
+}
+function ceilingUsd(env = process.env) {
+  const v = Number(env.OTB_AUTONOMY_CEILING_USD);
+  return Number.isFinite(v) && v > 0 ? v : DEFAULT_CEILING_USD;
+}
+
+// Pure: the go/no-go decision from already-gathered signals. No I/O — unit-tested.
+//   enabled        — master flag; when false the gate is inert (always GO).
+//   routine        — selects which signal matters (builder/triage/…).
+//   claimableCount — parallel-safe autonomous tasks available now.
+//   openIdeasCount — open idea_inbox rows.
+//   mtdSpendUsd    — autonomous (cron:%) api spend this month.
+//   ceiling        — the spend-brake threshold.
+//   headSha/lastHeadSha — origin/main now vs the last `go` run (no-signal check).
+function decide({ enabled, routine = '', claimableCount = 0, openIdeasCount = 0, mtdSpendUsd = 0, ceiling = DEFAULT_CEILING_USD, headSha = null, lastHeadSha = null } = {}) {
+  if (!enabled) {
+    return { decision: 'go', reason: `autonomy gate disabled (${AUTONOMY_FLAG}!=1) — proceeding as normal (inert)` };
+  }
+  // 1) Hard spend-brake first — economy safety trumps any signal.
+  if (mtdSpendUsd >= ceiling) {
+    return { decision: 'no-go', reason: `autonomous MTD spend $${mtdSpendUsd.toFixed(2)} ≥ ceiling $${ceiling.toFixed(2)} — spend brake` };
+  }
+  // 2) No-signal skips, per routine kind.
+  const wantsClaimable = /builder|simplify|code-?review/i.test(routine);
+  const wantsIdeas = /idea|triage/i.test(routine);
+  const headUnchanged = !!(headSha && lastHeadSha && headSha === lastHeadSha);
+  if (wantsClaimable && claimableCount === 0 && headUnchanged) {
+    return { decision: 'no-go', reason: `no claimable autonomous tasks and origin/main unchanged since last run (${String(headSha).slice(0, 8)}) — no signal` };
+  }
+  if (wantsIdeas && openIdeasCount === 0) {
+    return { decision: 'no-go', reason: 'no open ideas to triage — no signal' };
+  }
+  return { decision: 'go', reason: `signal present (claimable=${claimableCount}, ideas=${openIdeasCount}, main ${headUnchanged ? 'unchanged' : 'changed'})` };
+}
+
+// Gather the live signals (DB + git). Real deps on the droplet; injectable for tests.
+async function gatherSignals(routine, deps = {}) {
+  // listClaimableTasks carved into modules/lifecycle/db.js (BV1.R86 / ADR 0093 §3).
+  // A CLI may require a module directly (outside the kernel boundary — precedent).
+  const db = deps.db || require('../../modules/lifecycle/db'); // listClaimableTasks — lifecycle
+  // The autonomy_runs slice (recordAutonomyRun/lastAutonomyHead) carved into
+  // modules/autonomy/db.js (BV1.R83 / ADR 0093 §1). This gate is a domain CLI that
+  // travels with the autonomy module but stays under scripts/ (a command travels
+  // with its domain; from outside the kernel boundary it may require the module
+  // directly — the memory/grading-carve precedent).
+  const autonomyDb = deps.autonomyDb || require('../../modules/autonomy/db');
+  const inbox = deps.inbox || require('../../modules/ideas/inbox'); // carved → modules/ideas/ (BV1.R78)
+  // autonomousApiSpendMtd carved into modules/economy/ (BV1.R77 / ADR 0093 §1-2).
+  // A CLI may require a module directly (the memory/grading-carve precedent); the
+  // economy cost module owns the autonomous-spend MTD read.
+  const economy = deps.economy || require('../../modules/economy/cost');
+  const git = deps.git || ((cmd) => require('child_process').execSync(cmd, { encoding: 'utf8' }).trim());
+  const claimable = await db.listClaimableTasks({ fit: 'autonomous' }).catch(() => []);
+  const openIdeasCount = await inbox.countOpenIdeas().catch(() => 0);
+  const mtdSpendUsd = await economy.autonomousApiSpendMtd().catch(() => 0);
+  let headSha = null;
+  try { git('git fetch origin main --quiet'); headSha = git('git rev-parse origin/main'); } catch (_) { /* git unavailable → null */ }
+  const lastHeadSha = await autonomyDb.lastAutonomyHead(routine).catch(() => null);
+  return { claimableCount: Array.isArray(claimable) ? claimable.length : 0, openIdeasCount: Number(openIdeasCount) || 0, mtdSpendUsd: Number(mtdSpendUsd) || 0, headSha, lastHeadSha };
+}
+
+// Full precheck: gather (only when enabled — no point paying for git/db when inert),
+// decide, record. Best-effort recording. Returns the decision + signals.
+async function precheck(routine, deps = {}) {
+  const env = deps.env || process.env;
+  const enabled = isEnabled(env);
+  let signals = { claimableCount: 0, openIdeasCount: 0, mtdSpendUsd: 0, headSha: null, lastHeadSha: null };
+  if (enabled) { try { signals = await gatherSignals(routine, deps); } catch (_) { /* fail-open → decide on zeros */ } }
+  const result = decide({ enabled, routine, ceiling: ceilingUsd(env), ...signals });
+  try {
+    // recordAutonomyRun carved into modules/autonomy/db.js (BV1.R83 / ADR 0093 §1).
+    const autonomyDb = deps.autonomyDb || require('../../modules/autonomy/db');
+    await autonomyDb.recordAutonomyRun({ routine, decision: result.decision, reason: result.reason, headSha: signals.headSha, claimableCount: signals.claimableCount, enabled });
+  } catch (_) { /* observability is best-effort; never block the gate on a log write */ }
+  return { routine, enabled, ...result, ...signals };
+}
+
+// System 3 (task 1354): the single-pass safe_autofix lane gate. A review finding
+// may be auto-fixed-AND-shipped in one run ONLY when ALL of these hold — anything
+// else stays on the inbox→promote (human-in-the-loop) path:
+//   - the autonomy gate is armed (OTB_AUTONOMY_ENABLED),
+//   - the grader is LIVE (NEVER auto-fix while GRADER_BYPASS is on — auto-shipping
+//     with the quality gate off is precisely the thing we must not do),
+//   - the change is NOT a protected path (permission-path-check.matchProtected),
+//   - the finding is high-confidence AND single-file.
+// Pure; the DEFAULTS are the refusing values (off / bypass-on / protected / low /
+// many files) so any missing field → no autofix, and the lane is inert by default.
+function autofixAllowed({ enabled = false, graderBypassOn = true, isProtected = true, confidence = 'low', fileCount = 99 } = {}) {
+  return enabled === true
+    && graderBypassOn === false
+    && isProtected === false
+    && String(confidence).toLowerCase() === 'high'
+    && Number(fileCount) === 1;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const routine = args.find((a) => !a.startsWith('--'));
+  if (!routine) { console.error('usage: autonomy-gate.js <routine> [--json]'); process.exit(2); }
+  const out = await precheck(routine);
+  if (args.includes('--json')) console.log(JSON.stringify(out, null, 2));
+  else console.log(`autonomy-gate [${routine}]: ${out.decision.toUpperCase()} — ${out.reason}`);
+  process.exit(out.decision === 'go' ? 0 : 1);
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error('autonomy-gate: error (fail-open → GO):', e && e.message); process.exit(0); });
+}
+
+module.exports = { decide, autofixAllowed, gatherSignals, precheck, isEnabled, ceilingUsd, AUTONOMY_FLAG, DEFAULT_CEILING_USD };

package/scripts/bongos/autonomy-gauge-statusline.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/autonomy-gauge-statusline.js — the WRITER half of the Autobongos
+// usage gauge (task 1003901; ADR 0307 §2).
+//
+// Wire this as Claude Code's `statusLine.command`. On every render Claude Code
+// pipes the status JSON in on stdin; for a subscriber, after the session's first
+// API response, that JSON carries the only structured read of remaining capacity
+// there is:
+//
+//   rate_limits.five_hour.{ used_percentage, resets_at }
+//   rate_limits.seven_day.{ used_percentage, resets_at }
+//
+// It is absent before that first response, which is exactly why this has to
+// persist it: the supervisor needs the number BETWEEN sessions, when nothing is
+// running to ask. So this script's real output is the file; the line it prints
+// is a courtesy.
+//
+// TWO HARD RULES, both because this runs inside somebody's prompt:
+//
+//  1. IT NEVER THROWS AND NEVER EXITS NON-ZERO. A statusline that crashes breaks
+//     the prompt of every session on the machine, including the owner's. Every
+//     failure path prints something harmless and exits 0.
+//  2. IT NEVER DESTROYS A READING IT DID NOT REPLACE. This is per-WINDOW, not
+//     per-file (grader finding, task 1003901). A render with no rate_limits at
+//     all leaves the file alone — but so does a render that reports only
+//     five_hour: the previously-known seven_day is CARRIED FORWARD rather than
+//     dropped, because the seven-day number is what the weekly pacing depends on
+//     and it is the half most likely to be transiently absent. Rebuilding the
+//     object from scratch each render silently lost it.
+//
+//     Carrying a window forward means it must age on its own, so each window
+//     records its OWN `observed_at` and the reader applies staleness per window.
+//     Refreshing a single file-level written_at while keeping old data is exactly
+//     how "unknown" would become "headroom" — the one mistake the reader exists
+//     to prevent.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function main(raw) {
+  let input = null;
+  try { input = JSON.parse(raw); } catch (_) { return 'bongos: (no status json)'; }
+  if (!input || typeof input !== 'object') return 'bongos: (no status json)';
+
+  const rl = input.rate_limits;
+  const five = rl && rl.five_hour;
+  const seven = rl && rl.seven_day;
+
+  const pct = (w) => (w && Number.isFinite(Number(w.used_percentage)) ? Number(w.used_percentage) : null);
+  const fivePct = pct(five);
+  const sevenPct = pct(seven);
+
+  // Rule 2: nothing to record → say so, touch nothing.
+  if (fivePct === null && sevenPct === null) return 'bongos: limits not reported yet';
+
+  const now = Math.floor(Date.now() / 1000);
+
+  // Same redirect the reader honours (autonomy-gauge.js). Without it the two
+  // halves disagree about where the file lives, and a test that thinks it
+  // redirected the writer silently writes into the real config dir instead —
+  // which is how that was found.
+  let target;
+  try {
+    target = process.env.AUTOBONGOS_GAUGE_FILE
+      || require('../../src/instance-config.js').configPath('autobongos-gauge.json');
+  } catch (_) {
+    return `bongos: 5h ${fivePct ?? '–'}% · 7d ${sevenPct ?? '–'}% (not persisted)`;
+  }
+
+  // Rule 2: start from what is already on disk, so a window this render did not
+  // report survives instead of being overwritten with nothing.
+  let prior = {};
+  try { const p = JSON.parse(fs.readFileSync(target, 'utf8')); if (p && typeof p === 'object') prior = p; } catch (_) {}
+
+  const gauge = { written_at: now, source: 'statusline' };
+  const carry = (key) => {
+    const old = prior[key];
+    if (old && Number.isFinite(Number(old.used_percentage)) && Number.isFinite(Number(old.resets_at))) {
+      // Keep its ORIGINAL observed_at so it ages out on its own; a carried
+      // window that inherited `now` would read as fresh evidence forever.
+      gauge[key] = { ...old, observed_at: Number.isFinite(Number(old.observed_at)) ? Number(old.observed_at) : Number(prior.written_at) || now };
+    }
+  };
+  const put = (key, w, p) => {
+    const resets = w && Number(w.resets_at);
+    if (p !== null && Number.isFinite(resets)) gauge[key] = { used_percentage: p, resets_at: resets, observed_at: now };
+    else carry(key);
+  };
+  put('five_hour', five, fivePct);
+  put('seven_day', seven, sevenPct);
+
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    // Atomic: the supervisor may read this at any instant, and a half-written
+    // file parses as "no gauge file", which is a hold. Correct, but needlessly
+    // pessimistic when the real answer was one rename away.
+    const tmp = `${target}.tmp-${process.pid}-${require('node:crypto').randomBytes(6).toString('hex')}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(gauge, null, 2)}\n`);
+    fs.renameSync(tmp, target);
+  } catch (_) {
+    return `bongos: 5h ${fivePct ?? '–'}% · 7d ${sevenPct ?? '–'}% (not persisted)`;
+  }
+
+  const bits = [];
+  if (fivePct !== null) bits.push(`5h ${Math.round(fivePct)}%`);
+  if (sevenPct !== null) bits.push(`7d ${Math.round(sevenPct)}%`);
+  return `bongos: ${bits.join(' · ')}`;
+}
+
+let buf = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (d) => { buf += d; });
+process.stdin.on('end', () => {
+  let line;
+  try { line = main(buf); } catch (_) { line = 'bongos: gauge error'; }
+  process.stdout.write(`${line}\n`);
+  process.exit(0);   // rule 1, unconditionally
+});
+// A statusline invoked with no stdin must still return promptly.
+setTimeout(() => { try { process.stdout.write('bongos: (no input)\n'); } catch (_) {} process.exit(0); }, 2000).unref();
+
+module.exports = { main };

package/scripts/bongos/autonomy-gauge.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/autonomy-gauge.js — the READER half of the Autobongos usage gauge
+// (task 1003901; ADR 0307 §2). The supervisor calls this between tasks to ask
+// one question: may I start another task right now, and if not, until when?
+//
+//   node scripts/bongos/autonomy-gauge.js            # human-readable
+//   node scripts/bongos/autonomy-gauge.js --json     # machine-readable
+//   node scripts/bongos/autonomy-gauge.js --sleep    # block until capacity, then exit 0
+//
+// Exit codes:  0 = go   1 = hold (sleepUntil printed)   2 = unknown gauge
+//
+// The DECISION is not here — it is the pure `decideCapacity` in
+// modules/autonomy/gauge.js, which is unit-tested with no clock and no disk.
+// This file is the I/O half only: find the file, read it, print the verdict.
+// Same split autonomy-gate.js draws between `decide` and `gatherSignals`.
+
+const fs = require('node:fs');
+const { decideCapacity } = require('../../modules/autonomy/gauge.js');
+
+function gaugePath() {
+  if (process.env.AUTOBONGOS_GAUGE_FILE) return process.env.AUTOBONGOS_GAUGE_FILE;
+  try { return require('../../src/instance-config.js').configPath('autobongos-gauge.json'); }
+  catch (_) { return null; }
+}
+
+function loadGauge(p) {
+  if (!p) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
+}
+
+function readConfig() {
+  // Operator overrides ride on env so the runner can be retuned without a deploy.
+  const num = (v) => (Number.isFinite(Number(v)) ? Number(v) : undefined);
+  const c = {};
+  if (process.env.AUTOBONGOS_TIMEZONE) c.timezone = process.env.AUTOBONGOS_TIMEZONE;
+  if (num(process.env.AUTOBONGOS_STALE_AFTER_S) !== undefined) c.staleAfterS = num(process.env.AUTOBONGOS_STALE_AFTER_S);
+  if (num(process.env.AUTOBONGOS_WEEKLY_SLACK) !== undefined) c.weeklySlack = num(process.env.AUTOBONGOS_WEEKLY_SLACK);
+  const rw = num(process.env.AUTOBONGOS_RESERVE_WORKING);
+  const ro = num(process.env.AUTOBONGOS_RESERVE_OVERNIGHT);
+  if (rw !== undefined || ro !== undefined) c.reserve = { ...(rw !== undefined && { working: rw }), ...(ro !== undefined && { overnight: ro }) };
+  const hs = num(process.env.AUTOBONGOS_HOURS_START);
+  const he = num(process.env.AUTOBONGOS_HOURS_END);
+  if (hs !== undefined || he !== undefined) c.ownerHours = { ...(hs !== undefined && { start: hs }), ...(he !== undefined && { end: he }) };
+  return c;
+}
+
+function evaluate(nowEpochS = Math.floor(Date.now() / 1000)) {
+  const p = gaugePath();
+  return { path: p, decision: decideCapacity({ gauge: loadGauge(p), now: nowEpochS, config: readConfig() }) };
+}
+
+async function main(argv) {
+  const json = argv.includes('--json');
+  const sleep = argv.includes('--sleep');
+
+  for (;;) {
+    const { path: p, decision: d } = evaluate();
+    if (json) console.log(JSON.stringify({ ...d, gauge_path: p }, null, 2));
+    else {
+      const when = d.sleepUntil ? ` → wake ${new Date(d.sleepUntil * 1000).toISOString()}` : '';
+      console.log(`${d.go ? 'GO' : d.unknown ? 'UNKNOWN' : 'HOLD'}: ${d.reason}${when}`);
+    }
+    if (d.go) return 0;
+    if (!sleep) return d.unknown ? 2 : 1;
+
+    // --sleep: wait exactly as long as the decision says, then re-read. An
+    // UNKNOWN gauge has no reset to aim at, so poll gently rather than spin.
+    const now = Math.floor(Date.now() / 1000);
+    const waitS = d.sleepUntil ? Math.max(1, d.sleepUntil - now) : 60;
+    if (!json) console.log(`  sleeping ${waitS}s…`);
+    await new Promise((r) => setTimeout(r, waitS * 1000));
+  }
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((c) => process.exit(c)).catch((e) => {
+    console.error(`autonomy-gauge: ${e && e.message ? e.message : e}`);
+    process.exit(2);
+  });
+}
+
+module.exports = { evaluate, gaugePath, loadGauge, readConfig };

package/scripts/bongos/backfill-cost.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// Backfill cost_log from the art-pipeline cost ledger.
+//
+// Reads art/iterations/cost_ledger.jsonl (gitignored, lives in whichever
+// worktree ran the pipeline) and POSTs each row to /api/bongos/cost.
+//
+// Idempotent thanks to migration 004_pms_cost_idempotency.sql:
+// re-running this script is a no-op (skipped rows print as 'dup').
+//
+// Usage:
+//   node scripts/bongos/backfill-cost.js [path/to/cost_ledger.jsonl]
+//
+// If no path is given, the script searches for the ledger in the
+// expected locations (current art/iterations/, sibling worktrees, or
+// $<PREFIX>_COST_LEDGER env var — BONGOS_COST_LEDGER on a vanilla instance, the
+// legacy OTB_COST_LEDGER still read).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { cliClient, requireSession, fmtUsd } = require('./cli-lib');
+const { resolveEnv, envPrefix } = require('../../src/instance-config');
+// Cost-attribution audit carved into modules/economy/cost-classify.js (BV1.R77 /
+// ADR 0093 §1-2). A CLI may require a module directly (the memory/grading-carve
+// precedent — grade-smoke.js requires modules/grading/grader).
+const { auditCostAttribution, formatAuditReport } = require('../../modules/economy/cost-classify');
+
+// The places a ledger is looked for, env override first. A function so the test can
+// hand it an env; resolved once below for the CLI.
+const knownLedgerPaths = (env = process.env) => [
+  resolveEnv('COST_LEDGER', { env }),
+  path.resolve(__dirname, '../../art/iterations/cost_ledger.jsonl'),
+  // Two historical absolute-path fallbacks (under the old Desktop folder name)
+  // were dropped after the project-folder rename. Pass the ledger path as a CLI
+  // arg or set <PREFIX>_COST_LEDGER to point at any non-default location.
+];
+const KNOWN_LEDGER_PATHS = knownLedgerPaths();
+
+function findLedger(argPath) {
+  const candidates = argPath ? [argPath, ...KNOWN_LEDGER_PATHS] : KNOWN_LEDGER_PATHS;
+  for (const p of candidates) {
+    if (p && fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+function parseLedger(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8');
+  const rows = [];
+  let lineNum = 0;
+  for (const line of text.split('\n')) {
+    lineNum++;
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      rows.push({ ...JSON.parse(trimmed), _line: lineNum });
+    } catch (err) {
+      console.warn(`skip malformed line ${lineNum}: ${err.message}`);
+    }
+  }
+  return rows;
+}
+
+async function postCost(row, sourceRef) {
+  const payload = {
+    amount_usd: Number(row.cost_usd),
+    category: 'art',
+    description: [row.model, row.kind, row.tile, row.attempt != null ? `attempt ${row.attempt}` : null]
+      .filter(Boolean)
+      .join(' · '),
+    source: 'art_pipeline',
+    source_ref: sourceRef,
+    recorded_at: row.ts,
+  };
+  // V3.R11 (#91): forward the per-builder attribution stamped onto the ledger
+  // row by cost_ledger.log_call(). The cost route enforces that builder_id
+  // matches the authed builder, so we only pass it through if the row's id
+  // matches our session — otherwise we send no id and the route defaults it
+  // to the authed builder (which is the right behavior for "I'm backfilling
+  // my own historical ledger").
+  if (row.builder_id != null) {
+    payload.builder_id = Number(row.builder_id);
+  }
+  const api = await cliClient();
+  return api.cost.postCost({ body: payload });
+}
+
+async function main() {
+  // --audit (V3.R83 #303): run the cost-attribution audit against the live
+  // public cost-summary and exit. No ledger, no session needed — it reads the
+  // public endpoint and reports how much spend is attributed vs. honestly
+  // unattributed, and flags any orphaned attribution. Add --json for the raw
+  // report object.
+  if (process.argv.includes('--audit')) {
+    const api = await cliClient();
+    const summary = await api.public.getPublicCostSummary();
+    if (!summary.ok) {
+      console.error(`audit: failed to fetch cost-summary (HTTP ${summary.status})`);
+      process.exit(1);
+    }
+    const report = auditCostAttribution(summary.data);
+    if (process.argv.includes('--json')) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(formatAuditReport(report));
+    }
+    process.exit(report.ok ? 0 : 1);
+  }
+
+  const argPath = process.argv[2];
+  await requireSession();
+
+  const ledgerPath = findLedger(argPath);
+  if (!ledgerPath) {
+    console.error(`No cost_ledger.jsonl found. Pass a path or set ${envPrefix()}_COST_LEDGER.`);
+    console.error('Searched:');
+    for (const p of KNOWN_LEDGER_PATHS) if (p) console.error(`  - ${p}`);
+    process.exit(2);
+  }
+  console.log(`Using ledger: ${ledgerPath}`);
+
+  const rows = parseLedger(ledgerPath);
+  console.log(`Loaded ${rows.length} rows.`);
+
+  let inserted = 0;
+  let dup = 0;
+  let failed = 0;
+  let totalUsdInserted = 0;
+
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    if (typeof row.cost_usd !== 'number' || row.cost_usd <= 0) {
+      // Skip zero-cost rows (no point logging $0).
+      continue;
+    }
+    const sourceRef = `ledger:${row.ts}:${row.tile || 'unknown'}:${row._line}`;
+    const res = await postCost(row, sourceRef);
+    if (res.status === 201) {
+      inserted++;
+      totalUsdInserted += Number(row.cost_usd);
+    } else if (res.status === 200 && res.data && res.data.skipped) {
+      dup++;
+    } else {
+      failed++;
+      if (failed <= 5) {
+        console.warn(`row ${i} failed: ${res.status} ${JSON.stringify(res.data)}`);
+      }
+    }
+    if ((i + 1) % 50 === 0) {
+      console.log(`  progress: ${i + 1}/${rows.length} (inserted=${inserted}, dup=${dup}, failed=${failed})`);
+    }
+  }
+
+  console.log('');
+  console.log(`Done. inserted=${inserted}  dup=${dup}  failed=${failed}`);
+  console.log(`Total inserted: ${fmtUsd(totalUsdInserted)}`);
+
+  // Final check against the public summary
+  const api = await cliClient();
+  const summary = await api.public.getPublicCostSummary();
+  if (summary.ok) {
+    console.log(`Public total now: ${fmtUsd(summary.data.total_usd)}`);
+  }
+
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+// Run only when invoked directly: requiring this file (the test does, for
+// knownLedgerPaths) must never start a backfill.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('backfill-cost.js failed:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = { knownLedgerPaths };

package/scripts/bongos/backfill-disciplines.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// scripts/bongos/backfill-disciplines.js — task 1002988: give every role-less task a craft.
+//
+// WHY THIS EXISTS SEPARATELY FROM THE MIGRATION. core_247 narrows
+// tasks_discipline_check to {engineer, artist, ideator, ui} and carries a
+// last-resort `UPDATE ... SET discipline='engineer'` so a fresh install can never
+// be blocked on a human remembering to run a script. But that net is a blunt
+// guess. The real classification is classifyTaskDiscipline() — a JS heuristic over
+// title + description + touches that SQL cannot express — so the good pass runs
+// here, first, and the migration only catches what is left.
+//
+// Run this BEFORE deploying core_247. Order matters: rows this script resolves keep
+// a reasoned craft; rows it does not are parked on 'engineer' by the migration.
+//
+// USAGE
+//   node scripts/bongos/backfill-disciplines.js              # dry run — the spot-check list
+//   node scripts/bongos/backfill-disciplines.js --apply      # commit the PATCHes
+//   node scripts/bongos/backfill-disciplines.js --sample 40  # widen the printed sample
+//
+// The dry run is the default on purpose: the task required a spot-check list for the
+// owner BEFORE anything was applied, and 1,189 rows is not a diff anyone reviews in
+// their head.
+
+'use strict';
+
+const { cliClient, requireSession } = require('./cli-lib');
+const { resolveWriteDiscipline, WRITABLE_DISCIPLINES } = require('../../modules/lifecycle/task-classifier.js');
+
+// Rows whose title marks them as test debris. The classifier already skips these
+// (they are not real work), but they still carry 'unclassified' and therefore still
+// violate the narrowed constraint — so they must be resolved, not skipped, or the
+// migration's net silently becomes the thing that handles 164 rows.
+const SMOKE_RE = /__smoke__/;
+
+// The fallback for anything the heuristic refuses. Stated as a constant with its
+// reasoning rather than inlined, because this value is a GUESS and every report
+// below labels it as one.
+const FALLBACK = 'engineer';
+
+function classify(task) {
+  const resolved = resolveWriteDiscipline({
+    title: task.title, description: task.description, touches: task.touches,
+  });
+  if (resolved.discipline) {
+    return { discipline: resolved.discipline, reasoned: true, confidence: resolved.confidence ?? null };
+  }
+  return { discipline: FALLBACK, reasoned: false, confidence: null };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// PATCH one row, WAITING OUT the per-session rate limit rather than counting it as a
+// failure. The first run of this backfill treated a 429 as a failed row and stopped
+// having written 120 of 1,189 — the limiter was doing its job and the script was
+// reading "slow down" as "no". The server tells us how long to wait; honour it.
+// Re-running is safe either way: the query only returns rows still unclassified.
+async function patchWithBackoff(api, id, discipline, maxAttempts = 6) {
+  for (let attempt = 1; ; attempt += 1) {
+    const res = await api.tasks.patchTasksId({ id, body: { discipline } });
+    if (res.status !== 429 || attempt >= maxAttempts) return res;
+    const retryAfter = Number(res.data?.error?.details?.retry_after_seconds);
+    const waitMs = (Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : 2 ** attempt) * 1000;
+    console.log(`    rate limited — waiting ${Math.round(waitMs / 1000)}s (attempt ${attempt}/${maxAttempts - 1})`);
+    await sleep(waitMs + 500);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const apply = args.includes('--apply');
+  const sampleIdx = args.indexOf('--sample');
+  const sampleSize = sampleIdx >= 0 ? Number(args[sampleIdx + 1]) || 20 : 20;
+
+  await requireSession();
+  const api = await cliClient();
+
+  const r = await api.tasks.getTasks({ query: { discipline: 'unclassified' } });
+  if (!r.ok) {
+    console.error(`failed to read tasks (${r.status}):`, r.data);
+    process.exit(1);
+  }
+  const tasks = r.data?.tasks || [];
+  if (!tasks.length) {
+    console.log('Nothing to do — no task carries discipline=unclassified.');
+    return;
+  }
+
+  const plan = tasks.map((t) => ({ task: t, ...classify(t), smoke: SMOKE_RE.test(t.title || '') }));
+  const reasoned = plan.filter((p) => p.reasoned);
+  const guessed = plan.filter((p) => !p.reasoned);
+  const byDiscipline = {};
+  for (const p of plan) byDiscipline[p.discipline] = (byDiscipline[p.discipline] || 0) + 1;
+
+  console.log(`\n${apply ? 'Applying' : 'DRY RUN —'} discipline backfill over ${plan.length} role-less task(s)\n`);
+  console.log('  Resolved by the classifier (a reasoned answer):');
+  for (const [d, n] of Object.entries(byDiscipline).sort((a, b) => b[1] - a[1])) {
+    const reasonedN = reasoned.filter((p) => p.discipline === d).length;
+    console.log(`    ${d.padEnd(12)} ${String(reasonedN).padStart(5)}`);
+  }
+  console.log(`\n  BEST GUESS (classifier refused → ${FALLBACK}): ${guessed.length}`);
+  console.log(`    of which __smoke__ test debris:            ${guessed.filter((p) => p.smoke).length}`);
+  console.log('    These are NOT determined answers. A later reader must not treat');
+  console.log('    them as evidence that anyone classified the row (owner decision 2026-09-17).\n');
+
+  console.log(`  Spot-check sample — reasoned (first ${sampleSize}):`);
+  for (const p of reasoned.slice(0, sampleSize)) {
+    console.log(`    ${p.discipline.padEnd(9)} ${p.confidence != null ? `(${p.confidence.toFixed(2)})` : '      '}  ${String(p.task.title).slice(0, 72)}`);
+  }
+  console.log(`\n  Spot-check sample — GUESSED (first ${sampleSize}):`);
+  for (const p of guessed.filter((x) => !x.smoke).slice(0, sampleSize)) {
+    console.log(`    ${p.discipline.padEnd(9)}          ${String(p.task.title).slice(0, 72)}`);
+  }
+
+  if (!apply) {
+    console.log(`\nDry run — nothing was written. Re-run with --apply to commit.\n`);
+    return;
+  }
+
+  let ok = 0;
+  const failures = [];
+  for (const p of plan) {
+    const res = await patchWithBackoff(api, p.task.id, p.discipline);
+    if (res.ok) ok += 1;
+    else failures.push({ id: p.task.id, status: res.status, detail: JSON.stringify(res.data).slice(0, 160) });
+    if (ok % 100 === 0 && res.ok) console.log(`  … ${ok}/${plan.length}`);
+  }
+  console.log(`\nApplied: ${ok}/${plan.length}`);
+  if (failures.length) {
+    console.log(`Failed:  ${failures.length}`);
+    for (const f of failures.slice(0, 20)) console.log(`   #${f.id} → ${f.status} ${f.detail}`);
+    process.exitCode = 1;
+  }
+  // Report the residue against the same query, so the number quoted afterwards is
+  // measured rather than assumed.
+  const after = await api.tasks.getTasks({ query: { discipline: 'unclassified' } });
+  const left = after.ok ? (after.data?.tasks || []).length : null;
+  console.log(`Remaining unclassified: ${left == null ? '(re-read failed)' : left}`);
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error(e && e.message ? e.message : e); process.exit(1); });
+}
+
+module.exports = { classify, FALLBACK, SMOKE_RE };