@bongos/core 1.19.572 → 1.19.573

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.572",
-  "core_contract": "1.19.572",
-  "source_commit": "31894c826b1cb16600f02046b2e17a09f78f3712",
+  "core_version": "1.19.573",
+  "core_contract": "1.19.573",
+  "source_commit": "4dac3d1041574ffba78b27c7586c270a75f23d2a",
   "source_ref": "HEAD",
-  "built_at": "2026-09-07T00:51:07.099Z",
+  "built_at": "2026-09-07T01:25:15.478Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 450,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2516,
-  "tree_sha256": "dc4746621684478bdfcc20dba9ccc094ed1722956378f38939e11ff3f83e35d5",
+  "tree_sha256": "3b3601c11e3adbff7e0520361632f5bebe355f1da99cdbc8f67b773da63a87d0",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -112,7 +112,7 @@
     {
       "path": ".claude/skills/builder-start/SKILL.md",
       "mode": "0000644",
-      "sha256": "37b65ec352cb7ca14a117f4e21c7bdbb2808d0ad3af48fdfd1fe3f700778fcc2"
+      "sha256": "5f67e62add4e4d2dd1d6cc26702d0b278dda25158a805b98f4da26541e92d749"
     },
     {
       "path": ".claude/skills/builder-sync/SKILL.md",
@@ -2692,7 +2692,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "d7acc0617ab16007150c0f733248576e5c285286f22b32ec722fa061748994f9"
+      "sha256": "0b6c38bb0ded3d36a7024229c993f6d3271772f582af4b2b9aa2633805e55329"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7547,12 +7547,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "439507cc695f5ef93f4fe1aa9a48556b4b9e11a023fa4e60912de1ed8befc5ee"
+      "sha256": "18bdddc767294c810ce9ee48f2e3dd0f56b4e4ac796762654ec092e1ca6a3d4d"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "bf5fe42d980095754ea4b13501ede3a559376dae4127a99915767ba4be0c27d2"
+      "sha256": "8b5e28c08069f6c10abad7791bac3829918e1fd7a2b8d5a126e6bcbb9348591b"
     },
     {
       "path": "public-docs/index.html",
@@ -8782,7 +8782,7 @@
     {
       "path": "scripts/gds/start.js",
       "mode": "0000644",
-      "sha256": "cb37801c6ef35a64734af422c9651b287236c4d67f7ed72a63e1cd75a94d8b38"
+      "sha256": "81c60afdec1b7b05babe1eceaad38e0f27b932bef74e9dcb2cd3782c58524e30"
     },
     {
       "path": "scripts/gds/status.js",
@@ -9252,7 +9252,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "be71a580784409ac5e4507201fbbf9915e16f0682098e3b9e98ec49a0af98216"
+      "sha256": "6f2d2cf5cb0bbe6626a121ee87675ed9596875e644221aa0c4e21b14cdc0bbfc"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12302,7 +12302,7 @@
     {
       "path": "tests/start_env_guard.mjs",
       "mode": "0000644",
-      "sha256": "ef2cf566dc4fcb71487357b181c28bd9bebe4f0b4ec0800c6b7d33e1bf03a1c5"
+      "sha256": "9b0a7d7aeb761cb6fb0c5e1ae650e0848af12e92887ebd630814b35b434c1f41"
     },
     {
       "path": "tests/start_rebase_warning.mjs",

package/.claude/skills/builder-start/SKILL.md

@@ -31,8 +31,13 @@ Delivery is now deterministic (task 1288). The **card-delivery hook** (`.claude/
 
 `/builder-start` is frequently the **first** command run in a freshly-cloned instance, where the local environment isn't set up yet. In that state the script can't produce a card — so **route the builder to the one missing step instead of surfacing a raw error**. Match what you see and relay the single fix, plainly:
 
-- **`bongos: command not found`, a "cannot find module" from `node scripts/gds/start.js`, or you can otherwise tell this is a fresh checkout** (a scaffolded instance whose `node_modules` is absent). The `bongos` CLI ships *inside* the not-yet-installed `@bongos/core` package, so nothing runs until deps are installed — this is the #1 fresh-clone wall. Route: run `npm install`, then `bongos dev` (one-command local bring-up), then re-run `/builder-start`. Don't try to hand-run internal scripts; the package isn't unpacked yet.
-- **The card says the instance isn't reachable / running.** The local server was never brought up. Route: `bongos dev`, then re-run. (`start.js` now prints this guided card itself on a connection failure — relay it verbatim.)
+> **FIRST, read WHERE THIS INSTANCE'S BOARD LIVES — `config/branding.json` → `domains.buildersOrigin`.** Every route below branches on it, and getting it wrong is worse than an error. A **remote `https://` origin** means the board is **HOSTED**: it is a running website with the builder's real tasks in it. A **`localhost`** origin means the instance is genuinely local and has to be brought up. Prescribing the local cure on a hosted instance walks the builder through three obedient steps to a board that is not theirs.
+
+- **`bongos: command not found`, a "cannot find module" from `node scripts/gds/start.js`, or you can otherwise tell this is a fresh checkout** (a scaffolded instance whose `node_modules` is absent). The `bongos` CLI ships *inside* the not-yet-installed `@bongos/core` package, so nothing runs until deps are installed — this is the #1 fresh-clone wall. Note before prescribing anything: **`@bongos/core` is a PRIVATE package**, so a bare `npm install` **404s on any machine with no `NPM_TOKEN`**. That 404 is the expected tokenless outcome, **not** a yanked or missing version — never go hunting for "a version that still exists" to repoint the dependency at. Route by `buildersOrigin`:
+  - **Hosted (remote origin)** — lead with the fact that **nothing needs installing**: the board is a website, so open `<buildersOrigin>/builders` to see and claim work right now. The CLI is an optional second client and needs a token. **Never route to `bongos dev` here** — it stands up a *local* instance with its *own empty database*, so it cannot show the hosted board and quietly answers a different question than the one asked.
+  - **Local (`localhost` origin)** — the instance really is local: `npm install`, then `bongos dev` (one-command local bring-up), then re-run `/builder-start`.
+  Either way, don't hand-run internal scripts; the package isn't unpacked yet.
+- **The card says the instance isn't reachable / running.** Same branch. **Hosted:** the server is not this machine's to start — check the origin is up (`curl -sI <buildersOrigin>/healthz`) and re-run; `bongos dev` cannot reach it, and starting a local instance instead would hide the outage behind an empty board. **Local:** the server was never brought up — route: `bongos dev`, then re-run. (`start.js` prints a guided card itself on a connection failure — relay it verbatim.)
 - **Exit code 3 / "Wrong instance — refusing to act".** This machine's signed-in session targets a *different* instance than this project's `config/branding.json`. This is correct-by-design (it prevents writing to the wrong place). Route: run the exact `bongos login <origin>` line the message prints (the origin is right there), then re-run. **Do not** set an env override to force the mismatched instance.
 - **"no Bongos session"** — the auth case above (`/builder-setup` for a first-timer, `/builder-reauth` for a stale session).
 

package/docs/module-api-changelog.md

@@ -1593,5 +1593,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.570 with no explicit bump. run 34065943703. (task 1002620)
   1.19.572 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.571 with no explicit bump. run 34071078624. (task 1002620)
+  1.19.573 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.572 with no explicit bump. run 34072921884. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.572",
+  "version": "1.19.573",
   "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/start.js

@@ -518,14 +518,56 @@ function isConnectionError(err) {
   return /fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|network|socket hang up/i.test(msg);
 }
 
+// isLocalOrigin — does this origin name a server THIS MACHINE is supposed to run?
+// The whole shape of the unreachable-instance advice turns on it, so it is its own
+// named predicate rather than an inline regex (task 1003675). Anything that is not
+// recognisably loopback is treated as REMOTE: guessing "local" for a hosted board
+// is the failure this exists to prevent, and the remote branch degrades gracefully
+// (it points at a URL) while the local branch would tell someone to stand up a
+// second, empty instance.
+function isLocalOrigin(origin) {
+  if (!origin) return true; // nothing to go on → the old local-first wording
+  let host;
+  try { host = new URL(origin).hostname.toLowerCase(); } catch (_) { return false; }
+  return host === 'localhost' || host.endsWith('.localhost')
+    || host === '127.0.0.1' || host.startsWith('127.') || host === '::1' || host === '[::1]';
+}
+
 // The guided "instance isn't running" card. Markdown (never leads with `<`), so
-// the builder-start skill relays it verbatim even in --widget mode. Tailors the
-// first step to whether deps are installed — a fresh clone needs `npm install`
-// before the `bongos` CLI (which ships inside @bongos/core) even exists.
+// the builder-start skill relays it verbatim even in --widget mode.
+//
+// It branches on WHERE THE BOARD LIVES, because the same words are actively
+// harmful in the two cases (task 1003675 — the owner hit this twice on a hosted
+// instance). A HOSTED instance is not this machine's server to start: `bongos dev`
+// would stand up a separate LOCAL instance with its OWN EMPTY DATABASE, so a
+// builder who follows it obediently arrives at a board that is not theirs and the
+// real outage stays hidden behind it. The hosted branch therefore leads with the
+// thing that needs nothing installed — the board is a website — and offers the
+// health probe instead of a bring-up.
+//
+// The local branch is unchanged, and still tailors its first step to whether deps
+// are installed: a fresh clone needs `npm install` before the `bongos` CLI (which
+// ships inside the PRIVATE @bongos/core package) even exists.
 function instanceNotRunningCard({ origin, depsMissing } = {}) {
   const out = [];
   out.push(`**builder-start — this instance isn't reachable yet**`);
   out.push('');
+
+  if (!isLocalOrigin(origin)) {
+    out.push(`I couldn't reach \`${origin}\`. That instance is **hosted** — it isn't this machine's server to start, so there's nothing to bring up here.`);
+    out.push('');
+    out.push(`1. **The board is a website, and it needs nothing installed** — open ${origin}/builders to see and claim work right now.`);
+    out.push(`2. If that doesn't load either, the instance itself is down: \`curl -sI ${origin}/healthz\` says whether it's answering.`);
+    out.push(`3. Once it answers, re-run \`/builder-start\`.`);
+    out.push('');
+    out.push(`**Don't run \`bongos dev\` for this.** It stands up a *separate local* instance with its own empty database — it cannot show you this board, and it would hide the outage behind an empty one.`);
+    if (depsMissing) {
+      out.push('');
+      out.push(`(The \`bongos\` CLI isn't installed here. It's optional — the website above is the same board. \`@bongos/core\` is a **private** package, so installing it needs an \`NPM_TOKEN\`; a 404 without one is expected, not a missing version.)`);
+    }
+    return out.join('\n');
+  }
+
   out.push(`I couldn't reach the Cloud Bongos instance${origin ? ` at \`${origin}\`` : ''}. On a freshly-cloned project that almost always just means it hasn't been brought up yet. To start it locally:`);
   out.push('');
   let n = 1;
@@ -932,4 +974,5 @@ module.exports = {
   rebaseWarningWidget,
   isConnectionError,
   instanceNotRunningCard,
+  isLocalOrigin,
 };

package/src/module-api.js

@@ -49,7 +49,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // 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.572'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.573'; // 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/start_env_guard.mjs

@@ -18,7 +18,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const { isConnectionError, instanceNotRunningCard } = require('../scripts/gds/start.js');
+const { isConnectionError, instanceNotRunningCard, isLocalOrigin } = require('../scripts/gds/start.js');
 
 let passed = 0;
 let failed = 0;
@@ -63,9 +63,12 @@ t('always points at bongos dev and the re-run', () => {
   assert.ok(card.includes('localhost:3007'), 'names the unreachable origin when known');
 });
 
+// The origin must be LOOPBACK: these assert the LOCAL bring-up card, and since
+// task 1003675 a non-loopback origin selects the hosted card, which deliberately
+// says neither of these things. `http://x` used to work here only by accident.
 t('mentions npm install ONLY when deps are missing', () => {
-  const missing = instanceNotRunningCard({ origin: 'http://x', depsMissing: true });
-  const present = instanceNotRunningCard({ origin: 'http://x', depsMissing: false });
+  const missing = instanceNotRunningCard({ origin: 'http://localhost:3007', depsMissing: true });
+  const present = instanceNotRunningCard({ origin: 'http://localhost:3007', depsMissing: false });
   assert.ok(missing.includes('npm install'), 'fresh clone (no deps) → npm install step');
   assert.ok(!present.includes('npm install'), 'deps present → skip the npm install step');
 });
@@ -79,9 +82,49 @@ t('is markdown (never leads with `<`) so the skill relays it verbatim', () => {
 });
 
 t('offers the wrong-instance escape hatch (bongos login)', () => {
-  const card = instanceNotRunningCard({ origin: 'http://x', depsMissing: false });
+  const card = instanceNotRunningCard({ origin: 'http://localhost:3007', depsMissing: false });
   assert.ok(/bongos login/.test(card), 'points at bongos login for a different running instance');
 });
 
+// --- the HOSTED branch (task 1003675) --------------------------------------
+// A hosted instance is not this machine's server to start. Telling someone to run
+// `bongos dev` there walks them to a SEPARATE, EMPTY local board — three obedient
+// steps to the wrong destination, with the real outage hidden behind it. The
+// owner hit this twice before it was fixed, so each half is pinned here.
+t('a hosted origin never routes to bongos dev', () => {
+  for (const deps of [true, false]) {
+    const card = instanceNotRunningCard({ origin: 'https://example-instance.cloudbongos.com', depsMissing: deps });
+    assert.ok(!/^\s*\d+\.\s*`bongos dev`/m.test(card), 'must not list `bongos dev` as a step');
+    assert.ok(/Don't run `bongos dev`/.test(card), 'must say plainly not to, and why');
+    assert.ok(/empty database/.test(card), 'must name the consequence, not just forbid it');
+  }
+});
+
+t('a hosted origin leads with the board being a website that needs no install', () => {
+  const card = instanceNotRunningCard({ origin: 'https://example-instance.cloudbongos.com', depsMissing: true });
+  assert.ok(card.includes('https://example-instance.cloudbongos.com/builders'), 'hands over the actual board URL');
+  assert.ok(/nothing installed/.test(card), 'says it needs nothing installed');
+  assert.ok(/healthz/.test(card), 'offers the health probe instead of a bring-up');
+});
+
+t('a hosted origin explains the private-package 404 rather than implying a lost version', () => {
+  const card = instanceNotRunningCard({ origin: 'https://example-instance.cloudbongos.com', depsMissing: true });
+  assert.ok(/private/i.test(card) && /NPM_TOKEN/.test(card), 'names the real cause of a tokenless install failure');
+  assert.ok(/not a missing version/.test(card), 'kills the "go find a version that still exists" wild goose chase');
+});
+
+t('isLocalOrigin: loopback is local, everything else is remote', () => {
+  for (const o of ['http://localhost:3000', 'http://app.localhost:3000', 'http://127.0.0.1:3000', 'http://[::1]:3000']) {
+    assert.equal(isLocalOrigin(o), true, `${o} should be local`);
+  }
+  for (const o of ['https://example-instance.cloudbongos.com', 'http://x', 'https://10.0.0.5']) {
+    assert.equal(isLocalOrigin(o), false, `${o} should be remote`);
+  }
+  // Unknown → the old local-first wording; unparseable → treated as remote, which
+  // degrades to a URL rather than to "stand up a second instance".
+  assert.equal(isLocalOrigin(''), true, 'no origin at all → keep the local wording');
+  assert.equal(isLocalOrigin('not a url'), false, 'unparseable → remote (fail toward the safer card)');
+});
+
 console.log(`\nstart_env_guard: ${passed} passed, ${failed} failed`);
 if (failed > 0) process.exitCode = 1;