@bongos/core 1.19.572 → 1.19.574

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "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.574",
+  "core_contract": "1.19.574",
+  "source_commit": "cb6c20fba8bc93877d7917986195294b3d7d2d42",
   "source_ref": "HEAD",
-  "built_at": "2026-09-07T00:51:07.099Z",
+  "built_at": "2026-09-07T02:14:28.259Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 450,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2042,
+    "functional_verbatim": 2043,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2516,
-  "tree_sha256": "dc4746621684478bdfcc20dba9ccc094ed1722956378f38939e11ff3f83e35d5",
+  "file_count": 2517,
+  "tree_sha256": "9160b243d293a7be2f13cb02991462b82a800e4e9948486d898f30a7598a0141",
   "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": "34f3a97a9b2396e37b6b8739a008aa3c79fffa0f7e02df8b8586b755d6cd0206"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4267,7 +4267,7 @@
     {
       "path": "modules/economy/credits.js",
       "mode": "0000644",
-      "sha256": "08890c50f8c8b2551a495e8a54e0e4fb2925b928ece5dc9aaf2090ea1c37adb3"
+      "sha256": "ce98912ffa428298ad4fe1a2dbf1d6e1121fb9f966cb3c41092ac40fb1428a43"
     },
     {
       "path": "modules/economy/migrations/economy_001_fix_gds_shipper_description.sql",
@@ -4284,6 +4284,11 @@
       "mode": "0000644",
       "sha256": "cc953acd69f844d158c3a79ea4de3b12d652ea0247c878c6a6c33d5abf68eab3"
     },
+    {
+      "path": "modules/economy/reward-policy.js",
+      "mode": "0000644",
+      "sha256": "e1f432cc9871bcb992face1f8ecd9f63fea17b3b67c121d59e8e28a89ba8d7d5"
+    },
     {
       "path": "modules/economy/reward.js",
       "mode": "0000644",
@@ -7547,12 +7552,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "439507cc695f5ef93f4fe1aa9a48556b4b9e11a023fa4e60912de1ed8befc5ee"
+      "sha256": "267cb45a286e4a22e781d2c5ff28f5c609683bc79b5d8c327d2b3606aa0795a2"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "bf5fe42d980095754ea4b13501ede3a559376dae4127a99915767ba4be0c27d2"
+      "sha256": "aca40a127da79a5a8217c05ab5c074072dc0840d4b2baf89159d68412cfd6a08"
     },
     {
       "path": "public-docs/index.html",
@@ -7807,7 +7812,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "5aa658b099b2acda06cdb3aecfe905da7de79f2b12c844faca091ff061454017"
+      "sha256": "b08ad47b79417816a9f132e8149f78743eefb47b8824edf3380cdea23447e07f"
     },
     {
       "path": "scripts/gds/client-baseurl-guard.js",
@@ -8782,7 +8787,7 @@
     {
       "path": "scripts/gds/start.js",
       "mode": "0000644",
-      "sha256": "cb37801c6ef35a64734af422c9651b287236c4d67f7ed72a63e1cd75a94d8b38"
+      "sha256": "81c60afdec1b7b05babe1eceaad38e0f27b932bef74e9dcb2cd3782c58524e30"
     },
     {
       "path": "scripts/gds/status.js",
@@ -9252,7 +9257,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "be71a580784409ac5e4507201fbbf9915e16f0682098e3b9e98ec49a0af98216"
+      "sha256": "8b068b3a2cefb919013cdcc7cf35ec4a84859fe16d6e5cf7723d3434370bfcd5"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12302,7 +12307,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,9 @@ 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)
+  1.19.574 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.573 with no explicit bump. run 34075598213. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/economy/credits.js

@@ -151,7 +151,24 @@ const IDEA_GOVERNANCE_PASS_FLOOR = 30;  // owner: floor ~30 — see the note on
 // these defaults; the pure helper keeps its code defaults so tests stay
 // deterministic and the call site passes the resolved config. The currency LABEL
 // is `branding.currency.label`.
-const REWARD_MARGIN_PCT = 20; // cost-plus margin, percent — DEFAULT (task 1005)
+// task 1003676: the reward POLICY (these constants + rewardPolicy/rewardConfig)
+// moved to ./reward-policy so a CLIENT can resolve it without importing this file,
+// which pulls { pool, branding } from src/module-api and with it the whole server.
+// Re-exported below, so this module is still the one place reward resolution lives
+// (ADR 0146) and every existing caller is unchanged.
+const {
+  REWARD_MARGIN_PCT, REWARD_MODE_DEFAULT, REWARD_MODE_COST_PLUS_ONLY, rewardPolicy,
+} = require('./reward-policy');
+
+// Per-instance reward policy, resolved over the code defaults. Stays HERE, not in
+// reward-policy.js: the branding read must go through the module port (ADR 0083),
+// and a file the CLI can share may not import the port. Best-effort — a branding
+// hiccup falls back to the defaults so reward accrual never crashes.
+function rewardConfig() {
+  let r = {};
+  try { r = (branding().reward) || {}; } catch { r = {}; }
+  return rewardPolicy(r);
+}
 
 // Reward MODE — which reward streams an instance pays (task 1002270, ADR 0146).
 // The two streams (ADR 0054 "two drachma conventions, one ledger") are:
@@ -170,8 +187,6 @@ const REWARD_MARGIN_PCT = 20; // cost-plus margin, percent — DEFAULT (task 100
 //       else. Cloud Bongos's choice (owner decision, 2026-07-16).
 // Unknown/garbage mode → treated as the default (pay both): a config typo must
 // never silently zero out every builder's per-task reward.
-const REWARD_MODE_DEFAULT = 'cost-plus-and-estimate';
-const REWARD_MODE_COST_PLUS_ONLY = 'cost-plus-only';
 
 // Pure policy resolver — maps a raw branding.reward object to the effective reward
 // policy. Exported so a test can assert the mapping without touching the memoized
@@ -185,24 +200,6 @@ const REWARD_MODE_COST_PLUS_ONLY = 'cost-plus-only';
 // credit writers (IC2/IC4/IC5) gate on `ideatorCredit`, never on `perTaskCredit`.
 // An instance opts the ideator lane out with `reward.ideatorCredit: false`;
 // absent/any-non-false → the default TRUE (a pre-ADR-0172 config keeps paying).
-function rewardPolicy(rawReward) {
-  const r = rawReward || {};
-  const marginPct = Number.isFinite(Number(r.marginPct)) ? Number(r.marginPct) : REWARD_MARGIN_PCT;
-  const usdPeg = Number.isFinite(Number(r.usdPeg)) && Number(r.usdPeg) > 0 ? Number(r.usdPeg) : 1;
-  const mode = r.mode === REWARD_MODE_COST_PLUS_ONLY ? REWARD_MODE_COST_PLUS_ONLY : REWARD_MODE_DEFAULT;
-  const perTaskCredit = mode !== REWARD_MODE_COST_PLUS_ONLY;
-  // Default-on, opt-out-only: only an explicit `false` withholds the ideator lane.
-  const ideatorCredit = r.ideatorCredit !== false;
-  return { marginPct, usdPeg, mode, perTaskCredit, ideatorCredit };
-}
-
-// Per-instance reward policy, resolved over the code defaults. Best-effort: a
-// branding hiccup falls back to the defaults so reward accrual never crashes.
-function rewardConfig() {
-  let r = {};
-  try { r = (branding().reward) || {}; } catch { r = {}; }
-  return rewardPolicy(r);
-}
 
 // Pure helper — exported for tests. Returns { trueCostUsd, marginPct, drachmae,
 // description }. drachmae = round(cost × (1+margin) × usdPeg); at the 1:1 peg a

package/modules/economy/reward-policy.js

@@ -0,0 +1,50 @@
+// modules/economy/reward-policy.js — the reward POLICY shape, and nothing else
+// (task 1003676).
+//
+// What it is: the reward defaults and the PURE function that resolves a branding
+// pack's `reward` block over them — margin, USD peg, mode, whether the per-task
+// credit and the ideator lane are on.
+//
+// Why it is its own file, and why it imports NOTHING: this is the one piece of
+// economy a CLIENT needs. `bongos start` prints a task's credit reward and the
+// wording depends on the mode, so the CLI must resolve the policy. It used to get
+// that by requiring credits.js, which imports { pool, branding } from
+// src/module-api at module scope — so one lazy require of one config reader pulled
+// Postgres, auth and db-kernel into the closure of every CLI subcommand, and that
+// is what made the CLI impossible to publish as a client-only package (goal
+// 1000054) and left a new builder with no private-registry credential unable to
+// claim anything.
+//
+// It takes the raw `reward` block as an ARGUMENT rather than reading branding
+// itself: a module may import only src/module-api (ADR 0083, enforced by
+// fitness.js), so a file that both a module and a client can share has to be free
+// of host reads. Each caller supplies its own — credits.js through the module port,
+// the CLI straight from src/branding. One resolver, two readers; ADR 0146's rule
+// that reward resolution is always economy's still holds, because this file is
+// economy's.
+
+// Cost-plus margin, percent — the DEFAULT (task 1005).
+const REWARD_MARGIN_PCT = 20;
+const REWARD_MODE_DEFAULT = 'cost-plus-and-estimate';
+const REWARD_MODE_COST_PLUS_ONLY = 'cost-plus-only';
+
+// PURE. Resolves a raw branding `reward` block over the code defaults. Every field
+// is validated rather than trusted: a malformed pack degrades to the defaults
+// instead of poisoning an award.
+function rewardPolicy(rawReward) {
+  const r = rawReward || {};
+  const marginPct = Number.isFinite(Number(r.marginPct)) ? Number(r.marginPct) : REWARD_MARGIN_PCT;
+  const usdPeg = Number.isFinite(Number(r.usdPeg)) && Number(r.usdPeg) > 0 ? Number(r.usdPeg) : 1;
+  const mode = r.mode === REWARD_MODE_COST_PLUS_ONLY ? REWARD_MODE_COST_PLUS_ONLY : REWARD_MODE_DEFAULT;
+  const perTaskCredit = mode !== REWARD_MODE_COST_PLUS_ONLY;
+  // Default-on, opt-out-only: only an explicit `false` withholds the ideator lane.
+  const ideatorCredit = r.ideatorCredit !== false;
+  return { marginPct, usdPeg, mode, perTaskCredit, ideatorCredit };
+}
+
+module.exports = {
+  REWARD_MARGIN_PCT,
+  REWARD_MODE_DEFAULT,
+  REWARD_MODE_COST_PLUS_ONLY,
+  rewardPolicy,
+};

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.572",
+  "version": "1.19.574",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.572",
+      "version": "1.19.574",
       "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.574",
   "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/cli-lib.js

@@ -82,7 +82,17 @@ function rewardPolicy(fromServer) {
     return { mode: fromServer.mode, perTaskCredit: fromServer.perTaskCredit !== false };
   }
   try {
-    const p = require('../../modules/economy/credits').rewardConfig();
+    // economy's PURE resolver + our own branding read, NOT ./credits (task
+    // 1003676): credits.js imports { pool, branding } from src/module-api at
+    // module scope, so this one fallback require used to drag Postgres + auth +
+    // db-kernel into EVERY CLI subcommand's closure — which is what stopped the
+    // CLI shipping as a public, client-only package. Same resolver, same answer,
+    // no server. The CLI is not a module, so reading src/branding directly here
+    // is allowed where it would not be inside modules/ (ADR 0083).
+    const { rewardPolicy: resolve } = require('../../modules/economy/reward-policy');
+    let raw = {};
+    try { raw = (require('../../src/branding').branding().reward) || {}; } catch (_) { raw = {}; }
+    const p = resolve(raw);
     if (p && typeof p.mode === 'string') return p;
   } catch (_) { /* fall through */ }
   return { mode: 'cost-plus-and-estimate', perTaskCredit: true };

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.574'; // 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;