@bongos/core 1.20.33 → 1.20.34

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.33",
-  "core_contract": "1.20.33",
-  "source_commit": "9b3842cb58220f06a93271aaf4d5c78088cf4374",
+  "core_version": "1.20.34",
+  "core_contract": "1.20.34",
+  "source_commit": "b6e2dfd60ddc3de92e31e4ca330985ae253bedab",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T22:01:27.383Z",
+  "built_at": "2026-09-30T22:16:46.560Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 562,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 3259,
-  "tree_sha256": "aed626c2d3ddceedaf350fb3e2b40ada409404d6f830499bb790de6dec0f03d6",
+  "tree_sha256": "91cd2d81b5a990188e0fc5b9230e3f322cf350277f64f07a5d3db549627845bf",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -617,7 +617,7 @@
     {
       "path": "docs/adr/0042-builder-self-deploy-ci-auto-merge.md",
       "mode": "0000644",
-      "sha256": "9d51518e14f6a7818f2f6504519f4f3159296f78d7b89409361d459c0974f5db"
+      "sha256": "1a2c7e3b5ebeb50991f65dfe4032dab10de8be0848193c3daf9baae9aed4e314"
     },
     {
       "path": "docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md",
@@ -2257,7 +2257,7 @@
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "d21d0eb8389864b4f7394ba0f4b0d0d809182f0bef82d9fc6824edd00e174b39"
+      "sha256": "17dbc3a335653ba36f2e415c44eced76d94011585477a079765dd1f5fad36d86"
     },
     {
       "path": "docs/api-reference.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "62c1b89b8efed5d249b25f70db5bfb238cb9240c748122406d74fdc718e8b903"
+      "sha256": "974525f923ba04ab5b3fe9a0746a4ec6c859a30e4aebbb55a223e75e9c60689c"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2912,7 +2912,7 @@
     {
       "path": "docs/recipes/autobongos-windows-host.md",
       "mode": "0000644",
-      "sha256": "e70faa969725827307388ccb0620bde203500333ed299d860ca7a001cc8577a1"
+      "sha256": "5e4821f62223ffc49cef22475f7c31d5bb798bde167ed03823931694f15060d7"
     },
     {
       "path": "docs/recipes/bongos-cli-release.md",
@@ -4077,7 +4077,7 @@
     {
       "path": "modules/autonomy/cadence.js",
       "mode": "0000644",
-      "sha256": "24e717247143b6fae013c344d36f8b74dc3e4a228396dcfff39c383c2a762e6c"
+      "sha256": "e2ab1fd3381fa94af9966a036467ddcffe004cec6e4c07cc25da29b9f7aa4446"
     },
     {
       "path": "modules/autonomy/db.js",
@@ -4097,7 +4097,7 @@
     {
       "path": "modules/autonomy/gauge.js",
       "mode": "0000644",
-      "sha256": "8a126f3c93b41c18971c8bc07d424446db5c6179ad9fb1aaaad03c10d5b5f9c9"
+      "sha256": "5cbbe803f8c977f49d715cb803fa7dc20bd1800e599659669c5fe28f4f9b9b20"
     },
     {
       "path": "modules/autonomy/migrations/autonomy_001_autobongos_fence.sql",
@@ -8992,12 +8992,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "faabe741a65a2f632b26900d4d5aeac7e489263d0140c9d8633a1edf9761b8a9"
+      "sha256": "59289cb04f2457826ed40890631dffdbf24e079c5af32938989be59732703cd6"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "de12fffa22b571c06d6757c17cc153ef9a3867bc44893d572141bf989b80c185"
+      "sha256": "95aa8bfbee50b46e7eb01de527366c0ed88c2d262b00f1550a7eb177cf90967d"
     },
     {
       "path": "public-docs/index.html",
@@ -9017,7 +9017,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "695627258a4d47ae703472c86e7fb573ed751e6e2d351e47441c9ff29be824e5"
+      "sha256": "f93660db46a480e8ed3fd8302937423a3b69843192b2e052ddd4c3e17e0614b0"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9172,12 +9172,12 @@
     {
       "path": "scripts/gds/autobongos-loop.js",
       "mode": "0000644",
-      "sha256": "3415d46e27c2a198180744425f70084c72bfe0b11253f79fd8667604f2e91c8c"
+      "sha256": "6aba5f9b059680ea802993d1d79dc24caa9e16de35fdc334344dbec27d82fad0"
     },
     {
       "path": "scripts/gds/autobongos-run.js",
       "mode": "0000644",
-      "sha256": "667d8acc1ca0b709a61aebabd0ab79171873d66c32b42dcff2e86829adc2cae0"
+      "sha256": "ac0d77b54920e50205546db4269957fd6a0fc2f1ba1aca9c097abc920fa04f2a"
     },
     {
       "path": "scripts/gds/autobongos-service.cmd",
@@ -11157,7 +11157,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "0969a3b47823d6b24c9eaaeb777a69c2e6d20688908bb1995dd5893cd5ae6cf2"
+      "sha256": "df86f50ae0baa2f659cc454dfd08b57841fe02ae2704c4a40c425f36046d794c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11602,7 +11602,7 @@
     {
       "path": "tests/autobongos_cadence.mjs",
       "mode": "0000644",
-      "sha256": "d6afd12b3d2da5e77f832e8206defb676840b340d6e7a5f064fc2bb96a7c2ffb"
+      "sha256": "67b8d8868952172945c1db8f6fa2fe2e3a28212c49afc2b2378e0801df000441"
     },
     {
       "path": "tests/autobongos_fence.mjs",
@@ -11617,7 +11617,7 @@
     {
       "path": "tests/autobongos_loop.mjs",
       "mode": "0000644",
-      "sha256": "2d2017585d61ee15f217bd6eaae26025732ef099dbcfebd26f3729790b8c9078"
+      "sha256": "91e92c46fe27a4382a762029418437642b038a77286de0977ac694397759a0b6"
     },
     {
       "path": "tests/autobongos_service_ps1.mjs",

package/docs/adr/0042-builder-self-deploy-ci-auto-merge.md

@@ -2,7 +2,7 @@
 
 **Date:** 2026-06-07
 **Context:** GDS-V3, task [#679](https://example.com/builders#/task/679) (cut prod deploy over to CI). Completes the [#597](https://example.com/builders#/task/597) / [ADR 0031](0031-cloud-dev-environments-for-builders.md) §6 goal — *no builder box holds the production droplet SSH key*. Extends [ADR 0031](0031-cloud-dev-environments-for-builders.md) §6; re-applies [ADR 0016](0016-trust-boundary-server-enforced-permissions.md) to CI.
-**Status:** Accepted — **armed in production 2026-06-13** (interim, grader-off variant — task [#859](https://example.com/builders#/task/859); `config/deploy.json` `mode: ci`; see the *Arming record* below + session log [`<redacted>.md`](../session-logs/<redacted>.md)).
+**Status:** Accepted — **armed in production 2026-06-13** (interim, grader-off variant — task [#859](https://example.com/builders#/task/859); `config/deploy.json` `mode: ci`; see the *Arming record* below + session log [`<redacted>.md`](../session-logs/<redacted>.md)).
 **Amended 2026-09-30:** the CI grade-gate (precondition 1) is permanently retired, not deferred — see the *Amendment* at the end (task 1004456, blocker 1000103).
 
 ## Problem
 
@@ -35,7 +35,7 @@ With no human in the merge loop, **the CI checks *are* the authority**. The thre
 
 1. **[`CODEOWNERS`](../../CODEOWNERS)** — a PR touching any gate surface (`.github/`, `config/deploy.json`, `ship.js`, the grader, `auth.js`/`route-rank-check.js`) **or any code that executes on the droplet at deploy** (`migrations/`, `scripts/migrate.sh`, `package.json`/`package-lock.json`, `scripts/deploy/` — `~/deploy.sh` runs migrations + `npm ci` from the merged tree, so a malicious migration or poisoned lockfile would otherwise auto-merge and run on prod) requires Archon review *even under auto-merge*, when branch protection has "Require review from Code Owners" on. Ordinary PRs (game, art, docs) carry no code owner and auto-merge freely — that's the point.
 
-2. **The grader must RE-RUN in CI** — CODEOWNERS only catches *committed* changes to `ship.js`. A builder could run a **locally-edited, uncommitted** `ship.js` that skips the grade and opens an auto-merge PR anyway. An earlier draft of this ADR proposed a CI check that *reads the server-recorded grade* — but that is **theater**: `POST /tasks/:id/grade` records the grader scores *from the request body* (the server does not recompute them), so a tampered local ship.js can POST a fake passing grade. The only tamper-proof gate runs the grader **in CI, against the PR diff**, where the builder cannot touch it — [`.github/workflows/grade-gate.yml`](../../.github/workflows/grade-gate.yml) + [`scripts/gds/ci-grade.js`](../../scripts/gds/ci-grade.js) ([#855](https://example.com/builders#/task/855)), which reuse the exact production grading path (`ship.js runSubagentGrader` → the adversarial worker panel) and **fail closed**. It is **skip-safe** (green-but-not-gating) until the operator wires a grader auth secret AND marks it a required check — the same inert-until-armed pattern as `deploy-prod.yml`. This is a **hard precondition** of arming `ci` mode.
+2. **The grader must RE-RUN in CI** — CODEOWNERS only catches *committed* changes to `ship.js`. A builder could run a **locally-edited, uncommitted** `ship.js` that skips the grade and opens an auto-merge PR anyway. An earlier draft of this ADR proposed a CI check that *reads the server-recorded grade* — but that is **theater**: `POST /tasks/:id/grade` records the grader scores *from the request body* (the server does not recompute them), so a tampered local ship.js can POST a fake passing grade. The only tamper-proof gate runs the grader **in CI, against the PR diff**, where the builder cannot touch it — [`.github/workflows/grade-gate.yml`](../../.github/workflows/grade-gate.yml) + [`scripts/gds/ci-grade.js`](../../scripts/gds/ci-grade.js) ([#855](https://example.com/builders#/task/855)), which reuse the exact production grading path (`ship.js runSubagentGrader` → the adversarial worker panel) and **fail closed**. It is **skip-safe** (green-but-not-gating) until the operator wires a grader auth secret AND marks it a required check — the same inert-until-armed pattern as `deploy-prod.yml`. This was written as a **hard precondition** of arming `ci` mode. *(Superseded 2026-09-30: the CI grade-gate is permanently retired — see the Amendment below.)*
 
 ### Why not just hand builders the droplet key
 
@@ -43,7 +43,7 @@ Rejected. It puts a full shell on the production box (prod DB, every secret) on
 
 ## Cutover preconditions (do NOT arm `ci` until ALL hold)
 
-1. **CI grade-gate armed + verified** — the grader RE-RUN-in-CI check (`grade-gate.yml` + `ci-grade.js`, [#855](https://example.com/builders#/task/855)) is built and skip-safe but NOT yet a real gate. The operator must (a) add a grader auth secret (`ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` — the grader spawns the `claude` CLI, ~4 model calls/PR), (b) verify a real grader-in-CI run passes a known-good PR and fails a known-bad one, and (c) mark `grade-gate` a required status check on `main`. *Without this, `ci` mode lets a tampered local ship.js bypass the quality grader.* (Built in [#855](https://example.com/builders#/task/855); arming/verification is part of the cutover.)
+1. ~~**CI grade-gate armed + verified**~~ *(retired 2026-09-30 — see the Amendment below; never armed)* — the grader RE-RUN-in-CI check (`grade-gate.yml` + `ci-grade.js`, [#855](https://example.com/builders#/task/855)) is built and skip-safe but NOT yet a real gate. The operator must (a) add a grader auth secret (`ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` — the grader spawns the `claude` CLI, ~4 model calls/PR), (b) verify a real grader-in-CI run passes a known-good PR and fails a known-bad one, and (c) mark `grade-gate` a required status check on `main`. *Without this, `ci` mode lets a tampered local ship.js bypass the quality grader.* (Built in [#855](https://example.com/builders#/task/855); arming/verification is part of the cutover.)
 2. **Functional checks required** — the DB-free **unit suite** runs as a PR check ([`.github/workflows/pr-unit-tests.yml`](../../.github/workflows/pr-unit-tests.yml) + [`scripts/gds/run-unit-tests.js`](../../scripts/gds/run-unit-tests.js), 56 tests, [#856](https://example.com/builders#/task/856)); the operator marks it required at cutover. The **integration smoke** (full server + Postgres service container) is a follow-up ([#862](https://example.com/builders#/task/862)). The existing `secrets-scan` / `dep-audit` already run on PRs.
 3. **Branch protection on `main`** — require a PR (block direct pushes), require the checks in (1)+(2) + Code-Owner review, enable auto-merge.
 4. **`deploy-prod.yml` armed** — `PROD_SSH_KEY` + `DROPLET_KNOWN_HOSTS` secrets + `PROD_DEPLOY_VIA_CI=true` (a dedicated deploy keypair, not a personal key).
@@ -60,7 +60,7 @@ Until (1)–(5), the switch stays `laptop` and the operator lands work as today
 
 ## Follow-ups (filed as GDS tasks)
 
-- CI **grade-gate** reading the server-recorded grade — **blocks cutover** (precondition 1).
+- ~~CI **grade-gate** reading the server-recorded grade — **blocks cutover** (precondition 1).~~ Retired 2026-09-30 (Amendment below).
 - PR-check workflows: unit suite + integration smoke (Postgres service) as required checks (precondition 2).
 - Drop the per-builder `gh` dependency (server-mediated PR creation) + `doctor.js gh` check.
 - Commit/version endpoint for a commit-pinned edge deploy confirmation.
@@ -79,4 +79,18 @@ during the provider outage. With the grader off everywhere, gating auto-merge on
 
 What was set: `PROD_SSH_KEY` (a dedicated ed25519 deploy key, **forced-command `~/deploy.sh`** in the droplet's `authorized_keys`) + `DROPLET_KNOWN_HOSTS` secrets; repo var `PROD_DEPLOY_VIA_CI=true`; branch protection on `main` (require PR, required checks `unit`+`trufflehog`, require Code-Owner review, 0 ordinary approvals, block direct push for non-admins); repo auto-merge enabled; `config/deploy.json` → `ci`. `deploy-prod.yml` verified end-to-end (Actions → SSH → `~/deploy.sh` → public healthz) before the flip.
 
-**Tighten-later (re-arm when the grader returns):** turn `GRADER_BYPASS_ENABLED` off, re-introduce the `grade-gate` required check (precondition 1, needs an `ANTHROPIC_API_KEY` Actions secret), and land the integration-smoke gate (task 862, precondition 2). **Rollback:** set `config/deploy.json` → `laptop` **and** unset the `PROD_DEPLOY_VIA_CI` repo var (admins retain direct main-push for this).
+**Tighten-later (re-arm when the grader returns):** turn `GRADER_BYPASS_ENABLED` off ~~, re-introduce the `grade-gate` required check (precondition 1, needs an `ANTHROPIC_API_KEY` Actions secret)~~ *(the grade-gate leg is retired — Amendment below)*, and land the integration-smoke gate (task 862, precondition 2). **Rollback:** set `config/deploy.json` → `laptop` **and** unset the `PROD_DEPLOY_VIA_CI` repo var (admins retain direct main-push for this).
+
+## Amendment — 2026-09-30: the CI grade-gate is permanently retired
+
+**Owner ruling** (blocker 1000103, recorded under task 1004456): precondition 1 — the grader re-run in CI (`grade-gate.yml` + `scripts/gds/ci-grade.js`) — is **retired, not deferred**. It was never armed: `grade-gate.yml` does not exist and `ci-grade.js` has no caller. This ADR no longer promises it.
+
+**What holds instead** is the layered model [ADR 0164](0164-implausible-pass-guard-substance-and-evidence.md) documents:
+
+- **Grade time — honest-mistake hygiene.** The panel verdict stays *client-asserted* (`POST /tasks/:id/grade` records scores from the request body). The implausible-pass guard catches empty or evidence-free passes; it is not a tamper-proof gate and does not claim to be.
+- **Land time — the binding authorities.** The required CI `unit` check, gate-review, Code-Owner review on gate surfaces, and the deploy-time main audit ([ADR 0043](0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md)) decide what reaches `main`, whatever the grade said.
+- **Metic+ grade-time honesty is accepted honor-system.** The forgery classes this leaves uncaught are listed in ADR 0164 §3.
+
+**Why B over landing the gate.** Across the 106-grade evaluation window (goal 1000056) there were zero known forged passes. A CI re-grade would roughly double grading spend per ship and add a new required check that strands every ship whenever the grader is down — the outage class later work spent two waves defusing. The honor-system residual is judged cheaper than that.
+
+**Revisit if** a forged or tampered grade is ever found on `main`: the gate design in §*The auto-merge gate must be tamper-proof* (item 2) remains the reference for re-introducing it.

package/docs/adr/README.md

@@ -134,7 +134,7 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 0039 | [Setup-first onboarding UX: two-config selector + action-only Path checklist](0039-setup-first-onboarding-ux.md) | GDS / builder onboarding |
 | 0040 | [Remote Control is the default browser-only on-ramp (reverses 0038's "RC is dead" verdict)](0040-remote-control-default-browser-onramp.md) | GDS / builder onboarding |
 | 0041 | [Temporary global grader-bypass kill-switch (`GRADER_BYPASS_ENABLED`)](0041-temporary-grader-bypass-killswitch.md) | GDS / shipping pipeline |
-| 0042 | [Builder self-deploy: CI auto-deploy on main + PR auto-merge (no builder box holds the prod key)](0042-builder-self-deploy-ci-auto-merge.md) | GDS / shipping pipeline |
+| 0042 | [Builder self-deploy: CI auto-deploy on main + PR auto-merge (no builder box holds the prod key). **Amended 2026-09-30:** the CI grade-gate (precondition 1) is permanently retired in favour of ADR 0164's layered model](0042-builder-self-deploy-ci-auto-merge.md) | GDS / shipping pipeline |
 | 0043 | [Git/SSH trust-boundary gap + a rank floor on permission-sensitive paths](0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md) | GDS / trust boundary |
 | 0044-a | [Full Mediterranean palette replacement (not a split)](0044-mediterranean-palette-replacement.md) | Art pipeline / palette |
 | 0044-b | [Per-box live game preview (the builder sandbox)](0044-per-box-live-game-preview.md) | GDS / builder experience |

package/docs/module-api-changelog.md

@@ -2722,6 +2722,8 @@ is load-bearing: the script throws rather than guess if it is missing, and
   1.20.32 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.31 with no explicit bump. run 36781343271. (task 1002620)
   1.20.33 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
-        landed since 1.20.32 with no explicit bump. run 36783021915. (task 1002620)
+        landed since 1.20.32 with no explicit bump. run 36783765458. (task 1002620)
+  1.20.34 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.33 with no explicit bump. run 36784565937. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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

@@ -178,7 +178,7 @@ It is the machine's working copy, not a place to edit.
 | Runner line says **Not checking in** | is the PC on? `...\autobongos-service.ps1 status` on the box |
 | **Checking in** but nothing ever ships | first the Gate page — is a goal allowlisted, and is the switch on? If both are on, the **gauge**: `autobongos-service.ps1 digest`, or `node scripts/gds/autonomy-gauge.js`. A `hold` with `unknown: true` means it cannot read your remaining capacity, and it will wait forever rather than guess |
 | The log repeats `hold ... unknown: true` | the gauge has no reading it can vouch for. Open a **terminal** `claude` session on the box once — that writes it. A desktop-app session does not: the writer is a statusLine command, and only a terminal renders one |
-| `hold` naming a **derived** gauge and a cap | working as designed. After the last real reading's window resets, the runner may do `AUTOBONGOS_DERIVED_TASK_CAP` tasks (default 2) before it wants a fresh reading. A terminal session lifts it |
+| `hold` naming the **usage limit** | working as designed. A worker was cut off by the subscription limit, so the runner sleeps until the reset time and then resumes by itself. There is no fixed task cap (task 1004454) |
 | 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 |
 

package/modules/autonomy/cadence.js

@@ -110,6 +110,14 @@ function classifyEvent(row = {}) {
     // counting it as such would hold a broken runner at full speed indefinitely.
     if (row.verified === true) return { class: 'progress', detail: 'a task shipped and the ledger confirms it' };
     if (row.ledger_shape === 'undetermined') return { class: 'transient', detail: 'the ledger could not be read back' };
+    // CUT OFF BY THE USAGE LIMIT (task 1004454). Checked before workerNeverRan,
+    // whose shape it shares (seconds long, nothing spent): the machine is fine,
+    // the window is spent, and the owner has said hitting it is acceptable. So it
+    // is a wait to the reset, never a step toward probing.
+    if (row.usage_limit) {
+      const resetAt = row.usage_limit.reset_at ?? null;
+      return { class: 'quiet', detail: `the usage limit was hit — sleeping to its reset${resetAt ? '' : ' (time not stated; a bounded wait)'}`, sleepUntil: resetAt };
+    }
     // DID THE WORKER ACTUALLY RUN? (task 1004179, found by the 1003907 proof run.)
     //
     // Everything below this line assumes a worker that ran and met a real

package/modules/autonomy/gauge.js

@@ -283,7 +283,11 @@ function decideCapacity({ gauge, now, config = {} } = {}) {
   // actually binds a heavy week — does not run at all. A stale weekly figure
   // cannot stand in for it either: usage only grows, so an under-reported value
   // makes the check MORE permissive, which is the wrong direction to be wrong in.
-  // Bounding the work done since `derivedSince` is what replaces that pacing.
+  // Bounding the work done since `derivedSince` is what replaced that pacing,
+  // until the owner ruled against a fixed cap (task 1004454, 2026-09-30): the
+  // runner now works on a derived reading and stops when a worker is actually cut
+  // off by the limit, sleeping to its reset. The field is kept on the decision so
+  // the log still says which boundary a derived reading stood on.
   //
   // The MOST RECENT boundary, not the oldest (task 1004376). A derived seven-day
   // window starts up to a week back; counting from there would make the cap a

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.33",
+  "version": "1.20.34",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.33",
+      "version": "1.20.34",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.33",
+  "version": "1.20.34",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -8266,6 +8266,10 @@
     }
   ],
   "1.20.33": [
+    {
+      "id": "1004456",
+      "text": "The self-deploy decision record no longer promises a CI re-grade check that was never built; it now records the owner's choice to retire it."
+    },
     {
       "id": "1004396",
       "text": "The unattended runner no longer gets stuck retrying a task it isn't allowed to take: it moves on to the next one, and only waits when a stuck ship is blocking everyone, resuming by itself once that lands."
@@ -8274,5 +8278,11 @@
       "id": "1004449",
       "text": "When a project update fails in a way the system can't fix by itself, it now opens one blocker for a person and posts one message on Discord, instead of failing quietly. When a later update succeeds, the blocker closes by itsel"
     }
+  ],
+  "1.20.34": [
+    {
+      "id": "1004454",
+      "text": "The unattended runner no longer stops after two tasks: it keeps working while there's usage left, and if it hits the usage limit it sleeps until the limit resets and then carries on by itself."
+    }
   ]
 }

package/scripts/gds/autobongos-loop.js

@@ -164,7 +164,43 @@ function classifyRun({ envelope = null, exitCode = 0, timedOut = false, spawnErr
   return { outcome: 'claims_shipped', reason: parsed.verdict.what_happened, releaseClaim: false, verdict: parsed.verdict, costUsd: parsed.costUsd };
 }
 
+// usageLimitHit — was this worker cut off by the subscription's usage limit?
+// (task 1004454)
+//
+// Owner ruling, 2026-09-30: no fixed cap on work; hitting the limit is fine, and
+// the runner restarts once it resets. That makes the limit message the stop
+// signal, so it has to be recognised — otherwise a limit-hit worker (seconds
+// long, nothing spent) reads as workerNeverRan() and escalates the runner into
+// probing for a condition the owner accepts.
+//
+// Only an ERROR envelope, or a run with no parseable envelope, can be a limit
+// hit. A worker that FINISHED may well write about limits in its verdict (it
+// might have fixed a rate-limit bug), and sleeping on that would stop the runner
+// for doing its job.
+//
+// The CLI's machine form is `Claude AI usage limit reached|<epoch seconds>`; the
+// human forms ("You've hit your limit · resets 3am", "5-hour limit reached ∙
+// resets 3pm") carry a clock time in a zone we would have to guess, so they
+// return resetAt: null and the caller picks a bounded wait instead of parsing one.
+const LIMIT_EPOCH_RE = /usage limit reached\|(\d{9,11})/i;
+const LIMIT_TEXT_RE = /usage limit reached|hit your (usage )?limit|\b(5|five)-hour limit reached|weekly limit reached|limit reached\s*[∙·•|-]\s*resets/i;
+function usageLimitHit({ envelope = null, stderr = '' } = {}) {
+  let text = '';
+  let parsedEnvelope = null;
+  try { parsedEnvelope = typeof envelope === 'string' ? (envelope.trim() ? JSON.parse(envelope) : null) : envelope; } catch (_) { parsedEnvelope = null; }
+  if (parsedEnvelope && typeof parsedEnvelope === 'object') {
+    if (parsedEnvelope.is_error !== true) return null;
+    text = String(parsedEnvelope.result || '');
+  } else if (typeof envelope === 'string') {
+    text = envelope;
+  }
+  text = `${text}\n${stderr || ''}`;
+  const m = LIMIT_EPOCH_RE.exec(text);
+  if (m) return { resetAt: Number(m[1]) };
+  return LIMIT_TEXT_RE.test(text) ? { resetAt: null } : null;
+}
+
 module.exports = {
   WORKER_VERDICT_SCHEMA, DEFAULT_MODEL, DEFAULT_WORKER_TIMEOUT_MS,
-  buildWorkerArgs, buildWorkerPrompt, parseWorkerEnvelope, classifyRun,
+  buildWorkerArgs, buildWorkerPrompt, parseWorkerEnvelope, classifyRun, usageLimitHit,
 };

package/scripts/gds/autobongos-run.js

@@ -40,7 +40,7 @@ const os = require('node:os');
 const seq = require('./sequence.js');
 const gauge = require('./autonomy-gauge.js');
 const {
-  buildWorkerArgs, buildWorkerPrompt, classifyRun, DEFAULT_MODEL, DEFAULT_WORKER_TIMEOUT_MS,
+  buildWorkerArgs, buildWorkerPrompt, classifyRun, usageLimitHit, DEFAULT_MODEL, DEFAULT_WORKER_TIMEOUT_MS,
 } = require('./autobongos-loop.js');
 const { verifyShip, failureReason } = require('./autobongos-verify.js');
 const fence = require('../../modules/autonomy/fence.js');
@@ -95,55 +95,6 @@ function logPath() {
   try { return require('../../src/instance-config.js').configPath('autobongos-runs.jsonl'); }
   catch (_) { return path.join(REPO_ROOT, 'autobongos-runs.jsonl'); }
 }
-// countWorkedSince — how many tasks this runner has worked since an epoch-second
-// mark. Reads the run log, because that is the only record that survives a
-// restart, and the cap it feeds has to hold across one (a runner that forgets
-// its count on every crash has no cap at all).
-//
-// BOUNDED ON BOTH AXES, because this runs every iteration of a loop that never
-// exits and the log only grows. It reads the TAIL rather than the file, and it
-// scans BACKWARDS and stops at the first row older than the mark — the rows that
-// can possibly count are the newest ones, so the common case touches a handful
-// of lines whatever the log's size.
-//
-// A torn or missing log counts as zero rather than refusing: the fence and the
-// gauge are the gates, this is a bound on top of them, and a bound that bricks
-// the runner when its own log is unreadable is worse than one that occasionally
-// allows an extra task.
-const WORKED_SCAN_TAIL_BYTES = 1024 * 1024;
-const NEWLINE = String.fromCharCode(10);
-
-function countWorkedSince(sinceEpochS) {
-  if (!Number.isFinite(sinceEpochS) || sinceEpochS <= 0) return 0;
-  let text;
-  try {
-    const p = logPath();
-    const { size } = fs.statSync(p);
-    const from = Math.max(0, size - WORKED_SCAN_TAIL_BYTES);
-    const fd = fs.openSync(p, 'r');
-    try {
-      const buf = Buffer.alloc(Math.min(size, WORKED_SCAN_TAIL_BYTES));
-      fs.readSync(fd, buf, 0, buf.length, from);
-      text = buf.toString('utf8');
-    } finally { fs.closeSync(fd); }
-    // A tail read can land mid-line; drop the first partial one.
-    if (from > 0) text = text.slice(text.indexOf(NEWLINE) + 1);
-  } catch (_) { return 0; }
-
-  const lines = text.split(NEWLINE);
-  let n = 0;
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i];
-    if (!line.trim()) continue;
-    let row;
-    try { row = JSON.parse(line); } catch (_) { continue; }   // a torn line costs one row, not the count
-    const at = Date.parse(row.at);
-    if (!Number.isFinite(at)) continue;
-    if (at / 1000 < sinceEpochS) break;   // the log is append-ordered: nothing older can count
-    if (row.event === 'worked') n += 1;
-  }
-  return n;
-}
 
 function record(entry) {
   const row = { at: new Date().toISOString(), ...entry };
@@ -401,9 +352,14 @@ const CLAIM_SET_ASIDE_MS = 30 * 60 * 1000;
 // A bound on claim attempts in ONE pass, so a queue of refusals cannot turn one
 // iteration into dozens of worktree creations.
 const MAX_CLAIM_ATTEMPTS = 5;
+// A limit message with no machine-readable reset (the CLI's human forms name a
+// clock time in a zone we would have to guess). Half an hour is short against a
+// five-hour window and long against a spawn that is cut off in two seconds, so a
+// guess that is wrong costs one wasted spawn per half hour, not one per wake.
+const LIMIT_UNKNOWN_RESET_MS = 30 * 60 * 1000;
 
 function newRunnerState() {
-  return { setAside: new Map(), queueGate: null };
+  return { setAside: new Map(), queueGate: null, limitUntil: null };
 }
 const RUNNER_STATE = newRunnerState();
 
@@ -474,42 +430,30 @@ async function iteration(opts, deps = {}) {
     return log({ event: 'hold', go: false, unknown: !!g.decision.unknown, reason: g.decision.reason, sleep_until: g.decision.sleepUntil ?? null });
   }
 
-  // 1b. A DERIVED gauge buys a BOUNDED amount of work (task 1004178).
-  //
-  // `derived` means the last real reading's window had already reset, so the
-  // baseline is a retired observation rather than a measurement. That is sound
-  // for the FIVE-hour window, which turns over during a night. It does nothing
-  // for the SEVEN-day one, which does not — so the weekly pace check, the thing
-  // the module's notes call what actually binds a heavy week, is simply absent
-  // on a derived reading. A stale weekly figure cannot substitute: usage only
-  // grows, so an under-reported value makes the check more permissive, and that
-  // is the wrong direction to be wrong in.
-  //
-  // So the bound is a task count, not a percentage: on one derived window, do
-  // AUTOBONGOS_DERIVED_TASK_CAP tasks and then hold until a real reading exists.
-  // A terminal session writes one; the owner opening a terminal in the morning
-  // is what lifts it. Default 2 — each worker is wall-clock bounded at 90
-  // minutes, so two of them is well inside a five-hour window even at worst, and
-  // the cap only has to be small enough that being wrong is survivable.
-  if (g.decision.derived) {
-    const cap = Number(process.env.AUTOBONGOS_DERIVED_TASK_CAP ?? 2);
-    const since = Number(g.decision.derivedSince) || 0;
-    const done = countWorkedSince(since);
-    if (Number.isFinite(cap) && cap >= 0 && done >= cap) {
+  // 1b. The usage limit, once HIT (task 1004454). Owner ruling 2026-09-30: no
+  // fixed cap on how much work a reading buys — the gauge above is read before
+  // every task and a derived reading proceeds — and hitting the limit is
+  // acceptable, so long as the runner then waits for the reset and resumes by
+  // itself. A worker cut off by the limit records when it resets; until then no
+  // task is taken, because every worker spawned would be cut off the same way.
+  const state = deps.state || RUNNER_STATE;
+  const now = deps.now ? deps.now() : Date.now();
+  if (state.limitUntil) {
+    if (now < state.limitUntil) {
       return log({
-        event: 'hold', go: false, unknown: false, derived: true, worked_since_derived: done,
-        reason: `derived gauge: ${done} task(s) already done since the window reset and the cap is ${cap} — holding for a real reading (a terminal session writes one)`,
-        sleep_until: null,
+        event: 'hold', go: false, unknown: false, usage_limit: true,
+        reason: 'the subscription usage limit was hit — sleeping to its reset, then resuming by itself',
+        sleep_until: Math.round(state.limitUntil / 1000),
       });
     }
+    log({ event: 'usage_limit_reset', was_until: new Date(state.limitUntil).toISOString() });
+    state.limitUntil = null;
   }
 
   // 1c. A QUEUE-WIDE gate from an earlier pass (task 1004396). While the
   // stranded task it named is still `confirmed`, every claim would be refused, so
   // none is attempted. The wait wakes early when main moves (waitOrJump), which is
   // exactly what the strand landing does.
-  const state = deps.state || RUNNER_STATE;
-  const now = deps.now ? deps.now() : Date.now();
   if (state.queueGate) {
     if (await queueGateHolds(state.queueGate, deps)) return log(queueGatedRow(state.queueGate, now));
     log({ event: 'queue_gate_cleared', waited_on: state.queueGate.owed, waited_s: Math.max(0, Math.round((now - state.queueGate.since) / 1000)) });
@@ -592,6 +536,10 @@ async function iteration(opts, deps = {}) {
   const started = Date.now();
   const res = await spawnWork({ task, model: opts.model, timeoutMs: opts.timeoutMs, cwd: wtPath, deps });
   const verdict = classifyRun(res);
+  // Cut off by the usage limit? Recorded here so the NEXT iteration sleeps to the
+  // reset instead of spawning a worker that will be cut off the same way.
+  const limit = verdict.outcome === 'claims_shipped' ? null : usageLimitHit({ envelope: res.envelope, stderr: res.stderr });
+  if (limit) state.limitUntil = limit.resetAt ? limit.resetAt * 1000 : now + LIMIT_UNKNOWN_RESET_MS;
 
   // 6. VERIFY FROM THE LEDGER (task 1003903). Read the task back from Bongos and
   // let IT say what happened — for every outcome, not only a claimed ship. The
@@ -623,6 +571,7 @@ async function iteration(opts, deps = {}) {
     session_id: res.sessionId || null, duration_s: Math.round((Date.now() - started) / 1000),
     cost_usd: verdict.costUsd ?? null,
     output_truncated: !!res.truncated,
+    ...(limit ? { usage_limit: { reset_at: limit.resetAt } } : {}),
     undetermined_decisions: verdict.verdict ? verdict.verdict.undetermined_decisions : null,
     // What the LEDGER says, kept separate from what the worker said, so the run
     // log can be read afterwards without having to trust either one alone.
@@ -1022,6 +971,15 @@ async function forever(opts, deps = {}) {
       // corpse.
       await beat({ mode: state.mode, last_event: row.event, working_task_id: Number(row.task_id) || undefined });
       const seen = cadence.classifyEvent(row);
+      // A hold that names its reset SECOND waits until that second (task 1004454).
+      // classifyEvent carries it as an absolute epoch; the cadence has no clock of
+      // its own, so the conversion to a wait lives here beside the one clock read.
+      // Without it every hold waited the fixed idle and the "wake at the reset"
+      // the goal asks for was only ever as accurate as the poll.
+      if (Number.isFinite(Number(seen.sleepUntil)) && seen.sleepUntil !== null) {
+        const nowS = Math.floor((deps.now ? deps.now() : Date.now()) / 1000);
+        seen.sleepUntilS = Math.max(0, Number(seen.sleepUntil) - nowS);
+      }
       state = cadence.nextCadence(state, seen, opts.cadence);
       log({ event: 'cadence', mode: state.mode, consecutive_failures: state.consecutiveFailures, wait_s: state.waitS, class: seen.class, why: state.why });
       // A burst continues only while work is actually landing. Anything else ends
@@ -1082,8 +1040,8 @@ if (require.main === module) {
 
 module.exports = {
   readArgv, pickTask, iteration, record, logPath, spawnWorker, workerEnv, WORKER_ENV_ALLOW, resolveWorkerBin,
-  worktreeName, readFence, reconcileLeftoverClaims, pollSignals, waitOrJump, forever, CLAIM_PREFIX, countWorkedSince, codeDrifted, loadedHead, UPGRADE_EXIT_CODE, MIN_UPTIME_BEFORE_UPGRADE_MS,
+  worktreeName, readFence, reconcileLeftoverClaims, pollSignals, waitOrJump, forever, CLAIM_PREFIX, codeDrifted, loadedHead, UPGRADE_EXIT_CODE, MIN_UPTIME_BEFORE_UPGRADE_MS,
   heartbeatPath, writeHeartbeat, readHeartbeat, pidAlive, anotherRunnerIsAlive, HEARTBEAT_STALE_MS,
   isRunnerTree, RUNNER_TREE_RE, postHeartbeat, RUNNER_STARTED_AT, failureReason,
-  newRunnerState, QUEUE_GATED_EXIT, CLAIM_SET_ASIDE_MS, MAX_CLAIM_ATTEMPTS, owedTaskIds,
+  newRunnerState, LIMIT_UNKNOWN_RESET_MS, QUEUE_GATED_EXIT, CLAIM_SET_ASIDE_MS, MAX_CLAIM_ATTEMPTS, owedTaskIds,
 };

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.33'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.34'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/autobongos_cadence.mjs

@@ -293,6 +293,33 @@ function loopHarness({ rows, maxLoops = 6 }) {
   return { deps, waits: emitted, recorded, opts: { goals: [], maxTasks: 3, maxLoops } };
 }
 
+// ── the usage limit: a wait to a known second, not a failure (task 1004454) ──
+
+test('a worker cut off by the usage limit is quiet, not a failed launch', () => {
+  // It exits in seconds having spent nothing — exactly workerNeverRan()'s shape —
+  // but the machine is fine: the window is spent. Escalating it would put the
+  // runner into probing for a limit the owner has said is acceptable to hit.
+  const seen = classifyEvent({ event: 'worked', outcome: 'worker_failed', duration_s: 2, cost_usd: null, reason: 'x', usage_limit: { reset_at: 1790300000 } });
+  assert.equal(seen.class, 'quiet');
+  assert.equal(seen.sleepUntil, 1790300000);
+});
+
+test('a hold with a reset time makes the loop wait until THAT second, not a fixed idle', async () => {
+  const nowS = 1_790_290_000;
+  const h = loopHarness({ rows: [{ event: 'hold', go: false, reason: 'five-hour burn at the ceiling', sleep_until: nowS + 3600 }], maxLoops: 1 });
+  h.deps.now = () => nowS * 1000;
+  await runner.forever(h.opts, h.deps);
+  assert.equal(h.waits[0].waitS, 3600, 'the wake is the reset second the gauge named');
+});
+
+test('a hold whose reset has already passed waits no time at all', async () => {
+  const nowS = 1_790_290_000;
+  const h = loopHarness({ rows: [{ event: 'hold', go: false, reason: 'x', sleep_until: nowS - 5 }], maxLoops: 1 });
+  h.deps.now = () => nowS * 1000;
+  await runner.forever(h.opts, h.deps);
+  assert.equal(h.waits[0].waitS, 0);
+});
+
 test('PULLING THE NETWORK: the loop backs off and never returns', async () => {
   const h = loopHarness({ rows: [{ event: 'pick_failed', reason: 'fetch failed ECONNREFUSED' }] });
   await runner.forever(h.opts, h.deps);

package/tests/autobongos_loop.mjs

@@ -11,7 +11,7 @@ import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
 const {
-  WORKER_VERDICT_SCHEMA, buildWorkerArgs, buildWorkerPrompt, parseWorkerEnvelope, classifyRun,
+  WORKER_VERDICT_SCHEMA, buildWorkerArgs, buildWorkerPrompt, parseWorkerEnvelope, classifyRun, usageLimitHit,
 } = require('../scripts/gds/autobongos-loop.js');
 const runner = require('../scripts/gds/autobongos-run.js');
 
@@ -836,119 +836,132 @@ test('workerEnv passes Claude auth through, and still refuses the rest', () => {
     assert.equal(env[leak], undefined, `${leak} must never reach a bypassPermissions worker`);
   }
 });
-// --- a derived gauge buys BOUNDED work (task 1004178) -----------------------
+// --- usage is judged continuously; hitting the limit sleeps to its reset (task 1004454) ---
 //
-// `derived` retires a reading whose window has reset. That is sound for the
-// five-hour window, which turns over during a night. The SEVEN-day one does
-// not, so its stale reading is dropped and the weekly pace check — what the
-// module's notes call the thing that actually binds a heavy week — does not run
-// at all on a derived reading. The task cap is what stands in for it, so the
-// cap has to work, and it has to survive a restart: the count comes from the
-// run log, not from memory.
+// Owner ruling, 2026-09-30: no fixed cap. The derived-gauge cap (task 1004178)
+// held the runner after two tasks on an inferred reading — 776 holds in one
+// 2026-09-26..29 run — for a risk the owner accepts: "if you hit usage limits
+// that's fine, but then restart once the limit resets". So the gauge is still
+// read before every task, a derived reading proceeds, and the limit itself is
+// the stop: a worker cut off by it puts the runner to sleep until the reset.
 
 import { mkdtempSync, writeFileSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-const derivedLog = () => {
-  const dir = mkdtempSync(join(tmpdir(), 'autobongos-cap-'));
-  return join(dir, 'runs.jsonl');
-};
-
-test('countWorkedSince counts only worked rows at or after the mark', () => {
-  const p = derivedLog();
-  process.env.AUTOBONGOS_LOG_FILE = p;
-  const at = (s) => new Date(s * 1000).toISOString();
-  writeFileSync(p, [
-    JSON.stringify({ at: at(1000), event: 'worked', task_id: '1' }),   // before the mark
-    JSON.stringify({ at: at(3000), event: 'hold' }),                   // not a worked row
-    JSON.stringify({ at: at(3100), event: 'worked', task_id: '2' }),
-    '{ this line is torn',                                             // costs one row, not the count
-    JSON.stringify({ at: at(3200), event: 'worked', task_id: '3' }),
-  ].join('\n'));
-  assert.equal(runner.countWorkedSince(2000), 2);
-  assert.equal(runner.countWorkedSince(0), 0, 'a zero/absent mark counts nothing rather than everything');
-  delete process.env.AUTOBONGOS_LOG_FILE;
-});
-
-test('countWorkedSince treats an unreadable log as zero, not as a refusal', () => {
-  process.env.AUTOBONGOS_LOG_FILE = join(tmpdir(), 'autobongos-cap-nope', 'missing.jsonl');
-  assert.equal(runner.countWorkedSince(1), 0,
-    'the fence and the gauge are the gates; a bound that bricks the runner when its own log is gone is worse');
-  delete process.env.AUTOBONGOS_LOG_FILE;
-});
-
-test('a derived gauge HOLDS once the cap is reached, and the reason says why', async () => {
-  const p = derivedLog();
-  process.env.AUTOBONGOS_LOG_FILE = p;
-  process.env.AUTOBONGOS_DERIVED_TASK_CAP = '2';
+test('a derived gauge keeps WORKING however many tasks it has already done — there is no cap', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'autobongos-nocap-'));
+  process.env.AUTOBONGOS_LOG_FILE = join(dir, 'runs.jsonl');
   const at = (s) => new Date(s * 1000).toISOString();
-  writeFileSync(p, [
-    JSON.stringify({ at: at(5100), event: 'worked', task_id: '1' }),
-    JSON.stringify({ at: at(5200), event: 'worked', task_id: '2' }),
-  ].join('\n'));
-
+  const rows = [];
+  for (let i = 0; i < 6; i++) rows.push(JSON.stringify({ at: at(5100 + i), event: 'worked', task_id: String(i) }));
+  writeFileSync(process.env.AUTOBONGOS_LOG_FILE, rows.join('\n'));
+  let reachedPicker = false;
   const events = [];
   await runner.iteration({ goals: [], maxTasks: 1 }, {
+    state: runner.newRunnerState(),
     readFence: async () => ({ raw: { enabled: true, goals: [{ goal_id: 7 }] }, graderBypassed: false }),
     gauge: () => ({ decision: { go: true, unknown: false, derived: true, derivedSince: 5000, reason: 'derived' } }),
-    pickTask: async () => { throw new Error('CAP BREACHED: reached the picker'); },
+    pickTask: async () => { reachedPicker = true; return { none: true, skipped: [] }; },
     record: (row) => { events.push(row); return row; },
-    run: async () => { throw new Error('CAP BREACHED: ran a command'); },
-    spawnWorker: async () => { throw new Error('CAP BREACHED: spawned a worker'); },
   });
-  assert.equal(events[0].event, 'hold');
-  assert.equal(events[0].derived, true);
-  assert.equal(events[0].worked_since_derived, 2);
-  assert.match(events[0].reason, /cap is 2/);
-  delete process.env.AUTOBONGOS_LOG_FILE; delete process.env.AUTOBONGOS_DERIVED_TASK_CAP;
-});
-
-test('a derived gauge still WORKS while under the cap', async () => {
-  const p = derivedLog();
-  process.env.AUTOBONGOS_LOG_FILE = p;
-  process.env.AUTOBONGOS_DERIVED_TASK_CAP = '2';
-  writeFileSync(p, JSON.stringify({ at: new Date(5100 * 1000).toISOString(), event: 'worked', task_id: '1' }));
-  let reachedPicker = false;
+  assert.equal(reachedPicker, true, 'six tasks since the reset must not stop the seventh');
+  assert.ok(!events.some((e) => e.event === 'hold'), 'no hold on a derived reading');
+  delete process.env.AUTOBONGOS_LOG_FILE;
+});
+
+test('the gauge is still read before EVERY task, and a real hold still holds', async () => {
+  let reads = 0;
   const events = [];
-  await runner.iteration({ goals: [], maxTasks: 1 }, {
+  const d = {
+    state: runner.newRunnerState(),
     readFence: async () => ({ raw: { enabled: true, goals: [{ goal_id: 7 }] }, graderBypassed: false }),
-    gauge: () => ({ decision: { go: true, unknown: false, derived: true, derivedSince: 5000, reason: 'derived' } }),
-    pickTask: async () => { reachedPicker = true; return { none: true, skipped: [] }; },
+    gauge: () => { reads += 1; return { decision: { go: false, unknown: false, reason: 'five-hour burn 80% is past the ceiling', sleepUntil: 1790218521 } }; },
+    pickTask: async () => { throw new Error('picked past a hold'); },
     record: (row) => { events.push(row); return row; },
-  });
-  assert.equal(reachedPicker, true, 'one task done against a cap of two must still proceed');
-  delete process.env.AUTOBONGOS_LOG_FILE; delete process.env.AUTOBONGOS_DERIVED_TASK_CAP;
+  };
+  await runner.iteration({ goals: [], maxTasks: 1 }, d);
+  await runner.iteration({ goals: [], maxTasks: 1 }, d);
+  assert.equal(reads, 2);
+  assert.equal(events[1].event, 'hold');
+  assert.equal(events[1].sleep_until, 1790218521);
 });
 
-test('countWorkedSince is bounded: a huge log does not mean a huge scan', () => {
-  const p = derivedLog();
-  process.env.AUTOBONGOS_LOG_FILE = p;
-  const at = (s) => new Date(s * 1000).toISOString();
-  // 40k old rows, then the two that matter. A whole-file parse would touch
-  // every one of them on EVERY iteration of a loop that never exits.
-  const old = [];
-  for (let i = 0; i < 40000; i++) old.push(JSON.stringify({ at: at(1000 + i), event: 'worked', task_id: String(i) }));
-  old.push(JSON.stringify({ at: at(900000), event: 'worked', task_id: 'recent-1' }));
-  old.push(JSON.stringify({ at: at(900100), event: 'worked', task_id: 'recent-2' }));
-  writeFileSync(p, old.join('\n'));
-  const t0 = Date.now();
-  assert.equal(runner.countWorkedSince(800000), 2, 'only the rows at or after the mark count');
-  assert.ok(Date.now() - t0 < 500, 'and it must not walk the whole log to say so');
-  delete process.env.AUTOBONGOS_LOG_FILE;
+test('usageLimitHit reads the reset second out of the CLI\'s own limit message', () => {
+  const env = JSON.stringify({ type: 'result', subtype: 'success', is_error: true, result: 'Claude AI usage limit reached|1790300000' });
+  assert.deepEqual(usageLimitHit({ envelope: env }), { resetAt: 1790300000 });
 });
 
-test('countWorkedSince stops at the first row older than the mark', () => {
-  const p = derivedLog();
-  process.env.AUTOBONGOS_LOG_FILE = p;
-  const at = (s) => new Date(s * 1000).toISOString();
-  writeFileSync(p, [
-    JSON.stringify({ at: at(100), event: 'worked', task_id: 'ancient' }),
-    JSON.stringify({ at: at(5000), event: 'worked', task_id: 'before-mark' }),
-    JSON.stringify({ at: at(9000), event: 'worked', task_id: 'after-mark' }),
-  ].join('\n'));
-  assert.equal(runner.countWorkedSince(8000), 1);
-  delete process.env.AUTOBONGOS_LOG_FILE;
+test('usageLimitHit recognises a limit message with no machine-readable time, and says so', () => {
+  const env = JSON.stringify({ type: 'result', is_error: true, result: "You've hit your limit · resets 3am (America/New_York)" });
+  assert.deepEqual(usageLimitHit({ envelope: env }), { resetAt: null });
+  assert.deepEqual(usageLimitHit({ envelope: '', stderr: '5-hour limit reached ∙ resets 3pm' }), { resetAt: null });
+});
+
+test('usageLimitHit ignores the word "limit" in a worker that FINISHED', () => {
+  // A worker that fixed a GitHub rate-limit bug writes about rate limits in its
+  // verdict. Only an ERROR envelope, or a run with no envelope at all, can be a
+  // limit hit — anything else would put the runner to sleep for doing its job.
+  const env = JSON.stringify({ type: 'result', is_error: false, result: 'Claude AI usage limit reached|1790300000 is the banner text I fixed', structured_output: { outcome: 'shipped', what_happened: 'fixed the usage limit reached banner' } });
+  assert.equal(usageLimitHit({ envelope: env }), null);
+  assert.equal(usageLimitHit({ envelope: JSON.stringify({ is_error: true, result: 'API Error: 500' }) }), null);
+});
+
+function limitHarness(state, now, envelopeText) {
+  const rows = [];
+  const deps = {
+    state, now: () => now.t,
+    gauge: () => ({ decision: { go: true, unknown: false, derived: true, derivedSince: 1, reason: 'derived' } }),
+    readFence: async () => ({ raw: { enabled: true, goals: [{ goal_id: 1000119 }] }, graderBypassed: false }),
+    api: {},
+    verifyDeps: {
+      task: { id: 4242, status: 'active', updated_at: new Date().toISOString() },
+      probeArtifact: async () => ({ checked: true, onMain: false }),
+      fileBlocker: async () => ({ filed: false }),
+    },
+    release: async () => ({ ok: true, code: 0, stdout: '', stderr: '' }),
+    pickTask: async () => ({ task: { id: 4242, title: 't', kind: 'feature', description: 'd'.repeat(300), goal_id: 1000119, touches: [] }, goalId: 1000119, skipped: [] }),
+    worktreeName: () => 'autobongos-4242-abc123',
+    record: (r) => { rows.push(r); return r; },
+    run: async () => ({ ok: true, code: 0, stdout: '', stderr: '' }),
+    spawnWorker: async () => ({ envelope: envelopeText, exitCode: 1, sessionId: 's' }),
+  };
+  return { deps, rows };
+}
+
+test('a worker cut off by the usage limit puts the runner to sleep until the reset, then it resumes by itself', async () => {
+  const state = runner.newRunnerState();
+  const now = { t: 1_790_290_000_000 };
+  const env = JSON.stringify({ type: 'result', is_error: true, result: 'Claude AI usage limit reached|1790300000' });
+  const h = limitHarness(state, now, env);
+
+  const worked = await runner.iteration(opts, h.deps);
+  assert.equal(worked.event, 'worked');
+  assert.deepEqual(worked.usage_limit, { reset_at: 1790300000 }, 'the row says the limit was hit and when it resets');
+
+  let picked = false;
+  const asleep = await runner.iteration(opts, { ...h.deps, pickTask: async () => { picked = true; return { none: true }; } });
+  assert.equal(asleep.event, 'hold');
+  assert.equal(asleep.sleep_until, 1790300000, 'it sleeps to the reset second the CLI named');
+  assert.match(asleep.reason, /usage limit/);
+  assert.equal(picked, false, 'no task is taken while the limit is spent');
+
+  now.t = 1_790_300_001_000;
+  const awake = await runner.iteration(opts, { ...h.deps, pickTask: async () => { picked = true; return { none: true, skipped: [] }; } });
+  assert.equal(picked, true, 'past the reset it picks again without anyone touching it');
+  assert.equal(awake.event, 'nothing_claimable');
+  assert.equal(state.limitUntil, null);
+});
+
+test('a limit hit with no stated reset sleeps a bounded while and then tries again', async () => {
+  const state = runner.newRunnerState();
+  const now = { t: 2_000_000_000_000 };
+  const h = limitHarness(state, now, JSON.stringify({ is_error: true, result: '5-hour limit reached ∙ resets 3pm' }));
+  const worked = await runner.iteration(opts, h.deps);
+  assert.deepEqual(worked.usage_limit, { reset_at: null });
+  const asleep = await runner.iteration(opts, h.deps);
+  assert.equal(asleep.event, 'hold');
+  assert.equal(asleep.sleep_until, Math.round((now.t + runner.LIMIT_UNKNOWN_RESET_MS) / 1000));
 });
 
 // --- a --forever runner must be able to take a fix (task 1004374) -----------