@bongos/core 1.17.0 → 1.17.2

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;

package/src/bongos/serve-internal.js

@@ -318,7 +318,16 @@ function mountInternalSurfaces(app) {
   // confirmation can commit-PIN (deployedCommit === mergeCommit) rather than only
   // checking liveness via /healthz. Low-sensitivity (a public commit sha).
   app.get('/version', (_req, res) => {
-    res.json(buildInfo());
+    // coreVersion — the @bongos/core doorway version this process is running
+    //   (src/module-api CORE_VERSION), read lazily to avoid a load-time cycle
+    //   (module-api requires build-info at load, so a top-level require here
+    //   would be circular). Additive: lets fleet/upgrade tooling confirm which
+    //   core an instance actually materialized after a `bongos upgrade`,
+    //   alongside the deployed git commit below. (Added in 1.17.2, task 2148 —
+    //   the throwaway `updateCanary` proof marker was removed in phase E.)
+    let coreVersion = null;
+    try { coreVersion = require('../module-api').CORE_VERSION; } catch { /* fail-soft: version unknown */ }
+    res.json({ ...buildInfo(), coreVersion });
   });
 
   // Generated typed client for classic <script> web pages (task 1996 / R09).

package/src/branding.js

@@ -42,6 +42,7 @@ const ENV_OVERRIDES = [
   ['BUILDERS_ORIGIN', ['domains', 'buildersOrigin']],
   ['STATUS_ORIGIN', ['domains', 'statusOrigin']],
   ['OAUTH_ORIGIN', ['domains', 'oauthOrigin']],
+  ['PROVISIONING_ORIGIN', ['domains', 'provisioningOrigin']],
   ['COOKIE_DOMAIN', ['domains', 'cookieDomain']],
 ];
 

package/src/instance-config.js

@@ -172,7 +172,7 @@ function resolveInstanceRoot({ env = process.env } = {}) {
 // is written/read. A consumer that installs the core as an npm dep points at its
 // own repo (via <PREFIX>_INSTANCE_ROOT / bongos.config.json — e.g. `bongos
 // upgrade` sets it), so the docs+client regenerate INTO the instance, not into
-// node_modules/@cloudbongos/core. In a single checkout no pointer is set, so this
+// node_modules/@bongos/core. In a single checkout no pointer is set, so this
 // is resolveCoreRoot() — BYTE-IDENTICAL to today (ADR 0108). Deliberately NOT the
 // cwd fallback: a generated-doc write must be deterministic.
 function resolveDocsRoot(opts = {}) {

package/src/module-api.js

@@ -176,8 +176,31 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         the same reason validateOrRespond/LIMITS are on the doorway. Additive
 //         (new exports, no export removed or changed) → MINOR; every `^1.x`
 //         module keeps working, and a module using them is satisfied by 1.17.0.
+// 1.17.1 — task 2124 (republish after task 2121): the FIRST PATCH bump on this
+//         surface. No doorway export is added, changed, or removed — the exported
+//         surface is byte-identical to 1.17.0. What changed is the PUBLISHED ARTIFACT's
+//         content: (a) task 2121 taught package-core to replace every CLAUDE.md/AGENTS.md
+//         in the @bongos/core tarball with a tiny brand-free stub, so a consumer instance's
+//         agent no longer auto-loads the platform's own project memory from
+//         node_modules/@bongos/core/ (the 2026-07-08 demo audit leak); (b) the bundled code
+//         carries the task-2126 clearer device_flow_disabled error surfacing. A backwards-
+//         compatible artifact fix with no API change is exactly semver PATCH. The bump is
+//         REQUIRED because 1.17.0 was already published to npm and task 2121 shipped
+//         without one, so `bongos package-core --publish` on 1.17.0 would be rejected as a
+//         re-publish. Every `^1.x` / `^1.17` module pin is satisfied by 1.17.1.
+// 1.17.2 — task 2148 (canary upgrade-proof on demo.cloudbongos.com): a controlled
+//         PATCH bump used to round-trip the real `bongos upgrade` channel on the live
+//         demo instance with an OBSERVABLE code marker (the channel shipped in 1.16.0
+//         and was proven on emersonian-circles by task 1976, but never on demo with a
+//         served marker). No doorway export is added, changed, or removed — the exported
+//         surface is byte-identical to 1.17.1. What changed: the served /version payload
+//         now carries `coreVersion` (the running doorway version — a PERMANENT additive
+//         read so upgrade/fleet tooling can confirm which core an instance materialized),
+//         plus a THROWAWAY `updateCanary` marker removed in the phase-E follow-up. A
+//         backwards-compatible additive change with no API removal is exactly semver
+//         PATCH. Every `^1.x` / `^1.17` module pin is satisfied by 1.17.2.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.17.0'; // see the changelog above — R14 adds the shared pagination helpers to the doorway (#2001)
+const CORE_VERSION = '1.17.2'; // see the changelog above — 1.17.2 is the task-2148 canary upgrade-proof bump (adds /version coreVersion; no doorway export change)
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/src/module-loader/loader.js

@@ -19,11 +19,42 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { validateManifest } = require('./manifest-schema');
 const { satisfies } = require('./semver');
-const { resolveCoreRoot } = require('../instance-config');
+const { resolveCoreRoot, resolveInstanceRoot } = require('../instance-config');
 
-// ADR 0108 §1: modules/ ships WITH the core package. resolveCoreRoot() returns
-// the repo root today, so this is byte-identical for the live instance.
-const DEFAULT_ROOTS = [path.join(resolveCoreRoot(), 'modules')];
+// Collapse roots that resolve to the SAME absolute path, preserving order.
+// Normalizes via path.resolve so a cwd that arrives with a trailing '.'/'//'
+// segment still dedupes against the core root. Returns the resolved (canonical)
+// paths. (Exported for the loader tests.)
+function dedupeRoots(roots) {
+  const out = [];
+  const seen = new Set();
+  for (const r of roots) {
+    const key = path.resolve(r);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(key);
+  }
+  return out;
+}
+
+// ADR 0108 §1 + task 2133 (R89-prereq): discovery must span TWO roots — the core
+// PACKAGE's own modules/ (resolveCoreRoot()) AND the consumer/instance's own
+// modules/ (resolveInstanceRoot()). Post-split the host modules (game /
+// art-pipeline / provisioning) live at the instance root and are EXCLUDED from
+// the @bongos/core package, so a core-only scan boots a split instance with none
+// of its host modules.
+//
+// DEDUP BY RESOLVED PATH IS MANDATORY. In a single checkout resolveInstanceRoot()
+// falls back to process.cwd(), which equals resolveCoreRoot() (the repo root), so
+// the two candidates are the SAME directory. discoverModules() treats a repeated
+// module KEY as a hard ERROR (not a skip), so scanning one root twice would turn
+// every module into a "duplicate module key" error. dedupeRoots() collapses the
+// coincident roots, so a single checkout scans ONE root (byte-identical to
+// before) while a diverged split scans BOTH.
+const DEFAULT_ROOTS = dedupeRoots([
+  path.join(resolveCoreRoot(), 'modules'),
+  path.join(resolveInstanceRoot(), 'modules'),
+]);
 
 // Lazy — avoids an eval-time require cycle (modules.js → loader → module-api →
 // auth → …). By call time the graph is loaded; falls back to the known initial
@@ -263,6 +294,7 @@ module.exports = {
   stopModulePollers,
   loaderSnapshot,
   coreVersion,
+  dedupeRoots,
   DEFAULT_ROOTS,
   _reset,
 };

package/src/module-loader/manifest-schema.js

@@ -30,7 +30,11 @@
 //     },
 //     "provides":      ["reward"],      // OPTIONAL. seam PORTS this module registers a provider for.
 //     "consumes":      ["grade"],       // OPTIONAL. seam ports this module resolves (required capabilities).
-//     "prerequisites": { "modules": ["economy"] }  // OPTIONAL. other modules that must be enabled.
+//     "prerequisites": { "modules": ["economy"] },  // OPTIONAL. other modules that must be enabled.
+//     "dependencies":  { "discord.js": "^14.26.4" }  // OPTIONAL. external npm deps this module needs at
+//                                       //   runtime. Core stays lean (express+pg, ADR 0108); a bundled
+//                                       //   module that needs more declares it HERE, and the consumer
+//                                       //   composes the deps of the modules it ENABLES (ADR 0138).
 //   }
 //
 // validateManifest(obj) -> { valid, errors[], manifest } — pure, no I/O.
@@ -126,6 +130,17 @@ function validateManifest(obj) {
     }
   }
 
+  // --- optional runtime npm dependencies (ADR 0138 / task 2160) ---
+  // A bundled module's own external npm deps. @bongos/core stays lean (express+pg, ADR 0108);
+  // a module that needs more (e.g. discord.js) declares it here, and the consumer composes the
+  // deps of the modules it ENABLES (scripts/gds/init.js). Shape: { "<npm-name>": "<semver-range>" }.
+  if ('dependencies' in obj) {
+    const d = obj.dependencies;
+    if (!isObj(d) || !Object.entries(d).every(([k, v]) => isStr(k) && isStr(v))) {
+      E('dependencies: must be an object of { "<npm-name>": "<semver-range>" } string pairs');
+    }
+  }
+
   return { valid: errors.length === 0, errors, manifest: errors.length === 0 ? obj : null };
 }
 

package/tests/branding.mjs

@@ -52,6 +52,17 @@ test('env override is ignored when empty', () => {
   assert.equal(b.domains.publicOrigin, 'https://amazonprimea.com');
 });
 
+test('provisioningOrigin: optional, passes through config, env-overridable (task 2101)', () => {
+  // Not required — unset resolves to undefined, and callers fall back to publicOrigin.
+  assert.equal(resolveBranding({ neutral: NEUTRAL, instance: OTB }).domains.provisioningOrigin, undefined);
+  // Set in the instance pack, it survives the deep-merge.
+  const inst = resolveBranding({ neutral: NEUTRAL, instance: { ...OTB, domains: { ...OTB.domains, provisioningOrigin: 'https://get.cloudbongos.com' } } });
+  assert.equal(inst.domains.provisioningOrigin, 'https://get.cloudbongos.com');
+  // And <PREFIX>_PROVISIONING_ORIGIN beats config (same precedence as the other origins).
+  const env = resolveBranding({ neutral: NEUTRAL, instance: OTB, env: { OTB_PROVISIONING_ORIGIN: 'https://get.cloudbongos.com' } });
+  assert.equal(env.domains.provisioningOrigin, 'https://get.cloudbongos.com');
+});
+
 test('missing required field throws', () => {
   assert.throws(() => resolveBranding({ neutral: { identity: { productName: 'X' } } }), /missing required field/);
 });

package/tests/claim_error_surface.mjs

@@ -0,0 +1,107 @@
+// tests/claim_error_surface.mjs
+//
+// task 1476 — a failed /builder-claim must read as GUIDANCE, not a raw object
+// dump. The API returns the R01 error envelope (ADR 0116):
+//   { error: { code, message, details } }
+// so claim.js's old `r.data.error === 'CODE'` string branches all silently
+// missed (error is now an object) and the refusal printed as `[object Object]`.
+// This exercises the pure formatClaimFailure() surface DB-free, over BOTH the
+// current envelope shape and the legacy flat shape.
+//
+// Run:  node tests/claim_error_surface.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { formatClaimFailure } = require('../scripts/gds/claim.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const envelope = (code, details = {}, message = code, status = 409) => ({
+  status,
+  data: { error: { code, message, details } },
+});
+const text = (r) => r.lines.join('\n');
+
+// The regression guard: no refusal may ever render a raw object.
+t('never dumps [object Object] for any known code', () => {
+  const codes = [
+    'stage_required', 'session_already_has_active_claim', 'session_claim_check_failed',
+    'newcomer_must_ship_first', 'ALREADY_CLAIMED', 'MODULE_CONFLICT',
+    'TOUCHES_CONFLICT', 'TASK_NOT_READY', 'TASK_NOT_FOUND', 'DEPS_NOT_SHIPPED',
+    'some_unmapped_future_code',
+  ];
+  for (const c of codes) {
+    const out = text(formatClaimFailure(envelope(c, { active_task_id: 5 }, 'msg'), 12));
+    assert.ok(!out.includes('[object Object]'), `${c} produced a raw object dump`);
+    assert.ok(out.trim().length > 0, `${c} produced no output`);
+  }
+});
+
+// The core 1476 case: one-claim-per-session refusal is guidance + teaches parallel.
+t('session_already_has_active_claim: names the in-flight task and teaches parallelism', () => {
+  const out = text(formatClaimFailure(
+    envelope('session_already_has_active_claim', {
+      active_task_id: 42, active_task_title: 'Foo', what_to_do: 'ship 42 first',
+    }), 99));
+  assert.match(out, /#42/, 'should name the in-flight task id');
+  assert.match(out, /Foo/, 'should name the in-flight task title');
+  assert.match(out, /ship 42 first/, 'should relay the server what_to_do');
+  assert.match(out, /PARALLEL/i, 'should teach how to parallelize');
+  assert.match(out, /worktree|bulk-claim/i, 'should point at separate worktree or bulk-claim');
+});
+
+t('session_claim_check_failed shares the same guidance branch', () => {
+  const out = text(formatClaimFailure(envelope('session_claim_check_failed', {}), 3));
+  assert.match(out, /active claim/i);
+  assert.match(out, /PARALLEL/i);
+});
+
+// Envelope + legacy flat shape must BOTH resolve the code + fields.
+t('TASK_NOT_READY: envelope shape reads details.currentStatus + hint', () => {
+  const out = text(formatClaimFailure(
+    envelope('TASK_NOT_READY', { currentStatus: 'backlog', hint: 'promote it first' }), 7));
+  assert.match(out, /not ready/i);
+  assert.match(out, /backlog/);
+  assert.match(out, /promote it first/);
+});
+
+t('TASK_NOT_READY: legacy flat shape still resolves', () => {
+  const flat = { status: 409, data: { error: 'TASK_NOT_READY', currentStatus: 'blocked' } };
+  const out = text(formatClaimFailure(flat, 7));
+  assert.match(out, /not ready/i);
+  assert.match(out, /blocked/);
+});
+
+t('DEPS_NOT_SHIPPED: lists each blocking dependency', () => {
+  const out = text(formatClaimFailure(
+    envelope('DEPS_NOT_SHIPPED', { deps: [{ id: 10, status: 'ready', title: 'Dep A' }] }), 8));
+  assert.match(out, /#10/);
+  assert.match(out, /Dep A/);
+});
+
+t('MODULE_CONFLICT + TOUCHES_CONFLICT: list conflicting task titles', () => {
+  const mc = text(formatClaimFailure(
+    envelope('MODULE_CONFLICT', { module_key: 'economy', conflictTaskTitles: ['Bar'] }), 4));
+  assert.match(mc, /economy/);
+  assert.match(mc, /Bar/);
+  const tc = text(formatClaimFailure(
+    envelope('TOUCHES_CONFLICT', { conflictTaskTitles: ['Baz'] }), 4));
+  assert.match(tc, /Baz/);
+});
+
+t('unknown code: fallback carries code + message, exit 1', () => {
+  const r = formatClaimFailure(envelope('weird_thing', {}, 'boom', 500), 1);
+  assert.equal(r.exit, 1);
+  assert.match(text(r), /weird_thing/);
+  assert.match(text(r), /boom/);
+});
+
+console.log(`\nclaim_error_surface: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/claude_materialize.mjs

@@ -108,6 +108,26 @@ t('materializeClaude: copies + rewrites skills into a fresh instance dir (no lef
   rmSync(dir, { recursive: true, force: true });
 });
 
+t('materializeClaude: materializes scheduled-tasks — bodies→bongos, companions keep _core-resolve (task 2138)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'w3-rt-'));
+  const res = m.materializeClaude({ coreRoot: ROOT, instanceDir: dir, dryRun: false });
+  assert.ok(res.scheduledTasks > 0, 'at least one scheduled-task file materialized');
+  const rt = join(dir, '.claude', 'scheduled-tasks');
+  assert.ok(existsSync(rt), '.claude/scheduled-tasks created in the instance');
+  // A prose/judgment body's core invocation is bongosified so a consumer-layout model can run it.
+  const stale = readFileSync(join(rt, 'stale-claim-release', 'SKILL.md'), 'utf8');
+  assert.ok(stale.includes('bongos exec scripts/gds/pulse.js'), 'body core-invocation rewritten to bongos exec');
+  assert.ok(!stale.includes('node scripts/gds/pulse.js'), 'no bare relative node scripts/gds left in the body');
+  // A deterministic routine's `.claude/...` companion-step command is NOT a core invocation → preserved.
+  const dd = readFileSync(join(rt, 'diagram-drift', 'SKILL.md'), 'utf8');
+  assert.ok(dd.includes('node .claude/scheduled-tasks/diagram-drift/check.js'), 'companion-path step command preserved');
+  // Companion .js resolves its core require()s via the materialized _core-resolve.js sibling (task 2139 pattern).
+  const check = readFileSync(join(rt, 'diagram-drift', 'check.js'), 'utf8');
+  assert.ok(check.includes("require('../../hooks/_core-resolve.js')"), 'companion resolves core via _core-resolve');
+  assert.ok(!check.includes("require('../../../scripts/gds/"), 'no bare ../../../scripts/gds require left in the companion');
+  rmSync(dir, { recursive: true, force: true });
+});
+
 t('materializeClaude: SELF-COPY guard — target === core root is a no-op (byte-identical for the live instance)', () => {
   const res = m.materializeClaude({ coreRoot: ROOT, instanceDir: ROOT, dryRun: false });
   assert.equal(res.skipped, true, 'materializing onto the core root must skip');
@@ -144,5 +164,110 @@ t('copyTreeTransformed: overwrite defaults true → greenfield still clobbers (r
   rmSync(dest, { recursive: true, force: true });
 });
 
+// ---- instance rebrand (task 2103a) -----------------------------------------
+const OTB = { domains: { publicOrigin: 'https://amazonprimea.com', buildersOrigin: 'https://builders.amazonprimea.com', statusOrigin: 'https://status.amazonprimea.com' }, configDir: 'otb', envPrefix: 'OTB' };
+
+t('buildRebrandRules: full target → founder origin/config-dir/prefix all rewritten', () => {
+  const to = { domains: { publicOrigin: 'https://demo.cloudbongos.com', buildersOrigin: 'https://demo.cloudbongos.com', statusOrigin: 'https://demo.cloudbongos.com' }, envPrefix: 'CLOUDBONGOS' };
+  const out = m.rebrandText('b="https://amazonprimea.com" h="builders.amazonprimea.com" ~/.config/otb OTB_API_BASE [otb]', m.buildRebrandRules(OTB, to));
+  assert.ok(!out.includes('amazonprimea'), `no founder host survives: ${out}`);
+  assert.ok(out.includes('https://demo.cloudbongos.com'), 'public origin rewritten');
+  assert.ok(out.includes('~/.config/cloudbongos') && out.includes('CLOUDBONGOS_API_BASE') && out.includes('[cloudbongos]'), 'config-dir + prefix + log tag rewritten');
+});
+
+t('buildRebrandRules: partial target (only publicOrigin) → subdomains fall back to target public host, not builders.<target>', () => {
+  const out = m.rebrandText('builders.amazonprimea.com', m.buildRebrandRules(OTB, { domains: { publicOrigin: 'https://acme.example.org' }, envPrefix: 'ACME' }));
+  assert.equal(out, 'acme.example.org', 'no builders.acme.example.org mangling');
+});
+
+t('buildRebrandRules: source === target is an empty ruleset → rebrandText is a no-op', () => {
+  assert.equal(m.buildRebrandRules(OTB, OTB).length, 0);
+  const s = 'https://amazonprimea.com ~/.config/otb';
+  assert.equal(m.rebrandText(s, m.buildRebrandRules(OTB, OTB)), s);
+});
+
+// ---- skill filtering by disabled module (task 2103b) -----------------------
+t('disabledModuleSkills: only skills of DISABLED modules are collected (default + explicit override)', () => {
+  const core = mkdtempSync(join(tmpdir(), 'rb-core-'));
+  const inst = mkdtempSync(join(tmpdir(), 'rb-inst-'));
+  const mod = (key, def, skills) => { const d = join(core, 'modules', key); mkdirSync(d, { recursive: true }); writeFileSync(join(d, 'module.json'), JSON.stringify({ key, default: def, contributes: { skills } })); };
+  mod('foo', false, ['a']);   // default off, but ENABLED in config → keep
+  mod('bar', true, ['b']);    // default on, not overridden → keep
+  mod('baz', false, ['c']);   // default off, not overridden → SKIP
+  mod('qux', true, ['d']);    // default on, but DISABLED in config → SKIP
+  mkdirSync(join(inst, 'config'), { recursive: true });
+  writeFileSync(join(inst, 'config', 'modules.json'), JSON.stringify({ modules: { foo: true, qux: false } }));
+  const skip = m.disabledModuleSkills({ coreRoot: core, instanceDir: inst });
+  assert.deepEqual([...skip].sort(), ['c', 'd']);
+  rmSync(core, { recursive: true, force: true }); rmSync(inst, { recursive: true, force: true });
+});
+
+// ---- materializeClaude end-to-end: rebrand + skill-exclude (from the REAL repo) --
+t('materializeClaude: copied hooks carry NO founder origin/config-dir; a disabled-module skill is excluded', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'rb-e2e-'));
+  // Target instance: demo-branded, art-pipeline OFF (so its otb-* skills must be dropped).
+  mkdirSync(join(dir, 'config'), { recursive: true });
+  writeFileSync(join(dir, 'config', 'branding.json'), JSON.stringify({ domains: { publicOrigin: 'https://demo.cloudbongos.com', buildersOrigin: 'https://demo.cloudbongos.com', statusOrigin: 'https://demo.cloudbongos.com', oauthOrigin: 'https://demo.cloudbongos.com' }, configDir: 'cloudbongos', envPrefix: 'CLOUDBONGOS' }));
+  writeFileSync(join(dir, 'config', 'modules.json'), JSON.stringify({ modules: { 'art-pipeline': false } }));
+  const res = m.materializeClaude({ coreRoot: ROOT, instanceDir: dir, dryRun: false });
+  assert.ok(res.rebrandRules > 0, 'rebrand rules were built from the OTB→demo branding delta');
+
+  // (a) no copied hook may still name the founder origin or config dir.
+  const offenders = [];
+  const hooksDir = join(dir, '.claude', 'hooks');
+  if (existsSync(hooksDir)) {
+    const walk = (d) => { for (const n of readdirSync(d, { withFileTypes: true })) { const p = join(d, n.name); if (n.isDirectory()) walk(p); else { const txt = readFileSync(p, 'utf8'); if (txt.includes('amazonprimea.com') || txt.includes('.config/otb') || txt.includes('/etc/otb')) offenders.push(n.name); } } };
+    walk(hooksDir);
+  }
+  assert.deepEqual(offenders, [], `founder origin/config-dir survived in: ${offenders.join(', ')}`);
+
+  // (b) art-pipeline is off → its otb-* skills are excluded; a core skill remains.
+  assert.ok(res.excludedSkills.includes('otb-tile-generate'), `art-pipeline skill excluded (got ${res.excludedSkills.join(',')})`);
+  assert.ok(!existsSync(join(dir, '.claude', 'skills', 'otb-tile-generate')), 'excluded skill not written');
+  assert.ok(existsSync(join(dir, '.claude', 'skills', 'builder-ship')), 'a core skill is still materialized');
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ---- CLAUDE.md scaffold (task 2104) ----------------------------------------
+const tmpl = require('../scripts/gds/claude-md-template.js');
+
+t('renderInstanceClaudeMd: brand-substituted — names the instance + its hall/currency, no founder literal', () => {
+  const md = tmpl.renderInstanceClaudeMd({ identity: { productName: 'Acme', worldName: 'Acmeland', company: { name: 'Widgets Inc' } }, domains: { publicOrigin: 'https://acme.example.org', buildersOrigin: 'https://builders.acme.example.org', statusOrigin: 'https://status.acme.example.org' }, currency: { label: 'coins' } });
+  assert.ok(md.startsWith('# Acme — Project Memory'), 'titled with the product name');
+  assert.ok(md.includes('the Acmeland world') && md.includes('by Widgets Inc'), 'world + company woven in');
+  assert.ok(md.includes('https://builders.acme.example.org'), 'hall origin present');
+  assert.ok(md.includes('coins'), 'currency label present');
+  assert.ok(!md.toLowerCase().includes('amazonprimea') && !md.includes('~/.config/otb'), 'no founder literal in the starter');
+});
+
+t('renderInstanceClaudeMd: degrades cleanly on a minimal branding (no world dup, defaults currency)', () => {
+  const md = tmpl.renderInstanceClaudeMd({ identity: { productName: 'Solo', worldName: 'Solo' } });
+  assert.ok(md.startsWith('# Solo — Project Memory'));
+  assert.ok(!md.includes('the Solo world'), 'world == product is not duplicated');
+  assert.ok(md.includes('credits'), 'currency defaults to credits');
+});
+
+t('materializeClaude: writes a brand-substituted CLAUDE.md when the instance has none', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'cm-md-'));
+  mkdirSync(join(dir, 'config'), { recursive: true });
+  writeFileSync(join(dir, 'config', 'branding.json'), JSON.stringify({ identity: { productName: 'Freshie' }, domains: { publicOrigin: 'https://freshie.example.com' }, configDir: 'freshie', envPrefix: 'FRESHIE' }));
+  const res = m.materializeClaude({ coreRoot: ROOT, instanceDir: dir, dryRun: false });
+  assert.equal(res.claudeMd, true, 'reported writing CLAUDE.md');
+  assert.ok(readFileSync(join(dir, 'CLAUDE.md'), 'utf8').startsWith('# Freshie — Project Memory'), 'written + brand-substituted');
+  rmSync(dir, { recursive: true, force: true });
+});
+
+t('materializeClaude: NEVER clobbers an existing CLAUDE.md (init / adopt / upgrade safe)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'cm-md2-'));
+  mkdirSync(join(dir, 'config'), { recursive: true });
+  writeFileSync(join(dir, 'config', 'branding.json'), JSON.stringify({ identity: { productName: 'Freshie' }, domains: { publicOrigin: 'https://freshie.example.com' } }));
+  const owner = '# My own CLAUDE.md — do not touch\n';
+  writeFileSync(join(dir, 'CLAUDE.md'), owner);
+  const res = m.materializeClaude({ coreRoot: ROOT, instanceDir: dir, dryRun: false });
+  assert.equal(res.claudeMd, false, 'did not (re)write');
+  assert.equal(readFileSync(join(dir, 'CLAUDE.md'), 'utf8'), owner, 'existing CLAUDE.md left byte-untouched');
+  rmSync(dir, { recursive: true, force: true });
+});
+
 console.log(`\nclaude_materialize: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);