@bongos/core 1.17.0 → 1.17.2

package/scripts/gds/upgrade.js

@@ -7,7 +7,7 @@
 //
 //   pre-flight   clean git tree + module-compat vs the TARGET core version
 //     → bump pin   vendor the new core .tgz, rewrite the package.json `file:` dependency
-//     → npm install  node_modules/@cloudbongos/core becomes the new version
+//     → npm install  node_modules/@bongos/core becomes the new version
 //     → migrate      `npm run migrate` → the core's migrate.sh applies additive `core_*` migrations
 //     → materialize  refresh .claude/ skills+settings+hooks from the new core (claude-materialize / W3)
 //     → restart      restart the instance's service so the new core is live
@@ -16,7 +16,7 @@
 // SCOPE (ADR 0100 §2, reshaped by ADR 0103 §4): the SMALLEST channel the FIRST real consumer needs
 // on its first core bump — driven by that consumer, not designed up front. That consumer is
 // emersonian-circles (task 1917): a greenfield npm-dependency instance that pins the core as
-//   "@cloudbongos/core": "file:vendor/cloudbongos-core-<ver>.tgz"
+//   "@bongos/core": "file:vendor/bongos-core-<ver>.tgz"
 // with `start`/`migrate` npm scripts and a materialized .claude/. Every step below maps to something
 // that consumer actually has. A published-registry source, rollback, and multi-consumer shapes are
 // deliberately OUT — they are follow-ups a second consumer's needs will define.
@@ -30,9 +30,10 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
+const { writeNpmrc, hasNpmToken } = require('./npmrc'); // ADR 0134 (task 2090): the --registry channel's env-fed .npmrc
 
-const CORE_PKG = '@cloudbongos/core';
-const ARTIFACT = 'cloudbongos-core';
+const CORE_PKG = '@bongos/core';
+const ARTIFACT = 'bongos-core';
 
 // ---- pure helpers (no I/O side effects beyond the injected fs) --------------
 
@@ -44,6 +45,16 @@ function versionFromTgzPath(p) {
   return m ? m[1] : null;
 }
 
+// The version from a REGISTRY dep spec — a bare semver, optionally range-prefixed
+// (`1.17.0`, `^1.17.0`, `~1.17.0`). Returns null for a `file:` tarball spec (that's
+// versionFromTgzPath's job) so the two never both match. ADR 0134 (task 2090).
+function versionFromDep(dep) {
+  const s = String(dep || '').trim();
+  if (!s || /^file:/.test(s)) return null;
+  const m = s.match(/^[\^~>=<\s]*v?(\d+\.\d+\.\d+[A-Za-z0-9.+-]*)$/);
+  return m ? m[1] : null;
+}
+
 function readJson(file, fsImpl = fs) {
   try { return JSON.parse(fsImpl.readFileSync(file, 'utf8')); } catch { return null; }
 }
@@ -54,11 +65,13 @@ function readInstalledCoreVersion(instanceDir, fsImpl = fs) {
   return pkg && pkg.version ? pkg.version : null;
 }
 
-// The version the consumer's package.json currently pins (from the `file:` tarball path).
+// The version the consumer's package.json currently pins — from either the `file:`
+// tarball path (vendored) or a bare registry semver (ADR 0134). A best-effort "from"
+// hint; readInstalledCoreVersion (node_modules) is the authoritative source.
 function readPinnedCoreVersion(instanceDir, fsImpl = fs) {
   const pkg = readJson(path.join(instanceDir, 'package.json'), fsImpl);
   const dep = pkg && ((pkg.dependencies || {})[CORE_PKG] || (pkg.devDependencies || {})[CORE_PKG]);
-  return versionFromTgzPath(dep);
+  return versionFromTgzPath(dep) || versionFromDep(dep);
 }
 
 // Rewrite the consumer package.json to pin `file:<vendorRel>`. Returns the previous dep string.
@@ -73,6 +86,35 @@ function writePin(instanceDir, vendorRel, fsImpl = fs) {
   return prev;
 }
 
+// Rewrite the consumer package.json to pin an EXACT registry version (ADR 0134, task
+// 2090): the registry sibling of writePin. `npm install` then resolves @bongos/core@version
+// from the registry (auth via the env-fed .npmrc). Returns the previous dep string.
+function writeRegistryPin(instanceDir, version, fsImpl = fs) {
+  const pkgPath = path.join(instanceDir, 'package.json');
+  const pkg = readJson(pkgPath, fsImpl);
+  if (!pkg) throw new Error(`no readable package.json at ${pkgPath}`);
+  pkg.dependencies = pkg.dependencies || {};
+  const prev = pkg.dependencies[CORE_PKG];
+  pkg.dependencies[CORE_PKG] = version;
+  fsImpl.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  return prev;
+}
+
+// Restore the consumer package.json's @bongos/core pin to an EXACT previous dep string,
+// VERBATIM — whether that was a `file:` tarball path (vendored) or a bare registry semver.
+// The inverse of writePin/writeRegistryPin used by the auto-rollback path (task 2149), which
+// snapshots the returned prev-dep before the bump. Returns the dep string it overwrote.
+function restorePin(instanceDir, depString, fsImpl = fs) {
+  const pkgPath = path.join(instanceDir, 'package.json');
+  const pkg = readJson(pkgPath, fsImpl);
+  if (!pkg) throw new Error(`no readable package.json at ${pkgPath}`);
+  pkg.dependencies = pkg.dependencies || {};
+  const prev = pkg.dependencies[CORE_PKG];
+  pkg.dependencies[CORE_PKG] = depString;
+  fsImpl.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  return prev;
+}
+
 // ---- steps (each injectable for tests) --------------------------------------
 
 function gitTreeClean(instanceDir, run = spawnSync) {
@@ -127,10 +169,11 @@ function runMigrate(instanceDir, run = spawnSync) {
 
 // Regenerate the per-instance API artifacts (OpenAPI spec + api-reference + typed
 // client) from the NEW core's routes — the claude-materialize sibling (task 2051).
-// WHY: the routes + generators ship WITH core, but the generated spec/docs/client are
-// EXCLUDED from the package (per-instance artifacts), so a bump changes the served API
-// while the instance's committed spec/client lag until the next ship's fitness gate.
-// This closes that gap on upgrade. We SPAWN the new core's generators (a fresh child
+// WHY: the routes + generators ship WITH core, and the generated spec/docs/client also
+// ship as CORE STARTERS (task 2078 — a fresh hall/docs must render before first regen),
+// but they are per-instance GENERATED, so a bump changes the served API while the
+// instance's committed spec/client lag until regenerated (the classification settled in
+// task 2141; init does the same at standup). We SPAWN the new core's generators (a fresh child
 // captures its output root from the env below) with <FALLBACK_PREFIX>_INSTANCE_ROOT set
 // so resolveDocsRoot() writes INTO the instance repo, not node_modules. docs first — the
 // client reads the spec it produces. Best-effort: a hiccup warns, never fails the bump
@@ -252,6 +295,64 @@ async function pollHealth(healthUrl, deps = {}) {
   }
 }
 
+// Auto-rollback (task 2149): a bump failed AFTER the pin was moved — an install or migrate
+// error, or a failed post-restart health check. Revert the code pin to the pre-upgrade
+// snapshot, reinstall the previous core, restart, re-verify health, and record the reversal
+// in the ledger. The DB is deliberately NOT rolled back: core migrations are additive +
+// forward-safe (the core migration rule), so any already-applied migration is left in place —
+// only the code PIN moves back. Best-effort + fail-soft: every sub-step logs but never throws,
+// so a rollback attempt can't itself crash the upgrader on top of the original failure.
+async function rollback({ instanceDir, snapshot, fromVersion, toVersion, opts }, reason, deps = {}) {
+  const log = deps.log || console.log;
+  const err = deps.err || console.error;
+  const run = deps.run || spawnSync;
+  const fsImpl = deps.fs || fs;
+  const restore = deps.restorePin || restorePin;
+
+  err(`  ↩ rolling back: ${reason} — reverting ${CORE_PKG} ${toVersion} → ${snapshot.prevVersion || snapshot.prevPin}`);
+  const result = { rolledBack: true, reason, restoredPin: snapshot.prevPin, restoredVersion: snapshot.prevVersion };
+
+  // 1. revert the pin to the exact previous dep string.
+  try { restore(instanceDir, snapshot.prevPin, fsImpl); result.restoreOk = true; log(`  ✓ restored pin → ${snapshot.prevPin}`); }
+  catch (e) { result.restoreOk = false; err(`  ! could not restore pin (${e.message}) — package.json may need manual repair`); }
+
+  // 2. reinstall the previous core.
+  const inst = npmInstall(instanceDir, run);
+  result.reinstallOk = !!inst.ok;
+  if (inst.ok) log('  ✓ reinstalled previous core');
+  else err(`  ! reinstall of previous core failed (${inst.reason || 'exit ' + inst.code}) — the instance may need manual repair`);
+
+  // 3. restart back onto the previous core.
+  const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run);
+  if (rs.skipped) log('  • restart: no --service/--restart-cmd — restart the instance service manually to load the reverted core.');
+  else if (!rs.ok) err(`  ! restart after rollback failed (exit ${rs.code}) — restart the service manually.`);
+  else log(`  ✓ restarted ${opts.service || 'service'} on the previous core`);
+  result.restartOk = rs.ok;
+
+  // 4. re-verify: installed == previous, optional health recovery.
+  const installedNow = readInstalledCoreVersion(instanceDir, fsImpl);
+  result.installedAfter = installedNow;
+  log(`  ${installedNow === snapshot.prevVersion ? '✓' : '!'} installed core after rollback: ${installedNow || '(unknown)'}`);
+  if (opts.healthUrl) {
+    const h = await pollHealth(opts.healthUrl, deps);
+    result.healthOk = h.ok;
+    if (h.ok) log(`  ✓ health recovered ${opts.healthUrl} → ${h.status}${h.attempts > 1 ? ` (after ${h.attempts} tries)` : ''}`);
+    else err(`  ! health STILL failing after rollback (${h.error || 'status ' + h.status}) — manual intervention needed`);
+  }
+
+  // 5. record the reversal in the ledger via the always-present `note` column (no schema
+  //    dependency — so it records even when a FAILED migrate means a newer column wouldn't exist).
+  const note = `rolled_back: ${reason} (attempted ${fromVersion || '(none)'} → ${toVersion}, restored ${snapshot.prevVersion || 'previous'})`;
+  const ledger = await recordLedger({ fromVersion, toVersion, sourceCommit: opts.sourceCommit, note }, deps);
+  if (ledger.ok) log('  ✓ recorded rollback in core_upgrades ledger');
+  else if (ledger.skipped) log(`  • rollback ledger skipped (${ledger.reason})`);
+  else err(`  ! rollback ledger insert failed (${ledger.reason}) — record it manually`);
+  result.ledger = ledger.ok;
+
+  err(`  ↩ rollback complete — instance restored to core ${snapshot.prevVersion || snapshot.prevPin}.`);
+  return result;
+}
+
 // ---- orchestration ----------------------------------------------------------
 
 async function runUpgrade(opts, deps = {}) {
@@ -264,9 +365,16 @@ async function runUpgrade(opts, deps = {}) {
   const instanceDir = path.resolve(opts.instance || process.cwd());
   const targetVersion = opts.to;
   const dryRun = !!opts.dryRun;
+  // Auto-rollback is ON by default (task 2149); `--no-rollback-on-failure` opts out (e.g. an
+  // interactive run that wants to inspect a broken state). Programmatic callers pass false.
+  const rollbackOnFailure = opts.rollbackOnFailure !== false;
+  // Pre-upgrade snapshot { prevPin, prevVersion } — captured the instant the pin is moved, so a
+  // failure AFTER that point (install / migrate / health) can revert. null until then = nothing to undo.
+  let snapshot = null;
   if (!targetVersion) return { ok: false, error: 'missing --to <version> (the target core version)' };
 
   const fromVersion = readInstalledCoreVersion(instanceDir, fsImpl) || readPinnedCoreVersion(instanceDir, fsImpl);
+  const doRollback = (reason) => rollback({ instanceDir, snapshot, fromVersion, toVersion: targetVersion, opts }, reason, deps);
   log(`bongos upgrade — ${CORE_PKG}: ${fromVersion || '(none)'} → ${targetVersion}`);
   log(`  instance: ${instanceDir}${dryRun ? '   [DRY RUN — no changes]' : ''}`);
   if (fromVersion === targetVersion && !opts.force) {
@@ -282,30 +390,56 @@ async function runUpgrade(opts, deps = {}) {
   log(`  ✓ pre-flight: ${mods.note}`);
   if (!mods.ok) return { ok: false, error: `module pre-check failed: ${mods.blocking.map((b) => b.key).join(', ')} incompatible with core ${targetVersion}` };
 
-  // 2. bump the pin (vendor the tarball + rewrite the file: dep).
-  let vendorRel = opts.pinPath || (opts.from ? null : path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`));
-  if (opts.from) {
-    if (!fsImpl.existsSync(opts.from)) return { ok: false, error: `--from tarball not found: ${opts.from}` };
-    if (dryRun) { log(`  [dry-run] would vendor ${opts.from} → vendor/${ARTIFACT}-${targetVersion}.tgz`); vendorRel = path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`); }
-    else vendorRel = vendorTarball({ instanceDir, fromTgz: path.resolve(opts.from), targetVersion }, fsImpl);
-  }
-  if (!fsImpl.existsSync(path.join(instanceDir, vendorRel)) && !dryRun) {
-    return { ok: false, error: `no core tarball at ${vendorRel} — pass --from <path-to-.tgz> to vendor it` };
+  // 2. bump the pin. Two mutually exclusive core sources (ADR 0134, task 2090):
+  //    REGISTRY (--registry): pin @bongos/core@<version> + ensure the env-fed .npmrc, so
+  //      the `npm install` below pulls the PRIVATE package from the registry (needs NPM_TOKEN).
+  //    VENDORED (default, --from <tgz>): copy the .tgz into vendor/ + rewrite the file: dep.
+  if (opts.registry) {
+    if (opts.from) return { ok: false, error: '--registry and --from are mutually exclusive (registry pull vs vendored tarball) — pick one core source' };
+    if (!hasNpmToken()) log('  ! no NPM_TOKEN in env — `npm install` will 404 on the PRIVATE @bongos/core until a read-only automation token is provided (ADR 0134).');
+    const prevPin = dryRun ? null : writeRegistryPin(instanceDir, targetVersion, fsImpl);
+    if (!dryRun) { writeNpmrc(instanceDir, { fsImpl, overwrite: false, log }); snapshot = { prevPin, prevVersion: fromVersion }; }
+    log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → ${targetVersion} (registry)${dryRun ? ' + write an env-fed .npmrc' : ''}${prevPin ? `  (was ${prevPin})` : ''}`);
+  } else {
+    let vendorRel = opts.pinPath || (opts.from ? null : path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`));
+    if (opts.from) {
+      if (!fsImpl.existsSync(opts.from)) return { ok: false, error: `--from tarball not found: ${opts.from}` };
+      if (dryRun) { log(`  [dry-run] would vendor ${opts.from} → vendor/${ARTIFACT}-${targetVersion}.tgz`); vendorRel = path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`); }
+      else vendorRel = vendorTarball({ instanceDir, fromTgz: path.resolve(opts.from), targetVersion }, fsImpl);
+    }
+    if (!fsImpl.existsSync(path.join(instanceDir, vendorRel)) && !dryRun) {
+      return { ok: false, error: `no core tarball at ${vendorRel} — pass --from <path-to-.tgz> to vendor it (or --registry to pull from the npm registry)` };
+    }
+    const prevPin = dryRun ? null : writePin(instanceDir, vendorRel, fsImpl);
+    if (!dryRun) snapshot = { prevPin, prevVersion: fromVersion };
+    log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → file:${vendorRel}${prevPin ? `  (was ${prevPin})` : ''}`);
   }
-  const prevPin = dryRun ? null : writePin(instanceDir, vendorRel, fsImpl);
-  log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → file:${vendorRel}${prevPin ? `  (was ${prevPin})` : ''}`);
 
   if (dryRun) { log('  [dry-run] would: npm install → npm run migrate → materialize .claude → regen API docs+client → restart → verify'); return { ok: true, dryRun: true, fromVersion, toVersion: targetVersion }; }
 
   // 3. npm install.
   const inst = npmInstall(instanceDir, run);
-  if (!inst.ok) return { ok: false, error: `npm install failed (${inst.reason || 'exit ' + inst.code})`, fromVersion };
+  if (!inst.ok) {
+    const error = `npm install failed (${inst.reason || 'exit ' + inst.code})`;
+    if (rollbackOnFailure && snapshot) {
+      const rb = await doRollback('npm install failed');
+      return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };
+    }
+    return { ok: false, error, fromVersion };
+  }
   log('  ✓ npm install');
 
   // 4. migrate (additive core_* migrations).
   if (!opts.skipMigrate) {
     const mig = runMigrate(instanceDir, run);
-    if (!mig.ok) return { ok: false, error: `migrate failed (${mig.reason || 'exit ' + mig.code})`, fromVersion };
+    if (!mig.ok) {
+      const error = `migrate failed (${mig.reason || 'exit ' + mig.code})`;
+      if (rollbackOnFailure && snapshot) {
+        const rb = await doRollback('migrate failed');
+        return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };
+      }
+      return { ok: false, error, fromVersion };
+    }
     log('  ✓ migrate');
   } else log('  • migrate skipped (--skip-migrate)');
 
@@ -345,6 +479,14 @@ async function runUpgrade(opts, deps = {}) {
     else err(`  ! health ${opts.healthUrl} not ready after ${h.attempts} tr${h.attempts === 1 ? 'y' : 'ies'}: ${h.error || 'status ' + h.status}`);
   }
 
+  // A failed post-restart health check means the new core is serving broken — auto-revert (task
+  // 2149) instead of recording an "upgraded" row + leaving the instance down. The rollback writes
+  // its OWN rolled_back ledger row, so skip the normal insert below.
+  if (healthOk === false && rollbackOnFailure && snapshot) {
+    const rb = await doRollback('health check failed after restart');
+    return { ok: false, error: `health check failed after restart — rolled back to ${snapshot.prevVersion || 'the previous core'}`, fromVersion, toVersion: targetVersion, versionOk, healthOk: false, rolledBack: true, rollback: rb };
+  }
+
   const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: opts.note }, deps);
   if (ledger.ok) log('  ✓ recorded in core_upgrades ledger');
   else if (ledger.skipped) log(`  • ledger skipped (${ledger.reason})`);
@@ -366,11 +508,13 @@ function parseArgs(argv) {
     sourceCommit: arg('--source-commit', argv),
     note: arg('--note', argv),
     pinPath: arg('--pin-path', argv),
+    registry: hasFlag('--registry', argv), // ADR 0134: pull @bongos/core@<--to> from the npm registry instead of vendoring
     dryRun: hasFlag('--dry-run', argv),
     force: hasFlag('--force', argv),
     skipMigrate: hasFlag('--skip-migrate', argv),
     skipMaterialize: hasFlag('--skip-materialize', argv),
     skipRegenDocs: hasFlag('--skip-regen-docs', argv),
+    rollbackOnFailure: !hasFlag('--no-rollback-on-failure', argv), // ADR 0100: auto-revert ON by default (task 2149)
   };
 }
 
@@ -385,6 +529,7 @@ async function main(argv = process.argv.slice(2)) {
       '',
       '  --to <version>       target core version — presence switches from pre-check to a real bump',
       '  --from <tgz>         source tarball to vendor into vendor/ (else it must already be there)',
+      '  --registry           pull @bongos/core@<--to> from the npm registry (env-fed .npmrc + NPM_TOKEN) instead of vendoring a tarball (ADR 0134); mutually exclusive with --from',
       '  --instance <dir>     consumer instance root (default: cwd)',
       '  --service <unit>     systemd unit to restart after applying',
       '  --restart-cmd <cmd>  explicit restart command (overrides --service)',
@@ -392,10 +537,12 @@ async function main(argv = process.argv.slice(2)) {
       '  --skip-migrate       do not run `npm run migrate`',
       '  --skip-materialize   do not refresh .claude/',
       '  --skip-regen-docs    do not regenerate the OpenAPI spec + typed client from the new core',
+      '  --no-rollback-on-failure  do NOT auto-revert on a failed install/migrate/health check (default: auto-rollback ON)',
       '  --dry-run            show the plan; change nothing',
       '  --force              skip the clean-tree + same-version guards',
       '',
       'Full bump: pre-flight → bump pin → npm install → migrate → materialize .claude → regen API docs+client → restart → verify.',
+      'On a failure after the pin moves (install/migrate/health), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
     ].join('\n') + '\n');
     return 0;
   }
@@ -410,8 +557,8 @@ async function main(argv = process.argv.slice(2)) {
 }
 
 module.exports = {
-  runUpgrade, parseArgs, main,
-  versionFromTgzPath, readInstalledCoreVersion, readPinnedCoreVersion, writePin,
+  runUpgrade, parseArgs, main, rollback,
+  versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
   vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, restartService, recordLedger, pollHealth,
   CORE_PKG, ARTIFACT,
 };

package/src/bongos/CLAUDE.md

@@ -1,64 +1,15 @@
-# src/bongos/ — GDS core (agent notes)
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> Nested CLAUDE.md — loads on demand when you work here. Root [CLAUDE.md](../../CLAUDE.md) is the index; this is the altitude map for this directory. See [ADR 0061](../../docs/adr/<redacted>.md) for why these exist.
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
 
-**Purpose.** `src/bongos/` is the Game Development System — the build-methodology backend (builders, tasks, claims, credits, grading, memory, dev boxes), mounted at `/api/gds` in the same Node process as the game. This is where **server-side enforcement lives**: rank/permission gates, the ship/grade pipeline, and credit accounting all run here, never on the client. The DB is the source of truth; this code is its only authoritative writer.
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
 
-**Key files / public surface.**
-- `db.js` — the **RESIDUE** after the lifecycle carve (BV1.R86): builder IDENTITY + admission, RANK/status management (`setBuilderRank`/`_applyRankChangeTx`), AUTH `builder_sessions`, the social TWINS (Discord link, karma feed, `listAuditLog`, the grade-trend `builderRollingAvgGrade`), the `security_docs` store, and the Gemini-key leak. **The build state machine (tasks·claims·versions·done-when·ship) graduated to [`modules/lifecycle/db.js`](../../modules/lifecycle/CLAUDE.md)** — so the residue here is exactly the kernel identity/auth/twin slice + `db-kernel.js` (ADR 0093 §3). (The **credits/costs** slice graduated to economy; the **session_records** slice graduated to sessions.) Don't read end-to-end — `grep` for the helper name. `withTx(fn)` wraps BEGIN/COMMIT. `sealSessionLog` + `_applyRankChangeTx`(+`RANKS`/`singleRungPromotionError`) + the `gradePassCount` fragment are deliberately TWINNED with `modules/lifecycle/db.js` (ADR 0091 §2 — keep in sync).
-- **Lifecycle graduated out** → [`modules/lifecycle/`](../../modules/lifecycle/CLAUDE.md) (the build state machine — tasks · claims · versions · done-when · goals · dependencies · the claim→ship→grade→credit lifecycle · github-push + merge-lock + conflict-resolve + publish-reconciler + ship-card/preflight + version-close; the LAST + most-coupled domain, BV1.R86). Core reaches it only through the `lifecycle` kernel **port** the module registers — `routes/{public,me,builders}.js` + `cascade-dispatch.js` resolve `seams.resolveOptional('lifecycle')` for the version/ship feed, per-builder claims/grades, the Archon roster, and the task-kind classifier; the moved routes (`routes/{tasks,claims,versions,done-when,goals,dependencies,gate-approvals,analytics}.js`) mount via the loader. It **retired the last three doorway leaks** (`createTask`/`VOTABLE_TASK_STATUSES`/`tallyPeerVotes` → behind the port). As a transaction-participant it RESOLVES the `reward`+`onboarding` ports inside its claim/ship/confirm txns ([ADR 0093](../../docs/adr/<redacted>.md) §1,§3).
-- **Grading graduated out** → [`modules/grading/`](../../modules/grading/CLAUDE.md) (the quality gate: v4 adversarial worker panel Narc/Quality/Hacker/Efficiency + deterministic pre-passes + the rubric; BV1.R73). Core reaches it only through the `grade` kernel **port** — the lifecycle module's `routes/tasks.js` + core `routes/public.js` resolve `seams.resolveOptional('grade')`, never a direct require ([ADR 0091](../../docs/adr/<redacted>.md) §4, [ADR 0024](../../docs/adr/<redacted>.md)). `cascade-dispatch.js` (dormant System 3) stayed core.
-- **Economy graduated out** → [`modules/economy/`](../../modules/economy/CLAUDE.md) (credit allocation + the cost-plus/kind-multiplier model, the cost ledger + dashboard rollups, streaks, achievements, the leaderboard; BV1.R77). Core reaches it only through the `reward` kernel **port** — a **transaction-participant** port: the lifecycle (`applyGrade`/`confirmTask`/`decideOverrideRequest`/`claimTask`/`upsertSessionRecordWithReward`) keeps its state-machine SQL and the `credit_log`/`cost_log` *guards*, but resolves `seams.resolveOptional('reward')` and passes its own tx `client` for every credit/achievement WRITE; the read routes (`me.js`/`public.js`/`builders.js`/`sessions.js`) + `publish-reconciler.js` resolve the same port ([ADR 0093](../../docs/adr/<redacted>.md) §1-2). `llm-pricing.js` stays core shared LLM-cost infra (doorway leak `api.llmPricing`, like `llm-cache.js`).
-- **Ideas graduated out** → [`modules/ideas/`](../../modules/ideas/CLAUDE.md) (the `idea_inbox` capture/triage/criterion-proposal flow + the `blockers` queue; BV1.R78). The discord `#ideas` inbound reaches it only through the `ideas.capture` kernel **port** the module registers — which **retired** the `captureIdea` doorway leak ([ADR 0093](../../docs/adr/<redacted>.md) §5). `routes/public.js` keeps its **own** inline `idea_inbox`/`blockers` SELECTs (core querying a shared table with its own SQL is fine — no import, no twin).
-- **Security FEATURE graduated out** → [`modules/security/`](../../modules/security/CLAUDE.md) (red-team / vulnerability **reports** + the **bounty** payout table, rank-gated Metic+; `security.js` + `routes/reports.js`; BV1.R79). Core reaches the bounty schedule only through the `security` kernel **port** the module registers — `routes/public.js`'s `/public/bounty-table` resolves `seams.resolveOptional('security').bountyTableDetailed()`, never a direct require ([ADR 0093](../../docs/adr/<redacted>.md) §1; [02-module-map §5](../../docs/design/modular-architecture/02-module-map.md)). **<redacted> stays kernel:** `permission-path-check.js`/`route-rank-check.js` (authz) AND `routes/security.js` (the `/security/adr` threat-model reader + the Archon-only `/security/docs` exploit-detail store, backed by core `db.js` `security_docs` queries) all stayed in core.
-- **Builder-settings graduated out** → [`modules/builder-settings/`](../../modules/builder-settings/CLAUDE.md) (the per-builder PREFS domain — wandering · skill · sound · render — + builder-needs + their `db.js` slice; the five `/me/*-prefs` routes; BV1.R80). The `GET /me` aggregator (`routes/me.js`) + `cascade-dispatch.js` reach it only through the `builder-settings` kernel **port** the module registers (`seams.resolveOptional('builder-settings')` for the wandering/render/needs profile slices + the skill ceiling), never a direct require ([ADR 0093](../../docs/adr/<redacted>.md) §1). The five `skill_model_prefs`/`sound_prefs`/`behavior_prefs`/`event_sound_prefs` getter/setter pairs left `db.js`; the `builders` table + the Gemini-key columns (art-pipeline credential infra) stay core.
-- `auth.js` — GitHub Device Flow (CLI) + web OAuth → `builder_sessions`. Exports the request guards: `requireBuilder`, `requireRank`, `allowBoxScope` (box tokens are deny-by-default, [ADR 0053](../../docs/adr/0053-scoped-dev-box-session.md)), plus Discord OAuth helpers.
-- `github-push.js` — server-mediated branch publish ([ADR 0055](../../docs/adr/<redacted>.md)): box uploads a git bundle, server pushes + opens PR + auto-merges via a short-lived **GitHub App** installation token (no standing PAT). Also `mergeIfGreen`, gate commit-status helpers.
-- `routes.js` + `routes/` — **thin mounter**: each feature is a sub-router in `routes/`; adding a feature = one new file + one `.use()` line. Audit + rate-limit middleware mount first. See `routes/`'s own nested CLAUDE.md.
-- `permission-path-check.js` / `route-rank-check.js` — the pure protected-path + route-rank matchers (SEC [#863](https://example.com/builders#/task/863) / [ADR 0043](../../docs/adr/<redacted>.md)), reused by the grading module (via the doorway — `api.routeRankCheck`/`api.permissionPathCheck`), pre-push hook, and `--fit` runner.
-- **Onboarding graduated out** → [`modules/onboarding/`](../../modules/onboarding/CLAUDE.md) (admission · the server-ticked newcomer onboarding state machine · the friction analyzer · the evergreen newcomer-chore restock; `onboarding-state.js` + `onboarding.js` + `newcomer-restock.js` + `routes/access-requests.js` + `approval-broadcast.js` + its `db.js` slice; BV1.R81). The novel shape: it is the FIRST core→module port the LIFECYCLE drives — core reaches the state machine + restock only through the `onboarding` kernel **port** the module registers (`seams.resolveOptional('onboarding')` in `db.js` claim/ship, `auth.js`, `routes/me.js`/`builders.js`/`tasks.js`/`claims.js`), never a direct require ([ADR 0093](../../docs/adr/<redacted>.md) §1). The admission GATE READS (`hasInvitedAccessRequest`/`getBuilderByGithubId`) stay core `db.js` (kernel identity/admission).
-- **Sessions/BFG graduated out** → [`modules/sessions/`](../../modules/sessions/CLAUDE.md) (the `session_records` corpus + its `/sessions` data plane, the BFG cross-builder scorer, the session-pulse/stale-claim helpers; `bfg.js` + `pulse.js` + `routes/sessions.js` + its `db.js` slice; BV1.R82). Like `memory`, it registers **NO port** — core never calls back in: the ship-time session-digest write is an **HTTP POST** to the module's own `/sessions` route. Its one outward edge is the economy `reward` port it *resolves* (`seams.resolveOptional('reward')` in `db.js` `upsertSessionRecordWithReward` + `routes/sessions.js`) for the cost-plus token reward + `sumCreditsForTasks` ([ADR 0093](../../docs/adr/<redacted>.md) §1). **Stays core:** `session_logs` (the per-claim ship LOG, `sealSessionLog` — lifecycle) and `builder_sessions` (auth tokens) are NOT this domain.
-- **Autonomy/MAS graduated out** → [`modules/autonomy/`](../../modules/autonomy/CLAUDE.md) (the Multi-Agent System — the autonomy gate, the conductor/architect/run-routine CLIs, and the in-process routine timers; `routes/autonomy.js` + `pollers/routine-timers.js` + the `autonomy_runs` `db.js` slice; BV1.R83). Like `sessions`/`memory`, it registers **NO port** — core never calls back in. The cross-cutting bit: the **routine timer** (was `routineTimers.start()` in `server.js`) is now a loader-started **poller** (`contributes.pollers`), and the **precheck route** (was mounted in `routes.js`) a module route; both severed their `src/`/`server.js` import. The timer's one outward edge is the lifecycle **`tallyPeerVotes`** capability it resolves through the **doorway** (`api.tallyPeerVotes` — the SAME tx `POST /tasks/peer-votes/tally` runs; a tracked lifecycle leak until R86), never a core require ([ADR 0093](../../docs/adr/<redacted>.md) §1). **Stays core:** `tallyPeerVotes` itself (lifecycle — writes `karma_log`/`peer_votes`/`tasks`); the MAS-domain CLIs travel with the domain but stay under `scripts/gds/`.
-- `boxes.js` · `box-access.js` · `do-api.js` · `cf-tunnel.js` — per-builder cloud dev-box lifecycle, rank-gated source clawback, DigitalOcean client, and the Cloudflare named-tunnel control plane ([ADR 0031](../../docs/adr/<redacted>.md)).
-- **Discord graduated out** → [`modules/discord/`](../../modules/discord/CLAUDE.md) (bot, broadcast, role-sync, channels, bug-attachments, link/role; BV1.R47). Core reaches it only through the doorway seams — ports `discord.isLinked`/`discord.guildJoinSpec`, events `task.shipped`/`builder.role-sync-needed` — never a direct require. Discord is a mirror only, never authority ([ADR 0033](../../docs/adr/<redacted>.md)).
-- `llm-pricing.js` · `task-classifier.js` · `search-chunker.js` · `search.js` · `publish-reconciler.js` · `conflict-resolve.js` — token→USD pricing (cost-plus reward), `tasks.kind` heuristic, retrieval-layer chunker + search ([ADR 0060](../../docs/adr/0060-gds-retrieval-layer.md)), the confirmed→shipped auto-heal sweep, and (`conflict-resolve.js`, [ADR 0082](../../docs/adr/<redacted>.md)) the SERVER-side generated-file/append-index merge-conflict resolver the reconciler calls on `merge_conflict` (temp-clone merge with the `otb-regen` driver + `union`, then push; never bypasses a check).
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
 
-**Gotchas / invariants.**
-- **Permissions enforced server-side, per-request, no cache** ([ADR 0016](../../docs/adr/<redacted>.md)) — `requireRank`/`requireBuilder` read live `builders.rank`; editing local files grants nothing.
-- `db.js` is huge — **skim by section/grep, never read whole** (see efficiency note above). (`grader.js` graduated to `modules/grading/` — BV1.R73.)
-- Protected-path + route-rank logic is defined **once** in `permission-path-check.js` / `route-rank-check.js`; reuse the matcher, don't re-implement.
-- `routes.js` is deliberately conflict-free — feature logic goes in a `routes/` sub-router, not here.
-- `preview-server.js` is **not** here — it lives at `../preview-server.js` (game-only sandbox).
-
-<!-- BEGIN GENERATED REPO-MAP (scripts/gds/gen-repo-map.js — do not hand-edit) -->
-**Symbol skeleton (generated from the code — do not hand-edit; refresh: `node scripts/gds/gen-repo-map.js`).** Exported signatures, most-referenced first. The interpretive notes above are hand-written; this factual list is regenerated on deploy so it can't drift ([ADR 0063](../../docs/adr/<redacted>.md)).
-
-- `api-errors.js` — `envelope(codeOrError, message, details)`, `classify(code)`, `class ApiError`, `CATEGORIES`, `OVERRIDES`, `isApiError(x)`, `DEFAULT_CATEGORY`, `statusForCode(code, override)`, `categoryForCode(code)`, `isRetriable(code)`
-- `api-path-404.js` — `apiNotFoundBody(p)`, `isApiShapedPath(p)`, `apiPathHint(p)`, `GDS_ROOTS`
-- `api-prefix.js` — `API_PREFIX`, `API_VERSION`, `LEGACY_API_PREFIXES`, `VERSIONED_API_PREFIX`, `ALL_API_PREFIXES`
-- `app-pair.js` — `pairStore`, `createPairStore(opts = {})`, `normalizeCode(raw)`
-- `auth.js` — `requireBuilder(req, res, next)`, `requireRank(...allowed)`, `allowBoxScope(req, _res, next)`, `authConfigured()`, `requireBfgPrincipal(req, res, next)`, `loadDiscordBotToken()`, `requireArchonPage(req, res, next)`, `isValidDiscordUserId(id)`, `requireBuilderPage(req, res, next)`, `completeWebFlow({ code, redirectUri, userAgent })` _(+20 more)_
-- `cascade-dispatch.js` — `dispatch({ prompt, taskKind, title, description, discipline, ceiling = 'opus', expectSchema = null,…)`, `LADDER`, `startRungForTask({ taskKind, title, description } = {})`, `startRungForKind(taskKind)`, `ceilingForBuilder(builderPrefs, skillName)`, `MAX_ESCALATIONS`, `rungIndex(model)`, `shouldEscalate(result, expectSchema)`
-- `db-kernel.js` — `getBuilderById(id)`, `insertAuditLog({)`, `withTx(fn, { pool: p = pool } = {})`, `RANKS`, `LIVE_RANK_LADDER`, `createSession({ builderId, token, source, userAgent, expiresAt })`, `lookupSession(token)`, `upsertBuilder({ githubId, githubLogin, displayName, avatarUrl })`, `getBuilderByGithubId(githubId)`, `hasInvitedAccessRequest(login)` _(+3 more)_
-- `db.js` — `setBuilderRank({ builderId, newRank, actorBuilderId })`, `getDiscordLink(builderId)`, `hasCliSession(builderId)`, `recordApplause({ targetTaskId, discordUserId })`, `singleRungPromotionError(oldRank, newRank)`, `deactivateBuilder({ builderId, reason, actorBuilderId })`, `<redacted>(builderId)`, `listAuditLog({ limit = 100, offset = 0, builderId, method, surface } = {})`, `revokeAllSessionsForBuilder(builderId)`, `unlinkDiscord(builderId)` _(+11 more)_
-- `goal-scope-check.js` — `check(goalScopeModules, touches, builderRank)`, `isCovered(touch, goalGlobs)`, `protectedPathBlock(touches, builderRank)`, `scopeSubset(goalScopeModules, touches)`
-- `hierarchy-config.js` — `tier`, `hierarchy()`, `tiers`, `INSTANCE_PATH`, `DEFAULT_HIERARCHY`, `ROLE_KEYS`, `_resetForTests()`, `STANDARD_KEYS`, `loadHierarchy({ instancePath, env = process.env } = {})`, `membershipTier` _(+9 more)_
-- `live-channel.js` — `subscribe(fn)`, `CHANNEL`, `_state()`
-- `llm-cache.js` — `store(spec, { resultStdout, resultCostUsd = 0 } = {})`, `normalize(taskType, prompt)`, `makeCacheSpec({ prompt, model, task_type, scope_sha, owner_builder_id = null, ttl_ms = null } = {})`, `NORMALIZERS`, `poolReachable()`, `withCache(spec, producer)`, `computeCacheKey({ prompt, model, task_type, scope_sha } = {})`, `recordSaving(spec, { resultCostUsd = 0, hitCount = 0 } = {})`, `scopeShaFor(paths, { runner, cwd } = {})`, `stripVolatile(text)` _(+2 more)_
-- `llm-pricing.js` — `priceUsage(model, usage)`, `PRICES`, `priceModelUsage(modelUsage)`, `componentsFromModelUsage(modelUsage)`, `familyFor(model)`, `canonicalizeModelId(model)`
-- `metrics.js` — `render(p = pool)`, `HIST_BUCKETS`, `authorizeScrape(req)`, `httpMiddleware()`, `incCounter(name, help, labels = {}, by = 1)`, `collectDbGauges(p = pool)`, `metricsHandler()`, `normalizeRoute(p)`, `observeHistogram(name, help, labels, value)`, `__resetForTests()`
-- `module-scope-map.js` — `MODULE_SCOPE_MAP`, `moduleKeys()`, `scopeIncludesProtected(keys)`, `isModuleKey(key)`, `isProtected(globs)`, `MODULE_GLOBS`, `globsForModules(keys)`, `scopeForModule(key)`, `isProtectedModule(key)`, `protectedModules()`
-- `optimizer.js` — `VALID_MODES`, `DEFAULT_MAX_PARALLEL`, `optimizeSession({ builderId, mode, timeBudgetMin, maxParallel })`
-- `path-match.js` — `touchesOverlap(a, b)`, `matchOne(file, touches)`
-- `permission-path-check.js` — `PROTECTED_GLOBS`, `SPECIALTY`, `matchProtected(files)`, `checkPermissionPaths({ changedFiles, builderRank } = {})`, `globToRegExp(glob)`, `RANK_TIER`, `tierOf(rank)`, `toWorkerResult(result)`, `MIN_TIER`, `isBelowFloor(rank)`
-- `pool.js` — `instanceDbName()`
-- `repo-info.js` — `loadRepoInfo()`, `parseRemote(remote)`, `_resetCacheForTests()`
-- `route-rank-check.js` — `EXPECTED_RANKS`, `SPECIALTY`, `MODULES_DIR`, `MODULE_EXPECTED_RANKS`, `checkRouteRanks({ routesDir = ROUTES_DIR, modulesDir } = {})`, `toWorkerResult(result)`, `KNOWN_RANKS`, `WRITE_METHODS`, `classifyRank(lines, i)`, `classifyText(text)` _(+2 more)_
-- `routes.js` — `buildGdsRouter()`
-- `secret-box.js` — `VERSION`, `isConfigured()`, `decrypt(blob)`, `encrypt(plaintext)`, `provisionMasterKey(opts = {})`, `masterKeyFile()`
-- `sensitive-surfaces.js` — `isSensitive(file)`, `SENSITIVE_SURFACES`
-- `serve-internal.js` — `isBuildersHost(req)`, `mountInternalSurfaces(app)`, `isStatusHost(req)`, `injectBrandingGlobal(html, brand = clientBranding()`, `applyBrandTokens(html, brand = clientBranding()`, `injectBrandingInto(stamped, brand = clientBranding()`, `injectModuleHallWidgets(html, scripts = hallWidgetScripts({ isEnabled: isModuleEnabled })`, `themeMarkup(theme)`
-- `uptime-poller.js` — `start()`
-<!-- END GENERATED REPO-MAP -->
-
-**See also.** [ADR 0010](../../docs/adr/0010-pms-architecture.md) (GDS architecture) · [ADR 0016](../../docs/adr/<redacted>.md) (trust boundary) · [docs/architecture.md](../../docs/architecture.md) · `routes/CLAUDE.md` (HTTP surface).
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/src/bongos/auth.js

@@ -224,6 +224,30 @@ async function startDeviceFlow() {
     throw new Error(`device/code failed (${res.status}): ${text}`);
   }
   const data = await res.json();
+  // GitHub returns HTTP 200 with an { error, error_description } body for OAuth-App
+  // misconfig — most often device_flow_disabled (Device Flow not enabled on the App)
+  // or incorrect_client_credentials. res.ok is TRUE there, so without this the missing
+  // device_code silently produced a broken flow / an opaque 500 (the 2026-07-08 demo
+  // login failure). Mirror the token-exchange guard (data.error, above); task 2126.
+  if (data.error) {
+    // device_flow_disabled is self-inflicted + common: GitHub defaults Device Flow OFF on new
+    // Apps and the one-click manifest can't enable it (task 2129). Make the CLI error self-
+    // service by naming the right settings surface. We hold only client_id here (not the app
+    // slug — that lives on the control plane), so we can't build /settings/apps/<slug>; but the
+    // id PREFIX distinguishes a GitHub App (Iv*) from an OAuth App (Ov*), which picks the right
+    // listing to open.
+    let hint = '';
+    if (data.error === 'device_flow_disabled') {
+      const where = /^Iv/i.test(creds.client_id || '')
+        ? 'https://github.com/settings/apps (org-owned apps: https://github.com/organizations/<org>/settings/apps)'
+        : 'https://github.com/settings/developers';
+      hint = ` — terminal sign-in needs Device Flow enabled on the app: open ${where}, open your app, check "Enable Device Flow", and save. Web sign-in is unaffected.`;
+    }
+    throw new Error(`GitHub rejected device-flow start: ${data.error}${data.error_description ? ` — ${data.error_description}` : ''}${hint}`);
+  }
+  if (!data.device_code) {
+    throw new Error('GitHub device/code returned no device_code (unexpected response shape).');
+  }
   // data: { device_code, user_code, verification_uri, expires_in, interval }
   deviceFlows.set(data.device_code, {
     interval: data.interval || 5,

package/src/bongos/module-submissions.js

@@ -0,0 +1,56 @@
+// src/bongos/module-submissions.js — the ADR 0107 §1 upstreaming review queue
+// (task 1770, migration core_191). A rank-gated (metic+archon) queue a builder
+// files a packaged module into (manifest + attribution + file snapshot + DCO
+// sign-off) before it can be reviewed/accepted upstream. See
+// docs/adr/0135-module-upstream-submission-interim-queue.md for why this queue
+// lives in THIS instance's own DB rather than a live cross-repo call.
+//
+// Pure DB access — the packaging (pre-check, file read, sign-off) is
+// scripts/gds/module.js's job (build tooling, fs-only); the route wires the
+// two together.
+
+const { pool } = require('./pool');
+
+async function createModuleSubmission({
+  moduleKey, submittedBy, manifest, files, signOff, precheckPassedAt, sourceRepo,
+}) {
+  const { rows } = await pool.query(
+    `INSERT INTO module_submissions
+       (module_key, submitted_by, manifest, files, sign_off, precheck_passed_at, source_repo)
+     VALUES ($1, $2, $3::jsonb, $4::jsonb, $5::jsonb, $6, $7)
+     RETURNING id, module_key, submitted_by, manifest, sign_off, precheck_passed_at,
+               source_repo, status, reviewed_by, reviewed_at, review_notes, submitted_at`,
+    [
+      moduleKey,
+      submittedBy,
+      JSON.stringify(manifest),
+      JSON.stringify(files),
+      JSON.stringify(signOff),
+      precheckPassedAt,
+      sourceRepo || null,
+    ]
+  );
+  return rows[0];
+}
+
+// Metadata-only list (no files jsonb — the file snapshot can run to hundreds of
+// KB per submission, and no list consumer needs it; a future GET .../:id can add
+// a with-files fetch if task 1771's review UI needs the code inline).
+async function listModuleSubmissions({ status, moduleKey } = {}) {
+  const clauses = [];
+  const params = [];
+  if (status) { params.push(status); clauses.push(`status = $${params.length}`); }
+  if (moduleKey) { params.push(moduleKey); clauses.push(`module_key = $${params.length}`); }
+  const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+  const { rows } = await pool.query(
+    `SELECT id, module_key, submitted_by, manifest, sign_off, precheck_passed_at,
+            source_repo, status, reviewed_by, reviewed_at, review_notes, submitted_at
+       FROM module_submissions
+       ${where}
+      ORDER BY submitted_at DESC`,
+    params
+  );
+  return rows;
+}
+
+module.exports = { createModuleSubmission, listModuleSubmissions };

package/src/bongos/route-rank-check.js

@@ -177,6 +177,12 @@ const MODULE_EXPECTED_RANKS = {
     'POST /goals/:id/requests/:reqId/respond': 'any-builder',
     'POST /goals/:id/invitations': 'any-builder',
     'POST /goals/:id/invitations/:reqId/respond': 'any-builder',
+    // the goal's own pending-queue view + requester self-withdraw (task 1953) —
+    // same in-handler walls: GET /requests is owner|manager|Archon
+    // (authorizeGoalManagement); withdraw is the requester only
+    // (authorizeWithdrawJoinRequest).
+    'GET /goals/:id/requests': 'any-builder',
+    'POST /goals/:id/requests/:reqId/withdraw': 'any-builder',
     // criterion confirmation + goal auto-achieve (ADR 0086 §6) — the planner's close loop.
     'POST /done-when/:criterionId/satisfy': 'metic+archon',
     // runtime criterion create (ADR 0105 gap fix, task 1874) — scope-truth write, Archon-only.

package/src/bongos/routes/CLAUDE.md

@@ -1,43 +1,15 @@
-# src/bongos/routes/ — GDS HTTP surface (agent notes)
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> Nested CLAUDE.md — loads on demand when you work here. Root [CLAUDE.md](../../../CLAUDE.md) is the index. See [ADR 0061](../../../docs/adr/<redacted>.md) for why these exist.
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
 
-**Purpose.** Express route handlers for the GDS API, all mounted under `/api/gds/*` in the same Node process as the game server. One file per resource group; each exports a `buildXRouter()` factory that returns its own `express.Router()`. The thin mounter is [`../routes.js`](../routes.js) — adding a feature = new file here + one `router.use(buildXRouter())` line there (kept conflict-free across parallel branches). `routes.js` also wires the global 64 KB JSON parser (skipped for `/memory/sync`, `/sessions`, `/tasks/:id/publish-branch` — they mount their own larger parser), the audit-log finish hook, and the rate limiter — all BEFORE the feature routers.
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
 
-**Conventions (read before adding a route).**
-- Auth/rank: middleware from [`../auth.js`](../auth.js) — `auth.requireBuilder` (valid session) then `auth.requireRank('metic','archon')` / `auth.requireRank('archon')`. **The server enforces rank per-request, no caching** ([ADR 0016](../../../docs/adr/<redacted>.md)). A `// rank:` comment sits above most handlers — it feeds the **generated** OpenAPI spec + [`docs/api-reference.md`](../../../docs/api-reference.md) (via `scripts/gds/gen-api-docs.js`; do NOT hand-maintain a mirror — it regenerates on ship, task 1918/[ADR 0109](../../../docs/adr/<redacted>.md)). `auth.allowBoxScope` opens a route to the deny-by-default box token (box.js bootstrap only).
-- Public surface: `public.js` + `analytics.js` are unauthenticated read-only (status page reads cross-origin) — wrap with `corsPublicGet(scope)` from `_helpers.js`; no secrets.
-- Validation: [`_helpers.js`](./_helpers.js) — `validateOrRespond(req,res,schema)` (opt-in, never rejects extras, structured 400), `LIMITS` (TITLE/DESCRIPTION/NOTES caps), `parseId`, `asyncHandler(tag, fn)`.
-- GitHub-rendered output only: the PR title/body built in `tasks.js` de-hashes bare `#NNN` (so it doesn't 404-autolink to GitHub issues) via the local `deHashRefs` helper — which mirrors ship.js's `sanitizeGitHubRefs` (not requirable here). Mirror `deHashRefs`; don't hand-roll. DB-row prose (tasks/inbox/memory) is stored as-is — sanitization happens only at the GitHub boundary.
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
 
-**Route groups.**
-- Work-tracking: `tasks.js`, `claims.js`, `versions.js`, `done-when.js` — the task lifecycle, claims, versions, done-when criteria.
-- Auth/identity: `auth.js`, `me.js`, `sessions.js` — Device/web/app-pair flows, self profile/prefs, session digests. (Admission gating — `access-requests.js` — carved to [`modules/onboarding/`](../../../modules/onboarding/CLAUDE.md) at R81; the loader mounts it.)
-- Builder ops: `builders.js`, `cost.js`, `leaderboard.js`, `memory.js`, `learnings.js` — builder records/budget, cost log, rankings, BFG-scoped memory, learnings.
-- Dev-box: `box.js` — provision/wake/close, SSH keys, terminal/sandbox tunnels, server-mediated branch publish.
-- Social/data: `discord.js`, `inbox.js`, `blockers.js`, `analytics.js`, `audit-log.js` — idea inbox, blockers, Discord link, analytics, Archon audit trail.
-- GDS-V4 / security: `search.js` (recall), `gate-approvals.js` (Archon gate PRs), `security.js` (red-team reports + Archon-served docs).
-- Util: `healthz.js`, `public.js`, `optimizer.js`, `bug-attachments.js`.
-
-**Gotchas / invariants.**
-- `tasks.js` (~79 KB), `box.js`, `auth.js`, `memory.js` are large — grep `router.(get|post|...)(` for the route, don't read end-to-end.
-- Rank gates are load-bearing (trust boundary). Default a write to `requireRank('archon')` unless it's deliberately broader; never loosen one without the permissions doc + an ADR.
-- Mount order: `public.js` is mounted LAST in routes.js; keep new files' prefixes from shadowing it.
-
-<!-- BEGIN GENERATED REPO-MAP (scripts/gds/gen-repo-map.js — do not hand-edit) -->
-**Symbol skeleton (generated from the code — do not hand-edit; refresh: `node scripts/gds/gen-repo-map.js`).** Exported signatures, most-referenced first. The interpretive notes above are hand-written; this factual list is regenerated on deploy so it can't drift ([ADR 0063](../../../docs/adr/<redacted>.md)).
-
-- `_helpers.js` — `validateOrRespond(req, res, schema, opts = {})`, `parseId(req, res, { param = 'id', code = 'bad_id', positiveInt = false } = {})`, `LIMITS`, `validate(body, schema, { strict = false, query = false } = {})`, `asyncHandler(tag, handler, { message = true, errorCode = 'server_error' } = {})`, `publicOrigin(req)`, `pageMeta(limit, offset, total)`, `parsePagination(req, { defaultLimit = PAGINATION.DEFAULT_LIMIT, maxLimit = PAGINATION.MAX_LIMIT } = {})`, `corsPublicGet(scope)`, `parseCookie(req, name)` _(+2 more)_
-- `auth.js` — `renderAuthErrorPage(heading, detail, opts = {})`, `sessionCookieDomainOpts(req)`, `safeReturnTo(raw)`, `reqHost(req)`
-- `backup.js` — `latestDump()`
-- `builders.js` — `boxHasEverConnected(builderId)`, `discordIsLinked(builderId)`, `displayRank(rank)`, `<redacted>({ displayName, direction, newRank })`, `fireDiscordBroadcast(text)`
-- `instance.js` — `MANIFEST_SCHEMA`, `buildInstanceManifest({)`, `AUTH_METHODS`
-- `live.js` — `buildLiveRouter()`, `frameEvent(event, data)`, `MAX_CONN_PER_IP`, `streamLive(req, res, deps = {})`
-- `llm-cache.js` — `badKey(res)`, `knownTaskType(t)`, `clampedCost(raw)`
-- `me.js` — `boxHasEverConnected(builderId)`, `artSharedKeyConfigured()`, `discordIsLinked(builderId)`
-- `modules.js` — `listModules()`
-- `public.js` — `projectPublicTask(task)`, `projectPublicBlocker(blocker)`, `projectPublicIdea(idea)`, `recentShippedWindow(rawDays)`
-- `security.js` — `adrPath()`, `readFullAdr()`
-<!-- END GENERATED REPO-MAP -->
-
-**See also.** [ADR 0016](../../../docs/adr/<redacted>.md) (trust boundary), [`docs/api-reference.md`](../../../docs/api-reference.md) (generated per-endpoint reference; `/docs` renders it), [`docs/canonical-permissions.md`](../../../docs/canonical-permissions.md) (rank ladder), [`../routes.js`](../routes.js) (mounter), [`../auth.js`](../auth.js).
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/src/bongos/routes/auth.js

@@ -209,7 +209,12 @@ module.exports = function buildAuthRouter() {
       res.json(out);
     } catch (err) {
       console.error('[gds] device/start', err);
-      res.fail('device_start_failed', { status: 500, message: 'internal error' });
+      // Surface the underlying reason (task 2126). A thrown device-flow start is almost
+      // always a GitHub OAuth-App misconfig (device_flow_disabled / bad client) — safe,
+      // non-secret, and actionable — so return it instead of an opaque "internal error".
+      // 502: the failure is upstream (GitHub), not a bug in this server.
+      const reason = String(err && err.message ? err.message : 'internal error').slice(0, 300);
+      res.fail('device_start_failed', { status: 502, message: reason });
     }
   });