@bongos/core 1.19.871 → 1.19.872

package/docs/design/hall-direction-v2.md

@@ -1,7 +1,7 @@
 # The builders' hall, direction v2: five archetypes of the chrome world (task 1003302)
 
 **Date:** 2026-08-30 · **Goal:** 1000081 (Builders' hall in the world) · **Criterion:** `hall-archetypes-approved` ·
-**World:** the chrome world, recorded in `DESIGN.md` at the repo root by task 1003298 ([ADR 0196](adr/0196-chrome-world-token-contract-and-the-landing-sheets.md), [ADR 0204](adr/0204-the-apex-is-dark-only.md)).
+**World:** the chrome world, recorded in `DESIGN.md` at the repo root by task 1003298 ([ADR 0196](../adr/0196-chrome-world-token-contract-and-the-landing-sheets.md), [ADR 0204](../adr/0204-the-apex-is-dark-only.md)).
 
 This document records the hall's composition round: five archetype pages, three versions each, built as real
 HTML against the world the apex already lives in. It is the round that answers *how the hall should look*.
@@ -177,7 +177,7 @@ does differently, and its honest risk.
 4. **Two regions on the task page do not exist today.** This round's brief asked for a grade panel and a session
    log; grades live on Standing and session logs on `/sessions`. The task mocks show both marked `proposed`, with
    a dashed edge and a mono eyebrow. Say whether the build adds them or leaves them where they are.
-5. **The light mode.** The apex went dark only ([ADR 0204](adr/0204-the-apex-is-dark-only.md)), so the hall is now
+5. **The light mode.** The apex went dark only ([ADR 0204](../adr/0204-the-apex-is-dark-only.md)), so the hall is now
    the only surface with a real light mode. Confirm it stays, since it doubles the build's contrast work.
 
 **If no pick lands, the build takes v2 "the sheet" for all five archetypes**, as the version that reads the

package/docs/module-api-changelog.md

@@ -2216,5 +2216,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.869 with no explicit bump. run 35388809554. (task 1002620)
   1.19.871 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.870 with no explicit bump. run 35393164740. (task 1002620)
+  1.19.872 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.871 with no explicit bump. run 35419318693. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/onboarding/diagrams/README.md

@@ -11,7 +11,7 @@ Five flowcharts that explain Bongos to a new builder at a glance. Each diagram i
 | Diagram | What drives its state |
 |---|---|
 | `01-task-lifecycle` · `02-rank-ladder` · `05-versioning` (**mechanical**) | The task-status set + rank enum/wiring (read from `migrations/` + `src/bongos/`) and the live version set (production API). No auth needed — always regenerate. |
-| `03-example-karma` · `04-architecture` (**conceptual**) | Each feature-piece is **LIVE iff its backing Bongos task is `shipped`**, plus 03's "N seeded" count from the achievements seed in `migrations/`. These read the **authenticated** `/tasks/:id` status, so when no Bongos session is available (headless run, no creds) the generator **skips** 03/04 and leaves them untouched rather than emit wrong data. (04's device/box/server/GitHub *topology* is structural; only its LIVE/PLANNED markers — the memory chain + the box→prod ship-flow legs — are task-gated.) |
+| `03-drachmae-karma` · `04-architecture` (**conceptual**) | Each feature-piece is **LIVE iff its backing Bongos task is `shipped`**, plus 03's "N seeded" count from the achievements seed in `migrations/`. These read the **authenticated** `/tasks/:id` status, so when no Bongos session is available (headless run, no creds) the generator **skips** 03/04 and leaves them untouched rather than emit wrong data. (04's device/box/server/GitHub *topology* is structural; only its LIVE/PLANNED markers — the memory chain + the box→prod ship-flow legs — are task-gated.) |
 
 The mechanical diagrams regenerate **on every deploy** (`ship.js` / `/merge-mode` run `gen-diagrams.js` before deploying; a changed diagram is committed and shipped automatically). The conceptual diagrams regenerate the same way whenever a session is present (the deploy host has one). The `diagram-drift` routine remains as a belt-and-braces backstop. So `/builders/diagrams` is never more than one deploy behind the live architecture.
 
@@ -42,11 +42,11 @@ The 16-value reserved rank enum (migration 023) in three Greek bands, which rank
 Source: [`02-rank-ladder.mmd`](02-rank-ladder.mmd)
 
 ### 3. Example & karma — sourcing and spending
-Where each comes from and where each goes. Key facts: **example = credits** (same thing, in-world name), they are **equity, not a spendable currency**, and the **primary source is now a cost-plus reward on each shipped session** — `round(true_cost × 1.20)` ([ADR 0054](../../adr/0054-session-token-reward-cost-plus.md)) — alongside per-task `credits_reward × kind multiplier` ([ADR 0023](../../adr/0023-kind-multipliers-and-idea-bonus.md)), achievements, and the (rate-card-live) security bounty. Karma is a separate peer-trust signal that does **not** gate rank promotions; its LIVE/PLANNED state tracks its backing tasks (R25/R32/R26). The full write-up is [`docs/onboarding/example-and-karma.md`](../example-and-karma.md).
+Where each comes from and where each goes. Key facts: **example = credits** (same thing, in-world name), they are **equity, not a spendable currency**, and the **primary source is now a cost-plus reward on each shipped session** — `round(true_cost × 1.20)` ([ADR 0054](../../adr/0054-session-token-reward-cost-plus.md)) — alongside per-task `credits_reward × kind multiplier` ([ADR 0023](../../adr/0023-kind-multipliers-and-idea-bonus.md)), achievements, and the (rate-card-live) security bounty. Karma is a separate peer-trust signal that does **not** gate rank promotions; its LIVE/PLANNED state tracks its backing tasks (R25/R32/R26). The full write-up is [`docs/onboarding/example-and-karma.md`](../drachmae-and-karma.md).
 
-![Example and karma](03-example-karma.png)
+![Example and karma](03-drachmae-karma.png)
 
-Source: [`03-example-karma.mmd`](03-example-karma.mmd)
+Source: [`03-drachmae-karma.mmd`](03-drachmae-karma.mmd)
 
 ### 4. The complete architecture — where your work runs and how code reaches production
 One map of the whole system, merging the old "server ↔ repo ↔ memory" three-layer view with the dev-box → production ship flow. The four places Claude Code splits across — your **device** (screen only) · the **dev box** (the worker, the code, *and* your local memory dir) · the **server/droplet** (authority *and* production: Postgres, the server-side memory store, the push credential) · **GitHub** (branch-protected main + Actions) — plus two flows woven through it: the **per-builder memory layer** (ADR 0024 — local ↔ server, sync-on-ship / pull-on-start) and the **box → prod ship path** (a credential-less box re-auths and uploads its branch as a git bundle; the server pushes it with a GitHub App credential; the PR auto-merges and GitHub Actions deploys — no droplet key on any box). Every feature-piece + flow edge is LIVE/solid iff its backing task is `shipped`. Backing tasks: memory chain [#273](https://example.com/builders#/task/273)–[#276](https://example.com/builders#/task/276); dev box [#904](https://example.com/builders#/task/904)/[#774](https://example.com/builders#/task/774)/[#897](https://example.com/builders#/task/897)/[#919](https://example.com/builders#/task/919); box→prod [#1025](https://example.com/builders#/task/1025)/[#859](https://example.com/builders#/task/859)/[#1028](https://example.com/builders#/task/1028)/[#1027](https://example.com/builders#/task/1027) (all shipped → the map reads all-LIVE today). See [ADR 0024](../../adr/0024-cloneable-repo-local-first-memory.md) (cloneable memory), [ADR 0055](../../adr/0055-server-mediated-branch-publish.md) (server-mediated publish), [ADR 0053](../../adr/0053-scoped-dev-box-session.md) (scoped box token), [ADR 0042](../../adr/0042-builder-self-deploy-ci-auto-merge.md) (CI self-deploy), [ADR 0016](../../adr/0016-trust-boundary-server-enforced-permissions.md) (trust boundary).

package/docs/onboarding/drachmae-and-karma.md

@@ -2,7 +2,7 @@
 
 *The complete reference for the two reputation tracks in Bongos. The [primer](primer.md) gives you the one-paragraph version; this is the full picture, kept honest against the live system. ~8 minutes.*
 
-> **Source of truth.** The numbers live in the production database (`builders.total_credits`, `builders.karma`) and the rules live in code (`src/bongos/db.js`, `src/bongos/cost.js`). This doc *describes* them; where they disagree, the code wins. The two diagrams that visualize this — [task lifecycle](diagrams/01-task-lifecycle.png) and [example & karma](diagrams/03-example-karma.png) — are auto-generated from the same live facts.
+> **Source of truth.** The numbers live in the production database (`builders.total_credits`, `builders.karma`) and the rules live in code (`src/bongos/db.js`, `src/bongos/cost.js`). This doc *describes* them; where they disagree, the code wins. The two diagrams that visualize this — [task lifecycle](diagrams/01-task-lifecycle.png) and [example & karma](diagrams/03-drachmae-karma.png) — are auto-generated from the same live facts.
 
 ---
 
@@ -173,6 +173,6 @@ Both are reputation. Neither is a spendable currency today. You don't have to *d
 ## See it / dig deeper
 
 - **Your numbers:** [builders' hall](https://example.com/builders) (profile card + leaderboard), or `/builder-start` (shows your credit total).
-- **The diagram:** [`diagrams/03-example-karma.png`](diagrams/03-example-karma.png) — sources and sinks at a glance.
+- **The diagram:** [`diagrams/03-drachmae-karma.png`](diagrams/03-drachmae-karma.png) — sources and sinks at a glance.
 - **The decisions:** [ADR 0054](../adr/0054-session-token-reward-cost-plus.md) (cost-plus reward), [ADR 0023](../adr/0023-kind-multipliers-and-idea-bonus.md) (kind multipliers + idea bonus), [ADR 0028](../adr/0028-honest-llm-spend-accounting.md) (token→USD pricing).
 - **The code:** `src/bongos/db.js` (`REWARD_MARGIN_PCT`, `KIND_MULTIPLIERS`, `computeSessionTokenReward`), `src/bongos/llm-pricing.js` (pricing), `src/bongos/cost.js` (budget cap), `src/bongos/bfg.js` (builder strength).

package/docs/onboarding/primer.md

@@ -10,7 +10,7 @@ When you're done, open [/builders](https://example.com/builders) and run `/build
 
 ## What this project is
 
-This primer teaches the **platform** — how you claim work and ship it, the same on every Cloud Bongos instance. *What* you're building here — the product, its world, and its visual style — is specific to this instance and lives in **[`docs/project-context.md`](../project-context.md)**. Read that first for the product; everything below is the build system you'll use to make it.
+This primer teaches the **platform** — how you claim work and ship it, the same on every Cloud Bongos instance. *What* you're building here — the product, its world, and its visual style — is specific to this instance and lives in **[`docs/project-context.template.md`](../project-context.template.md)**. Read that first for the product; everything below is the build system you'll use to make it.
 
 ## What Bongos is
 

package/docs/recipes/README.md

@@ -16,7 +16,7 @@ A "recipe" is not a limitation (something the project cannot do). It is a multi-
 ## What does not go here
 
 - Architectural decisions → [`docs/adr/`](../../docs/adr/)
-- Things the project cannot do → [`limitations/`](../../limitations/)
+- Things the project cannot do → `limitations/` (instance-side)
 - Things stuck on the prompter's input → the blockers queue (`POST /api/gds/blockers`, reviewed via `/blocker-review`)
 
 ## Read order while working

package/docs/recipes/bongos-cli-release.md

@@ -12,11 +12,11 @@ deliberate operator step.
 | Piece | Where | Role |
 |---|---|---|
 | Build wrapper | [`scripts/gds/build-bongos.js`](../../scripts/gds/build-bongos.js) | `bun build --compile` → per-platform binaries in `dist/` |
-| CI | [`.github/workflows/build-bongos-cli.yml`](../../.github/workflows/build-bongos-cli.yml) | runs the wrapper, uploads `bongos-cli-binaries` artifacts (no publish) |
-| Release pointer | [`config/bongos-cli.json`](../../config/bongos-cli.json) | `releases_repo` + `version` + per-target asset filenames |
+| CI | `.github/workflows/build-bongos-cli.yml` (instance-side) | runs the wrapper, uploads `bongos-cli-binaries` artifacts (no publish) |
+| Release pointer | `config/bongos-cli.json` (instance-side) | `releases_repo` + `version` + per-target asset filenames |
 | Redirects | [`src/bongos-downloads.js`](../../src/bongos-downloads.js) → `/downloads/bongos/*` in [`serve-internal.js`](../../src/bongos/serve-internal.js) | `/downloads/bongos/<target>` 302s to the release asset; `/version` + `/latest.json` for update-checks |
-| Installer | [`infra/bongos-install.sh`](../../infra/bongos-install.sh) + [`.ps1`](../../infra/bongos-install.ps1) | served (origin-pinned) at `/downloads/bongos/install.sh` / `.ps1` |
-| Package managers | [`packaging/homebrew/bongos.rb`](../../packaging/homebrew/bongos.rb), [`packaging/scoop/bongos.json`](../../packaging/scoop/bongos.json) | brew/scoop templates (fill sha256 at release) |
+| Installer | `infra/bongos-install.sh` + `.ps1` (instance-side) | served (origin-pinned) at `/downloads/bongos/install.sh` / `.ps1` |
+| Package managers | `packaging/homebrew/bongos.rb`, `packaging/scoop/bongos.json` (instance-side) | brew/scoop templates (fill sha256 at release) |
 
 ## What the user runs
 

package/docs/recipes/core-release-pipeline.md

@@ -62,7 +62,7 @@ node -e "console.log(require('./scripts/gds/publish-manifest').isPublishable('do
 
 The ordinary claim→ship loop: `/builder-claim N` → build → `/builder-ship`. That chains `completed` → `confirmed` → `shipped`, and credits land at `shipped` ([ADR 0120](../adr/0120-pay-on-land-and-builder-owned-rebase-gate.md)).
 
-Landing is CI-gated (tasks 1002610/1002611/1002619, ADR 0159): every PR runs the **`unit`** check — the DB-free suite plus the fitness gates, via `npm test` — and branch protection **requires** it, so a red suite blocks the merge. PRs touching the hard-floor safety surfaces ([`CODEOWNERS`](../../CODEOWNERS)) additionally need the owner's review. The owner kill-switch is `node scripts/gds/gating.js on|off|status` — reversible by construction, snapshot-restored.
+Landing is CI-gated (tasks 1002610/1002611/1002619, ADR 0159): every PR runs the **`unit`** check — the DB-free suite plus the fitness gates, via `npm test` — and branch protection **requires** it, so a red suite blocks the merge. PRs touching the hard-floor safety surfaces (`CODEOWNERS` (instance-side)) additionally need the owner's review. The owner kill-switch is `node scripts/gds/gating.js on|off|status` — reversible by construction, snapshot-restored.
 
 **Stop here and nothing happens to any user.** This is the gate that feels like the finish line and is not.
 
@@ -138,7 +138,7 @@ The mechanics of the bump itself — pre-flight, pin-verify, migrate, `.claude/`
 
 Also: an instance can have **more than one plane to update** (e.g. a web instance plus a control plane that resolves its tooling from its own vendored core). Updating one does not update the other.
 
-**Worked example — cloudbongos.com (task 1002621).** The web instance moved off `file:vendor/...` onto a bare registry pin (`bongos upgrade --to <v> --registry --force`, then commit+push `package.json`/`package-lock.json`/`.npmrc` — no tarball) and is enrolled in [`config/update-subscriptions.json`](../../config/update-subscriptions.json) on the `patch` channel, with the `core-update-subscription` routine armed via a dedicated systemd timer on the control-plane box (daily; see [upgrading-the-core](upgrading-the-core.md) for the generic enroll/arm steps). The deploy service's `npm ci` and the routine's `npm view` both authenticate via a root-owned `NPM_TOKEN` env file wired in through each unit's `EnvironmentFile` — a read-only token never committed to any repo. The control plane's own tooling pin is a separate, not-yet-migrated plane (see above).
+**Worked example — cloudbongos.com (task 1002621).** The web instance moved off `file:vendor/...` onto a bare registry pin (`bongos upgrade --to <v> --registry --force`, then commit+push `package.json`/`package-lock.json`/`.npmrc` — no tarball) and is enrolled in `config/update-subscriptions.json` (instance-side) on the `patch` channel, with the `core-update-subscription` routine armed via a dedicated systemd timer on the control-plane box (daily; see [upgrading-the-core](upgrading-the-core.md) for the generic enroll/arm steps). The deploy service's `npm ci` and the routine's `npm view` both authenticate via a root-owned `NPM_TOKEN` env file wired in through each unit's `EnvironmentFile` — a read-only token never committed to any repo. The control plane's own tooling pin is a separate, not-yet-migrated plane (see above).
 
 ---
 
@@ -327,7 +327,7 @@ Exit codes: `0` aligned, `1` diverged, `2` undetermined.
 
 | Act | Gate | Who |
 |---|---|---|
-| Land a change on `main` | 1 | any builder holding a claim, behind the required `unit` check (protected paths are Metic+; hard-floor paths need owner review per [`CODEOWNERS`](../../CODEOWNERS); [canonical-permissions](../canonical-permissions.md)) |
+| Land a change on `main` | 1 | any builder holding a claim, behind the required `unit` check (protected paths are Metic+; hard-floor paths need owner review per `CODEOWNERS` (instance-side); [canonical-permissions](../canonical-permissions.md)) |
 | Bump `CORE_VERSION` | 2a | a builder, inside a claimed task |
 | Build the artifact | 2b | any builder — `package-core` is tokenless and network-free |
 | Publish to npm | 2c | **automatic on merge** once the owner arms the lane ([ADR 0161](../adr/0161-publish-on-merge.md)); the manual `--publish --live` fallback stays owner-only |

package/docs/recipes/instance-deploy.md

@@ -1,13 +1,13 @@
 # Recipe — deploying a Cloud Bongos instance on a pinned core (`git reset` → `npm ci`)
 
-> ADR [0108](../adr/0108-instance-composition-configurable-root.md) §4 (configurable-root W4, task [#1884](https://example.com/builders#/task/1884)). How a **consumer instance** — one that installs `@bongos/core` as a versioned npm dependency rather than living in the monorepo — deploys. This is the target the live droplet deploy converts to; the reference implementation is [`scripts/deploy/deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh).
+> ADR [0108](../adr/0108-instance-composition-configurable-root.md) §4 (configurable-root W4, task [#1884](https://example.com/builders#/task/1884)). How a **consumer instance** — one that installs `@bongos/core` as a versioned npm dependency rather than living in the monorepo — deploys. This is the target the live droplet deploy converts to; the reference implementation is `scripts/deploy/deploy-instance.sh` (instance-side).
 
 ## The two models
 
 | | Pre-split (today, `example`) | Post-split (consumer instance) |
 |---|---|---|
 | Core code | in-tree (the monorepo) | `node_modules/@bongos/core` (a pinned version) |
-| Deploy | [`deploy-prod.sh`](../../scripts/deploy/deploy-prod.sh): `git reset --hard origin/main` on a shared checkout | [`deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh): `git pull` the instance repo → `npm ci` → migrate → restart |
+| Deploy | `scripts/deploy/deploy-prod.sh` (instance-side): `git reset --hard origin/main` on a shared checkout | `scripts/deploy/deploy-instance.sh` (instance-side): `git pull` the instance repo → `npm ci` → migrate → restart |
 | Upgrade the core | (n/a — one tree) | bump the pin in `package.json` → `npm ci` → migrate → restart (ADR 0108 §4; the R86 channel, task [#1690](https://example.com/builders#/task/1690)) |
 | `cloudbongos.com` | a 2nd service on the **same** checkout (why it ran stale) | its **own** consumer repo + its own `deploy-instance.sh` |
 

package/docs/recipes/ops-gotchas.md

@@ -23,7 +23,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
   ```
   (Or set `PGHOST=/var/run/postgresql` in the environment.) That directory is the Debian/Ubuntu default Postgres socket location; on other distros it may differ.
 - **Why it bites:** The `pg` library's defaults assume a standard TCP+password setup, which is the most common configuration but not the cheapest one for a single-machine deploy. Peer auth is more secure and frictionless once you know the socket path. The error message points at SASL, not at the host setting, which buries the real cause.
-- **Where this lives in the codebase:** [`src/db.js`](../../src/db.js) has the explicit socket host.
+- **Where this lives in the codebase:** [`src/bongos/pool.js`](../../src/bongos/pool.js) has the explicit socket host.
 
 ### Re-provisioning an EXISTING instance moves its `HOME`, orphaning any stored builder secrets
 
@@ -170,7 +170,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 - **Behavior (V3.R59 [#278](https://example.com/builders#/task/278)):** `.env.local` is gitignored, so `git worktree add` does not carry it over. The `SessionStart` hook [`.claude/hooks/session-start.js`](../../.claude/hooks/session-start.js) copies it from the main checkout into the worktree on first session — no manual `cp` from a sibling needed.
 - **If the main checkout has no `.env.local`:** the hook tells you to run `/builder-setup`.
-- **The Google AI Studio key is separate:** it resolves from `~/.config/otb/env`, which already survives worktree churn — see [`art/pipeline/gen_api.py`](../../art/pipeline/gen_api.py).
+- **The Google AI Studio key is separate:** it resolves from `~/.config/otb/env`, which already survives worktree churn — see `art/pipeline/gen_api.py` (instance-side).
 - **All hooks run via `node`, not `bash` ([#671](https://example.com/builders#/task/671)):** `SessionStart`, `UserPromptSubmit`, and `Stop` run identically on Windows/macOS/Linux. `session-start.js` chains the env-copy + onboarding + rank-change greeting + memory pull that the old `sync-env-local.sh` shell chain ran.
 
 ---

package/docs/recipes/search-index-ingestion.md

@@ -14,7 +14,7 @@ How the `search_chunks` index (the recall layer, [ADR 0060](../adr/0060-gds-retr
 
 ## When it runs
 
-A **non-blocking step in the prod deploy** ([`scripts/deploy/deploy-prod.sh`](../../scripts/deploy/deploy-prod.sh), mirrored in the droplet's hand-maintained `~/deploy.sh`), after the code update + migrations + healthz, where the new markdown and the DB are both on disk. It's wrapped `timeout 60 … || echo "…deploy unaffected"` — **an ingest failure never fails a deploy**; the next deploy (or a manual run) catches up.
+A **non-blocking step in the prod deploy** (`scripts/deploy/deploy-prod.sh` (instance-side), mirrored in the droplet's hand-maintained `~/deploy.sh`), after the code update + migrations + healthz, where the new markdown and the DB are both on disk. It's wrapped `timeout 60 … || echo "…deploy unaffected"` — **an ingest failure never fails a deploy**; the next deploy (or a manual run) catches up.
 
 > ⚠️ `scripts/deploy/deploy-prod.sh` is a **byte-faithful mirror** of the droplet's `~/deploy.sh`, which is **hand-maintained and NOT auto-installed** (the ci deploy key is forced-command-locked — [ADR 0042](../adr/0042-builder-self-deploy-ci-auto-merge.md)/[0043](../adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md)). When you change the mirror, **re-apply the same edit to `~/deploy.sh` on the droplet by hand** (`ssh lars@REDACTED_IP`), or the deploy hook won't actually run there. (Same caveat as the [prod deploy-script mirror](../../docs/recipes/ops-gotchas.md) note.)
 
@@ -46,7 +46,7 @@ Security ([ADR 0060](../adr/0060-gds-retrieval-layer.md) §6 / [ADR 0016](../adr
 - **`vulnerability_reports` + `security_reports` are excluded entirely** — raw security findings don't belong in a broadly-searchable index.
 - **Session/memory/grade text is scrubbed** through `ship.js` `scrubSecrets` (known shapes + high-entropy) before storage — the index must never hold a leaked credential.
 
-It runs on a **nightly systemd timer** ([`infra/search-index-db.timer`](../../infra/search-index-db.timer) → [`infra/search-index-db.service`](../../infra/search-index-db.service), 03:30 UTC, 30 min before the pg_dump so they don't contend), modeled on `gds-db-backup`. DB prose changes more slowly than docs, so nightly is fresh enough; the repo-md half stays intra-day via the deploy hook.
+It runs on a **nightly systemd timer** (`infra/search-index-db.timer` → `infra/search-index-db.service` (instance-side), 03:30 UTC, 30 min before the pg_dump so they don't contend), modeled on `gds-db-backup`. DB prose changes more slowly than docs, so nightly is fresh enough; the repo-md half stays intra-day via the deploy hook.
 
 **Operator install (one-time, on the droplet):**
 

package/docs/recipes/upgrading-the-core.md

@@ -89,7 +89,7 @@ The sections above are the *manual* `bongos upgrade`. The **subscription** runs
 
 A **major** is never automatic; prereleases are never auto-targeted.
 
-**Enrolling an instance** — add it to [`config/update-subscriptions.json`](../../config/update-subscriptions.json) (ships empty). `env` carries per-instance vars merged into the upgrade child — set `PGDATABASE` so `migrate` hits the right DB (see the Gotchas):
+**Enrolling an instance** — add it to `config/update-subscriptions.json` (instance-side) (ships empty). `env` carries per-instance vars merged into the upgrade child — set `PGDATABASE` so `migrate` hits the right DB (see the Gotchas):
 
 ```json
 {

package/modules/autonomy/gauge.js

@@ -0,0 +1,218 @@
+'use strict';
+
+// modules/autonomy/gauge.js — the Autobongos usage gauge (task 1003901, goal
+// 1000119, criterion wa11-unattended-ship; design of record ADR 0307 §2).
+//
+// WHAT THIS READS, AND WHY IT CANNOT JUST ASK. There is no `claude usage`
+// command and nothing on disk caches remaining subscription capacity. The one
+// structured read is the statusLine hook's input JSON, which Claude Code feeds a
+// status script on every render:
+//
+//   rate_limits.five_hour.{ used_percentage, resets_at }
+//   rate_limits.seven_day.{ used_percentage, resets_at }     resets_at = epoch SECONDS
+//
+// Anthropic's own note on the field: "Only present for subscribers after first
+// API response." So the gauge CANNOT BE READ COLD — there is no way to ask "how
+// much is left" before a session has already started spending. The mechanism is
+// therefore a writer (autonomy-gauge-statusline.js) that PERSISTS both windows
+// on every render, and this reader, which the supervisor consults between tasks.
+//
+// THE RULE THAT MAKES IT SAFE: a gauge we cannot vouch for is UNKNOWN, never
+// HEADROOM. A stale file, a missing file, a malformed file and a file with no
+// rate_limits block all decide the same way — hold. Treating absence as "plenty
+// left" is the one failure that spends a window it does not have, and it is the
+// failure a missing file looks most like.
+//
+// PURE. No I/O, no clock of its own — `now` is always injected. The readers that
+// touch disk live in the CLI (scripts/gds/autonomy-gauge.js), the same split
+// autonomy-gate.js draws between `decide` and `gatherSignals`.
+
+const WEEK_SECONDS = 7 * 24 * 60 * 60;
+
+// A gauge older than this is not evidence. The five-hour window moves fast
+// enough that a half-hour-old reading can be wrong by a lot, and the writer
+// refreshes on every statusline render (seconds apart while a session runs), so
+// anything this old means no session has run for a while — exactly when the
+// number is least trustworthy.
+const DEFAULT_STALE_AFTER_S = 1800;
+
+// Reserve = capacity deliberately left unspent, in percentage points.
+//
+// It exists for exactly two reasons, and neither is thrift:
+//   1. NOT DYING AT 99%. A worker killed mid-task by the limit is wasted work
+//      with a held claim, so we stop starting tasks while a task's worth of room
+//      remains. Until the ledger can say what a task costs, this is a constant.
+//   2. NOT THROTTLING THE OWNER. The runner and the owner draw on the SAME
+//      five-hour window. Overnight that does not matter and the reserve drops to
+//      near zero — the whole point is to spend the idle capacity. During the
+//      owner's working hours it matters a great deal.
+const DEFAULT_CONFIG = {
+  staleAfterS: DEFAULT_STALE_AFTER_S,
+  timezone: 'America/New_York',
+  ownerHours: { start: 8, end: 20 },   // local, [start, end)
+  reserve: { working: 25, overnight: 2 },
+  // Seven-day slack, in percentage points above an even pace. Bursting is fine;
+  // running a week's allowance down by Wednesday is not.
+  weeklySlack: 15,
+};
+
+function cfg(overrides = {}) {
+  return {
+    ...DEFAULT_CONFIG,
+    ...overrides,
+    ownerHours: { ...DEFAULT_CONFIG.ownerHours, ...(overrides.ownerHours || {}) },
+    reserve: { ...DEFAULT_CONFIG.reserve, ...(overrides.reserve || {}) },
+  };
+}
+
+// localHour — the owner's wall-clock hour, which is what "overnight" means.
+// Deterministic given (now, timezone): Intl resolves the offset including DST,
+// so this needs no zone table and cannot drift twice a year.
+const HOUR_FORMATTERS = new Map();   // per-timezone; building one per call is pure waste
+function hourFormatter(timezone) {
+  let f = HOUR_FORMATTERS.get(timezone);
+  if (!f) {
+    f = new Intl.DateTimeFormat('en-US', { timeZone: timezone, hour: 'numeric', hour12: false });
+    HOUR_FORMATTERS.set(timezone, f);
+  }
+  return f;
+}
+
+function localHour(nowEpochS, timezone) {
+  try {
+    const h = hourFormatter(timezone).format(new Date(nowEpochS * 1000));
+    const n = Number(h);
+    return Number.isFinite(n) ? (n % 24) : null;
+  } catch (_) {
+    return null;   // an unknown zone must not throw; fall back to the cautious branch
+  }
+}
+
+// reserveFor — how much five-hour capacity to hold back right now, and why.
+// An unresolvable hour takes the WORKING reserve: the cautious side, because
+// guessing "overnight" wrongly is what throttles the owner mid-afternoon.
+function reserveFor(nowEpochS, config = {}) {
+  const c = cfg(config);
+  const hour = localHour(nowEpochS, c.timezone);
+  if (hour === null) {
+    return { pct: c.reserve.working, window: 'working', why: `timezone ${c.timezone} unresolvable — holding the working-hours reserve` };
+  }
+  const { start, end } = c.ownerHours;
+  // A window that wraps midnight (e.g. 20→8) is still one contiguous span.
+  const working = start <= end ? (hour >= start && hour < end) : (hour >= start || hour < end);
+  return working
+    ? { pct: c.reserve.working, window: 'working', why: `${hour}:00 ${c.timezone} is inside the owner's hours (${start}-${end})` }
+    : { pct: c.reserve.overnight, window: 'overnight', why: `${hour}:00 ${c.timezone} is outside the owner's hours (${start}-${end}) — spend it` };
+}
+
+// readGauge — normalize a parsed gauge file into evidence or a named absence.
+// Every failure shape collapses to { known: false, reason }, because they all
+// decide identically and a caller that has to enumerate them will miss one.
+function readGauge(raw, nowEpochS, config = {}) {
+  const c = cfg(config);
+  if (!raw || typeof raw !== 'object') return { known: false, reason: 'no gauge file — the statusline writer has never run' };
+
+  const writtenAt = Number(raw.written_at);
+  if (!Number.isFinite(writtenAt)) return { known: false, reason: 'gauge file has no readable written_at' };
+
+  const ageS = nowEpochS - writtenAt;
+  if (ageS > c.staleAfterS) {
+    return { known: false, ageS, reason: `gauge is ${Math.round(ageS / 60)}m old (stale after ${Math.round(c.staleAfterS / 60)}m) — unknown, not headroom` };
+  }
+  // A clock that ran backwards is not evidence either.
+  if (ageS < -60) return { known: false, ageS, reason: 'gauge is dated in the future — clock skew, treating as unknown' };
+
+  // STALENESS IS PER WINDOW, not per file. The writer carries a window forward
+  // when a render does not report it (so a transient absence cannot destroy the
+  // seven-day reading the pacing depends on), and a carried window keeps its own
+  // `observed_at`. Ageing the file as a whole would let that carried value ride
+  // on a fresh written_at forever — "unknown" quietly becoming "headroom".
+  // Files written before observed_at existed fall back to written_at, which is
+  // exactly what they meant.
+  const win = (w) => {
+    const o = raw[w];
+    if (!o || typeof o !== 'object') return null;
+    const used = Number(o.used_percentage);
+    const resets = Number(o.resets_at);
+    if (!Number.isFinite(used) || !Number.isFinite(resets)) return null;
+    const observedAt = Number.isFinite(Number(o.observed_at)) ? Number(o.observed_at) : writtenAt;
+    if (nowEpochS - observedAt > c.staleAfterS) return null;   // this half is no longer evidence
+    return { used, resetsAt: resets, observedAt, ageS: nowEpochS - observedAt };
+  };
+  const fiveHour = win('five_hour');
+  const sevenDay = win('seven_day');
+
+  // Both windows are optional in the source ("may be absent"), but with neither
+  // there is nothing to decide on.
+  if (!fiveHour && !sevenDay) {
+    return { known: false, ageS, reason: 'gauge carries no window fresh enough to use — absent or aged out' };
+  }
+  return { known: true, ageS, fiveHour, sevenDay };
+}
+
+// weeklyPace — the share of the seven-day allowance an even burn would have
+// reached by now, plus slack. Derived from resets_at rather than a stored start,
+// so it needs no second source of truth for when the week began.
+function weeklyPace(sevenDay, nowEpochS, config = {}) {
+  const c = cfg(config);
+  const remainingS = Math.max(0, sevenDay.resetsAt - nowEpochS);
+  const elapsedFraction = Math.min(1, Math.max(0, 1 - remainingS / WEEK_SECONDS));
+  return { elapsedFraction, allowedPct: elapsedFraction * 100 + c.weeklySlack };
+}
+
+// whenPaceAllows — the epoch second at which an even burn catches up with what
+// has already been spent. The inverse of weeklyPace: this is what turns "you are
+// ahead of pace" into a time to wake up, instead of a poll loop.
+function whenPaceAllows(sevenDay, config = {}) {
+  const c = cfg(config);
+  const neededFraction = Math.min(1, Math.max(0, (sevenDay.used - c.weeklySlack) / 100));
+  return Math.ceil(sevenDay.resetsAt - WEEK_SECONDS * (1 - neededFraction));
+}
+
+// decideCapacity — the whole gauge question in one pure call:
+// may the supervisor start another task right now, and if not, until when.
+//
+// Order is deliberate. Unknown first (we cannot reason at all). Then the
+// seven-day pace, because the week is the binding constraint on a heavy run and
+// a five-hour window that looks fine can still be the one that burns the week.
+// Then the five-hour reserve.
+function decideCapacity({ gauge, now, config = {} } = {}) {
+  const c = cfg(config);
+  const g = readGauge(gauge, now, c);
+
+  if (!g.known) return { go: false, unknown: true, sleepUntil: null, reason: g.reason };
+
+  if (g.sevenDay) {
+    const pace = weeklyPace(g.sevenDay, now, c);
+    if (g.sevenDay.used >= 100) {
+      return { go: false, unknown: false, sleepUntil: g.sevenDay.resetsAt, window: 'seven_day',
+        reason: `seven-day window spent (${g.sevenDay.used.toFixed(1)}%) — sleeping to its reset` };
+    }
+    if (g.sevenDay.used > pace.allowedPct) {
+      const until = whenPaceAllows(g.sevenDay, c);
+      // Never propose a wake in the past, and never past the reset itself.
+      const sleepUntil = Math.min(Math.max(until, now + 1), g.sevenDay.resetsAt);
+      return { go: false, unknown: false, sleepUntil, window: 'seven_day',
+        reason: `seven-day burn ${g.sevenDay.used.toFixed(1)}% is ahead of pace (${pace.allowedPct.toFixed(1)}% allowed at ${(pace.elapsedFraction * 100).toFixed(0)}% through the week) — holding so the week does not go dark` };
+    }
+  }
+
+  if (g.fiveHour) {
+    const reserve = reserveFor(now, c);
+    const ceiling = 100 - reserve.pct;
+    if (g.fiveHour.used >= ceiling) {
+      return { go: false, unknown: false, sleepUntil: g.fiveHour.resetsAt, window: 'five_hour',
+        reason: `five-hour burn ${g.fiveHour.used.toFixed(1)}% is at or past the ${ceiling}% ceiling (${reserve.window} reserve ${reserve.pct}%: ${reserve.why}) — sleeping to its reset` };
+    }
+  }
+
+  const bits = [];
+  if (g.fiveHour) bits.push(`5h ${g.fiveHour.used.toFixed(1)}%`);
+  if (g.sevenDay) bits.push(`7d ${g.sevenDay.used.toFixed(1)}%`);
+  return { go: true, unknown: false, sleepUntil: null, reason: `headroom (${bits.join(', ')}; gauge ${Math.round(g.ageS)}s old)` };
+}
+
+module.exports = {
+  decideCapacity, readGauge, reserveFor, weeklyPace, whenPaceAllows, localHour,
+  cfg, DEFAULT_CONFIG, WEEK_SECONDS, DEFAULT_STALE_AFTER_S,
+};

package/modules/dev-box/app/README.md

@@ -35,7 +35,7 @@ What it does beyond the switch — each fixing a failure observed in the
   and, when the published release is strictly newer, shows the Update banner; the
   Update button downloads the installer and hands it to the OS (browser-download
   fallback on any error). **Bumping `config/devbox-app.json` version is what makes
-  the banner appear in the field** — see [`docs/recipes/devbox-app-release.md`](../docs/recipes/devbox-app-release.md).
+  the banner appear in the field** — see [`docs/recipes/devbox-app-release.md`](../../../docs/recipes/devbox-app-release.md).
 - `renderer/` — the panel UI (sandboxed, contextIsolated; preload exposes
   named verbs only).
 - `scripts/gen-icons.js` — regenerates all icons from pixel grids (`npm run

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -323,6 +323,10 @@ function createClient(opts = {}) {
       // GET /copy-desk/strings — rank: any-builder — GET /copy-desk/strings
       getCopyDeskStrings: (args) => request("GET", "/copy-desk/strings", { hasBody: false }, args),
     },
+    "coreUpdate": {
+      // GET /core-update — rank: archon — GET /core-update
+      getCoreUpdate: (args) => request("GET", "/core-update", { hasBody: false }, args),
+    },
     "cost": {
       // POST /cost — rank: any-builder — POST /cost
       postCost: (args) => request("POST", "/cost", { hasBody: true }, args),