@bongos/core 1.21.5 → 1.21.6

package/modules/autonomy/config-idle.js

@@ -0,0 +1,192 @@
+'use strict';
+
+// modules/autonomy/config-idle.js — idle because there is no work, or idle
+// because of a setting the owner can fix? (task 1004539.) Pure: no I/O, no clock
+// of its own; `nowMs` is injected and the one outward call (`post`) is too.
+//
+// THE INCIDENT. From 2026-10-01T23:48Z to 2026-10-02T09:47Z a runner sat fenced
+// with `no_builder_scope` — its builder had picked no goals — while the hall said
+// "alive, waiting for work" and nobody was told. Ten hours of a machine doing
+// exactly what it was configured to do, which was nothing.
+//
+// TWO KINDS OF IDLE, and the whole point is that they must not look alike:
+//   · QUIET — nothing claimable, a capacity hold with a known reset, the owner's
+//     kill switch, the owner's pause on one builder. Either there is no work, or
+//     a person deliberately said stop. Telling the owner about their own decision
+//     is noise, and noise is how a status light gets ignored.
+//   · CONFIGURATION — the runner would work, but a setting stops it and nothing
+//     will change until someone changes the setting. These are the codes below.
+//
+// THE GRACE. A configuration refusal is surfaced only after it has held for its
+// grace. Fifteen minutes for the settings a person changes on purpose (an owner
+// mid-edit on the Gate page is not an incident), an hour for the two that can
+// also be a passing blip (an instance restart, a gauge between sessions).
+//
+// THE SPLIT OF WORK. The RUNNER knows what refused it and for how long, so it
+// tracks that (trackIdle) and, once the grace has passed, says so on its
+// heartbeat as `last_event: 'config_idle:<code>'` (markBeat). The SERVER reads
+// that one string: runner-health.js turns it into a not-ok state with the fix,
+// and the notifier below posts one Discord notice per change. No new column: the
+// heartbeat already carries a free-text last event, and a runner that predates
+// this sends none of these, which reads exactly as before.
+
+const GRACE_S = 15 * 60;
+const LONG_GRACE_S = 60 * 60;
+
+// Every configuration code, the sentence the owner reads, and the fix. A code
+// that is not here is never an alert — that is how kill_switch, builder_paused
+// and not_permitted stay quiet by construction rather than by an exception.
+const CONFIG_IDLE = Object.freeze({
+  no_builder_scope: Object.freeze({
+    graceS: GRACE_S,
+    why: 'no goals are picked for this runner, so it takes no work',
+    remedy: 'Choose which goals your runner works in Settings → Your Autobongos runner (/builders/settings#autobongos).',
+  }),
+  no_allowlist: Object.freeze({
+    graceS: GRACE_S,
+    why: 'no goal is allowed for runners on this project',
+    remedy: 'Allow at least one goal for runners on the Gate page.',
+  }),
+  goal_not_allowlisted: Object.freeze({
+    graceS: GRACE_S,
+    why: 'it was started for goals that are not on the allowlist',
+    remedy: 'Add those goals on the Gate page, or restart the runner without --goal / AUTOBONGOS_GOALS.',
+  }),
+  fence_unreadable: Object.freeze({
+    graceS: LONG_GRACE_S,
+    why: 'it cannot read its fence from this instance, so nothing is permitted',
+    remedy: 'Check the runner PC can reach this instance and that its Bongos CLI session is still valid (re-issue it in Settings if not).',
+  }),
+  gauge_unknown: Object.freeze({
+    graceS: LONG_GRACE_S,
+    why: 'its usage gauge has no fresh reading, so it will not start work',
+    remedy: 'Wire the usage-gauge statusLine on the runner PC (modules/autonomy/CLAUDE.md, "Wiring the gauge"), or open one Claude session there.',
+  }),
+});
+
+const PREFIX = 'config_idle:';
+const PENDING = 'config_pending:';
+
+// configIdleCode — which configuration, if any, one run-log row is idle on.
+function configIdleCode(row) {
+  if (!row || typeof row !== 'object') return null;
+  if (row.event === 'fenced') {
+    const code = row.code;
+    // goal_not_allowlisted counts only at RUN level (every requested goal
+    // refused). The same code on one TASK is the fence doing its job on one pick.
+    if (code === 'goal_not_allowlisted') return row.task_id ? null : code;
+    if (code === 'no_builder_scope' || code === 'no_allowlist' || code === 'fence_unreadable') return code;
+    return null;
+  }
+  // An UNKNOWN gauge, never a capacity hold: a spent window has a reset and ends
+  // by itself, and the usage limit is a hold the owner has ruled acceptable.
+  if (row.event === 'hold' && row.unknown === true && !row.usage_limit) return 'gauge_unknown';
+  return null;
+}
+
+// trackIdle — the runner's memory of how long it has been idle on one code.
+// Any row that is not a configuration refusal ends the stretch; a DIFFERENT code
+// starts a new one, because the fix changed and so did the owner's grace.
+function trackIdle(prev, row, nowMs) {
+  const code = configIdleCode(row);
+  if (!code) return null;
+  if (prev && prev.code === code && Number.isFinite(prev.sinceMs)) return prev;
+  return { code, sinceMs: nowMs };
+}
+
+// idleEvent — the heartbeat word for a stretch that has outlived its grace.
+function idleEvent(tracker, nowMs) {
+  if (!tracker || !CONFIG_IDLE[tracker.code]) return null;
+  if (!Number.isFinite(nowMs) || nowMs - tracker.sinceMs < CONFIG_IDLE[tracker.code].graceS * 1000) return null;
+  return `${PREFIX}${tracker.code}`;
+}
+
+// markBeat — the beat fields the runner sends. A beat that carries a task, a
+// boot or an exit says something more specific than "idle" and is left alone.
+// Inside the grace the stretch is PENDING (`config_pending:<code>`): the hall
+// reads it as an ordinary fence wait, and the notifier knows it is the same
+// setting still holding — so a runner that restarts mid-stretch does not "clear"
+// and then re-raise its notice, while a real capacity hold or a kill switch
+// (which end the stretch, so are sent as themselves) still clears it.
+function markBeat(fields, tracker, nowMs) {
+  const f = fields || {};
+  if (f.working_task_id || f.last_event === 'boot' || f.last_event === 'upgrade_exit') return f;
+  const ev = idleEvent(tracker, nowMs);
+  if (ev) return { ...f, last_event: ev };
+  if (tracker && CONFIG_IDLE[tracker.code]) return { ...f, last_event: `${PENDING}${tracker.code}` };
+  return f;
+}
+
+// parseIdleEvent — the code a heartbeat's last_event names, or null. Only a KNOWN
+// code is honoured, so a heartbeat cannot make the hall print arbitrary text.
+function parseIdleEvent(lastEvent) {
+  if (typeof lastEvent !== 'string' || !lastEvent.startsWith(PREFIX)) return null;
+  const code = lastEvent.slice(PREFIX.length);
+  return Object.prototype.hasOwnProperty.call(CONFIG_IDLE, code) ? code : null;
+}
+
+// Heartbeat events that say nothing about whether the setting was fixed: the
+// loop's own rhythm and a restart. A pending stretch on the SAME code is neutral
+// too (see markBeat). Anything else — a fence or hold the runner sent as itself,
+// a pick, a worker, "nothing claimable" — means the setting no longer holds it.
+const NEUTRAL = new Set([null, undefined, '', 'boot', 'loop', 'waiting', 'code_refreshed', 'upgrade_exit']);
+
+function pendingCode(lastEvent) {
+  if (typeof lastEvent !== 'string' || !lastEvent.startsWith(PENDING)) return null;
+  const code = lastEvent.slice(PENDING.length);
+  return Object.prototype.hasOwnProperty.call(CONFIG_IDLE, code) ? code : null;
+}
+
+// noticeDecision — post, or stay quiet? `notified` is the code last announced for
+// this runner (null for none). Raise once per code, clear once when it resolves,
+// and say nothing on every other beat.
+function noticeDecision(notified, { lastEvent = null, workingTaskId = null } = {}) {
+  const code = parseIdleEvent(lastEvent);
+  if (code) return code === notified ? { action: null, next: notified } : { action: 'raise', code, next: code };
+  if (!notified) return { action: null, next: null };
+  if (!workingTaskId && (NEUTRAL.has(lastEvent) || pendingCode(lastEvent) === notified)) return { action: null, next: notified };
+  return { action: 'clear', code: notified, next: null };
+}
+
+// A host name is the builder's own text and lands in a shared channel, so it is
+// cut to the characters a host name has and set as code — never a link, never
+// formatting.
+function safeHost(host) {
+  const h = String(host || '').replace(/[^A-Za-z0-9._-]/g, '').slice(0, 64);
+  return h ? ` on \`${h}\`` : '';
+}
+
+function noticeText({ action, code, host }) {
+  const spec = CONFIG_IDLE[code];
+  const pc = safeHost(host);
+  if (action === 'clear') return `Autobongos runner${pc}: no longer held — it was idle because ${spec.why}, and that has changed.`;
+  return `Autobongos runner${pc} is idle because ${spec.why}. Fix: ${spec.remedy}`;
+}
+
+// createNotifier — the de-duplicating Discord line. One remembered code per
+// (builder, host), in memory: an instance restart forgets it and may repeat one
+// notice, which is the cheap end of the trade against a migration for a flag.
+// `post` is the discord.post port ({ channel, text }) or null when the instance
+// has no Discord; then nothing is remembered either, so wiring Discord later
+// still gets the first notice.
+function createNotifier({ post = null, channel = 'ship_news' } = {}) {
+  const notified = new Map();
+  return {
+    notified,
+    async observe({ builderId, host, lastEvent, workingTaskId } = {}) {
+      const key = `${builderId}|${String(host || '').toLowerCase()}`;
+      const d = noticeDecision(notified.get(key) || null, { lastEvent, workingTaskId });
+      if (!d.action) return { posted: false, action: null };
+      if (typeof post !== 'function') return { posted: false, action: d.action, reason: 'no_discord' };
+      const res = await post({ channel, text: noticeText({ action: d.action, code: d.code, host }) });
+      if (res && res.posted === false) return { posted: false, action: d.action, reason: res.reason || 'not_posted' };
+      if (d.next) notified.set(key, d.next); else notified.delete(key);
+      return { posted: true, action: d.action, code: d.code };
+    },
+  };
+}
+
+module.exports = {
+  GRACE_S, LONG_GRACE_S, CONFIG_IDLE,
+  configIdleCode, trackIdle, idleEvent, markBeat, parseIdleEvent, pendingCode, noticeDecision, noticeText, createNotifier,
+};

package/modules/autonomy/routes/autonomy.js

@@ -30,6 +30,7 @@ const autonomyGate = require('../../../scripts/gds/autonomy-gate');
 const db = require('../db');
 const fence = require('../fence');
 const runnerHealth = require('../runner-health');
+const configIdle = require('../config-idle');
 // 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');
@@ -109,6 +110,18 @@ module.exports = function buildAutonomyRouter() {
   governorDocket.contributeAutonomyToDocket();
   const router = express.Router();
 
+  // The one Discord line for a runner idle on a setting (task 1004539). The port
+  // is resolved per post, not here: the discord module registers it at mount and
+  // may mount after this router. No Discord on the instance answers no_discord,
+  // and the hall's runner panel still says it either way.
+  const idleNotifier = configIdle.createNotifier({
+    post: async (msg) => {
+      const port = typeof api.resolveOptional === 'function' ? api.resolveOptional('discord.post', null) : null;
+      if (typeof port !== 'function') return { posted: false, reason: 'no_discord' };
+      return port(msg);
+    },
+  });
+
   router.get('/autonomy/precheck', auth.requireBuilder, auth.requirePermission('autonomy.precheck'), async (req, res) => {
     const routine = String(req.query.routine || '').slice(0, 64);
     if (!routine) return res.fail('routine_required', { status: 400, message: 'pass ?routine=<name>' });
@@ -377,6 +390,15 @@ module.exports = function buildAutonomyRouter() {
         claudeAccount: typeof b.claude_account === 'string' && b.claude_account.trim() ? b.claude_account.trim() : null,
       });
       res.json({ ok: true, heartbeat: row });
+      // AFTER the answer, and never awaited by it: a notice that cannot be posted
+      // must not turn a recorded check-in into a failed one (the fail-soft rule
+      // below). It de-duplicates itself — once per cause, once when it clears.
+      idleNotifier.observe({
+        builderId: req.builder.id,
+        host: b.host,
+        lastEvent: b.last_event || null,
+        workingTaskId: Number.isInteger(b.working_task_id) ? b.working_task_id : null,
+      }).catch((e) => log.warn(`[gds] autonomy: idle notice not posted: ${e && e.message ? e.message : e}`));
     } 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

package/modules/autonomy/runner-health.js

@@ -24,6 +24,12 @@
 //     relaunches, which takes a minute or two, and the owner ruled that a restart
 //     must read as a restart, never as a death (task 1004407). Past RESTART_S the
 //     relaunch has failed and it is dead again — with a detail that says so.
+//   · idle_config — alive, but idle on a setting the owner can fix (no goals
+//     picked, an empty allowlist, a fence it cannot read, a gauge with no
+//     reading), for longer than that setting's grace (task 1004539). NOT ok, and
+//     it carries the fix as `remedy`. The runner decides the grace and says
+//     `config_idle:<code>` on its heartbeat; only a code config-idle.js knows is
+//     honoured, so the owner's kill switch and pause can never read as an alarm.
 
 // 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
@@ -38,6 +44,8 @@ const LATE_S = 2 * 60 * 60;
 // relaunch which never happened is noticed the same evening.
 const RESTART_S = 10 * 60;
 
+const configIdle = require('./config-idle.js');
+
 const SHA_RE = /^[0-9a-f]{40}$/;
 const sha = (v) => (typeof v === 'string' && SHA_RE.test(v) ? v : null);
 
@@ -129,8 +137,21 @@ function describeRunner(heartbeat, { nowMs = Date.now(), aliveS = ALIVE_S, lateS
     };
   }
 
+  // Idle on configuration — but only while the runner is still talking. Past the
+  // dead line silence wins: a dead runner cannot vouch for its settings.
+  const idleCode = configIdle.parseIdleEvent(heartbeat.last_event);
+  if (idleCode && age <= lateS) {
+    const spec = configIdle.CONFIG_IDLE[idleCode];
+    return {
+      state: 'idle_config', ok: false, ageS: age, age: humanAge(age), ...ident,
+      idleCode, why: spec.why, remedy: spec.remedy,
+      detail: `idle${where} because ${spec.why}`,
+    };
+  }
+
   if (age <= aliveS) {
-    const doing = ACTIVITY[heartbeat.last_event];
+    // A setting still inside its grace reads as the fence wait it is, not "running".
+    const doing = ACTIVITY[heartbeat.last_event] || (configIdle.pendingCode(heartbeat.last_event) ? ACTIVITY.fenced : null);
     return {
       state: 'alive', ok: true, ageS: age, age: humanAge(age), ...ident,
       detail: working