@bongos/core 1.19.611 → 1.19.612

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "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.612",
+  "core_contract": "1.19.612",
+  "source_commit": "40c2360599907381009ddf7b676722ed4df90d10",
   "source_ref": "HEAD",
-  "built_at": "2026-09-09T03:07:36.926Z",
+  "built_at": "2026-09-09T04:22:55.358Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 458,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2562,
-  "tree_sha256": "c6a3113ed2f20af25a3ebcaee8cb4ff9cd42890d51e890a85c31ddf9d63ff5ea",
+  "tree_sha256": "5fd467fedfc4ddaeb527aba61440ecd7f5590a0ac941438cc7e28fc2240b7b3b",
   "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",
@@ -2732,7 +2732,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "4cc20b3afc8ec94a1d53e3d3f746269a1a7def4b6798d81402fe9078c002d3b1"
+      "sha256": "b4249f1559e94a715eff18a2b869b12ffab3a3bda0c99566824933a3450c8688"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7632,12 +7632,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "73ce6d69717b6ed9e4cf704e12b5578a86a5a9d34baaa1df34df7caa5accbedb"
+      "sha256": "e5976c35d2d34d80cb6beacbeaf14658a71ee0b3be7ece60cb60a48c88a09c4a"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "5ac0729891d64cd779f810b1bf4f98997a7dd8756c8baaa9d82577c7e7e29b60"
+      "sha256": "3281707852a3d8ddb7528ceb04c22b1abc9cc26d0656e502fd55fc3c7342f152"
     },
     {
       "path": "public-docs/index.html",
@@ -7712,7 +7712,7 @@
     {
       "path": "scripts/gds/api.js",
       "mode": "0000644",
-      "sha256": "96d6b69e9440dac3ed81c490e460a832d385714de0b379650af80817f89ded0f"
+      "sha256": "a018f4ccc228950065ef0a376445ba6fc79318e451f9a6bc648dc8dd97235b87"
     },
     {
       "path": "scripts/gds/api.ps1",
@@ -7807,7 +7807,7 @@
     {
       "path": "scripts/gds/box-connect-lib.js",
       "mode": "0000644",
-      "sha256": "56c6f3eae23d427d9c74763521739bae5b704bcd02ad234e43a5434645657519"
+      "sha256": "dbc4dd22d858a7d17c34ebf211edbd6d885afa39ab7b9e3032a7390cd5526638"
     },
     {
       "path": "scripts/gds/box-infra.js",
@@ -7837,7 +7837,7 @@
     {
       "path": "scripts/gds/build-cli-package.js",
       "mode": "0000644",
-      "sha256": "760dbc00a1d8ed5dfa2184e93f9106383bbb36c7fdd973ddfc67b7e03f3bc2f8"
+      "sha256": "81ad7fbc99f5c85219f1385cdd6e6954d27a0e2943f285676f060611a4878f4e"
     },
     {
       "path": "scripts/gds/bump-version.js",
@@ -7897,7 +7897,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "beb9d466f7623cae12788f23d0e30fbf3a520fec769e416ce3ad6458b23ceb2b"
+      "sha256": "44b8c997a25d9fcc68ba573d33391546ff98a871c7d99e9aa6d982c69a703824"
     },
     {
       "path": "scripts/gds/client-baseurl-guard.js",
@@ -8717,7 +8717,7 @@
     {
       "path": "scripts/gds/setup.js",
       "mode": "0000644",
-      "sha256": "98671f5666ae6bdafa7691bd519367345772c3041680b59c24ec83c56b99f419"
+      "sha256": "36b5c59af3cde0398e432db37f1cd645aab08ea70b308a5e53671a4fce06f7fe"
     },
     {
       "path": "scripts/gds/shell.js",
@@ -9362,7 +9362,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "790abd4adb2065c87aa21a729b69b33d01ed07be1c5c307a865f2f8942cc9d3f"
+      "sha256": "7b843863aec10abe437301fd0b0656d02e651f0ced17d616ccc8457b0dbfca9b"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9967,7 +9967,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/module-api-changelog.md

@@ -1671,5 +1671,7 @@ 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)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.611",
+  "version": "1.19.612",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.611",
+      "version": "1.19.612",
       "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.612",
   "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.612'; // 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/);
+});