@bongos/core 1.19.830 → 1.19.832

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.830",
-  "core_contract": "1.19.830",
-  "source_commit": "f052e69e7ed4925bc7578f461eed7f296c70bc24",
+  "core_version": "1.19.832",
+  "core_contract": "1.19.832",
+  "source_commit": "c8e1d760c29ed41a5d66af6b1c4f9936a7fd0f32",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T14:39:41.882Z",
+  "built_at": "2026-09-17T15:29:22.894Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 491,
+    "docs_redacted": 492,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2242,
+    "functional_verbatim": 2244,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2759,
-  "tree_sha256": "07ddb7b8f4644eedae95fe56586daa10e5e895b3dd6304e8239da98e8151097c",
+  "file_count": 2762,
+  "tree_sha256": "0795b0e4670053ed5c638dac4719252988b0dbfd0d863dafef3df5b466a11f45",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -407,7 +407,7 @@
     {
       "path": "docker-compose.yml",
       "mode": "0000644",
-      "sha256": "1742d8f1fe0795a1b1396e0e59b17bb324cba1101cb89b17336a866a34eeddd1"
+      "sha256": "098a2645a43876141b6c711362c2a93e134d1de7533cb6e17de9e80ccfb1327e"
     },
     {
       "path": "docker-entrypoint.sh",
@@ -1984,10 +1984,15 @@
       "mode": "0000644",
       "sha256": "f52bf2568d02d5cf8589dc394dc76cbf0ea3a7ba193275f300e320c2ab64a51c"
     },
+    {
+      "path": "docs/adr/0300-a-missing-protected-surface-registry-is-a-broken-install.md",
+      "mode": "0000644",
+      "sha256": "7c5d4c49dc98d37a8a41aa0cddd158c3a46a60cdb4e79b018d68c6b5222b7e79"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "0b4e0cd78a8bd6ae3d41c0d010634dfdc29ecd4dca1f8b49127791d1b4cd7450"
+      "sha256": "8af8b8c5ea9b368bb790280eadd167b99ed9f864350e101ba18a4b0ec8f5ed5e"
     },
     {
       "path": "docs/api-reference.md",
@@ -2552,7 +2557,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "bb0d3a828688ed757efe4e321907837a4c15754b4ab72baaa31b88eca7b0a7c4"
+      "sha256": "02d7156a9ee2a022e71835b03c120059c44b36cf9358085bf2c2d1fb91a72bd4"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2782,7 +2787,7 @@
     {
       "path": "docs/recipes/self-host.md",
       "mode": "0000644",
-      "sha256": "8f97eeefdd7e2e0bd15ff066a7a7ab10378716182bbcc494ef0bdde1fd7c3f2b"
+      "sha256": "2108b55f6e3264af35c2db885b5a98ff8cc9a5c5c68881d3f5ce8037db1bf159"
     },
     {
       "path": "docs/recipes/server-bring-up.md",
@@ -7837,12 +7842,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "86518fa351500812c81035964030dba99e78a1e75d8c4a1e584c13b5a96d4f7d"
+      "sha256": "f833d910fdbed07c2c2a6a1597d5d6315780e4633c6015bde77629b7682f8c8d"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "a61e5b17236e35d52bd8047254f0c40a0dc9cb1eeb6c836905d1cb8e9787e18f"
+      "sha256": "6fd9cd7067b463895344e6de0710ce6eda471f96d659161c56f9ce3cc9c0edb1"
     },
     {
       "path": "public-docs/index.html",
@@ -9467,7 +9472,7 @@
     {
       "path": "src/bongos/auth-admission.js",
       "mode": "0000644",
-      "sha256": "27b9f2ed74d5abbf8dade5199da278fe758c0e6472fbdb1d280bfbb9c24e4596"
+      "sha256": "2d11e7b745a0476fa0643fd997c2e17a49709bae1ef93a7c4636f7efd18c7ab0"
     },
     {
       "path": "src/bongos/auth-config.js",
@@ -9492,7 +9497,7 @@
     {
       "path": "src/bongos/auth.js",
       "mode": "0000644",
-      "sha256": "0cfc14e764b04d21b710278132ed35a297417954b1200db0db7f61ece224a389"
+      "sha256": "7e9b3c48e6d4bc3e0370e6ff4dba799691abeb02181d8910d0807651656f7d7e"
     },
     {
       "path": "src/bongos/cascade-dispatch.js",
@@ -9507,7 +9512,7 @@
     {
       "path": "src/bongos/db-kernel.js",
       "mode": "0000644",
-      "sha256": "e9a566e63b95225e3ee15331424af831875f75b5ea977c73f077bb50f46c4c6b"
+      "sha256": "1fffc39fb9b70cd009d7d239729a9ff329cd41ca1f35b50b7c9e6b89aa83624e"
     },
     {
       "path": "src/bongos/db.js",
@@ -9592,7 +9597,7 @@
     {
       "path": "src/bongos/permission-path-check.js",
       "mode": "0000644",
-      "sha256": "14ba2ffb603cbea7d8388c196b74f8e7db92b777fb0da7c69c7d3c7c9e27f386"
+      "sha256": "75264cfa68b2a8344c38565d96d16c28e101d286ad0b5794baa83ab774269d74"
     },
     {
       "path": "src/bongos/platform-visibility-gate.js",
@@ -9652,7 +9657,7 @@
     {
       "path": "src/bongos/routes/auth.js",
       "mode": "0000644",
-      "sha256": "40ff17b595791bf6a8c7ae1cd17c54d8ce5cc6fa805622fd8fbc2dc2c398c961"
+      "sha256": "66abf424a565cdcc4de85350774d91e93be826a3b01a23ad75fee1feb7977a3c"
     },
     {
       "path": "src/bongos/routes/backup.js",
@@ -9762,7 +9767,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a717714b35118b907e81f90fdb5e10be2e85552d8abfd8463f70da6b1f07274a"
+      "sha256": "8e0d57c0e24d78b95565b3c81fdae6ca50647ad6f84ea337eed213109594056e"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10544,6 +10549,11 @@
       "mode": "0000644",
       "sha256": "3f9e3ea6d2b88cd6592ba7b0575908eb020a072e6ccdb8cdf908bfba65b5191c"
     },
+    {
+      "path": "tests/compose_demo_credentials.mjs",
+      "mode": "0000644",
+      "sha256": "1d625746b022de4f4e23ce071e276ce5758e048f5997fce690ac8e301b6c6721"
+    },
     {
       "path": "tests/conductor.mjs",
       "mode": "0000644",
@@ -10969,6 +10979,11 @@
       "mode": "0000644",
       "sha256": "8006f4696e6bae21b84c9e8ec25cb7a7d34c5899f187d2ac59b2a6dcbb6f92d1"
     },
+    {
+      "path": "tests/first_admin_unset_signin.mjs",
+      "mode": "0000644",
+      "sha256": "88b3d0c7fb278e560850f440ec6721655efb62bcafcd983deb7e9ddb25103b65"
+    },
     {
       "path": "tests/first_run_engine_check.mjs",
       "mode": "0000644",
@@ -11367,7 +11382,7 @@
     {
       "path": "tests/government_protected_surfaces.mjs",
       "mode": "0000644",
-      "sha256": "4478853e79266130c2ad3ab7a523f0f20fb98a97e88f1dd2476ef09db6b96dcc"
+      "sha256": "1d8502e8d25eedb54ed0fcbe3ce1a0fe87495d03bd8bda7322e55d6004669a63"
     },
     {
       "path": "tests/government_rank_sync.mjs",

package/docker-compose.yml

@@ -14,7 +14,10 @@ services:
     image: postgres:16-alpine
     environment:
       POSTGRES_USER: cloudbongos
-      POSTGRES_PASSWORD: cloudbongos
+      # Under 8 characters on purpose: the leak scan treats any 8+ character value of a
+      # secret-named variable as a live credential, and this file ships in the core
+      # (task 1002717). The db port is not published; this value never leaves the network.
+      POSTGRES_PASSWORD: demo-pw
       POSTGRES_DB: cloudbongos
     volumes:
       - cloudbongos-db:/var/lib/postgresql/data
@@ -35,7 +38,7 @@ services:
       PGHOST: db
       PGPORT: "5432"
       PGUSER: cloudbongos
-      PGPASSWORD: cloudbongos
+      PGPASSWORD: demo-pw
       PGDATABASE: cloudbongos
       # Bind to all interfaces inside the container so the published port works.
       HOST: 0.0.0.0

package/docs/adr/0300-a-missing-protected-surface-registry-is-a-broken-install.md

@@ -0,0 +1,109 @@
+# ADR 0300 — A missing protected-surface registry is a broken install, not a module opt-out
+
+**Status:** accepted · **Date:** 2026-09-17 · **Task:** [task 1003662](https://cloudbongos.com/builders#/task/1003662) (goal 1000091 — BONGOS-V2)
+
+**Related:** [ADR 0043](0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md) (the protected-surface boundary this registry enforces) · [ADR 0083](0083-modular-architecture-strangler-build-plan.md) (core never depends on a module's behavior) · [ADR 0108](0108-instance-composition-configurable-root.md) §1 (the core is consumed as a versioned npm package, and `modules/` ships inside it)
+
+## Context
+
+[task 1003662](https://cloudbongos.com/builders#/task/1003662) was filed as a bug with a
+concrete remedy attached:
+
+> `require('./module-scope-map')` throws on any checkout where
+> `modules/government/protected-surfaces.json` is absent … This breaks any checkout that has
+> disabled or not yet materialized the government module … Make `module-scope-map.js` degrade
+> gracefully (empty protected set + a loud warning) when the government module isn't present,
+> matching the `resolveOptional` pattern used elsewhere for optional module capabilities.
+
+The throw is real and reproduces exactly as described. Moving the registry aside and requiring
+the kernel file gives:
+
+```
+protected-surface registry unreadable at <root>/modules/government/protected-surfaces.json:
+ENOENT: no such file or directory. Refusing to run with an empty protected set (ADR 0043).
+```
+
+Everything after that first sentence is wrong, in four separate ways — and the remedy it
+proposes would disable the ADR 0043 boundary on exactly the installs least able to notice.
+
+**1. The throw is not in the file the task names.** `module-scope-map.js` contains no `throw`
+and no file read. It does `require('./permission-path-check')` at line 39, and
+`permission-path-check.js`'s `loadRegistry()` throws at module scope. Any "fix" applied to the
+file in the title would be applied to the wrong file; the behavior is owned by its sibling.
+
+**2. The throw is a written contract, not an oversight.** `permission-path-check.js` states it
+in its own header, in capitals, above the code:
+
+> FAIL-CLOSED: a missing/empty/malformed registry THROWS. It never degrades to "nothing is
+> protected" — an unreadable registry is a broken install, not an opted-out module.
+
+The remedy asks for the one behavior the header names and refuses. That header also pre-answers
+the architectural worry the title gestures at (a kernel file reaching into `modules/`): the read
+is `fs`, never `require`, because ADR 0083's one-way rule forbids core from requiring a module's
+*code* — and this is not code, it is a static declarative data file. The sibling trust primitive
+`route-rank-check.js` reads `modules/*/routes/*.js` off disk the same way. Code still flows one
+way; nothing in core requires the module.
+
+**3. Disabling the government module cannot produce the ENOENT.** Module enablement is a
+runtime flag, not a file deletion — disabling a module leaves its files on disk untouched. The
+registry read never consults enablement, deliberately: per the same header, a module's
+enable/disable state must never be something the kernel depends on. So the "disabled" half of
+the premise describes a state that cannot occur.
+
+**4. The "not yet materialized" half does not occur either, because the file ships with the
+core.** `package.json` declares no `files[]` allowlist, so the whole directory ships.
+`npm pack --dry-run` on this commit puts `modules/government/protected-surfaces.json` in the
+tarball at 13,274 bytes, one of 3,419 files. Per [ADR 0108](0108-instance-composition-configurable-root.md)
+§1 the core is consumed as a versioned npm dependency and `resolveCoreRoot()` resolves the core
+package's own `modules/` inside `node_modules`. You cannot have `@bongos/core` without this
+file. If it is absent, the install is damaged — a partial extract, a lossy copy, a `.gitignore`
+that ate a JSON file — and that is a fact worth surfacing loudly, not smoothing over.
+
+**The `resolveOptional` precedent does not transfer.** `resolveOptional` is real and used in
+roughly a dozen places, but it is the module **seam/port resolver**: `api.resolveOptional('grade')`
+lets one module degrade when another module's *runtime capability* is absent, which is exactly
+right for an optional capability. A protected-surface registry is not a capability being
+resolved at a seam. It is the static data the trust boundary is made of, read synchronously from
+disk by enforcers that run where there is no server and no database — a git hook on a laptop, a
+CI job. Borrowing the seam pattern here reads as consistency, but it silently converts "the
+boundary is unreadable" into "there is no boundary".
+
+## Decision
+
+**Fail-closed stays. The registry is not optional, and a missing registry is a broken install.**
+
+Concretely:
+
+1. **No behavior change to `permission-path-check.js` or `module-scope-map.js`.** The throw is
+   correct, its placement is correct, and the header already documents why.
+2. **The task's described remedy is rejected**, on the grounds above — chiefly that an empty
+   protected set is not a degraded mode of a trust boundary, it is the absence of one.
+3. **The error message gains a remediation line.** This is the one genuine defect the report
+   surfaced: the message states the refusal and cites ADR 0043, but never tells the reader what
+   to *do*, which is precisely how a reader concludes the module must be optional and files this
+   task. It now names the likely cause and the fix.
+
+The asymmetry is the whole point. A false "nothing is protected" is silent, permanent, and
+grants authority; a false "this install is broken" is loud, immediate, and grants nothing. Only
+one of those is safe to be wrong about.
+
+## Consequences
+
+**A damaged install fails loudly at require time, and now says what to do about it.** That was
+already true of the first half; the second half is new. The reader who hits this next gets
+pointed at reinstalling the core rather than at weakening the check.
+
+**The report will recur in some form, and that is acceptable.** Anyone meeting this ENOENT
+cold sees a kernel file reaching into `modules/` and reasonably suspects a layering bug. This
+ADR is the durable answer to that suspicion, which is why it exists rather than a won't-fix
+note: the next agent to wonder can be pointed at a number.
+
+**If a legitimate need for a core-only checkout without `modules/` ever appears, this decision
+is the thing to revisit** — and the revisit is "where should the registry live", not "should it
+be optional". Relocating the canonical data into `src/` and having the government module
+contribute to it would preserve fail-closed while removing the cross-directory read. Nothing
+today needs that, and doing it speculatively would move a trust primitive for no gain.
+
+**What this does not decide:** whether other `modules/` reads from core (`route-rank-check.js`
+reading `modules/*/routes/*.js`) should follow the same rule. They share the mechanism and the
+justification, but each is its own trust surface and none is currently in question.

package/docs/adr/README.md

@@ -391,3 +391,4 @@ This keeps the decision history honest and traceable.
 | 0297 | [**A task’s creator may retire it, and that is the ownership axis’s first route** ([task 1002443](https://cloudbongos.com/builders#/task/1002443), goal 1000095 — owner request 2026-07-25: *"the creator of that task should be able to abandon that task directly inside of the UI"*). Attribution itself shipped earlier and elsewhere (`core_227`, [task 1003278](https://cloudbongos.com/builders#/task/1003278)); what had not moved is that **retiring a task was a rank power and nothing else** — `task.abandon` floors at `metic` (ADR 0152), so a sub-Metic builder could file a task and then could not withdraw their own proposal. The model already had the vocabulary and had never used it: ADR 0151 §3 defines an **ownership axis** where a `scope:'own'` key authorizes nothing until a handler supplies the row's owner, R100 made `requirePermission` refuse such a key outright so `.own` can never degrade into `.any`, and it recorded that **zero call sites passed one**. This is that axis’s first real consumer. **Decision: two authorities, only one rank-shaped** — `task.abandon` (metic, any task) OR new `task.abandon.own` (xenos, a task you created, while it is still backlog/ready/blocked). Route becomes `requireBuilder` + an in-handler decision (the `POST /goals/:id/members` shape), pin `metic+archon`→`any-builder` so it now catches an accidental **tightening** as loudly as a gate removal. **The two facts resolve in two places on purpose:** the RANK fact is request-scoped and resolves before the transaction (uncached, ADR 0016); the OWNER fact is a column that can change under us, so `created_by` joins `abandonTask`’s existing `FOR UPDATE` SELECT and a new optional `authorize` callback decides under that lock. Reading `created_by` in the route would be a TOCTOU window; resolving permissions inside the transaction would hold a row lock across a second pool acquire. The decision is a PURE module (`abandon-authz.js`, the `goal-route-authz.js` precedent) so every branch is pinned DB-free and the hall hint and server verdict provably read one rule. **A creator’s window stops at the grader** — completed/confirmed stay cross-owner, because past the grader a retire is a ledger correction, not an author changing their mind; nothing is subtracted from `task.abandon`, pinned by a test. `counterpart: ['task.abandon']` is declared not derived, verb `act` not `manage` — `manage` would silently dominate every future narrower `task.*.own` key (the verb-blind escalation task 1003195 closed). **A null creator belongs to nobody and that is load-bearing:** ~1,357 pre-`core_227` tasks plus seed/restock/discord vectors are unattributed, so the owner comparison is the government resolver’s own — injected, never re-implemented, since a duplicated ownership comparison is how one quietly widens — and one slip would open every historical task to a xenos grant at once. Fail-closed throughout: a missing `government` port, a throwing resolver, and anything but an explicit `{ok:true}` all deny, and `authorize` runs BEFORE the idempotent already-abandoned return and the shipped/active-claim guards so an unauthorized caller cannot probe a row through a 200. No guard removed. Does NOT widen edit/promote/dependency (still Metic), does not touch `task.merge`, and does not backfill attribution — the control simply does not appear on tasks predating `core_227`.](0297-a-tasks-creator-may-retire-it.md) | authority / lifecycle / ownership |
 | 0298 | [**The grader gets a reader lens: advisory, scoped to copy-bearing diffs, and it waits on a written voice** ([task 1003937](https://cloudbongos.com/builders#/task/1003937), goal 1000095 — Working area 6; owner decision 2026-09-17). Every artist review the cascade files opened with *“REVIEW THE GRADER … coach it”*, and it could not be followed: the v4 panel runs narc, quality, hacker and efficiency — completion, code quality, security, runtime cost — and not one of them reads a sentence for whether it is true, clear, in the project’s voice or worth a person’s attention. Four consecutive reviews hit the same wall and all four graded ships deservedly PASSED on the axes that were measured; the gate is not lenient, it is not pointed at this. `grader-prompt.js` already injects the craft’s written responsibility, but only when `discipline === ‘artist’`, so the unjudged case is copy shipped by someone whose craft is not the copy. **Decision: a fifth ADVISORY `reader` worker, on three settled terms.** It runs only where `modules/lifecycle/cascade.js`’s existing `hasCopyOrVisualWork` says the ship is copy-bearing — the same predicate the after-the-fact review uses, so the two can never disagree about coverage, and every other ship costs exactly what it costs today. It records `issues[]` and a `copy_score` and can never verdict `fail` or drag the panel to `concerns`, because [ADR 0241](0241-the-artist-gate-is-a-per-project-deploy-gate-that-reads-a-state.md) put the artist’s judgement on the DEPLOY and off the ship path; gating would need that ADR amended first. And it is NOT BUILT until the instance writes a voice guide — today the whole written standard is one dash rule in `DESIGN.md`, a tagline, a registry of which 1,860 strings exist, and one responsibility sentence, so a lens built now would record taste and call it a finding. Until the reader exists, STEP 1 asks the artist to WRITE DOWN what the grade could not see rather than to coach a lens that is not listening — followable today, and the corpus both the guide and the lens get written from. Nothing in the rubric, the active panel or any existing worker changes.](0298-the-reader-lens-is-advisory-and-waits-on-a-voice-guide.md) | grading / the artist’s loop / voice |
 | 0299 | [**The nod queue stays scoped to routed filings; the backlog walk is the widening** ([task 1003748](https://cloudbongos.com/builders#/task/1003748), goal 1000089). `listRoutedAwaitingNod` filters `origin='route'`, and on 2026-09-08 showed 11 of 232 backlog rows. Re-measured after `/backlog-review` (task 1003746) shipped: 115 backlog rows = 109 dep-gated + 2 spikes (not a person's decision) + 1 stranded + 3 awaiting a nod, all four walked by `/backlog-review`. **Decision: do not widen the card.** The omitted population already has a walkable review with the dependency predicate any widening needed; the copy says *reported* work, so the name is honest; a card slice would be a second copy of the walk's four-bucket partition. Revisit if the un-routed nod bucket outgrows a daily walk (then a count + link, derived from the same partition) or if the walk stops being run.](0299-the-nod-queue-stays-scoped-to-routed-filings.md) | ideas / backlog / attention |
+| 0300 | [**A missing protected-surface registry is a broken install, not a module opt-out** ([task 1003662](https://cloudbongos.com/builders#/task/1003662), goal 1000091). Filed as a bug with a remedy attached: `require('./module-scope-map')` throws when `modules/government/protected-surfaces.json` is absent, so make it degrade to an empty protected set + a warning, matching `resolveOptional`. The throw reproduces, and the rest is wrong four times over. **The throw is not in the named file** — `module-scope-map.js` has no throw and no file read; it requires `permission-path-check.js`, whose `loadRegistry()` throws at module scope. **It is a written contract, not an oversight** — that file's header says FAIL-CLOSED in capitals and already pre-answers the layering worry (the read is `fs`, never `require`, so ADR 0083's one-way rule holds; static data, not code; `route-rank-check.js` reads `modules/*/routes/*.js` the same way). **Disabling the module cannot cause it** — enablement is a runtime flag, never a file deletion, and the read never consults it. **"Not yet materialized" cannot either** — no `files[]` allowlist, so `npm pack --dry-run` puts the 13,274-byte registry in the tarball; per ADR 0108 §1 you cannot have `@bongos/core` without it. The `resolveOptional` precedent does not transfer: that is the module **seam/port** resolver for a missing runtime *capability*, whereas this is the static data the boundary is made of, read where there is no server and no DB (a git hook, a CI job) — borrowing it converts "the boundary is unreadable" into "there is no boundary". **Decision: fail-closed stays, no behavior change, the remedy is rejected — and the one genuine defect is fixed: the message now names the cause and the fix** (reinstall the core; do not empty the set), because stating a refusal without a remedy is exactly how a reader concludes the module is optional and files this task. The asymmetry is the point: a false "nothing is protected" is silent, permanent and grants authority; a false "this install is broken" is loud and grants nothing. Revisit only if a core-only checkout without `modules/` becomes legitimate — and then the question is *where the registry lives*, not whether it is optional.](0300-a-missing-protected-surface-registry-is-a-broken-install.md) | governance / permissions |

package/docs/module-api-changelog.md

@@ -2134,5 +2134,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.828 with no explicit bump. run 35234300466. (task 1002620)
   1.19.830 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.829 with no explicit bump. run 35235005422. (task 1002620)
+  1.19.831 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.830 with no explicit bump. run 35238952391. (task 1002620)
+  1.19.832 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.831 with no explicit bump. run 35240512571. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/self-host.md

@@ -18,6 +18,10 @@ That builds the image, starts Postgres, applies the build-system migrations (gam
 
 To stop and wipe: `docker compose down -v` (the `-v` drops the `cloudbongos-db` volume).
 
+**Before your first sign-in, set `BONGOS_FIRST_ADMIN` to your GitHub login** (in `docker-compose.override.yml`, below). A new instance has no owner to approve anyone, so without it every sign-in is refused, yours included, and the page says so.
+
+**Upgrading from a compose file older than task 1002717?** The demo database password changed from `cloudbongos` to `demo-pw`, and an existing volume keeps the old one. Either wipe it (`docker compose down -v`) or keep your data and update the password in place: `docker compose exec db psql -U cloudbongos -c "ALTER USER cloudbongos PASSWORD 'demo-pw'"`.
+
 ## Branding / configuring your instance
 
 The image is intentionally vanilla. To make it yours, supply your own config at runtime by mounting it over the build:
@@ -35,7 +39,7 @@ Author `config/branding.json` from the neutral starter — see [the branding con
 
 **Or scaffold it with `bongos init`** ([task #1204](https://example.com/builders#/task/1204)): a short interview (or `bongos init --from spec.json` for a hands-free / CI run) that writes both config files, **seeds your first version + its done-when goal**, and **files the human-only kickoff steps** (register a GitHub OAuth app, first owner sign-in, repo binding, admission) as real tracked tasks — so a fresh instance has a claimable queue on day one instead of an empty hall. It never invents your branding (it points you at the fill prompt for that). Preview the whole plan with `bongos init --dry-run`.
 
-**Production hosting, optional (the `provisioning` module — [ADR 0111](../adr/0111-instance-hosting-provisioning-module.md) §3).** If you enable the `provisioning` module and answer the interview's hosting questions (shape — co-tenant `$0` or a dedicated droplet — bring-your-own domain, credential ref, tier), init turns those answers into a real **provisioning request** (a queued `provision` intent the control-plane runner drains) instead of only filing a manual "production topology" task. The two irreducibly-human legs — the GitHub OAuth app and the first owner sign-in — stay guided/manual. If the module isn't enabled on the target instance, init falls back to the manual production-topology task, so nothing is silently skipped.
+**Production hosting, optional (the `provisioning` module — [ADR 0111](../adr/0111-instance-hosting-provisioning-module.md) §3).** If you enable the `provisioning` module and answer the interview's hosting questions (shape — co-tenant `$0` or a dedicated droplet — bring-your-own domain, credential ref, tier), init turns those answers into a real **provisioning request** (a queued `provision` intent the control-plane runner drains) instead of only filing a manual "production topology" task. **A queued request does nothing until a runner drains it:** on the control plane that is a systemd timer running `node scripts/gds/provision.js run-intents --apply`. This Docker image cannot run that today (no git in the image, systemd and a DigitalOcean token assumed; task 1002718), so on a compose self-host a new project waits indefinitely. The two irreducibly-human legs — the GitHub OAuth app and the first owner sign-in — stay guided/manual. If the module isn't enabled on the target instance, init falls back to the manual production-topology task, so nothing is silently skipped.
 
 ## Configuration surface
 
@@ -46,6 +50,8 @@ Author `config/branding.json` from the neutral starter — see [the branding con
 | `MEDUSA_GDS_ONLY` | `1` = hard force-skip the OTB **instance-seed** migrations (`migrations/instance/`) — belt-and-suspenders over the default. A vanilla instance never wants OTB's versions/goals/criteria (task 1704 / [ADR 0105](../adr/0105-instance-seed-migrations-out-of-core.md)). | `1` |
 | `GDS_APPLY_INSTANCE_SEEDS` | `1` = opt IN to applying the bundled OTB instance-seed migrations. Default (unset) = **skip** — so a self-host never inherits OTB scope-truth. Only the owning instance sets this, and only when rebuilding its DB from scratch (DR). | unset |
 | `BONGOS_PUBLIC_ORIGIN` | public origin for OAuth callbacks etc. | `http://localhost:3000` |
+| `BONGOS_FIRST_ADMIN` | GitHub login seated as the first Archon at their first sign-in. Unset, nobody can sign in, because nobody exists to approve them. | unset |
+| `BONGOS_BUILDERS_ORIGIN` | origin the builders' hall is served on. The vanilla pack uses the public origin's host, which makes the hall the whole site: pages that only live on the apex, such as `/projects` and `/create`, return 404. Set a separate host (e.g. `http://builders.localhost:3000`) when you enable `provisioning`. | same host as the public origin |
 
 (The env prefix is the instance's `envPrefix` from its branding pack — `BONGOS` for vanilla.)
 

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.830",
+  "version": "1.19.832",
   "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/src/bongos/auth-admission.js

@@ -16,6 +16,7 @@
 const {
   upsertBuilder,
   seatFirstAdminIfUnclaimed,
+  archonExists,
   createSession,
   lookupSession,
   getBuilderById,
@@ -308,6 +309,20 @@ async function webAdmissionStatus(login) {
   return { admitted, expectedSoon: admitted || state.pending || isFirstAdmin };
 }
 
+// instanceNeedsFirstAdmin — true while no Archon exists AND no firstAdmin is
+// configured: the vanilla self-host, where every sign-in (the operator's own
+// included) is refused and the generic page told them to ask an owner who does not
+// exist (task 1002717). A DB error answers false, leaving the generic page.
+async function instanceNeedsFirstAdmin() {
+  if (firstAdminLogin()) return false;
+  try {
+    return !(await archonExists());
+  } catch (err) {
+    log.error('[auth] instanceNeedsFirstAdmin', err);
+    return false;
+  }
+}
+
 // First-admin bootstrap (R62 / task 1201, ADR 0062). The configured firstAdmin
 // login — an install-time env override (<PREFIX>_FIRST_ADMIN, incl. legacy) wins,
 // else branding.firstAdmin. Empty/unset (the vanilla starter) means "no one is
@@ -456,6 +471,7 @@ async function readApplicantProfileFromHub(githubId) {
 module.exports = {
   firstAdminLogin,
   firstTimeAdmissionBlocked,
+  instanceNeedsFirstAdmin,
   readApplicantProfileFromHub,
   // Re-exported, not defined here (task 1003579 moved it to project-door.js with
   // the two knobs it composes against). auth.js, the doorway's api.joinabilityMode

package/src/bongos/auth.js

@@ -55,7 +55,7 @@ const ic = require('../instance-config');
 const { branding, userAgent } = require('../branding');
 
 const { SCOPE, authConfigured, grantedScopeCoversRepos, idpConfigured, idpEnabled, loadIdpConfig, scopeForWebFlow } = require('./auth-config.js');
-const { firstAdminLogin, firstTimeAdmissionBlocked, joinabilityMode, maybeSeatFirstAdmin, membershipKind, openEnrollmentEnabled, readApplicantProfileFromHub, webAdmissionStatus } = require('./auth-admission.js');
+const { firstAdminLogin, firstTimeAdmissionBlocked, instanceNeedsFirstAdmin, joinabilityMode, maybeSeatFirstAdmin, membershipKind, openEnrollmentEnabled, readApplicantProfileFromHub, webAdmissionStatus } = require('./auth-admission.js');
 const { buildAuthorizeUrl, completeWebFlow, pollDeviceFlow, startDeviceFlow } = require('./auth-github.js');
 const { buildIdpAuthorizeUrl, completeDeviceExchange, completeIdpFlow, idpAuthorizeUrl, loadHubPublicKey, logoutTokenJtiSeenAndRecord, verifyHubAssertion, verifyHubLogoutToken } = require('./auth-idp.js');
 const { addDiscordGuildMember, buildDiscordAuthorizeUrl, discordAuthorizeUrl, discordBotConfigured, discordConfigured, exchangeDiscordCode, fetchDiscordUser, isValidDiscordUserId, loadDiscordBotToken, loadDiscordCreds, removeDiscordGuildMember } = require('./auth-discord.js');
@@ -895,6 +895,7 @@ module.exports = {
   joinabilityMode,
   readApplicantProfileFromHub,
   firstTimeAdmissionBlocked,
+  instanceNeedsFirstAdmin,
   webAdmissionStatus,
   firstAdminLogin,
   maybeSeatFirstAdmin,

package/src/bongos/db-kernel.js

@@ -212,6 +212,14 @@ async function seatFirstAdminIfUnclaimed(builderId, login) {
   return rowCount > 0;
 }
 
+// archonExists — has anyone been seated as Archon yet? The same predicate the seat
+// above guards on, so "no owner yet" is exactly the window in which a configured
+// firstAdmin would still be seated (task 1002717).
+async function archonExists() {
+  const { rows } = await pool.query(`SELECT EXISTS (SELECT 1 FROM builders WHERE rank = 'archon') AS has`);
+  return !!(rows[0] && rows[0].has);
+}
+
 // getBuilderByGithubId — minimal identity read by stable GitHub numeric id (login
 // can change; github_id is the stable key). Backs the approval-gated web sign-in.
 async function getBuilderByGithubId(githubId) {
@@ -378,6 +386,7 @@ module.exports = {
   SESSION_TTL_MS,
   upsertBuilder,
   seatFirstAdminIfUnclaimed,
+  archonExists,
   getBuilderByGithubId,
   hasInvitedAccessRequest,
   accessStateByLogin,

package/src/bongos/permission-path-check.js

@@ -73,16 +73,31 @@ const RANK_TIER = { xenos: 1, thetes: 2, metic: 3, archon: 4 };
 // hook.
 const REGISTRY_PATH = path.join(__dirname, '..', '..', 'modules', 'government', 'protected-surfaces.json');
 
+// WHY THE REFUSAL NAMES A FIX: the FAIL-CLOSED note above tells the reader what
+// this throw refuses to do, but nothing told them what to DO — and a reader who
+// meets this cold sees a core file reaching into modules/ and concludes the
+// module must be optional. That is not hypothetical: task 1003662 was filed
+// asking for exactly the degrade-to-empty-set this refuses, on that reading. The
+// registry SHIPS INSIDE @bongos/core (modules/ is in the published tarball, ADR
+// 0108 §1), so it cannot be absent on an intact install and disabling the
+// government module cannot remove it — a module's enable/disable state is a
+// runtime flag, never a file deletion. Absent therefore means the install is
+// damaged, and reinstalling is the fix. Full reasoning: ADR 0300.
+const REMEDIATION =
+  'modules/government/protected-surfaces.json ships inside @bongos/core, so an intact install always has it '
+  + '— this is a damaged install (partial extract or lossy copy), not a disabled module. Reinstall/repair the '
+  + 'core package; do NOT degrade to an empty protected set (ADR 0043, ADR 0300).';
+
 function loadRegistry(file) {
   let raw;
   try {
     raw = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch (e) {
-    throw new Error(`protected-surface registry unreadable at ${file}: ${e.message}. Refusing to run with an empty protected set (ADR 0043).`);
+    throw new Error(`protected-surface registry unreadable at ${file}: ${e.message}. Refusing to run with an empty protected set (ADR 0043). ${REMEDIATION}`);
   }
   const surfaces = Array.isArray(raw && raw.surfaces) ? raw.surfaces : null;
   if (!surfaces || surfaces.length === 0) {
-    throw new Error(`protected-surface registry ${file} declares no surfaces. Refusing to run with an empty protected set (ADR 0043).`);
+    throw new Error(`protected-surface registry ${file} declares no surfaces. Refusing to run with an empty protected set (ADR 0043). ${REMEDIATION}`);
   }
   const defaultFloor = raw.floor;
   const defaultPermission = raw.permission;

package/src/bongos/routes/auth.js

@@ -40,7 +40,7 @@ const { pairStore } = require('../app-pair');
 const { publicOrigin, parseCookie, validateOrRespond } = require('./_helpers');
 const { accountExistenceReadRateLimit } = require('../middleware/rate-limit');
 const { branding } = require('../../branding');
-const { resolveEnv } = require('../../instance-config');
+const { resolveEnv, envPrefix } = require('../../instance-config');
 const seams = require('../../module-seams');
 // task 1003208: structured logging — was console.*. A core file logs through
 // the kernel logger directly; only MODULES go via api.logger (the doorway).
@@ -738,6 +738,19 @@ module.exports = function buildAuthRouter() {
         if (expectedSoon) {
           return res.status(202).type('text/html').send(renderAccessPendingPage(err.login, recoveryStartHref(req)));
         }
+        // task 1002717: with no owner and no FIRST_ADMIN, everyone is refused, the
+        // operator included. Name the fix instead of pointing at an owner who does not exist.
+        if (await auth.instanceNeedsFirstAdmin()) {
+          return res.status(403).type('text/html').send(renderAuthErrorPage(
+            'This instance has no owner yet',
+            `Nobody can sign in until an owner is configured. If you run this instance, set ${envPrefix()}_FIRST_ADMIN to your GitHub login, restart it, and sign in again. That account becomes the first Archon and can approve everyone after it.`,
+            {
+              subtitle: 'A new instance needs its owner set before anyone can sign in.',
+              startHref: recoveryStartHref(req),
+              note: 'The self-host recipe (docs/recipes/self-host.md) lists this setting.',
+            },
+          ));
+        }
         // The founder-shaped branch (only reachable with open enrollment OFF):
         // a stranger who was on their way to create a project is told the
         // approval brings them back to it — the return cookie says where.

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.830'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.832'; // 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('dev-box'); log.info('mounted');

package/tests/compose_demo_credentials.mjs

@@ -0,0 +1,30 @@
+// tests/compose_demo_credentials.mjs — the self-host demo credentials never read as a live secret (task 1002717).
+//
+// docker-compose.yml used PGPASSWORD=cloudbongos. The env-secret leak scan
+// (collectEnvSecrets) treats any secret-named env value of 8+ characters as a live
+// credential, and package-core refuses to build when a functional file contains one.
+// Inside the compose container that meant every file mentioning the brand name, and
+// docker-compose.yml itself ships in the core, so any long demo value trips it.
+//
+// Run:  node --test tests/compose_demo_credentials.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { collectEnvSecrets } = require('../modules/security/secret-scrub.js');
+
+const compose = fs.readFileSync(new URL('../docker-compose.yml', import.meta.url), 'utf8');
+const env = {};
+for (const m of compose.matchAll(/^\s+([A-Z][A-Z0-9_]*):\s*"?([^"\r\n#]*?)"?\s*$/gm)) env[m[1]] = m[2];
+
+test('the compose file declares the database password for both services', () => {
+  assert.ok(env.POSTGRES_PASSWORD, 'db service password');
+  assert.equal(env.PGPASSWORD, env.POSTGRES_PASSWORD, 'the app connects with the password the db was created with');
+});
+
+test('no compose env value is collected as a live secret', () => {
+  assert.deepEqual(collectEnvSecrets(env), []);
+});

package/tests/first_admin_unset_signin.mjs

@@ -0,0 +1,80 @@
+// tests/first_admin_unset_signin.mjs — a fresh instance with no owner says so (task 1002717).
+//
+// A vanilla docker-compose self-host configures no FIRST_ADMIN, so the very first
+// sign-in (the operator's own) is refused, and the page it lands on said "ask the
+// owner to confirm your request" on an instance that has no owner. The callback
+// now asks auth.instanceNeedsFirstAdmin() first and, when it is true, names the fix.
+//
+// The stub goes into require.cache BEFORE auth.js loads: auth-admission destructures
+// its db-kernel bindings at require time.
+//
+// Run:  node --test tests/first_admin_unset_signin.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const kernelPath = require.resolve('../src/bongos/db-kernel.js');
+const realKernel = require(kernelPath);
+let archon = false;
+let dbThrows = false;
+require.cache[kernelPath].exports = {
+  ...realKernel,
+  archonExists: async () => {
+    if (dbThrows) throw new Error('simulated DB outage');
+    return archon;
+  },
+};
+
+// Any prefix resolveEnv reads — the instance's own and the legacy spellings.
+for (const k of Object.keys(process.env)) if (k.endsWith('_FIRST_ADMIN')) delete process.env[k];
+
+const auth = require('../src/bongos/auth.js');
+
+test('precondition: this pack configures no firstAdmin', () => {
+  assert.equal(auth.firstAdminLogin(), null);
+});
+
+test('no owner and no FIRST_ADMIN: the instance needs one', async () => {
+  archon = false;
+  assert.equal(await auth.instanceNeedsFirstAdmin(), true);
+});
+
+test('an Archon exists: an established instance never shows the no-owner page', async () => {
+  archon = true;
+  assert.equal(await auth.instanceNeedsFirstAdmin(), false);
+});
+
+test('FIRST_ADMIN is configured: the bootstrap will seat them, so no', async () => {
+  archon = false;
+  process.env.OTB_FIRST_ADMIN = 'founding-owner';
+  try {
+    assert.equal(await auth.instanceNeedsFirstAdmin(), false);
+  } finally {
+    delete process.env.OTB_FIRST_ADMIN;
+  }
+});
+
+test('a DB error answers false, leaving the generic page', async () => {
+  dbThrows = true;
+  try {
+    assert.equal(await auth.instanceNeedsFirstAdmin(), false);
+  } finally {
+    dbThrows = false;
+  }
+});
+
+test('the callback checks for a missing owner before the generic not-approved pages', () => {
+  const src = fs.readFileSync(new URL('../src/bongos/routes/auth.js', import.meta.url), 'utf8').replace(/\r\n/g, '\n');
+  const waiting = src.indexOf('if (expectedSoon) {');
+  const noOwner = src.indexOf('if (await auth.instanceNeedsFirstAdmin()) {');
+  const inviteOnly = src.indexOf("if (effectiveJoinDoor() !== 'apply') {");
+  assert.ok(waiting > 0 && noOwner > 0 && inviteOnly > 0, 'all three branches present');
+  assert.ok(waiting < noOwner && noOwner < inviteOnly, 'waiting page, then no-owner page, then the refusals');
+  const branch = src.slice(noOwner, inviteOnly);
+  assert.match(branch, /'This instance has no owner yet'/);
+  assert.match(branch, /\$\{envPrefix\(\)\}_FIRST_ADMIN/, 'names the setting under this instance\'s own env prefix');
+});

package/tests/government_protected_surfaces.mjs

@@ -742,6 +742,55 @@ test('a missing registry fails CLOSED — it never degrades to "nothing is prote
   }, /unreadable|Refusing/i);
 });
 
+// The refusal text, not just the refusal. Run the kernel load in a cold subprocess
+// with a patched read and hand back stderr, so a message assertion sees what an
+// operator would actually read.
+function refusalStderr(patch) {
+  try {
+    execFileSync(process.execPath, ['-e',
+      "const fs=require('node:fs');const real=fs.readFileSync;" + patch
+      + "require('./src/bongos/permission-path-check');",
+    ], { cwd: ROOT, stdio: 'pipe' });
+  } catch (e) {
+    return String(e.stderr || '');
+  }
+  return '';
+}
+
+// WHY ASSERT ON THE WORDS (task 1003662, ADR 0300). The sibling probe above proves
+// the load REFUSES; it cannot tell whether the refusal is actionable. It was not:
+// the message stated the refusal and cited ADR 0043 but never named a fix, and a
+// reader who meets it cold sees a core file reaching into modules/ and concludes
+// the module must be optional. Task 1003662 was filed on exactly that reading,
+// asking for the degrade-to-empty-set this refuses. The remediation line is the
+// fix for that, so it is part of the contract and not decoration.
+//
+// The EMPTY-surfaces branch is covered here for the first time. Until now only the
+// unreadable branch had a probe, so `surfaces: []` — the shape an out-of-band
+// registry write most plausibly produces — could have degraded silently.
+test('both refusal branches name the fix, not just the refusal (ADR 0300)', () => {
+  const gone = refusalStderr(
+    "fs.readFileSync=(p,...r)=>{ if(String(p).includes('protected-surfaces.json')) throw new Error('gone'); return real(p,...r); };",
+  );
+  const empty = refusalStderr(
+    "fs.readFileSync=(p,...r)=>(String(p).includes('protected-surfaces.json') ? '{\"surfaces\":[]}' : real(p,...r));",
+  );
+
+  assert.match(empty, /declares no surfaces/,
+    'an empty surfaces[] must refuse too — not only an unreadable file');
+
+  for (const [name, text] of [['unreadable', gone], ['empty', empty]]) {
+    assert.match(text, /Refusing to run with an empty protected set/,
+      `the ${name} branch must still state the refusal`);
+    assert.match(text, /ships inside @bongos\/core/,
+      `the ${name} branch must say the registry ships with the core (so absent means damaged, not disabled)`);
+    assert.match(text, /[Rr]einstall/,
+      `the ${name} branch must name the action that fixes it`);
+    assert.match(text, /ADR 0300/,
+      `the ${name} branch must cite the ADR that rejected degrading to an empty set`);
+  }
+});
+
 // ---------- the matcher, driven by registry data ----------
 
 test('a known path is protected at the right floor; an unknown path is not', () => {