@bongos/core 1.18.3 → 1.18.19

package/scripts/gds/cf-tunnel.js

@@ -89,6 +89,128 @@ function ipv4Dispatcher() {
 
 const CfApiError = makeApiError('CfApiError', 'CF_API_ERROR');
 
+// The Cloudflare token permission each ruleset phase is gated behind, named exactly
+// as it reads in the dashboard's token editor so the guidance is click-followable.
+const RULESET_PHASE_PERMISSION = {
+  [COOKIE_STRIP_PHASE]: 'Transform Rules',
+  [CACHE_BYPASS_PHASE]: 'Cache Rules',
+};
+
+// The one fix for every not-readable verdict: widen the token. Both edit scopes are
+// named because provisioning applies BOTH ruleset legs (cookie-strip + cache-bypass)
+// and an operator in the token editor should add them in one pass.
+function rulesetScopeGuidance(zone) {
+  return `Widen CLOUDFLARE_API_TOKEN on the control plane: Cloudflare dashboard → My Profile → API Tokens → `
+    + `edit the token → Permissions → add "Zone → Transform Rules → Edit" (the ADR 0053 cookie-strip) and `
+    + `"Zone → Cache Rules → Edit" (the sandbox cache bypass) → Zone Resources → Include → Specific zone → ${zone} `
+    + `→ Continue → Save. Only the account owner can do this. Until then, apply the rule by hand in the dashboard `
+    + `(see docs/recipes/builder-box-lifecycle.md).`;
+}
+
+// PURE. Given the outcome of the READ-ONLY phase-entrypoint probe (HTTP status +
+// parsed Cloudflare JSON), say what we actually know about the token's scope.
+//
+// HONESTY — THIS IS A NEGATIVE DETECTOR, NOT A POSITIVE ONE. The probe is a GET, so
+// a 200 proves the token can READ the phase entrypoint; it does NOT prove the token
+// can EDIT it. Cloudflare exposes no read-only way to prove edit scope — only the
+// real PUT does. So:
+//   - 401/403  → DEFINITIVELY no scope. This is the actionable case the preflight
+//                exists to catch, and the only verdict we assert about the token.
+//   - 200/404  → readable. Edit scope stays UNPROVEN until the rule PUT runs.
+//   - anything else → inconclusive, reported as not-readable so the operator is
+//                warned rather than falsely reassured.
+// The field is named `readable` and never `editable` for exactly this reason, and no
+// verdict here may render as "scope confirmed".
+function classifyRulesetScope({ status, body, phase, zone }) {
+  const z = String(zone || '');
+  const perm = RULESET_PHASE_PERMISSION[phase] || 'Transform Rules';
+  if (status === 401 || status === 403) {
+    return {
+      readable: false,
+      reason: `Cloudflare refused to read the "${phase}" ruleset on ${z} (HTTP ${status}) — the token definitively lacks zone "${perm}" scope there`,
+      guidance: rulesetScopeGuidance(z),
+    };
+  }
+  // A zone with no rules in this phase yet has no entrypoint ruleset. That is a
+  // legitimate empty state (ensureCookieStripRule's PUT creates it), not a denial.
+  if (status === 404) {
+    return {
+      readable: true,
+      reason: `the "${phase}" phase has no entrypoint ruleset on ${z} yet (HTTP 404) — readable; edit scope is NOT proven until the rule is applied`,
+      guidance: '',
+    };
+  }
+  if (status !== 200 || !body || body.success !== true) {
+    const errs = body && Array.isArray(body.errors) ? body.errors.map((e) => e && e.message).filter(Boolean).join('; ') : '';
+    return {
+      readable: false,
+      reason: `the "${phase}" ruleset probe on ${z} failed and is inconclusive (HTTP ${status}${errs ? `: ${errs}` : ''})`,
+      guidance: `Re-run once network/Cloudflare recovers. If it keeps failing, ${rulesetScopeGuidance(z)}`,
+    };
+  }
+  return {
+    readable: true,
+    reason: `the token can READ the "${phase}" ruleset on ${z} — edit scope is NOT proven until the rule is applied`,
+    guidance: '',
+  };
+}
+
+// Read-only preflight for a zone ruleset phase. Does its OWN raw fetch rather than
+// routing through CfTunnelApi._req, because _req THROWS on failure and is dry-run
+// gated — a preflight must return a verdict (never throw) and must run on the
+// dry-run path too. Mirrors provision.js's checkDnsTokenScope.
+//
+// Deliberately does NOT use `GET /user/tokens/verify`: an IP-locked token answers
+// "Invalid API Token" there even when it is valid (docs/recipes/builder-box-
+// lifecycle.md). Probe the real operation instead.
+//
+// Returns { zone, phase, readable, reason, guidance[, zoneId] }. Never throws.
+async function checkRulesetScope({
+  zone, phase = COOKIE_STRIP_PHASE, token = process.env.CLOUDFLARE_API_TOKEN,
+  fetchImpl, zoneId = null, dispatcher,
+} = {}) {
+  const base = { zone, phase };
+  if (!zone) return { ...base, readable: false, reason: 'no Cloudflare zone given', guidance: 'set CLOUDFLARE_ZONE on the control plane' };
+  if (!token) {
+    return { ...base, readable: false, reason: `no CLOUDFLARE_API_TOKEN configured`,
+      guidance: `Set CLOUDFLARE_API_TOKEN in the control-plane box.env. ${rulesetScopeGuidance(zone)}` };
+  }
+  const doFetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  if (!doFetch) return { ...base, readable: false, reason: 'no fetch implementation available', guidance: 'run on a Node with global fetch, or inject fetchImpl' };
+  const init = { headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' } };
+  if (dispatcher !== undefined) init.dispatcher = dispatcher;
+  else { const d = ipv4Dispatcher(); if (d) init.dispatcher = d; }
+
+  let id = zoneId;
+  if (!id) {
+    let res;
+    try {
+      res = await doFetch(`${CF_API_BASE}/zones?name=${encodeURIComponent(zone)}`, init);
+    } catch (e) {
+      return { ...base, readable: false, reason: `Cloudflare zone lookup failed: ${e.message}`, guidance: 'check control-plane network + token, then retry' };
+    }
+    const body = await res.json().catch(() => null);
+    const match = (body && Array.isArray(body.result) ? body.result : []).find((r) => r && r.id);
+    if (!match) {
+      const errs = body && Array.isArray(body.errors) ? body.errors.map((e) => e && e.message).filter(Boolean).join('; ') : '';
+      return { ...base, readable: false,
+        reason: `could not resolve zone "${zone}" (HTTP ${res.status}${errs ? `: ${errs}` : ''})`,
+        guidance: `Check that CLOUDFLARE_API_TOKEN is valid and its Zone Resources include ${zone}. ${rulesetScopeGuidance(zone)}` };
+    }
+    id = match.id;
+  }
+
+  let status = 0; let bodyJson = null;
+  try {
+    const res = await doFetch(`${CF_API_BASE}/zones/${id}/rulesets/phases/${phase}/entrypoint`, init);
+    status = res.status;
+    bodyJson = await res.json().catch(() => null);
+  } catch (e) {
+    return { ...base, zoneId: id, readable: false, reason: `Cloudflare ruleset probe failed: ${e.message}`, guidance: 'check control-plane network + token, then retry' };
+  }
+  return { ...base, zoneId: id, ...classifyRulesetScope({ status, body: bodyJson, phase, zone }) };
+}
+
 // Deterministic per-builder names so teardown can find what provision created
 // WITHOUT persisting an id in the DB (no migration): the tunnel name and the DNS
 // hostname are both pure functions of the login.
@@ -359,25 +481,38 @@ class CfTunnelApi extends JsonHttpApi {
     const zoneId = await this.getZoneId(zone);
     await this.upsertDnsRoute({ zoneId, name: hostname, tunnelId });
     await this.upsertDnsRoute({ zoneId, name: previewHost, tunnelId });
+    // Both edge-rule legs are BEST-EFFORT and report their outcome STRUCTURALLY so
+    // the caller can surface a failure in its summary instead of leaving it buried
+    // in a mid-run log line (task 1002511). `applied` is false in dry-run because
+    // nothing WAS applied — these are security/caching controls, and a plan must
+    // never read as though the rule is in place.
+    const edgeRules = {
+      cookieStrip: { applied: false, error: null },
+      cacheBypass: { applied: false, error: null },
+    };
     // SECURITY (#919 / SR#11): strip the apex cookie at the edge for the box
-    // subdomains. BEST-EFFORT — a CF token without Transform Rules scope must not
-    // block provisioning (the box still works; the rule is defense-in-depth). Warn
+    // subdomains. A CF token without Transform Rules scope must not block
+    // provisioning (the box still works; the rule is defense-in-depth). Warn
     // loudly so the operator adds the scope or applies the rule once by hand.
     try {
       await this.ensureCookieStripRule({ zone });
+      edgeRules.cookieStrip.applied = !this.dryRun;
     } catch (e) {
+      edgeRules.cookieStrip.error = e.message;
       this.log(`⚠ #919 cookie-strip Transform Rule NOT applied (${e.message}) — add zone "Transform Rules" scope to CLOUDFLARE_API_TOKEN or apply it once in the CF dashboard (ADR 0053)`);
     }
     // #1065: stop Cloudflare's 4h Browser Cache TTL from serving stale sandbox
-    // game code. BEST-EFFORT — a CF token without Cache-Rules scope must not block
-    // provisioning. Warn loudly so the operator adds the scope or applies the rule
-    // once by hand (operator blocker, like the cookie-strip rule).
+    // game code. A CF token without Cache-Rules scope must not block provisioning.
+    // Warn loudly so the operator adds the scope or applies the rule once by hand
+    // (operator blocker, like the cookie-strip rule).
     try {
       await this.ensureCacheBypassRule({ zone });
+      edgeRules.cacheBypass.applied = !this.dryRun;
     } catch (e) {
+      edgeRules.cacheBypass.error = e.message;
       this.log(`⚠ #1065 sandbox cache-bypass Cache Rule NOT applied (${e.message}) — add zone "Cache Rules" (Account Rulesets) scope to CLOUDFLARE_API_TOKEN or add it once in the CF dashboard`);
     }
-    return { tunnelId, token, hostname, previewHostname: previewHost, created };
+    return { tunnelId, token, hostname, previewHostname: previewHost, created, edgeRules };
   }
 
   // Tear down the per-builder tunnel + its DNS route. Best-effort: each leg is
@@ -416,4 +551,8 @@ module.exports = {
   tunnelName, terminalHostname, previewHostname,
   // #1065: the sandbox edge cache-bypass rule constants, exported for the test.
   CACHE_BYPASS_PHASE, CACHE_BYPASS_RULE_DESC, CACHE_BYPASS_EXPRESSION,
+  // #919 / SR#11: the cookie-strip rule constants + the read-only scope preflight
+  // box.js runs before any droplet spend (task 1002511).
+  COOKIE_STRIP_PHASE, COOKIE_STRIP_RULE_DESC, COOKIE_STRIP_EXPRESSION,
+  classifyRulesetScope, checkRulesetScope,
 };

package/scripts/gds/claim.js

@@ -10,7 +10,7 @@
 const { execSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
-const { cliClient, requireSession, fmtTouches, printOnboardingNudge } = require('./cli-lib');
+const { cliClient, requireSession, fmtTouches, printOnboardingNudge, rewardPolicy, costPlusOnlyNote } = require('./cli-lib');
 const { nextNumbers, padAdr, padMig } = require('./next-number');
 const { CORE_NS } = require('./migration-namespace');
 const { contextPack, formatContextPack } = require('./context-pack');
@@ -85,6 +85,28 @@ function captureHeadSha() {
   }
 }
 
+// Auto-detect this claim's worktree name when --worktree is omitted, so the
+// server's one-active-claim guard (keyed on the WORKING TREE, not the shared auth
+// session) can tell genuinely-parallel worktrees apart. Only names a LINKED git
+// worktree — where git-dir != git-common-dir, i.e. a real `.claude/worktrees/<name>`
+// checkout — using its top-level directory basename (the `<name>` the convention
+// already uses). The MAIN checkout returns null (unchanged behaviour: one claim at
+// a time there — parallelism is what worktrees are for). Best-effort: any git
+// hiccup yields null, so this can never break a claim.
+function detectWorktreeName() {
+  try {
+    const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+    const commonDir = execSync('git rev-parse --git-common-dir', { encoding: 'utf8' }).trim();
+    // Same dir → the main checkout, not a linked worktree → leave unnamed.
+    if (path.resolve(gitDir) === path.resolve(commonDir)) return null;
+    const top = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+    const name = path.basename(top);
+    return name || null;
+  } catch (_) {
+    return null;
+  }
+}
+
 // task 1278: nudge (don't block) when this session's build scripts are behind
 // origin/main. The completion cards + skills are CLI-script features that ride
 // the LOCAL checkout, not the deployed server — a worktree branched from a stale
@@ -233,7 +255,10 @@ async function main() {
     process.exit(2);
   }
   const wIdx = args.indexOf('--worktree');
-  const worktree = wIdx >= 0 ? args[wIdx + 1] : null;
+  // Explicit --worktree always wins; otherwise auto-detect a linked worktree so
+  // parallel worktrees off one login each hold their own claim (the server guard
+  // keys on this). null in the main checkout → unchanged one-claim behaviour.
+  const worktree = (wIdx >= 0 ? args[wIdx + 1] : null) || detectWorktreeName();
   // touches[] cleanup [5/8] (task 880): touches[] overlap with another active
   // claim is ADVISORY for an interactive human claim (just a warning — git merge
   // is the real collision detector). The autonomous --parallel runner passes
@@ -255,7 +280,13 @@ async function main() {
     const { claim, task } = r.data;
     console.log(`Claimed task #${task.id}: ${task.title}`);
     console.log(`Claim id: ${claim.id}`);
-    console.log(`Version: ${task.version_id}  ·  Priority: P${task.priority ?? '?'}  ·  Credit reward: ${task.credits_reward}`);
+    // The reward figure is the task's ADVERTISED estimate. On a cost-plus-only
+    // instance it is never paid, so label it as an estimate and name the real
+    // payer right here — this line is where the expectation forms (task 1002469).
+    const rewardLabel = rewardPolicy(r.data.reward).perTaskCredit ? 'Credit reward' : 'Credit reward (est. only)';
+    console.log(`Version: ${task.version_id}  ·  Priority: P${task.priority ?? '?'}  ·  ${rewardLabel}: ${task.credits_reward}`);
+    const cpNote = costPlusOnlyNote(r.data.reward);
+    if (cpNote) console.log(`  ${cpNote}`);
     if (task.parallel_safe === true) console.log('Parallel-safe: yes (eligible for a parallel autonomous slot)');
     // BV1.R53 (task 1422): module_key is the primary scope signal. touches[] is
     // demoted to derived/advisory for module-keyed tasks; fall back to it for

package/scripts/gds/cli-lib.js

@@ -27,16 +27,105 @@ const SESSION_READ_PATHS = [
   ...ic.configReadPaths('gds-session.json'),
   ...ic.configReadPaths('pms-session.json'),
 ];
-// The last-resort default API base — THIS instance's own publicOrigin from the
-// branding pack (task 1002201). One source of truth in instance-config so no CLI
-// script hard-codes another instance's URL; pre-ADR-0139 the literal
-// 'https://amazonprimea.com' was baked in at four sites here, so an unconfigured
-// consumer targeted the founder's (game-only) box. Override with <PREFIX>_API_BASE
-// for local dev / staging:
+// The API base every CLI call targets, resolved ONCE through the single source of
+// truth in instance-config: <PREFIX>_API_BASE (then legacy GDS_/OTB_/PMS_) → the
+// persisted session's api_base → THIS instance's publicOrigin from the branding
+// pack. Override for local dev / staging:
 //   CLOUDBONGOS_API_BASE=http://localhost:3000 node scripts/gds/start.js
-// Resolves the configured prefix first, then legacy GDS_/OTB_/PMS_API_BASE.
-const DEFAULT_API_BASE = ic.defaultApiBase();
-const API_BASE = ic.resolveEnv('API_BASE') || DEFAULT_API_BASE;
+// No CLI script hard-codes another instance's URL (task 1002201; pre-ADR-0139 the
+// literal 'https://amazonprimea.com' was baked in at four sites here). The session
+// leg was added at task 1002427 — this const previously stopped at the branding
+// default, so module-level consumers (reauth's Settings URL, the hall links
+// hallBase() prints) named the checkout's own instance instead of the one the
+// builder is signed into.
+const API_BASE = ic.resolveApiBase();
+
+// User-Agent for the GDS CLI's HTTP calls — the branding-derived neutral platform UA
+// from the single source, src/branding.js userAgent() (`<repo.name|envPrefix>-gds/1.0`,
+// neutral fallback `cloud-bongos-gds/1.0`), matching the `cloud-bongos-` convention the
+// hooks use (tests/hook_user_agents.mjs). Was the hardcoded 'amazonprimea-gds-cli/1.0'
+// at both fetch sites — task 1002234. Resolved once so apiCall + cliClient never diverge
+// and branding is read a single time; falls back neutrally if branding is unreadable.
+const CLI_USER_AGENT = (() => {
+  try { return require('../../src/branding').userAgent(); }
+  catch (_) { return 'cloud-bongos-gds/1.0'; }
+})();
+
+// productName() — the instance's product name for user-facing CLI copy, from the
+// branding pack (task 1002428). Was hardcoded as the founder brand at several
+// print sites, so a non-OTB instance told ITS builders about someone else's
+// product. Neutral fallback, never a foreign brand.
+function productName() {
+  try {
+    const id = require('../../src/branding').branding().identity || {};
+    if (id.productName) return id.productName;
+  } catch (_) { /* fall through */ }
+  return 'Cloud Bongos';
+}
+
+// rewardPolicy() — the instance's RESOLVED reward policy (ADR 0146), for CLI copy
+// that prints a task's `credits_reward`. On a `cost-plus-only` instance that
+// number is an advertised GUIDE and is never paid; the cost-plus session reward
+// is the sole stream. Printing it bare reads as a promise, and a builder who
+// then ships and sees `+0` reasonably concludes the payout broke (it cost a real
+// session on 2026-07-26 — task 1002469).
+//
+// PREFER THE SERVER'S ANSWER. The mode is INSTANCE config, and an instance's
+// config/branding.json is NOT in the builder's checkout — a laptop resolving
+// locally sees only config/branding.neutral.json and would report the paying
+// default on the very instance that withholds. So callers pass the `reward`
+// block the server sends (GET /me, POST /claims); the local read is a fallback
+// for an older server that doesn't send one, and the ADR default is the floor.
+// Resolution itself is always economy's (ADR 0146) — never re-derived here.
+function rewardPolicy(fromServer) {
+  if (fromServer && typeof fromServer.mode === 'string') {
+    return { mode: fromServer.mode, perTaskCredit: fromServer.perTaskCredit !== false };
+  }
+  try {
+    const p = require('../../modules/economy/credits').rewardConfig();
+    if (p && typeof p.mode === 'string') return p;
+  } catch (_) { /* fall through */ }
+  return { mode: 'cost-plus-and-estimate', perTaskCredit: true };
+}
+
+// The one-line builder-facing explanation shown wherever an estimate is
+// displayed on a cost-plus-only instance. Returns null on a paying instance so
+// every call site is a no-op there. Single source for the wording so claim /
+// start / ship say the SAME thing (task 1002469).
+function costPlusOnlyNote(fromServer) {
+  if (rewardPolicy(fromServer).perTaskCredit) return null;
+  return 'This instance pays cost-plus only: you earn real session cost + 20%, not the estimate above.';
+}
+
+// hallBase(base) — the instance's builders' hall root for a given API base, e.g.
+// https://cloudbongos.com/builders. Derived from the RESOLVED base (env → session →
+// branding default), never a hardcoded host — so a CLI-printed link always points at
+// the instance the command is actually talking to, not the founder's amazonprimea box
+// (task 1002233; the printed-link twin of the task-1002201 default-base fix). Falls
+// back to `${base}/builders` when base isn't a parseable absolute URL.
+function hallBase(base = API_BASE) {
+  try { return `${new URL(base).origin}/builders`; }
+  catch { return `${String(base || '').replace(/\/+$/, '')}/builders`; }
+}
+
+// Node-24-on-Windows workaround: every CLI invocation here is a short-lived
+// process that makes one or a handful of requests, but a kept-alive socket can
+// still be mid-close when the caller's process.exit() runs, tripping a
+// UV_HANDLE_CLOSING assertion that corrupts piped JSON stdout. Connection reuse
+// buys these one-shot processes nothing, so route requests through a dispatcher
+// with keep-alive effectively disabled (mirrors cf-tunnel.js's dispatcher
+// pattern). Degrades to the default dispatcher if undici can't be required.
+let _noKeepAliveDispatcher;
+let _noKeepAliveTried = false;
+function noKeepAliveDispatcher() {
+  if (_noKeepAliveTried) return _noKeepAliveDispatcher;
+  _noKeepAliveTried = true;
+  try {
+    const { Agent } = require('undici');
+    _noKeepAliveDispatcher = new Agent({ keepAliveTimeout: 1, keepAliveMaxTimeout: 1 });
+  } catch { _noKeepAliveDispatcher = undefined; }
+  return _noKeepAliveDispatcher;
+}
 
 async function readSessionFile(p) {
   try {
@@ -97,18 +186,37 @@ function hasFlag(name, args = process.argv.slice(2)) {
   return args.includes(name);
 }
 
+// stripBom(s) — remove a leading UTF-8 BOM (U+FEFF), the artifact PowerShell's
+// `Out-File`/`>` redirection writes. JSON.parse does not strip it, so a
+// --body-file written from PS 5.1 fails to parse unless this runs first.
+// Non-string input passes through unchanged. Extracted (rather than left
+// inline in api.js) so it's unit-testable — api.js itself has no exports.
+function stripBom(s) {
+  if (typeof s !== 'string') return s;
+  return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+
+// resolveQuiet(args, env) — true when api.js's stderr status banner should be
+// suppressed: the --quiet flag or the GDS_QUIET env var. Both default to the
+// live process, matching hasFlag()'s own default-args contract. Default OFF —
+// existing pipelines that scrape the banner off stderr are unaffected.
+function resolveQuiet(args = process.argv.slice(2), env = process.env) {
+  return hasFlag('--quiet', args) || !!env.GDS_QUIET;
+}
+
 // readSessionToken() — the { token, apiBase } a token-only raw fetch needs, read
-// synchronously from the session file. Distinct from API_BASE: apiBase here also
-// honors the PERSISTED session api_base (written by setup.js) AFTER the env
-// overrides — <PREFIX>_API_BASE (incl. legacy GDS_/PMS_) || session.api_base ||
-// default. Returns null when not signed in. Callers that must FAIL OPEN (e.g. the
-// sound player) use this + their own fetch rather than apiCall (which exits on 401).
+// synchronously from the session file. apiBase resolves the one way every base
+// resolution does — <PREFIX>_API_BASE (incl. legacy GDS_/PMS_) || session.api_base
+// || the branding default — via ic.resolveApiBase, passing the session we already
+// loaded so it needs no second disk read (task 1002427). Returns null when not
+// signed in. Callers that must FAIL OPEN (e.g. the sound player) use this + their
+// own fetch rather than apiCall (which exits on 401).
 function readSessionToken() {
   const j = loadSessionSync();
   if (!j || !j.token) return null;
   return {
     token: j.token,
-    apiBase: ic.resolveEnv('API_BASE') || j.api_base || DEFAULT_API_BASE,
+    apiBase: ic.resolveApiBase({ session: j }),
   };
 }
 
@@ -121,7 +229,7 @@ function printUnauthGuidanceAndExit() {
   // Stable, single-screen guidance. Builders should see exactly this when
   // their CLI session breaks — no raw API JSON, no stack trace.
   console.error('');
-  console.error('✖ Your GDS CLI session is no longer valid.');
+  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');
@@ -164,7 +272,7 @@ function printBoxScopeGuidanceAndExit() {
   console.error('');
   console.error('    /builder-reauth      (or: node scripts/gds/reauth.js)');
   console.error('');
-  console.error('  It opens your Settings page (https://amazonprimea.com/builders/settings) on');
+  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.');
   console.error('  No terminal Device Flow. Once re-authed, re-run whichever command you were');
   console.error('  trying — if it had already done work, it resumes from where it stopped (task 941).');
@@ -189,6 +297,18 @@ function safeBranding() {
   catch { return {}; }
 }
 
+// True when THIS checkout declares an instance identity — i.e. config/branding.json
+// exists. A NEUTRAL checkout (the portable core, or a fresh template carrying only
+// branding.neutral.json) returns false: its resolved publicOrigin is just the neutral
+// placeholder, not a real declared instance, so there is nothing to enforce a session
+// against. Injectable so the pure guard stays unit-testable. (task 1002399, area 2)
+function defaultHasInstanceConfig() {
+  try {
+    const { INSTANCE_PATH } = require('../../src/branding');
+    return !!(INSTANCE_PATH && fs.existsSync(INSTANCE_PATH));
+  } catch { return false; }
+}
+
 // Host of an origin string, or null if unparseable. Comparing HOSTS (not full
 // origins) tolerates scheme / trailing-slash noise between branding + session.
 function instanceOriginHost(origin) {
@@ -200,12 +320,18 @@ function instanceOriginHost(origin) {
 // DIFFERENT instance than this repo is configured for. Fails OPEN (no mismatch)
 // when: an explicit <PREFIX>_API_BASE override is set (dev/staging — the operator
 // is deliberately steering the base); OR there is no session (nothing to borrow —
-// the no-session/401 path handles that); OR the repo declares no publicOrigin
+// the no-session/401 path handles that); OR this checkout is NEUTRAL (no
+// config/branding.json — no declared instance to enforce, so trust the session:
+// this is what lets a neutral core checkout run every /builder-* command with NO
+// <PREFIX>_API_BASE prefix — task 1002399); OR the repo declares no publicOrigin
 // (unknown identity — you can't assert a mismatch you can't define). Otherwise the
-// mismatch is expectedHost !== sessionHost.
-function detectInstanceMismatch({ session, brand = safeBranding(), env = process.env } = {}) {
+// mismatch is expectedHost !== sessionHost — the guard that still fires for a
+// BRANDED checkout whose session points at a different instance (the 2026-07-08
+// hazard).
+function detectInstanceMismatch({ session, brand = safeBranding(), env = process.env, hasInstanceConfig = defaultHasInstanceConfig } = {}) {
   if (ic.resolveEnv('API_BASE', { env })) return { mismatch: false };
   if (!session || !session.api_base) return { mismatch: false };
+  if (!hasInstanceConfig()) return { mismatch: false };
   const expected = brand && brand.domains && brand.domains.publicOrigin;
   if (!expected) return { mismatch: false };
   const expectedHost = instanceOriginHost(expected);
@@ -284,10 +410,10 @@ async function apiCall(method, urlPath, body = null, opts = {}) {
   // (local dev / staging override), then the logged-in instance, then prod. OTB
   // sessions already store api_base='https://amazonprimea.com', so this is a no-op
   // for the OTB instance and only bites once someone logs in to a different one.
-  const base = ic.resolveEnv('API_BASE') || (session && session.api_base) || DEFAULT_API_BASE;
+  const base = ic.resolveApiBase({ session: session || null });
   const headers = {
     'Content-Type': 'application/json',
-    'User-Agent': 'amazonprimea-gds-cli/1.0',
+    'User-Agent': CLI_USER_AGENT,
   };
   if (session && session.token) {
     headers['Authorization'] = `Bearer ${session.token}`;
@@ -302,6 +428,7 @@ async function apiCall(method, urlPath, body = null, opts = {}) {
     method,
     headers,
     body: body ? JSON.stringify(body) : null,
+    dispatcher: noKeepAliveDispatcher(),
   });
   const text = await res.text();
   let data;
@@ -355,7 +482,7 @@ async function cliClient(opts = {}) {
       printInstanceMismatchAndExit(mm);
     }
   }
-  const base = ic.resolveEnv('API_BASE') || (session && session.api_base) || DEFAULT_API_BASE;
+  const base = ic.resolveApiBase({ session: session || null });
   const token = (session && session.token) || null;
   const key = `${base}|${token || ''}|${allowUnauthenticated}|${allowBoxScope}`;
   if (_clientCache.has(key)) return _clientCache.get(key);
@@ -363,7 +490,8 @@ async function cliClient(opts = {}) {
   const { createClient } = await _clientModPromise;
   const authedFetch = async (url, init) => {
     init = init || {};
-    init.headers = Object.assign({ 'User-Agent': 'amazonprimea-gds-cli/1.0' }, init.headers);
+    init.headers = Object.assign({ 'User-Agent': CLI_USER_AGENT }, init.headers);
+    if (init.dispatcher === undefined) init.dispatcher = noKeepAliveDispatcher();
     const res = await fetch(url, init);
     if (res.status === 401 && !allowUnauthenticated && !_unauthExitInFlight) {
       _unauthExitInFlight = true;
@@ -386,7 +514,7 @@ async function cliClient(opts = {}) {
 async function requireSession() {
   const s = await loadSession();
   if (!s || !s.token) {
-    console.error(`No GDS session found at ${SESSION_PATH}.`);
+    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)`);
@@ -482,7 +610,7 @@ function nudgeActionForStage(stage) {
     case 'auth_complete':
       return 'Run node scripts/gds/setup.js to authenticate.';
     case 'pick_disciplines':
-      return 'Choose the work that calls you — open the hall at https://amazonprimea.com/builders and pick engineer, artist, ideator, or any mix.';
+      return `Choose the work that calls you — open the hall at ${hallBase()} and pick engineer, artist, ideator, or any mix.`;
     case 'first_start':
       return 'Run /builder-start to survey what you can claim.';
     case 'first_claim':
@@ -537,7 +665,7 @@ function printCostWarning(meBody) {
 // when nothing needs action (covered / satisfied items don't nag) or when the
 // payload is absent (older API / network glitch). One line per item, with the
 // concrete place to fix it. The hall Standing card renders the same `needs` data.
-const HALL_BASE = 'https://amazonprimea.com/builders';
+const HALL_BASE = hallBase();
 function printNeedsNudge(meBody) {
   if (!meBody || typeof meBody !== 'object') return;
   const needs = meBody.needs;
@@ -606,12 +734,18 @@ function parseSessionRequest(text) {
 
 module.exports = {
   API_BASE,
+  hallBase,
+  productName,
+  rewardPolicy,
+  costPlusOnlyNote,
   SESSION_PATH,
   loadSession,
   loadSessionSync,
   saveSession,
   arg,
   hasFlag,
+  stripBom,
+  resolveQuiet,
   readSessionToken,
   apiCall,
   cliClient,

package/scripts/gds/code.js

@@ -67,11 +67,15 @@ async function main() {
 
   if (local) return runLocal({ log });
 
-  console.log('▸ Connecting VS Code to your Amazonprimea dev box…');
-  const { box } = await lib.prepareConnection({ log });
+  console.log(`▸ Connecting VS Code to your ${require('./cli-lib').productName()} dev box…`);
+  const { box, keyPath } = await lib.prepareConnection({ log });
   const host = box.hostname;
   const authority = lib.remoteAuthority(host);
 
+  // BV1.R101: re-scope /workspace to the active claim before the window opens, so
+  // VS Code shows exactly that task's code. Best-effort — VS Code opens regardless.
+  lib.resyncBoxOverSsh({ host, keyPath, log });
+
   if (!noExtension) {
     log(`  Installing Claude's VS Code extension on the box (${lib.CLAUDE_VSCODE_EXTENSION})…`);
     const ext = runCode(['--remote', authority, '--install-extension', lib.CLAUDE_VSCODE_EXTENSION]);