@bongos/core 1.19.876 → 1.19.878

package/modules/autonomy/digest.js

@@ -0,0 +1,344 @@
+'use strict';
+
+// modules/autonomy/digest.js — the night, readable afterwards (task 1003906,
+// ADR 0307). Pure: rows in, a digest out. No I/O, no clock of its own.
+//
+// THE OWNER IS NOT AT THE KEYBOARD. That is the whole premise, and it means the
+// run log — an append-only JSONL nobody will ever open — is not an answer. One
+// page has to answer five questions, and it has to answer them without anyone
+// reading a log: what shipped, what is on hold and why, what each worker decided
+// that its task description did not determine, what it cost, and where the two
+// limit windows stand.
+//
+// THE THIRD QUESTION IS THE ONE THAT COMPOUNDS, and it is worth saying why it is
+// here at all. A worker will NOT reliably stop to ask: tested on an ambiguous
+// task, it made four genuine judgement calls and wrote them straight into the
+// file, which is what a competent engineer does with an under-specified brief.
+// So the decisions happen either way. What the digest changes is whether anyone
+// finds out. And every entry is also a sentence the task description SHOULD have
+// contained — which makes this list a spec-quality signal, not just an audit
+// trail: the goals whose decisions pile up are the goals whose specs are thin,
+// and fixing those is what lowers tomorrow's halt count.
+//
+// WHAT COUNTS AS SHIPPED IS THE LEDGER'S ANSWER, never the worker's. A `worked`
+// row with `verified: false` is a task that ran and did not ship, and putting it
+// under "shipped" because a session ended would reintroduce the exact confusion
+// task 1003903 exists to end.
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const isRow = (r) => r && typeof r === 'object' && typeof r.event === 'string';
+
+// num — a number, or null for "not a number I can use".
+//
+// THE GUARD ON null IS LOAD-BEARING, and it is not defensive noise:
+// `Number(null)` is 0 and 0 is finite, so the obvious one-liner turns every
+// absent cost into a free worker and every absent duration into an instant one.
+// The same trap cost a bug in modules/autonomy/cadence.js's fingerprint, where an
+// unread claimable count became the literal string "null" for the same reason.
+// Empty string behaves identically. Both are spelled out rather than trusted to
+// Number().
+const num = (v) => {
+  if (v === null || v === undefined || v === '') return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+function parseAt(row) {
+  const t = Date.parse(row && row.at);
+  return Number.isFinite(t) ? t : null;
+}
+
+// humanDuration — minutes and hours, the way a person says them.
+function humanDuration(s) {
+  const n = num(s);
+  if (n === null || n < 0) return null;
+  if (n < 90) return `${Math.round(n)}s`;
+  if (n < 5400) return `${Math.round(n / 60)}m`;
+  return `${(n / 3600).toFixed(1)}h`;
+}
+
+function usd(n) {
+  const v = num(n);
+  return v === null ? null : `$${v.toFixed(2)}`;
+}
+
+// windowsFromGauge — question five, from the gauge file's own shape.
+//
+// Reports what it can SEE and says so when it cannot. A digest that silently
+// omits a window reads as "nothing to report", and the one morning that matters
+// is the morning the gauge stopped being written.
+// STALENESS IS GAUGE.JS'S RULE, NOT A SECOND ONE. modules/autonomy/gauge.js holds
+// a window UNKNOWN when its `observed_at` is older than staleAfterS (30 minutes
+// by default), and the runner HOLDS on unknown. A digest that applied a laxer
+// test would print "41% used, resets in 2h" about a window the runner had already
+// decided it could not vouch for — two surfaces disagreeing about one file, with
+// the reader believing the one that is wrong. Same threshold, same conclusion.
+// (Grader finding, task 1003906.)
+function windowsFromGauge(gauge, nowEpochS, { staleAfterS = null } = {}) {
+  const limit = staleAfterS === null ? require('./gauge.js').DEFAULT_STALE_AFTER_S : staleAfterS;
+  const writtenAt = gauge && typeof gauge === 'object' ? num(gauge.written_at) : null;
+  const one = (key, label) => {
+    const w = gauge && typeof gauge === 'object' ? gauge[key] : null;
+    const used = w ? num(w.used_percentage) : null;
+    const resets = w ? num(w.resets_at) : null;
+    // Per-window observed_at, falling back to the file's written_at — exactly the
+    // shape gauge.js reads, because one window can go unreported while the other
+    // is carried forward.
+    const observedAt = w ? (num(w.observed_at) ?? writtenAt) : null;
+    if (used === null) return { key, label, known: false, detail: 'not reported' };
+
+    const ageS = observedAt !== null && Number.isFinite(nowEpochS) ? nowEpochS - observedAt : null;
+    if (ageS !== null && ageS > limit) {
+      return {
+        key, label, known: false, stale: true, usedPct: Math.round(used), resetsAt: resets, ageS,
+        detail: `last read ${Math.round(used)}% used ${humanDuration(ageS)} ago — older than the runner trusts, so it is holding`,
+      };
+    }
+    const ahead = resets !== null && Number.isFinite(nowEpochS) ? resets - nowEpochS : null;
+
+    // A RESET TIME IN THE PAST MEANS THE READING IS STALE, not that the window is
+    // about to turn over. The percentage was true of a window that has since
+    // rolled, so printing it as a live figure is worse than printing nothing —
+    // "41% used, resets in 0s" invites a decision about headroom that no longer
+    // exists. Say the reading is old and let the reader go look.
+    if (ahead !== null && ahead <= 0) {
+      return {
+        key, label, known: false, stale: true, usedPct: Math.round(used), resetsAt: resets, resetsInS: 0,
+        detail: `last read ${Math.round(used)}% used, but that window has since reset — the gauge is stale`,
+      };
+    }
+    return {
+      key, label, known: true, usedPct: Math.round(used),
+      resetsAt: resets, resetsInS: ahead,
+      detail: `${Math.round(used)}% used${ahead !== null ? `, resets in ${humanDuration(ahead)}` : ''}`,
+    };
+  };
+  return [one('five_hour', 'Five-hour window'), one('seven_day', 'Seven-day window')];
+}
+
+// ---------------------------------------------------------------------------
+// The digest
+// ---------------------------------------------------------------------------
+
+// buildDigest — every question answered from the rows, or explicitly unanswered.
+//
+// `rows` is the run log for the period, oldest first. `gauge` is the raw gauge
+// file (the same shape modules/autonomy/gauge.js reads). Unrecognised rows are
+// COUNTED rather than dropped: a digest that silently ignores what it does not
+// understand is how a new failure mode stays invisible for a week.
+function buildDigest(rows = [], { gauge = null, nowEpochS = null, sinceMs = null, untilMs = null, staleAfterS = null } = {}) {
+  const all = (Array.isArray(rows) ? rows : []).filter(isRow);
+  const worked = all.filter((r) => r.event === 'worked');
+
+  // 1. WHAT SHIPPED — the ledger's answer.
+  const shipped = worked.filter((r) => r.verified === true).map((r) => ({
+    taskId: String(r.task_id ?? ''), title: r.title || null, goalId: r.goal_id ?? null,
+    durationS: num(r.duration_s), costUsd: num(r.cost_usd),
+  }));
+
+  // 2. WHAT IS ON HOLD, AND WHY. Four different shapes of "did not ship", kept
+  // apart because the owner's next action differs for each.
+  const ranButDidNotShip = worked.filter((r) => r.verified !== true).map((r) => ({
+    taskId: String(r.task_id ?? ''), title: r.title || null,
+    shape: r.ledger_shape || 'unknown',
+    // THE LEDGER'S REASON FIRST, and the worker's only as a fallback. `row.reason`
+    // is verdict.reason — the WORKER's account of itself — and quoting that in the
+    // "did not ship" section is the precise inversion this whole goal exists to
+    // undo: a worker that stopped dead needing a decision reports success. The
+    // ledger's explanation ("the grade passed and the land never finished") is the
+    // one a person can act on. Older rows predate ledger_reason, so the fallback
+    // stays rather than leaving them blank.
+    reason: r.ledger_reason || r.reason || null,
+    remedy: r.ledger_remedy || null,
+    workerSaid: r.reason || null,
+    blockerId: r.blocker_id ?? null,
+    parked: !!r.task_parked,
+    claimReleased: !!r.claim_released,
+  }));
+
+  const fenced = all.filter((r) => r.event === 'fenced').map((r) => ({
+    code: r.code || 'unknown', reason: r.reason || null, taskId: r.task_id ? String(r.task_id) : null,
+  }));
+
+  // An UNWORKABLE QUEUE is not breakage, and the digest must not present it as
+  // such: the machine is healthy and there is nothing it may work on.
+  const unworkable = [];
+  for (const r of all) {
+    if (r.event !== 'nothing_claimable') continue;
+    for (const sk of (Array.isArray(r.skipped) ? r.skipped : [])) {
+      unworkable.push({ taskId: String(sk.id ?? ''), goalId: sk.goal_id ?? null, reasons: sk.reasons || [] });
+    }
+  }
+
+  const held = all.filter((r) => r.event === 'hold').map((r) => ({ reason: r.reason || null, sleepUntil: r.sleep_until ?? null }));
+
+  // 3. WHAT EACH WORKER DECIDED that its spec did not determine — grouped by task,
+  // because the SHAPE of this list is the signal. One task with six decisions is a
+  // thin spec; six tasks with one each is a normal night.
+  const decisions = [];
+  for (const r of worked) {
+    const list = Array.isArray(r.undetermined_decisions) ? r.undetermined_decisions : [];
+    if (!list.length) continue;
+    decisions.push({
+      taskId: String(r.task_id ?? ''), title: r.title || null, goalId: r.goal_id ?? null,
+      shipped: r.verified === true,
+      decisions: list.map((d) => String(d)),
+    });
+  }
+  const decisionCount = decisions.reduce((n, d) => n + d.decisions.length, 0);
+  // The thinnest spec of the night, named. A list is browsable; a name is
+  // actionable, and this one is the sentence the description should have carried.
+  const thinnestSpec = decisions.slice().sort((a, b) => b.decisions.length - a.decisions.length)[0] || null;
+
+  // 4. WHAT IT COST. Nulls are EXCLUDED and counted, never coerced to zero — a
+  // worker whose cost was not reported must not make the night look cheaper.
+  const costs = worked.map((r) => num(r.cost_usd));
+  const knownCosts = costs.filter((c) => c !== null);
+  const cost = {
+    totalUsd: knownCosts.reduce((a, b) => a + b, 0),
+    reported: knownCosts.length,
+    unreported: costs.length - knownCosts.length,
+    workerRuns: worked.length,
+    totalDurationS: worked.reduce((a, r) => a + (num(r.duration_s) || 0), 0),
+  };
+
+  // 5. THE TWO LIMIT WINDOWS.
+  const windows = windowsFromGauge(gauge, nowEpochS, { staleAfterS });
+
+  // How the runner spent the night, so "nothing shipped" can be told apart from
+  // "nothing ran".
+  const KNOWN = new Set(['worked', 'fenced', 'hold', 'nothing_claimable', 'dry_run',
+    'pick_failed', 'worktree_failed', 'claim_failed', 'verify_halt', 'cadence', 'boot_reconcile']);
+  const byEvent = {};
+  let unrecognised = 0;
+  for (const r of all) {
+    byEvent[r.event] = (byEvent[r.event] || 0) + 1;
+    if (!KNOWN.has(r.event)) unrecognised += 1;
+  }
+
+  const cadenceRows = all.filter((r) => r.event === 'cadence' && r.mode);
+  const endedProbing = cadenceRows.length ? cadenceRows[cadenceRows.length - 1].mode === 'probing' : false;
+
+  // reduce, not Math.min(...times): `--all` on a long-lived log can hold more
+  // timestamps than the engine will accept as call arguments, and a reporting CLI
+  // that throws on a big log fails exactly when the log is most worth reading.
+  const times = all.map(parseAt).filter((t) => t !== null);
+  const minAt = times.length ? times.reduce((a, b) => (b < a ? b : a)) : null;
+  const maxAt = times.length ? times.reduce((a, b) => (b > a ? b : a)) : null;
+  return {
+    period: {
+      fromMs: sinceMs ?? minAt,
+      toMs: untilMs ?? maxAt,
+      rows: all.length,
+    },
+    shipped,
+    onHold: { ranButDidNotShip, fenced, unworkable, held },
+    decisions, decisionCount, thinnestSpec,
+    cost,
+    windows,
+    runner: { byEvent, unrecognised, endedProbing, bootReconciles: byEvent.boot_reconcile || 0 },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+// renderDigest — the five questions, in the order they are asked, as plain text a
+// person reads over coffee. Deliberately not a table: the widths are unknowable
+// and a wrapped table is worse than prose.
+//
+// EVERY SECTION PRINTS, even when empty. A digest whose quiet sections vanish
+// teaches its reader that absence means "fine", and then the one morning a
+// section is missing because the DATA is missing reads exactly the same.
+function renderDigest(d, { title = 'Autobongos — overnight' } = {}) {
+  const L = [];
+  const when = d.period.fromMs && d.period.toMs
+    ? `${new Date(d.period.fromMs).toISOString().slice(0, 16).replace('T', ' ')} → ${new Date(d.period.toMs).toISOString().slice(11, 16)} UTC`
+    : 'no runs recorded';
+  L.push(title, '='.repeat(title.length), when, '');
+
+  // 1
+  L.push(`SHIPPED — ${plural(d.shipped.length, 'task', 'tasks')}`);
+  if (!d.shipped.length) L.push('  nothing shipped.');
+  for (const s of d.shipped) {
+    L.push(`  ${s.taskId}  ${s.title || '(untitled)'}`);
+    const bits = [humanDuration(s.durationS), usd(s.costUsd)].filter(Boolean);
+    if (bits.length) L.push(`         ${bits.join(' · ')}`);
+  }
+  L.push('');
+
+  // 2
+  const holdTotal = d.onHold.ranButDidNotShip.length + d.onHold.fenced.length + d.onHold.unworkable.length + d.onHold.held.length;
+  L.push(`ON HOLD — ${plural(holdTotal, 'thing', 'things')}`);
+  if (!holdTotal) L.push('  nothing is waiting on you.');
+  for (const r of d.onHold.ranButDidNotShip) {
+    L.push(`  ${r.taskId}  ran but did not ship — ${r.shape}`);
+    if (r.reason) L.push(`         ${String(r.reason).slice(0, 160)}`);
+    if (r.remedy) L.push(`         next: ${String(r.remedy).slice(0, 160)}`);
+    // Printed only when it ADDS something. A worker that agreed with the ledger
+    // tells the reader nothing twice; one that claimed success against a ledger
+    // that says otherwise is the single most useful line on the page.
+    if (r.workerSaid && r.workerSaid !== r.reason) L.push(`         the worker said: ${String(r.workerSaid).slice(0, 160)}`);
+    if (r.blockerId) L.push(`         blocker ${r.blockerId}${r.parked ? ' (task parked, out of the queue)' : ''}`);
+  }
+  // Fenced refusals are collapsed by code: twenty identical lines say nothing the
+  // first one did not.
+  const byCode = {};
+  for (const f of d.onHold.fenced) (byCode[f.code] = byCode[f.code] || []).push(f);
+  for (const [code, list] of Object.entries(byCode)) {
+    L.push(`  fence: ${code} ×${list.length}`);
+    if (list[0].reason) L.push(`         ${String(list[0].reason).slice(0, 160)}`);
+  }
+  if (d.onHold.unworkable.length) {
+    L.push(`  queue: ${plural(d.onHold.unworkable.length, 'task', 'tasks')} in the allowlist, every one halted`);
+    L.push('         (this is not a runner failure — it has nothing it may work on)');
+    for (const u of d.onHold.unworkable.slice(0, 5)) L.push(`         ${u.taskId}: ${(u.reasons || []).join(', ') || 'halted'}`);
+  }
+  if (d.onHold.held.length) L.push(`  capacity: held ${plural(d.onHold.held.length, 'time', 'times')} — ${d.onHold.held[0].reason || 'no headroom'}`);
+  L.push('');
+
+  // 3 — the one that compounds.
+  L.push(`DECIDED FOR YOU — ${plural(d.decisionCount, 'decision', 'decisions')} across ${plural(d.decisions.length, 'task', 'tasks')}`);
+  if (!d.decisionCount) {
+    L.push('  no worker had to fill a gap in its spec.');
+  } else {
+    L.push('  Each line is a sentence the task description should have contained.');
+    for (const t of d.decisions) {
+      L.push(`  ${t.taskId}  ${t.title || '(untitled)'}${t.shipped ? '' : '  [did not ship]'}`);
+      for (const one of t.decisions) L.push(`       · ${one}`);
+    }
+    if (d.thinnestSpec && d.thinnestSpec.decisions.length > 1) {
+      L.push('');
+      L.push(`  Thinnest spec: ${d.thinnestSpec.taskId} (${d.thinnestSpec.decisions.length} decisions).`);
+      L.push('  Tightening that description is what lowers tomorrow’s halts.');
+    }
+  }
+  L.push('');
+
+  // 4
+  L.push('COST');
+  L.push(`  ${usd(d.cost.totalUsd)} across ${plural(d.cost.workerRuns, 'worker run', 'worker runs')}` +
+    (d.cost.unreported ? ` (${d.cost.unreported} did not report a cost)` : ''));
+  if (d.cost.totalDurationS) L.push(`  ${humanDuration(d.cost.totalDurationS)} of worker time`);
+  L.push('');
+
+  // 5
+  L.push('LIMITS');
+  for (const w of d.windows) L.push(`  ${w.label.padEnd(18)} ${w.detail}`);
+  L.push('');
+
+  // The footer answers "did it run at all", which none of the five questions do.
+  const events = Object.entries(d.runner.byEvent).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k} ${n}`).join(' · ');
+  L.push(`RUNNER  ${events || 'no rows'}`);
+  if (d.runner.endedProbing) L.push('  Ended the night PROBING — it hit repeated failures and slowed itself down.');
+  if (d.runner.unrecognised) L.push(`  ${plural(d.runner.unrecognised, 'row', 'rows')} of a kind this digest does not know about.`);
+  return L.join('\n');
+}
+
+module.exports = { buildDigest, renderDigest, windowsFromGauge, humanDuration };

package/modules/autonomy/migrations/autonomy_002_runner_heartbeat.sql

@@ -0,0 +1,93 @@
+-- autonomy_002_runner_heartbeat.sql — a dead runner must be VISIBLE, not silent
+-- (task 1003905, ADR 0307 §5).
+--
+-- WHY THE SERVER HAS TO HOLD THIS. autonomy_001 gave the owner a switch the
+-- machine can read and cannot write. This is the same argument pointed the other
+-- way: the owner needs to see the machine, and a status written only on the
+-- machine is invisible on precisely the day it matters — the day the machine is
+-- off, unplugged, or wedged. The runner writes a local heartbeat file too
+-- (scripts/gds/autobongos-run.js, the guard against two runners fighting over one
+-- claim), but that file cannot be read from a web page in another country. This
+-- table can.
+--
+-- SILENCE IS THE SIGNAL, which is why the row records a TIME and not a state.
+-- A "status: running" column would be written by a healthy runner and then left
+-- untouched by a dead one, so it would read "running" forever — exactly the class
+-- of lie provisioning_006 was written to end ("status records what the runner DID,
+-- not what the instance actually does"). Only `last_seen_at` can go stale on its
+-- own, so only `last_seen_at` can tell the truth without being told.
+--
+-- NO ROW MEANS NEVER SEEN, and that is a third answer, not a missing one. A
+-- runner that has never checked in and a runner that checked in yesterday and
+-- stopped need different words from the hall — "not set up yet" versus "it died".
+-- Same distinction provisioning_006 draws between NULL and false.
+--
+-- KEYED BY (builder_id, host), AND THE BUILDER HALF IS A SECURITY BOUNDARY, not
+-- bookkeeping. With `host` alone as the key, any authenticated builder could POST
+-- a heartbeat naming the real runner's hostname and keep the liveness signal
+-- reading "alive" forever — defeating the exact property this table exists for,
+-- which is that a dead machine holding broad spawn permissions becomes VISIBLE.
+-- An ownership check in the handler would also close it, and would be one `if`
+-- away from being removed by a later edit that looked reasonable. Putting the
+-- caller in the KEY makes the forgery structurally impossible instead: a stranger
+-- writing "winbox" writes THEIR OWN row and cannot touch the owner's. (Found by
+-- the grader's security worker on task 1003905.)
+--
+-- A singleton was the other option and is worse for a second reason: one row per
+-- host means a second runner shows up as a second row instead of silently
+-- overwriting the first, which is the failure a singleton discovers at the worst
+-- possible moment.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): every
+-- object is autonomy_-prefixed, there is no down-migration, and the filename is
+-- autonomy_-prefixed (ADR 0108 §5). Idempotent: safe to re-run.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS autonomy_runner_heartbeat (
+  -- WHO is reporting. Half the primary key — see the header: this is what makes a
+  -- forged heartbeat impossible rather than merely checked for.
+  builder_id           bigint NOT NULL,
+  -- The machine's own name for itself (os.hostname()). Lowercased by the writer
+  -- so one host cannot appear twice under two spellings.
+  host                 text NOT NULL,
+  pid                  integer,
+  -- THE ONLY LOAD-BEARING COLUMN. Everything else is colour for the hall.
+  last_seen_at         timestamptz NOT NULL DEFAULT now(),
+  -- When this process started, so the hall can say "up 3 days" and a restart loop
+  -- is visible as a start time that keeps moving.
+  started_at           timestamptz,
+  -- The cadence, verbatim from modules/autonomy/cadence.js: 'full' | 'probing'.
+  -- Free text rather than an enum: the vocabulary lives in that file, and a CHECK
+  -- here would mean a schema migration every time it gains a word.
+  mode                 text,
+  consecutive_failures integer,
+  -- The last run-log event, so "last seen 4 minutes ago" can be followed by WHAT
+  -- it was doing. A runner quiet because it is mid-worker and one quiet because it
+  -- is wedged look identical without this.
+  last_event           text,
+  -- The task a worker is building, when there is one. A long gap is EXPECTED while
+  -- a worker runs (they may take an hour and a half), and without this the hall
+  -- would cry dead every time the runner did its job.
+  working_task_id      bigint,
+  updated_at           timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (builder_id, host)
+);
+
+-- ON RE-RUNNING THIS AGAINST A TABLE THAT ALREADY EXISTS IN A DIFFERENT SHAPE:
+-- it would not be corrected, and that is deliberate rather than overlooked. An
+-- earlier cut of this same file keyed the table on `host` alone, and the obvious
+-- repair -- detect the old key, DROP CONSTRAINT, re-add -- is DESTRUCTIVE DDL,
+-- which a module migration may not use (ADR 0083 section Decision #5, enforced by
+-- fitness.js: "disabling a module stops applying, it never drops"). It was
+-- written, it was caught by that gate, and the gate is right: a module that can
+-- drop things on its way in is a module that can take a host's data with it.
+--
+-- The reason it is safe to leave is narrower than "nobody will hit it". This
+-- table is NEW in an UNRELEASED task -- no published core version contains it, so
+-- no instance can have applied any shape of it. The only databases that ever saw
+-- the host-only version were throwaway probes on the author's machine, since
+-- deleted. If that ever stops being true, the fix is a NEW additive migration,
+-- not an edit here. (Grader finding, task 1003905.)
+
+COMMIT;

package/modules/autonomy/routes/autonomy.js

@@ -28,6 +28,7 @@ const auth = api;
 // neither core internals nor a sibling module, so importing it here is allowed.
 const autonomyGate = require('../../../scripts/gds/autonomy-gate');
 const db = require('../db');
+const runnerHealth = require('../runner-health');
 // The doorway's namespaced logger and strict body validator. Raw console.* is
 // ratcheted repo-wide (fitness.js console_call_count) and unstructured besides.
 const log = api.logger('autonomy');
@@ -143,5 +144,73 @@ module.exports = function buildAutonomyRouter() {
     }
   });
 
+  // ── the runner heartbeat (task 1003905) ────────────────────────────────────
+  //
+  // A dead runner must be VISIBLE, not silent. The runner also writes a heartbeat
+  // FILE on its own host — that one stops two runners fighting over a claim — but
+  // a file on the machine is unreadable on exactly the day it matters, the day
+  // the machine is off. This pair is the half the owner can see from a web page.
+
+  // The runner's check-in, once per loop. ANY-BUILDER is safe because the row is
+  // keyed by the CALLER: a stranger reporting "winbox" writes their own row and
+  // cannot touch the owner's, so the liveness signal cannot be forged into reading
+  // alive. Keeping the bar low matters — the failure mode of a refused heartbeat
+  // is a healthy runner reported dead.
+  router.post('/autonomy/heartbeat', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      host: { required: true, type: 'string', maxLength: 255, minLength: 1 },
+      pid: { type: 'number' },
+      started_at: { type: 'string', maxLength: 64 },
+      mode: { type: 'string', maxLength: 32 },
+      consecutive_failures: { type: 'number' },
+      last_event: { type: 'string', maxLength: 64 },
+      working_task_id: { type: 'number' },
+    })) return;
+    const b = req.body || {};
+    try {
+      const row = await db.recordRunnerHeartbeat({
+        // From the SESSION, never the body. A caller cannot name someone else's
+        // runner, because the row they write is keyed by who they are.
+        builderId: req.builder.id,
+        host: b.host,
+        pid: Number.isInteger(b.pid) ? b.pid : null,
+        startedAt: b.started_at || null,
+        mode: b.mode || null,
+        consecutiveFailures: Number.isInteger(b.consecutive_failures) ? b.consecutive_failures : null,
+        lastEvent: b.last_event || null,
+        workingTaskId: Number.isInteger(b.working_task_id) ? b.working_task_id : null,
+      });
+      res.json({ ok: true, heartbeat: row });
+    } catch (err) {
+      // FAIL SOFT, and deliberately unlike the fence's GET. A heartbeat that
+      // cannot be written is a monitoring gap; turning it into an error the runner
+      // has to handle would let the watching mechanism take down the thing it
+      // watches. The gap shows up on its own — as silence, which is the signal.
+      log.error('[gds] POST /autonomy/heartbeat', err);
+      res.fail('heartbeat_write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // What the hall renders: the CALLER'S OWN runners, with the pure verdict attached
+  // so the page and any future alert cannot disagree about what "dead" means. A
+  // row names a machine, its hostname and a pid — the caller's infrastructure, and
+  // nobody else's business.
+  router.get('/autonomy/runners', auth.requireBuilder, async (req, res) => {
+    try {
+      const rows = await db.readRunnerHeartbeats(req.builder.id);
+      const nowMs = Date.now();
+      res.json({
+        // An EMPTY list is the honest answer for "nobody has ever checked in" —
+        // never_seen is a third state, not a missing one, so no row is fabricated
+        // to stand in for it.
+        runners: rows.map((r) => ({ ...r, health: runnerHealth.describeRunner(r, { nowMs }) })),
+        none: runnerHealth.describeRunner(null, { nowMs }),
+      });
+    } catch (err) {
+      log.error('[gds] GET /autonomy/runners', err);
+      res.fail('runners_unreadable', { status: 503, message: 'could not read the runner heartbeats' });
+    }
+  });
+
   return router;
 };

package/modules/autonomy/runner-health.js

@@ -0,0 +1,97 @@
+'use strict';
+
+// modules/autonomy/runner-health.js — is the runner alive? (task 1003905.)
+// Pure: no I/O, no clock of its own. `now` is injected.
+//
+// THE QUESTION THIS ANSWERS IS ASYMMETRIC, and that is the whole design. A
+// running machine can say so; a dead one cannot say anything. So the signal is
+// not a status the runner writes — a dead runner leaves "running" on the screen
+// forever — but the AGE of the last thing it said. Silence is the only report a
+// dead process can file, so silence is what this reads.
+//
+// FOUR STATES, because three of them are different kinds of quiet:
+//   · never_seen — no row at all. Not a failure: nobody has set the host up yet,
+//     and telling an owner their runner "died" before it ever ran is how a status
+//     light trains people to ignore it.
+//   · alive      — heard from within the window.
+//   · late       — quiet longer than a loop, but not longer than a WORKER. The
+//     runner legitimately goes quiet for up to the worker ceiling while doing
+//     exactly what it is for, and crying dead every time it works is worse than
+//     saying nothing.
+//   · dead       — quiet longer than any legitimate explanation.
+
+// Reasoned from the runner's own numbers, not picked. The loop beats at the top of
+// every pass and again on each poll inside a wait (every 60s), so a healthy runner
+// that is merely idle or backing off is never quiet for more than about a minute.
+const ALIVE_S = 15 * 60;
+// The worker wall-clock ceiling is 90 minutes (DEFAULT_WORKER_TIMEOUT_MS), and a
+// worker holds the loop for its whole run. Two hours is that ceiling plus room for
+// the ship, the grade and the verify that follow it.
+const LATE_S = 2 * 60 * 60;
+
+function ageS(lastSeenAt, nowMs) {
+  const t = Date.parse(lastSeenAt || '');
+  if (!Number.isFinite(t) || !Number.isFinite(nowMs)) return null;
+  return Math.max(0, Math.round((nowMs - t) / 1000));
+}
+
+// humanAge — the same shape strand-watch.js uses, so two surfaces describing a
+// duration do not describe it two ways.
+function humanAge(s) {
+  if (!Number.isFinite(s)) return 'unknown';
+  if (s < 90) return `${s}s`;
+  if (s < 5400) return `${Math.round(s / 60)}m`;
+  if (s < 172800) return `${Math.round(s / 3600)}h`;
+  return `${Math.round(s / 86400)}d`;
+}
+
+// describeRunner — one heartbeat row becomes one sentence the hall can print.
+//
+// `heartbeat` is null/undefined for "no row", which is never_seen. An UNPARSEABLE
+// last_seen_at is `dead`, not never_seen: a row that exists but cannot be read is
+// a runner we heard from once and cannot account for now, and the fail direction
+// on a liveness check is to raise the alarm rather than to explain it away.
+function describeRunner(heartbeat, { nowMs = Date.now(), aliveS = ALIVE_S, lateS = LATE_S } = {}) {
+  if (!heartbeat || typeof heartbeat !== 'object') {
+    return {
+      state: 'never_seen', ok: true, ageS: null, age: null,
+      detail: 'no runner has ever checked in from this instance',
+    };
+  }
+
+  const age = ageS(heartbeat.last_seen_at, nowMs);
+  if (age === null) {
+    return { state: 'dead', ok: false, ageS: null, age: 'unknown', detail: 'the runner’s last check-in cannot be read' };
+  }
+
+  const host = typeof heartbeat.host === 'string' ? heartbeat.host : null;
+  const mode = heartbeat.mode === 'probing' ? 'probing' : (heartbeat.mode === 'full' ? 'full' : null);
+  const working = heartbeat.working_task_id ? String(heartbeat.working_task_id) : null;
+  const where = host ? ` on ${host}` : '';
+
+  if (age <= aliveS) {
+    return {
+      state: 'alive', ok: true, ageS: age, age: humanAge(age), host, mode, workingTaskId: working,
+      detail: working
+        ? `working task ${working}${where}`
+        : `${mode === 'probing' ? 'probing after failures' : 'running'}${where}`,
+    };
+  }
+
+  if (age <= lateS) {
+    return {
+      state: 'late', ok: true, ageS: age, age: humanAge(age), host, mode, workingTaskId: working,
+      // Deliberately NOT an alarm. This is what a runner doing its job looks like.
+      detail: working
+        ? `quiet for ${humanAge(age)} — expected while task ${working} builds`
+        : `quiet for ${humanAge(age)} — longer than a loop, still within a worker's run`,
+    };
+  }
+
+  return {
+    state: 'dead', ok: false, ageS: age, age: humanAge(age), host, mode, workingTaskId: working,
+    detail: `no check-in for ${humanAge(age)}${where} — longer than any worker takes, so the runner is not running`,
+  };
+}
+
+module.exports = { ALIVE_S, LATE_S, ageS, humanAge, describeRunner };

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -180,8 +180,12 @@ function createClient(opts = {}) {
       postAutonomyFenceGoals: (args) => request("POST", "/autonomy/fence/goals", { hasBody: true }, args),
       // DELETE /autonomy/fence/goals/{goalId} — rank: archon — DELETE /autonomy/fence/goals/:goalId
       deleteAutonomyFenceGoalsGoalId: (args) => request("DELETE", "/autonomy/fence/goals/{goalId}", { hasBody: false }, args),
+      // POST /autonomy/heartbeat — rank: any-builder — POST /autonomy/heartbeat
+      postAutonomyHeartbeat: (args) => request("POST", "/autonomy/heartbeat", { hasBody: true }, args),
       // GET /autonomy/precheck — rank: metic+archon — GET /autonomy/precheck
       getAutonomyPrecheck: (args) => request("GET", "/autonomy/precheck", { hasBody: false }, args),
+      // GET /autonomy/runners — rank: any-builder — GET /autonomy/runners
+      getAutonomyRunners: (args) => request("GET", "/autonomy/runners", { hasBody: false }, args),
     },
     "backup": {
       // GET /backup/status — rank: metic+archon — GET /backup/status

package/modules/hall-ui/public/gate.html

@@ -52,6 +52,9 @@
           <section class="scroll" id="fence-panel" aria-labelledby="fence-h" hidden>
             <h2 class="scroll__h" id="fence-h">Autobongos runner</h2>
             <p class="scroll__lede">The unattended runner works only the goals listed here, and only while it is on. This is the switch — it lives on the server, so the machine can read it and cannot change it.</p>
+            <!-- Liveness first (task 1003905): "is it running at all" is the
+                 question before "is it allowed to run". -->
+            <div id="fence-runner"><span class="kit-skel"></span></div>
             <div id="fence-state"><span class="kit-skel"></span></div>
             <div id="fence-goals"></div>
           </section>
@@ -78,6 +81,6 @@
 <script src="/builders/palette.js" defer></script>
 <script src="/builders/dom-utils.js?v=2026-06-16-gate"></script>
 <script src="/builders/hall-kit.js"></script>
-<script src="/builders/gate.js?v=2026-09-19-fence"></script>
+<script src="/builders/gate.js?v=2026-09-19-runner"></script>
 </body>
 </html>