@bongos/core 1.19.611 → 1.19.613

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.611",
-  "core_contract": "1.19.611",
-  "source_commit": "2fe1716bf46fd008eb614d9fb317b0e9ee2874eb",
+  "core_version": "1.19.613",
+  "core_contract": "1.19.613",
+  "source_commit": "86c4eeb0c9ed29d15cfa0331071100cabd8c0837",
   "source_ref": "HEAD",
-  "built_at": "2026-09-09T03:07:36.926Z",
+  "built_at": "2026-09-09T04:38:02.786Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 458,
+    "docs_redacted": 459,
     "agent_docs_stubbed": 24,
     "functional_verbatim": 2080,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2562,
-  "tree_sha256": "c6a3113ed2f20af25a3ebcaee8cb4ff9cd42890d51e890a85c31ddf9d63ff5ea",
+  "file_count": 2563,
+  "tree_sha256": "9254c8e86a95c04620946437ea658877a5d12f5d40f1342f3088ea735f733d71",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1807,7 +1807,7 @@
     {
       "path": "docs/adr/0258-the-public-cli-is-a-generated-client-package-not-the-published-core.md",
       "mode": "0000644",
-      "sha256": "28f3644d3d9dcd2985b7e3f42cf2135af86203eee35b6e509d1ff98f630f1228"
+      "sha256": "43bf2232da3353ab49bfd956a73d09c5045e5fa155e0004d0855a50587c299cd"
     },
     {
       "path": "docs/adr/0259-a-projects-departure-from-the-public-list-is-public.md",
@@ -1844,10 +1844,15 @@
       "mode": "0000644",
       "sha256": "c9cd485b1ffce55fea15fd5b544a01e5753309e291c88bd223d33e6c11c4ebec"
     },
+    {
+      "path": "docs/adr/0266-the-board-room-is-its-own-surface-reachable-by-whoever-may-vote.md",
+      "mode": "0000644",
+      "sha256": "ac348289412efce1b3d67d74fccb5ff81347d196715ff53fd77e79e22228fad3"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "c4bbd4c0ff9163a435564b56c4aac1d2c08e2b129d32b7f24779a60674096b47"
+      "sha256": "6cdaf9ffd4b14ae27231158fc040d59f084b86a93e6ecc43fb16bdea54e32fb6"
     },
     {
       "path": "docs/api-reference.md",
@@ -2732,7 +2737,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "4cc20b3afc8ec94a1d53e3d3f746269a1a7def4b6798d81402fe9078c002d3b1"
+      "sha256": "b91dcdf5bd99bbaa08679535a2ee122afb40367b275d7f0790236fc358283890"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7632,12 +7637,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "73ce6d69717b6ed9e4cf704e12b5578a86a5a9d34baaa1df34df7caa5accbedb"
+      "sha256": "16da9aa01a2a13938d0160a61d612c0d3757631e74c7236a545b86a87bd5fd1d"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "5ac0729891d64cd779f810b1bf4f98997a7dd8756c8baaa9d82577c7e7e29b60"
+      "sha256": "8137fdc6cc9e9bdebbf3376f0a3095c75818c1e807c3fec8f37f95d4313cd37d"
     },
     {
       "path": "public-docs/index.html",
@@ -7712,7 +7717,7 @@
     {
       "path": "scripts/gds/api.js",
       "mode": "0000644",
-      "sha256": "96d6b69e9440dac3ed81c490e460a832d385714de0b379650af80817f89ded0f"
+      "sha256": "a018f4ccc228950065ef0a376445ba6fc79318e451f9a6bc648dc8dd97235b87"
     },
     {
       "path": "scripts/gds/api.ps1",
@@ -7807,7 +7812,7 @@
     {
       "path": "scripts/gds/box-connect-lib.js",
       "mode": "0000644",
-      "sha256": "56c6f3eae23d427d9c74763521739bae5b704bcd02ad234e43a5434645657519"
+      "sha256": "dbc4dd22d858a7d17c34ebf211edbd6d885afa39ab7b9e3032a7390cd5526638"
     },
     {
       "path": "scripts/gds/box-infra.js",
@@ -7837,7 +7842,7 @@
     {
       "path": "scripts/gds/build-cli-package.js",
       "mode": "0000644",
-      "sha256": "760dbc00a1d8ed5dfa2184e93f9106383bbb36c7fdd973ddfc67b7e03f3bc2f8"
+      "sha256": "81ad7fbc99f5c85219f1385cdd6e6954d27a0e2943f285676f060611a4878f4e"
     },
     {
       "path": "scripts/gds/bump-version.js",
@@ -7897,7 +7902,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "beb9d466f7623cae12788f23d0e30fbf3a520fec769e416ce3ad6458b23ceb2b"
+      "sha256": "44b8c997a25d9fcc68ba573d33391546ff98a871c7d99e9aa6d982c69a703824"
     },
     {
       "path": "scripts/gds/client-baseurl-guard.js",
@@ -8717,7 +8722,7 @@
     {
       "path": "scripts/gds/setup.js",
       "mode": "0000644",
-      "sha256": "98671f5666ae6bdafa7691bd519367345772c3041680b59c24ec83c56b99f419"
+      "sha256": "36b5c59af3cde0398e432db37f1cd645aab08ea70b308a5e53671a4fce06f7fe"
     },
     {
       "path": "scripts/gds/shell.js",
@@ -9362,7 +9367,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "790abd4adb2065c87aa21a729b69b33d01ed07be1c5c307a865f2f8942cc9d3f"
+      "sha256": "5f2889a1593cd4d896fdb5bf56cbad44d99809b8a60e955bf378d321f8320891"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9967,7 +9972,7 @@
     {
       "path": "tests/cli_surface.mjs",
       "mode": "0000644",
-      "sha256": "589ecc771ab18829049eabc6183939843072160e8476828e246eadd8ff6f0709"
+      "sha256": "5a8cc9320d66980280965ee34fbb5fc4bbcc30c8ffa860324a99ce0ce4e4d61f"
     },
     {
       "path": "tests/cli_token_reissue.mjs",

package/docs/adr/0258-the-public-cli-is-a-generated-client-package-not-the-published-core.md

@@ -124,6 +124,23 @@ benefit. It gains one when ADR 0099's mirror lands.
   dependency — a public package that depended on a private one would be uninstallable for
   everyone.
 - Task 1002025 is superseded and should be closed against this ADR rather than done.
+- **The journey above is instance-dependent, and 0.1.1 shipped assuming it was not**
+  ([task 1003730](https://cloudbongos.com/builders#/task/1003730)). `bongos shell` is the answer
+  this package gives to `bongos claim`, but `dev-box` is a **control-plane** module — it
+  provisions droplets, so every hosted co-tenant checked (hermeslines-marketing, mercury, demo)
+  runs without it while cloudbongos.com has it. On those instances the only route the CLI offered
+  to a checkout ended in `HTTP 404: not_found`: a newcomer could list the work and not start it.
+  The instance manifest had always said so — `/api/gds/instance` carries `modules.enabled` — and
+  no CLI script read it. It now does, **failing open** (a core too old to publish a roster must
+  never block a working box), and the dispatcher's checkout-only text presents `bongos shell` as
+  conditional rather than promising a box it cannot verify.
+- **A surface conversion is only as complete as the paths it is tested on.** Task 1003680 routed
+  `start.js` through `surface.js` and pinned exactly that file, so eleven `/builder-*` lines
+  shipped in 0.1.1 — including `requireSession()`, the gate every unauthenticated verb passes
+  through, which told terminal users to run `/builder-setup`, and `setup.js`'s completion footer,
+  which told a newly-registered builder to run two verbs this package does not have. Several also
+  named `node scripts/gds/<x>.js`, the checkout this package exists to avoid needing. The test now
+  **runs** the guidance printers under both surfaces rather than scanning one file's source.
 
 ## Rejected
 

package/docs/adr/0266-the-board-room-is-its-own-surface-reachable-by-whoever-may-vote.md

@@ -0,0 +1,150 @@
+# 0266 — The Board Room is its own surface, reachable by whoever may vote
+
+- **Status:** Accepted
+- **Date:** 2026-09-08
+- **Tasks:** [#1003734](https://cloudbongos.com/builders#/task/1003734) (this record). Executed by [#1003735](https://cloudbongos.com/builders#/task/1003735) (the carve), [#1003736](https://cloudbongos.com/builders#/task/1003736) (the deep links), [#1003737](https://cloudbongos.com/builders#/task/1003737) (the waiting-vote count).
+- **Goal:** [#1000111](https://cloudbongos.com/builders#/goal/1000111) — Working area 7, Government; criterion `wa7-government`.
+- **Decided by:** the owner (Masterqua / `IAMMASTERQUA`, Archon, member of area 7), 2026-09-08.
+- **Builds on:** [ADR 0175](<redacted>.md) (the Board Room, and §6 — who governs is configuration), [ADR 0157](<redacted>.md) (the `page.view.government` floor at metic), [ADR 0151](<redacted>.md) (permissions as the atom), [ADR 0016](<redacted>.md) (server-enforced, uncached, per request).
+- **Related:** [ADR 0174](<redacted>.md) (government, not governance).
+
+## 1. Context — the room with no door
+
+The Board Room is the hall's only upward-pointing gate (ADR 0175): the surface
+on which a Full Idea that cleared the completeness bar is ratified, and the only
+surface on which the constitution itself can be amended. It ships today as a
+**hash tab** (`#board-room`) inside the `/government` page, beside Permissions
+and Constitution.
+
+Two facts about that placement do not survive inspection.
+
+**The nav never followed the page.** When R16 turned `/government` into three
+rooms it correctly widened the *page* gate from `government.manage` (archon) to
+`page.view.government` (metic+). The comment it left in
+[`serve-internal.js`](../../src/bongos/serve-internal.js) states the principle
+plainly — *"The shell follows the widest legitimate audience — the audience
+changed when the page did."* But `modules/hall-ui/public/shell.js` still
+declares that nav item as `label: 'Permissions'`, `gate: 'archon'`. So the page
+widened and the door did not: a Metic who sits on the board has **no nav link to
+the Board Room at all**, and the only word an Archon sees in the nav is
+"Permissions", which does not suggest a voting room is behind it. Every other
+government room — Watch, Harbor, Gate, Sessions — carries its own nav item. The
+Board Room is the one room reachable only by knowing a URL fragment.
+
+**The surface is narrower than the franchise.** `board.vote.cast` floors at
+**xenos**, and that is deliberate: `modules/government/board.js:149` records the
+floor is low *so that widening the board works*. The page shell requires
+metic+. Today `membership: rank:archon` and every Archon clears both, so the
+contradiction is latent. The moment a constitution widens membership below
+Metic — the exact act ADR 0175 §6 exists to make a configuration change — those
+members may cast a vote through the API and **cannot load the page they would
+cast it on**.
+
+The second is the load-bearing one. ADR 0175 §6 put membership, pass rule and
+window in `config/government.json`, resolved per request and uncached, so that
+"flipping the switch later changes numbers, not a code path that has never run."
+A page gate keyed to a different atom than the vote reintroduces exactly the
+code-path change that decision removed.
+
+## 2. Decision
+
+### 1. The Board Room becomes its own page at `/board-room`
+
+Carved out of `/government`, which keeps Permissions and Constitution. It joins
+Watch, Harbor, Gate and Sessions as a first-class room in the Government nav
+group, with its own nav item.
+
+The alternative — leaving the tab in place and adding a nav item that deep-links
+to `/government#board-room` — was considered and rejected. It is cheaper and it
+preserves the existing hash links for free, but it leaves the voting room inside
+a page whose gate answers a different question, which is defect (2) above left
+standing. The room that constrains the owner should not be a tab inside the
+owner's admin page.
+
+### 2. Its reach follows `board.vote.cast`, not `page.view.government`
+
+The page gate resolves the **same atom the vote route checks**. The surface
+reach and the right to vote become one thing, and widening the board stays a
+configuration change.
+
+`board.vote.cast`'s floor is only the coarse gate. **Membership is still checked
+in-handler, per item, against that item's own snapshotted constitution** — the
+floor decides who may receive the shell, never who may vote on what. A builder
+who clears the floor but sits on no board sees the room and no ballot, which is
+the correct and honest state: ADR 0175 §9 made the ballot open on purpose,
+because "a board whose votes are invisible cannot constrain anyone."
+
+### 3. The old deep links are migrated client-side, because a fragment never reaches the server
+
+`#board-room` is a URL fragment. It is **not sent to the server**, so no
+server-side route or redirect can ever see it. The compatibility path is
+therefore a client-side redirect in `government.js`: on load, a `#board-room`
+hash sends the browser to `/board-room`, preserving `?item=N`.
+
+This is recorded as a decision rather than left as an implementation note
+because it is the thing a reader will otherwise get wrong — adding
+`GOVERNMENT_BOARD_RE` to `serve-internal.js` looks like the obvious fix and
+silently never fires.
+
+Three writers emit the old form and all three move (task
+[#1003736](https://cloudbongos.com/builders#/task/1003736)): the Discord
+window-open announcement (`modules/discord/board-broadcast.js`), the
+`board_votes` need's action href (`modules/builder-settings/builder-needs.js`),
+and the docs. The redirect stays for at least one release regardless, because
+announcements already sitting in Discord channel history carry the old link
+forever and ADR 0175 §8 makes that mention the "vote within X" notice.
+
+### 4. A waiting-vote count belongs on the nav item, and the hall has no mechanism for one
+
+The owner's second ask was to see that items are waiting **without going
+inside**. The data already exists and needs nothing new server-side:
+`boardVotesNeed` (`builder-needs.js`) carries a live count and the oldest
+waiting item id, pre-filtered to what the vote route would actually accept, and
+`GET /me` already serves it.
+
+What does not exist is any badge, bell, dot or count mechanism in
+`shell.js` — the nav renders label and icon and nothing else. Task
+[#1003737](https://cloudbongos.com/builders#/task/1003737) adds that once,
+generically, so a second consumer can adopt it without a second pattern. Zero is
+silent, and the badge is visible to exactly whoever the nav item is: a count is
+board activity, and it must not leak to someone who cannot see the room.
+
+A **sound** is deliberately out of scope. The instance ships `alert.wav` and
+`chime.wav`, so it would be easy and it was not asked for.
+
+## 3. Consequences
+
+**The `/government` tab strip loses a room, and that is the point.** Two rooms
+remain, both administrative, both correctly behind the archon-shaped item they
+already sit behind. The existing Permissions nav item keeps `gate: 'archon'` —
+it *is* the archon admin surface, so that gate was never wrong for it. It was
+wrong as the only door to three rooms.
+
+**Widening the board becomes a real config change.** After this, an instance may
+set `membership: rank:metic` — or wider — and the members it names can actually
+reach the room. Before it, that edit produced members who could vote only by
+`curl`. This is the property ADR 0175 §6 claimed and did not have.
+
+**One more page joins the statically-parsed gate map.** `tests/hall_page_gate_map.mjs`
+rebuilds the URL→gate map by parsing `serve-internal.js` as text, so the new
+`const BOARD_ROOM_PAGE_RE = /…/;` must keep the bare form with nothing between
+the `=` and the literal — a comment in that gap drops the regex out of the map
+and the page silently tests as ungated. The file already records this rule at
+`PROJECT_SETTINGS_PAGE_RE`; this ADR notes it because the failure is invisible.
+
+**A defect found while scoping this, filed separately.** The hall renders needs
+as a *single slot* (`needs.items.find(n => n.state !== 'satisfied')`), and
+`computeNeeds` sorts only by state with a stable sort — so inside the
+`action_needed` bucket the registry array order decides, and `boardVotesNeed` is
+fourth, behind `artKeyNeed`. Any builder with an unresolved image-generation key
+therefore never sees the board notice at all. It was live for the owner of this
+decision at the moment they asked for the bell. Filed as
+[#1003738](https://cloudbongos.com/builders#/task/1003738) rather than folded in
+here: the badge and the banner are two surfaces, and fixing the ordering is a
+change to what every need in the hall does.
+
+**Rejected: a bell in the global header rather than on the item.** A header bell
+is a second inbox — it needs its own read/unread state, its own dismissal
+semantics, and a home for notifications that are not board votes. The ask was to
+see the count on the section, and the nav item is where the reader already looks
+for the room.

package/docs/adr/README.md

@@ -357,3 +357,4 @@ This keeps the decision history honest and traceable.
 | 0263 | [**How a version closes: auto, early, roll-forward, and the maintenance exemption** ([task 1003593](https://cloudbongos.com/builders#/task/1003593) · goal 1000086 — *Strict versioning*). [ADR 0250](<redacted>.md) D5 decided a version *can* close; this is the design pass that makes its five build tasks mechanical, so they do not each invent their own refusal codes and payload shapes and meet only in production. **The asymmetry that shrinks the feature:** auto-close fires when the last non-maintenance goal achieves — so by construction every non-maintenance goal is already closed and the set needing a disposition is EMPTY. All the machinery (the disposition map, the refusal that returns the goals, successor lineage) belongs to EARLY close alone; R16 is small and R12 carries the weight. **Auto-close hangs off BOTH achievement writers** (`db-goals.achieveGoalIfComplete` and the `done-when` cascade — the deliberate duplicate D2 already governs, a require cycle being the reason they are not one helper), on the caller `exec` so it sees the ship's uncommitted flip, and **may never fail a ship**: wrapped and swallowed like `closeCompletedWorkForShip`, idempotent under `WHERE status='building'`, so a failure leaves a version un-closed (self-healing on the next reconciler sweep) and never half-closed. **Early close** is the R10 archive two-step verbatim in spirit — refuse with `version_holds_open_goals` **returning the goals**, then proceed with a per-goal `roll_forward`/`abandon` map and a required `reason`; six named codes, because the callers are agents. **Two briefs are corrected by measurement:** the lineage column is `succeeded_by_goal_id` (migration 160, on the OLD row pointing forward) — not the `succeeds_goal_id` both 0250 and R17's brief name, so R17 needs NO migration; and R18's `is_maintenance` flag is load-bearing rather than cosmetic, because answering the close count with a `title NOT LIKE` would let a hand-titled goal silently exempt itself from the gate that decides when a VERSION closes. Promotion runs inside the close txn and BEFORE roll-forward (`ensureMaintenanceGoal` returns null for a non-`building` version, so a carry-over run first silently carries nothing); zero planning versions is not an error; R19's one migration should carry the `building` AND `planning` partial unique indexes so the promotion race resolves like a 23505 rather than a prayer. Rejected: auto-creating the successor version inside a close (the "fake hotfix version" escape hatch 0250 built the override counter to prevent), writing `limitations/<version>-shipped.md` from the route (file I/O in a ship transaction — it stays R23's CLI work), and a version reopen.](<redacted>.md) | version lifecycle / scope closure |
 | 0264 | [**The ten working areas: one goal per area, held until 5,000 builders** ([task 1003696](https://cloudbongos.com/builders#/task/1003696) · goal 1000086 — *Strict versioning*, criterion `sv-cutover-proven-live`). The owner and the full team ran a manual goal review on 2026-09-07 and cut **38 open goals down to 10**, one per working area, each with a named owner and a described 5,000-builder end state: project creation (Rini), account/community (Rini), human project management (Scott), core distribution (Lars/Will), module distribution & economy (Will), the four-role experience incl. agents (Masterqua/Rini), government (Will/Masterqua), the credit economy (Scott), platform analytics (Lars), security (everyone bar Nils and Scott). **Why the rules were not enough on their own:** [ADR 0250](<redacted>.md) D1 closes the goal set of a BUILDING version — which freezes 38 goals exactly as effectively as it would freeze 10. Enforcement cannot shrink a scope that is already too large, so the rules and the cut are two halves of one move; the horizon is a SCALE (5,000 builders), not a date, because that is the question that decides when this set stops being the right set. **The finding that reorders the goal:** none of the cut can be executed today. R10 ([task 1003597](https://cloudbongos.com/builders#/task/1003597)) made `POST /goals/:id/archive` refuse a goal holding unfinished tasks and demand a disposition — correct, and exactly D3 — but the vector that SUPPLIES a disposition is R14 ([task 1003601](https://cloudbongos.com/builders#/task/1003601)), unshipped. Every one of the 12 deletes and every fold goes through that door, so **R14 is the keystone of the whole cut**, not one feature among thirteen, and is built before the rest of the version-close chain rather than in rank order. It looks like a bug and is not: the refusal is the design, landed one task ahead of its own remedy. "Delete" means `archived`, never a row removal (`goals.status` is open|achieved|archived, migration 160; reversible via `/reopen`) — preserving the rows keeps shipped-task attribution and credit history a delete would strand. Three open goals were NOT covered by the review and are surfaced as open questions rather than guessed: 1000003 (the catch-all — already R25's target), 1000065 (assumed to be area 2's community half), and 1000088 (repo cleanup — maps to no area, needs an owner decision). Deliberately does not decide: the areas' priority order, criteria for the six goals R29 must create (inventing criteria for someone else's area is how a goal acquires scope its owner never agreed to), or any task rehoming (R25/R26).](<redacted>.md) | scope / goal set / owner decision |
 | 0265 | [**Work with no goal survives a version close, and the order the ten-area cut actually needs** ([task 1003713](https://cloudbongos.com/builders#/task/1003713) · goal 1000086 — *Strict versioning*, criteria `sv-every-task-has-a-goal` + `sv-cutover-proven-live`). `closeVersion`'s post-apply invariant counts GOALS, and every task write inside the close is scoped `WHERE goal_id = $1` — so a task belonging to no goal is reached by no disposition, counted by no re-count, and ships stranded on a version that is over. Not hypothetical: six such tasks already sat on shipped GDS-V3/GDS-V4, and 47 rows on BONGOS-V1 carried a null `goal_id` (R11 required the column going forward but never backfilled, because every catch-all lookup matches the exact title `<VERSION> — general` and BONGOS-V1's is titled 'Work with no goal yet'). Decision: a second invariant in the same transaction refuses a close leaving ANY non-terminal task on the version, failing `CLOSE_LEAVES_STRANDED_TASKS` with the ids; exempting only the maintenance goal (its carry-forward runs in the later `onClosed` hook) — through the SAME `maintenanceGoalExemptSql` the goal count uses, never a second copy — and `__smoke__` fixtures. Consequence recorded here too: because `PATCH /tasks/:id {goal_id}` refuses a cross-version move (409 `goal_version_mismatch`) and `roll_forward` CREATES a successor rather than merging into one, [ADR 0264](<redacted>.md)'s cut must run home-then-close-then-**fold on the planning version**, where task and destination finally share a version. Rejected: a `fold_into` disposition (puts scope decisions inside a shipping transaction), creating the six new areas on the building version via R07 admissions (spends ten overrides to route around the rule they price), and a backfill instead of a gate (fixes today's rows, not the forty-eighth).](<redacted>.md) | lifecycle / version boundary |
+| 0266 | [**The Board Room is its own surface, reachable by whoever may vote** ([task 1003734](https://cloudbongos.com/builders#/task/1003734) · goal 1000111 — *Working area 7, Government*, criterion `wa7-government`; owner decision 2026-09-08). The hall's only **upward-pointing** gate ([ADR 0175](<redacted>.md)) shipped as a hash tab inside `/government`, and two things about that did not survive inspection. **The nav never followed the page:** R16 correctly widened the PAGE gate from `government.manage` (archon) to `page.view.government` (metic+) when the page became three rooms — its own comment says *"the shell follows the widest legitimate audience"* — but `shell.js` still declares that item as label Permissions with gate archon, so a Metic who SITS on the board has no nav link at all and the only word in the nav is Permissions. Watch, Harbor, Gate and Sessions each own a nav item; the voting room was reachable only by knowing a URL fragment. **The surface was narrower than the franchise:** `board.vote.cast` floors at XENOS deliberately (`board.js:149` — the floor is low *so that widening the board works*) while the shell demands metic+, so the moment a constitution widens membership below Metic — the exact act [ADR 0175](<redacted>.md) §6 exists to make a CONFIG change — those members may vote by API and cannot load the page they would vote on, reintroducing the code-path change §6 removed. Decision: **its own page at `/board-room`, gated on the same atom the vote route checks.** The floor stays coarse — membership is still checked in-handler per item against that item's own snapshotted constitution — so a builder who clears the floor but sits on no board sees the room and no ballot, which is honest (§9 made the ballot open on purpose). **The migration is client-side because a fragment never reaches the server:** `#board-room` cannot be caught by any server route, so `government.js` redirects on load, preserving `?item=N` — recorded as a decision because adding a regex to `serve-internal.js` looks like the obvious fix and silently never fires. Three writers move (Discord `board-broadcast.js`, the `board_votes` need href, docs), and the redirect stays a release regardless because announcements already in channel history carry the old link forever. A **waiting-vote count** goes on the nav item: the data already exists (`boardVotesNeed` carries a live count pre-filtered to what the vote route would accept, served on `GET /me`), but `shell.js` has NO badge/bell/dot mechanism at all, so one is built once, generically, zero-is-silent, visible to exactly whoever the item is. Found while scoping and filed separately ([task 1003738](https://cloudbongos.com/builders#/task/1003738)): the hall renders needs as a SINGLE slot and `computeNeeds` sorts only by state with a stable sort, so registry order decides inside the `action_needed` bucket and `boardVotesNeed` sits fourth behind `artKeyNeed` — any builder with an unresolved image key never sees the board notice, which was live for this decision's own owner at the moment they asked for the bell. Rejected: a nav item merely deep-linking to the existing tab (cheaper, keeps the hash links free, but leaves the voting room inside a page whose gate answers a different question); a bell in the global header (a second inbox, needing its own read/unread and dismissal semantics); and a SOUND (`alert.wav`/`chime.wav` already ship, so it would be easy — it was not asked for).](<redacted>.md) | government / the board / hall nav |

package/docs/module-api-changelog.md

@@ -1671,5 +1671,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.609 with no explicit bump. run 34305007041. (task 1002620)
   1.19.611 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.610 with no explicit bump. run 34305857169. (task 1002620)
+  1.19.612 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.611 with no explicit bump. run 34310708322. (task 1002620)
+  1.19.613 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.612 with no explicit bump. run 34311691842. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.611",
+  "version": "1.19.613",
   "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/scripts/gds/api.js

@@ -18,7 +18,8 @@
 // on a 2xx, 1 on any non-2xx or transport error, 2 on bad invocation.
 
 const fs = require('node:fs');
-const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanceAndExit, cliExit, repairMsysMangledPath } = require('./cli-lib');
+const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanceAndExit, cliExit, repairMsysMangledPath,
+  instanceDevBoxSupport, devBoxUnavailableMessage } = require('./cli-lib');
 
 
 (async () => {
@@ -89,6 +90,14 @@ const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanc
   if (res.data !== undefined && res.data !== null) {
     console.log(JSON.stringify(res.data, null, 2));
   }
+  // task 1003730: `bongos box` in the public CLI is this passthrough aimed at
+  // POST /box/ensure, so on an instance without the dev-box module a builder got a raw
+  // 404 body and no idea why. api.js stays generic — it just adds the one explanation
+  // that a /box/ 404 always means — and only for a reader who typed a box command.
+  if (res.status === 404 && /^\/api\/(?:bongos\/v1|bongos|gds)\/box\b/.test(urlPath)) {
+    const { available } = await instanceDevBoxSupport();
+    if (!available) console.error(`\n✖ ${devBoxUnavailableMessage()}`);
+  }
   // task 1002734: process.exit() here aborted node 5/5 on Windows —
   // "Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c"
   // — AFTER the JSON had already printed, so every caller that checks the exit code

package/scripts/gds/box-connect-lib.js

@@ -30,7 +30,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
 const ic = require('../../src/instance-config');
-const { cliClient } = require('./cli-lib');
+const { cliClient, surfaceAction, assertDevBoxAvailable } = require('./cli-lib');
 
 // The box always runs as root and the repo is cloned to /workspace (the devcontainer
 // standardizes the same path). NOT ~/workspace — root's ~ is /root, which has no clone.
@@ -330,9 +330,9 @@ async function ensureKeyRegistered({ created, keyPath, pubKey, log = console.log
       log('  ✓ Registered your public key with the dev system.');
       return { registered: true };
     }
-    log(`  ! Could not register your key (${res.data?.error || res.status}); if SSH is refused, add it via /builder-box.`);
+    log(`  ! Could not register your key (${res.data?.error || res.status}); if SSH is refused, add it via ${surfaceAction('box')}.`);
   } catch (err) {
-    log(`  ! Could not register your key (${err.message}); if SSH is refused, add it via /builder-box.`);
+    log(`  ! Could not register your key (${err.message}); if SSH is refused, add it via ${surfaceAction('box')}.`);
   }
   return { registered: false };
 }
@@ -349,6 +349,7 @@ function sleep(ms) {
 // public box object from /box/me ({ state, hostname, ip, host_keys, … }).
 // Throws on a provision denial (rank/blocked) or a timeout.
 async function ensureBoxActive({ log = console.log, timeoutMs = 6 * 60 * 1000, intervalMs = 5000, sleepFn = sleep } = {}) {
+  await assertDevBoxAvailable();
   const api = await cliClient();
   const ensureRes = await api.box.postBoxEnsure();
   if (ensureRes.status === 403) {
@@ -462,6 +463,9 @@ function pinKnownHosts({ hostname, hostKeys, ip = null, log = console.log }) {
 // The one-shot "get the box ready + local SSH set up" used by both verbs.
 // Returns { box, keyPath }.
 async function prepareConnection({ log = console.log } = {}) {
+  // Before touching keys: key registration hits the box API too, so without this the reader gets
+  // a puzzling "Could not register your key (not_found)" line before the real explanation.
+  await assertDevBoxAvailable();
   const { keyPath, pubKey, created } = ensureSshKey({ log });
   await ensureKeyRegistered({ created, keyPath, pubKey, log });
   const box = await ensureBoxActive({ log });

package/scripts/gds/build-cli-package.js

@@ -35,7 +35,7 @@ const REPO_ROOT = path.join(__dirname, '..', '..');
 
 // The package's OWN version — deliberately independent of the core's. The core moves many times
 // a day (CI auto-patch, ADR 0161); the CLI's public contract should not.
-const PACKAGE_VERSION = '0.1.1';
+const PACKAGE_VERSION = '0.1.2';
 const PACKAGE_NAME = '@cloudbongos/cli';
 
 // ── What the package carries ────────────────────────────────────────────────────────────────
@@ -140,6 +140,10 @@ const VERBS = {
 // Verbs that exist in the full core CLI and are deliberately absent here. The dispatcher prints
 // the reason and the actual next step, because a newcomer hitting a bare "unknown command" learns
 // nothing — that silence is the exact failure this whole task is fixing.
+//
+// The next step it names is CONDITIONAL prose, not a promise: dev boxes are a control-plane
+// capability many instances run without (task 1003730). The dispatcher has no session or manifest
+// yet, so it must not claim `bongos shell` will work — that verb makes the determination itself.
 const CHECKOUT_ONLY = {
   claim:   'Claiming a task writes code, so it needs a real checkout and a worktree.',
   ship:    'Shipping grades, merges and deploys from a real checkout.',
@@ -307,10 +311,13 @@ function main(argv) {
   if (CHECKOUT_ONLY[verb]) {
     process.stderr.write(
       'bongos: "' + verb + '" is not in the public CLI.\\n  ' + CHECKOUT_ONLY[verb] + '\\n\\n' +
-      'To get a checkout without installing anything locally:\\n' +
+      'If this instance offers cloud dev boxes, you can get a checkout without\\n' +
+      'installing anything locally:\\n' +
       '  bongos shell            open a terminal on your cloud dev box\\n' +
       '  bongos code             open VS Code on it over Remote-SSH\\n\\n' +
-      'The full CLI (including ' + verb + ') is already installed inside that box.\\n'
+      'Not every instance runs dev boxes. If yours does not, bongos shell says so,\\n' +
+      'and the route is a checkout of the project repo instead. The full CLI\\n' +
+      '(including ' + verb + ') is installed in both.\\n'
     );
     return 2;
   }

package/scripts/gds/cli-lib.js

@@ -363,11 +363,19 @@ function printUnauthGuidanceAndExit() {
   console.error('');
   console.error('✖ Your Bongos CLI session is no longer valid.');
   console.error('');
-  console.error('  Recover the fast (UI-first) way — run /builder-reauth, or:');
-  console.error('    node scripts/gds/reauth.js');
-  console.error('  (opens your Settings page; under "CLI Access" click "Re-issue CLI');
-  console.error('   token", copy the one-liner, paste it back — no terminal Device Flow.)');
-  console.error('  Fallback (terminal Device Flow): node scripts/gds/setup.js --force');
+  if (isTerminalSurface()) {
+    // No checkout here, so `node scripts/gds/*.js` is not a path this reader has (task 1003730).
+    console.error(`  Recover the fast (UI-first) way — run ${surfaceAction('reauth')}`);
+    console.error('  (opens your Settings page; under "CLI Access" click "Re-issue CLI');
+    console.error('   token", copy the one-liner, paste it back — no terminal Device Flow.)');
+    console.error('  Fallback (browser sign-in): bongos login <instance-url>');
+  } else {
+    console.error('  Recover the fast (UI-first) way — run /builder-reauth, or:');
+    console.error('    node scripts/gds/reauth.js');
+    console.error('  (opens your Settings page; under "CLI Access" click "Re-issue CLI');
+    console.error('   token", copy the one-liner, paste it back — no terminal Device Flow.)');
+    console.error('  Fallback (terminal Device Flow): node scripts/gds/setup.js --force');
+  }
   console.error('');
   console.error('  Possible causes:');
   console.error('    - Your session token expired (24h idle TTL, auto-refreshes on each request)');
@@ -375,7 +383,8 @@ function printUnauthGuidanceAndExit() {
   console.error('    - A recent deploy applied an auth-changing migration (see deploy banner)');
   console.error('');
   console.error('  Once re-authed, re-run whichever command you were trying.');
-  console.error('  For a full diagnosis, run: node scripts/gds/doctor.js');
+  // `doctor` is checkout-only — it is not one of the public CLI's verbs (ADR 0258).
+  if (!isTerminalSurface()) console.error('  For a full diagnosis, run: node scripts/gds/doctor.js');
   console.error('');
   process.exit(2);
 }
@@ -414,7 +423,7 @@ function printBoxScopeGuidanceAndExit() {
   console.error('  not claim / ship / grade / etc. (the box holds no full-authority token by');
   console.error('  design — ADR 0053). Re-auth to a real CLI session, then re-run:');
   console.error('');
-  console.error('    /builder-reauth      (or: node scripts/gds/reauth.js)');
+  console.error(isTerminalSurface() ? '    bongos reauth' : '    /builder-reauth      (or: node scripts/gds/reauth.js)');
   console.error('');
   console.error(`  It opens your Settings page (${hallBase()}/settings) on`);
   console.error('  YOUR machine — under "CLI Access" click "Re-issue CLI token", copy the one-liner, paste it back.');
@@ -655,13 +664,78 @@ async function cliClient(opts = {}) {
   return client;
 }
 
+// ---- does this instance even HAVE dev boxes? (task 1003730) -----------------
+// The dev-box module is a CONTROL-PLANE capability: it provisions DigitalOcean droplets, so a
+// hosted co-tenant instance runs without it. The instance manifest has always said so —
+// GET /api/gds/instance carries modules.enabled — but no CLI script read it, so `bongos shell`
+// on such an instance died with a bare `POST /box/ensure failed (HTTP 404: not_found)`.
+//
+// That mattered far more than a bad error string: the public CLI (ADR 0258) answers
+// `bongos claim` by pointing at `bongos shell`, so on every dev-box-less instance the ONLY route
+// it offered to a checkout was a dead end — a newcomer could see the work and not start it.
+//
+// Cached per process, and FAILS OPEN: a manifest hiccup must never block a working box.
+let _devBoxCheck = null;
+
+// The decision, kept pure so it is testable without a network: does THIS manifest prove the
+// instance has no dev box? Anything short of an explicit module roster answers "assume yes" —
+// an older core, a truncated body or an unreachable manifest must never block a working box.
+function devBoxEnabledInManifest(manifest) {
+  const enabled = manifest && manifest.modules && manifest.modules.enabled;
+  if (!enabled || typeof enabled !== 'object') return true;
+  return enabled['dev-box'] === true;
+}
+
+async function instanceDevBoxSupport() {
+  if (_devBoxCheck) return _devBoxCheck;
+  _devBoxCheck = (async () => {
+    try {
+      const api = await cliClient();
+      const res = await api.instance.getInstance();
+      return { available: devBoxEnabledInManifest(res && res.ok ? res.data : null) };
+    } catch (_) {
+      return { available: true };
+    }
+  })();
+  return _devBoxCheck;
+}
+
+// The explanation a reader can act on. Deliberately does NOT name the instance: a co-tenant's
+// manifest currently reports the platform's name rather than its own, so naming it would be wrong
+// more often than helpful.
+function devBoxUnavailableMessage() {
+  return (
+    `This instance doesn't offer cloud dev boxes.\n` +
+    `  It runs without the dev-box module, so there is no box to open a shell on.\n` +
+    `  Claiming and shipping happen in a checkout of the project's repo, where the full\n` +
+    `  CLI is installed.\n` +
+    `\n` +
+    `  → Ask the project's owner for repo access, then run ${surfaceAction('claim', 'N')} from that checkout.`
+  );
+}
+
+// Throw that explanation when this instance has no dev box. Callers run it BEFORE any box call,
+// so nothing prints a confusing intermediate 404 first.
+async function assertDevBoxAvailable() {
+  const { available } = await instanceDevBoxSupport();
+  if (available) return;
+  throw new Error(devBoxUnavailableMessage());
+}
+
 async function requireSession() {
   const s = await loadSession();
   if (!s || !s.token) {
     console.error(`No Bongos session found at ${SESSION_PATH}.`);
     console.error(`You're not signed in yet — pick the line that fits:`);
-    console.error(`  • First time on the project  → run /builder-setup   (one-time GitHub sign-in that also registers you)`);
-    console.error(`  • Signed in before / expired → run /builder-reauth  (fast UI re-issue of your CLI token)`);
+    if (isTerminalSurface()) {
+      // A terminal reader may have no instance configured at all — naming one is the whole point
+      // of `login`, and `/builder-*` does not exist outside a Claude Code session (task 1003730).
+      console.error(`  • First time here            → run bongos login <instance-url>  (sign in with a browser click)`);
+      console.error(`  • Signed in before / expired → run bongos reauth                (re-issue your CLI token)`);
+    } else {
+      console.error(`  • First time on the project  → run /builder-setup   (one-time GitHub sign-in that also registers you)`);
+      console.error(`  • Signed in before / expired → run /builder-reauth  (fast UI re-issue of your CLI token)`);
+    }
     process.exit(2);
   }
   return s;
@@ -752,11 +826,21 @@ function tableTask(t) {
 // The nudges name an action the reader can run. Which spelling is right depends on who is
 // reading — see scripts/gds/surface.js (task 1003680). Fail-open: a missing surface module must
 // never break a nudge.
+//
+// Both helpers are `function` declarations so they hoist — the guidance printers above (which run
+// far earlier in the file) call them, and moving them up would churn the nudge block they belong to.
 function surfaceAction(verb, arg) {
   try { return require('./surface').action(verb, arg); }
   catch (_) { return `/builder-${verb}${arg == null ? '' : ` ${arg}`}`; }
 }
 
+// Is a person at a console reading this, rather than a Claude Code session? Fails open to AGENT,
+// so a missing/broken surface module leaves the agent contract byte-identical (task 1003730).
+function isTerminalSurface() {
+  try { return require('./surface').isTerminal(); }
+  catch (_) { return false; }
+}
+
 function nudgeActionForStage(stage) {
   switch (stage) {
     case 'auth_complete':
@@ -937,6 +1021,12 @@ module.exports = {
   _noKeepAliveResetForTest,
   cliClient,
   requireSession,
+  surfaceAction,
+  isTerminalSurface,
+  devBoxEnabledInManifest,
+  instanceDevBoxSupport,
+  devBoxUnavailableMessage,
+  assertDevBoxAvailable,
   printUnauthGuidanceAndExit,
   isBoxScope,
   printBoxScopeGuidanceAndExit,

package/scripts/gds/setup.js

@@ -19,7 +19,7 @@
 // home directory) and prints the builder profile.
 
 const readline = require('readline');
-const { cliClient, saveSession, SESSION_PATH, loadSession, printOnboardingNudge, API_BASE, hallBase } = require('./cli-lib');
+const { cliClient, saveSession, SESSION_PATH, loadSession, printOnboardingNudge, API_BASE, hallBase, surfaceAction, isTerminalSurface } = require('./cli-lib');
 
 // The instance's status dashboard, from branding — never a hardcoded host, so a
 // non-OTB instance points its builders at ITS OWN dashboard (task 1002428).
@@ -386,8 +386,11 @@ async function finishSetup(builder) {
       console.log('');
       console.log('Newcomer path:');
       console.log(`  1. Choose thy craft:  open ${hallBase()} (creative / engineering)`);
-      console.log('  2. Survey work:       /builder-start');
-      console.log('  3. Claim + ship:      /builder-claim N    →    /builder-ship');
+      console.log(`  2. Survey work:       ${surfaceAction('start')}`);
+      console.log(`  3. Claim + ship:      ${surfaceAction('claim', 'N')}    →    ${surfaceAction('ship')}`);
+      // Claiming writes code, so it needs a checkout. In a terminal the public CLI answers
+      // `bongos claim` with where to get one; say so here rather than let step 3 look self-serve.
+      if (isTerminalSurface()) console.log('     (claim + ship run in a checkout — `bongos claim` shows how to get one)');
       console.log('  4. Ship three works and you rise to Thetes — the whole queue opens.');
     }
   } catch (_) {
@@ -546,11 +549,11 @@ async function main() {
       console.error('');
       console.error('This GitHub account has not been approved yet.');
       console.error('An Archon must approve your access request before you can enroll.');
-      console.error('  → Ask an Archon to invite you, then re-run /builder-setup.');
+      console.error(`  → Ask an Archon to invite you, then re-run ${surfaceAction('setup')}.`);
       process.exit(1);
     }
     if (flow.state !== 'ok') {
-      console.error(`\nSign-in did not complete (${flow.state}). Re-run /builder-setup.`);
+      console.error(`\nSign-in did not complete (${flow.state}). Re-run ${surfaceAction('setup')}.`);
       process.exit(1);
     }
     const { token, builder } = flow;
@@ -629,7 +632,9 @@ async function main() {
       console.error(`${require('./cli-lib').productName()} admits new builders by invitation: an Archon must`);
       console.error('approve your access request before you can enroll.');
       console.error('  → Ask an Archon to invite you / approve your access request,');
-      console.error('    then re-run /builder-setup (or: node scripts/gds/setup.js).');
+      console.error(isTerminalSurface()
+        ? `    then re-run ${surfaceAction('setup')}.`
+        : '    then re-run /builder-setup (or: node scripts/gds/setup.js).');
       process.exit(1);
     }
     if (!poll.ok) {

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // 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.611'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.613'; // 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/cli_surface.mjs

@@ -144,3 +144,172 @@ test('the skills still invoke the scripts directly, which is what keeps agents o
   const skill = fs.readFileSync(path.join(REPO_ROOT, '.claude', 'skills', 'builder-start', 'SKILL.md'), 'utf8');
   assert.match(skill, /node scripts\/gds\/start\.js/, 'builder-start must call the script directly');
 });
+
+// ── 4. The rest of the shipped CLI, not just start.js (task 1003730) ────────────────────────
+//
+// Section 3 above pinned start.js and nothing else, which is exactly why eleven `/builder-*`
+// lines shipped in @cloudbongos/cli@0.1.1 — including the one EVERY unauthenticated verb prints.
+// A terminal reader was told to run `/builder-setup`, which exists only inside Claude Code.
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+
+// Every .js the public package ships, read out of the build manifest so a newly-shipped script
+// is covered the day it is added rather than the day someone remembers to list it here.
+function shippedScripts() {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'build-cli-package.js'), 'utf8');
+  const block = src.match(/const FILES = \[([\s\S]*?)\n\];/);
+  assert.ok(block, 'could not read the FILES manifest out of build-cli-package.js');
+  return [...block[1].matchAll(/'([^']+\.js)'/g)].map((m) => m[1]);
+}
+
+// Run one cli-lib guidance printer in a child process (they all call process.exit) and return
+// everything it wrote. HOME is pointed at nothing so no real session can satisfy requireSession.
+function runGuidance(fn, env) {
+  const code =
+    `const l=require(${JSON.stringify(path.join(REPO_ROOT, 'scripts', 'gds', 'cli-lib.js'))});` +
+    `Promise.resolve(l[${JSON.stringify(fn)}]()).catch(()=>{});`;
+  const r = spawnSync(process.execPath, ['-e', code], {
+    encoding: 'utf8',
+    env: { ...process.env, ...env, HOME: path.join(REPO_ROOT, 'no-such-home-for-tests') },
+  });
+  return `${r.stdout || ''}${r.stderr || ''}`;
+}
+
+const GUIDANCE = ['printUnauthGuidanceAndExit', 'printBoxScopeGuidanceAndExit', 'requireSession'];
+
+test('no guidance path speaks slash commands to a terminal reader', () => {
+  for (const fn of GUIDANCE) {
+    const out = runGuidance(fn, { BONGOS_SURFACE: 'terminal' });
+    const leaks = [...out.matchAll(/\/builder-[a-z-]+/g)].map((m) => m[0]);
+    assert.deepEqual(leaks, [], `${fn} leaked to a terminal reader: ${leaks.join(', ')}\n${out}`);
+    assert.ok(!/node scripts\/gds\//.test(out), `${fn} told a terminal reader to run a repo script:\n${out}`);
+  }
+});
+
+test('the agent still gets its slash commands from those same paths', () => {
+  // The inverse guard: a blanket rewrite that "fixed" the leak by deleting the slash commands
+  // would break the reader they were written for, and nothing else here would notice.
+  assert.match(runGuidance('printUnauthGuidanceAndExit', {}), /\/builder-reauth/);
+  assert.match(runGuidance('printBoxScopeGuidanceAndExit', {}), /\/builder-reauth/);
+  assert.match(runGuidance('requireSession', {}), /\/builder-setup/);
+});
+
+test('every shipped script that names a slash command routes it through the surface switch', () => {
+  // A `/builder-*` literal is only legitimate inside a surface branch. Rather than parse
+  // branches, require that any shipped file printing one also consults the switch — and pin the
+  // set, so a NEW unguarded file fails here instead of on a newcomer's laptop.
+  const ALLOWED = new Set([
+    'scripts/gds/cli-lib.js',        // agent side of the three branches, proven above
+    'scripts/gds/setup.js',          // re-run + newcomer-path lines, asserted below
+    'scripts/gds/box-connect-lib.js',// key-registration hint, asserted below
+    'scripts/gds/surface.js',        // the switch itself
+    'scripts/gds/start.js',          // section 3's documented agent-only exemptions
+  ]);
+  const offenders = [];
+  for (const rel of shippedScripts()) {
+    const full = path.join(REPO_ROOT, rel);
+    if (!fs.existsSync(full)) continue;
+    const code = fs.readFileSync(full, 'utf8')
+      .split('\n').filter((l) => !l.trim().startsWith('//')).join('\n');
+    // Only lines that actually PRINT — a comment or a require path is not user-facing.
+    const prints = code.split('\n').filter((l) => /\/builder-[a-z-]/.test(l) && /console\.(log|error)|log\(/.test(l));
+    if (prints.length && !ALLOWED.has(rel)) offenders.push(`${rel}: ${prints[0].trim()}`);
+  }
+  assert.deepEqual(offenders, [], `shipped scripts print slash commands with no surface switch:\n${offenders.join('\n')}`);
+});
+
+test('setup.js routes its newcomer path and re-run lines through the surface', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'setup.js'), 'utf8');
+  // The completion footer is the worst possible place for a wrong command: it is the first thing
+  // a brand-new builder reads after registering.
+  assert.match(src, /Survey work:\s*\$\{surfaceAction\('start'\)\}/, 'the newcomer path must use surfaceAction');
+  assert.match(src, /surfaceAction\('claim', 'N'\)/, 'claim step must use surfaceAction');
+  assert.ok(!/console\.log\('  2\. Survey work:       \/builder-start'\)/.test(src), 'hard-coded /builder-start left in setup.js');
+  assert.match(src, /re-run \$\{surfaceAction\('setup'\)\}/, 'the re-run lines must use surfaceAction');
+});
+
+test('box-connect-lib names the box command for the reader it has', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'box-connect-lib.js'), 'utf8');
+  assert.ok(!/add it via \/builder-box/.test(src), 'hard-coded /builder-box left in box-connect-lib.js');
+  assert.match(src, /add it via \$\{surfaceAction\('box'\)\}/);
+});
+
+// ── 5. The dead end: an instance with no dev box (task 1003730) ─────────────────────────────
+//
+// `bongos claim N` refuses and points at `bongos shell`. On an instance whose manifest carries
+// no dev-box module that call 404s, so the public CLI's only offered route to a checkout was a
+// hard error — a newcomer could see the work and not start it. The manifest always said so;
+// nothing read it.
+
+const cliLib = require(path.join(REPO_ROOT, 'scripts', 'gds', 'cli-lib.js'));
+
+test('the manifest decides, and only an explicit roster can prove absence', () => {
+  assert.equal(cliLib.devBoxEnabledInManifest({ modules: { enabled: { 'dev-box': true } } }), true);
+  assert.equal(cliLib.devBoxEnabledInManifest({ modules: { enabled: { economy: true } } }), false);
+});
+
+test('the check fails OPEN — a hiccup must never block a working box', () => {
+  // Every one of these is "I could not tell", and the safe answer to that is to proceed and let
+  // the real API call speak. Failing closed here would break `bongos shell` on every instance
+  // running a core too old to publish a module roster.
+  for (const manifest of [null, undefined, {}, { modules: {} }, { modules: { enabled: null } }, 'nonsense']) {
+    assert.equal(cliLib.devBoxEnabledInManifest(manifest), true, `should fail open for ${JSON.stringify(manifest)}`);
+  }
+});
+
+test('the explanation names a command the reader can actually run', () => {
+  // It routes through the same switch as everything else: a terminal reader must not be handed
+  // `/builder-claim`, and an agent in a checkout must still get it.
+  const prev = process.env.BONGOS_SURFACE;
+  try {
+    process.env.BONGOS_SURFACE = 'terminal';
+    const term = cliLib.devBoxUnavailableMessage();
+    assert.ok(!/\/builder-/.test(term), `slash command in the terminal dev-box message: ${term}`);
+    assert.match(term, /bongos claim N/);
+    assert.match(term, /doesn't offer cloud dev boxes/);
+    assert.match(term, /checkout/, 'must name the actual alternative, not just refuse');
+
+    delete process.env.BONGOS_SURFACE;
+    assert.match(cliLib.devBoxUnavailableMessage(), /\/builder-claim N/, 'agents keep the slash command');
+  } finally {
+    if (prev === undefined) delete process.env.BONGOS_SURFACE;
+    else process.env.BONGOS_SURFACE = prev;
+  }
+});
+
+test('both box entry points check BEFORE they touch the box API', () => {
+  // Ordering is the whole point: key registration hits the box API too, so gating only the
+  // ensure call still printed "Could not register your key (not_found)" first.
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'box-connect-lib.js'), 'utf8');
+  assert.match(
+    src,
+    /async function prepareConnection\([^)]*\) \{[\s\S]{0,400}?await assertDevBoxAvailable\(\);[\s\S]{0,200}?ensureSshKey/,
+    'prepareConnection must assert before ensureSshKey/key registration',
+  );
+  assert.match(
+    src,
+    /async function ensureBoxActive\([^)]*\) \{\s*await assertDevBoxAvailable\(\);/,
+    'ensureBoxActive must assert before postBoxEnsure',
+  );
+});
+
+test('the raw box passthrough explains a 404 too', () => {
+  // `bongos box` is api.js aimed at POST /box/ensure, so without this it dumped a bare 404 body.
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'api.js'), 'utf8');
+  assert.match(src, /instanceDevBoxSupport/, 'api.js must consult the dev-box check');
+  assert.match(src, /res\.status === 404/, 'only on a 404');
+  assert.match(src, /\\\/box\\b/, 'and only for a box path — api.js stays generic');
+});
+
+test('the generated dispatcher does not promise a dev box it cannot verify', () => {
+  // The dispatcher has no session or manifest yet, so it must present `bongos shell` as
+  // conditional. Stating it flatly is what sent newcomers into the 404.
+  const gen = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'build-cli-package.js'), 'utf8');
+  assert.ok(
+    !/'To get a checkout without installing anything locally/.test(gen),
+    'the unconditional promise is back in the checkout-only refusal',
+  );
+  assert.match(gen, /If this instance offers cloud dev boxes/);
+  assert.match(gen, /Not every instance runs dev boxes/);
+});