@bongos/core 1.19.875 → 1.19.877

package/docs/api/openapi.json

@@ -1946,6 +1946,55 @@
         ]
       }
     },
+    "/autonomy/heartbeat": {
+      "post": {
+        "operationId": "post_autonomy_heartbeat",
+        "tags": [
+          "autonomy"
+        ],
+        "summary": "POST /autonomy/heartbeat",
+        "description": "The runner's check-in, once per loop. ANY-BUILDER is safe because the row is keyed by the CALLER: a stranger reporting \"winbox\" writes their own row and cannot touch the owner's, so the liveness signal cannot be forged into reading alive. Keeping the bar low matters — the failure mode of a refused heartbeat is a healthy runner reported dead.\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",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostAutonomyHeartbeatRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostAutonomyHeartbeatResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/autonomy/precheck": {
       "get": {
         "operationId": "get_autonomy_precheck",
@@ -1980,6 +2029,44 @@
         ]
       }
     },
+    "/autonomy/runners": {
+      "get": {
+        "operationId": "get_autonomy_runners",
+        "tags": [
+          "autonomy"
+        ],
+        "summary": "GET /autonomy/runners",
+        "description": "What the hall renders: the CALLER'S OWN runners, with the pure verdict attached so the page and any future alert cannot disagree about what \"dead\" means. A row names a machine, its hostname and a pid — the caller's infrastructure, and nobody else's business.\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": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetAutonomyRunnersResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/backup/status": {
       "get": {
         "operationId": "get_backup_status",
@@ -18634,6 +18721,17 @@
           "admitted"
         ]
       },
+      "GetAutonomyRunnersResponse": {
+        "type": "object",
+        "properties": {
+          "runners": {},
+          "none": {}
+        },
+        "required": [
+          "runners",
+          "none"
+        ]
+      },
       "GetBackupStatusResponse": {
         "type": "object",
         "properties": {
@@ -21381,6 +21479,54 @@
         ],
         "additionalProperties": false
       },
+      "PostAutonomyHeartbeatRequest": {
+        "type": "object",
+        "properties": {
+          "host": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255
+          },
+          "pid": {
+            "type": "number"
+          },
+          "started_at": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "mode": {
+            "type": "string",
+            "maxLength": 32
+          },
+          "consecutive_failures": {
+            "type": "number"
+          },
+          "last_event": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "working_task_id": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "host"
+        ],
+        "additionalProperties": false
+      },
+      "PostAutonomyHeartbeatResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "heartbeat": {}
+        },
+        "required": [
+          "ok",
+          "heartbeat"
+        ]
+      },
       "PostBackupTriggerResponse": {
         "type": "object",
         "properties": {
@@ -25211,9 +25357,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 398,
-  "x-schema-count": 436,
+  "x-endpoint-count": 400,
+  "x-schema-count": 439,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 298,
+  "x-response-schemas": 300,
   "x-generated-by": "scripts/gds/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. 398 endpoints across 64 route files.
+> **Generated from the live route files** — the route file is authoritative. 400 endpoints across 64 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`.
@@ -83,7 +83,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/auth/web/callback` | `public` | — | OAuth callback; the state cookie + code are the bearer. |
 | GET | `/api/bongos/auth/web/start` | `public` | — | /auth/web — browser flow (used by the /builders page). |
 
-## `autonomy` (5)
+## `autonomy` (7)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -91,7 +91,9 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/autonomy/fence` | `archon` | `enabled`, `reason` | The kill switch. |
 | 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/heartbeat` | `any-builder` | `host`, `pid`, `started_at`, `mode`, `consecutive_failures`, `last_event`, `working_task_id` | The runner's check-in, once per loop. |
 | GET | `/api/bongos/autonomy/precheck` | `metic+archon` | — |  |
+| 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… |
 
 ## `backup` (2)
 

package/docs/copy-inventory.md

@@ -4,13 +4,13 @@
 > Deterministic on a given tree — regenerate and commit rather than hand-editing.
 > Machine-readable twin: [`copy-registry.json`](copy-registry.json).
 
-**1912 strings** across 3 surfaces · 1656 distinct pieces of copy · 1912 certain, 0 heuristic · 175 shown in more than one place.
+**1913 strings** across 3 surfaces · 1657 distinct pieces of copy · 1913 certain, 0 heuristic · 175 shown in more than one place.
 
 ## Surfaces
 
 | surface | lives at | files | strings |
 |---|---|---|---|
-| `builders-hall` | `modules/hall-ui/public` | 89 | 1422 |
+| `builders-hall` | `modules/hall-ui/public` | 89 | 1423 |
 | `status-dashboard` | `modules/status-ui/public` | 4 | 100 |
 | `landing` | `modules/public-landing/public` | 5 | 390 |
 
@@ -78,7 +78,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `22825067f4c5` | 2x | 1 builder | modules/public-landing/public/index.html:747, modules/public-landing/public/index.html:752 |
 | … | | _135 more in the JSON registry_ | |
 
-## `builders-hall` — 1422 strings
+## `builders-hall` — 1423 strings
 
 | id | conf | text | where |
 |---|---|---|---|
@@ -248,7 +248,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `906c2947dfc1` | certain | Changes save at once and take effect the next time you start a session on this machine. | `modules/hall-ui/public/settings.html:409` |
 | `52384bdc035c` | certain | Changes save at once. Your new choice plays the next time that event fires. | `modules/hall-ui/public/settings.html:422` |
 | `cab7a9526ca1` | certain | Changes save the moment you pick. “Default” clears your override and falls back to the system's choice. | `modules/hall-ui/public/settings.html:392` |
-| `4b714191b423` | certain | Changes touching protected build surfaces, held for your approval. | `modules/hall-ui/public/gate.js:355` |
+| `4b714191b423` | certain | Changes touching protected build surfaces, held for your approval. | `modules/hall-ui/public/gate.js:403` |
 | `e6982a9ff948` | certain | Charter library | `modules/hall-ui/public/government.js:799` |
 | `f8725cf3ba62` | certain | Checking dependency order… | `modules/hall-ui/public/work.js:852` |
 | `7a41b18c0de8` | certain | Checking for conflicts… | `modules/hall-ui/public/work.js:831` |
@@ -435,7 +435,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `d59beed97d58` | certain | Drag to pan, scroll to zoom | `modules/hall-ui/public/diagrams.html:33` |
 | `67f09099c2d3` | certain | Duplicate — should be said once, in one place | `modules/hall-ui/public/copy-desk.html:93` |
 | `db7f370c0d38` | certain | Each builder’s dev box at a glance. | `modules/hall-ui/public/harbor.js:361` |
-| `77b7e3abfb07` | certain | Each one touched a protected surface and stopped at the gate check. Approving records your seal on that commit | `modules/hall-ui/public/gate.html:61` |
+| `77b7e3abfb07` | certain | Each one touched a protected surface and stopped at the gate check. Approving records your seal on that commit | `modules/hall-ui/public/gate.html:64` |
 | `0ddc87f11713` | certain | Each rank opens more of the system. You see full details for your current rank and the one directly above it;  | `modules/hall-ui/public/ranks.html:47` |
 | `7f1b1c32d360` | certain | Each slash-command can run on a different model. The system has a default for every skill; choose another to o | `modules/hall-ui/public/settings.html:378` |
 | `854a21d2eb39` | certain | Eight achievements recognize sustained contribution. Earned ones are highlighted; the rest show what’s left to | `modules/hall-ui/public/hall-widgets.js:197` |
@@ -523,7 +523,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `53eb8a07e0f8` | certain | Harbor — {{worldName}} | `modules/hall-ui/public/harbor.html:6` |
 | `53eb8a07e0f8` | certain | Harbor — {{worldName}} | `modules/hall-ui/public/harbor.html:6` |
 | `7cdddb5e2332` | certain | Held changes summary | `modules/hall-ui/public/gate.html:44` |
-| `adac4cd8b973` | certain | Held pull requests | `modules/hall-ui/public/gate.html:60` |
+| `adac4cd8b973` | certain | Held pull requests | `modules/hall-ui/public/gate.html:63` |
 | `ce8a068a34cf` | certain | Higher ranks only | `modules/hall-ui/public/sessions.html:40` |
 | `d9bd3b703fe4` | certain | Hover an island to light its links, click one for its details, or open it from the index below. | `modules/hall-ui/public/atlas.html:68` |
 | `6dd3c797943b` | certain | How Claude should engage you in it | `modules/hall-ui/public/settings.html:311` |
@@ -1308,6 +1308,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `c767b3e07826` | certain | is only the screen; the | `modules/hall-ui/public/diagrams.html:74` |
 | `d0e722302840` | certain | is published and this box is not on it yet. | `modules/hall-ui/public/deploy.js:108` |
 | `aa530bd15088` | certain | itself). The registry stays the single source of truth for what the hall shows; a fitness check (scripts/gds/f | `modules/hall-ui/public/index.html:53` |
+| `966b32c8af7e` | certain | last check-in {…} ago | `modules/hall-ui/public/gate.js:360` |
 | `9018bf6e99eb` | certain | last used {…} · signed in {…} | `modules/hall-ui/public/settings-sessions.js:46` |
 | `2ce7738b1eb0` | certain | loading goals… | `modules/hall-ui/public/task-detail.js:482` |
 | `754bdec368ed` | certain | lowest credits | `modules/hall-ui/public/hall-widgets.js:136` |

package/docs/copy-registry.json

@@ -3,9 +3,9 @@
   "generator": "scripts/gds/copy-inventory.js",
   "goal": 1000074,
   "counts": {
-    "strings": 1912,
-    "unique_ids": 1656,
-    "certain": 1912,
+    "strings": 1913,
+    "unique_ids": 1657,
+    "certain": 1913,
     "heuristic": 0,
     "duplicate_ids": 175
   },
@@ -13,7 +13,7 @@
     "builders-hall": {
       "at": "modules/hall-ui/public",
       "files": 89,
-      "strings": 1422
+      "strings": 1423
     },
     "status-dashboard": {
       "at": "modules/status-ui/public",
@@ -3370,7 +3370,7 @@
       "surface": "builders-hall",
       "text": "Changes touching protected build surfaces, held for your approval.",
       "file": "modules/hall-ui/public/gate.js",
-      "line": 355,
+      "line": 403,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -5053,7 +5053,7 @@
       "surface": "builders-hall",
       "text": "Each one touched a protected surface and stopped at the gate check. Approving records your seal on that commit and re-runs the check.",
       "file": "modules/hall-ui/public/gate.html",
-      "line": 61,
+      "line": 64,
       "origin": "html-text",
       "confidence": "certain"
     },
@@ -5845,7 +5845,7 @@
       "surface": "builders-hall",
       "text": "Held pull requests",
       "file": "modules/hall-ui/public/gate.html",
-      "line": 60,
+      "line": 63,
       "origin": "html-text",
       "confidence": "certain"
     },
@@ -12905,6 +12905,15 @@
       "origin": "html-text",
       "confidence": "certain"
     },
+    {
+      "id": "966b32c8af7e",
+      "surface": "builders-hall",
+      "text": "last check-in {…} ago",
+      "file": "modules/hall-ui/public/gate.js",
+      "line": 360,
+      "origin": "js-markup",
+      "confidence": "certain"
+    },
     {
       "id": "9018bf6e99eb",
       "surface": "builders-hall",

package/docs/module-api-changelog.md

@@ -2224,5 +2224,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.873 with no explicit bump. run 35419921833. (task 1002620)
   1.19.875 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.874 with no explicit bump. run 35420682750. (task 1002620)
+  1.19.876 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.875 with no explicit bump. run 35420916304. (task 1002620)
+  1.19.877 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.876 with no explicit bump. run 35438291185. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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

@@ -0,0 +1,138 @@
+# Setting up the Autobongos runner on the Windows PC
+
+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
+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.
+
+---
+
+## What you need on the box first
+
+Open PowerShell as your normal user (not Administrator) and check all three:
+
+```powershell
+node --version ; git --version ; claude --version
+```
+
+All three must print a version. The installer refuses to proceed otherwise —
+a runner that starts without `claude` on its PATH fails every worker and looks
+like a mysterious outage in the log rather than a missing program.
+
+You also need, as **your own user** (not an administrator account):
+
+- a `git` credential that can fetch the repo,
+- a signed-in Claude Code session,
+- a Bongos CLI session (`/builder-reauth` if it has expired).
+
+The runner deliberately runs as you, not as SYSTEM: SYSTEM has none of those
+credentials, and "as you" is also the smaller blast radius for a process that
+spawns workers with blanket permissions.
+
+## 1. Turn the runner on in the hall — *before* installing anything
+
+The kill switch and the goal allowlist live on the server, and both ship **off**.
+A runner installed before this step will start, find it is not allowed to do
+anything, and idle — which is correct, but looks like a broken install.
+
+1. Open **cloudbongos.com/builders/gate** (you must be the Archon).
+2. Under **Autobongos runner**, add the goal(s) it may work.
+3. Press **Start the runner**.
+
+Nothing on the PC can change either of those. That is the point: anything the
+machine can write, the worker running on it can write too.
+
+## 2. Install the scheduled task
+
+From the checkout:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 install
+powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 start
+```
+
+That registers a task called `Autobongos` that starts **at boot** (not at sign-in
+— nobody should have to log in), restarts if it crashes, and never times out.
+
+It is Task Scheduler rather than a real Windows service on purpose: node cannot
+speak the service protocol, so every "node as a service" route needs a
+third-party wrapper to download, verify and keep updated. Task Scheduler is
+already on the machine and does everything needed except appear in the Services
+panel.
+
+## 3. The acceptance test — do this, do not skip it
+
+**A cold reboot must bring the runner back with nobody at the keyboard.**
+
+1. Reboot the PC. Do **not** sign in.
+2. From any other device, open **cloudbongos.com/builders/gate**.
+3. Within a few minutes the runner line should read **Checking in**.
+
+If it does not, sign in on the box and run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 status
+```
+
+which prints the task state, the last result, and the tail of the log.
+
+## 4. Watching it from anywhere
+
+The **Gate** page is the remote view. It shows two separate things, and the
+difference matters:
+
+| Line | Means |
+|---|---|
+| **Checking in** | the process is alive and talking to the server |
+| **Quiet** | no check-in for a while — normal while a worker builds (they can take 90 minutes) |
+| **Not checking in** | nothing for longer than any worker takes: the runner is not running |
+| **Allowed to work** / **Stopped** | the kill switch — nothing to do with whether the process is up |
+
+A runner can be **Allowed to work** and **Not checking in** at the same time:
+that is a machine that is off, unplugged or wedged, and it is the state worth
+noticing.
+
+The full log lives on the box at `%LOCALAPPDATA%\cloudbongos\autobongos.log`.
+
+## 5. Stopping it
+
+Use the **kill switch in the hall**, not the scheduled task. The switch survives
+a reboot and cannot be undone by anything running on the machine; stopping the
+task only stops this run, and the next boot starts it again.
+
+`autobongos-service.ps1 stop` exists for maintenance on the box itself and says
+this when you use it.
+
+## Keeping the checkout current
+
+`autobongos-service.cmd` runs `git fetch` + `git reset --hard origin/main` before
+each start, on the **main checkout only** — worker trees are separate worktrees
+and are never touched. A fetch that fails does not stop the runner: being one
+commit behind beats not running at all.
+
+Because of that reset, **never leave uncommitted work in the runner's checkout.**
+It is the machine's working copy, not a place to edit.
+
+## If something looks wrong
+
+| Symptom | Where to look |
+|---|---|
+| Runner line says **Not checking in** | is the PC on? `...\autobongos-service.ps1 status` on the box |
+| **Checking in** but nothing ever ships | the Gate page — is a goal allowlisted, and is the switch on? |
+| Shipping stopped after a while | the log: the runner backs off after three failures and probes; the reason is in the log |
+| It keeps restarting | `status` shows the last result; the `====` banners in the log mark each start |
+
+The runner is built not to stop: three failures in a row drop it to a slow probe
+rather than an exit, and it returns to full speed on its own once the cause
+clears ([task 1003904](https://cloudbongos.com/builders#/task/1003904)). If the
+scheduled task's restart counter is climbing, something is wrong that the
+internal backoff should have absorbed — that is worth reading the log over.

package/docs/recipes/instance-deploy.md

@@ -15,11 +15,35 @@
 
 1. **`git pull --ff-only origin main`** the *instance* repo — host content only: `config/`, `migrations/instance/`, and the pinned core version in `package.json`.
 2. **`npm ci --omit=dev`** — installs the pinned `@bongos/core` + instance deps. This is what replaces `git reset --hard`: the core is a dependency, so an upgrade is a pin bump + `npm ci`, not a source merge.
-3. **`bash <core>/scripts/migrate.sh`** — the core's **three-root** migrate (W5 / ADR 0108 §5) merges `<core>/migrations` + `<instance>/migrations/instance` + each enabled module's migrations, keyed by namespaced filename stems (`core_NNN_`, `<key>_NNN_`, bare instance) so the two repos never collide. It resolves core-root vs instance-root via `src/instance-config.js`.
-4. **restart the platform** — a systemd unit runs `node <core>/src/platform-server.js` (Bongos-only) with `WorkingDirectory` = the instance root (so `resolveInstanceRoot()` resolves to the instance) + `PORT`/`HOST` env; then poll `/healthz`.
+3. **`sh <core>/scripts/gds/deploy-main-audit-gate.sh`** — the SEC #863 gate (ADR 0043). Refuses the deploy if a below-Metic author touched a permission-sensitive path in the delta being deployed, and on refusal **restores the checkout** to the previously-deployed SHA. See below; it is not optional and it is not last.
+4. **`bash <core>/scripts/migrate.sh`** — the core's **three-root** migrate (W5 / ADR 0108 §5) merges `<core>/migrations` + `<instance>/migrations/instance` + each enabled module's migrations, keyed by namespaced filename stems (`core_NNN_`, `<key>_NNN_`, bare instance) so the two repos never collide. It resolves core-root vs instance-root via `src/instance-config.js`.
+5. **restart the platform** — a systemd unit runs `node <core>/src/platform-server.js` (Bongos-only) with `WorkingDirectory` = the instance root (so `resolveInstanceRoot()` resolves to the instance) + `PORT`/`HOST` env; then poll `/healthz`.
 
 `docker-compose.yml` + `.github/workflows/selfhost-boot.yml` already model this shape (fresh Postgres → `npm ci` → `migrate.sh` → `platform-server`), so the flow is validated end-to-end there.
 
+## The audit gate: where it goes, and why exactly there
+
+**Between `npm ci` and `migrate`.** Both neighbours are load-bearing (task 1001426):
+
+- **After `npm ci`**, because the gate runs `main-audit.js` out of the core it is deploying. Run it before the install and it audits with the *previous* core's copy — which, until this task, had a `--db` roster read pointing at a function the per-domain `db.js` carve had moved, so it resolved nobody and passed everything.
+- **Before `migrate`**, because nothing from the new commit has EXECUTED yet at that point. `npm ci` installs; `migrate` and the restart are what run. A gate placed after either of them is a report, not a gate.
+
+**The deployed marker is the checkout's HEAD, and it advances only on success.** There is no marker file. The gate can only audit what was pulled, so the tree has already moved when it runs; if a refusal left it moved, the next deploy would compute its "previously deployed" SHA from the refused commit, never re-audit that delta, and find it already checked out. So the gate resets the tree back to `OTB_DEPLOY_PREV_SHA` before exiting non-zero. That restore lives inside the gate rather than in each caller's `~/deploy.sh`, so a new caller cannot forget it. `tests/deploy_audit_gate.mjs` pins it.
+
+Capture the previous SHA **before** the pull:
+
+```sh
+PREV_SHA="$(git rev-parse HEAD)"          # BEFORE git reset/pull
+git reset --hard origin/main
+npm ci --omit=dev
+export OTB_DEPLOY_PREV_SHA="$PREV_SHA"
+sh node_modules/@bongos/core/scripts/gds/deploy-main-audit-gate.sh || exit 1
+```
+
+**`OTB_AUDIT_STRICT` stays off.** Ranks resolve on `github_login` only — deliberately, since `display_name` is builder-controlled and keying it let one builder alias another's rank. A deploy lane whose commits are authored under a human display name (`Firstname Lastname`) rather than the builder's `github_login` therefore resolves to nothing, and strict would refuse every deploy forever. Non-strict still hard-blocks the incident class this exists for: a *resolved* below-Metic author on a protected path. Turn strict on once the lane commits under logins.
+
+**Known limit, stated rather than buried.** If the roster cannot be read at all, every author is unresolved and non-strict passes. `main-audit.js` now announces that loudly and falls through to the public roster instead of silently returning an empty map. Availability is chosen over a hard stop on purpose — a database blip must not freeze deploys — so read the stderr.
+
 ## Status — ready, not yet the live path
 
 `deploy-instance.sh` is **additive and inactive**: the live `example` droplet still deploys via `deploy-prod.sh` (`git reset --hard`). The cutover is deliberately deferred:
@@ -29,10 +53,12 @@
 
 `ship.js` needs no change: its deploy **trigger** SSHes `~/deploy.sh` (or fires the CI workflow) and is agnostic to what that script does internally — a consumer instance installs `deploy-instance.sh` as its `~/deploy.sh`.
 
+**The audit gate is the exception, and it is live.** Do not read the paragraph above as covering it: the deferred thing is the `deploy-instance.sh` *model*, not the gate. The gate was wired into `cloudbongos.com`'s existing `~/deploy.sh` under task 1001426 — between its `npm ci` and its `migrate`, with the previous SHA captured before the pull — and verified both ways against that real script on a throwaway clone. That host's `~/deploy.sh` is host state and lives in no repository, so **this diff is not where you can see it**; the wiring, its backup path and its one loose end are recorded on the task. The loose end: until a core carrying `scripts/gds/deploy-main-audit-gate.sh` is published and pinned there, the host runs a byte-identical transitional copy beside `~/deploy.sh`, and `deploy.sh` prefers the core's copy the moment it appears.
+
 ## Wiring it on a consumer host (R85/R89)
 
 1. Install the script as the droplet's `~/deploy.sh` (the CI deploy key is forced-command-locked to `~/deploy.sh` — ADR 0043 — so it stays hand-installed, like `deploy-prod.sh`).
 2. Create a systemd unit for the instance: `ExecStart=/usr/bin/node <instanceRoot>/node_modules/@bongos/core/src/platform-server.js`, `WorkingDirectory=<instanceRoot>`, `Environment=PORT=… HOST=127.0.0.1 <PREFIX>_INSTANCE_ROOT=<instanceRoot>`.
-   **`bongos serve` now writes exactly this unit for you** (plus the DB/migrate/health legs) — see [`server-bring-up.md`](server-bring-up.md) / [ADR 0169](../adr/0169-bongos-serve-server-bring-up.md). Step 4 of the flow above ("restart the platform") is `systemctl restart bongos-<db>` once it has.
+   **`bongos serve` now writes exactly this unit for you** (plus the DB/migrate/health legs) — see [`server-bring-up.md`](server-bring-up.md) / [ADR 0169](../adr/0169-bongos-serve-server-bring-up.md). Step 5 of the flow above ("restart the platform") is `systemctl restart bongos-<db>` once it has.
 3. Set `INSTANCE_SERVICE=<unit>` + `PORT=<port>` in the deploy environment.
 4. Front it with TLS and point the origins at the real domain (see [self-host.md](self-host.md)).