@bongos/core 1.24.76 → 1.24.78

package/scripts/bongos/autobongos-host.js

@@ -0,0 +1,883 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/autobongos-host.js — the Autobongos runner ON THIS DEVICE: set it
+// up, keep it running, stop it honestly (task 1005095, goal 1000139, ADR 0307 §5).
+//
+//   node scripts/bongos/autobongos-host.js setup --code abr_… --api-base https://…
+//   node scripts/bongos/autobongos-host.js status [--json]
+//   node scripts/bongos/autobongos-host.js start | stop
+//   node scripts/bongos/autobongos-host.js install | uninstall
+//   node scripts/bongos/autobongos-host.js digest [--since 24h]   # the night, in five answers
+//   node scripts/bongos/autobongos-host.js run          # what the start entry runs
+//
+// WHY. The runner could only be hosted one way: a Windows scheduled task
+// registered from an Administrator shell (autobongos-service.ps1 + .cmd), written
+// for one always-on PC. Owner direction 2026-11-09: it must run on ANY device —
+// Windows or Mac, always-on or a laptop — from one button. So this is one Node
+// program for both platforms, and nothing in it needs an administrator:
+//
+//   · It starts when the person SIGNS IN to the device (Windows: a per-user Run
+//     entry; Mac: a per-user launchd agent). A laptop that sleeps simply stops
+//     checking in and picks up again when it wakes; the hall says so.
+//   · `run` is the outer ring the .cmd used to be: bring the runner's own copy of
+//     the project current, launch the supervisor (autobongos-run.js --forever),
+//     relaunch it on its upgrade exit (75) or after a crash, with a growing wait.
+//   · The runner has ITS OWN login and files (BONGOS_CONFIG_ROOT), apart from the
+//     builder's CLI session on the same device, so adding a laptop as a runner
+//     never signs the builder's own tools out.
+//   · `stop` and `uninstall` WATCH the processes exit before saying so. The
+//     Windows stop once printed "stopped" over a live runner (task 1004375).
+//   · While the runner is allowed to work the device is kept from idle-sleeping,
+//     and released the moment the fence stops it.
+//
+// THE ONE THING IT REFUSES. `run` hard-resets its checkout to origin/main, so it
+// only ever does that in a copy marked as the runner's own (`setup
+// --mark-runner-copy`, which the bootstrap passes right after it clones). Run from
+// a builder's working copy it stops with a sentence instead of eating their work.
+//
+// The boot-time scheduled task (autobongos-service.ps1) stays for an always-on PC
+// that must come back with nobody signed in; it needs an elevated shell once.
+
+const { spawn, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+// The one shared sleep and the one shared escaper (tasks 1004893, 1004876).
+const { sleep: sharedSleep } = require('../../src/sleep');
+const { escapeHtml } = require('../../src/html-escape');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const LABEL = 'com.cloudbongos.autobongos';      // the launchd agent
+const RUN_VALUE = 'Autobongos';                  // the Windows Run entry
+const RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
+const RUNNER_COPY_MARK = 'autobongos-runner-copy';
+// The supervisor's one deliberate exit (autobongos-run.js UPGRADE_EXIT_CODE).
+// Pinned against it in tests/autobongos_host.mjs rather than required from it:
+// that file loads the whole CLI, and this loop must be able to start without it.
+const UPGRADE_EXIT_CODE = 75;
+const MIN_BACKOFF_S = 5;
+const MAX_BACKOFF_S = 300;
+const HEALTHY_RUN_MS = 10 * 60 * 1000;   // a run this long resets the crash backoff
+const LOCK_BEAT_MS = 30 * 1000;
+const LOCK_STALE_MS = 2 * 60 * 1000;
+const STOP_WAIT_MS = 20 * 1000;
+const LOG_ROTATE_BYTES = 20 * 1024 * 1024;
+
+// ── where the runner's own files live ──────────────────────────────────────
+
+// The runner's folder. AUTOBONGOS_HOME wins; otherwise a marked runner copy that
+// sits at <folder>/repo (where both bootstraps put it) IS inside its folder, so
+// the start entry needs no environment of its own to find the right files; and
+// only then the default.
+function runnerHome(env = process.env, home = os.homedir(), repoRoot = REPO_ROOT) {
+  if (env.AUTOBONGOS_HOME) return path.resolve(env.AUTOBONGOS_HOME);
+  if (path.basename(repoRoot) === 'repo' && isRunnerCopy(repoRoot)) return path.dirname(repoRoot);
+  return path.join(home, '.cloudbongos-runner');
+}
+
+// hostPaths — every file this program owns, from one root. `config` is handed to
+// the supervisor as BONGOS_CONFIG_ROOT, which is what keeps its login apart.
+function hostPaths(env = process.env, home = os.homedir()) {
+  const root = runnerHome(env, home);
+  return {
+    root,
+    configRoot: path.join(root, 'config'),
+    logDir: path.join(root, 'logs'),
+    log: path.join(root, 'logs', 'autobongos.log'),
+    lock: path.join(root, 'host.json'),
+    depsStamp: path.join(root, 'deps.sha'),
+    plist: path.join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`),
+  };
+}
+
+// The env the supervisor and its workers run under. The gauge file is pinned to
+// where a statusLine on this device would write it (the builder's own config
+// dir), so a device that does have a reading still uses it.
+function supervisorEnv(env = process.env, paths = hostPaths(env), configDirName = 'cloudbongos') {
+  const gauge = env.AUTOBONGOS_GAUGE_FILE
+    || path.join(os.homedir(), '.config', configDirName, 'autobongos-gauge.json');
+  return { ...env, BONGOS_CONFIG_ROOT: paths.configRoot, AUTOBONGOS_GAUGE_FILE: gauge };
+}
+
+// ── plain-language stops ───────────────────────────────────────────────────
+//
+// Every failure a person can do something about is a Stop: what happened, and
+// what to do, in words. main() prints those two lines and nothing else — never a
+// stack or raw tool output.
+class Stop extends Error {
+  constructor(what, fix) { super(what); this.name = 'Stop'; this.fix = fix || null; }
+}
+
+// ── the runner's own copy ──────────────────────────────────────────────────
+
+function runnerCopyMarkPath(repoRoot = REPO_ROOT) { return path.join(repoRoot, '.git', RUNNER_COPY_MARK); }
+
+// A linked worktree has a .git FILE, so the mark can only exist in a real clone.
+function isRunnerCopy(repoRoot = REPO_ROOT) {
+  try { return fs.statSync(runnerCopyMarkPath(repoRoot)).isFile(); } catch (_) { return false; }
+}
+
+function assertRunnerCopy(repoRoot = REPO_ROOT) {
+  if (isRunnerCopy(repoRoot)) return;
+  throw new Stop(
+    `${repoRoot} is not the runner's own copy of the project.`,
+    'The runner resets its copy to the latest code every time it starts, so it never runs in a working copy. Use the setup command from Settings → Your Autobongos runner; it makes the runner its own copy.',
+  );
+}
+
+// ── the lock: one outer loop per device ────────────────────────────────────
+
+function readJson(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; } }
+
+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'; }
+}
+
+// Is another outer loop running? A fresh beat AND a live pid AND not us — a pid
+// alone can be a number the system has since handed to something else.
+function lockHolder(lock, { now = Date.now(), alive = pidAlive, self = process.pid, takeover = null } = {}) {
+  if (!lock || !Number.isInteger(lock.pid)) return null;
+  if (lock.pid === self || lock.pid === takeover) return null;
+  if (!Number.isFinite(Number(lock.at)) || now - Number(lock.at) > LOCK_STALE_MS) return null;
+  return alive(lock.pid) ? lock.pid : null;
+}
+
+function writeLock(paths, fields = {}, now = Date.now()) {
+  try {
+    fs.mkdirSync(paths.root, { recursive: true });
+    fs.writeFileSync(paths.lock, JSON.stringify({ pid: process.pid, at: now, repo: REPO_ROOT, ...fields }));
+    return true;
+  } catch (_) { return false; }
+}
+
+// ── keep the device awake while the runner may work ────────────────────────
+
+// wantsAwake — from the supervisor's own rows. `fenced` means it is not allowed
+// to work (the switch is off, the owner paused it, no goals), and a device held
+// awake for a runner that is stopped is a laptop that never sleeps for nothing.
+// Anything else — working, waiting for work, resting until a usage reset — is a
+// runner the person pressed Run on, so the device stays up.
+function wantsAwake(event, prev = false) {
+  if (event === 'fenced') return false;
+  if (!event || event === 'boot_reconcile') return prev;
+  return true;
+}
+
+// The command that holds the device awake for as long as `pid` lives, or null
+// where there is none. Mac ships caffeinate; Windows needs the one kernel call.
+function keepAwakeCommand(platform = process.platform, pid = process.pid) {
+  if (platform === 'darwin') return { cmd: 'caffeinate', args: ['-i', '-w', String(pid)] };
+  if (platform === 'win32') {
+    // ES_CONTINUOUS | ES_SYSTEM_REQUIRED: no idle sleep; the screen may still turn off.
+    const ps = [
+      "$sig = '[DllImport(\"kernel32.dll\")] public static extern uint SetThreadExecutionState(uint f);'",
+      '$k = Add-Type -MemberDefinition $sig -Name AutobongosAwake -Namespace Win32 -PassThru',
+      '[void]$k::SetThreadExecutionState(2147483649)',
+      `try { Wait-Process -Id ${Number(pid)} -ErrorAction Stop } catch {}`,
+    ].join('; ');
+    return { cmd: 'powershell.exe', args: ['-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-Command', ps] };
+  }
+  return null;
+}
+
+function makeKeepAwake({ platform = process.platform, env = process.env, spawnFn = spawn, pid = process.pid } = {}) {
+  let child = null;
+  const off = String(env.AUTOBONGOS_KEEP_AWAKE || '') === '0';
+  return {
+    get on() { return !!child; },
+    set(want) {
+      if (off) return;
+      if (want && !child) {
+        const c = keepAwakeCommand(platform, pid);
+        if (!c) return;
+        try {
+          child = spawnFn(c.cmd, c.args, { stdio: 'ignore', windowsHide: true });
+          child.on('error', () => { child = null; });
+          child.on('exit', () => { child = null; });
+        } catch (_) { child = null; }
+      } else if (!want && child) {
+        try { child.kill(); } catch (_) { /* already gone */ }
+        child = null;
+      }
+    },
+  };
+}
+
+// ── the outer loop ─────────────────────────────────────────────────────────
+
+// runLoop — refresh, launch the supervisor, and decide what its exit means.
+//
+// Holds no I/O of its own: every effect is in `deps`, so the three behaviours
+// that matter are testable without a process — an upgrade exit relaunches at
+// once, any other exit relaunches after a wait that grows (and resets after a
+// healthy run), and a stop request ends it. Returns 'stopped', 'relaunch_self'
+// (this file changed under it; the caller starts a fresh copy), or the last exit
+// code when `maxCycles` bounds it for a test.
+async function runLoop(opts = {}, deps = {}) {
+  const log = deps.log || (() => {});
+  const now = deps.now || Date.now;
+  let backoffS = MIN_BACKOFF_S;
+  let cycles = 0;
+  for (;;) {
+    if (deps.shouldStop && deps.shouldStop()) return 'stopped';
+    // Best effort, both: a fetch that fails must not stop the runner starting on
+    // the code it has. Being a commit behind beats not running at all.
+    try { await deps.refresh(); } catch (e) { log(`refresh failed: ${e && e.message ? e.message : e}`); }
+    try { await deps.ensureDeps(); } catch (e) { log(`dependency install failed: ${e && e.message ? e.message : e}`); }
+    log('==== autobongos starting ====');
+    const started = now();
+    let code = 1;
+    try { code = await deps.spawnSupervisor(); } catch (e) { log(`could not start the supervisor: ${e && e.message ? e.message : e}`); }
+    cycles += 1;
+    if (deps.shouldStop && deps.shouldStop()) return 'stopped';
+    if (code === UPGRADE_EXIT_CODE) {
+      log('==== autobongos relaunching for an upgrade ====');
+      if (deps.selfChanged && deps.selfChanged()) return 'relaunch_self';
+      backoffS = MIN_BACKOFF_S;
+    } else {
+      if (now() - started >= HEALTHY_RUN_MS) backoffS = MIN_BACKOFF_S;
+      log(`==== autobongos exited ${code}; starting again in ${backoffS}s ====`);
+      if (opts.maxCycles && cycles >= opts.maxCycles) return code;
+      await deps.sleep(backoffS * 1000);
+      backoffS = Math.min(backoffS * 2, MAX_BACKOFF_S);
+      continue;
+    }
+    if (opts.maxCycles && cycles >= opts.maxCycles) return code;
+  }
+}
+
+function makeLogger(paths, { echo = false } = {}) {
+  return (line) => {
+    const text = `${new Date().toISOString()} ${line}\n`;
+    try {
+      fs.mkdirSync(paths.logDir, { recursive: true });
+      fs.appendFileSync(paths.log, text);
+    } catch (_) { /* a runner that cannot log still runs */ }
+    if (echo) process.stdout.write(text);
+  };
+}
+
+function rotateLog(paths) {
+  try {
+    if (fs.statSync(paths.log).size > LOG_ROTATE_BYTES) fs.renameSync(paths.log, `${paths.log}.1`);
+  } catch (_) { /* no log yet */ }
+}
+
+function git(args, opts = {}) {
+  return spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8', windowsHide: true, ...opts });
+}
+
+// refreshCheckout — the .cmd's fetch + reset, on the runner's own copy only.
+function refreshCheckout(log = () => {}) {
+  assertRunnerCopy();
+  const f = git(['fetch', '--quiet', 'origin', 'main']);
+  if (f.status !== 0) { log(`git fetch failed — running the code already here (${String(f.stderr || '').trim().slice(0, 200)})`); return false; }
+  const r = git(['reset', '--quiet', '--hard', 'origin/main']);
+  if (r.status !== 0) { log(`git reset failed (${String(r.stderr || '').trim().slice(0, 200)})`); return false; }
+  return true;
+}
+
+function fileSha(p) {
+  try { return crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex'); } catch (_) { return null; }
+}
+
+// ensureDeps — `npm ci` when the lockfile is not the one last installed. The
+// runner's copy moves with main, and a supervisor started against yesterday's
+// node_modules fails in ways that look like anything but a missing package.
+function ensureDeps(paths, log = () => {}, { stdio = 'ignore' } = {}) {
+  const want = fileSha(path.join(REPO_ROOT, 'package-lock.json'));
+  const have = (() => { try { return fs.readFileSync(paths.depsStamp, 'utf8').trim(); } catch (_) { return null; } })();
+  if (want && want === have && fs.existsSync(path.join(REPO_ROOT, 'node_modules'))) return { installed: false };
+  log('installing dependencies (npm ci)');
+  // One fixed command line through the shell, because npm is a .cmd on Windows.
+  const r = spawnSync('npm ci --no-audit --no-fund', { cwd: REPO_ROOT, stdio, shell: true, windowsHide: true });
+  if (r.status !== 0) throw new Error(`npm ci exited ${r.status}`);
+  if (want) { fs.mkdirSync(paths.root, { recursive: true }); fs.writeFileSync(paths.depsStamp, want); }
+  return { installed: true };
+}
+
+// Kill a process and everything under it. The supervisor's workers are sessions
+// with children of their own, and a worker left behind keeps building against a
+// claim nothing is watching.
+function killTree(pid, { platform = process.platform, force = false } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  if (platform === 'win32') {
+    // Always /F, whatever `force` says. Without it taskkill posts a close message
+    // to a window, and this tree has none (it runs under a headless console), so
+    // the polite form ends nothing and only spends the wait before the forced one.
+    spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+    return;
+  }
+  const sig = force ? 'SIGKILL' : 'SIGTERM';
+  // A detached child leads its own process group, so the negative pid reaches
+  // the whole tree; fall back to the one process when it does not.
+  try { process.kill(-pid, sig); } catch (_) { try { process.kill(pid, sig); } catch (__) { /* gone */ } }
+}
+
+// spawnSupervisor — one supervisor run. Its output goes to the log; its rows
+// (--json prints one per iteration) decide whether the device is held awake.
+function spawnSupervisorReal({ paths, env, log, keepAwake, state }) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [path.join(REPO_ROOT, 'scripts', 'bongos', 'autobongos-run.js'), '--forever', '--json'], {
+      cwd: REPO_ROOT, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
+      detached: process.platform !== 'win32',
+    });
+    state.child = child;
+    let awake = false;
+    let buf = '';
+    const out = (d) => {
+      try { fs.appendFileSync(paths.log, d); } catch (_) { /* keep running */ }
+      buf += String(d);
+      let nl;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        if (!line.startsWith('{')) continue;
+        let row = null;
+        try { row = JSON.parse(line); } catch (_) { row = null; }
+        if (row && typeof row.event === 'string') {
+          const next = wantsAwake(row.event, awake);
+          if (next !== awake) { awake = next; keepAwake.set(awake); }
+        }
+      }
+      if (buf.length > 1024 * 1024) buf = '';
+    };
+    child.stdout.on('data', out);
+    child.stderr.on('data', (d) => { try { fs.appendFileSync(paths.log, d); } catch (_) { /* keep running */ } });
+    child.on('error', (e) => { state.child = null; keepAwake.set(false); log(`supervisor error: ${e.message}`); resolve(1); });
+    child.on('close', (code, signal) => { state.child = null; keepAwake.set(false); resolve(code === null ? (signal ? 1 : 0) : code); });
+  });
+}
+
+// The boot-time scheduled task autobongos-service.ps1 registers. Two runners on
+// one device share a host name, so each would overwrite the other's check-in and
+// reconcile the other's claims away.
+function legacyBootTaskInstalled(platform = process.platform, run = spawnSync) {
+  if (platform !== 'win32') return false;
+  return run('schtasks', ['/Query', '/TN', 'Autobongos'], { stdio: 'ignore', windowsHide: true }).status === 0;
+}
+
+// ── starting it, now and at sign-in ────────────────────────────────────────
+
+function conhostPath(env = process.env) {
+  return path.join(env.SystemRoot || env.windir || 'C:\\Windows', 'System32', 'conhost.exe');
+}
+
+// The argv that runs `run` with no console window on Windows. A detached node has
+// NO console, so every git and claude it starts would open one of its own;
+// conhost's headless mode gives the whole tree one invisible console instead.
+function windowsRunArgv({ node = process.execPath, script = __filename, conhost = conhostPath(), hasConhost = fs.existsSync(conhost) } = {}) {
+  return hasConhost ? [conhost, '--headless', node, script, 'run'] : [node, script, 'run'];
+}
+
+// One command line, each part quoted, for the Run entry.
+function windowsRunCommand(argv = windowsRunArgv()) {
+  return argv.map((a) => (/^[A-Za-z0-9_\-./\\:]+$/.test(a) ? a : `"${a}"`)).join(' ');
+}
+
+// windowsStartSpawn — how THIS program launches that argv so it outlives it.
+//
+// FOUND BY RUNNING IT. Spawning conhost straight from node starts nothing: node
+// always hands a child its standard handles, and a headless conhost given handles
+// treats them as its terminal, finds they are not one, and exits 0 having run
+// nothing — no error anywhere. `start` creates the process the way the sign-in
+// entry does, with no handles to inherit, and that runs. Without conhost the plain
+// node argv is started the same way.
+function windowsStartSpawn(argv = windowsRunArgv()) {
+  return {
+    cmd: 'cmd.exe',
+    args: ['/d', '/s', '/c', `"start "" ${argv.map((a) => `"${a}"`).join(' ')}"`],
+    options: { detached: true, stdio: 'ignore', windowsHide: true, windowsVerbatimArguments: true },
+  };
+}
+
+// A plist is XML, and the five characters XML needs escaped are the ones HTML does.
+const xml = escapeHtml;
+
+// launchdPlist — the Mac start entry. A LaunchAgent (the person's own session),
+// not a LaunchDaemon: the runner needs their Claude sign-in and git credential,
+// both of which live in the login keychain. PATH is captured at install time
+// because launchd starts agents with a bare one and node, git and claude are
+// wherever this person's shell found them.
+function launchdPlist({ node = process.execPath, script = __filename, cwd = REPO_ROOT, paths = hostPaths(), envPath = process.env.PATH || '', home = os.homedir() } = {}) {
+  const env = { PATH: envPath, HOME: home, AUTOBONGOS_SUPERVISOR: 'launchd' };
+  if (process.env.AUTOBONGOS_HOME) env.AUTOBONGOS_HOME = paths.root;
+  const dict = Object.entries(env).map(([k, v]) => `      <key>${xml(k)}</key><string>${xml(v)}</string>`).join('\n');
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '  <dict>',
+    `    <key>Label</key><string>${LABEL}</string>`,
+    '    <key>ProgramArguments</key>',
+    '    <array>',
+    ...[node, script, 'run'].map((a) => `      <string>${xml(a)}</string>`),
+    '    </array>',
+    `    <key>WorkingDirectory</key><string>${xml(cwd)}</string>`,
+    '    <key>EnvironmentVariables</key>',
+    '    <dict>',
+    dict,
+    '    </dict>',
+    '    <key>RunAtLoad</key><true/>',
+    // Restarted whenever it exits: the outer loop only returns to hand over to a
+    // newer copy of itself, or because something killed it.
+    '    <key>KeepAlive</key><true/>',
+    `    <key>StandardOutPath</key><string>${xml(path.join(paths.logDir, 'launchd.log'))}</string>`,
+    `    <key>StandardErrorPath</key><string>${xml(path.join(paths.logDir, 'launchd.log'))}</string>`,
+    '  </dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+function launchctl(args) { return spawnSync('launchctl', args, { encoding: 'utf8' }); }
+const guiDomain = () => `gui/${typeof process.getuid === 'function' ? process.getuid() : 0}`;
+
+function installedState(platform = process.platform, paths = hostPaths(), run = spawnSync) {
+  if (platform === 'win32') {
+    const r = run('reg', ['query', RUN_KEY, '/v', RUN_VALUE], { encoding: 'utf8', windowsHide: true });
+    return r.status === 0;
+  }
+  if (platform === 'darwin') return fs.existsSync(paths.plist);
+  return false;
+}
+
+// install — register the start-at-sign-in entry. No administrator on either
+// platform: both entries belong to this person's own account.
+function install({ platform = process.platform, paths = hostPaths(), run = spawnSync, repoRoot = REPO_ROOT } = {}) {
+  assertRunnerCopy(repoRoot);
+  fs.mkdirSync(paths.logDir, { recursive: true });
+  if (platform === 'win32') {
+    const r = run('reg', ['add', RUN_KEY, '/v', RUN_VALUE, '/t', 'REG_SZ', '/d', windowsRunCommand(), '/f'], { encoding: 'utf8', windowsHide: true });
+    if (r.status !== 0 || !installedState(platform, paths, run)) {
+      throw new Stop('Windows would not save the start-at-sign-in entry.', 'Run the setup command again from an ordinary (not Administrator) PowerShell window signed in as you.');
+    }
+    return { kind: 'windows-run-entry' };
+  }
+  if (platform === 'darwin') {
+    fs.mkdirSync(path.dirname(paths.plist), { recursive: true });
+    fs.writeFileSync(paths.plist, launchdPlist({ paths }));
+    return { kind: 'launchd-agent' };
+  }
+  return { kind: 'none' };
+}
+
+// removeStartEntry — take the start-at-sign-in entry away, and LOOK afterwards.
+// Returns true only when the entry is really gone, so uninstall can say "could
+// not remove it" instead of promising a device that will not start again.
+function removeStartEntry({ platform = process.platform, paths = hostPaths(), run = spawnSync } = {}) {
+  if (platform === 'win32') run('reg', ['delete', RUN_KEY, '/v', RUN_VALUE, '/f'], { stdio: 'ignore', windowsHide: true });
+  if (platform === 'darwin') { try { fs.rmSync(paths.plist, { force: true }); } catch (_) { /* gone */ } }
+  return !installedState(platform, paths, run);
+}
+
+// startDetached — launch the outer loop so it outlives this command.
+function startDetached({ platform = process.platform, paths = hostPaths(), takeover = null } = {}) {
+  const env = { ...process.env, ...(takeover ? { AUTOBONGOS_TAKEOVER: String(takeover) } : {}) };
+  if (platform === 'darwin' && fs.existsSync(paths.plist) && !takeover) {
+    // Loaded into the person's session, so launchd restarts it if it dies.
+    launchctl(['bootout', `${guiDomain()}/${LABEL}`]);
+    const r = launchctl(['bootstrap', guiDomain(), paths.plist]);
+    if (r.status === 0) return { via: 'launchd' };
+  }
+  if (platform === 'win32') {
+    const { cmd, args, options } = windowsStartSpawn();
+    spawn(cmd, args, { cwd: REPO_ROOT, env, ...options }).unref();
+    return { via: 'start' };
+  }
+  const child = spawn(process.execPath, [__filename, 'run'], { cwd: REPO_ROOT, env, detached: true, stdio: 'ignore' });
+  child.unref();
+  return { via: 'spawn', pid: child.pid };
+}
+
+// ── stop, and say what actually happened ───────────────────────────────────
+
+function supervisorHeartbeatFile(paths = hostPaths(), configDirName = 'cloudbongos') {
+  return path.join(paths.configRoot, configDirName, 'autobongos-heartbeat.json');
+}
+
+// stopRunner — ask everything to exit, WATCH it exit, and report one of:
+//   stopped        the processes were alive and were watched to exit
+//   still_running  at least one outlived the wait (the caller exits non-zero)
+//   not_running    nothing was running to begin with
+// It never says "stopped" about a process it has not seen gone (task 1004375).
+async function stopRunner({
+  platform = process.platform, paths = hostPaths(), configDirName = 'cloudbongos',
+  alive = pidAlive, kill = killTree, sleep = sharedSleep,
+  waitMs = STOP_WAIT_MS, unload = null,
+} = {}) {
+  const lock = readJson(paths.lock);
+  const hb = readJson(supervisorHeartbeatFile(paths, configDirName));
+  const pids = [...new Set([lock && lock.pid, hb && hb.pid].filter((p) => Number.isInteger(p) && p > 0 && p !== process.pid))];
+  // Unload first on a Mac, or launchd restarts the loop the moment it dies.
+  if (unload) unload();
+  else if (platform === 'darwin') launchctl(['bootout', `${guiDomain()}/${LABEL}`]);
+  const running = pids.filter((p) => alive(p));
+  if (!running.length) return { outcome: 'not_running', pids };
+  for (const p of running) kill(p, { platform, force: false });
+  const deadline = Date.now() + waitMs;
+  let forced = false;
+  while (running.some((p) => alive(p)) && Date.now() < deadline) {
+    await sleep(250);
+    if (!forced && Date.now() > deadline - waitMs / 2) {
+      forced = true;
+      for (const p of running) if (alive(p)) kill(p, { platform, force: true });
+    }
+  }
+  const left = running.filter((p) => alive(p));
+  if (!left.length) { try { fs.rmSync(paths.lock, { force: true }); } catch (_) { /* gone */ } }
+  return { outcome: left.length ? 'still_running' : 'stopped', pids: running, left };
+}
+
+function stopReport(result, { platform = process.platform, installed = false } = {}) {
+  if (result.outcome === 'stopped') {
+    return [
+      `Stopped. The runner's processes (${result.pids.join(', ')}) have exited — watched, not assumed.`,
+      installed
+        ? 'It starts again the next time you sign in to this device. To keep it from working, use Stop on its card in Settings, or run uninstall.'
+        : 'It will not start again by itself.',
+    ];
+  }
+  if (result.outcome === 'still_running') {
+    const how = platform === 'win32' ? `taskkill /F /T /PID ${result.left[0]}` : `kill -9 ${result.left.join(' ')}`;
+    return [
+      `NOT STOPPED: process ${result.left.join(', ')} is still running after ${Math.round(STOP_WAIT_MS / 1000)} seconds.`,
+      `End it yourself with:  ${how}   — or restart this device.`,
+    ];
+  }
+  return ['The runner was not running on this device.'];
+}
+
+// ── status ─────────────────────────────────────────────────────────────────
+
+// status — what this device can say about its own runner, from its own files:
+// is the loop running (a fresh lock held by a live process), does it start at
+// sign-in, and which login does it hold. Never the token, only whose it is.
+function status({ platform = process.platform, paths = hostPaths(), configDirName = 'cloudbongos', now = Date.now(), run = spawnSync, alive = pidAlive } = {}) {
+  const lock = readJson(paths.lock);
+  const holder = lockHolder(lock, { now, self: -1, alive });
+  const session = readJson(path.join(paths.configRoot, configDirName, 'bongos-session.json'))
+    || readJson(path.join(paths.configRoot, configDirName, 'gds-session.json'));
+  return {
+    device: os.hostname(),
+    runner_copy: isRunnerCopy(),
+    starts_at_sign_in: installedState(platform, paths, run),
+    running: !!holder,
+    pid: holder || null,
+    signed_in_as: session && session.builder ? session.builder.github_login || null : null,
+    project: session ? session.api_base || null : null,
+    log: paths.log,
+  };
+}
+
+// ── setup ──────────────────────────────────────────────────────────────────
+
+function arg(argv, name) {
+  const i = argv.indexOf(name);
+  if (i !== -1 && argv[i + 1] !== undefined) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : null;
+}
+
+// The project address the code is traded at. HTTPS only: the one-time code goes
+// out and the runner's login comes back on this request, and neither may cross a
+// network in the clear. Plain http is accepted for this machine alone (localhost,
+// 127.0.0.1, a .localhost or .test name), which is a developer's own instance.
+function cleanBase(raw) {
+  const s = String(raw || '').trim().replace(/\/+$/, '');
+  if (/^https:\/\/[^\s/]+$/i.test(s)) return s;
+  return /^http:\/\/(localhost|127\.0\.0\.1|\[::1\]|[a-z0-9.-]+\.(localhost|test))(:\d+)?$/i.test(s) ? s : null;
+}
+
+// exchangeCode — trade the one-time code for the runner's own login.
+async function exchangeCode({ apiBase, code, fetchImpl = fetch }) {
+  let res;
+  try {
+    res = await fetchImpl(`${apiBase}/api/bongos/auth/runner-code/exchange`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'User-Agent': `autobongos-host/${os.hostname().replace(/[^A-Za-z0-9._-]/g, '').slice(0, 64)}` },
+      body: JSON.stringify({ code }),
+    });
+  } catch (_) {
+    throw new Stop(`This device could not reach ${apiBase}.`, 'Check it is online, then run the setup command again.');
+  }
+  if (res.status === 401) {
+    throw new Stop('That setup code is wrong, already used, or older than 15 minutes.', 'Go back to Settings → Your Autobongos runner, press Add a device again, and paste the new command.');
+  }
+  if (!res.ok) {
+    throw new Stop(`The project would not accept the setup code (it answered ${res.status}).`, 'Wait a minute and run the setup command again. If it keeps happening, tell the project owner.');
+  }
+  const data = await res.json();
+  if (!data || !data.token) throw new Stop('The project answered without a login for this device.', 'Run the setup command again with a new code from Settings.');
+  return data;
+}
+
+// sessionStillGood — does the project still accept the login this device has?
+// Asked with that login itself. Only an explicit yes counts: a refusal, an error
+// and an unreachable project all read as "no", and the caller then needs a code.
+async function sessionStillGood(session, fetchImpl = fetch) {
+  if (!session || !session.token || !session.api_base) return false;
+  try {
+    const res = await fetchImpl(`${session.api_base}/api/bongos/me`, { headers: { Authorization: `Bearer ${session.token}` } });
+    return res.ok === true;
+  } catch (_) { return false; }
+}
+
+// signIn — which login this device ends setup with: the one it already has, or a
+// new one bought with the code. Returns { session, fresh }.
+//
+// THE SETUP COMMAND IS RUN MORE THAN ONCE, and its code only works once. So a
+// device that already holds a login the project still accepts KEEPS it and never
+// spends the code: the second run of the same pasted line then changes nothing,
+// instead of stopping on "that code is already used" (grade finding, round 1).
+// The code is only traded when there is no login, the login is for another
+// project, or the project has since refused it (the device was removed).
+async function signIn({ code, apiBase, session, fetchImpl = fetch, hostName = os.hostname() } = {}) {
+  const base = apiBase == null ? null : cleanBase(apiBase);
+  if (code && !base) {
+    throw new Stop('The project address in the setup command is missing or is not a secure (https) address.', 'Copy the whole command again from Settings → Your Autobongos runner.');
+  }
+  const sameProject = session && session.token && (!base || String(session.api_base || '').replace(/\/+$/, '') === base);
+  if (sameProject && await sessionStillGood(session, fetchImpl)) return { session, fresh: false };
+  if (!code) {
+    throw new Stop(
+      session && session.token ? 'The project no longer accepts this device’s login (it was removed, or signed out).' : 'This device has no runner login yet.',
+      'Open Settings → Your Autobongos runner in the hall, press Add a device, and run the command it shows.',
+    );
+  }
+  const out = await exchangeCode({ apiBase: base, code, fetchImpl });
+  return {
+    fresh: true,
+    session: { token: out.token, api_base: out.api_base || base, builder: { github_login: out.builder_login || null }, runner: { label: out.label || hostName, session_id: out.session_id || null } },
+  };
+}
+
+// Is Claude Code here and signed in? `claude auth status` answers in JSON on
+// current versions; an older one that does not know the command falls back to
+// the sign-in Claude Code records on disk.
+function claudeState({ resolveBin, claudeAccountLabel, run = spawnSync } = {}) {
+  const { bin, shell } = resolveBin();
+  const v = run(bin, ['--version'], { encoding: 'utf8', shell, windowsHide: true, timeout: 30000 });
+  if (v.error || v.status !== 0) return { installed: false, signedIn: false, bin, shell };
+  const a = run(bin, ['auth', 'status'], { encoding: 'utf8', shell, windowsHide: true, timeout: 30000 });
+  let signedIn = null;
+  try { const j = JSON.parse(String(a.stdout || '')); if (typeof j.loggedIn === 'boolean') signedIn = j.loggedIn; } catch (_) { signedIn = null; }
+  if (signedIn === null) signedIn = !!claudeAccountLabel();
+  return { installed: true, signedIn, bin, shell };
+}
+
+async function setup(argv, { paths = hostPaths(), say = console.log } = {}) {
+  if (argv.includes('--mark-runner-copy')) {
+    // Only the bootstrap passes this, right after it clones: it is the statement
+    // "this copy was made for the runner and nothing else lives in it".
+    if (!fs.statSync(path.join(REPO_ROOT, '.git')).isDirectory()) throw new Stop('This folder is a linked working tree, not a copy of its own.', 'Use the setup command from Settings; it makes the runner its own copy.');
+    fs.writeFileSync(runnerCopyMarkPath(), `marked ${new Date().toISOString()}\n`);
+  }
+  assertRunnerCopy();
+
+  const ic = require('../../src/instance-config');
+  const dirName = ic.configDirName();
+  process.env.BONGOS_CONFIG_ROOT = paths.configRoot;   // before anything reads a session
+  fs.mkdirSync(paths.configRoot, { recursive: true });
+
+  say('1/5  Installing the project’s tools (a few minutes the first time)…');
+  try { ensureDeps(paths, () => {}, { stdio: 'inherit' }); } catch (_) {
+    throw new Stop('The project’s tools would not install.', 'Check this device is online and has a few gigabytes free, then run the setup command again.');
+  }
+
+  say('2/5  Signing this device in to the project…');
+  const cli = require('./cli-lib');
+  const signed = await signIn({
+    code: arg(argv, '--code'), apiBase: arg(argv, '--api-base'),
+    session: await cli.loadSession().catch(() => null),
+  });
+  const session = signed.session;
+  if (signed.fresh) await cli.saveSession(session);
+  else say('     Already signed in on this device; keeping that login.');
+
+  say('3/5  Checking Claude Code…');
+  const runner = require('./autobongos-run.js');
+  let claude = claudeState({ resolveBin: runner.resolveWorkerBin, claudeAccountLabel: runner.claudeAccountLabel });
+  if (!claude.installed) throw new Stop('Claude Code is not installed on this device.', 'Install it from https://claude.com/claude-code, open a new terminal window, and run the setup command again.');
+  if (!claude.signedIn && process.stdin.isTTY) {
+    say('     Claude Code needs you to sign in. A sign-in page will open; come back here when it is done.');
+    spawnSync(claude.bin, ['auth', 'login'], { stdio: 'inherit', shell: claude.shell });
+    claude = claudeState({ resolveBin: runner.resolveWorkerBin, claudeAccountLabel: runner.claudeAccountLabel });
+  }
+  if (!claude.signedIn) throw new Stop('Claude Code is not signed in on this device.', 'Run  claude auth login  in a terminal, finish the sign-in, then run the setup command again.');
+
+  say('4/5  Checking this device can fetch the project’s code…');
+  if (git(['ls-remote', 'origin', 'refs/heads/main'], { timeout: 60000 }).status !== 0) {
+    throw new Stop('This device could not fetch the project’s code from GitHub.', 'Sign in to GitHub on this device (run  git fetch  in the runner’s folder and follow the sign-in), then run the setup command again.');
+  }
+
+  say('5/5  Starting the runner…');
+  if (legacyBootTaskInstalled()) {
+    throw new Stop(
+      'this PC already runs Autobongos as a scheduled task (the always-on install).',
+      'One runner per device. Keep that one, or remove it first from an Administrator PowerShell:  powershell -ExecutionPolicy Bypass -File scripts\\bongos\\autobongos-service.ps1 uninstall  — then run the setup command again.',
+    );
+  }
+  const entry = install({ paths });
+  const lock = readJson(paths.lock);
+  if (!lockHolder(lock) && !argv.includes('--no-start')) startDetached({ paths });
+
+  let seen = argv.includes('--no-start');
+  if (!seen) seen = await waitForCheckIn({ session, dirName });
+  say('');
+  if (seen) say(`Done. This device is connected as an Autobongos runner for ${session.builder && session.builder.github_login ? session.builder.github_login : 'your account'}.`);
+  else say(`The runner is started but has not checked in yet. Give it a minute; if its card does not appear, look at ${paths.log}`);
+  if (entry.kind === 'none') say('It runs until this device restarts. Run this again after a restart (this system has no start-at-sign-in entry yet).');
+  else say('It starts by itself whenever you sign in to this device.');
+  say('Keep this device on and plugged in while it runs. If it sleeps, the runner pauses and picks up when it wakes.');
+  say(`Next: open ${session.api_base}/builders/settings#autobongos — choose its goals and press Run.`);
+  return 0;
+}
+
+// Wait for the supervisor's first check-in to reach the server, asked with the
+// runner's own login. Ninety seconds: a boot is a fetch, a reset and one request.
+async function waitForCheckIn({ session, fetchImpl = fetch, timeoutMs = 90000, sleep = sharedSleep }) {
+  const host = os.hostname().toLowerCase();
+  const until = Date.now() + timeoutMs;
+  while (Date.now() < until) {
+    try {
+      const res = await fetchImpl(`${session.api_base}/api/bongos/autonomy/runners`, { headers: { Authorization: `Bearer ${session.token}` } });
+      if (res.ok) {
+        const rows = ((await res.json()) || {}).runners || [];
+        const mine = rows.find((r) => String(r.host || '').toLowerCase() === host);
+        if (mine && Date.now() - Date.parse(mine.last_seen_at || '') < 5 * 60 * 1000) return true;
+      }
+    } catch (_) { /* not yet */ }
+    await sleep(3000);
+  }
+  return false;
+}
+
+// The digest CLI and its arguments, for `digest`: the same file a builder would
+// run by hand, with whatever they passed handed through.
+function digestArgv(rest = []) {
+  return [path.join(REPO_ROOT, 'scripts', 'bongos', 'autobongos-digest.js'), ...rest];
+}
+
+// ── the commands ───────────────────────────────────────────────────────────
+
+async function runCommand({ paths = hostPaths() } = {}) {
+  assertRunnerCopy();
+  const takeover = Number(process.env.AUTOBONGOS_TAKEOVER) || null;
+  if (takeover) {
+    // Handed over by an older copy of this loop: wait for it to be gone.
+    for (let i = 0; i < 40 && pidAlive(takeover); i++) await sharedSleep(250);
+  }
+  if (lockHolder(readJson(paths.lock), { takeover })) return 0;   // already running: one loop per device
+  const ic = require('../../src/instance-config');
+  const dirName = ic.configDirName();
+  const log = makeLogger(paths, { echo: !!process.stdout.isTTY });
+  const env = supervisorEnv(process.env, paths, dirName);
+  const state = { child: null, stopping: false };
+  const keepAwake = makeKeepAwake();
+  const selfSha = fileSha(__filename);
+  writeLock(paths);
+  const beat = setInterval(() => writeLock(paths), LOCK_BEAT_MS);
+  const shutdown = () => {
+    state.stopping = true;
+    keepAwake.set(false);
+    if (state.child) killTree(state.child.pid, { force: false });
+  };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  rotateLog(paths);
+  const out = await runLoop({}, {
+    log, shouldStop: () => state.stopping,
+    refresh: () => refreshCheckout(log),
+    ensureDeps: () => ensureDeps(paths, log),
+    spawnSupervisor: () => spawnSupervisorReal({ paths, env, log, keepAwake, state }),
+    selfChanged: () => fileSha(__filename) !== selfSha,
+    sleep: sharedSleep,
+  });
+  clearInterval(beat);
+  keepAwake.set(false);
+  if (out === 'relaunch_self') {
+    log('==== this program changed; handing over to the new copy ====');
+    // Under launchd, exiting IS the hand-over: KeepAlive starts the new file.
+    if (process.env.AUTOBONGOS_SUPERVISOR !== 'launchd') startDetached({ paths, takeover: process.pid });
+  }
+  try { if ((readJson(paths.lock) || {}).pid === process.pid) fs.rmSync(paths.lock, { force: true }); } catch (_) { /* gone */ }
+  return 0;
+}
+
+async function main(argv) {
+  const cmd = argv[0] || 'status';
+  const paths = hostPaths();
+  if (cmd === 'setup') return setup(argv.slice(1), { paths });
+  if (cmd === 'run') return runCommand({ paths });
+  const dirName = (() => { try { return require('../../src/instance-config').configDirName(); } catch (_) { return 'cloudbongos'; } })();
+  if (cmd === 'status') {
+    const s = status({ paths, configDirName: dirName });
+    if (argv.includes('--json')) { console.log(JSON.stringify(s, null, 2)); return 0; }
+    console.log(`device            : ${s.device}`);
+    console.log(`signed in as      : ${s.signed_in_as || '(no runner login — run the setup command from Settings)'}`);
+    console.log(`running           : ${s.running ? `yes (process ${s.pid})` : 'no'}`);
+    console.log(`starts at sign-in : ${s.starts_at_sign_in ? 'yes' : 'no'}`);
+    console.log(`log               : ${s.log}`);
+    console.log('Whether it is WORKING is on its card in Settings: the card reads its check-ins.');
+    return 0;
+  }
+  if (cmd === 'digest') {
+    // The runner's run log lives under ITS config root, so the digest has to be
+    // run with that root or it reads the builder's own (empty) one and reports a
+    // missing log (task 1005097).
+    const r = spawnSync(process.execPath, digestArgv(argv.slice(1)), { stdio: 'inherit', env: supervisorEnv(process.env, paths, dirName) });
+    return r.status === null ? 1 : r.status;
+  }
+  if (cmd === 'install') {
+    const e = install({ paths });
+    console.log(e.kind === 'none' ? 'This system has no start-at-sign-in entry yet; use start after each restart.' : 'The runner now starts whenever you sign in to this device.');
+    return 0;
+  }
+  if (cmd === 'start') {
+    assertRunnerCopy();
+    if (lockHolder(readJson(paths.lock))) { console.log('The runner is already running on this device.'); return 0; }
+    startDetached({ paths });
+    console.log('Started. Its card in Settings shows it checking in within a minute.');
+    return 0;
+  }
+  if (cmd === 'stop' || cmd === 'uninstall') {
+    const result = await stopRunner({ paths, configDirName: dirName });
+    let installed = installedState(process.platform, paths);
+    if (cmd === 'uninstall') {
+      const gone = removeStartEntry({ paths });
+      installed = !gone;
+      console.log(gone ? 'Removed the start-at-sign-in entry.' : 'COULD NOT remove the start-at-sign-in entry — it will start again at sign-in.');
+    }
+    for (const line of stopReport(result, { installed })) console.log(line);
+    return result.outcome === 'still_running' || (cmd === 'uninstall' && installed) ? 1 : 0;
+  }
+  console.error('usage: autobongos-host.js setup --code <code> --api-base <url> | status [--json] | start | stop | install | uninstall | digest [--since 24h] | run');
+  return 2;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((c) => { process.exitCode = c; }).catch((e) => {
+    if (e && e.name === 'Stop') {
+      console.error(`\nAutobongos stopped here: ${e.message}`);
+      if (e.fix) console.error(`What to do: ${e.fix}`);
+    } else {
+      console.error(`\nAutobongos stopped on something unexpected: ${e && e.message ? e.message : e}`);
+      console.error('What to do: run the same command again. If it stops here twice, send this line to the project owner.');
+    }
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  LABEL, UPGRADE_EXIT_CODE, HEALTHY_RUN_MS, LOCK_STALE_MS,
+  hostPaths, supervisorEnv, isRunnerCopy, assertRunnerCopy, runnerCopyMarkPath,
+  pidAlive, lockHolder, wantsAwake, keepAwakeCommand, makeKeepAwake, runLoop,
+  windowsRunArgv, windowsRunCommand, windowsStartSpawn, legacyBootTaskInstalled, launchdPlist,
+  stopRunner, stopReport, exchangeCode, claudeState, waitForCheckIn,
+  signIn, cleanBase, install, removeStartEntry, installedState, status, digestArgv,
+};