@bongos/core 1.24.77 → 1.24.78

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). |