@bongos/core 1.19.870 → 1.19.872

package/scripts/gds/autobongos-verify.js

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/autobongos-verify.js — read completion back from the LEDGER, never
+// from the session that claims it (task 1003903; ADR 0307 §4).
+//
+// THE CONFUSION THIS EXISTS TO END. A session exiting is not a task shipping,
+// and this project's worst incidents are all that one confusion wearing
+// different clothes: task 1002483 sat at `completed` for three days carrying 651
+// lines of tested work on a branch nobody had pushed; task 1002459 sat at
+// `confirmed` for four days with no artifact on any branch at all; a ship once
+// "timed out" after its merge had already landed. Every one of them was found by
+// accident, because a strand emits no signal of its own.
+//
+// The headless envelope makes it worse rather than better. A worker that stopped
+// dead needing a decision returns `subtype: "success"` — structurally identical
+// to one that finished the job. So the worker's `shipped` is a CLAIM, which is
+// why autobongos-loop.js names it `claims_shipped`, and this file is the half
+// that turns a claim into a fact or into a filed blocker.
+//
+// THE VOCABULARY IS BORROWED, NOT INVENTED. strand-watch.js (task 1003163)
+// already named the three mid-ship shapes — `unprovable`, `unlanded`,
+// `ungraded` — and /strand-fix routes on those names. Calling the same condition
+// something else here would give one situation two names and split the remedies,
+// so classifyStrand() is called directly. What changes is the THRESHOLD: the
+// board sweep waits an hour (a slow CI queue is not a strand), while here the
+// session that was supposed to finish the job has already exited, so waiting
+// cannot change the verdict. The thresholds are zeroed deliberately, and this
+// file is strictly stricter than the board check — never quieter.
+//
+// Usage (normally called by autobongos-run.js, but runnable by hand):
+//   node scripts/gds/autobongos-verify.js 1003902           # verify, report, change nothing
+//   node scripts/gds/autobongos-verify.js 1003902 --act     # also release + file the blocker
+//   node scripts/gds/autobongos-verify.js 1003902 --json
+//
+// Exit codes: 0 verified shipped · 1 not shipped (a shape is named) · 2 undetermined.
+
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+
+const { classifyStrand, WATCHED } = require('./strand-watch.js');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Statuses a claim can still be sitting in when the worker is already gone.
+// `active` is the live one; the others are listed because a future rename must
+// fail loudly here rather than silently reclassify a held claim as untouched.
+const HELD_STATUSES = new Set(['active', 'claimed', 'in_progress']);
+
+// ---------------------------------------------------------------------------
+// The pure half
+// ---------------------------------------------------------------------------
+
+// classifyLedger — what the ledger says happened, in one word.
+//
+// `artifact` is the result of probeArtifact() or null for "not probed". The
+// distinction is load-bearing: `checked: false` means we could not look (no
+// network, a detached checkout), and NOT LOOKING IS NOT EVIDENCE OF ABSENCE. A
+// failed probe must never manufacture a missing artifact.
+//
+// Every shape carries what to DO, because the caller must not re-derive it:
+//   releaseClaim — the task is still held by a session that no longer exists.
+//   fileBlocker  — a human has to look at this.
+//   linkBlocker  — link the blocker to the task, which parks it at `blocked` and
+//                  takes it out of claimable_tasks. Only meaningful once the task
+//                  is back at `ready` (LINK_BLOCKABLE_STATUSES in
+//                  modules/ideas/blockers.js is exactly ['ready']), which is why
+//                  the caller releases BEFORE it links.
+//   halt         — the run stops here rather than picking another task.
+function classifyLedger({ task, artifact = null, nowMs = Date.now() } = {}) {
+  const none = { releaseClaim: false, fileBlocker: false, linkBlocker: false, halt: false };
+
+  if (!task) {
+    // Cannot read the ledger => cannot verify anything => touch nothing. Releasing
+    // a claim on a guess is how work gets stranded, and this is the one branch
+    // where the honest move is to stop and let a person look.
+    return {
+      ...none, verified: false, shape: 'undetermined', status: null, halt: true,
+      reason: 'the task could not be read back from Bongos, so nothing about it is known',
+      remedy: 'check the instance is reachable, then re-run the verify by hand',
+    };
+  }
+
+  const status = String(task.status || '');
+
+  if (status === 'shipped') {
+    if (artifact && artifact.checked && !artifact.onMain) {
+      // The flip happened with nothing behind it — tasks 1002459 and 1002792,
+      // both credited, neither carrying a line of code on any branch. The task is
+      // NOT released and NOT linked: it is shipped, credits are paid, and parking
+      // it would help nobody. The blocker is the whole point — a person has to
+      // decide whether the work was codeless (legitimate: a DB-only change, work
+      // on another checkout) or simply never done.
+      return {
+        ...none, verified: false, shape: 'shipped_no_artifact', status, fileBlocker: true,
+        reason: 'the ledger says shipped but no commit on main names this task',
+        remedy: 'confirm the work was codeless, or redo it — do not try to deploy what is not there',
+      };
+    }
+    return {
+      ...none, verified: true, shape: 'shipped', status,
+      reason: artifact && artifact.checked
+        ? `shipped, and main carries ${artifact.sha ? artifact.sha.slice(0, 8) : 'a commit'} naming it`
+        : 'shipped',
+      remedy: null,
+    };
+  }
+
+  if (status === 'abandoned') {
+    // Terminal, but not a delivery. An unattended worker deciding to cut a task
+    // is a judgement call it was never given, so it stops the run.
+    return {
+      ...none, verified: false, shape: 'abandoned', status, fileBlocker: true, halt: true,
+      reason: 'the task was abandoned, not shipped — a cut is a decision a worker does not get to make',
+      remedy: 'decide whether the cut was right; re-open the task if it was not',
+    };
+  }
+
+  if (WATCHED.includes(status)) {
+    // The three shapes strand-watch already names. Thresholds zeroed: the board
+    // sweep is allowed to wait, this is not (see the header).
+    const strand = classifyStrand(task, { nowMs, confirmedStaleMs: -1, completedStaleMs: -1 });
+    // classifyStrand fails QUIET on an unparseable updated_at — right for a line
+    // injected into every session, wrong here, where quiet means the loop calls a
+    // strand a success. The status alone decides the shape when the date will not
+    // parse; `unprovable` is the only shape that needs a field to be sure of.
+    const shape = strand ? strand.shape : (status === 'confirmed' ? 'unlanded' : 'ungraded');
+    const remedy = strand ? strand.remedy : (status === 'confirmed'
+      ? '/merge-mode is the documented manual fallback'
+      : '/grade-recover diagnoses which of the three shapes parked it');
+    return {
+      ...none, verified: false, shape, status, fileBlocker: true,
+      reason: {
+        unprovable: 'the reconciler probed this, could not prove a land, and gave up — it will never self-heal',
+        unlanded: 'the grade passed and the land never finished',
+        ungraded: 'the grade parked this; it is not waiting on a land',
+      }[shape],
+      strandReason: strand ? strand.reason : null,
+      remedy,
+    };
+  }
+
+  if (HELD_STATUSES.has(status)) {
+    // The worker is gone and the claim is not. This is the one shape that
+    // actually needs the claim released — and the only one where the link can
+    // then park the task, because release returns it to `ready`.
+    return {
+      ...none, verified: false, shape: 'still_held', status,
+      releaseClaim: true, fileBlocker: true, linkBlocker: true,
+      reason: `the worker exited with the task still at '${status}' — the claim outlived the session holding it`,
+      remedy: 'read the worker output in the run log; the tree may hold committed work',
+    };
+  }
+
+  if (status === 'blocked') {
+    // Already out of the pool with a blocker on it. Filing a second one would
+    // just be noise, and the loop will skip it on the next pick either way.
+    return {
+      ...none, verified: false, shape: 'blocked', status,
+      reason: 'the task is blocked — it is already out of the claimable pool',
+      remedy: 'resolve the blocker that is on it',
+    };
+  }
+
+  // `ready`, `backlog`, or anything a future migration adds. The worker either
+  // released the claim itself or never took it. Still not shipped, so it still
+  // gets a blocker: a task a worker could not finish will be picked straight back
+  // up next iteration otherwise, and fail the same way, for the whole window.
+  return {
+    ...none, verified: false, shape: 'not_started', status, fileBlocker: true, linkBlocker: true,
+    reason: `the worker returned with the task back at '${status}' — no work was recorded against it`,
+    remedy: 'read the worker output in the run log before re-queueing it',
+  };
+}
+
+// blockerFor — the row a shape becomes. Pure, so the wording is testable.
+//
+// `source_ref` is the DEDUPE KEY: POST /blockers has ON CONFLICT (source,
+// source_ref) DO NOTHING, so a second failure of the SAME shape on the SAME task
+// is skipped rather than piling up a column of identical blockers. The shape is
+// part of the key on purpose — a task that fails a DIFFERENT way is a different
+// fact and deserves to be said out loud.
+function blockerFor(v, { taskId, taskTitle = null, worker = null } = {}) {
+  const lines = [
+    `Autobongos verified task ${taskId} against the ledger after its worker exited, and it is not shipped.`,
+    '',
+    `**Ledger status:** \`${v.status || 'unreadable'}\`  ·  **shape:** \`${v.shape}\``,
+    `**What that means:** ${v.reason}`,
+  ];
+  if (v.strandReason) lines.push(`**Reconciler recorded:** \`${v.strandReason}\``);
+  if (worker && worker.outcome) {
+    lines.push('', `**What the worker reported:** \`${worker.outcome}\`${worker.reason ? ` — ${String(worker.reason).slice(0, 400)}` : ''}`);
+  }
+  if (v.remedy) lines.push('', `**Next:** ${v.remedy}`);
+  lines.push('', 'Filed by `scripts/gds/autobongos-verify.js`. The supervisor reads completion from Bongos, never from the session — a session exiting is not a task shipping (ADR 0307 §4).');
+
+  return {
+    title: `Autobongos: task ${taskId} came back ${v.shape}${taskTitle ? ` — ${String(taskTitle).slice(0, 120)}` : ''}`.slice(0, 200),
+    body_md: lines.join('\n'),
+    source: 'autobongos',
+    source_ref: `task-${taskId}-${v.shape}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The I/O half
+// ---------------------------------------------------------------------------
+
+const runGit = (args, cwd) => new Promise((resolve) => {
+  execFile('git', args, { cwd, maxBuffer: 4 * 1024 * 1024 },
+    (err, stdout, stderr) => resolve({ ok: !err, stdout: stdout || '', stderr: stderr || '' }));
+});
+
+// probeArtifact — is there ANY trace of this task on main?
+//
+// Deliberately weak and deliberately cheap. It answers "is there a trace", not
+// "which commit is it": a body mention counts, because the question being asked
+// is the 1002459 question — was anything at all produced. The fixed-string grep
+// is against `(task N)`, the convention every ship commit follows.
+//
+// A probe that could not run returns `checked: false`, which classifyLedger
+// treats as no evidence either way.
+async function probeArtifact(taskId, { git = runGit, cwd = REPO_ROOT } = {}) {
+  const id = String(taskId);
+  if (!/^\d{1,19}$/.test(id)) return { checked: false, reason: 'task id is not a plain number' };
+
+  const fetched = await git(['fetch', '-q', 'origin', 'main'], cwd);
+  if (!fetched.ok) {
+    return { checked: false, reason: `git fetch failed: ${(fetched.stderr || '').trim().slice(-200)}` };
+  }
+  const log = await git(['log', 'FETCH_HEAD', '--max-count=5', '--format=%H %s', '-F', `--grep=(task ${id})`], cwd);
+  if (!log.ok) return { checked: false, reason: `git log failed: ${(log.stderr || '').trim().slice(-200)}` };
+
+  const first = log.stdout.split('\n').find((l) => l.trim());
+  if (!first) return { checked: true, onMain: false, sha: null, subject: null };
+  const sp = first.indexOf(' ');
+  return { checked: true, onMain: true, sha: first.slice(0, sp < 0 ? first.length : sp), subject: sp < 0 ? null : first.slice(sp + 1) };
+}
+
+// fetchTask returns the row or null, and says WHY on a null. The reason is the
+// only thing a person reading the run log afterwards has to go on — "undetermined"
+// alone cannot tell an expired session from an unreachable instance.
+async function fetchTask(api, taskId) {
+  try {
+    const r = await api.tasks.getTasksId({ id: Number(taskId) });
+    if (!r || !r.ok) return { task: null, error: `GET /tasks/${taskId} → ${r ? r.status : 'no response'}` };
+    const task = r.data && r.data.task;
+    return task ? { task } : { task: null, error: `GET /tasks/${taskId} returned no task` };
+  } catch (e) { return { task: null, error: e && e.message ? e.message : String(e) }; }
+}
+
+// fileBlocker — create the row, then link it to the task.
+//
+// The two steps are separate calls and the SECOND one is what actually takes the
+// task out of the pool: POST /blockers only creates a row, and claimable_tasks
+// excludes a task through `task_blockers`, not through the blockers table. A
+// blocker filed and never linked is a note nobody reads.
+//
+// The link is rank-gated (metic+, `blocker.review`), while filing is open to any
+// builder. A runner below that rank still gets the blocker written down; the
+// result says the link did not happen rather than pretending it did.
+async function fileBlocker(api, row, { taskId, link }) {
+  let created = null;
+  try {
+    const r = await api.blockers.postBlockers({ body: row });
+    if (!r || !r.ok) return { filed: false, reason: `POST /blockers → ${r ? r.status : 'no response'}`, linked: false };
+    if (r.data && r.data.skipped) return { filed: false, duplicate: true, reason: 'this task already carries a blocker of this shape', linked: false };
+    created = r.data && r.data.blocker;
+  } catch (e) { return { filed: false, reason: e && e.message ? e.message : String(e), linked: false }; }
+
+  if (!created || !created.id) return { filed: false, reason: 'POST /blockers returned no blocker', linked: false };
+  if (!link) return { filed: true, blockerId: created.id, linked: false };
+
+  try {
+    const r = await api.blockers.postBlockersIdLink({ id: Number(created.id), body: { task_id: Number(taskId) } });
+    // `blocked` is the server saying whether the task actually MOVED. It answers
+    // false when the task was not at `ready` — a dead link loop went unnoticed for
+    // six weeks on exactly that (task 1002559), so it is reported, not discarded.
+    return { filed: true, blockerId: created.id, linked: !!(r && r.ok), parked: !!(r && r.ok && r.data && r.data.blocked) };
+  } catch (e) { return { filed: true, blockerId: created.id, linked: false, reason: e && e.message ? e.message : String(e) }; }
+}
+
+// verifyShip — the whole step, in the order the order matters.
+//
+// RELEASE BEFORE LINK, always. linkBlockerToTask() parks the task only when it is
+// at `ready`; releasing is what puts it there. Link first and the row is written,
+// the task is not parked, and the release then hands it back to the pool — the
+// loop picks the same doomed task up next iteration and burns the window on it.
+async function verifyShip({ taskId, taskTitle = null, worker = null }, deps = {}) {
+  const api = deps.api || await (require('./cli-lib').cliClient)();
+  const probe = deps.probeArtifact || probeArtifact;
+  const release = deps.release || null;
+  const file = deps.fileBlocker || fileBlocker;
+  const act = deps.act !== false;
+
+  let task = deps.task;
+  let readError = null;
+  if (task === undefined) ({ task, error: readError } = await fetchTask(api, taskId));
+
+  // The artifact probe only earns its network round-trip when the ledger claims
+  // success. Every other shape is already not-shipped; what is on main cannot
+  // change that.
+  let artifact = null;
+  if (task && String(task.status) === 'shipped') {
+    artifact = await probe(taskId, { cwd: deps.cwd || REPO_ROOT });
+  }
+
+  const v = classifyLedger({ task, artifact, nowMs: deps.nowMs || Date.now() });
+  const out = { ...v, task_id: String(taskId), artifact, released: false, blocker: null };
+  if (readError) out.read_error = readError;
+  if (!act) return out;
+
+  if (v.releaseClaim) {
+    // A caller that forgot to hand over a release function must not read as "no
+    // release was needed". Silently skipping the one write that unlocks a task is
+    // precisely the class of failure this whole step exists to catch.
+    if (!release) out.release_error = 'no release function was given to verifyShip — the claim is still held';
+    else {
+      const r = await release(taskId, `autobongos: ${v.shape} — ${String(v.reason || '').slice(0, 180)}`);
+      out.released = !!(r && r.ok);
+      if (!out.released) out.release_error = (r && (r.stderr || r.stdout) ? String(r.stderr || r.stdout).slice(-300) : 'release failed');
+    }
+  }
+
+  if (v.fileBlocker) {
+    out.blocker = await file(api, blockerFor(v, { taskId, taskTitle: taskTitle || (task && task.title), worker }), {
+      taskId,
+      // Linking is only worth attempting where it can park the task. A shipped or
+      // mid-ship task is not claimable anyway, so a link there writes a row that
+      // changes nothing and muddies the blocker board.
+      link: v.linkBlocker && (out.released || String(v.status) === 'ready'),
+    });
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+async function main(argv) {
+  const taskId = argv.find((a) => /^\d+$/.test(a));
+  if (!taskId) {
+    console.error('usage: node scripts/gds/autobongos-verify.js <task-id> [--act] [--json]');
+    return 2;
+  }
+  const act = argv.includes('--act');
+  const release = async (id, reason) => new Promise((resolve) => {
+    execFile(process.execPath, [path.join(REPO_ROOT, 'scripts', 'gds', 'release.js'), String(id), '--reason', reason],
+      { cwd: REPO_ROOT }, (err, stdout, stderr) => resolve({ ok: !err, stdout: stdout || '', stderr: stderr || '' }));
+  });
+
+  const out = await verifyShip({ taskId }, { act, release });
+  if (argv.includes('--json')) { console.log(JSON.stringify(out, null, 2)); }
+  else {
+    console.log('');
+    console.log(`  task ${taskId}  ledger says: ${out.status || 'unreadable'}  →  ${out.shape}`);
+    console.log(`  ${out.reason}`);
+    if (out.remedy) console.log(`  next: ${out.remedy}`);
+    if (out.artifact && out.artifact.checked === false) console.log(`  (artifact not probed: ${out.artifact.reason})`);
+    if (out.released) console.log('  claim released');
+    if (out.blocker) console.log(`  blocker: ${out.blocker.filed ? `#${out.blocker.blockerId}${out.blocker.parked ? ' (task parked at blocked)' : out.blocker.linked ? ' (linked)' : ' (not linked)'}` : `not filed — ${out.blocker.reason}`}`);
+    if (!act && (out.releaseClaim || out.fileBlocker)) console.log('  (read-only — pass --act to release and file)');
+    console.log('');
+  }
+  return out.shape === 'undetermined' ? 2 : (out.verified ? 0 : 1);
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((c) => process.exit(c)).catch((e) => {
+    console.error(`autobongos-verify: ${e && e.message ? e.message : e}`);
+    process.exit(2);
+  });
+}
+
+module.exports = { classifyLedger, blockerFor, probeArtifact, fileBlocker, verifyShip };

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

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/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/gds/autonomy-gauge.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/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/gds/autonomy-gauge.js            # human-readable
+//   node scripts/gds/autonomy-gauge.js --json     # machine-readable
+//   node scripts/gds/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 };