@bongos/core 1.18.0 → 1.18.18

package/src/bongos/routes/me.js

@@ -83,7 +83,7 @@ module.exports = function buildMeRouter() {
     const [
       builder, activeClaims, estVsActual, unlocked, lockedWithProgress, streakInfo,
       recentGrades, builderAvg, onboardingRow, shipCount, recentKarma, karma30d, discordLink, boxConnected, cliAuthed,
-      behaviorPrefs, geminiKeyRow,
+      behaviorPrefs, geminiKeyRow, needsRebaseTasks,
     ] = await Promise.all([
       db.getBuilderById(req.builder.id),
       lc().getActiveClaimsForBuilder(req.builder.id),
@@ -136,6 +136,14 @@ module.exports = function buildMeRouter() {
       // Own Gemini-key status via the art-pipeline port (ADR 0102) — the storage
       // is art-pipeline domain now; degrades to a no-key shape on a vanilla instance.
       seams.resolveOptional('art.getBuilderGeminiKeyRow', async () => ({ enc: null, last4: null, set_at: null }))(req.builder.id),
+      // ADR 0120 part 5: the confirmed tasks this builder owes a rebase on —
+      // un-landed confirmed work the publish-reconciler flagged needs_rebase
+      // (part 2). It GATES new claims (part 3: claimTask refuses REBASE_REQUIRED)
+      // and its per-task reward now lands only on ship (part 1), so the CLI
+      // (/builder-start) + the hall surface an owed-rebase warning from this
+      // without a follow-up call. Through the `lifecycle` port; [] on a
+      // lifecycle-less instance (guarded — the port is resolveOptional).
+      lc() ? lc().needsRebaseTasksForBuilder(req.builder.id) : [],
     ]);
     // V3.R84 (#302), criterion C3: the builder's month-to-date spend vs their
     // monthly budget. Surfaced here so the CLI (session-start ping) and the hall
@@ -148,6 +156,18 @@ module.exports = function buildMeRouter() {
     } catch (err) {
       console.error('[gds] GET /me cost status', err);
     }
+    // Best-effort read of the resolved reward policy (see the payload note).
+    // Never break the profile over a display concern — null degrades the CLI to
+    // its own paying default rather than a wrong "not paid" claim.
+    const rewardPolicySafe = () => {
+      try {
+        const p = typeof reward.rewardConfig === 'function' ? reward.rewardConfig() : null;
+        return p && typeof p.mode === 'string' ? { mode: p.mode, perTaskCredit: p.perTaskCredit !== false } : null;
+      } catch (err) {
+        console.error('[gds] GET /me reward policy', err);
+        return null;
+      }
+    };
     // For each active claim, compute the streak preview (cheap; pool query).
     // Lets the CLI render "shipping this would extend streak to N days" hints.
     const activeClaimsWithPreview = await Promise.all(
@@ -161,6 +181,20 @@ module.exports = function buildMeRouter() {
       active_claims: activeClaimsWithPreview,
       // Legacy field — first claim only. Prefer active_claims (plural).
       active_claim: activeClaimsWithPreview[0] ?? null,
+      // ADR 0120 part 5: un-landed confirmed tasks this builder owes a rebase on.
+      // Each row: { id, title, needs_rebase_reason, needs_rebase_at }, oldest
+      // first. Empty when none owed (or on a lifecycle-less instance). These GATE
+      // new claims (part 3) and their reward is pending until they land on ship
+      // (part 1); the CLI + hall render a warning off this array.
+      needs_rebase_tasks: needsRebaseTasks,
+      // ADR 0146 / task 1002469: the instance's RESOLVED reward policy, so the
+      // CLI can label a task's advertised `credits_reward` honestly. On a
+      // `cost-plus-only` instance that estimate is never paid, and a builder who
+      // isn't told reads a correct `+0` at ship as a broken payout. It must come
+      // from the SERVER — the instance's branding.json is not in the builder's
+      // checkout, so a laptop reading local config always sees the default.
+      // Resolved by economy (never re-derived); null if economy is disabled.
+      reward: rewardPolicySafe(),
       est_vs_actual: estVsActual,
       unlocked,
       locked_with_progress: lockedWithProgress,

package/src/bongos/routes.js

@@ -20,6 +20,7 @@ const express = require('express');
 const buildHealthzRouter = require('./routes/healthz');
 const buildInstanceRouter = require('./routes/instance');
 const buildAuthRouter = require('./routes/auth');
+const buildGithubRouter = require('./routes/github');
 const buildMeRouter = require('./routes/me');
 const buildBuildersRouter = require('./routes/builders');
 // The LIFECYCLE routes (tasks · claims · versions · done-when · goals ·
@@ -116,6 +117,7 @@ function buildGdsRouter() {
   router.use(buildHealthzRouter());
   router.use(buildInstanceRouter());
   router.use(buildAuthRouter());
+  router.use(buildGithubRouter());
   router.use(buildMeRouter());
   router.use(buildBuildersRouter());
   // tasks · claims · versions · done-when · goals · dependencies · analytics now

package/src/bongos/serve-internal.js

@@ -47,7 +47,7 @@ const { buildBongosDownloads } = require('../bongos-downloads');
 const { clientBranding, branding } = require('../branding');
 const { clientModules, isModuleEnabled } = require('../modules');
 const { hallWidgetScripts, moduleWebSurfaces } = require('../module-loader/loader');
-const { resolveCoreRoot } = require('../instance-config');
+const { resolveCoreRoot, resolveDocsRoot, resolveInstanceRoot } = require('../instance-config');
 const { API_PREFIX, LEGACY_API_PREFIXES, API_VERSION, VERSIONED_API_PREFIX, ALL_API_PREFIXES } = require('./api-prefix');
 
 // ADR 0108 §1: every use of ROOT below (infra/ installers, modules/, docs/) is
@@ -56,15 +56,28 @@ const { API_PREFIX, LEGACY_API_PREFIXES, API_VERSION, VERSIONED_API_PREFIX, ALL_
 const ROOT = resolveCoreRoot();
 
 // Instance-only RELEASE config (config/devbox-app.json, config/bongos-cli.json) is
-// boundary-excluded from the portable core (publish-manifest INSTANCE_EXCLUDE), so a
-// vanilla self-host boot ships without it. Requiring it hard used to CRASH the boot
-// (task 1824). Guard the require so an absent config makes its download surface simply
-// not mount (fail-to-vanilla, like branding/modules) rather than take the server down.
-// A malformed config (JSON parse error, etc.) still throws — only a MISSING file is
-// tolerated. A branded instance that ships the config gets the routes exactly as before.
-function tryRequireConfig(relPath) {
-  try { return require(relPath); }
-  catch (e) { if (e && e.code === 'MODULE_NOT_FOUND') return null; throw e; }
+// boundary-excluded from the portable core (publish-manifest INSTANCE_EXCLUDE), so it is
+// HOST content: it lives at the INSTANCE root, which on a vendored instance is NOT the
+// package dir this file sits under. A core-relative require therefore looked in
+// node_modules/@bongos/core/config/ and never found it, so /downloads/* silently failed
+// to mount (task 1002371 — same class as ADR 0144's vendored infra/ path bug; ADR 0145's
+// copy-the-config-into-node_modules workaround is lost on the next `npm ci`). So resolve
+// the instance root FIRST — the branding/modules resolution (src/branding.js INSTANCE_PATH)
+// — then the core package dir, which keeps a single checkout (and that copied-in
+// workaround) byte-identical.
+//
+// Fail-soft is preserved verbatim: an ABSENT config makes its download surface simply not
+// mount (fail-to-vanilla, like branding/modules) rather than crash the boot as the original
+// hard require did (task 1824); a MALFORMED config still throws — only a MISSING file is
+// tolerated. `roots` is injected so the ladder is unit-testable with zero ambient state.
+function tryLoadInstanceConfig(name, roots = [resolveInstanceRoot(), ROOT]) {
+  for (const root of new Set(roots)) {
+    let raw;
+    try { raw = fs.readFileSync(path.join(root, 'config', name), 'utf8'); }
+    catch (e) { if (e.code === 'ENOENT') continue; throw e; }
+    return JSON.parse(raw);
+  }
+  return null;
 }
 
 // Map the pack's camelCase theme color keys → the kebab-case CSS custom
@@ -193,6 +206,60 @@ function docsIndexHtml() {
   return _docsHtml;
 }
 
+// The OpenAPI 3.1 spec served at /docs/openapi.json — SELF-HEALING (task 1002200).
+// The Redoc page (public-docs/) ships as static assets, but the SPEC is a generated
+// artifact whose on-disk copy is NOT guaranteed at every deploy topology, so a bare
+// res.sendFile(one fixed path) 404s exactly when the file is missing:
+//   • Standalone instance (ADR 0108/0140): the route resolves from the CORE package
+//     (resolveCoreRoot → node_modules/@bongos/core) while the generator writes the
+//     INSTANCE's own spec to resolveDocsRoot (the instance repo) — a path mismatch.
+//   • A pinned @bongos/core that predates the spec's packaging ships NO copy at all
+//     (the observed cloudbongos.com 404: public-docs/ shipped, docs/api/ didn't).
+//   • A fresh instance, before its first generate, has neither.
+// So resolve the spec in tiers: (1) the committed spec at resolveDocsRoot() (the
+// instance's own — carries its module routes), then (2) at resolveCoreRoot() (the
+// core-package copy), then (3) GENERATE it in-process from the live route source.
+// gen-api-docs.build() reads routes from resolveCoreRoot() (always present — it IS
+// the running code), is DB-free + express-free (a pure line+regex extractor that
+// never executes a route or opens a connection), and yields the identical spec.
+// resolveOpenapiJson is the pure, injectable core so the fallback ladder is unit-
+// testable (tests/docs_openapi_route.mjs).
+function resolveOpenapiJson({ candidates = [], generate } = {}) {
+  for (const p of candidates) {
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; } // absent → next tier
+    try { JSON.parse(raw); } catch { continue; }                  // corrupt → next tier
+    return raw;
+  }
+  if (typeof generate === 'function') {
+    try {
+      const out = generate();
+      if (out) return out;
+    } catch (e) {
+      console.error('[docs] in-process OpenAPI generation failed:', e && e.message);
+    }
+  }
+  return '';
+}
+
+// Memoized like docsIndexHtml: one resolve per process; a redeploy restarts and
+// re-resolves. '' (→ the route falls through to 404) only if every tier fails.
+let _openapiJson;
+function openapiJson() {
+  if (_openapiJson !== undefined) return _openapiJson;
+  const roots = [...new Set([resolveDocsRoot(), ROOT])]; // instance repo first, then core pkg
+  _openapiJson = resolveOpenapiJson({
+    candidates: roots.map((r) => path.join(r, 'docs/api/openapi.json')),
+    generate() {
+      // Lazy require: boot never pays for it, and a generator hiccup is contained
+      // to this one endpoint rather than taking down server start.
+      const gen = require('../../scripts/gds/gen-api-docs.js');
+      return JSON.stringify(gen.build().spec, null, 2) + '\n';
+    },
+  });
+  return _openapiJson;
+}
+
 // The browser-global build of the generated typed client (task 1996 / R09),
 // served at /lib/bongos-client.js so classic <script> web pages can consume the
 // same generated client the CLI uses (window.BongosClient). Read once at boot
@@ -408,7 +475,7 @@ function mountInternalSurfaces(app) {
   // builders.<apex> (the builders rewrite shim below only prefixes non-/api
   // paths, so without this placement /downloads/* would be rewritten to
   // /builders/downloads/* and 404).
-  const devboxCfg = tryRequireConfig('../../config/devbox-app.json');
+  const devboxCfg = tryLoadInstanceConfig('devbox-app.json');
   if (devboxCfg) {
     const devboxDownloads = buildDevboxDownloads(devboxCfg);
     app.get('/downloads/devbox/latest.json', (_req, res) => {
@@ -439,7 +506,7 @@ function mountInternalSurfaces(app) {
   // every user-facing URL on the apex. The installer scripts are served with the
   // server's PINNED origin substituted for __GDS_API_BASE__ — never a request
   // header, so a spoofed Host can't redirect a `curl | sh` (the box-connect.sh rule).
-  const bongosCfg = tryRequireConfig('../../config/bongos-cli.json');
+  const bongosCfg = tryLoadInstanceConfig('bongos-cli.json');
   if (bongosCfg) {
     const bongosDownloads = buildBongosDownloads(bongosCfg);
     // Pinned public origin for the served installer scripts (never a request header —
@@ -847,7 +914,7 @@ function mountInternalSurfaces(app) {
   // external fetch (matches the /vendor/* self-hosting convention; CSP-safe).
   //   GET /docs                    → the Redoc host page (branding-injected)
   //   GET /docs/redoc.standalone.js → the vendored renderer (long-cached)
-  //   GET /docs/openapi.json        → the generated spec (CORS-open so Postman/Swagger/AI can fetch it)
+  //   GET /docs/openapi.json        → the spec, SELF-HEALING (committed → generated), CORS-open so Postman/Swagger/AI can fetch it; see openapiJson()
   app.get('/docs', (req, res, next) => {
     if (isModuleSurfaceHost(req)) return next();
     const html = docsIndexHtml();
@@ -864,10 +931,12 @@ function mountInternalSurfaces(app) {
   });
   app.get('/docs/openapi.json', (req, res, next) => {
     if (isModuleSurfaceHost(req)) return next();
+    const json = openapiJson();
+    if (!json) return next(); // no committed spec + generation failed → fall through to 404
     res.set('Access-Control-Allow-Origin', '*'); // read-only spec — tools fetch it cross-origin
     res.set('Cache-Control', 'public, max-age=60');
     res.type('application/json');
-    res.sendFile(path.join(ROOT, 'docs/api/openapi.json'));
+    res.send(json);
   });
 
   app.use((req, res, next) => {
@@ -895,4 +964,4 @@ function mountInternalSurfaces(app) {
   return app;
 }
 
-module.exports = { mountInternalSurfaces, isStatusHost, isBuildersHost, injectBrandingGlobal, injectBrandingInto, injectModuleHallWidgets, themeMarkup, applyBrandTokens };
+module.exports = { mountInternalSurfaces, isStatusHost, isBuildersHost, injectBrandingGlobal, injectBrandingInto, injectModuleHallWidgets, themeMarkup, applyBrandTokens, resolveOpenapiJson, openapiJson, tryLoadInstanceConfig };

package/src/branding.js

@@ -44,6 +44,16 @@ const ENV_OVERRIDES = [
   ['OAUTH_ORIGIN', ['domains', 'oauthOrigin']],
   ['PROVISIONING_ORIGIN', ['domains', 'provisioningOrigin']],
   ['COOKIE_DOMAIN', ['domains', 'cookieDomain']],
+  // Cross-site identity federation flip (ADR 0141 §4). Provisioning sets
+  // <PREFIX>_AUTH_IDP=true per hosted instance (config/branding.neutral.json ships
+  // idp:false), so a co-tenant instance sharing the neutral pack still federates
+  // individually. 'bool'-coerced below — auth.js idpEnabled() reads it as strict === true.
+  ['AUTH_IDP', ['auth', 'idp'], 'bool'],
+  // Post-sign-in landing when no ?return=/Referer was carried (auth.js
+  // postLoginLanding). Env-overridable so a platform-home instance can flip its
+  // front door with one env var and no instance branding.json — cloudbongos.com
+  // sets <PREFIX>_POST_LOGIN_LANDING=/gate/ (the orbs). Task 1002240.
+  ['POST_LOGIN_LANDING', ['landing', 'postLogin']],
 ];
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
@@ -69,6 +79,12 @@ function deepFreeze(o) {
   return o;
 }
 
+// This is the ONE structured host-identity contract. Project context (vision/world/visual-style
+// prose in docs/project-context.md) is deliberately PROSE-ONLY — there is no parallel resolver for
+// it, because nothing in the platform reads project context as data; it is written for agents to
+// read. If a host value must be CODE-READ, add it HERE (branding), not a new project-context
+// resolver. Decided in ADR 0142 (audit H11 / task 1002224).
+//
 // Pure resolver — all inputs injected, so tests drive it with zero I/O.
 function resolveBranding({ neutral = {}, instance = {}, env = {} } = {}) {
   // structuredClone so the merged result shares no nested references with the
@@ -76,9 +92,13 @@ function resolveBranding({ neutral = {}, instance = {}, env = {} } = {}) {
   // the caller's input objects (deepMerge shallow-copies only the top level).
   const resolved = structuredClone(deepMerge(neutral, instance));
   const prefix = resolved.envPrefix || 'CLOUDBONGOS';
-  for (const [suffix, p] of ENV_OVERRIDES) {
+  for (const [suffix, p, coerce] of ENV_OVERRIDES) {
     const v = env[`${prefix}_${suffix}`];
-    if (v !== undefined && v !== '') setPath(resolved, p, v);
+    if (v === undefined || v === '') continue;
+    // Most overrides are string-valued (origins, cookie domain) and set verbatim. A
+    // 'bool'-tagged override (auth.idp) coerces the env string to a real boolean —
+    // idpEnabled() checks `=== true`, so an uncoerced "true" would never federate.
+    setPath(resolved, p, coerce === 'bool' ? /^(1|true|yes|on)$/i.test(String(v)) : v);
   }
   const missing = REQUIRED.filter((p) => {
     const v = getPath(resolved, p);
@@ -177,7 +197,34 @@ function clientBranding(b = branding()) {
       notFound: b.copy?.notFound || 'Page not found.',
     },
     rankLabels: b.rankLabels || {},
+    reward: clientReward(),
   };
 }
 
+// The RESOLVED reward policy, projected client-safe (ADR 0146 follow-up, task
+// 1002469). Display surfaces need to know which streams this instance actually
+// pays — on a `cost-plus-only` instance the per-task "Est." is a guide, never a
+// payout, and a builder who is not told that reads a correct `+0` as a bug.
+//
+// Resolved through the economy module's `reward` port, NOT re-derived here: the
+// mode→perTaskCredit mapping is economy's to own (ADR 0146 put the knob inside
+// the module deliberately). `module-seams` is a dependency-free leaf, so this
+// adds no boot-order coupling to the config layer.
+//
+// Fail-safe: an instance with economy disabled, or a resolve that throws, falls
+// back to the ADR 0146 DEFAULT (pay both streams) — the same direction the pure
+// resolver takes an unknown mode, so a hiccup can never silently tell builders
+// their per-task reward is withheld.
+function clientReward() {
+  const fallback = { mode: 'cost-plus-and-estimate', perTaskCredit: true };
+  try {
+    const reward = require('./module-seams').resolveOptional('reward');
+    const p = reward && typeof reward.rewardConfig === 'function' ? reward.rewardConfig() : null;
+    if (!p || typeof p.mode !== 'string') return fallback;
+    return { mode: p.mode, perTaskCredit: p.perTaskCredit !== false };
+  } catch (_) {
+    return fallback;
+  }
+}
+
 module.exports = { resolveBranding, loadBranding, deepMerge, branding, clientBranding, userAgent, NEUTRAL_PATH, INSTANCE_PATH };

package/src/instance-config.js

@@ -50,6 +50,50 @@ function envPrefix(b = safeBrand()) {
   return b.envPrefix || FALLBACK_ENV_PREFIX;
 }
 
+// The default API base the CLI targets when there is no <PREFIX>_API_BASE env
+// override AND no logged-in session api_base — i.e. the last-resort fallback.
+// Resolves to THIS instance's own publicOrigin from the branding pack (OTB →
+// https://amazonprimea.com, vanilla → http://localhost:3000), so the portable
+// core never hard-codes another instance's URL (task 1002201 — pre-ADR-0139 the
+// literal 'https://amazonprimea.com' was baked into cli-lib, sending every
+// unconfigured consumer at the founder's game box). Single source of truth: every
+// CLI base resolution routes through here. Last-resort http://localhost:3000 when
+// branding can't be read at all — a local dev origin, never a foreign prod, so an
+// unconfigured raw CLI fails safe rather than acting against someone else's DB.
+function defaultApiBase(b = safeBrand()) {
+  const origin = b && b.domains && b.domains.publicOrigin;
+  return (typeof origin === 'string' && origin.trim()) || 'http://localhost:3000';
+}
+
+// The API base a CLI command should actually talk to:
+//   <PREFIX>_API_BASE (env) → the PERSISTED session's api_base → defaultApiBase()
+// The session beats the branding default because a builder authenticated against
+// instance A must keep hitting A even when this checkout's own branding names B —
+// which is exactly what broke re-auth (task 1002427). cliClient() had this order
+// right; paste-token.js hardcoded the founder host and reauth.js used the bare
+// branding default, so a token minted by one instance was verified against
+// another and rejected 401. Every base resolution routes through here so the
+// three cannot drift again.
+//
+// `session` is injected by callers that already loaded it (cliClient) and read
+// from the session file otherwise; pass null to mean "no session" without a disk
+// read. Never returns empty — an unusable api_base falls back to the default.
+function resolveApiBase({ session, env = process.env, b = safeBrand() } = {}) {
+  const fromEnv = resolveEnv('API_BASE', { env, prefix: envPrefix(b) });
+  if (fromEnv) return fromEnv;
+  let s = session;
+  if (s === undefined) {
+    try {
+      const raw = readConfigFileSync('gds-session.json', { b });
+      s = raw ? JSON.parse(raw) : null;
+    } catch (_) {
+      s = null; // unreadable/corrupt session must never break base resolution
+    }
+  }
+  const fromSession = s && typeof s.api_base === 'string' && s.api_base.trim();
+  return fromSession || defaultApiBase(b);
+}
+
 // Absolute path to the instance config dir — the WRITE target and first read.
 function configHome(b = safeBrand()) {
   return path.join(os.homedir(), '.config', configDirName(b));
@@ -186,6 +230,8 @@ module.exports = {
   LEGACY_ENV_PREFIXES,
   configDirName,
   envPrefix,
+  defaultApiBase,
+  resolveApiBase,
   configHome,
   configReadDirs,
   configPath,

package/src/module-api.js

@@ -218,8 +218,138 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         post-dates the published 1.17.3 tarball — a new user-facing feature set with no
 //         doorway export removal, so semver MINOR. NOT yet published to npm (that is the
 //         follow-on release task); amazonprimea still runs the vendored 1.17.3.
+// 1.18.1 — go-live cut deployed to cloudbongos.com (owner-directed, 2026-07-14). Rolling
+//         1.18.0 content PLUS the onboarding GitHub repo picker + auto-create (task 1002099,
+//         ADR 0143 — core auth: opt-in public_repo scope, encrypted short-TTL token store,
+//         GET/POST /github/repos) and the goal 1000041 cross-project hub features
+//         (platform-identity module, ADR 0141). Adds no doorway export → semver PATCH.
+// 1.18.2 — go-live cut for cloudbongos.com (owner-directed, 2026-07-14). Rolling 1.18.1
+//         content PLUS the /create onboarding repo-picker rendering fix (task 1002228):
+//         the Home step's `hidden` attribute was defeated by author display rules
+//         (.field/.row2), so the adopt-picker / fresh-name / manual sub-panels all showed
+//         at once, and #ghConnect never appeared (toggled via `hidden` instead of its .on
+//         class). A CSS/markup-only fix in public-landing/create.html. No doorway export
+//         change → semver PATCH.
+// 1.18.3 — package-core .gitignore pin fix (task 1002229, idea 1000543). `npm install` never
+//         materializes .gitignore/.npmignore/.npmrc into an installed package, but package-core
+//         pinned a tracked .gitignore in tree_sha256 → every vendored `bongos upgrade` pin-verify
+//         failed with `missing installed file: .gitignore` and auto-rolled-back (the workaround
+//         was --skip-pin-verify, which the unattended auto-upgrade subscription cannot pass).
+//         package-core now drops npm-stripped files from the manifest + pin so it describes exactly
+//         what npm installs. Build-tool fix, no doorway export change → semver PATCH.
+// 1.18.4 — ship the platform-identity hub module in the core package (task 1002235, goal 1000041).
+//         The module (ADR 0141: /sso/*, projects catalog, my-projects, scouting + its migrations) was
+//         built but never added to publish-manifest PUBLISH_ALLOWLIST, so it did not ship in
+//         @bongos/core — the hub's enabledModules() threw "unknown module platform-identity" and
+//         provision.js's federation load MODULE_NOT_FOUNDed. Reclassified IN (sibling of provisioning);
+//         default:false → shipped ≠ enabled, dormant on every instance until the hub turns it on. PATCH.
+// 1.18.5 — configurable post-login landing (task 1002240, goal 1000041). A successful web sign-in
+//         that carried no explicit ?return= / same-apex Referer now lands on branding.landing.postLogin
+//         (auth.js postLoginLanding) instead of a hardcoded /builders. Portable default stays
+//         '/builders' (the hall always exists); env-overridable per instance via
+//         <PREFIX>_POST_LOGIN_LANDING. cloudbongos.com sets it to /gate/ so a visitor who signs in
+//         from the orbs returns to the orbs, never auto-redirected into the builders' hall. The value
+//         is validated through the open-redirect allowlist. Additive config read, no doorway change → PATCH.
+// 1.18.6 — post-login ?return= fix (task 1002241). parseCookie() now URL-DECODES the cookie
+//         value, symmetric with Express res.cookie's percent-ENCODING. Before this, a return
+//         target like "/create" was stored as "%2Fcreate"; safeReturnTo() rejected the encoded
+//         form and every explicit ?return= fell through to the post-login landing (on
+//         cloudbongos.com, /gate/) — most visibly the onboarding "Connect GitHub" button, which
+//         bounced to the orbs instead of back to the wizard. Also un-breaks the #726 subdomain
+//         return. A bug fix in a shared route helper, no doorway change → PATCH.
+// 1.18.7 — federated single-logout (task 1002238, goal 1000041, ADR 0144). Signing out of the hub now
+//         signs you out of every federated project too. Core gains: a `builder.logout` seam event
+//         (emitted by POST /auth/logout), a POST /auth/backchannel-logout endpoint (dormant unless the
+//         instance federates — idp set), and auth.js verifyHubLogoutToken. The hub (platform-identity)
+//         listens for builder.logout and fans a hub-signed EdDSA logout token out to each federated
+//         instance the builder entered, which verifies it (aud-scoped, purpose-tagged, ~120s TTL) and
+//         revokes that builder's local sessions. Identity/trust boundary intact (the token carries only
+//         a subject + purpose, never a rank). Additive event + route, no doorway change → PATCH.
+// 1.18.8 — hall sign-out works on every page (task 1002245). The real sign-out (POST /auth/logout:
+//         revoke session + clear cookies + emit the `builder.logout` federated single-logout) was wired
+//         ONLY in the index script (builders.js); shell.js draws the sign-out control on EVERY hall page
+//         as a bare GET anchor to the POST-only endpoint, so on non-index pages the click 404'd — the
+//         session was never revoked and the hub never notified (the 1.18.7 SLO was bypassed). Centralized
+//         in shell.js (doLogout + a delegated click listener), with tests/hall_signout.mjs proving it.
+//         Also carries minor /create wizard polish (tasks 1002246/1002247). Client + shared-surface fix,
+//         no doorway change → PATCH.
+// 1.18.9 — /create onboarding: the wizard's own "Sign in with GitHub" now requests repo scope up front
+//         (read:user + public_repo via &repos=1), so a visitor who signs in THROUGH the create flow grants
+//         everything in one GitHub screen and never hits the separate "Connect GitHub" step at Home —
+//         ensureRepoAccess()'s probe finds the stored token and shows the picker/creator directly. Also
+//         reworks the residual need-connect copy + button ("Allow repo access") so a user already signed
+//         in with identity-only scope isn't asked to "connect" as if signing in twice. Hall + CLI sign-in
+//         stay identity-only (ADR 0143 least-privilege default). Client-only (public-landing/create.html),
+//         no doorway change → PATCH. (task 1002259)
+// 1.18.10 — reward-mode go-live: the configurable per-instance branding.reward.mode knob (economy;
+//         ADR 0146) lands together with the goal-1000037 pay-on-land migrations. Cloud Bongos selects
+//         "cost-plus-only" (instance config), so a shipped task pays only the cost-plus session reward,
+//         not the per-task author estimate; the estimate still rides the row for display + the no-zero
+//         claim gate. This deploy applies core_193 (tasks.needs_rebase columns) + core_194 (the one-time
+//         confirmed-backlog clawback). Default stays "cost-plus-and-estimate" → every other instance is
+//         unchanged; economy-only, no doorway change → PATCH. (task 1002270 + goal 1000037 go-live 1002273)
+//   1.18.12 — Docs-surface correctness (task 1002374). User-facing "GDS"/"Game Development System" →
+//         "Bongos" (primer, OpenAPI spec title/description + reference header, the two CLI session
+//         messages the primer quotes). 04-architecture diagram REDRAWN for the standalone model —
+//         own repo + auto-pull deploy (ADR 0129) + vendored @bongos/core (ADR 0108), product-neutral;
+//         it had hardcoded the reference game monorepo (amazonprimea.com / GitHub-Actions deploy-prod.yml
+//         / "the live game"). Docs/prose + diagram generator only, no schema/doorway change → PATCH.
+//   1.18.11 — Standalone instances get live-updating docs (ADR 0147, task 1002314). gen-session-index.js
+//         now resolves the INSTANCE root (was hardcoded to the core, so a standalone box indexed
+//         node_modules/@bongos/core instead of its own sessions); adds upgrade.regenerateNavDocs() +
+//         a regen-instance-docs.js CLI wired into init/upgrade/provision-deploy; INSTANCE_GITIGNORE
+//         ignores the whole-file nav docs. Docs-pipeline only, no schema/doorway change → PATCH.
+//         (go-live 1002318)
+//   1.18.12 — docs-surface correctness: GDS→Bongos rename + standalone architecture redraw
+//         (task 1002374). Docs/prose + diagram generator only, no schema/doorway change → PATCH.
+//   1.18.13 — `bongos dev`: one-command LOCAL launcher for a standalone instance (task 1002397,
+//         ADR 0149). New CLI verb + scripts/gds/dev.js + dev-lib.js so a freshly-created,
+//         localhost-configured project stands up locally in one step. No schema/doorway change → PATCH.
+//   1.18.14 — module pollers actually start on a standalone instance (task 1002419). The loader's
+//         startModulePollers had ZERO callers once the game entrypoint server.js was retired, so
+//         EVERY module poller was dead — most visibly lifecycle/publish-reconciler, which is what
+//         drives confirmed→shipped, leaving merged tasks stranded at 'confirmed' indefinitely
+//         (12 rows, oldest 6.2 days). src/platform-server.js now starts them at boot behind the
+//         same isEnabled gate mountModuleRoutes uses, and stops them on SIGTERM/SIGINT. Wiring
+//         only — no schema/doorway change → PATCH. Any instance on ≤1.18.13 lands nothing until
+//         it takes this bump.
+//   1.18.15 — re-release of the 1.18.14 module-poller fix (task 1002419) under a fresh number.
+//         A SEPARATE release had already published 1.18.14 for the task-scoped dev-box go-live
+//         (goal 1000051), so the poller-fix 1.18.14 could never reach an instance already pinned to
+//         the dev-box 1.18.14 (same version = npm no-op; the pull-deploy loop skips npm ci when the
+//         lockfile is unchanged). This bump carries the identical src/platform-server.js poller
+//         wiring forward on a number no instance has taken yet, so the pin can actually move. No
+//         code delta vs the 1.18.14 already on main — version constant only → PATCH. (task 1002421)
+//   1.18.16 — go-live carrier for the hall version-UI work already merged to main since 1.18.15:
+//         the Roadmap "Command deck" redesign (task 1002426) and the sidebar reorg — nav order
+//         Roadmap→Goals→Tasks, the "Work" board relabelled "Tasks", goal-detail task parity
+//         (task 1002425, PR #17). Both landed on main with NO version bump, so no vendored-tarball
+//         instance could take them (the pull-deploy pin only moves on a fresh number). No new code
+//         delta beyond this constant → PATCH. (go-live task 1002431)
+//   1.18.17 — Goals page reorganised into a task-readiness rollup (grouped
+//         Active/Blocked/Achieved; each goal rolls its tasks into ready/in-progress/
+//         blocked + a next claimable task) and the task-list API gained an opt-in
+//         `?include=deps` that enriches each task with blocked_by[]/blocks so the
+//         hall can paint readiness without an N+1 (db.attachTaskDepSummaries). New
+//         export is additive; the enrichment is opt-in → PATCH. (task 1002439)
+//   1.18.18 — go-live carrier for 171 commits that landed on main between 2026-07-24
+//         and 2026-08-03 with no bump behind them, so no vendored-tarball instance
+//         could take any of them. Headline: the governance permission system
+//         (BV1.R95–R109 — resolver + kernel port, first-class principals, session
+//         scopes, requirePermission(), ownership-scoped grants, config/governance.json)
+//         and the route-rank/validation hardening that followed it; the ship.js
+//         Windows project-path fix so Windows sessions actually get paid (89f291c);
+//         the sequential chain runner (task 1002484); Metic task abandon/un-abandon
+//         (ADR 0152); goal-authored criteria + the orphan-task goal_advisory (ADR
+//         0154); the nightly-backup 203/EXEC fix (task 1002479); and a broad hall
+//         pass (jump palette, sidebar regroup, browser-side idea triage, mobile
+//         overflow). This bump also carries the /version-vs-CORE_VERSION divergence
+//         check added under task 1002521 — the gap above went unnoticed for ten days
+//         precisely because nothing compared live against main. The doorway surface
+//         is byte-identical to 1.18.17 (governance is reached through the kernel
+//         port, not a new export), so despite the size this is → PATCH. (task 1002521)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.18.0'; // see the changelog above — 1.18.0 is the first cut from the cloud-bongos authoritative source (re-seed task 2190); includes the builders'-hall UI redesign beyond published 1.17.3
+const CORE_VERSION = '1.18.18'; // go-live carrier for 171 unreleased commits + the deploy-divergence check (task 1002521); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');
@@ -245,6 +375,15 @@ module.exports = {
   //     tokens. A module's own bootstrap routes flag themselves; everything else
   //     stays closed to box tokens (the ADR 0016 trust boundary).
   allowBoxScope: auth.allowBoxScope,
+  // resolveSession(req) — resolve the request to a live session row (or null)
+  //     WITHOUT the 401-or-pass behaviour of requireBuilder. A module route that
+  //     must make its own auth decision — e.g. a browser page that REDIRECTS to
+  //     sign-in on a missing session rather than returning JSON 401 (the
+  //     platform-identity /sso/authorize leg, ADR 0141) — needs the raw resolve.
+  //     Returns the same shape lookupSession does (builder_id, github_id,
+  //     github_login, display_name, avatar_url, rank, source, status); rank is
+  //     still never an authority a module should trust for cross-instance identity.
+  resolveSession: (...a) => auth.resolveSession(...a),
 
   // --- data — the shared Postgres pool. A module owns its namespaced tables
   //     (<key>_*) via its own migrations (BV1.R46); it reaches them through this.