@bongos/core 1.19.876 → 1.19.878

package/scripts/gds/autobongos-run.js

@@ -6,8 +6,9 @@
 // one worker → record. No model anywhere in this file; every branch it takes is
 // a branch a person can read.
 //
-//   node scripts/gds/autobongos-run.js                           # every allowlisted goal
-//   node scripts/gds/autobongos-run.js --goal 1000119            # narrow to one of them
+//   node scripts/gds/autobongos-run.js --forever                 # the daemon shape
+//   node scripts/gds/autobongos-run.js                           # one task, then exit
+//   node scripts/gds/autobongos-run.js --goal 1000119            # narrow to one goal
 //   node scripts/gds/autobongos-run.js --max-tasks 5
 //   node scripts/gds/autobongos-run.js --dry-run                 # pick only, claim nothing
 //
@@ -22,13 +23,19 @@
 //     1003903), called at step 6. A worker's `shipped` is a CLAIM — recorded here
 //     as `claims_shipped` so nothing can mistake it for a fact — and the ledger
 //     read is what turns it into one, or into a released claim and a blocker.
-//   · BACKOFF and never-terminally-stopping is task 1003904. This exits after
-//     its budget; it does not yet decide when to come back.
+//   · IT NEVER TERMINALLY STOPS (task 1003904, ADR 0307 §5). `--forever` runs the
+//     cadence state machine in modules/autonomy/cadence.js: three straight
+//     failures drop to `probing` — no new work, a growing wait, then exactly one
+//     task — and one success returns it to full speed. Nothing exits the loop,
+//     not even the kill switch, because a machine nobody is watching must not be
+//     able to look idle while it is dead. On boot it reconciles every claim a
+//     previous run left behind.
 
 const { execFile, spawn } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const os = require('node:os');
 
 const seq = require('./sequence.js');
 const gauge = require('./autonomy-gauge.js');
@@ -42,11 +49,12 @@ const fence = require('../../modules/autonomy/fence.js');
 // where it would not be inside modules/ — which is exactly why fence.js takes the
 // hits as an argument instead of matching them itself.
 const { matchProtected } = require('../../src/bongos/permission-path-check');
+const cadence = require('../../modules/autonomy/cadence.js');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
 function readArgv(argv) {
-  const out = { goals: [], maxTasks: 1, dryRun: false, json: false, model: DEFAULT_MODEL, timeoutMs: DEFAULT_WORKER_TIMEOUT_MS };
+  const out = { goals: [], maxTasks: 1, dryRun: false, json: false, forever: false, maxLoops: Infinity, model: DEFAULT_MODEL, timeoutMs: DEFAULT_WORKER_TIMEOUT_MS };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--goal') { out.goals.push(Number(argv[++i])); continue; }
@@ -56,6 +64,12 @@ function readArgv(argv) {
     if (a === '--timeout-min') { out.timeoutMs = Number(argv[++i]) * 60_000; continue; }
     if (a === '--dry-run') { out.dryRun = true; continue; }
     if (a === '--json') { out.json = true; continue; }
+    // --forever is the DAEMON shape: never returns, decides its own speed.
+    if (a === '--forever') { out.forever = true; continue; }
+    // --max-loops bounds the forever loop. It exists so a test (and an operator
+    // trying the thing out) can run the machine to completion; production passes
+    // it never, and Infinity is the honest default.
+    if (a === '--max-loops') { out.maxLoops = Number(argv[++i]); continue; }
   }
   if (!out.goals.length && process.env.AUTOBONGOS_GOALS) {
     out.goals = String(process.env.AUTOBONGOS_GOALS).split(',').map((g) => Number(g.trim())).filter(Boolean);
@@ -111,6 +125,12 @@ async function pickTask(goals, deps = {}) {
   }
   const claimableIds = await seq.fetchClaimableIds(api);
 
+  // The skipped lists from EVERY goal are kept, not just the last one. An empty
+  // queue and a queue where every task halts both yield no task, and telling them
+  // apart is the whole of `unworkable_queue` (task 1003904): calling the second
+  // one "idle" is how a goal full of blocked work sits for a week with the runner
+  // reporting itself perfectly healthy.
+  const allSkipped = [];
   for (const goalId of goals) {
     let byId;
     try { byId = await seq.fetchGoalTasks(api, goalId, seq.GOAL_PAGE); }
@@ -120,8 +140,9 @@ async function pickTask(goals, deps = {}) {
     const { order } = seq.topoOrder(candidates);
     const { next, skipped } = seq.pickNext(order, { rank, claimableIds });
     if (next) return { task: next, goalId, skipped };
+    for (const sk of skipped) allSkipped.push({ ...sk, goal_id: goalId });
   }
-  return { none: true };
+  return { none: true, skipped: allSkipped };
 }
 
 // WORKER_ENV_ALLOW — what a worker is allowed to inherit (grader finding, task
@@ -277,7 +298,14 @@ async function iteration(opts, deps = {}) {
   // for. gate.goals is already the intersection.
   const picked = await pick(gate.goals, deps.pickDeps || {});
   if (picked.error) return log({ event: 'pick_failed', reason: picked.error });
-  if (picked.none) return log({ event: 'nothing_claimable', goals: opts.goals });
+  if (picked.none) {
+    return log({
+      event: 'nothing_claimable', goals: gate.goals,
+      // Carried so the cadence can tell an EMPTY queue from one where every task
+      // halts — the reasons are the matrix's own codes, safe to print.
+      skipped: (picked.skipped || []).map((sk) => ({ id: sk.id, goal_id: sk.goal_id, reasons: (sk.reasons || []).map((r) => r.code) })),
+    });
+  }
   const task = picked.task;
 
   // 2b. The per-TASK half of the fence. sequence.js's halt matrix already refuses
@@ -353,6 +381,13 @@ async function iteration(opts, deps = {}) {
     // What the LEDGER says, kept separate from what the worker said, so the run
     // log can be read afterwards without having to trust either one alone.
     ledger_status: ledger.status, ledger_shape: ledger.shape, verified: !!ledger.verified,
+    // The LEDGER's own explanation, kept beside the worker's. `reason` above is
+    // verdict.reason — what the WORKER said happened — and it was the only reason
+    // in the row, so anything reading the log afterwards was quoting the thing
+    // being checked rather than the check. The morning digest did exactly that
+    // until the grader caught it (task 1003906).
+    ledger_reason: ledger.reason || null,
+    ledger_remedy: ledger.remedy || null,
     artifact_on_main: ledger.artifact && ledger.artifact.checked ? !!ledger.artifact.onMain : null,
     claim_released: !!ledger.released,
     blocker_id: ledger.blocker && ledger.blocker.blockerId ? ledger.blocker.blockerId : null,
@@ -364,19 +399,343 @@ async function iteration(opts, deps = {}) {
   return log(row);
 }
 
+// ---------------------------------------------------------------------------
+// Boot recovery, and the forever loop (task 1003904, ADR 0307 §5)
+// ---------------------------------------------------------------------------
+
+// reconcileLeftoverClaims — the FIRST thing a run does.
+//
+// "A silently locked task is the worst outcome this loop can produce" is the
+// task's own wording, and cutting power mid-task is exactly how it happens: the
+// claim is held by a session that no longer exists anywhere, and nothing times it
+// out. So before taking any new work, every claim a previous run left behind is
+// read back from the ledger and resolved.
+//
+// The reconciliation is autobongos-verify.js, unchanged (task 1003903). That file
+// already answers "did this actually ship, and if not what do I do about it" for
+// a worker that just exited; a worker that exited three days ago in a power cut
+// is the same question with a longer gap. Writing a second, subtly different
+// answer here is how two code paths end up disagreeing about what `confirmed`
+// means.
+//
+// ONLY TREES THE RUNNER ITSELF MADE, matched against the EXACT shape
+// worktreeName() produces — not a loose prefix.
+//
+// FOUND THE HARD WAY, twice. `autobongos-` as a prefix reads as "ours", and it is
+// not: a person naming a worktree `autobongos-resume-1003904-d29f25` while
+// working on this very feature matched it, and reconciliation released their live
+// claim out from under them. A human at a keyboard picks readable names; the
+// runner picks `autobongos-<task id>-<6 hex>` and nothing else. Matching the
+// generator's own shape is the difference between "probably ours" and "ours".
+//
+// Derived FROM worktreeName so the two cannot drift: change the name format and
+// this regex is what stops the next reconciliation from quietly matching nothing.
+const CLAIM_PREFIX = 'autobongos-';
+const RUNNER_TREE_RE = /^autobongos-\d+-[0-9a-f]{6}$/;
+const isRunnerTree = (name) => RUNNER_TREE_RE.test(String(name || ''));
+
+// ── the heartbeat, and why reconciliation needs one ──────────────────────────
+//
+// FOUND BY RUNNING IT. The first live run of reconcileLeftoverClaims released a
+// claim that was very much alive — the one held by the session writing this code.
+// It was right by its own rules (an `autobongos-` tree, a task sitting at
+// `active`), and that is the problem: THE LEDGER CANNOT TELL A LIVE RUN FROM A
+// DEAD ONE. Both look like a held claim. A reconciler that guesses wrong in one
+// direction leaves a task locked forever; in the other it yanks a claim out from
+// under a worker mid-build and strands whatever it had committed.
+//
+// So the runner says, on disk, that it is alive. A heartbeat file carries the pid
+// and a timestamp; reconciliation refuses to touch anything while one is FRESH
+// and its pid still exists. Both halves are needed — a stale file from a power
+// cut must not veto recovery forever, and a fresh file whose process is gone is
+// just litter. This is also what stops two runners on one machine from fighting
+// over each other's claims.
+const HEARTBEAT_STALE_MS = 10 * 60 * 1000;
+
+function heartbeatPath() {
+  if (process.env.AUTOBONGOS_HEARTBEAT_FILE) return process.env.AUTOBONGOS_HEARTBEAT_FILE;
+  try { return require('../../src/instance-config.js').configPath('autobongos-heartbeat.json'); }
+  catch (_) { return path.join(REPO_ROOT, '.autobongos-heartbeat.json'); }
+}
+
+// Best-effort in both directions: a runner that cannot write its heartbeat must
+// still run (it only loses the guard), and one that cannot read it must assume
+// nothing is alive — the file's absence is the common case, on every first boot.
+//
+// DO NOT point AUTOBONGOS_HEARTBEAT_FILE UNDER /proc TO TEST THE FAILURE PATH (task
+// 1004052). The mkdirSync below is recursive, and on Linux a recursive mkdir under
+// /proc never returns — measured 10s+ with no result, where the same call throws
+// EACCES instantly under /sys or /, and the NON-recursive form throws ENOENT instantly
+// under /proc itself. macOS has no /proc, so it fails fast there. A test that used it
+// was green on every developer machine and hung the Ubuntu CI runner for 90s with no
+// output, reddening `unit` on main and blocking every PR. Use a regular FILE as the
+// parent directory instead: mkdir under it is ENOTDIR immediately, everywhere, and it
+// does not depend on the caller's permissions.
+function writeHeartbeat(now = Date.now()) {
+  try {
+    const p = heartbeatPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ pid: process.pid, at: now }));
+    return true;
+  } catch (_) { return false; }
+}
+
+// postHeartbeat — tell the SERVER we are alive (task 1003905).
+//
+// The file above guards against two runners on this machine; this is the half an
+// owner can see from a web page in another country. Both matter and neither
+// replaces the other: a file is unreadable on exactly the day the machine is off.
+//
+// FAILS SILENTLY, ON PURPOSE. A runner that cannot check in must keep working —
+// letting the watching mechanism take down the thing it watches is a strictly
+// worse outcome than a gap in the log. The gap reports itself anyway: the hall
+// reads the AGE of the last check-in, so a failed post shows up as silence, which
+// is the signal.
+const RUNNER_STARTED_AT = new Date().toISOString();
+
+async function postHeartbeat(fields = {}, deps = {}) {
+  try {
+    const api = deps.api || await (require('./cli-lib').cliClient)();
+    await api.autonomy.postAutonomyHeartbeat({
+      body: {
+        host: os.hostname(),
+        pid: process.pid,
+        started_at: RUNNER_STARTED_AT,
+        ...fields,
+      },
+    });
+    return true;
+  } catch (_) { return false; }
+}
+
+function readHeartbeat() {
+  try { return JSON.parse(fs.readFileSync(heartbeatPath(), 'utf8')); }
+  catch (_) { return null; }
+}
+
+// pidAlive — `kill(pid, 0)` signals nothing and throws ESRCH when the process is
+// gone. EPERM means it exists and belongs to someone else, which still counts as
+// alive: the question is "is something running", not "is it mine".
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e && e.code === 'EPERM'; }
+}
+
+// anotherRunnerIsAlive — the veto. Fresh file AND a live pid AND not us.
+function anotherRunnerIsAlive({ now = Date.now(), hb = readHeartbeat() } = {}) {
+  if (!hb || !Number.isFinite(Number(hb.at))) return false;
+  if (Number(hb.pid) === process.pid) return false;         // our own beat
+  if (now - Number(hb.at) > HEARTBEAT_STALE_MS) return false;  // a power cut leaves a stale file
+  return pidAlive(Number(hb.pid));
+}
+
+async function reconcileLeftoverClaims(deps = {}) {
+  const api = deps.api || await (require('./cli-lib').cliClient)();
+  const log = deps.record || record;
+  const verify = deps.verifyShip || verifyShip;
+  const runCmd = deps.run || run;
+  const isAlive = deps.anotherRunnerIsAlive || anotherRunnerIsAlive;
+
+  // Refuse outright while another runner is beating. Releasing a claim a live
+  // worker is building against strands whatever it has committed — the same harm
+  // as leaving one locked, pointed the other way.
+  if (isAlive()) return log({ event: 'boot_reconcile', ok: true, skipped: 'another runner is alive', leftover: null });
+
+  let claims = [];
+  try {
+    const me = await api.me.getMe();
+    if (!me || !me.ok) return log({ event: 'boot_reconcile', ok: false, reason: `GET /me → ${me ? me.status : 'no response'}` });
+    claims = (me.data.active_claims || []).filter((c) => isRunnerTree(c.worktree_name));
+  } catch (e) {
+    // Unreadable is NOT "nothing to reconcile". Say so and let the cadence treat
+    // it as a failure, rather than starting work on top of an unknown lock.
+    return log({ event: 'boot_reconcile', ok: false, reason: e && e.message ? e.message : String(e) });
+  }
+
+  if (!claims.length) return log({ event: 'boot_reconcile', ok: true, leftover: 0 });
+
+  const resolved = [];
+  for (const c of claims) {
+    const wtPath = path.join(REPO_ROOT, '.claude', 'worktrees', c.worktree_name);
+    const out = await verify(
+      { taskId: c.task_id, taskTitle: c.title, worker: { outcome: 'interrupted', reason: 'a previous run did not finish this claim' } },
+      {
+        api,
+        // The tree may be gone — a power cut leaves the claim, not necessarily the
+        // checkout. verifyShip only uses cwd for the artifact probe, which degrades
+        // to `checked: false` rather than failing, so a missing path is survivable.
+        cwd: fs.existsSync(wtPath) ? wtPath : REPO_ROOT,
+        release: (id, reason) => runCmd(process.execPath,
+          [path.join(REPO_ROOT, 'scripts', 'gds', 'release.js'), String(id), '--reason', reason],
+          { cwd: fs.existsSync(wtPath) ? wtPath : REPO_ROOT }),
+      },
+    );
+    resolved.push({ task_id: String(c.task_id), worktree: c.worktree_name, shape: out.shape, released: !!out.released, blocker_id: out.blocker?.blockerId ?? null });
+  }
+  return log({ event: 'boot_reconcile', ok: true, leftover: claims.length, resolved });
+}
+
+// pollSignals — the cheap facts whose change makes waiting pointless.
+//
+// Three reads, all small, all failing SILENTLY to null. A failed probe is not a
+// signal: treating it as one would turn an unreachable instance into a busy loop
+// hammering it, which is the exact opposite of backing off.
+async function pollSignals(deps = {}) {
+  const api = deps.api || await (require('./cli-lib').cliClient)();
+  let head = null; let fenceUpdatedAt = null; let claimableCount = null;
+  try {
+    const r = await runFetchHead(deps);
+    if (r) head = r;
+  } catch (_) { /* null */ }
+  try {
+    const f = await api.autonomy.getAutonomyFence();
+    if (f && f.ok) fenceUpdatedAt = f.data.updated_at || null;
+  } catch (_) { /* null */ }
+  try {
+    const ids = await seq.fetchClaimableIds(api);
+    if (ids) claimableCount = ids.size;
+  } catch (_) { /* null */ }
+  return cadence.signalFingerprint({ head, fenceUpdatedAt, claimableCount });
+}
+
+// The head of origin/main, or null. `git ls-remote` rather than `fetch`: it moves
+// no refs and writes nothing, so polling it every few minutes cannot interfere
+// with a worker building in a tree beside it.
+async function runFetchHead(deps = {}) {
+  const runCmd = deps.run || run;
+  const r = await runCmd('git', ['ls-remote', 'origin', 'refs/heads/main']);
+  if (!r.ok) return null;
+  const m = /^([0-9a-f]{40})/.exec(String(r.stdout).trim());
+  return m ? m[1] : null;
+}
+
+// waitOrJump — sleep, but wake early if the world moved.
+//
+// Polls at most every `pollEveryS`, so a thirty-minute backoff costs six cheap
+// probes rather than a spin. `sleep` is injected so a test can drive an hour of
+// wall clock in a millisecond.
+async function waitOrJump(waitS, deps = {}, cfg = {}) {
+  if (!(waitS > 0)) return { waited: 0, jumped: false };
+  const pollEveryS = cfg.pollEveryS ?? 60;
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const poll = deps.pollSignals || pollSignals;
+
+  const before = await poll(deps);
+  let waited = 0;
+  while (waited < waitS) {
+    const chunk = Math.min(pollEveryS, waitS - waited);
+    await sleep(chunk * 1000);
+    waited += chunk;
+    // Beat DURING the wait. A thirty-minute backoff is the runner working exactly
+    // as designed, and it must not be indistinguishable from a machine that fell
+    // over at the start of it.
+    if (deps.beat) { try { await deps.beat({ last_event: 'waiting' }); } catch (_) { /* never break a wait */ } }
+    if (waited >= waitS) break;
+    const now = await poll(deps);
+    if (cadence.shouldJumpWait(before, now)) return { waited, jumped: true, signal: now };
+  }
+  return { waited, jumped: false };
+}
+
+// forever — the loop that has no terminal stop (task 1003904, ADR 0307 §5).
+//
+// It is a `while (true)` on purpose and the exceptions are the interesting part:
+// NOTHING in here returns. Not an unreachable instance, not an expired token, not
+// the kill switch. The only exits are a signal from the operating system and
+// `--max-loops`, which exists so a test can run the machine to completion.
+//
+// What varies is the SPEED, and the speed is decided entirely by
+// modules/autonomy/cadence.js from the row the last iteration recorded. This
+// function holds no policy — it turns a `waitS` into a wait and a `takeWork` into
+// an iteration, so the rules stay somewhere a test can reach without a clock.
+async function forever(opts, deps = {}) {
+  const log = deps.record || record;
+  const iterate = deps.iteration || iteration;
+  const reconcile = deps.reconcileLeftoverClaims || reconcileLeftoverClaims;
+  const wait = deps.waitOrJump || waitOrJump;
+  const emit = deps.emit || ((row) => {
+    if (opts.json) console.log(JSON.stringify(row));
+    else console.log(`${row.event}${row.task_id ? ` task ${row.task_id}` : ''}${row.outcome ? ` → ${row.outcome}` : ''}${row.reason ? `: ${row.reason}` : ''}`);
+  });
+
+  // Claim the machine BEFORE reconciling: a second runner starting a moment later
+  // must see this one alive rather than deciding its claims are litter.
+  // Both halves of "I am alive": the local file (which stops a second runner
+  // treating this one's claims as litter) and the server row (which is the only
+  // one an owner can see from anywhere else).
+  const beatFile = deps.writeHeartbeat || writeHeartbeat;
+  const beatServer = deps.postHeartbeat || postHeartbeat;
+  // WRAPPED AT THE CALL SITE, not just inside postHeartbeat. The guarantee is
+  // "reporting that I am alive can never be what kills me", and that has to hold
+  // for whatever beat implementation is in play — a future one, an injected one —
+  // not only for the well-behaved default. Letting the watching mechanism take
+  // down the thing it watches is strictly worse than a gap in the log, and the gap
+  // reports itself anyway: the hall reads the AGE of the last check-in, so a
+  // failed beat shows up as silence, which is the signal.
+  const beat = async (fields) => {
+    try { beatFile(); } catch (_) { /* a runner that cannot write its file still runs */ }
+    try { await beatServer(fields, deps); } catch (_) { /* and one that cannot reach the instance still runs */ }
+  };
+  await beat({ last_event: 'boot' });
+
+  // BEFORE ANY WORK. A claim left locked by a previous run is the worst thing
+  // this loop produces, and taking new work on top of one compounds it.
+  emit(await reconcile(deps));
+
+  let state = { ...cadence.START };
+  const maxLoops = Number.isFinite(Number(opts.maxLoops)) ? Number(opts.maxLoops) : Infinity;
+
+  for (let loop = 0; loop < maxLoops; loop++) {
+    // Every loop, so a crash leaves a heartbeat that goes stale on its own — the
+    // runner never has to notice it is dying for its death to become visible.
+    await beat({ mode: state.mode, consecutive_failures: state.consecutiveFailures, last_event: 'loop' });
+    // In `probing` the runner takes exactly ONE task and only after its wait, so
+    // a broken window costs a handful of cheap requests rather than a night of
+    // failing spawns. `maxTasks` still bounds a full-speed burst.
+    const budget = state.mode === 'probing' ? 1 : opts.maxTasks;
+    let row = null;
+
+    for (let i = 0; i < budget; i++) {
+      row = await iterate(opts, deps);
+      emit(row);
+      // Carry the task id so the hall can tell "quiet because it is building
+      // task 1234" from "quiet because it is dead". A worker may hold the loop for
+      // ninety minutes, and without this every honest hour of work looks like a
+      // corpse.
+      await beat({ mode: state.mode, last_event: row.event, working_task_id: Number(row.task_id) || undefined });
+      const seen = cadence.classifyEvent(row);
+      state = cadence.nextCadence(state, seen, opts.cadence);
+      log({ event: 'cadence', mode: state.mode, consecutive_failures: state.consecutiveFailures, wait_s: state.waitS, class: seen.class, why: state.why });
+      // A burst continues only while work is actually landing. Anything else ends
+      // the burst and hands the decision to the cadence, which is the only thing
+      // allowed to say how long to wait.
+      if (seen.class !== 'progress') break;
+    }
+
+    const { waited, jumped } = await wait(state.waitS, { ...deps, beat }, opts.cadence);
+    if (jumped) log({ event: 'cadence', mode: state.mode, jumped: true, waited_s: waited, why: 'a new signal arrived — main moved, the fence changed, or the queue did' });
+  }
+  return 0;
+}
+
 async function main(argv) {
   const opts = readArgv(argv);
   // No "name a goal" refusal here any more. It used to be the only allowlist, and
   // it lived on the machine being fenced; the database owns that now, and an empty
   // `--goal` means "every allowlisted goal" rather than "anything claimable". The
   // refusal did not disappear — it moved somewhere the runner host cannot edit.
+  if (opts.forever) return forever(opts);
+
+  // The one-shot path, kept for an operator running a single task by hand. It
+  // still reconciles first: a leftover claim is a leftover claim whoever is
+  // watching.
+  const boot = await reconcileLeftoverClaims();
+  if (opts.json) console.log(JSON.stringify(boot));
   for (let i = 0; i < opts.maxTasks; i++) {
     const row = await iteration(opts);
     if (opts.json) console.log(JSON.stringify(row));
     else console.log(`${row.event}${row.task_id ? ` task ${row.task_id}` : ''}${row.outcome ? ` → ${row.outcome}` : ''}${row.reason ? `: ${row.reason}` : ''}`);
-    // Anything that is not a completed piece of work ends this run — including
-    // `verify_halt`, which is the ledger being unreadable. Deciding when to come
-    // back is task 1003904's job, not this one's.
     if (row.event !== 'worked') break;
   }
   return 0;
@@ -389,4 +748,9 @@ if (require.main === module) {
   });
 }
 
-module.exports = { readArgv, pickTask, iteration, record, logPath, spawnWorker, workerEnv, WORKER_ENV_ALLOW, worktreeName, readFence };
+module.exports = {
+  readArgv, pickTask, iteration, record, logPath, spawnWorker, workerEnv, WORKER_ENV_ALLOW,
+  worktreeName, readFence, reconcileLeftoverClaims, pollSignals, waitOrJump, forever, CLAIM_PREFIX,
+  heartbeatPath, writeHeartbeat, readHeartbeat, pidAlive, anotherRunnerIsAlive, HEARTBEAT_STALE_MS,
+  isRunnerTree, RUNNER_TREE_RE, postHeartbeat, RUNNER_STARTED_AT,
+};

package/scripts/gds/autobongos-service.cmd

@@ -0,0 +1,38 @@
+@echo off
+REM scripts/gds/autobongos-service.cmd -- what the scheduled task actually runs
+REM (task 1003905). A .cmd, not a direct node invocation, for three reasons the
+REM scheduler cannot do itself.
+REM
+REM 1. THE CHECKOUT IS BROUGHT CURRENT FIRST. A runner pinned to whatever was on
+REM    disk the day it was installed drifts silently, and the first symptom is
+REM    workers building against a stale fence. `git fetch` + `reset --hard` on the
+REM    MAIN checkout only -- worker trees are separate worktrees and are never
+REM    touched here.
+REM 2. OUTPUT IS APPENDED TO ONE FILE the owner can read remotely. The scheduler
+REM    keeps only an exit code, which cannot answer "what was it doing".
+REM 3. A NON-ZERO EXIT IS RETURNED so the scheduler's restart rule can see it.
+REM
+REM The runner itself never exits on failure (task 1003904) -- it backs off and
+REM probes -- so reaching the end of this file at all means something the inner
+REM loop could not survive.
+
+setlocal
+set "REPO=%~dp0..\.."
+set "LOGDIR=%LOCALAPPDATA%\cloudbongos"
+set "LOG=%LOGDIR%\autobongos.log"
+if not exist "%LOGDIR%" mkdir "%LOGDIR%"
+
+cd /d "%REPO%" || exit /b 1
+
+echo. >> "%LOG%"
+echo ==== autobongos starting %DATE% %TIME% ==== >> "%LOG%"
+
+REM Best effort: a fetch that fails must not stop the runner from starting on the
+REM code it already has. Being a commit behind beats not running at all.
+git fetch --quiet origin main >> "%LOG%" 2>&1
+git reset --quiet --hard origin/main >> "%LOG%" 2>&1
+
+node scripts\gds\autobongos-run.js --forever --json >> "%LOG%" 2>&1
+set EXITCODE=%ERRORLEVEL%
+echo ==== autobongos exited %EXITCODE% at %DATE% %TIME% ==== >> "%LOG%"
+exit /b %EXITCODE%

package/scripts/gds/autobongos-service.ps1

@@ -0,0 +1,135 @@
+# scripts/gds/autobongos-service.ps1 -- install the Autobongos runner so it
+# outlives the reboot (task 1003905, ADR 0307 section 5).
+#
+#   powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 install
+#   powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 status
+#   powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 digest
+#   powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 start|stop|uninstall
+#
+# WHY TASK SCHEDULER AND NOT A REAL SERVICE. Windows services speak a protocol
+# (SCM handshakes, stop signals) that node does not, so every "node as a service"
+# route needs a third-party wrapper: nssm, winsw, node-windows. Each is a binary
+# to download, verify, update and explain -- a permanent dependency bought for one
+# machine. Task Scheduler is already on the box, runs at boot with no session,
+# survives sign-out, and restarts a crashed task natively. The one thing it does
+# not give is the Services panel, which nobody here needs.
+#
+# WHAT ACTUALLY KEEPS IT ALIVE IS THE INNER LOOP, and that is the important part
+# to understand before reading the RestartCount settings below. `--forever` never
+# returns: it backs off and probes instead of exiting (task 1003904), so the
+# scheduler's restart is the OUTER ring, for the cases the loop cannot survive at
+# all -- a reboot, a power cut, a node crash, an OOM kill. If this ring is doing
+# work regularly, something is wrong that the backoff should have absorbed, and
+# the run log will say so.
+#
+# UNPRIVILEGED ON PURPOSE. It runs as the logged-in user, not SYSTEM: the runner
+# needs that user's git credential, npm config and Claude session, and SYSTEM has
+# none of them. It is also the smaller blast radius for a process that spawns
+# workers with blanket bypassPermissions.
+
+[CmdletBinding()]
+param(
+  [Parameter(Position = 0)]
+  [ValidateSet('install', 'uninstall', 'start', 'stop', 'status', 'digest')]
+  [string]$Action = 'status',
+
+  # The checkout to run from. Defaults to the repo this script lives in, so the
+  # common case needs no argument and cannot point at the wrong tree by typo.
+  [string]$RepoRoot,
+
+  [string]$TaskName = 'Autobongos'
+)
+
+$ErrorActionPreference = 'Stop'
+
+if (-not $RepoRoot) {
+  $RepoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+}
+$LogDir = Join-Path $env:LOCALAPPDATA 'cloudbongos'
+$LogFile = Join-Path $LogDir 'autobongos.log'
+$Wrapper = Join-Path $RepoRoot 'scripts\gds\autobongos-service.cmd'
+
+function Assert-Prereqs {
+  if (-not (Test-Path (Join-Path $RepoRoot 'scripts\gds\autobongos-run.js'))) {
+    throw "No autobongos-run.js under $RepoRoot -- pass -RepoRoot <path to the checkout>."
+  }
+  foreach ($exe in @('node', 'git', 'claude')) {
+    if (-not (Get-Command $exe -ErrorAction SilentlyContinue)) {
+      # Named, not guessed at: a runner that starts without `claude` on PATH will
+      # spawn-fail every worker and look like a mysterious outage in the log.
+      throw "'$exe' is not on PATH for this user. The runner needs node, git and claude."
+    }
+  }
+}
+
+function Show-Status {
+  $t = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+  if (-not $t) { Write-Host "not installed  (task '$TaskName' does not exist)"; return }
+  $info = Get-ScheduledTaskInfo -TaskName $TaskName
+  Write-Host "task       : $TaskName"
+  Write-Host "state      : $($t.State)"
+  Write-Host "last run   : $($info.LastRunTime)  (result $($info.LastTaskResult))"
+  Write-Host "next run   : $($info.NextRunTime)"
+  Write-Host "log        : $LogFile"
+  if (Test-Path $LogFile) {
+    Write-Host "log size   : $([math]::Round((Get-Item $LogFile).Length / 1KB)) KB"
+    Write-Host ''
+    Write-Host '--- last 15 lines ---'
+    Get-Content $LogFile -Tail 15
+  } else {
+    Write-Host 'log        : (not written yet)'
+  }
+  Write-Host ''
+  Write-Host 'The scheduler only says whether the PROCESS is up. Whether the runner'
+  Write-Host 'is actually working is the hall: it reads the heartbeat this posts.'
+}
+
+switch ($Action) {
+  'install' {
+    Assert-Prereqs
+    New-Item -ItemType Directory -Force -Path $LogDir | Out-Null
+
+    $action = New-ScheduledTaskAction -Execute $Wrapper -WorkingDirectory $RepoRoot
+    # AtStartup covers the cold reboot the done-when actually names. AtLogOn is
+    # NOT used: it would wait for someone to sign in, which is the one thing that
+    # must not be required.
+    $trigger = New-ScheduledTaskTrigger -AtStartup
+    $principal = New-ScheduledTaskPrincipal -UserId "$env:USERDOMAIN\$env:USERNAME" -LogonType S4U -RunLevel Limited
+    $settings = New-ScheduledTaskSettingsSet `
+      -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
+      -StartWhenAvailable `
+      -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) `
+      -ExecutionTimeLimit ([TimeSpan]::Zero) `
+      -MultipleInstances IgnoreNew
+    # ExecutionTimeLimit ZERO = never kill it. The default is three days, and a
+    # daemon silently executed after three days is exactly the invisible death
+    # this whole task exists to prevent.
+    # MultipleInstances IgnoreNew = the scheduler will not start a second copy
+    # over a live one; the heartbeat file is the second guard, inside the runner.
+
+    Register-ScheduledTask -TaskName $TaskName -Action $action -Trigger $trigger `
+      -Principal $principal -Settings $settings -Force | Out-Null
+
+    Write-Host "installed '$TaskName' -- starts at boot, restarts on crash, logs to $LogFile"
+    Write-Host ''
+    Write-Host 'Start it now with:   .\scripts\gds\autobongos-service.ps1 start'
+    Write-Host 'Then confirm from the hall (/builders/gate) that it is checking in.'
+  }
+  'uninstall' {
+    Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
+    Write-Host "removed '$TaskName'. The log at $LogFile is left in place."
+  }
+  'digest' {
+    # The night in one page (task 1003906). On the box for convenience; the same
+    # five answers are what the Gate page and a mailed digest would carry.
+    & node (Join-Path $RepoRoot 'scripts\gds\autobongos-digest.js') @args
+  }
+  'start'  { Start-ScheduledTask -TaskName $TaskName; Write-Host "started '$TaskName'" }
+  'stop'   {
+    Stop-ScheduledTask -TaskName $TaskName
+    Write-Host "stopped '$TaskName' -- but note this only stops the PROCESS on this machine."
+    Write-Host 'The durable way to stop the runner is the kill switch in the hall, which'
+    Write-Host 'survives a reboot and cannot be undone by anything running here.'
+  }
+  default  { Show-Status }
+}