@bongos/core 1.24.76 → 1.24.78

package/docs/adr/0307-autobongos-a-deterministic-supervisor-and-agentic-workers.md

@@ -112,6 +112,36 @@ match the **exact worktree name the runner generates**, not an `autobongos-`
 prefix: the loose form matched a human's hand-named tree and released their live
 claim out from under them, twice, during the task that added it.
 
+**Any device, not one always-on PC** (task 1005095, goal 1000139; owner direction
+2026-11-09). The host above was written for a single Windows box: a scheduled task
+registered from an Administrator shell, started at boot. The owner's rule is now
+that the runner runs on any device, Windows or Mac, always-on or a laptop, from one
+button. Four decisions carry that, in `scripts/bongos/autobongos-host.js`:
+
+- **It starts at sign-in, as the person, with no administrator.** A per-user Run
+  entry on Windows and a per-user launchd agent on a Mac. Boot-time start needs an
+  elevated registration on Windows and cannot reach the login keychain on a Mac,
+  where the Claude sign-in lives; sign-in start needs neither. A laptop that
+  sleeps stops checking in and resumes when it wakes, and the hall already reads
+  silence as silence. The boot-time task stays as the opt-in for an always-on PC.
+- **One Node program replaces the `.cmd` wrapper on this path**, so Windows and
+  Mac cannot drift: refresh the runner's copy, launch the supervisor, relaunch on
+  its upgrade exit, restart after a crash with a growing wait. Stop and uninstall
+  watch the processes exit before saying so.
+- **The runner keeps its own files** (`BONGOS_CONFIG_ROOT`, passed on to every
+  worker). A runner's own login in the builder's one session slot would sign the
+  builder's own tools out; a root of its own also means the runner can never fall
+  back to the builder's session.
+- **A device with no gauge at all works until the usage limit** (`absentMeansGo`,
+  passed only by the supervisor). §2's writer is a terminal statusLine, so a
+  device whose owner uses the desktop app never has a reading, and "unknown, so
+  hold" left it armed and idle forever. This is the 2026-09-30 ruling — hit the
+  limit, wait for its reset, resume — with nothing to read first. A reading that
+  exists and cannot be vouched for still holds.
+
+The program hard-resets its checkout on every start, so it refuses to run anywhere
+but a copy the setup marked as the runner's own.
+
 ### 6. The fence, and where it is enforced
 
 The allowlist of goals lives in the database and is edited from the hall, never
@@ -171,6 +201,21 @@ core moves are out of its reach, and the project-owner door to a core move is sh
 it. Removing the PC is the ordinary own-session revoke. The worktree-name check is
 kept for runners not yet moved to their own login.
 
+**Each device has its own Run switch** (task 1005094, goal 1000139; owner direction
+2026-11-09: running the runner on a device is one button, and any cooldown is on
+the button). Under the builder's goal picks sits one more layer, per device:
+`autonomy_runner_heartbeat.run_requested`. The runner names its device on the fence
+read it already makes (`?host=`) and the server folds the switch in as the last
+reason to stop (`device_stopped`), so the runner still decides nothing. It is last
+because it is the builder's own choice about one machine; every stop above it is
+someone else's, and a runner should report the widest reason that applies. Three
+properties keep it a brake the device cannot release: the two routes that move it
+refuse a runner's own login, a check-in can only set the value a new row is born
+with, and a device added through the new setup is born stopped, so the first press
+is a person's. The column defaults to on, so a runner that predates it is unchanged.
+The runner also reports when a rest ends (`hold_until`), which is only ever shown,
+on the button; it decides nothing on the server.
+
 ### 7. Workers run with blanket `bypassPermissions`
 
 `--permission-prompt-tool` exists and is print-mode only, so routing every

package/docs/api/openapi.json

@@ -2622,7 +2622,7 @@
           "autonomy"
         ],
         "summary": "GET /autonomy/fence",
-        "description": "The runner's own read, every iteration. ANY-BUILDER on purpose: learning that you must stop should never require an elevated session, because the failure mode of \"could not read the fence\" is a machine that keeps going. The body carries no secret — it is a boolean, a reason string and a list of goal ids. THE CALLER'S fence, not the project's (task 1004501). The top-level `enabled` and `goals` are what THIS builder's runner may do: the project switch, then `autonomy.run`, then the owner's pause on this builder, and the allowlist 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.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "The runner's own read, every iteration. ANY-BUILDER on purpose: learning that you must stop should never require an elevated session, because the failure mode of \"could not read the fence\" is a machine that keeps going. The body carries no secret — it is a boolean, a reason string and a list of goal ids. THE CALLER'S fence, not the project's (task 1004501). The top-level `enabled` and `goals` are what THIS builder's runner may do: the project switch, then `autonomy.run`, then the owner's pause on this builder, and the allowlist 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.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/autonomy/routes/autonomy.js",
         "responses": {
@@ -2969,6 +2969,48 @@
         ]
       }
     },
+    "/autonomy/runner-setup.ps1": {
+      "get": {
+        "operationId": "get_autonomy_runner_setup_ps1",
+        "tags": [
+          "autonomy"
+        ],
+        "summary": "GET /autonomy/runner-setup.ps1",
+        "description": "the Windows first lines; see the note above.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/autonomy/routes/autonomy.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
+    "/autonomy/runner-setup.sh": {
+      "get": {
+        "operationId": "get_autonomy_runner_setup_sh",
+        "tags": [
+          "autonomy"
+        ],
+        "summary": "GET /autonomy/runner-setup.sh",
+        "description": "the Mac first lines; see the note above.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/autonomy/routes/autonomy.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
     "/autonomy/runners": {
       "get": {
         "operationId": "get_autonomy_runners",
@@ -3048,6 +3090,124 @@
         ]
       }
     },
+    "/autonomy/runners/{host}": {
+      "delete": {
+        "operationId": "delete_autonomy_runners_host",
+        "tags": [
+          "autonomy"
+        ],
+        "summary": "DELETE /autonomy/runners/:host",
+        "description": "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.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/autonomy/routes/autonomy.js",
+        "parameters": [
+          {
+            "name": "host",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `host`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeleteAutonomyRunnersHostResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/autonomy/runners/{host}/run": {
+      "post": {
+        "operationId": "post_autonomy_runners_host_run",
+        "tags": [
+          "autonomy"
+        ],
+        "summary": "POST /autonomy/runners/:host/run",
+        "description": "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.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `autonomy.run` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/autonomy/routes/autonomy.js",
+        "x-permissions": [
+          "autonomy.run"
+        ],
+        "parameters": [
+          {
+            "name": "host",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `host`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostAutonomyRunnersHostRunRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostAutonomyRunnersHostRunResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/autonomy/runs": {
       "get": {
         "operationId": "get_autonomy_runs",
@@ -31946,6 +32106,23 @@
           "removed"
         ]
       },
+      "DeleteAutonomyRunnersHostResponse": {
+        "type": "object",
+        "properties": {
+          "removed": {
+            "type": "boolean"
+          },
+          "host": {},
+          "had_own_login": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "removed",
+          "host",
+          "had_own_login"
+        ]
+      },
       "DeleteBlockersIdLinkTaskIdResponse": {
         "type": "object",
         "properties": {
@@ -36408,6 +36585,9 @@
           "claude_account": {
             "type": "string",
             "maxLength": 200
+          },
+          "hold_until": {
+            "type": "number"
           }
         },
         "required": [
@@ -36428,6 +36608,31 @@
           "heartbeat"
         ]
       },
+      "PostAutonomyRunnersHostRunRequest": {
+        "type": "object",
+        "properties": {
+          "run": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "run"
+        ],
+        "additionalProperties": false
+      },
+      "PostAutonomyRunnersHostRunResponse": {
+        "type": "object",
+        "properties": {
+          "host": {},
+          "run_requested": {},
+          "run_changed_at": {}
+        },
+        "required": [
+          "host",
+          "run_requested",
+          "run_changed_at"
+        ]
+      },
       "PostBackupTriggerResponse": {
         "type": "object",
         "properties": {
@@ -43060,9 +43265,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 686,
-  "x-schema-count": 723,
+  "x-endpoint-count": 690,
+  "x-schema-count": 726,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 459,
+  "x-response-schemas": 461,
   "x-generated-by": "scripts/bongos/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 686 endpoints across 117 route files.
+> **Generated from the live route files** — the route file is authoritative. 690 endpoints across 117 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -106,7 +106,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/auth/web/handoff` | `public` | — | GET /auth/web/handoff?code=&return= — the far side of the one-time session handoff (task 1004357). |
 | GET | `/api/bongos/auth/web/start` | `public` | — | /auth/web — browser flow (used by the /builders page). |
 
-## `autonomy` (12)
+## `autonomy` (16)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -116,10 +116,14 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/autonomy/fence/goals` | `archon` | `goal_id`, `note` | Add a goal to the allowlist. |
 | DELETE | `/api/bongos/autonomy/fence/goals/:goalId` | `archon` | — | Revoke one. |
 | POST | `/api/bongos/autonomy/fence/priority` | `archon` | `goal_id` | The priority goal (task 1004453): which allowlisted goal the runner works first. |
-| POST | `/api/bongos/autonomy/heartbeat` | `any-builder` | `host`, `pid`, `started_at`, `mode`, `consecutive_failures`, `last_event`, `working_task_id`, `working_goal_id`, `head`, `disk_head`, `main_head`, `claude_account` | The runner's check-in, once per loop. |
+| POST | `/api/bongos/autonomy/heartbeat` | `any-builder` | `host`, `pid`, `started_at`, `mode`, `consecutive_failures`, `last_event`, `working_task_id`, `working_goal_id`, `head`, `disk_head`, `main_head`, `claude_account`, `hold_until` | The runner's check-in, once per loop. |
 | PUT | `/api/bongos/autonomy/me/goals` | `metic+archon` | `goal_ids` | A builder picks which allowlisted goals THEIR runner works. |
 | GET | `/api/bongos/autonomy/precheck` | `metic+archon` | — |  |
+| GET | `/api/bongos/autonomy/runner-setup.ps1` | `public` | — | the Windows first lines; see the note above. |
+| GET | `/api/bongos/autonomy/runner-setup.sh` | `public` | — | the Mac first lines; see the note above. |
 | GET | `/api/bongos/autonomy/runners` | `any-builder` | — | What the hall renders: the CALLER'S OWN runners, with the pure verdict attached so the page and any future alert cannot disagree about wh… |
+| DELETE | `/api/bongos/autonomy/runners/:host` | `any-builder` | — | Forget one of the caller's own devices. |
+| POST | `/api/bongos/autonomy/runners/:host/run` | `metic+archon` | `run` | Run or Stop ONE of the caller's own devices. |
 | GET | `/api/bongos/autonomy/runners/all` | `archon` | — | The owner's view of every builder's runners: who, which goals they picked, whether they are paused, and each runner's health — the server… |
 | GET | `/api/bongos/autonomy/runs` | `metic+archon` | — | The gate's past decisions — did a routine fire, and what did it decide, and why (task 1002669). |