@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/autobongos-run.js

@@ -0,0 +1,1361 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/autobongos-run.js — the Autobongos supervisor's I/O half
+// (task 1003902; ADR 0307 §1). One iteration is: gauge → pick → claim → spawn
+// one worker → record. No model anywhere in this file; every branch it takes is
+// a branch a person can read.
+//
+//   node scripts/bongos/autobongos-run.js --forever                 # the daemon shape
+//   node scripts/bongos/autobongos-run.js                           # one task, then exit
+//   node scripts/bongos/autobongos-run.js --goal 1000119            # narrow to one goal
+//   node scripts/bongos/autobongos-run.js --max-tasks 5
+//   node scripts/bongos/autobongos-run.js --dry-run                 # pick only, claim nothing
+//
+// SCOPE, and what deliberately is NOT here:
+//   · the ALLOWLIST and the KILL SWITCH live in the DATABASE (task 1003908,
+//     ADR 0307 §6) and are read at step 0 of every iteration. `--goal` and
+//     AUTOBONGOS_GOALS survive only as a NARROWING filter — they can take goals
+//     away from the allowlist and can never add one, because a setting on this
+//     machine is editable by the very bypassPermissions worker the allowlist
+//     exists to bound.
+//   · CONFIRMING a ship against the ledger is autobongos-verify.js (task
+//     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.
+//   · 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');
+const {
+  buildWorkerArgs, buildWorkerPrompt, classifyRun, usageLimitHit, DEFAULT_MODEL, DEFAULT_WORKER_TIMEOUT_MS,
+} = require('./autobongos-loop.js');
+const { verifyShip, failureReason, recheckLands, pendingLandIds } = require('./autobongos-verify.js');
+const gradeCap = require('./autobongos-grade-cap.js');
+const fence = require('../../modules/autonomy/fence.js');
+const tweakLane = require('./autobongos-tweak-lane.js');
+// The ADR 0043 protected-path registry, reused rather than re-derived. scripts/
+// sits outside the kernel boundary, so this direct core require is allowed here
+// 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 { resolveEnv, envPrefix, LEGACY_ENV_PREFIXES } = require('../../src/instance-config');
+const cadence = require('../../modules/autonomy/cadence.js');
+const configIdle = require('../../modules/autonomy/config-idle.js');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+function readArgv(argv) {
+  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; }
+    if (a.startsWith('--goal=')) { out.goals.push(Number(a.slice(7))); continue; }
+    if (a === '--max-tasks') { out.maxTasks = Number(argv[++i]); continue; }
+    if (a === '--model') { out.model = argv[++i]; continue; }
+    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);
+  }
+  // NOTE the semantics changed in task 1003908: `out.goals` is a REQUESTED filter,
+  // intersected with the database allowlist. An empty list no longer means "refuse
+  // to run" — it means "every allowlisted goal" — because the thing that refuses
+  // when nothing is permitted is now the fence, which this machine cannot edit.
+  return out;
+}
+
+const run = (file, args, opts = {}) => new Promise((resolve) => {
+  execFile(file, args, { cwd: REPO_ROOT, maxBuffer: 32 * 1024 * 1024, ...opts },
+    (err, stdout, stderr) => resolve({ ok: !err, code: err ? (err.code ?? 1) : 0, stdout: stdout || '', stderr: stderr || '' }));
+});
+
+// The run log is the supervisor's own record. It is NOT the ledger — Bongos is —
+// but a machine nobody is watching must be able to say afterwards what it did,
+// and an append-only JSONL survives a kill -9 mid-iteration.
+function logPath() {
+  if (process.env.AUTOBONGOS_LOG_FILE) return process.env.AUTOBONGOS_LOG_FILE;
+  try { return require('../../src/instance-config.js').configPath('autobongos-runs.jsonl'); }
+  catch (_) { return path.join(REPO_ROOT, 'autobongos-runs.jsonl'); }
+}
+
+function record(entry) {
+  const row = { at: new Date().toISOString(), ...entry };
+  try {
+    const p = logPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, `${JSON.stringify(row)}\n`);
+  } catch (_) { /* a runner that cannot log must still run */ }
+  return row;
+}
+
+// readRunLogRows — the run log back as rows, newest last. Only the TAIL is read
+// (a log that runs for weeks must not be slurped whole every loop), and a line
+// that will not parse — the half-written last line of a kill -9 — is skipped.
+function readRunLogRows(p = logPath(), maxBytes = 4 * 1024 * 1024) {
+  let text = '';
+  try {
+    const size = fs.statSync(p).size;
+    const fd = fs.openSync(p, 'r');
+    try {
+      const len = Math.min(size, maxBytes);
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, size - len);
+      text = buf.toString('utf8');
+    } finally { fs.closeSync(fd); }
+  } catch (_) { return []; }
+  const rows = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); } catch (_) { /* partial line */ }
+  }
+  return rows;
+}
+
+// recheckPendingLands — once per loop (task 1004538). Which tasks are waiting on
+// a land comes from the run log on disk and when they shipped comes from the
+// ledger, so a restart loses neither. Open `shipped_no_artifact` blockers are read
+// from the database and resolved once main carries the commit. Every outcome is a
+// row, so the next pass reads it back.
+//
+// The blocker sweep runs at most once per LAND_SWEEP_MS per process (and at once
+// after a restart): a false alarm closing within the hour is plenty, and the
+// open-blocker list need not be read on every loop. Pending lands are re-probed
+// every loop — and cost nothing when there are none.
+const LAND_SWEEP_MS = 60 * 60 * 1000;
+async function recheckPendingLands(deps = {}) {
+  const log = deps.record || record;
+  const st = deps.state || RUNNER_STATE;
+  const now = deps.now ? deps.now() : Date.now();
+  const sweepBlockers = !st.landSweepAt || now - st.landSweepAt >= LAND_SWEEP_MS;
+  const ids = pendingLandIds(readRunLogRows());
+  if (!ids.length && !sweepBlockers) return { rechecked: [], resolved: [], errors: [] };
+  const out = await recheckLands({ pendingIds: ids, sweepBlockers }, { ...(deps.api ? { api: deps.api } : {}), ...(deps.landDeps || {}) });
+  if (sweepBlockers) st.landSweepAt = now;
+  for (const r of out.rechecked) log({ event: 'land_recheck', ...r });
+  for (const r of out.resolved) {
+    log({ event: 'land_blocker_resolved', task_id: r.task_id, blocker_id: r.blocker_id, sha: r.sha,
+      reason: `main now carries ${r.sha} naming task ${r.task_id} — the no-artifact blocker was a slow land, resolved` });
+  }
+  if (out.errors.length) log({ event: 'land_recheck_failed', errors: out.errors.slice(0, 10) });
+  return out;
+}
+
+// pickedFrom — the row fields that say where a pick came from (task 1004453).
+// `priority` is true only when the fence named a priority goal AND this pick came
+// from it, so "the priority goal ran dry and the runner moved on" reads as
+// priority:false beside the goal it moved on to.
+function pickedFrom(goalId, gate) {
+  const p = gate && gate.priorityGoal != null ? gate.priorityGoal : null;
+  return { priority: p !== null && Number(goalId) === p };
+}
+
+// pickTask — the allowlisted goals, in order, through sequence.js's halt matrix.
+// The matrix is reused rather than re-derived: it already refuses thin specs,
+// protected paths, judgement kinds and unmet dependencies, from facts on the row.
+// The assembly below mirrors sequence.js's own --goal --next path step for step,
+// so the runner and a person running /builder-sequence cannot disagree about
+// which task is next.
+//
+// `claimableIds` is fetched because the matrix's `not_claimable` reason defers to
+// the server's own feed rather than re-deriving its filter here. A null (feed
+// unreadable) makes that one reason stay QUIET rather than halt everything —
+// ADR 0153 records the bug where the opposite turned an empty read into a
+// universal halt.
+async function pickTask(goals, deps = {}) {
+  const api = deps.api || await (require('./cli-lib').cliClient)();
+  let rank = deps.rank;
+  if (rank === undefined) {
+    const me = await api.me.getMe();
+    rank = me.ok ? me.data.builder?.rank : null;
+  }
+  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); }
+    catch (e) { return { error: `goal ${goalId}: ${e.message}` }; }
+
+    const candidates = Array.from(byId.values()).filter((t) => !seq.TERMINAL.has(t.status));
+    const { order } = seq.topoOrder(candidates);
+    // Tasks this process set aside after a refused claim (task 1004396) drop out
+    // AFTER ordering, so a dependent of one is still halted by its own unmet
+    // dependency rather than promoted by the task's absence.
+    const exclude = deps.exclude || null;
+    const unexcluded = exclude && exclude.size ? order.filter((t) => !exclude.has(String(t.id))) : order;
+    // Work this machine structurally cannot do — SSH, root, systemd on a live
+    // host (task 1004537) — is skipped BEFORE the claim, and listed with its
+    // reason. It is decided here and not in sequence.js's matrix because the
+    // matrix also serves /builder-sequence, where the builder may well hold the
+    // host access an unattended runner never has.
+    const hostSkipped = [];
+    const open = unexcluded.filter((t) => {
+      const host = fence.needsHostAccess(t);
+      if (!host.needs) return true;
+      hostSkipped.push({ id: t.id, title: t.title, reasons: [{ code: 'needs_host_access', detail: `${fence.REFUSALS.needs_host_access} (${host.signals.join('; ')})` }] });
+      return false;
+    });
+    const { next, skipped } = seq.pickNext(open, { rank, claimableIds });
+    if (next) return { task: next, goalId, skipped: [...hostSkipped, ...skipped] };
+    for (const sk of [...hostSkipped, ...skipped]) allSkipped.push({ ...sk, goal_id: goalId });
+  }
+  return { none: true, skipped: allSkipped };
+}
+
+// WORKER_ENV_ALLOW — what a worker is allowed to inherit (grader finding, task
+// 1003902). Spreading `process.env` handed a bypassPermissions session every
+// credential the supervisor happened to hold — DB URLs, npm and git tokens — to a
+// process whose only injection defence is a prompt fence. The fence is good and
+// it is not a technical barrier, so the blast radius of a jailbreak has to be
+// bounded by something that is.
+//
+// The worker needs: to run node and claude (PATH/HOME/SHELL and the platform's
+// own required vars), to reach the instance (BONGOS_API_BASE), and to be told it
+// is a subagent. It does NOT need a git push credential — the road to main is the
+// server-mediated pipeline (ADR 0307 §6) — so none is passed.
+function claudeBinEnvNames() {
+  return [...new Set([envPrefix(), ...LEGACY_ENV_PREFIXES].map((p) => `${p}_CLAUDE_BIN`)), 'CLAUDE_BIN'];
+}
+
+const WORKER_ENV_ALLOW = [
+  'PATH', 'HOME', 'SHELL', 'LANG', 'LC_ALL', 'TZ', 'TMPDIR', 'USER', 'LOGNAME',
+  'SystemRoot', 'windir', 'COMSPEC', 'PATHEXT', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP',
+  'BONGOS_API_BASE', 'CLOUDBONGOS_API_BASE',
+  // Every spelling resolveWorkerBin below can read (task 1001441): the branded
+  // <PREFIX>_CLAUDE_BIN, the legacy ones, and the unprefixed CLAUDE_BIN. A name
+  // missing here would be set on the host and silently absent in the worker.
+  ...claudeBinEnvNames(),
+  'XDG_CONFIG_HOME',
+  // THE WORKER'S OWN CREDENTIAL, and it has to be here (task 1003907, found by
+  // running it). On a desktop, the claude CLI authenticates from the credential
+  // store under USERPROFILE/HOME, which are already allowed - so this list looked
+  // complete. On a HEADLESS host there is no interactive login to have written
+  // one, and setup.js's own preflight says to set CLAUDE_CODE_OAUTH_TOKEN there
+  // instead. Stripping it meant every worker on the machine this was built for
+  // started unauthenticated, exited in ~2s, and the run recorded only "worker
+  // output was not JSON".
+  //
+  // This is not the leak the list exists to prevent. The worker IS a Claude
+  // session; its own auth is the one credential it cannot do its job without.
+  // Everything the comment above refuses - DB URLs, git and npm tokens - stays
+  // refused.
+  'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY',
+];
+
+function workerEnv(source = process.env, extra = {}) {
+  const out = {};
+  for (const k of WORKER_ENV_ALLOW) if (source[k] !== undefined) out[k] = source[k];
+  // An operator can widen this deliberately and visibly, never by accident.
+  const widen = String(source.AUTOBONGOS_WORKER_ENV_EXTRA || '').split(',').map((x) => x.trim()).filter(Boolean);
+  for (const k of widen) if (source[k] !== undefined) out[k] = source[k];
+  return { ...out, OTB_SUBAGENT: '1', ...extra };
+}
+
+const MAX_WORKER_OUTPUT = 8 * 1024 * 1024;   // a misbehaving worker must not grow memory until the timeout
+
+// resolveWorkerBin — WHICH `claude`, and whether it needs a shell.
+//
+// THE BUG THIS EXISTS FOR (task 1003907, found by running it on the real Windows
+// host). On Windows `claude` on PATH is a .cmd shim, and Node has refused to
+// spawn .cmd/.bat without a shell since CVE-2024-27980 — so this used to pass
+// `shell: process.platform === 'win32'`. But `shell: true` does not pass argv
+// through: it CONCATENATES it into one command line that cmd.exe re-parses,
+// which destroys every embedded quote. `--json-schema` is a JSON blob made
+// almost entirely of quotes, so claude received a mangled argument and exited in
+// ~2s with `--json-schema is not valid JSON`. Every worker. Every run. Forever —
+// and the cadence classes that as `quiet`, so it never trips the failure ladder.
+//
+// The npm package ships a REAL claude.exe beside the shim, so prefer it: a true
+// executable spawns with shell:false and exact argv, and nothing re-parses.
+// Falling back to the old behaviour is deliberate — a host with a differently
+// laid-out install should still run, and a corrupted schema surfaces as a failed
+// worker rather than as a refusal to start at all.
+function resolveWorkerBin(env = process.env, platform = process.platform) {
+  const override = resolveEnv('CLAUDE_BIN', { env }) || env.CLAUDE_BIN;
+  if (override) return { bin: override, shell: platform === 'win32' && /\.(cmd|bat)$/i.test(override) };
+  if (platform !== 'win32') return { bin: 'claude', shell: false };
+  for (const dir of String(env.PATH || env.Path || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const candidates = [
+      path.join(dir, 'node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude.exe'),
+      path.join(dir, 'claude.exe'),
+    ];
+    for (const c of candidates) {
+      try { if (fs.existsSync(c)) return { bin: c, shell: false }; } catch (_) {}
+    }
+  }
+  return { bin: 'claude', shell: true };
+}
+
+// gradeLedgerPath — the run's LOCAL ledger (task 1004536): the file ship.js reads
+// to refuse a third grade early. A fresh file per run, under the instance config
+// dir, never inside the task's tree. It is the courtesy half of the cap — see the
+// header of autobongos-grade-cap.js; the boundary is the server count below.
+const GRADE_CAP_WATCH_MS = 30_000;
+function gradeLedgerPath(taskId) {
+  const id = Number(taskId);
+  if (!Number.isSafeInteger(id) || id <= 0) throw new Error(`gradeLedgerPath: task id must be a positive integer, got ${taskId}`);
+  const name = path.join('autobongos-grades', `${id}-${Date.now()}-${crypto.randomBytes(3).toString('hex')}.jsonl`);
+  try { return require('../../src/instance-config.js').configPath(name); }
+  catch (_) { return path.join(os.tmpdir(), name); }
+}
+
+// gradeCapReader — how the supervisor counts this run's graded rounds.
+//
+// The SERVER's grade_attempts is the count that matters: the worker has no write
+// path to it, so clearing an env var or deleting a file cannot reset it. The
+// baseline is the newest attempt recorded BEFORE the worker starts; only rounds
+// after it belong to this run. When the server cannot be read, the local ledger
+// is the fallback — and either source showing the cap exhausted is enough.
+async function gradeCapReader({ api, taskId, ledger }) {
+  const before = await gradeCap.readServerAttempts(api, taskId);
+  const afterMs = before ? gradeCap.newestAttemptAt(before) : null;
+  return async function read() {
+    const local = gradeCap.gradeCapState(gradeCap.readLedger(ledger), taskId);
+    const attempts = before ? await gradeCap.readServerAttempts(api, taskId) : null;
+    if (!attempts) return { ...local, source: 'local' };
+    const server = gradeCap.gradeCapState(gradeCap.roundsFromAttempts(attempts, taskId, afterMs), taskId);
+    return server.exhausted || !local.exhausted ? { ...server, source: 'server' } : { ...local, source: 'local' };
+  };
+}
+
+// spawnWorker — one headless session, bounded by WALL CLOCK, in the task's own
+// working tree.
+async function spawnWorker({ task, model, timeoutMs, cwd, gradeLedger = null, capCheck = null, prompt: givenPrompt = null, deps = {} }) {
+  const spawnFn = deps.spawn || spawn;
+  const sessionId = deps.sessionId || crypto.randomUUID();   // pinned, so the session can be resumed
+  const { bin, shell: workerShell } = deps.resolveBin ? deps.resolveBin() : resolveWorkerBin();
+  const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+  const args = buildWorkerArgs({ sessionId, model, isRoot });
+  const prompt = givenPrompt || buildWorkerPrompt({ task });   // the tweak lane names its own (task 1004679)
+
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnFn(bin, args, {
+        cwd,
+        // stdin is a PIPE we write the prompt into and close. Never inherit: a
+        // `claude -p` with an open inherited stdin waits seconds for input that
+        // never comes, on every single spawn.
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: workerShell,
+        windowsHide: true,
+        // The run's local grade ledger (task 1004536): ship.js appends each graded
+        // round to it and refuses a third early. The worker can see this variable,
+        // so it is the courtesy half only — capCheck below is the boundary.
+        env: workerEnv(process.env, gradeLedger ? { [gradeCap.LEDGER_ENV]: gradeLedger } : {}),
+      });
+    } catch (e) { return resolve({ spawnError: e.message }); }
+
+    let stdout = ''; let stderr = ''; let timedOut = false; let truncated = false; let gradeCapped = false;
+    const cap = (cur, d) => {
+      if (cur.length >= MAX_WORKER_OUTPUT) { truncated = true; return cur; }
+      return cur + String(d).slice(0, MAX_WORKER_OUTPUT - cur.length);
+    };
+    const timer = setTimeout(() => { timedOut = true; try { child.kill('SIGKILL'); } catch (_) {} }, timeoutMs);
+    // task 1004536: once the second graded FAIL is recorded the run is over — the
+    // task goes to the owner. capCheck reads the SERVER's grade_attempts (see
+    // gradeCapReader), so a worker that cleared the ledger env or deleted the file
+    // is still stopped. One read at a time: a slow API must not stack polls.
+    let capBusy = false;
+    const capWatch = capCheck ? setInterval(async () => {
+      if (capBusy || gradeCapped) return;
+      capBusy = true;
+      try {
+        if ((await capCheck()).exhausted) {
+          gradeCapped = true; clearInterval(capWatch);
+          try { child.kill('SIGKILL'); } catch (_) {}
+        }
+      } catch (_) { /* an unreadable count is retried next tick; the post-run read still decides */ }
+      capBusy = false;
+    }, deps.capWatchMs || GRADE_CAP_WATCH_MS) : null;
+    const stopWatch = () => { if (capWatch) clearInterval(capWatch); };
+    child.stdout.on('data', (d) => { stdout = cap(stdout, d); });
+    child.stderr.on('data', (d) => { stderr = cap(stderr, d); });
+    child.on('error', (e) => { clearTimeout(timer); stopWatch(); resolve({ spawnError: e.message, sessionId }); });
+    child.on('close', (code) => {
+      clearTimeout(timer); stopWatch();
+      resolve({ envelope: stdout, exitCode: code, timedOut, truncated, gradeCapped, sessionId, stderr: stderr.slice(-2000) });
+    });
+    child.stdin.end(prompt);
+  });
+}
+
+// worktreeFor — the task gets its OWN linked working tree, and this is not a
+// nicety (grader finding, task 1003902).
+//
+// worktree-per-claim is an ENFORCED project default: worktree-claim-guard.js
+// refuses any claim made from the main checkout, with no escape but `--here`.
+// The natural shape for a long-lived unattended supervisor is one persistent
+// checkout — which is the main checkout — so the first cut of this loop would
+// have taken `claim_failed` on every single iteration and never done any work.
+// Reaching for `--here` would "fix" that by defeating the guard: the worker's
+// branch would land in the supervisor's own tree, which is precisely the strand
+// the guard exists to prevent.
+//
+// The name carries the task id plus a random suffix. Unique by construction, so
+// it cannot collide with another active claim's tree — a collision makes the
+// server store a disambiguated name the ship lock can never match (task 1004031).
+function worktreeName(taskId) {
+  return `autobongos-${taskId}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+// readFence — the two facts the fence is made of, in one place.
+//
+// BOTH come from the server. `GET /autonomy/fence` is the kill switch and the
+// allowlist; `GET /me`'s `grader_bypass` is ADR 0041's global grader killswitch,
+// resolved server-side from the server's own env. Neither is readable from a file
+// on this machine, and that is the entire point — see modules/autonomy/fence.js.
+//
+// A failure of EITHER read returns the shape that refuses. An unreachable
+// instance and a thrown kill switch are different facts, but they license the
+// same action: do nothing.
+async function readFence(deps = {}) {
+  const api = deps.api || await (require('./cli-lib').cliClient)();
+  let raw = null;
+  let graderBypassed = null;
+  try {
+    const r = await api.autonomy.getAutonomyFence();
+    if (r && r.ok) raw = r.data;
+  } catch (_) { /* unreadable → refuses below */ }
+  try {
+    const me = await api.me.getMe();
+    // Strictly a boolean or nothing. `undefined` from an older server is NOT
+    // `false`: it means this instance cannot tell us, which refuses.
+    if (me && me.ok && typeof me.data.grader_bypass === 'boolean') graderBypassed = me.data.grader_bypass;
+  } catch (_) { /* unreadable → refuses below */ }
+  return { raw, graderBypassed };
+}
+
+// ── what one process remembers between iterations (task 1004396) ────────────
+//
+// Owner ruling, 2026-09-30: a refused claim must not put the runner into waiting
+// by default. It sets THAT task aside and tries the next one. It waits only when
+// there is a block and nothing else it can claim.
+//
+// The two refusals are told apart by claim.js's exit code, because the message is
+// prose and the first cut of this read prose. The run that found this burned
+// ~30 attempts on task 1004254, whose refusal quoted "Your work changes the
+// tools…" — which reads like a per-task protected-path verdict and was in fact
+// the plain-words line of a QUEUE-WIDE gate about a different, stranded task.
+// Setting 1004254 aside would have moved the runner on to the next task, which
+// the same gate refuses too.
+//
+// QUEUE_GATED_EXIT is pinned against claim.js's own value in a test rather than
+// required from it: requiring the CLI would load its whole dependency graph into
+// a process that runs for weeks, to read one integer.
+const QUEUE_GATED_EXIT = 4;
+// How long a task refused ON ITS OWN is left alone. Not forever: most per-task
+// refusals clear (a dependency ships, a claim is released, a blocker resolves),
+// and a process that remembered them for its whole life would shelve work it can
+// do. Half an hour is several wakes at full speed, so a refused head of the queue
+// costs one attempt per half hour instead of one per wake.
+const CLAIM_SET_ASIDE_MS = 30 * 60 * 1000;
+// A bound on claim attempts in ONE pass, so a queue of refusals cannot turn one
+// iteration into dozens of worktree creations.
+const MAX_CLAIM_ATTEMPTS = 5;
+// A limit message with no machine-readable reset (the CLI's human forms name a
+// clock time in a zone we would have to guess). Half an hour is short against a
+// five-hour window and long against a spawn that is cut off in two seconds, so a
+// guess that is wrong costs one wasted spawn per half hour, not one per wake.
+const LIMIT_UNKNOWN_RESET_MS = 30 * 60 * 1000;
+
+function newRunnerState() {
+  return { setAside: new Map(), queueGate: null, limitUntil: null, diskHead: null, mainHead: null, landSweepAt: null };
+}
+const RUNNER_STATE = newRunnerState();
+
+// The stranded task ids a queue-gated refusal names ("  - task 777  Title"). An
+// empty list is a legal answer: the gate is still a gate, the runner simply has
+// nothing to poll and tries one claim per wake instead.
+function owedTaskIds(text) {
+  const ids = [];
+  const re = /^\s*-\s*task\s+(\d+)/gm;
+  let m;
+  while ((m = re.exec(String(text || ''))) !== null) ids.push(m[1]);
+  return ids;
+}
+
+// Does the gate still hold? Asked of the LEDGER, one read per stranded task, and
+// never by attempting a claim: a claim attempt per wake is the loop this replaces.
+// An unreadable task keeps the wait — guessing "cleared" would restart the
+// attempts on a read failure, the opposite of backing off.
+async function queueGateHolds(queueGate, deps = {}) {
+  if (!queueGate.owed.length) return false;
+  const api = deps.api && deps.api.tasks ? deps.api : await (require('./cli-lib').cliClient)();
+  for (const id of queueGate.owed) {
+    let r = null;
+    try { r = await api.tasks.getTasksId({ id: Number(id) }); } catch (_) { return true; }
+    if (!r || !r.ok || !r.data || !r.data.task) return true;
+    if (r.data.task.status === 'confirmed') return true;
+  }
+  return false;
+}
+
+function queueGatedRow(queueGate, now) {
+  const on = queueGate.owed.length ? queueGate.owed.map((id) => `task ${id}`).join(', ') : 'a stranded confirmed task';
+  return {
+    event: 'queue_gated', waiting_on: queueGate.owed,
+    waited_s: Math.max(0, Math.round((now - queueGate.since) / 1000)),
+    reason: `every claim is refused until ${on} lands — waiting, not claiming (${queueGate.reason})`,
+  };
+}
+
+async function iteration(opts, deps = {}) {
+  const runCmd = deps.run || run;
+  const spawnWork = deps.spawnWorker || spawnWorker;
+  const readGauge = deps.gauge || (() => gauge.evaluate());
+  const pick = deps.pickTask || pickTask;
+  const log = deps.record || record;
+
+  // 0. THE FENCE (task 1003908, ADR 0307 §6). Before the gauge, because three of
+  // its four gates make every task refusable and there is no sense paying for a
+  // capacity read to discover that. Before anything is picked, claimed or spawned,
+  // because a fence checked after the fact is not a fence.
+  const { raw, graderBypassed } = deps.readFence ? await deps.readFence(deps) : await readFence(deps);
+  // NOT named `run`. The module-level exec helper above is called `run`, and a
+  // `const run` anywhere in this function hoists into a Temporal Dead Zone that
+  // covers the WHOLE body — including `deps.run || run` at the top, which is the
+  // PRODUCTION call shape (main() passes no deps). That shadowing threw
+  // `ReferenceError: Cannot access 'run' before initialization` on the first line
+  // of every real iteration while every test stayed green, because the harness
+  // always injected deps.run. Caught by the grader on task 1003908; the test that
+  // now drives iteration() with no deps is the actual fix — this rename is half.
+  const gate = fence.decideRun({ fence: raw, requestedGoals: opts.goals, graderBypassed });
+  // ADR 0371 D3 (task 1004679): the tweak lane's own setting replaces the GOAL
+  // ALLOWLIST for that lane only, so a fence that refused on goals alone still lets
+  // the lane run below; the kill switch and the grader stop refuse it here.
+  const fencedRow = () => log({ event: 'fenced', code: gate.code, reason: gate.reason, refused_goals: gate.refusedGoals || [] });
+  const goalsOnly = !gate.go && tweakLane.GOAL_ONLY_CODES.has(gate.code)
+    && await (deps.laneSwitchOn || tweakLane.laneSwitchOn)(deps.api);
+  if (!gate.go && !goalsOnly) return fencedRow();
+
+  // 1. The gauge. Never start a task we cannot pay for out of the window.
+  const g = readGauge();
+  if (!g.decision.go) {
+    return log({ event: 'hold', go: false, unknown: !!g.decision.unknown, reason: g.decision.reason, sleep_until: g.decision.sleepUntil ?? null });
+  }
+
+  // 1b. The usage limit, once HIT (task 1004454). Owner ruling 2026-09-30: no
+  // fixed cap on how much work a reading buys — the gauge above is read before
+  // every task and a derived reading proceeds — and hitting the limit is
+  // acceptable, so long as the runner then waits for the reset and resumes by
+  // itself. A worker cut off by the limit records when it resets; until then no
+  // task is taken, because every worker spawned would be cut off the same way.
+  const state = deps.state || RUNNER_STATE;
+  const now = deps.now ? deps.now() : Date.now();
+  if (state.limitUntil) {
+    if (now < state.limitUntil) {
+      return log({
+        event: 'hold', go: false, unknown: false, usage_limit: true,
+        reason: 'the subscription usage limit was hit — sleeping to its reset, then resuming by itself',
+        sleep_until: Math.round(state.limitUntil / 1000),
+      });
+    }
+    log({ event: 'usage_limit_reset', was_until: new Date(state.limitUntil).toISOString() });
+    state.limitUntil = null;
+  }
+
+  // 1c. A QUEUE-WIDE gate from an earlier pass (task 1004396). While the
+  // stranded task it named is still `confirmed`, every claim would be refused, so
+  // none is attempted. The wait wakes early when main moves (waitOrJump), which is
+  // exactly what the strand landing does.
+  if (state.queueGate) {
+    if (await queueGateHolds(state.queueGate, deps)) return log(queueGatedRow(state.queueGate, now));
+    log({ event: 'queue_gate_cleared', waited_on: state.queueGate.owed, waited_s: Math.max(0, Math.round((now - state.queueGate.since) / 1000)) });
+    state.queueGate = null;
+  }
+  for (const [id, until] of state.setAside) if (until <= now) state.setAside.delete(id);
+
+  // 1d. THE TWEAK LANE (task 1004679, ADR 0371 D1): before ordinary work, the
+  // oldest submitted page round the lane may take. Null means it took none.
+  const laneRow = await (deps.tweakLaneStep || tweakLane.tweakLaneStep)({ opts, state }, {
+    api: deps.api || await (require('./cli-lib').cliClient)(), log, matchProtected, runCmd, spawnWork,
+    worktreeName: deps.worktreeName || worktreeName, spawnDeps: deps, gradeCapReader,
+    gradeLedgerPath: deps.gradeLedgerPath || gradeLedgerPath, ...(deps.laneDeps || {}),
+  });
+  if (laneRow) return laneRow;
+  if (goalsOnly) return fencedRow();
+
+  // 2–4, up to MAX_CLAIM_ATTEMPTS times: pick, fence, tree, claim. A task refused
+  // on its own is set aside and the NEXT one is tried in the same pass.
+  let task = null; let picked = null; let wtName = null; let wtPath = null;
+  let lastRefusal = null;
+  for (let attempt = 0; attempt < MAX_CLAIM_ATTEMPTS && !task; attempt++) {
+    const exclude = new Set(state.setAside.keys());
+    // 2. Pick — from the ALLOWLISTED goals, never from what the command line asked
+    // for. gate.goals is already the intersection.
+    const got = await pick(gate.goals, { ...(deps.pickDeps || {}), exclude });
+    if (got.error) return log({ event: 'pick_failed', reason: got.error });
+    // A picker that hands back a set-aside task is treated as having none left:
+    // the exclusion is this function's contract, not the picker's courtesy.
+    if (got.none || exclude.has(String(got.task.id))) {
+      // Everything left was refused in THIS pass: return the last refusal, not
+      // "nothing claimable". Every claim failing at once is also what an outage
+      // looks like, and it must still reach the failure ladder (task 1004179).
+      if (lastRefusal) return lastRefusal;
+      return log({
+        event: 'nothing_claimable', goals: gate.goals, priority_goal: gate.priorityGoal ?? null,
+        // 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: (got.skipped || []).map((sk) => ({ id: sk.id, goal_id: sk.goal_id, reasons: (sk.reasons || []).map((r) => r.code) })),
+        set_aside: Array.from(state.setAside, ([id, until]) => ({ id, until: new Date(until).toISOString() })),
+      });
+    }
+    const candidate = got.task;
+
+    // 2b. The per-TASK half of the fence. sequence.js's halt matrix already refuses
+    // a protected-path task, and this re-asks anyway — not from distrust of the
+    // matrix, but because the matrix is a shared component with its own callers and
+    // the fence must not be a property of whoever happens to be picking. A gate that
+    // only holds while a collaborator keeps calling it is not a gate.
+    //
+    // Both halves read the task's DECLARED touches[], which is a claim, not a fact —
+    // see the header of modules/autonomy/fence.js for why that is acceptable as the
+    // OUTER of three layers and would not be as the only one.
+    const taskGate = fence.decideTask({
+      task: candidate, goals: gate.goals, protectedHits: matchProtected(candidate.touches || []),
+    });
+    if (!taskGate.go) {
+      return log({ event: 'fenced', code: taskGate.code, reason: taskGate.reason, task_id: candidate.id, goal_id: got.goalId, ...pickedFrom(got.goalId, gate), globs: taskGate.globs || [] });
+    }
+
+    if (opts.dryRun) return log({ event: 'dry_run', task_id: candidate.id, title: candidate.title, goal_id: got.goalId, ...pickedFrom(got.goalId, gate) });
+
+    // 3. The task's own working tree.
+    const name = deps.worktreeName ? deps.worktreeName(candidate.id) : worktreeName(candidate.id);
+    const made = await runCmd(process.execPath, [path.join('scripts', 'bongos', 'worktree.js'), 'add', name, '--base', 'origin/main']);
+    if (!made.ok) {
+      return log({ event: 'worktree_failed', task_id: candidate.id, worktree: name, reason: failureReason(made, 'worktree.js') });
+    }
+    const treePath = path.join(REPO_ROOT, '.claude', 'worktrees', name);
+
+    // 4. Claim FROM that tree, so claim.js records it as the claim's tree and the
+    // ship lock later agrees with where the work actually is.
+    const claimed = await runCmd(process.execPath, [path.join(REPO_ROOT, 'scripts', 'bongos', 'claim.js'), String(candidate.id)], { cwd: treePath });
+    if (!claimed.ok) {
+      await runCmd(process.execPath, [path.join('scripts', 'bongos', 'worktree.js'), 'remove', name]);
+      const reason = failureReason(claimed, 'claim.js');
+      if (claimed.code === QUEUE_GATED_EXIT) {
+        state.queueGate = { owed: owedTaskIds(`${claimed.stderr || ''}\n${claimed.stdout || ''}`), since: now, reason };
+        return log({ ...queueGatedRow(state.queueGate, now), task_id: candidate.id, worktree: name });
+      }
+      state.setAside.set(String(candidate.id), now + CLAIM_SET_ASIDE_MS);
+      lastRefusal = log({ event: 'claim_failed', task_id: candidate.id, worktree: name, reason, set_aside_s: CLAIM_SET_ASIDE_MS / 1000 });
+      continue;
+    }
+    task = candidate; picked = got; wtName = name; wtPath = treePath;
+  }
+  if (!task) return lastRefusal;
+
+  // 5. Work, in that tree.
+  const started = Date.now();
+  const gradeLedger = deps.gradeLedgerPath ? deps.gradeLedgerPath(task.id) : gradeLedgerPath(task.id);
+  // Same client rule as verifyShip below: an injected api is used as given.
+  let capApi = deps.api || null;
+  if (!capApi) { try { capApi = await (require('./cli-lib').cliClient)(); } catch (_) { capApi = null; } }
+  const capCheck = await gradeCapReader({ api: capApi, taskId: task.id, ledger: gradeLedger });
+  const res = await spawnWork({ task, model: opts.model, timeoutMs: opts.timeoutMs, cwd: wtPath, gradeLedger, capCheck, deps });
+  let verdict = classifyRun(res);
+  // 5b. THE GRADE CAP (task 1004536). The owner's rule — a task that fails the
+  // grade twice goes to the owner — read from the run's ledger, not from the
+  // worker's verdict: the worker was told this in its prompt and kept re-grading.
+  const grades = await capCheck();
+  try { fs.rmSync(gradeLedger, { force: true }); } catch (_) {}   // its counts travel in the run-log row
+  if (grades && grades.exhausted) {
+    verdict = {
+      ...verdict, outcome: 'needs_human', releaseClaim: true,
+      reason: `the grade failed ${grades.fails} times in this run — handed to the owner instead of re-graded again (task 1004536)`,
+    };
+  }
+  // Cut off by the usage limit? Recorded here so the NEXT iteration sleeps to the
+  // reset instead of spawning a worker that will be cut off the same way.
+  const limit = verdict.outcome === 'claims_shipped' ? null : usageLimitHit({ envelope: res.envelope, stderr: res.stderr });
+  if (limit) state.limitUntil = limit.resetAt ? limit.resetAt * 1000 : now + LIMIT_UNKNOWN_RESET_MS;
+
+  // 6. VERIFY FROM THE LEDGER (task 1003903). Read the task back from Bongos and
+  // let IT say what happened — for every outcome, not only a claimed ship. The
+  // worker's own verdict becomes context in the blocker body, never the branch: a
+  // worker that stopped dead needing a decision and one that finished the job
+  // return structurally identical envelopes, and the ledger is the only thing
+  // that can tell them apart.
+  //
+  // The release decision moved HERE from the worker's verdict, and that move is
+  // the point of the step rather than a tidy-up. `still_held` is a fact about the
+  // ledger; `worker_failed` is a report from the thing being checked. The TREE is
+  // left alone either way — it may hold committed work, and the land/ship
+  // pipeline owns worktree cleanup.
+  const ledger = await verifyShip(
+    { taskId: task.id, taskTitle: task.title, worker: { outcome: verdict.outcome, reason: verdict.reason } },
+    {
+      api: deps.api,
+      cwd: wtPath,
+      release: deps.release || ((id, reason) => runCmd(process.execPath,
+        [path.join(REPO_ROOT, 'scripts', 'bongos', 'release.js'), String(id), '--reason', reason], { cwd: wtPath })),
+      ...(deps.verifyDeps || {}),
+    },
+  );
+
+  const row = {
+    event: 'worked', task_id: task.id, title: task.title, goal_id: picked.goalId,
+    ...pickedFrom(picked.goalId, gate),
+    worktree: wtName,
+    outcome: verdict.outcome, reason: verdict.reason,
+    session_id: res.sessionId || null, duration_s: Math.round((Date.now() - started) / 1000),
+    cost_usd: verdict.costUsd ?? null,
+    ...(grades && (grades.graded || grades.outages) ? { grade_rounds: grades.graded, grade_outages: grades.outages, grade_cap_reached: grades.exhausted, grade_count_source: grades.source } : {}),
+    output_truncated: !!res.truncated,
+    ...(limit ? { usage_limit: { reset_at: limit.resetAt } } : {}),
+    undetermined_decisions: verdict.verdict ? verdict.verdict.undetermined_decisions : null,
+    // 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,
+    task_parked: !!(ledger.blocker && ledger.blocker.parked),
+  };
+  // An unreadable ledger stops the run. Picking another task while unable to see
+  // what happened to the last one is how a machine nobody is watching digs.
+  if (ledger.halt) row.event = 'verify_halt';
+  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(), runnerState = RUNNER_STATE) {
+  try {
+    const p = heartbeatPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    // `head` is what this process is RUNNING, not what is on disk (task 1004374).
+    // Alive and alive-on-stale-code look identical from a check-in age alone.
+    // `disk_head` appears only when the checkout was refreshed in place past what
+    // is running (task 1004406): "up to date on disk, old supervisor" is visible.
+    const disk = runnerState && runnerState.diskHead && runnerState.diskHead !== LOADED_HEAD ? runnerState.diskHead : undefined;
+    fs.writeFileSync(p, JSON.stringify({ pid: process.pid, at: now, head: LOADED_HEAD, ...(disk ? { disk_head: disk } : {}) }));
+    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();
+
+// claudeAccountLabel — WHICH Claude account this machine's workers spend
+// (task 1004407), as a label and never a secret. Workers inherit
+// ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN from this process
+// (WORKER_ENV_ALLOW), and either one outranks the stored login, so those are
+// named first, by the variable that is set and never by its value. Otherwise it
+// is the login Claude Code itself records in ~/.claude.json (oauthAccount): the
+// email, plus the organisation when it has one. Read on every beat, so signing
+// a different account in shows up without a restart; null when nothing can be
+// read, which the card leaves blank rather than guessing.
+function claudeAccountLabel({ env = process.env, readFile = (p) => fs.readFileSync(p, 'utf8') } = {}) {
+  if (env.ANTHROPIC_API_KEY) return 'an API key (ANTHROPIC_API_KEY)';
+  if (env.CLAUDE_CODE_OAUTH_TOKEN) return 'a Claude token (CLAUDE_CODE_OAUTH_TOKEN)';
+  try {
+    const dir = env.CLAUDE_CONFIG_DIR || os.homedir();
+    const acct = JSON.parse(readFile(path.join(dir, '.claude.json'))).oauthAccount || {};
+    const email = typeof acct.emailAddress === 'string' ? acct.emailAddress.trim() : '';
+    if (!email) return null;
+    const org = typeof acct.organizationName === 'string' ? acct.organizationName.trim() : '';
+    return (org ? `${email} · ${org}` : email).slice(0, 200);
+  } catch (_) { return null; }
+}
+
+// heartbeatIdentity — the fields that say which code and which account (task
+// 1004407). Undefined fields are dropped, so a runner that cannot read its own
+// commit sends nothing for it rather than an empty string the route would refuse.
+function heartbeatIdentity(deps = {}) {
+  const st = deps.state || RUNNER_STATE;
+  const out = {
+    head: LOADED_HEAD || undefined,
+    disk_head: st.diskHead && st.diskHead !== LOADED_HEAD ? st.diskHead : undefined,
+    main_head: st.mainHead || undefined,
+    claude_account: (deps.claudeAccountLabel || claudeAccountLabel)() || undefined,
+  };
+  for (const k of Object.keys(out)) if (out[k] === undefined) delete out[k];
+  return out;
+}
+
+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,
+        ...heartbeatIdentity(deps),
+        ...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', 'bongos', '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 });
+}
+
+// UPGRADE_EXIT_CODE — the one exit `--forever` is allowed to make (task 1004374).
+//
+// THE PROBLEM. autobongos-service.cmd refreshes the checkout with git fetch +
+// reset --hard origin/main BEFORE launching node, and only then. `--forever`
+// never returns, by design (task 1003904): a stopped daemon on an always-on
+// machine is indistinguishable from a working one. Together those mean a
+// process never re-reads its code, so a shipped fix reaches the disk and never
+// reaches the runner, and nothing restarts it — not stopping IS the design. On
+// the host this ran week-old code for four days across three landed fixes,
+// while the heartbeat said alive and the hall showed a healthy runner.
+//
+// WHY AN EXIT IS SAFE HERE, when task 1003904 forbids exiting. That rule exists
+// so a machine nobody watches cannot look idle while it is dead. This exit is
+// the opposite: it is deliberate, it is logged as `upgrade_exit`, and the
+// WRAPPER loops on this specific code — re-running the fetch + reset and
+// relaunching — so the runner is not depending on Task Scheduler noticing.
+// Every other exit still falls through to the scheduler exactly as before.
+const UPGRADE_EXIT_CODE = 75;
+
+// MIN_UPTIME_BEFORE_UPGRADE_MS — the guard against a restart storm.
+//
+// The wrapper's `git reset --hard origin/main` is BEST EFFORT: a fetch that
+// fails leaves the checkout behind on purpose, because being a commit behind
+// beats not running at all. Without this guard that becomes a spin — the runner
+// starts behind, sees drift on its first loop, exits, and the wrapper relaunches
+// it into the same state as fast as the machine allows. One minute of required
+// uptime turns a failing fetch into a slow retry instead.
+const MIN_UPTIME_BEFORE_UPGRADE_MS = 60_000;
+
+// loadedHead — the commit this PROCESS is running, read once. Not re-read: the
+// point is to compare what is executing against what has landed, and re-reading
+// would just track the disk, which the wrapper already moves.
+let LOADED_HEAD = null;
+async function loadedHead(deps = {}) {
+  if (LOADED_HEAD !== null) return LOADED_HEAD;
+  const runCmd = deps.run || run;
+  try {
+    const r = await runCmd('git', ['rev-parse', 'HEAD'], { cwd: REPO_ROOT });
+    LOADED_HEAD = r && r.ok ? String(r.stdout || '').trim() || null : null;
+  } catch (_) { LOADED_HEAD = null; }
+  return LOADED_HEAD;
+}
+
+// codeDrifted — has main moved past the code this process loaded?
+//
+// Fails CLOSED in the "keep running" direction: an unreadable local head or an
+// unreachable origin returns false, so a network blip never cycles the runner.
+// The cost of a missed upgrade is one more loop; the cost of a false positive is
+// a restart storm.
+async function codeDrifted(deps = {}) {
+  // Injectable like every other collaborator here: the module-level cache is
+  // right for production (read the running commit ONCE) and would otherwise make
+  // the comparison untestable in isolation.
+  const mine = deps.loadedHead ? await deps.loadedHead(deps) : await loadedHead(deps);
+  if (!mine) return null;
+  // Measured from what is on DISK once the checkout has been refreshed in place
+  // (task 1004406), or every loop after a refresh would see the same drift again.
+  const base = ((deps.state || RUNNER_STATE).diskHead) || mine;
+  let tip = null;
+  try { tip = await runFetchHead(deps); } catch (_) { return null; }
+  if (!tip) return null;
+  // Kept for the heartbeat (task 1004407), so the hall can say "behind main"
+  // without the server ever reaching GitHub itself.
+  (deps.state || RUNNER_STATE).mainHead = tip;
+  return tip !== base ? { from: base.slice(0, 8), to: String(tip).slice(0, 8) } : false;
+}
+
+// ── pull always, restart rarely (task 1004406) ──────────────────────────────
+//
+// Owner-approved 2026-09-30. Main moves every time ANY session lands, and a
+// relaunch per merge meant a busy day of restarts (four in fourteen minutes on
+// 2026-09-29). But a restart only refreshes code THIS process holds in memory:
+// every worker, and every claim.js / worktree.js / release.js the loop shells
+// out to, is a fresh process that runs whatever is on disk. So on drift the
+// checkout is updated in place, and the process exits for the wrapper only when
+// a change touches code it has actually loaded.
+//
+// SUPERVISOR_PATH_RES catch the supervisor's own files even before they are
+// required (autobongos-verify.js is loaded lazily on the first ship), so a change
+// to a file the loop is ABOUT to load cannot mix old callers with a new callee.
+const SUPERVISOR_PATH_RES = [/^scripts\/(?:gds|bongos)\/autobongos-[^/]+$/, /^modules\/autonomy\//];
+
+// The repo files this process has loaded, repo-relative with forward slashes.
+function loadedFiles() {
+  const root = REPO_ROOT + path.sep;
+  const nm = path.sep + 'node_modules' + path.sep;
+  return Object.keys(require.cache)
+    .filter((p) => p.startsWith(root) && !p.includes(nm))
+    .map((p) => path.relative(REPO_ROOT, p).split(path.sep).join('/'));
+}
+
+// The changed files that force a restart: ones this process holds, or ones under
+// the supervisor's own paths. Everything else is picked up by the next child.
+function supervisorTouched(changed = [], loaded = loadedFiles()) {
+  const held = new Set(loaded);
+  return changed.filter((f) => held.has(f) || SUPERVISOR_PATH_RES.some((re) => re.test(f)));
+}
+
+// refreshCheckout — the wrapper's fetch + reset, done from inside the process.
+//
+// THE MAIN CHECKOUT ONLY. It runs `git reset --hard`, and a linked worktree is a
+// claim somebody is building in; resetting one would destroy their work. The
+// check compares git-dir to git-common-dir, which are equal only in the main
+// checkout. Armed only by main() (`opts.refreshInPlace`), so a test driving
+// forever() can never reach it — in CI that reset would wipe the code under test.
+//
+// The diff is from the LOADED commit, not the last refresh, so a supervisor
+// change that landed several refreshes ago still forces the restart it needs.
+async function refreshCheckout(deps = {}) {
+  const runCmd = deps.run || run;
+  const git = (args) => runCmd('git', args, { cwd: REPO_ROOT });
+  try {
+    const [gd, cd] = await Promise.all([git(['rev-parse', '--git-dir']), git(['rev-parse', '--git-common-dir'])]);
+    if (!gd.ok || !cd.ok) return { ok: false, reason: 'could not tell which checkout this is' };
+    if (path.resolve(REPO_ROOT, String(gd.stdout).trim()) !== path.resolve(REPO_ROOT, String(cd.stdout).trim())) {
+      return { ok: false, reason: 'not the main checkout — refusing to reset a linked worktree' };
+    }
+    const loaded = deps.loadedHead ? await deps.loadedHead(deps) : await loadedHead(deps);
+    if (!loaded) return { ok: false, reason: 'the running commit is unknown' };
+    if (!(await git(['fetch', '--quiet', 'origin', 'main'])).ok) return { ok: false, reason: 'fetch failed' };
+    const fh = await git(['rev-parse', 'FETCH_HEAD']);
+    const to = fh.ok ? String(fh.stdout).trim() : '';
+    if (!/^[0-9a-f]{40}$/.test(to)) return { ok: false, reason: 'could not read the fetched commit' };
+    const diff = await git(['diff', '--name-only', loaded, to]);
+    if (!diff.ok) return { ok: false, reason: 'could not diff the running commit against main' };
+    if (!(await git(['reset', '--quiet', '--hard', to])).ok) return { ok: false, reason: 'reset failed' };
+    const changed = String(diff.stdout).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    return { ok: true, to, changed };
+  } catch (e) {
+    return { ok: false, reason: e && e.message ? e.message : String(e) };
+  }
+}
+
+// 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.
+  // How long this runner has been idle on a setting the owner can fix (task
+  // 1004539). Past that setting's grace, every beat that is not about a task says
+  // `config_idle:<code>` instead of "waiting", so the hall shows the fix rather
+  // than "alive" for ten hours. Any row that is not that refusal ends the stretch.
+  let idle = null;
+  const clock = () => (deps.now ? deps.now() : Date.now());
+  const beat = async (rawFields) => {
+    const fields = configIdle.markBeat(rawFields, idle, clock());
+    // The runner state is passed, not defaulted: the file names `disk_head` from
+    // it (task 1004406), and an injected state must reach the beat that reports it.
+    try { beatFile(Date.now(), deps.state || RUNNER_STATE); } 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 */ }
+  };
+  // The running commit, read ONCE, BEFORE the first beat (task 1004397). It used
+  // to be read lazily by codeDrifted(), which sits behind the one-minute uptime
+  // floor, so every beat in a process's first minute said head:null — the window
+  // in which a crash-looping or repeatedly-restarted runner is being looked at.
+  // The floor exists to stop a restart STORM, not to avoid this read: one local
+  // rev-parse. Fails soft to null inside loadedHead(), and a null is retried by
+  // the drift check later, so an unreadable head never stops the runner.
+  try { await (deps.loadedHead ? deps.loadedHead(deps) : loadedHead(deps)); } catch (_) { /* head stays null */ }
+  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' });
+    // Slow lands (task 1004538): re-probe shipped tasks still waiting on main, and
+    // close no-artifact blockers whose commit has since landed. Armed only by
+    // main() (or an injected stub), like refreshInPlace, so no test harness that
+    // predates it can fall through to the network. It can never stop the loop.
+    if (opts.recheckLands || deps.recheckLands) {
+      try { await (deps.recheckLands || recheckPendingLands)(deps); } catch (e) {
+        log({ event: 'land_recheck_failed', errors: [e && e.message ? e.message : String(e)] });
+      }
+    }
+    // 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);
+      idle = configIdle.trackIdle(idle, row, clock());
+      // 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, working_goal_id: Number(row.goal_id) || undefined });
+      const seen = cadence.classifyEvent(row);
+      // A hold that names its reset SECOND waits until that second (task 1004454).
+      // classifyEvent carries it as an absolute epoch; the cadence has no clock of
+      // its own, so the conversion to a wait lives here beside the one clock read.
+      // Without it every hold waited the fixed idle and the "wake at the reset"
+      // the goal asks for was only ever as accurate as the poll.
+      if (Number.isFinite(Number(seen.sleepUntil)) && seen.sleepUntil !== null) {
+        const nowS = Math.floor((deps.now ? deps.now() : Date.now()) / 1000);
+        seen.sleepUntilS = Math.max(0, Number(seen.sleepUntil) - nowS);
+      }
+      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;
+    }
+
+    // AFTER the burst, never during one: a worker mid-task must not be abandoned
+    // to pick up a fix. Before the wait, because waiting is where the runner
+    // spends nearly all of its time and an upgrade should not sit behind it.
+    const upMs = (deps.now ? deps.now() : Date.now()) - Date.parse(RUNNER_STARTED_AT);
+    const mayUpgrade = upMs >= MIN_UPTIME_BEFORE_UPGRADE_MS;
+    let drift = mayUpgrade
+      ? (deps.codeDrifted ? await deps.codeDrifted(deps) : await codeDrifted(deps))
+      : false;
+    if (drift) {
+      // Pull always, restart rarely (task 1004406). Only main() arms the refresh.
+      let why = 'exiting so the wrapper can relaunch on the new code';
+      if (opts.refreshInPlace) {
+        const refreshed = await (deps.refreshCheckout || refreshCheckout)(deps);
+        if (refreshed && refreshed.ok) {
+          const touched = supervisorTouched(refreshed.changed, deps.loadedFiles ? deps.loadedFiles() : loadedFiles());
+          if (!touched.length) {
+            (deps.state || RUNNER_STATE).diskHead = refreshed.to;
+            log({ event: 'code_refreshed', from: drift.from, to: refreshed.to.slice(0, 8), changed: refreshed.changed.length,
+              reason: `main moved from ${drift.from} to ${refreshed.to.slice(0, 8)} — checkout updated in place; none of the ${refreshed.changed.length} changed file(s) is code this process runs, so no restart` });
+            await beat({ mode: state.mode, last_event: 'code_refreshed' });
+            drift = null;
+          } else {
+            const more = touched.length > 5 ? `, +${touched.length - 5} more` : '';
+            why = `it changed code this process runs (${touched.slice(0, 5).join(', ')}${more}) — exiting so the wrapper can relaunch on it`;
+          }
+        } else {
+          why = `the in-place refresh did not run (${(refreshed && refreshed.reason) || 'no result'}) — exiting so the wrapper's own refresh can`;
+        }
+      }
+      if (drift) {
+        log({ event: 'upgrade_exit', from: drift.from, to: drift.to, reason: `main moved from ${drift.from} to ${drift.to} — ${why}` });
+        await beat({ mode: state.mode, last_event: 'upgrade_exit' });
+        return UPGRADE_EXIT_CODE;
+      }
+    }
+
+    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, refreshInPlace: true, recheckLands: true });
+
+  // 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}` : ''}`);
+    if (row.event !== 'worked') break;
+  }
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((c) => process.exit(c)).catch((e) => {
+    console.error(`autobongos-run: ${e && e.message ? e.message : e}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  readArgv, pickTask, iteration, record, logPath, spawnWorker, workerEnv, WORKER_ENV_ALLOW, resolveWorkerBin,
+  worktreeName, readFence, gradeLedgerPath, gradeCapReader, reconcileLeftoverClaims, pollSignals, waitOrJump, forever, CLAIM_PREFIX, codeDrifted, loadedHead, UPGRADE_EXIT_CODE, MIN_UPTIME_BEFORE_UPGRADE_MS,
+  heartbeatPath, writeHeartbeat, readHeartbeat, pidAlive, anotherRunnerIsAlive, HEARTBEAT_STALE_MS,
+  isRunnerTree, RUNNER_TREE_RE, postHeartbeat, claudeAccountLabel, RUNNER_STARTED_AT, failureReason,
+  newRunnerState, loadedFiles, supervisorTouched, refreshCheckout, LIMIT_UNKNOWN_RESET_MS, QUEUE_GATED_EXIT, CLAIM_SET_ASIDE_MS, MAX_CLAIM_ATTEMPTS, owedTaskIds,
+  readRunLogRows, recheckPendingLands, LAND_SWEEP_MS,
+};