@bongos/core 1.17.0 → 1.17.1

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,20 @@ 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;
+}
+
 // ---- steps (each injectable for tests) --------------------------------------
 
 function gitTreeClean(instanceDir, run = spawnSync) {
@@ -282,18 +309,29 @@ 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 });
+    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);
+    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 }; }
 
@@ -366,6 +404,7 @@ 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),
@@ -385,6 +424,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)',
@@ -411,7 +451,7 @@ async function main(argv = process.argv.slice(2)) {
 
 module.exports = {
   runUpgrade, parseArgs, main,
-  versionFromTgzPath, readInstalledCoreVersion, readPinnedCoreVersion, writePin,
+  versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin,
   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,17 @@ 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) {
+    throw new Error(`GitHub rejected device-flow start: ${data.error}${data.error_description ? ` — ${data.error_description}` : ''}`);
+  }
+  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 });
     }
   });
 

package/src/bongos/routes/modules.js

@@ -1,5 +1,5 @@
 // src/gds/routes/modules.js — the hall "Modules" tab backend (ADR 0107 §9,
-// task 1776). Three jobs, matching the ADR:
+// task 1776). Four jobs, matching the ADR:
 //
 //   GET  /modules              list every on-disk module: enabled state,
 //                               attribution (author/origin/license/maintainer),
@@ -9,37 +9,72 @@
 //                               and reload the live process (§6: default-off
 //                               respected — this only ever flips an existing
 //                               module's flag, never invents a new key).
-//   POST /modules/:key/submit  the "submit for review" front door (§1). The
-//                               submit pipeline (task 1770) hasn't landed yet,
-//                               so this is a clear 501 stub, not a fake queue —
-//                               the button lights up for real once 1770 ships.
+//   POST /modules/:key/submit  the "submit for review" front door (§1) — files
+//                               a packaged submission into the upstreaming
+//                               review queue (task 1770). Re-runs the §4
+//                               pre-check + requires a DCO sign-off against
+//                               THIS box's own on-disk copy of the module (the
+//                               authoritative check — `bongos module submit`
+//                               is a thin CLI client of this same route).
+//   GET  /modules/submissions  list queued submissions (task 1771 reads this).
 //
 // Read is open to any signed-in builder (same gate as the atlas/primer pages);
-// the write (enable/disable) is metic+archon, same rank as /backup/trigger —
-// it changes running behavior for the whole instance, not just the caller.
+// every write (enable/disable, submit) is metic+archon, same rank as
+// /backup/trigger — it changes running behavior for the whole instance (or
+// files something into a shared review queue), not just the caller.
 //
-// Persistence note: this writes config/modules.json on disk and reloads the
-// in-process cache, so the effect is immediate on this box. Like any other
-// hand-edit of that file, surviving the next `git reset --hard` deploy needs
-// the change committed — this route does not auto-commit (an HTTP handler
-// auto-pushing to main bypasses the ship/grade/deploy pipeline, which the
-// project's trust boundary treats as a bigger risk than a toggle that needs a
-// human/agent to land it properly). Captured as a follow-up idea: durable
-// (DB-backed) module enablement that survives a deploy with no extra step.
+// Persistence note: /modules/:key/enable writes config/modules.json on disk
+// and reloads the in-process cache, so the effect is immediate on this box.
+// Like any other hand-edit of that file, surviving the next `git reset --hard`
+// deploy needs the change committed — this route does not auto-commit (an
+// HTTP handler auto-pushing to main bypasses the ship/grade/deploy pipeline,
+// which the project's trust boundary treats as a bigger risk than a toggle
+// that needs a human/agent to land it properly). Captured as a follow-up
+// idea: durable (DB-backed) module enablement that survives a deploy with no
+// extra step.
+//
+// Why the review queue is a table in THIS instance's own DB (not a live
+// cross-repo call to the extracted core repo): see
+// docs/adr/0135-module-upstream-submission-interim-queue.md.
 
 const express = require('express');
 const fs = require('node:fs');
 const path = require('node:path');
 const auth = require('../auth');
-const { asyncHandler, validateOrRespond } = require('./_helpers');
+const { asyncHandler, validateOrRespond, LIMITS } = require('./_helpers');
 const loader = require('../../module-loader/loader');
 const { deriveProvenance } = require('../../module-loader/provenance');
 const modulesLib = require('../../modules');
+// scripts/gds/ is a sibling CORE-package dir (both resolve under
+// resolveCoreRoot() — see scripts/gds/CLAUDE.md), so requiring its pure fs
+// logic from here is in-boundary. module.js never statically requires the CLI
+// session/fetch layer (cli-lib.js) — only cmdSubmit lazy-requires it, and only
+// when actually invoked from the CLI — so this stays safe in the always-on
+// server process.
+const moduleCli = require('../../../scripts/gds/module');
+const moduleSubmissions = require('../module-submissions');
+
+// A packaged submission embeds every file's content (base64) — cap the total
+// so a runaway/misbuilt module can't bloat the review-queue table. Generous
+// headroom over what a real feature module carries (routes + migrations + UI
+// + a CLAUDE.md are typically tens of KB); mirrors the security_docs content
+// cap (SECURITY_DOC_CONTENT_MAX) in routes/security.js.
+const SUBMISSION_MAX_BYTES = 5_000_000;
 
 function ownProjectName() {
   try { return require('../../branding').branding().identity.productName; } catch { return null; }
 }
 
+// "owner/name", e.g. "lars589/amazonprimea" — the provenance a submission
+// carries (ADR 0107 §2: attribution/provenance travels WITH the module as a
+// portable record, not a cross-GDS link). null if the branding pack has none.
+function sourceRepoLabel() {
+  try {
+    const repo = require('../../branding').branding().repo;
+    return repo && repo.name ? `${repo.owner || '?'}/${repo.name}` : null;
+  } catch { return null; }
+}
+
 function readInstanceConfig() {
   try { return JSON.parse(fs.readFileSync(modulesLib.INSTANCE_PATH, 'utf8')); }
   catch (e) { if (e.code === 'ENOENT') return { modules: {} }; throw e; }
@@ -78,7 +113,7 @@ module.exports = function buildModulesRouter() {
       modules: all,
       own_built: all.filter((m) => m.provenance === 'own').length,
       core_loaded: all.filter((m) => m.provenance === 'core').length,
-      submit_pipeline_live: false, // flips true once task 1770 ships
+      submit_pipeline_live: true, // task 1770 shipped — POST /modules/:key/submit is real
     });
   }));
 
@@ -108,7 +143,17 @@ module.exports = function buildModulesRouter() {
       res.json({ ok: true, key, enabled, note: 'Live on this box now. Persisting past the next deploy needs config/modules.json committed.' });
     }));
 
-  // rank: metic+archon — the "submit this module for review" front door (501 until the submit pipeline, task 1770, ships).
+  // POST /api/gds/modules/:key/submit — ADR 0107 §1 upstreaming submission.
+  //
+  // task 1770. Body: { signed_by?: "Name <email>" }. Re-runs the §4
+  // AGPL/publish pre-check + requires a DCO-style sign-off against THIS box's
+  // OWN on-disk copy of modules/:key (the authoritative check — a local
+  // `bongos module check` pass on a builder's box is a courtesy, not proof, if
+  // the module's changes aren't committed + shipped + deployed here yet).
+  // signed_by records a NEW sign-off only if none is on file; an existing
+  // .upstream-signoff.json is reused as-is (not overwritten).
+  //
+  // rank: metic+archon — files into a shared review queue, not just a toggle for the caller.
   router.post('/modules/:key/submit', auth.requireBuilder, auth.requireRank('metic', 'archon'),
     asyncHandler('POST /modules/:key/submit', async (req, res) => {
       const { key } = req.params;
@@ -116,10 +161,67 @@ module.exports = function buildModulesRouter() {
       if (!known.find((m) => m.key === key)) {
         return res.fail('not_found', { status: 404, message: `No on-disk module "${key}".` });
       }
-      res.fail('not_yet_available', {
-        status: 501,
-        message: 'The module-submit pipeline (bongos module submit → core review queue) is not live yet — tracked by task 1770 (ADR 0107 §8/§9). This front door will call straight through once it ships.',
+      if (validateOrRespond(req, res, { signed_by: { type: 'string', maxLength: LIMITS.TITLE } })) return;
+
+      const precheck = moduleCli.checkModulePublishability(key);
+      if (!precheck.ok) {
+        return res.fail('precheck_failed', {
+          status: 422,
+          message: `"${key}" is not clear to submit upstream (ADR 0107 §4 AGPL/publish pre-check failed).`,
+          findings: precheck.findings,
+        });
+      }
+
+      let signOff = moduleCli.readSignOff(key);
+      const signedBy = req.body && typeof req.body.signed_by === 'string' ? req.body.signed_by.trim() : '';
+      if (!signOff && signedBy) {
+        moduleCli.recordSignOff(key, signedBy);
+        signOff = moduleCli.readSignOff(key);
+      }
+      if (!signOff) {
+        return res.fail('sign_off_required', {
+          status: 422,
+          message: `No DCO-style sign-off on file for "${key}". Pass "signed_by": "Name <email>" to affirm + record it.`,
+        });
+      }
+
+      const pkg = moduleCli.packageModuleForSubmission(key);
+      if (pkg.totalBytes > SUBMISSION_MAX_BYTES) {
+        return res.fail('submission_too_large', {
+          status: 413,
+          message: `"${key}" is ${pkg.totalBytes} bytes, over the ${SUBMISSION_MAX_BYTES}-byte upstreaming cap.`,
+        });
+      }
+
+      const submission = await moduleSubmissions.createModuleSubmission({
+        moduleKey: key,
+        submittedBy: req.builder.id,
+        manifest: pkg.manifest,
+        files: pkg.files,
+        signOff,
+        precheckPassedAt: new Date(),
+        sourceRepo: sourceRepoLabel(),
       });
+
+      console.log(`[gds] module "${key}" submitted upstream by builder ${req.builder.id} — submission ${submission.id}`);
+      res.status(201).json({ ok: true, submission });
+    }));
+
+  // GET /api/gds/modules/submissions?status=&module_key= — the upstreaming
+  // review queue (task 1771 reads this). Metadata only — no file contents (a
+  // future GET .../:id can add a with-files fetch if the review UI needs it).
+  //
+  // rank: metic+archon — the review queue, same rank as filing into it.
+  router.get('/modules/submissions', auth.requireBuilder, auth.requireRank('metic', 'archon'),
+    asyncHandler('GET /modules/submissions', async (req, res) => {
+      const status = req.query.status ? String(req.query.status) : undefined;
+      if (status && !['pending', 'accepted', 'rejected'].includes(status)) {
+        return res.fail('bad_status', { status: 400, message: 'status must be one of pending|accepted|rejected.' });
+      }
+      const moduleKey = req.query.module_key ? String(req.query.module_key) : undefined;
+      const submissions = await moduleSubmissions.listModuleSubmissions({ status, moduleKey });
+      res.set('Cache-Control', 'no-store');
+      res.json({ submissions });
     }));
 
   return router;