@bongos/core 1.24.76 → 1.24.78

package/docs/recipes/autobongos-windows-host.md

@@ -1,4 +1,12 @@
-# Setting up the Autobongos runner on the Windows PC
+# The always-on Windows host: Autobongos that starts at boot
+
+> **Most builders want [Running Autobongos on your own device](autobongos-runner-setup.md)
+> instead.** That flow is one copied command and one Run button, works on Windows
+> and Mac, needs no administrator, and starts the runner when you sign in. This
+> page is the advanced path for ONE case it does not cover: a Windows PC that must
+> come back after a reboot or a power cut **with nobody signed in**. It needs an
+> Administrator window once. Use one or the other on a device, never both — the
+> setup command refuses to add a second runner beside this one.
 
 The runner is a program that claims tasks and spawns Claude Code sessions to work
 them, on an always-on machine with nobody at the keyboard. This is how it gets
@@ -7,12 +15,7 @@ installed so it survives a reboot, and how you check on it afterwards.
 **Design of record:** [ADR 0307](../adr/0307-autobongos-a-deterministic-supervisor-and-agentic-workers.md).
 Task [1003905](https://cloudbongos.com/builders#/task/1003905).
 
-> **NOT YET VERIFIED ON THE REAL MACHINE.** Everything below was written and
-> reviewed on a Mac; the install, the cold reboot and the crash-restart have not
-> been run on the Windows PC, because that machine is not reachable from where
-> this was built. The heartbeat half — the part that tells you whether the runner
-> is alive — *was* verified end to end against a real database. Treat step 3 as
-> the acceptance test, not as a formality.
+> Step 3 is the acceptance test, not a formality: do it after every install.
 
 ---
 

package/modules/autonomy/cadence.js

@@ -164,6 +164,9 @@ function classifyEvent(row = {}) {
     // The per-builder stops (task 1004501) are the same kind of fact as the project
     // switch: a person decided, and probing will not change their mind.
     if (code === 'builder_paused' || code === 'not_permitted') return { class: 'stopped', detail: row.reason || 'this builder’s runner is stopped' };
+    // The builder's own Stop on this device (task 1005094): the same kind of fact
+    // again. It waits, cheaply, for the press of Run.
+    if (code === 'device_stopped') return { class: 'stopped', detail: row.reason || 'this device is stopped' };
     if (code === 'grader_unavailable') return { class: 'transient', detail: 'the grader is unavailable, and it is the only review there is' };
     if (code === 'fence_unreadable') return { class: 'transient', detail: 'the fence could not be read' };
     // no_allowlist / goal_not_allowlisted / protected_path: the fence is working

package/modules/autonomy/db.js

@@ -267,7 +267,7 @@ async function readAllRunnerScopes() {
     // hosts can never push a quieter builder out of the owner's view.
     pool.query(
       `SELECT builder_id, host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id,
-              head, disk_head, main_head, claude_account, last_seen_at
+              head, disk_head, main_head, claude_account, last_seen_at, run_requested, hold_until
          FROM (SELECT h.*, row_number() OVER (PARTITION BY builder_id ORDER BY last_seen_at DESC) AS rn
                  FROM autonomy_runner_heartbeat h) t
         WHERE rn <= 20
@@ -302,11 +302,18 @@ async function readAllRunnerScopes() {
 // recordRunnerHeartbeat — upsert one host's check-in. ON CONFLICT so the normal
 // case is one write, and `host` is the key so a second runner appears as a second
 // row rather than silently overwriting the first.
-async function recordRunnerHeartbeat({ builderId, host, pid = null, startedAt = null, mode = null, consecutiveFailures = null, lastEvent = null, workingTaskId = null, workingGoalId = null, head = null, diskHead = null, mainHead = null, claudeAccount = null }) {
+//
+// THE DEVICE'S RUN SWITCH IS NEVER WRITTEN FROM HERE (task 1005094), with one
+// exception that is not a write of anyone's choice: `startStopped` decides the
+// value a BRAND-NEW row is born with. A device added through the new setup checks
+// in under its own login and starts stopped, so the first press of Run is the
+// person's; an existing row keeps whatever its builder last chose. The conflict
+// arm does not name run_requested at all, so no check-in can ever move it.
+async function recordRunnerHeartbeat({ builderId, host, pid = null, startedAt = null, mode = null, consecutiveFailures = null, lastEvent = null, workingTaskId = null, workingGoalId = null, head = null, diskHead = null, mainHead = null, claudeAccount = null, holdUntil = null, sessionId = null, startStopped = false }) {
   const { rows } = await pool.query(
     `INSERT INTO autonomy_runner_heartbeat
-       (builder_id, host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id, head, disk_head, main_head, claude_account, last_seen_at, updated_at)
-     VALUES ($8, $1, $2, $3, $4, $5, $6, $7, $9, $10, $11, $12, $13, now(), now())
+       (builder_id, host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id, head, disk_head, main_head, claude_account, hold_until, session_id, run_requested, last_seen_at, updated_at)
+     VALUES ($8, $1, $2, $3, $4, $5, $6, $7, $9, $10, $11, $12, $13, $14, $15, $16, now(), now())
      ON CONFLICT (builder_id, host) DO UPDATE SET
        pid = EXCLUDED.pid,
        started_at = COALESCE(EXCLUDED.started_at, autonomy_runner_heartbeat.started_at),
@@ -321,10 +328,15 @@ async function recordRunnerHeartbeat({ builderId, host, pid = null, startedAt =
        disk_head = EXCLUDED.disk_head,
        main_head = EXCLUDED.main_head,
        claude_account = EXCLUDED.claude_account,
+       -- Overwritten too: a runner that has stopped resting must stop saying so,
+       -- and a device moved back to its builder's CLI session has no login of
+       -- its own for Remove to revoke.
+       hold_until = EXCLUDED.hold_until,
+       session_id = EXCLUDED.session_id,
        last_seen_at = now(),
        updated_at = now()
-     RETURNING host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id, head, disk_head, main_head, claude_account, last_seen_at`,
-    [String(host).toLowerCase().slice(0, 255), pid, startedAt, mode, consecutiveFailures, lastEvent, workingTaskId, builderId, workingGoalId, head, diskHead, mainHead, claudeAccount]
+     RETURNING host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id, head, disk_head, main_head, claude_account, hold_until, run_requested, last_seen_at`,
+    [String(host).toLowerCase().slice(0, 255), pid, startedAt, mode, consecutiveFailures, lastEvent, workingTaskId, builderId, workingGoalId, head, diskHead, mainHead, claudeAccount, holdUntil, sessionId, startStopped !== true]
   );
   return rows[0] || null;
 }
@@ -340,7 +352,8 @@ async function recordRunnerHeartbeat({ builderId, host, pid = null, startedAt =
 async function readRunnerHeartbeats(builderId) {
   const { rows } = await pool.query(
     `SELECT host, pid, started_at, mode, consecutive_failures, last_event, working_task_id, working_goal_id,
-            head, disk_head, main_head, claude_account, last_seen_at
+            head, disk_head, main_head, claude_account, last_seen_at,
+            run_requested, run_changed_at, hold_until, session_id
        FROM autonomy_runner_heartbeat
       WHERE builder_id = $1
       ORDER BY last_seen_at DESC
@@ -351,9 +364,71 @@ async function readRunnerHeartbeats(builderId) {
     ...r,
     working_task_id: r.working_task_id ? String(r.working_task_id) : null,
     working_goal_id: r.working_goal_id ? String(r.working_goal_id) : null,
+    // The caller's OWN session id (a bigint, so a string): what "Remove this
+    // device" hands to the own-session revoke. Null when the runner has no login
+    // of its own.
+    session_id: r.session_id ? String(r.session_id) : null,
   }));
 }
 
+// ── each device's Run switch (task 1005094) ──────────────────────────────────
+
+const deviceHost = (host) => String(host == null ? '' : host).toLowerCase().slice(0, 255);
+
+// readRunnerDevice — one device's switch, for the fence read. Null when that
+// device has never checked in, which the fence reads as "no device layer": a
+// runner's first act is a check-in, so a missing row is a caller that is not one.
+async function readRunnerDevice(builderId, host) {
+  const h = deviceHost(host);
+  if (!h) return null;
+  const { rows } = await pool.query(
+    'SELECT host, run_requested, run_changed_at FROM autonomy_runner_heartbeat WHERE builder_id = $1 AND host = $2',
+    [builderId, h]
+  );
+  return rows[0] || null;
+}
+
+// readRunnerDeviceBySession — the device a runner's OWN login checks in from.
+// The session id is the server's (it came off the request's session, never the
+// body or the query), so this is the one way to find a runner's device that the
+// runner cannot steer. Null when that login has not checked in yet.
+async function readRunnerDeviceBySession(builderId, sessionId) {
+  if (sessionId == null) return null;
+  const { rows } = await pool.query(
+    `SELECT host, run_requested, run_changed_at FROM autonomy_runner_heartbeat
+      WHERE builder_id = $1 AND session_id = $2
+      ORDER BY last_seen_at DESC LIMIT 1`,
+    [builderId, sessionId]
+  );
+  return rows[0] || null;
+}
+
+// setRunnerRun — the builder presses Run or Stop on ONE of their own devices.
+// Keyed by the caller's id, so nobody can reach another builder's device. Returns
+// null when there is no such device, so a typo is a 404 and never an orphan row.
+async function setRunnerRun({ builderId, host, run }) {
+  const { rows } = await pool.query(
+    `UPDATE autonomy_runner_heartbeat
+        SET run_requested = $3, run_changed_at = now(), updated_at = now()
+      WHERE builder_id = $1 AND host = $2
+      RETURNING host, run_requested, run_changed_at`,
+    [builderId, deviceHost(host), run === true]
+  );
+  return rows[0] || null;
+}
+
+// removeRunner — forget one of the caller's own devices. Returns the row's
+// session id (or null) so the caller can say whether it had a login of its own;
+// revoking that login is the core's own-session route, not this module's.
+async function removeRunner({ builderId, host }) {
+  const { rows } = await pool.query(
+    'DELETE FROM autonomy_runner_heartbeat WHERE builder_id = $1 AND host = $2 RETURNING host, session_id',
+    [builderId, deviceHost(host)]
+  );
+  const r = rows[0];
+  return r ? { host: r.host, session_id: r.session_id ? String(r.session_id) : null } : null;
+}
+
 module.exports = {
   recordAutonomyRun,
   lastAutonomyHead,
@@ -361,6 +436,10 @@ module.exports = {
   readRankRoster,
   recordRunnerHeartbeat,
   readRunnerHeartbeats,
+  readRunnerDevice,
+  readRunnerDeviceBySession,
+  setRunnerRun,
+  removeRunner,
   readFence,
   setFenceEnabled,
   allowGoal,

package/modules/autonomy/fence.js

@@ -55,10 +55,11 @@ const REFUSALS = {
   builder_paused: 'the owner paused your runner',
   no_builder_scope: 'you have not picked any goals for your runner — choose them in Settings',
   pin_move: 'the worker would be told to move a live core pin, and going live always waits for a person',
+  device_stopped: 'this device is stopped — press Run on its card in Settings',
 };
 
 // The stop codes effectiveFence may set, and the refusal each one becomes.
-const STOP_CODES = new Set(['kill_switch', 'not_permitted', 'builder_paused']);
+const STOP_CODES = new Set(['kill_switch', 'not_permitted', 'builder_paused', 'device_stopped']);
 
 // effectiveFence — the fence ONE builder's runner reads (task 1004501).
 //
@@ -79,7 +80,16 @@ const STOP_CODES = new Set(['kill_switch', 'not_permitted', 'builder_paused']);
 // ({ goals:[ids], owner_paused, owner_paused_reason, updated_at }) or null for a
 // builder with no row; `mayRun` is the autonomy.run answer, where anything but
 // `true` refuses. Returns null when the project fence is null (unreadable).
-function effectiveFence({ project, scope = null, mayRun = false } = {}) {
+//
+// THE DEVICE'S OWN SWITCH is the last layer (task 1005094, owner direction
+// 2026-11-09: one Run button per device). `device` is db.readRunnerDevice()'s row
+// for the host the runner named, or null — no host named (a runner that predates
+// this), or a device that has never checked in. Only an explicit
+// `run_requested === false` stops it, so a caller that names no device is exactly
+// as fenced as before. It comes last because it is the builder's own choice about
+// one machine: every stop above it is someone else's decision or the project's,
+// and the reason a runner reports should be the widest one that applies.
+function effectiveFence({ project, scope = null, mayRun = false, device = null } = {}) {
   if (!project || typeof project !== 'object') return null;
   const picks = new Set(((scope && scope.goals) || []).map(Number).filter((n) => Number.isSafeInteger(n) && n > 0));
   const projectGoals = Array.isArray(project.goals) ? project.goals : [];
@@ -96,11 +106,13 @@ function effectiveFence({ project, scope = null, mayRun = false } = {}) {
   } else if (enabled && scope && scope.owner_paused === true) {
     enabled = false; stopCode = 'builder_paused';
     pausedReason = scope.owner_paused_reason ? `${REFUSALS.builder_paused}: ${scope.owner_paused_reason}` : REFUSALS.builder_paused;
+  } else if (enabled && device && device.run_requested === false) {
+    enabled = false; stopCode = 'device_stopped'; pausedReason = REFUSALS.device_stopped;
   }
 
-  // The later of the two rows, so a pick or a pause wakes a runner that waits on
-  // the fence's updated_at exactly as a project change does.
-  const stamps = [project.updated_at, scope && scope.updated_at].filter(Boolean).map((t) => new Date(t).getTime()).filter(Number.isFinite);
+  // The latest of the rows, so a pick, a pause or a press of Run wakes a runner
+  // that waits on the fence's updated_at exactly as a project change does.
+  const stamps = [project.updated_at, scope && scope.updated_at, device && device.run_changed_at].filter(Boolean).map((t) => new Date(t).getTime()).filter(Number.isFinite);
   const updatedAt = stamps.length ? new Date(Math.max(...stamps)).toISOString() : (project.updated_at || null);
 
   return {
@@ -119,6 +131,9 @@ function effectiveFence({ project, scope = null, mayRun = false } = {}) {
       owner_paused: !!(scope && scope.owner_paused === true),
       owner_paused_reason: (scope && scope.owner_paused_reason) || null,
     },
+    // The device the runner named and where its switch stands, so the runner's
+    // log can say which machine a stop was about. Null when it named none.
+    device: device ? { host: device.host || null, run_requested: device.run_requested !== false } : null,
     // The unnarrowed project fence, for the owner's gate page.
     project,
   };

package/modules/autonomy/gauge.js

@@ -116,7 +116,12 @@ function reserveFor(nowEpochS, config = {}) {
 // decide identically and a caller that has to enumerate them will miss one.
 function readGauge(raw, nowEpochS, config = {}) {
   const c = cfg(config);
-  if (!raw || typeof raw !== 'object') return { known: false, reason: 'no gauge file — the statusline writer has never run' };
+  // `absent` marks the one shape that is not a bad reading but NO reading: this
+  // device has never had a gauge at all (see decideCapacity, task 1005095).
+  // Only NOTHING is absent. A file that is there but is not a gauge — torn, or
+  // not JSON — is a bad reading like any other, and must never read as "none".
+  if (raw === null || raw === undefined) return { known: false, absent: true, reason: 'no gauge file — the statusline writer has never run' };
+  if (typeof raw !== 'object') return { known: false, reason: 'the gauge file is there but cannot be read as a gauge' };
 
   const writtenAt = Number(raw.written_at);
   if (!Number.isFinite(writtenAt)) return { known: false, reason: 'gauge file has no readable written_at' };
@@ -239,6 +244,25 @@ function decideCapacity({ gauge, now, config = {} } = {}) {
   const c = cfg(config);
   const g = readGauge(gauge, now, c);
 
+  // A DEVICE WITH NO GAUGE AT ALL (task 1005095, owner direction 2026-11-09: the
+  // runner must run on any device from one button). The gauge's only writer is a
+  // terminal statusLine, so a laptop whose owner uses the desktop app, or a PC
+  // set up five minutes ago, has no file and never will — and "unknown, so hold"
+  // left such a runner armed, checking in and idle forever. The owner already
+  // ruled (2026-09-30, task 1004454) that running until the usage limit is hit
+  // and resuming at its reset is acceptable; a device with no gauge is that same
+  // bargain with nothing to read first. So when the CALLER asks for it
+  // (`absentMeansGo`, which only the supervisor passes), no file is a go, marked
+  // `absent` and `derived` so the log says which kind of go it was. Everything
+  // else that cannot be vouched for — malformed, future-dated, aged out inside a
+  // window still running — is still UNKNOWN, and the default is unchanged: the
+  // gauge CLI and any other caller never default to go.
+  if (!g.known && g.absent && c.absentMeansGo === true) {
+    return {
+      go: true, unknown: false, sleepUntil: null, absent: true, derived: true, derivedSince: null,
+      reason: 'no usage gauge on this device — working until the usage limit says stop, then waiting for its reset',
+    };
+  }
   if (!g.known) return { go: false, unknown: true, sleepUntil: null, reason: g.reason };
 
   if (g.sevenDay) {

package/modules/autonomy/migrations/autonomy_006_runner_device.sql

@@ -0,0 +1,45 @@
+-- autonomy_006_runner_device.sql — each device's own Run switch, and what its
+-- button says while it waits (task 1005094, goal 1000139).
+--
+-- Owner direction, 2026-11-09: running the runner on a device is ONE button on
+-- that device's card, and any cooldown is shown on the button itself. Until now
+-- a builder had no switch of their own at all: a set-up device ran whenever the
+-- project switch and their goal picks allowed it, on every device at once.
+--
+--   run_requested   the device's switch. The builder flips it from Settings; the
+--                   runner reads it as part of its fence (GET /autonomy/fence
+--                   ?host=) and cannot write it — the routes that change it
+--                   refuse a runner's own login, so a worker can never press Run
+--                   for itself after its builder pressed Stop.
+--                   DEFAULT true ON PURPOSE: every runner that already exists
+--                   keeps working when this lands. A device added through the
+--                   new setup is written false by its first check-in (the route
+--                   does that, for a runner's own login only), so the first
+--                   press of Run is the person's.
+--   run_changed_at  when the switch last moved. It feeds the fence's updated_at,
+--                   which a waiting runner polls, so a press reaches the device
+--                   in under a minute instead of at its next idle wake; the hall
+--                   compares it with last_seen_at to show "Starting".
+--   hold_until      when a resting runner will resume: the reset time of the
+--                   usage limit or capacity hold it is sleeping to, as the runner
+--                   itself reports it. Null when it is not resting. The button
+--                   shows this time; it decides nothing.
+--   session_id      the runner's OWN login (builder_sessions.id), recorded from
+--                   the session that checked in — never from the body — when
+--                   that session is a runner's. "Remove this device" revokes
+--                   exactly that login. Null for a runner still on its builder's
+--                   CLI session, which Remove must not revoke.
+--
+-- No foreign key on session_id: a revoked session's row may be swept, and a
+-- check-in row that outlives it must simply read as "no login of its own".
+-- Additive and idempotent.
+
+BEGIN;
+
+ALTER TABLE autonomy_runner_heartbeat
+  ADD COLUMN IF NOT EXISTS run_requested boolean NOT NULL DEFAULT true,
+  ADD COLUMN IF NOT EXISTS run_changed_at timestamptz,
+  ADD COLUMN IF NOT EXISTS hold_until timestamptz,
+  ADD COLUMN IF NOT EXISTS session_id bigint;
+
+COMMIT;

package/modules/autonomy/module.json

@@ -9,7 +9,8 @@
   "maintenance": { "status": "core-maintained" },
   "contributes": {
     "routes": ["autonomy"],
-    "pollers": ["routine-timers", "daily-checks"]
+    "pollers": ["routine-timers", "daily-checks"],
+    "skills": ["autobongos-setup"]
   },
   "provides": [],
   "consumes": []

package/modules/autonomy/routes/autonomy.js

@@ -18,6 +18,8 @@
 // may not do. This route is a thin wrapper over its `precheck`.
 
 const express = require('express');
+const fs = require('node:fs');
+const path = require('node:path');
 // The published doorway — requireBuilder / requireRank live on the doorway surface
 // (a module never reaches into core auth directly; the one-way boundary, ADR 0083).
 const api = require('../../../src/module-api');
@@ -102,6 +104,40 @@ function commitOrNull(v) {
   return typeof v === 'string' && /^[0-9a-f]{40}$/.test(v) ? v : null;
 }
 
+// holdUntilOrNull — the time a resting runner says it resumes (task 1005094), as a
+// Date, or null. The runner sends epoch SECONDS. Kept only inside a window a real
+// rest can fall in: a usage window is at most seven days, so anything further out,
+// or more than a day in the past, is a clock or a bug and is dropped rather than
+// printed on a button.
+function holdUntilOrNull(v, nowMs = Date.now()) {
+  if (typeof v !== 'number' || !Number.isFinite(v)) return null;
+  const ms = v * 1000;
+  if (ms < nowMs - 24 * 3600 * 1000 || ms > nowMs + 8 * 24 * 3600 * 1000) return null;
+  return new Date(ms);
+}
+
+// A device name as a path or query value: what os.hostname() can be, and no more.
+// The row key is the lowercased name, so that is what is returned.
+function hostOrNull(v) {
+  if (typeof v !== 'string') return null;
+  const h = v.trim().toLowerCase();
+  return h && h.length <= 255 && /^[a-z0-9._ -]+$/.test(h) ? h : null;
+}
+
+// The two first lines of setup (task 1005095), served as text. They live under
+// scripts/ with the rest of the runner's device program; this module only hands
+// them out, read once per process.
+const BOOTSTRAP_DIR = path.join(__dirname, '..', '..', '..', 'scripts', 'bongos');
+const bootstrapCache = new Map();
+function bootstrapScript(name) {
+  if (!bootstrapCache.has(name)) {
+    let text = null;
+    try { text = fs.readFileSync(path.join(BOOTSTRAP_DIR, name), 'utf8'); } catch (_) { text = null; }
+    bootstrapCache.set(name, text);
+  }
+  return bootstrapCache.get(name);
+}
+
 // The governor's docket (task 1004523): the fence + the money reading,
 // contributed from this factory (see ../governor-docket.js).
 const governorDocket = require('../governor-docket');
@@ -182,17 +218,50 @@ module.exports = function buildAutonomyRouter() {
   // narrowed to their own picks (fence.js effectiveFence). Computing it here keeps
   // the runner dumb and means a runner that predates this change is narrowed too.
   // The unnarrowed project fence rides along as `project` for the owner's page.
+  //
+  // AND THE CALLER'S DEVICE (task 1005094). A runner names the machine it is on
+  // (?host=), and that device's own Run switch is the last layer: stopped there,
+  // the answer is enabled:false / stop_code device_stopped, whatever every other
+  // layer says. A caller that names no host — a runner that predates this, the
+  // Settings page — gets no device layer and is exactly as fenced as before. A
+  // host that will not parse is treated as not named, never as an error: the one
+  // thing this read must not do is fail a runner into "unreadable" over a name.
+  //
+  // ONE MORE READ, knowingly. holdsPermission above was written so that this
+  // route, which every runner asks on every iteration and every waiting poll,
+  // adds no query for the permission. The device layer does add one: a single
+  // row by primary key (builder, host), or by (builder, session) for a runner
+  // login, run beside the other reads rather than after them. It is paid only by
+  // a caller that names a device or is a runner login; the Settings page and a
+  // runner that predates this pay nothing new.
+  //
+  // A RUNNER'S OWN LOGIN DOES NOT GET TO CHOOSE. For such a session the device is
+  // the one that login checks in from, found by the session id the server holds;
+  // the name it sends is not consulted. Otherwise a runner whose builder pressed
+  // Stop could read its fence without a name, or under another device's, and be
+  // told to carry on. And a runner login with no check-in yet reads as STOPPED:
+  // its row will be born stopped anyway, and a login that has not said which
+  // device it is must not be answered as if it had none.
   router.get('/autonomy/fence', auth.requireBuilder, async (req, res) => {
     try {
-      const [project, scope, mayRun] = await Promise.all([
-        db.readFence(), db.readBuilderScope(req.builder.id), holdsPermission(req, 'autonomy.run'),
+      const host = hostOrNull(req.query && req.query.host);
+      const runnerLogin = req.builder.runner === true;
+      const sessionId = req.gdsSession && req.gdsSession.session_id != null ? req.gdsSession.session_id : null;
+      const readDevice = async () => {
+        if (runnerLogin) {
+          return (await db.readRunnerDeviceBySession(req.builder.id, sessionId)) || { host, run_requested: false, run_changed_at: null };
+        }
+        return host ? db.readRunnerDevice(req.builder.id, host) : null;
+      };
+      const [project, scope, mayRun, device] = await Promise.all([
+        db.readFence(), db.readBuilderScope(req.builder.id), holdsPermission(req, 'autonomy.run'), readDevice(),
       ]);
       // Null means the singleton row is missing, i.e. the migration has not run.
       // Say so rather than synthesising a default: a fabricated { enabled: false }
       // is indistinguishable from a real one, and an operator would chase a kill
       // switch nobody threw.
       if (!project) return res.fail('fence_uninitialised', { status: 503, message: 'the autonomy fence row is missing — run the module migrations' });
-      res.json(fence.effectiveFence({ project, scope, mayRun }));
+      res.json(fence.effectiveFence({ project, scope, mayRun, device }));
     } catch (err) {
       log.error('[gds] GET /autonomy/fence', err);
       // FAIL CLOSED, unlike the precheck above. That one is fail-open because an
@@ -378,8 +447,14 @@ module.exports = function buildAutonomyRouter() {
       disk_head: { type: 'string', maxLength: 40 },
       main_head: { type: 'string', maxLength: 40 },
       claude_account: { type: 'string', maxLength: 200 },
+      // When a resting runner resumes, in epoch seconds (task 1005094).
+      hold_until: { type: 'number' },
     })) return;
     const b = req.body || {};
+    // The runner's OWN login, when that is what checked in (task 1005094). From
+    // the session, never the body: it is what "Remove this device" revokes, and a
+    // caller must not be able to point that at a session of their choosing.
+    const ownLogin = req.builder.runner === true && req.gdsSession && req.gdsSession.session_id != null;
     try {
       const row = await db.recordRunnerHeartbeat({
         // From the SESSION, never the body. A caller cannot name someone else's
@@ -399,6 +474,11 @@ module.exports = function buildAutonomyRouter() {
         diskHead: commitOrNull(b.disk_head),
         mainHead: commitOrNull(b.main_head),
         claudeAccount: typeof b.claude_account === 'string' && b.claude_account.trim() ? b.claude_account.trim() : null,
+        holdUntil: holdUntilOrNull(b.hold_until),
+        sessionId: ownLogin ? req.gdsSession.session_id : null,
+        // A device set up the new way starts STOPPED, so the first press of Run is
+        // the person's. Only ever the birth value of a new row (db.js).
+        startStopped: ownLogin,
       });
       res.json({ ok: true, heartbeat: row });
       // AFTER the answer, and never awaited by it: a notice that cannot be posted
@@ -441,5 +521,87 @@ module.exports = function buildAutonomyRouter() {
     }
   });
 
+  // ── each device's Run button (task 1005094) ────────────────────────────────
+  //
+  // Owner direction, 2026-11-09: running the runner on a device is ONE button on
+  // that device's card. These two routes are that button and its Remove.
+  //
+  // NEITHER ANSWERS A RUNNER'S OWN LOGIN. A worker holds that login and runs with
+  // blanket permissions; if it could reach these, a runner whose builder pressed
+  // Stop could press Run for itself, or delete its own row and be born again. So
+  // both refuse `req.builder.runner` before anything is read. The builder's own
+  // browser or CLI session is the only thing that moves the switch.
+  const refuseRunnerLogin = (req, res) => {
+    if (req.builder && req.builder.runner === true) {
+      res.fail('runner_session', { status: 403, message: 'A runner cannot start, stop or remove itself. Use its card in Settings, signed in as yourself.' });
+      return true;
+    }
+    return false;
+  };
+
+  // Run or Stop ONE of the caller's own devices. Behind `autonomy.run`, like the
+  // goal picks: a builder who may not run a runner has nothing to start. Stopping
+  // is allowed to the same people and no wider — it is their own machine.
+  router.post('/autonomy/runners/:host/run', auth.requireBuilder, auth.requirePermission('autonomy.run'), async (req, res) => {
+    if (refuseRunnerLogin(req, res)) return;
+    if (validateOrRespond(req, res, { run: { required: true, type: 'boolean' } })) return;
+    const host = hostOrNull(req.params.host);
+    if (!host) return res.fail('bad_host', { status: 400, message: 'that is not a device name' });
+    try {
+      const row = await db.setRunnerRun({ builderId: req.builder.id, host, run: req.body.run });
+      if (!row) return res.fail('device_not_found', { status: 404, message: 'You have no device by that name. It appears once its runner has checked in.' });
+      log.info(`[gds] autonomy: builder ${req.builder.id} pressed ${req.body.run ? 'RUN' : 'STOP'} on device ${host}`);
+      res.json({ host: row.host, run_requested: row.run_requested, run_changed_at: row.run_changed_at });
+    } catch (err) {
+      log.error('[gds] POST /autonomy/runners/:host/run', err);
+      res.fail('run_write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Forget one of the caller's own devices. ANY-BUILDER, deliberately wider than
+  // Run: a builder who has since lost `autonomy.run` must still be able to clear
+  // their own device off their own page, and the row is keyed by the caller, so
+  // the only thing reachable is theirs. It does not revoke the device's login —
+  // that is the core's own-session route (POST /me/sessions/revoke), which the
+  // Settings page calls first with the `session_id` GET /autonomy/runners gave it.
+  // `had_own_login` says whether there was one to revoke.
+  router.delete('/autonomy/runners/:host', auth.requireBuilder, async (req, res) => {
+    if (refuseRunnerLogin(req, res)) return;
+    const host = hostOrNull(req.params.host);
+    if (!host) return res.fail('bad_host', { status: 400, message: 'that is not a device name' });
+    try {
+      const out = await db.removeRunner({ builderId: req.builder.id, host });
+      if (!out) return res.fail('device_not_found', { status: 404, message: 'You have no device by that name.' });
+      log.info(`[gds] autonomy: builder ${req.builder.id} removed device ${host}`);
+      res.json({ removed: true, host: out.host, had_own_login: !!out.session_id });
+    } catch (err) {
+      log.error('[gds] DELETE /autonomy/runners/:host', err);
+      res.fail('remove_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // The first lines of setup, one per platform (task 1005095). The command the
+  // Settings page shows fetches one of these and runs it with the one-time code.
+  //
+  // Not left open-ended: like every read with no limiter of its own they sit under
+  // the server's default per-address read ceiling, and each answer is a string
+  // already in memory (read once per process), so a flood costs no disk and no
+  // database.
+  //
+  // rank: public — a clean device has no login yet, which is the point of setup.
+  // The files hold no secret: they are the same text as scripts/bongos/ in the
+  // repository, they take the code, the project address and the repository as
+  // arguments, and nothing about this instance is written into them.
+  const sendBootstrap = (file, type) => (req, res) => {
+    const text = bootstrapScript(file);
+    if (!text) return res.fail('setup_script_missing', { status: 503, message: 'this instance cannot serve the runner setup script' });
+    res.set('Cache-Control', 'no-store');
+    res.type(type).send(text);
+  };
+  // rank: public — the Windows first lines; see the note above.
+  router.get('/autonomy/runner-setup.ps1', sendBootstrap('autobongos-bootstrap.ps1', 'text/plain; charset=utf-8'));
+  // rank: public — the Mac first lines; see the note above.
+  router.get('/autonomy/runner-setup.sh', sendBootstrap('autobongos-bootstrap.sh', 'text/x-shellscript; charset=utf-8'));
+
   return router;
 };

package/modules/autonomy/runner-health.js

@@ -30,6 +30,16 @@
 //     it carries the fix as `remedy`. The runner decides the grace and says
 //     `config_idle:<code>` on its heartbeat; only a code config-idle.js knows is
 //     honoured, so the owner's kill switch and pause can never read as an alarm.
+//   · stopped — alive, and its builder pressed Stop on this device (task
+//     1005094). Not an alarm and not "running": the device is doing what it was
+//     told, and its card shows Run. Only a runner that is still checking in can
+//     be stopped; a silent one is late or dead first, because a device nobody
+//     has heard from cannot vouch for anything, its switch included.
+//
+// Every state also carries `runRequested` (the device's switch, true unless its
+// builder turned it off) and `holdUntil` (when a resting runner resumes, as the
+// runner reported it — only while that time is still ahead), so the Run button
+// can show Stop, Starting or a rest time without a second read.
 
 // Reasoned from the runner's own numbers, not picked. The loop beats at the top of
 // every pass and again on each poll inside a wait (every 60s), so a healthy runner
@@ -118,10 +128,17 @@ function describeRunner(heartbeat, { nowMs = Date.now(), aliveS = ALIVE_S, lateS
   const mode = heartbeat.mode === 'probing' ? 'probing' : (heartbeat.mode === 'full' ? 'full' : null);
   const working = heartbeat.working_task_id ? String(heartbeat.working_task_id) : null;
   const where = host ? ` on ${host}` : '';
+  const runRequested = heartbeat.run_requested !== false;
+  // A rest the runner named, kept only while it is still ahead: a time already
+  // past is a runner that has resumed, or one that has gone quiet, and either
+  // way it is no longer what the button should say.
+  const holdMs = heartbeat.hold_until ? Date.parse(heartbeat.hold_until instanceof Date ? heartbeat.hold_until.toISOString() : heartbeat.hold_until) : NaN;
   const ident = {
     host, mode, workingTaskId: working,
     account: typeof heartbeat.claude_account === 'string' && heartbeat.claude_account ? heartbeat.claude_account : null,
     code: describeCode(heartbeat),
+    runRequested,
+    holdUntil: Number.isFinite(holdMs) && holdMs > nowMs ? new Date(holdMs).toISOString() : null,
   };
 
   if (heartbeat.last_event === 'upgrade_exit') {
@@ -149,6 +166,16 @@ function describeRunner(heartbeat, { nowMs = Date.now(), aliveS = ALIVE_S, lateS
     };
   }
 
+  // Stopped on this device by its builder, and not mid-task: the card shows Run.
+  // A runner still building when Stop was pressed finishes that task first, and
+  // reads as the working runner it is until then.
+  if (!runRequested && !working && age <= aliveS) {
+    return {
+      state: 'stopped', ok: true, ageS: age, age: humanAge(age), ...ident,
+      detail: `stopped${where} — press Run on its card to start it`,
+    };
+  }
+
   if (age <= aliveS) {
     // A setting still inside its grace reads as the fence wait it is, not "running".
     const doing = ACTIVITY[heartbeat.last_event] || (configIdle.pendingCode(heartbeat.last_event) ? ACTIVITY.fenced : null);