@bongos/core 1.24.76 → 1.24.78

package/tests/autobongos_host.mjs

@@ -0,0 +1,647 @@
+// tests/autobongos_host.mjs — the runner's device program
+// (scripts/bongos/autobongos-host.js, task 1005095).
+//
+// What must hold, each driven through the real code rather than read off it:
+//   · the outer loop relaunches at once on the supervisor's upgrade exit, waits
+//     longer after each crash, and ends on a stop request;
+//   · it never resets a checkout that is not marked as the runner's own;
+//   · stop WATCHES real processes exit before saying so, and says NOT STOPPED
+//     when one outlives the wait (the lie task 1004375 was filed for);
+//   · the runner's login lives under its own config root, where the builder's
+//     own session can neither be overwritten nor fallen back to;
+//   · the two start entries (a Windows Run value, a Mac launchd agent) are built
+//     for any path a real device has, spaces and all.
+//
+// Every case runs on every platform: the platform is an argument, so the Mac
+// entry is exercised on Windows and Linux and the Windows one on a Mac.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir, hostname } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const host = require('../scripts/bongos/autobongos-host.js');
+const HOST_JS = fileURLToPath(new URL('../scripts/bongos/autobongos-host.js', import.meta.url));
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+
+const tmp = mkdtempSync(path.join(tmpdir(), 'ab-host-'));
+process.on('exit', () => { try { rmSync(tmp, { recursive: true, force: true }); } catch (_) {} });
+const fresh = (name) => { const d = path.join(tmp, name); mkdirSync(d, { recursive: true }); return d; };
+
+// A loop harness: `exits` is what each supervisor run returns, in order.
+function loopDeps(exits, extra = {}) {
+  const calls = { refresh: 0, deps: 0, spawns: 0, sleeps: [], logs: [] };
+  let t = 0;
+  return {
+    calls,
+    deps: {
+      refresh: async () => { calls.refresh += 1; },
+      ensureDeps: async () => { calls.deps += 1; },
+      spawnSupervisor: async () => { calls.spawns += 1; t += extra.runMs || 1000; return exits.shift(); },
+      sleep: async (ms) => { calls.sleeps.push(ms / 1000); },
+      log: (l) => calls.logs.push(l),
+      now: () => t,
+      ...extra,
+    },
+  };
+}
+
+// ── the outer loop ──────────────────────────────────────────────────────────
+
+test('the upgrade exit code is the supervisor\'s own', () => {
+  const run = require('../scripts/bongos/autobongos-run.js');
+  assert.equal(host.UPGRADE_EXIT_CODE, run.UPGRADE_EXIT_CODE);
+});
+
+test('an upgrade exit relaunches at once, refreshing the copy first, with no wait', async () => {
+  const { calls, deps } = loopDeps([75, 75, 75]);
+  const out = await host.runLoop({ maxCycles: 3 }, deps);
+  assert.equal(out, 75);
+  assert.equal(calls.spawns, 3);
+  assert.equal(calls.refresh, 3, 'every launch brings the copy current first');
+  assert.equal(calls.deps, 3, 'and checks its dependencies');
+  assert.deepEqual(calls.sleeps, [], 'an upgrade is not a failure, so nothing waits');
+});
+
+test('a crash waits before the next launch, and the wait grows to a ceiling', async () => {
+  const { calls, deps } = loopDeps(new Array(9).fill(1));
+  await host.runLoop({ maxCycles: 9 }, deps);
+  assert.deepEqual(calls.sleeps, [5, 10, 20, 40, 80, 160, 300, 300], 'doubling from 5s, capped at 5 minutes');
+});
+
+test('a run that stayed up resets the wait, so one crash a day is not treated as a storm', async () => {
+  const { calls, deps } = loopDeps([1, 1, 1], { runMs: host.HEALTHY_RUN_MS });
+  await host.runLoop({ maxCycles: 3 }, deps);
+  assert.deepEqual(calls.sleeps, [5, 5]);
+});
+
+test('an upgrade exit after crashes clears the backoff', async () => {
+  const { calls, deps } = loopDeps([1, 1, 75, 1, 1]);
+  await host.runLoop({ maxCycles: 5 }, deps);
+  assert.deepEqual(calls.sleeps, [5, 10, 5]);
+});
+
+test('a stop request ends the loop instead of relaunching', async () => {
+  let stop = false;
+  const { calls, deps } = loopDeps([1, 1], { shouldStop: () => stop });
+  deps.spawnSupervisor = async () => { calls.spawns += 1; stop = true; return 1; };
+  assert.equal(await host.runLoop({}, deps), 'stopped');
+  assert.equal(calls.spawns, 1);
+  assert.deepEqual(calls.sleeps, []);
+});
+
+test('when this program itself changed, an upgrade exit hands over instead of looping on old code', async () => {
+  const { calls, deps } = loopDeps([75], { selfChanged: () => true });
+  assert.equal(await host.runLoop({}, deps), 'relaunch_self');
+  assert.equal(calls.spawns, 1);
+});
+
+test('a failed refresh or dependency install does not stop the runner starting', async () => {
+  const { calls, deps } = loopDeps([75]);
+  deps.refresh = async () => { throw new Error('offline'); };
+  deps.ensureDeps = async () => { throw new Error('npm ci exited 1'); };
+  assert.equal(await host.runLoop({ maxCycles: 1 }, deps), 75);
+  assert.equal(calls.spawns, 1, 'being a commit behind beats not running at all');
+  assert.ok(calls.logs.some((l) => /offline/.test(l)) && calls.logs.some((l) => /npm ci/.test(l)), 'and both are in the log');
+});
+
+// ── the runner's own copy ───────────────────────────────────────────────────
+
+test('a checkout is the runner\'s own only when it carries the mark, and a linked worktree never does', () => {
+  const clone = fresh('clone');
+  mkdirSync(path.join(clone, '.git'));
+  assert.equal(host.isRunnerCopy(clone), false);
+  assert.throws(() => host.assertRunnerCopy(clone), (e) => e.name === 'Stop' && /not the runner's own copy/.test(e.message) && /Settings/.test(e.fix));
+  writeFileSync(host.runnerCopyMarkPath(clone), 'marked\n');
+  assert.equal(host.isRunnerCopy(clone), true);
+  assert.doesNotThrow(() => host.assertRunnerCopy(clone));
+
+  const linked = fresh('linked');
+  writeFileSync(path.join(linked, '.git'), 'gitdir: /somewhere/else\n');   // what a linked worktree has
+  assert.equal(host.isRunnerCopy(linked), false);
+});
+
+test('run, start and install refuse a working copy with a sentence, and change nothing', () => {
+  // This checkout is a builder's (or CI's) working copy: it has no mark.
+  const home = fresh('refuse-home');
+  for (const cmd of ['run', 'start', 'install']) {
+    const r = spawnSync(process.execPath, [HOST_JS, cmd], { encoding: 'utf8', env: { ...process.env, AUTOBONGOS_HOME: home } });
+    assert.equal(r.status, 1, `${cmd} must refuse`);
+    assert.match(r.stderr, /Autobongos stopped here: .*not the runner's own copy/, cmd);
+    assert.match(r.stderr, /What to do: /, cmd);
+    assert.doesNotMatch(r.stderr, /\n\s+at /, `${cmd} must not print a stack`);
+  }
+  assert.equal(existsSync(path.join(home, 'host.json')), false, 'no lock was taken');
+});
+
+// ── one loop per device ─────────────────────────────────────────────────────
+
+test('the lock is held only by a fresh beat from a live process that is not us', () => {
+  const now = 1_000_000;
+  const alive = () => true;
+  assert.equal(host.lockHolder(null, { now, alive }), null);
+  assert.equal(host.lockHolder({ pid: 4242, at: now - 1000 }, { now, alive, self: 1 }), 4242);
+  assert.equal(host.lockHolder({ pid: 4242, at: now - 1000 }, { now, alive, self: 4242 }), null, 'our own beat');
+  assert.equal(host.lockHolder({ pid: 4242, at: now - 1000 }, { now, alive, self: 1, takeover: 4242 }), null, 'the copy handing over to us');
+  assert.equal(host.lockHolder({ pid: 4242, at: now - host.LOCK_STALE_MS - 1 }, { now, alive, self: 1 }), null, 'a stale beat is a dead loop, whatever now owns that pid');
+  assert.equal(host.lockHolder({ pid: 4242, at: now - 1000 }, { now, alive: () => false, self: 1 }), null);
+});
+
+// ── stop is honest ──────────────────────────────────────────────────────────
+
+const sleeper = () => spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore', detached: process.platform !== 'win32' });
+const waitGone = async (pid) => { for (let i = 0; i < 80 && host.pidAlive(pid); i++) await new Promise((r) => setTimeout(r, 100)); return !host.pidAlive(pid); };
+
+function stage(name, { loopPid, supervisorPid }) {
+  const home = fresh(name);
+  const paths = host.hostPaths({ AUTOBONGOS_HOME: home }, home);
+  if (loopPid) writeFileSync(paths.lock, JSON.stringify({ pid: loopPid, at: Date.now() }));
+  if (supervisorPid) {
+    mkdirSync(path.join(paths.configRoot, 'cloudbongos'), { recursive: true });
+    writeFileSync(path.join(paths.configRoot, 'cloudbongos', 'autobongos-heartbeat.json'), JSON.stringify({ pid: supervisorPid, at: Date.now() }));
+  }
+  return paths;
+}
+
+test('stop ends the loop AND the supervisor, watches both exit, and only then says stopped', async () => {
+  const loop = sleeper(); const sup = sleeper();
+  const paths = stage('stop-real', { loopPid: loop.pid, supervisorPid: sup.pid });
+  const out = await host.stopRunner({ paths, unload: () => {} });
+  assert.equal(out.outcome, 'stopped');
+  assert.deepEqual([...out.pids].sort(), [loop.pid, sup.pid].sort());
+  assert.equal(await waitGone(loop.pid), true, 'the loop is really gone');
+  assert.equal(await waitGone(sup.pid), true, 'and so is the supervisor');
+  assert.equal(existsSync(paths.lock), false, 'the lock goes with it');
+  assert.match(host.stopReport(out, { installed: true }).join('\n'), /watched, not assumed[\s\S]*starts again the next time you sign in/);
+});
+
+test('a process that outlives the wait is reported NOT STOPPED, with the command that ends it', async () => {
+  const paths = stage('stop-stuck', { loopPid: 999001, supervisorPid: null });
+  const killed = [];
+  const out = await host.stopRunner({
+    paths, unload: () => {}, waitMs: 400, alive: (p) => p === 999001,
+    kill: (p, o) => killed.push([p, o.force]), sleep: (ms) => new Promise((r) => setTimeout(r, Math.min(ms, 50))),
+  });
+  assert.equal(out.outcome, 'still_running');
+  assert.deepEqual(out.left, [999001]);
+  assert.ok(killed.some(([, force]) => force === false) && killed.some(([, force]) => force === true), 'asked nicely, then forced');
+  assert.equal(existsSync(paths.lock), true, 'a live loop keeps its lock');
+  const win = host.stopReport(out, { platform: 'win32' }).join('\n');
+  assert.match(win, /NOT STOPPED[\s\S]*taskkill \/F \/T \/PID 999001/);
+  assert.match(host.stopReport(out, { platform: 'darwin' }).join('\n'), /kill -9 999001/);
+});
+
+test('stopping a runner that is not running says so, and never claims to have stopped it', async () => {
+  const paths = stage('stop-idle', { loopPid: 999002, supervisorPid: 999003 });
+  const out = await host.stopRunner({ paths, unload: () => {}, alive: () => false, kill: () => { throw new Error('nothing to kill'); } });
+  assert.equal(out.outcome, 'not_running');
+  assert.match(host.stopReport(out).join('\n'), /was not running/);
+});
+
+test('on a Mac the agent is unloaded BEFORE anything is killed, or launchd restarts the loop', async () => {
+  const paths = stage('stop-order', { loopPid: 999004, supervisorPid: null });
+  const order = [];
+  let alive = true;
+  await host.stopRunner({ paths, platform: 'darwin', unload: () => order.push('unload'), alive: () => alive, kill: () => { order.push('kill'); alive = false; } });
+  assert.deepEqual(order, ['unload', 'kill']);
+});
+
+// ── its own login, apart from the builder's ────────────────────────────────
+
+test('the supervisor runs under the runner\'s own config root, and keeps a gauge the device already has', () => {
+  const paths = host.hostPaths({ AUTOBONGOS_HOME: path.join(tmp, 'h') }, path.join(tmp, 'h'));
+  const env = host.supervisorEnv({ PATH: 'x' }, paths, 'otb');
+  assert.equal(env.BONGOS_CONFIG_ROOT, paths.configRoot);
+  assert.match(env.AUTOBONGOS_GAUGE_FILE, /[\\/]\.config[\\/]otb[\\/]autobongos-gauge\.json$/, 'the builder-side file a statusLine writes');
+  assert.equal(host.supervisorEnv({ AUTOBONGOS_GAUGE_FILE: '/set/by/hand' }, paths).AUTOBONGOS_GAUGE_FILE, '/set/by/hand');
+});
+
+test('under BONGOS_CONFIG_ROOT every session path moves, and the builder\'s own session is not a fallback', () => {
+  const root = fresh('cfgroot');
+  const probe = `
+    const cli = require(${JSON.stringify(path.join(REPO, 'scripts', 'bongos', 'cli-lib.js'))});
+    const ic = require(${JSON.stringify(path.join(REPO, 'src', 'instance-config.js'))});
+    const run = require(${JSON.stringify(path.join(REPO, 'scripts', 'bongos', 'autobongos-run.js'))});
+    (async () => {
+      await cli.saveSession({ token: 't'.repeat(32), api_base: 'https://hub.example', builder: { github_login: 'runner' } });
+      process.stdout.write(JSON.stringify({
+        session: cli.SESSION_PATH, reads: ic.configReadDirs(), heartbeat: run.heartbeatPath(), log: run.logPath(),
+        loaded: (await cli.loadSession()).builder.github_login,
+      }));
+    })();`;
+  const r = spawnSync(process.execPath, ['-e', probe], { encoding: 'utf8', env: { ...process.env, BONGOS_CONFIG_ROOT: root, AUTOBONGOS_HEARTBEAT_FILE: '', AUTOBONGOS_LOG_FILE: '' } });
+  assert.equal(r.status, 0, r.stderr);
+  const out = JSON.parse(r.stdout);
+  const inside = (p) => path.resolve(p).startsWith(path.resolve(root) + path.sep);
+  assert.ok(inside(out.session), `session at ${out.session}`);
+  assert.ok(out.reads.every(inside), `every read dir is under the runner's root: ${out.reads.join(', ')}`);
+  assert.ok(inside(out.heartbeat) && inside(out.log), 'the supervisor\'s heartbeat and run log too');
+  assert.equal(out.loaded, 'runner');
+  // The host-keyed store saveSession also writes sits beside it, not in ~/.config.
+  assert.ok(existsSync(path.join(root, 'cloudbongos', 'instances', 'hub.example.json')), 'the per-instance store moved with it');
+});
+
+test('a worker inherits the runner\'s config root, or it would ship as the wrong session', () => {
+  const run = require('../scripts/bongos/autobongos-run.js');
+  assert.equal(run.workerEnv({ BONGOS_CONFIG_ROOT: '/runner/config', SECRET_DB_URL: 'x' }).BONGOS_CONFIG_ROOT, '/runner/config');
+  assert.equal(run.workerEnv({ SECRET_DB_URL: 'x' }).SECRET_DB_URL, undefined, 'and the allowlist still refuses everything else');
+});
+
+// ── keep-awake ──────────────────────────────────────────────────────────────
+
+test('the device is held awake while the runner may work, and released when the fence stops it', () => {
+  assert.equal(host.wantsAwake('worked', false), true);
+  assert.equal(host.wantsAwake('nothing_claimable', false), true, 'waiting for work is still a runner someone pressed Run on');
+  assert.equal(host.wantsAwake('hold', false), true, 'resting until a usage reset must wake to resume');
+  assert.equal(host.wantsAwake('fenced', true), false, 'stopped: a laptop must be allowed to sleep');
+  assert.equal(host.wantsAwake('boot_reconcile', true), true, 'a boot row says nothing either way');
+  assert.equal(host.wantsAwake('boot_reconcile', false), false);
+});
+
+test('keep-awake starts one holder, stops it on release, and can be switched off', () => {
+  const made = [];
+  const fake = () => { const c = { killed: false, on() {}, kill() { c.killed = true; } }; made.push(c); return c; };
+  const k = host.makeKeepAwake({ platform: 'darwin', env: {}, spawnFn: fake, pid: 77 });
+  k.set(true); k.set(true);
+  assert.equal(made.length, 1, 'asking twice holds once');
+  assert.equal(k.on, true);
+  k.set(false);
+  assert.equal(made[0].killed, true);
+  assert.equal(k.on, false);
+
+  const off = host.makeKeepAwake({ platform: 'darwin', env: { AUTOBONGOS_KEEP_AWAKE: '0' }, spawnFn: fake, pid: 77 });
+  off.set(true);
+  assert.equal(made.length, 1, 'AUTOBONGOS_KEEP_AWAKE=0 holds nothing');
+
+  assert.deepEqual(host.keepAwakeCommand('darwin', 77), { cmd: 'caffeinate', args: ['-i', '-w', '77'] });
+  const win = host.keepAwakeCommand('win32', 77);
+  assert.equal(win.cmd, 'powershell.exe');
+  assert.match(win.args.join(' '), /SetThreadExecutionState\(2147483649\)[\s\S]*Wait-Process -Id 77/);
+  assert.equal(host.keepAwakeCommand('linux', 77), null);
+});
+
+// ── the start entries ───────────────────────────────────────────────────────
+
+test('the Windows start entry runs headless when conhost is there, and quotes every path with a space', () => {
+  const argv = host.windowsRunArgv({ node: 'C:\\Program Files\\nodejs\\node.exe', script: 'C:\\Users\\A B\\.cloudbongos-runner\\repo\\scripts\\bongos\\autobongos-host.js', conhost: 'C:\\Windows\\System32\\conhost.exe', hasConhost: true });
+  assert.deepEqual(argv.slice(0, 2), ['C:\\Windows\\System32\\conhost.exe', '--headless']);
+  assert.equal(
+    host.windowsRunCommand(argv),
+    'C:\\Windows\\System32\\conhost.exe --headless "C:\\Program Files\\nodejs\\node.exe" "C:\\Users\\A B\\.cloudbongos-runner\\repo\\scripts\\bongos\\autobongos-host.js" run',
+  );
+  const bare = host.windowsRunArgv({ node: 'C:\\n\\node.exe', script: 'C:\\r\\autobongos-host.js', hasConhost: false });
+  assert.deepEqual(bare, ['C:\\n\\node.exe', 'C:\\r\\autobongos-host.js', 'run'], 'without conhost it still starts');
+});
+
+test('this program starts the Windows loop through cmd start, never by spawning conhost itself', () => {
+  // Found by running it: node hands a child its standard handles, and a headless
+  // conhost given handles runs nothing and exits 0. `start` gives it none.
+  const argv = ['C:\\Windows\\System32\\conhost.exe', '--headless', 'C:\\Program Files\\nodejs\\node.exe', 'C:\\Users\\A B\\repo\\scripts\\bongos\\autobongos-host.js', 'run'];
+  const { cmd, args, options } = host.windowsStartSpawn(argv);
+  assert.equal(cmd, 'cmd.exe');
+  assert.deepEqual(args.slice(0, 3), ['/d', '/s', '/c']);
+  assert.equal(args[3], '"start "" "C:\\Windows\\System32\\conhost.exe" "--headless" "C:\\Program Files\\nodejs\\node.exe" "C:\\Users\\A B\\repo\\scripts\\bongos\\autobongos-host.js" "run""');
+  // Real Windows paths: every backslash survives, and nothing in the line is a
+  // control character (a path typed with single backslashes turns \n and \r
+  // into a newline and a carriage return, and cmd would run a different line).
+  assert.equal((args[3].match(/\\/g) || []).length, 12);
+  assert.equal(/[\x00-\x1f]/.test(args[3]), false);
+  assert.equal(options.windowsVerbatimArguments, true, 'cmd must receive that line exactly as written');
+  assert.equal(options.detached, true);
+  assert.equal(options.stdio, 'ignore');
+});
+
+test('a PC that already runs the boot-time scheduled task is recognised, so setup can refuse a second runner', () => {
+  const asked = [];
+  const run = (status) => (cmd, args) => { asked.push([cmd, ...args]); return { status }; };
+  assert.equal(host.legacyBootTaskInstalled('win32', run(0)), true);
+  assert.equal(host.legacyBootTaskInstalled('win32', run(1)), false);
+  assert.deepEqual(asked[0], ['schtasks', '/Query', '/TN', 'Autobongos']);
+  assert.equal(host.legacyBootTaskInstalled('darwin', () => { throw new Error('a Mac has no scheduled tasks to ask'); }), false);
+});
+
+test('the Mac start entry is a per-user agent that starts at sign-in, restarts, and carries the PATH it was installed with', () => {
+  const paths = host.hostPaths({}, '/Users/a&b');
+  const plist = host.launchdPlist({ node: '/Users/a&b/.cloudbongos-runner/node/bin/node', script: '/r/autobongos-host.js', cwd: '/r', paths, envPath: '/opt/homebrew/bin:/usr/bin', home: '/Users/a&b' });
+  assert.match(plist, new RegExp(`<key>Label</key><string>${host.LABEL}</string>`));
+  assert.match(plist, /<key>RunAtLoad<\/key><true\/>/);
+  assert.match(plist, /<key>KeepAlive<\/key><true\/>/);
+  assert.match(plist, /<string>\/Users\/a&amp;b\/\.cloudbongos-runner\/node\/bin\/node<\/string>\s*<string>\/r\/autobongos-host\.js<\/string>\s*<string>run<\/string>/, 'node, the program, run — escaped');
+  assert.match(plist, /<key>PATH<\/key><string>\/opt\/homebrew\/bin:\/usr\/bin<\/string>/);
+  assert.match(plist, /<key>AUTOBONGOS_SUPERVISOR<\/key><string>launchd<\/string>/);
+  assert.doesNotMatch(plist, /a&b/, 'no raw ampersand: an unescaped one makes launchd refuse the whole file');
+  assert.match(paths.plist, /Library[\\/]LaunchAgents[\\/]com\.cloudbongos\.autobongos\.plist$/, 'a LaunchAgent in the person\'s own Library, never a system daemon');
+});
+
+// ── setup's two outward calls ───────────────────────────────────────────────
+
+test('the code exchange turns each refusal into a sentence with a next step', async () => {
+  const ok = await host.exchangeCode({ apiBase: 'https://hub.example', code: 'abr_x', fetchImpl: async (url, init) => {
+    assert.equal(url, 'https://hub.example/api/bongos/auth/runner-code/exchange');
+    assert.deepEqual(JSON.parse(init.body), { code: 'abr_x' });
+    return { ok: true, status: 200, json: async () => ({ token: 'tok', builder_login: 'ada' }) };
+  } });
+  assert.equal(ok.token, 'tok');
+
+  const stop = async (fetchImpl) => { try { await host.exchangeCode({ apiBase: 'https://hub.example', code: 'abr_x', fetchImpl }); } catch (e) { return e; } return null; };
+  const used = await stop(async () => ({ ok: false, status: 401, json: async () => ({}) }));
+  assert.equal(used.name, 'Stop');
+  assert.match(used.message, /already used, or older than 15 minutes/);
+  assert.match(used.fix, /Add a device again/);
+  const down = await stop(async () => { throw new Error('ECONNREFUSED 10.0.0.1:443'); });
+  assert.match(down.message, /could not reach https:\/\/hub\.example/);
+  assert.doesNotMatch(`${down.message} ${down.fix}`, /ECONNREFUSED|10\.0\.0\.1/, 'no raw error text reaches the person');
+  const odd = await stop(async () => ({ ok: true, status: 200, json: async () => ({}) }));
+  assert.match(odd.message, /without a login/);
+});
+
+test('running the same setup command twice keeps the login and never spends the used code', async () => {
+  // The pasted line carries a code that works once. The second run must change
+  // nothing, not stop on "already used".
+  const calls = [];
+  const fetchImpl = async (url) => {
+    calls.push(url);
+    if (url.endsWith('/api/bongos/me')) return { ok: true, status: 200, json: async () => ({}) };
+    return { ok: false, status: 401, json: async () => ({}) };   // the code is spent
+  };
+  const have = { token: 'tok', api_base: 'https://hub.example', builder: { github_login: 'ada' } };
+  const again = await host.signIn({ code: 'abr_used', apiBase: 'https://hub.example/', session: have, fetchImpl });
+  assert.equal(again.fresh, false);
+  assert.equal(again.session, have, 'the login it already had');
+  assert.deepEqual(calls, ['https://hub.example/api/bongos/me'], 'the code was never sent');
+});
+
+test('the code is traded when there is no login, the login is refused, or it belongs to another project', async () => {
+  const exchange = { ok: true, status: 200, json: async () => ({ token: 'new', builder_login: 'ada', session_id: '9', label: 'studio' }) };
+  const mk = (meOk) => { const calls = []; return { calls, fetchImpl: async (url) => { calls.push(url.replace('https://hub.example/api/bongos', '')); return url.endsWith('/me') ? { ok: meOk, status: meOk ? 200 : 401, json: async () => ({}) } : exchange; } }; };
+
+  const none = mk(true);
+  const first = await host.signIn({ code: 'abr_x', apiBase: 'https://hub.example', session: null, fetchImpl: none.fetchImpl, hostName: 'pc' });
+  assert.equal(first.fresh, true);
+  assert.deepEqual(first.session, { token: 'new', api_base: 'https://hub.example', builder: { github_login: 'ada' }, runner: { label: 'studio', session_id: '9' } });
+  assert.deepEqual(none.calls, ['/auth/runner-code/exchange'], 'no login to check, so straight to the exchange');
+
+  const removed = mk(false);   // the device was removed in Settings: its login is refused
+  const second = await host.signIn({ code: 'abr_x', apiBase: 'https://hub.example', session: { token: 'old', api_base: 'https://hub.example' }, fetchImpl: removed.fetchImpl });
+  assert.equal(second.fresh, true);
+  assert.deepEqual(removed.calls, ['/me', '/auth/runner-code/exchange']);
+
+  const other = mk(true);      // signed in to a different project: that login is not this one's
+  const third = await host.signIn({ code: 'abr_x', apiBase: 'https://hub.example', session: { token: 'old', api_base: 'https://elsewhere.example' }, fetchImpl: other.fetchImpl });
+  assert.equal(third.fresh, true);
+  assert.deepEqual(other.calls, ['/auth/runner-code/exchange'], 'another project\'s login is never even asked about');
+});
+
+test('with no code, a device keeps a good login and is told plainly when it has none or it was removed', async () => {
+  const good = async () => ({ ok: true, status: 200, json: async () => ({}) });
+  const refused = async () => ({ ok: false, status: 401, json: async () => ({}) });
+  const have = { token: 'tok', api_base: 'https://hub.example' };
+  assert.equal((await host.signIn({ session: have, fetchImpl: good })).fresh, false);
+  const stop = async (args) => { try { await host.signIn(args); } catch (e) { return e; } return null; };
+  const none = await stop({ session: null, fetchImpl: good });
+  assert.equal(none.name, 'Stop');
+  assert.match(none.message, /no runner login yet/);
+  assert.match(none.fix, /Add a device/);
+  const gone = await stop({ session: have, fetchImpl: refused });
+  assert.match(gone.message, /no longer accepts this device/);
+});
+
+test('the code and the login only ever cross the network over https', async () => {
+  for (const ok of ['https://hub.example', 'https://hub.example:8443', 'http://localhost:3000', 'http://127.0.0.1:4600', 'http://app.localhost', 'http://hall.test:3000']) {
+    assert.equal(host.cleanBase(`${ok}/`), ok, ok);
+  }
+  for (const bad of ['http://hub.example', 'http://evil.localhost.example', 'ftp://hub.example', 'https://hub.example/path', 'hub.example', '', null]) {
+    assert.equal(host.cleanBase(bad), null, String(bad));
+  }
+  let sent = false;
+  const e = await host.signIn({ code: 'abr_x', apiBase: 'http://hub.example', session: null, fetchImpl: async () => { sent = true; return { ok: true, json: async () => ({ token: 't' }) }; } }).catch((err) => err);
+  assert.equal(e.name, 'Stop');
+  assert.match(e.message, /not a secure \(https\) address/);
+  assert.equal(sent, false, 'nothing was sent to a plain-http project');
+});
+
+test('the Windows start entry is written, checked and removed through reg, and uninstall looks before it answers', () => {
+  const home = fresh('reg-home');
+  const paths = host.hostPaths({ AUTOBONGOS_HOME: home }, home);
+  const clone = fresh('reg-clone');
+  mkdirSync(path.join(clone, '.git'));
+  writeFileSync(host.runnerCopyMarkPath(clone), 'marked\n');
+  // A stand-in registry: one value, present or not.
+  let present = false;
+  const asked = [];
+  const reg = (cmd, args) => {
+    asked.push([cmd, args[0], ...args.slice(1, 4)]);
+    if (args[0] === 'add') { present = true; return { status: 0 }; }
+    if (args[0] === 'delete') { present = false; return { status: 0 }; }
+    return { status: present ? 0 : 1 };   // query
+  };
+  assert.equal(host.installedState('win32', paths, reg), false);
+  assert.deepEqual(host.install({ platform: 'win32', paths, run: reg, repoRoot: clone }), { kind: 'windows-run-entry' });
+  assert.equal(host.installedState('win32', paths, reg), true);
+  const add = asked.find((a) => a[1] === 'add');
+  assert.deepEqual(add, ['reg', 'add', 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run', '/v', 'Autobongos'], 'the person\'s own Run key: no administrator');
+
+  assert.equal(host.removeStartEntry({ platform: 'win32', paths, run: reg }), true, 'gone, and seen to be gone');
+  assert.equal(host.installedState('win32', paths, reg), false);
+
+  // A delete that does not take: uninstall must say so, not promise it is gone.
+  present = true;
+  const stuck = (cmd, args) => (args[0] === 'query' ? { status: 0 } : { status: 1 });
+  assert.equal(host.removeStartEntry({ platform: 'win32', paths, run: stuck }), false);
+
+  // And a refused write is a sentence, not a thrown reg error.
+  assert.throws(() => host.install({ platform: 'win32', paths, run: () => ({ status: 1 }), repoRoot: clone }), (e) => e.name === 'Stop' && /would not save the start-at-sign-in entry/.test(e.message));
+  // Installing from a working copy is refused before anything is written.
+  let touched = false;
+  assert.throws(() => host.install({ platform: 'win32', paths, run: () => { touched = true; return { status: 0 }; }, repoRoot: fresh('not-a-copy') }), (e) => e.name === 'Stop');
+  assert.equal(touched, false);
+});
+
+test('the Mac start entry is a file in LaunchAgents: install writes it, uninstall removes it and checks', () => {
+  const home = fresh('mac-home');
+  const paths = host.hostPaths({ AUTOBONGOS_HOME: path.join(home, 'runner') }, home);
+  const clone = fresh('mac-clone');
+  mkdirSync(path.join(clone, '.git'));
+  writeFileSync(host.runnerCopyMarkPath(clone), 'marked\n');
+  const never = () => { throw new Error('a Mac install must not call reg'); };
+  assert.equal(host.installedState('darwin', paths, never), false);
+  assert.deepEqual(host.install({ platform: 'darwin', paths, run: never, repoRoot: clone }), { kind: 'launchd-agent' });
+  assert.equal(existsSync(paths.plist), true);
+  assert.match(readFileSync(paths.plist, 'utf8'), /<key>Label<\/key><string>com\.cloudbongos\.autobongos<\/string>/);
+  assert.equal(host.installedState('darwin', paths, never), true);
+  assert.equal(host.removeStartEntry({ platform: 'darwin', paths, run: never }), true);
+  assert.equal(existsSync(paths.plist), false);
+  assert.equal(host.removeStartEntry({ platform: 'darwin', paths, run: never }), true, 'removing what is already gone is still "gone"');
+  // A system with neither has no entry, and says so rather than failing.
+  assert.deepEqual(host.install({ platform: 'linux', paths, run: never, repoRoot: clone }), { kind: 'none' });
+  assert.equal(host.installedState('linux', paths, never), false);
+});
+
+test('status reads the device\'s own files: running only on a fresh lock held by a live process, and whose login it holds', () => {
+  const home = fresh('status-home');
+  const paths = host.hostPaths({ AUTOBONGOS_HOME: home }, home);
+  const now = 5_000_000;
+  const notInstalled = () => ({ status: 1 });
+  const base = { platform: 'win32', paths, configDirName: 'cloudbongos', now, run: notInstalled };
+
+  let s = host.status({ ...base, alive: () => true });
+  assert.deepEqual([s.running, s.pid, s.signed_in_as, s.project, s.starts_at_sign_in], [false, null, null, null, false], 'a device that was never set up');
+  assert.equal(s.log, paths.log);
+
+  writeFileSync(paths.lock, JSON.stringify({ pid: 4242, at: now - 1000 }));
+  mkdirSync(path.join(paths.configRoot, 'cloudbongos'), { recursive: true });
+  writeFileSync(path.join(paths.configRoot, 'cloudbongos', 'bongos-session.json'), JSON.stringify({ token: 'SECRET-TOKEN', api_base: 'https://hub.example', builder: { github_login: 'ada' } }));
+  s = host.status({ ...base, alive: () => true, run: () => ({ status: 0 }) });
+  assert.deepEqual([s.running, s.pid, s.signed_in_as, s.project, s.starts_at_sign_in], [true, 4242, 'ada', 'https://hub.example', true]);
+  assert.equal(JSON.stringify(s).includes('SECRET-TOKEN'), false, 'status names whose login it is and never prints the login');
+
+  assert.equal(host.status({ ...base, alive: () => false }).running, false, 'a lock whose process is gone');
+  assert.equal(host.status({ ...base, now: now + host.LOCK_STALE_MS + 2000, alive: () => true }).running, false, 'a lock nobody has refreshed');
+});
+
+test('Claude is read as installed and signed in from its own answers, with a fallback for an older CLI', () => {
+  const resolveBin = () => ({ bin: 'claude', shell: false });
+  const run = (answers) => (bin, args) => answers[args.join(' ')] || { status: 1, stdout: '' };
+  const yes = host.claudeState({ resolveBin, claudeAccountLabel: () => null, run: run({ '--version': { status: 0, stdout: '2.1.0' }, 'auth status': { status: 0, stdout: '{"loggedIn":true}' } }) });
+  assert.deepEqual([yes.installed, yes.signedIn], [true, true]);
+  const no = host.claudeState({ resolveBin, claudeAccountLabel: () => 'ada@example.com', run: run({ '--version': { status: 0, stdout: '2.1.0' }, 'auth status': { status: 0, stdout: '{"loggedIn":false}' } }) });
+  assert.equal(no.signedIn, false, 'its own "no" wins over a stale file');
+  const old = host.claudeState({ resolveBin, claudeAccountLabel: () => 'ada@example.com', run: run({ '--version': { status: 0, stdout: '1.0.0' } }) });
+  assert.equal(old.signedIn, true, 'an older CLI with no auth command falls back to the recorded sign-in');
+  const none = host.claudeState({ resolveBin, claudeAccountLabel: () => null, run: () => ({ status: 1, error: new Error('ENOENT') }) });
+  assert.deepEqual([none.installed, none.signedIn], [false, false]);
+});
+
+test('setup waits for THIS device\'s check-in, not anyone\'s', async () => {
+  const session = { api_base: 'https://hub.example', token: 'tok' };
+  const rows = (list) => async () => ({ ok: true, json: async () => ({ runners: list }) });
+  const nowIso = new Date().toISOString();
+  const sleep = async () => {};
+  assert.equal(await host.waitForCheckIn({ session, sleep, timeoutMs: 200, fetchImpl: rows([{ host: 'some-other-pc', last_seen_at: nowIso }]) }), false);
+  assert.equal(await host.waitForCheckIn({ session, sleep, timeoutMs: 200, fetchImpl: rows([{ host: hostname().toUpperCase(), last_seen_at: nowIso }]) }), true, 'the server lowercases host names');
+  assert.equal(await host.waitForCheckIn({ session, sleep, timeoutMs: 200, fetchImpl: rows([{ host: hostname(), last_seen_at: '2020-01-01T00:00:00Z' }]) }), false, 'a check-in from a past install does not count');
+});
+
+// ── the bootstrap scripts ───────────────────────────────────────────────────
+
+const SH = fileURLToPath(new URL('../scripts/bongos/autobongos-bootstrap.sh', import.meta.url));
+const PS1 = fileURLToPath(new URL('../scripts/bongos/autobongos-bootstrap.ps1', import.meta.url));
+const bash = spawnSync('bash', ['--version'], { encoding: 'utf8' }).status === 0 ? 'bash' : null;
+if (!bash && process.env.CI) throw new Error('no bash on this CI runner — the bootstrap cases must run, not skip');
+
+test('the shell bootstrap stops with a sentence on an incomplete command, and changes nothing on a dry run', { skip: bash ? false : 'no bash on this machine' }, () => {
+  const home = fresh('sh-home');
+  const part = spawnSync(bash, [SH, '--code', 'abr_x'], { encoding: 'utf8', env: { ...process.env, AUTOBONGOS_HOME: home } });
+  assert.equal(part.status, 1);
+  assert.match(part.stderr, /Autobongos setup stopped here: the setup command is incomplete\.\nWhat to do: Copy the whole command again/);
+
+  const bad = spawnSync(bash, [SH, '--code', 'abr_x', '--api-base', 'https://hub.example', '--repo', 'git@github.com:a/b.git'], { encoding: 'utf8', env: { ...process.env, AUTOBONGOS_HOME: home } });
+  assert.equal(bad.status, 1);
+  assert.match(bad.stderr, /project address in the command does not look right/);
+
+  // The code is sent to the project address, so a plain-http one is refused
+  // before anything is installed or copied; this machine's own is allowed.
+  const clear = spawnSync(bash, [SH, '--code', 'abr_x', '--api-base', 'http://hub.example', '--repo', 'https://github.com/a/b', '--dry-run'], { encoding: 'utf8', env: { ...process.env, AUTOBONGOS_HOME: home } });
+  assert.equal(clear.status, 1);
+  assert.match(clear.stderr, /not a secure \(https\) address/);
+  const local = spawnSync(bash, [SH, '--code', 'abr_x', '--api-base', 'http://localhost:3000', '--repo', 'https://github.com/a/b', '--dry-run'], { encoding: 'utf8', env: { ...process.env, AUTOBONGOS_HOME: home } });
+  assert.equal(local.status, 0, local.stderr);
+
+  const dry = spawnSync(bash, [SH, '--code', 'abr_x', '--api-base', 'https://hub.example', '--repo', 'https://github.com/a/b', '--dry-run'], { encoding: 'utf8', env: { ...process.env, AUTOBONGOS_HOME: home } });
+  assert.equal(dry.status, 0, dry.stderr);
+  assert.match(dry.stdout, /Would make the runner's copy of the project in /);
+  assert.equal(existsSync(path.join(home, 'repo')), false, 'a dry run makes no copy');
+});
+
+test('the shell bootstrap makes the runner its own copy and hands over to the device program', { skip: bash ? false : 'no bash on this machine' }, () => {
+  // A local repository stands in for GitHub: one commit carrying a stand-in
+  // device program that records how it was called.
+  const origin = fresh('origin');
+  const g = (args, cwd) => { const r = spawnSync('git', args, { cwd, encoding: 'utf8' }); assert.equal(r.status, 0, `${args.join(' ')}: ${r.stderr}`); return r; };
+  g(['init', '-q', '-b', 'main'], origin);
+  mkdirSync(path.join(origin, 'scripts', 'bongos'), { recursive: true });
+  writeFileSync(path.join(origin, 'scripts', 'bongos', 'autobongos-host.js'),
+    'require("fs").writeFileSync(require("path").join(process.env.AUTOBONGOS_HOME, "handover.json"), JSON.stringify(process.argv.slice(2)));\n');
+  g(['add', '-A'], origin);
+  g(['-c', 'user.name=t', '-c', 'user.email=t@example.com', 'commit', '-q', '-m', 'init'], origin);
+
+  const home = fresh('sh-real');
+  // A stand-in `claude` on the PATH. A machine without Claude Code (CI) would
+  // otherwise have this test INSTALL it from the network, which is the script
+  // doing its job and the last thing a unit test should set off.
+  const bin = fresh('sh-bin');
+  writeFileSync(path.join(bin, 'claude'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+  // The script only accepts an https address; point that address at the local repo.
+  const env = { ...process.env, PATH: `${bin}${path.delimiter}${process.env.PATH}`, AUTOBONGOS_HOME: home, GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: `url.${origin}.insteadOf`, GIT_CONFIG_VALUE_0: 'https://github.example/a/b' };
+  const args = [SH, '--code', 'abr_code', '--api-base', 'https://hub.example', '--repo', 'https://github.example/a/b'];
+  const first = spawnSync(bash, args, { encoding: 'utf8', env });
+  assert.equal(first.status, 0, first.stderr + first.stdout);
+  assert.ok(existsSync(path.join(home, 'repo', '.git')), 'the copy is in the runner\'s own folder');
+  assert.deepEqual(JSON.parse(readFileSync(path.join(home, 'handover.json'), 'utf8')),
+    ['setup', '--code', 'abr_code', '--api-base', 'https://hub.example', '--mark-runner-copy']);
+
+  // Run again: the copy is brought current, not cloned twice, and it still hands over.
+  rmSync(path.join(home, 'handover.json'));
+  const second = spawnSync(bash, args, { encoding: 'utf8', env });
+  assert.equal(second.status, 0, second.stderr + second.stdout);
+  assert.match(second.stdout, /already here; bringing it up to date/);
+  assert.ok(existsSync(path.join(home, 'handover.json')));
+});
+
+function findPowerShell() {
+  for (const bin of ['pwsh', 'powershell']) {
+    if (spawnSync(bin, ['-NoProfile', '-NonInteractive', '-Command', '1'], { encoding: 'utf8' }).status === 0) return bin;
+  }
+  return null;
+}
+const PS = findPowerShell();
+if (!PS && process.env.CI) throw new Error('no PowerShell (pwsh/powershell) on this CI runner — the bootstrap cases must run, not skip');
+
+test('the PowerShell bootstrap stops with a sentence on an incomplete command, and is plain ASCII', { skip: PS ? false : 'no PowerShell on this machine' }, () => {
+  const part = spawnSync(PS, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', PS1, '-Code', 'abr_x'], { encoding: 'utf8' });
+  assert.equal(part.status, 1);
+  assert.match(part.stdout, /Autobongos setup stopped here: the setup command is incomplete\./);
+  assert.match(part.stdout, /What to do: Copy the whole command again/);
+  const bad = spawnSync(PS, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', PS1, '-Code', 'abr_x', '-ApiBase', 'https://hub.example', '-Repo', 'git@github.com:a/b.git'], { encoding: 'utf8' });
+  assert.equal(bad.status, 1);
+  assert.match(bad.stdout, /project address in the command does not look right/);
+  const clear = spawnSync(PS, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', PS1, '-Code', 'abr_x', '-ApiBase', 'http://hub.example', '-Repo', 'https://github.com/a/b', '-DryRun'], { encoding: 'utf8' });
+  assert.equal(clear.status, 1);
+  assert.match(clear.stdout, /not a secure \(https\) address/);
+  // Windows PowerShell 5.1 reads a BOM-less file as ANSI, so one curly quote or
+  // long dash turns into mojibake inside a string — or a parse error.
+  assert.equal(/[^\x00-\x7F]/.test(readFileSync(PS1, 'utf8')), false);
+});
+
+// ── the night, read from the runner's own files (task 1005097) ───────────────
+
+test('the digest is read from the RUNNER’s run log: bare, the digest CLI looks in the builder’s own folder and finds none', () => {
+  const home = fresh('digest-home');
+  const paths = host.hostPaths({ AUTOBONGOS_HOME: home }, home);
+  const dirName = require('../src/instance-config').configDirName();
+  const logDir = path.join(paths.configRoot, dirName);
+  mkdirSync(logDir, { recursive: true });
+  writeFileSync(path.join(logDir, 'autobongos-runs.jsonl'), `${JSON.stringify({
+    at: new Date().toISOString(), event: 'worked', task_id: 424242, title: 'the task the runner built',
+    outcome: 'claims_shipped', verified: true, ledger_status: 'shipped', ledger_shape: 'shipped', cost_usd: 1.5,
+  })}\n`);
+
+  const argv = host.digestArgv(['--all', '--json']);
+  assert.equal(path.basename(argv[0]), 'autobongos-digest.js');
+  assert.deepEqual(argv.slice(1), ['--all', '--json'], 'whatever the person passed is handed through');
+
+  // Through the device program: the runner's night.
+  const viaHost = spawnSync(process.execPath, [HOST_JS, 'digest', '--all', '--json'], { encoding: 'utf8', env: { ...process.env, AUTOBONGOS_HOME: home, AUTOBONGOS_LOG_FILE: '' } });
+  assert.equal(viaHost.status, 0, viaHost.stderr);
+  assert.ok(viaHost.stdout.includes('424242'), 'the task the runner built is in it');
+
+  // Bare, with an empty folder standing in for the builder's own: nothing to read.
+  const bare = spawnSync(process.execPath, argv, { encoding: 'utf8', env: { ...process.env, BONGOS_CONFIG_ROOT: fresh('digest-builder-root'), AUTOBONGOS_LOG_FILE: '' } });
+  assert.equal(bare.status, 0, 'the digest never fails a morning');
+  assert.equal(bare.stdout.includes('424242'), false, 'which is why the guide sends people through the device program');
+});