@bongos/core 1.17.1 → 1.17.3

package/scripts/hall-preview/server.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// scripts/hall-preview/server.js — the hall preview harness (task 2167).
+//
+// The dev-box sandbox previews the GAME only (/builders 404s there, idea 490),
+// so hall-ui changes are reviewed HERE: a tiny express app that serves the real
+// modules/hall-ui/public files through the REAL serving seams (boot-time ?v=
+// stamping, {{token}} replacement, __BRANDING__/__MODULES__ injection, theme
+// markup) with the /api/gds|bongos reads answered from checked-in fixtures.
+// Boots DB-less (pg pools connect lazily). Proven recipe from tasks 1723/1742,
+// finally checked in.
+//
+//   node scripts/hall-preview/server.js [--port 4600] [--brand <file>]
+//        [--modules-off dev-box,provisioning] [--empty]
+//
+//   --port         listen port (default 4600)
+//   --brand        branding pack file — default config/branding.neutral.json
+//                  (vanilla); pass config/branding.json for the instance pack
+//   --modules-off  comma list of module keys to report disabled in
+//                  window.__MODULES__ (verifies moduleOn() gating)
+//   --empty        serve every fixture with its arrays emptied — the
+//                  empty-state screenshot pass
+//
+// Browse http://builders.localhost:<port>/ — Chromium resolves *.localhost,
+// and the `builders.` host prefix exercises the real subdomain serving path.
+// Refresh fixtures from live data: node scripts/hall-preview/refresh-fixtures.js
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PUB = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const FIXTURES = path.join(__dirname, 'fixtures');
+
+// ---- flags (before any src/ require: --brand must win the branding resolve) --
+function arg(name) {
+  const i = process.argv.indexOf(name);
+  return i > -1 ? process.argv[i + 1] : null;
+}
+const PORT = Number(arg('--port')) || 4600;
+const EMPTY = process.argv.includes('--empty');
+const MODULES_OFF = String(arg('--modules-off') || '').split(',').map((s) => s.trim()).filter(Boolean);
+// --modules-on: force-report modules as enabled — a dev box's local config
+// often lacks prod's instance modules (provisioning, dev-box), and their
+// widgets can't be reviewed without it (task 2169).
+const MODULES_ON = String(arg('--modules-on') || '').split(',').map((s) => s.trim()).filter(Boolean);
+const BRAND_FILE = arg('--brand') || 'config/branding.neutral.json';
+process.env.GDS_BRANDING_FILE = path.resolve(ROOT, BRAND_FILE);
+
+/* eslint-disable import/no-dynamic-require */
+// express comes from this tree's node_modules when installed, else node's
+// normal upward walk finds the main checkout's copy (a git worktree under
+// .claude/worktrees/ has no node_modules of its own). The src/ seams below are
+// ALWAYS taken from THIS tree so a worktree's edits are what gets previewed.
+let express;
+try { express = require(path.join(ROOT, 'node_modules', 'express')); }
+catch (_) { express = require('express'); }
+const { buildStampedHtml } = require(path.join(ROOT, 'src', 'asset-version.js'));
+const { injectBrandingGlobal, mountInternalSurfaces } = require(path.join(ROOT, 'src', 'bongos', 'serve-internal.js'));
+const { clientModules } = require(path.join(ROOT, 'src', 'modules.js'));
+
+// ---- fixtures ---------------------------------------------------------------
+// File naming: the API path with slashes as "__" — /me/recent-ships →
+// me__recent-ships.json. Query strings are ignored when matching. Id-bearing
+// paths fall back to the generic names below so one fixture serves any id.
+const FIXTURE_FALLBACKS = [
+  [/^goals\/\d+\/conflicts$/, 'goals__conflicts'],
+  [/^goals\/\d+\/requests$/, 'goals__requests'],
+  [/^goals\/\d+$/, 'goals__detail'],
+  [/^tasks\/\d+$/, 'tasks__detail'],
+  [/^analytics\/builder\/\d+$/, 'analytics__builder'],
+  [/^builders\/\d+\/active-claims$/, 'builders__active-claims'],
+];
+
+function loadFixture(name) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(FIXTURES, `${name}.json`), 'utf8'));
+  } catch (_) { return undefined; }
+}
+
+// --empty: the same pages, with nothing in them — every array drains so each
+// page's empty states render. Scalars/strings survive (identity stays real).
+function emptied(v) {
+  if (Array.isArray(v)) return [];
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const [k, val] of Object.entries(v)) out[k] = emptied(val);
+    return out;
+  }
+  return v;
+}
+
+function fixtureFor(apiPath) {
+  const exact = loadFixture(apiPath.replace(/\//g, '__'));
+  if (exact !== undefined) return exact;
+  for (const [re, name] of FIXTURE_FALLBACKS) {
+    if (re.test(apiPath)) {
+      const hit = loadFixture(name);
+      if (hit !== undefined) return hit;
+    }
+  }
+  return undefined;
+}
+
+// ---- app ----------------------------------------------------------------------
+const app = express();
+
+// The API stub — intercepts every /api/gds/*, /api/bongos/*, /api/bongos/v1/*
+// request BEFORE mountInternalSurfaces can reach the real routes (which would
+// touch Postgres — the harness is DB-less by design). A plain function
+// middleware, not a path mount: regex-mount semantics differ across express
+// majors and a silent non-match here means a pg crash.
+app.use((req, res, next) => {
+  const m = req.path.match(/^\/api\/(?:gds|bongos)(?:\/v1)?\/(.+)$/);
+  if (!m) return next();
+  const apiPath = m[1].replace(/\/$/, '');
+
+  // SSE live channel: emit one nudge (so "live refresh" paths run once), then
+  // keep-alive comments. Pages treat this exactly like prod's stream.
+  if (apiPath === 'live') {
+    res.set({ 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+    res.flushHeaders();
+    setTimeout(() => res.write('event: nudge\ndata: {}\n\n'), 1200);
+    const tick = setInterval(() => res.write(': keep-alive\n\n'), 25000);
+    req.on('close', () => clearInterval(tick));
+    return;
+  }
+
+  if (req.method !== 'GET') {
+    return res.status(501).json({ error: { code: 'preview_readonly', message: 'the preview harness serves fixtures; writes are not wired' } });
+  }
+  const fix = fixtureFor(apiPath);
+  if (fix === undefined) {
+    console.log(`  no fixture: ${apiPath}  (add scripts/hall-preview/fixtures/${apiPath.replace(/\//g, '__')}.json)`);
+    return res.status(404).json({ error: { code: 'no_fixture', message: apiPath } });
+  }
+  res.json(EMPTY ? emptied(fix) : fix);
+});
+
+// The hall pages, pre-auth-gate, through the real seams: boot-time stamped
+// (?v= content hashes), {{token}}-replaced, __BRANDING__/__MODULES__ injected,
+// theme markup appended — byte-for-byte what prod serves after its gates.
+const stamped = buildStampedHtml(PUB, '/builders/');
+const mods = JSON.parse(JSON.stringify(clientModules()));
+for (const key of MODULES_OFF) {
+  if (mods.enabled && key in mods.enabled) mods.enabled[key] = false;
+  else (mods.enabled = mods.enabled || {})[key] = false;
+}
+for (const key of MODULES_ON) {
+  (mods.enabled = mods.enabled || {})[key] = true;
+}
+
+function sendPage(res, name) {
+  const html = stamped[name];
+  if (!html) return false;
+  res.type('html').send(injectBrandingGlobal(html, undefined, mods));
+  return true;
+}
+
+app.get('/', (req, res, next) => { if (!sendPage(res, 'index.html')) next(); });
+app.get(/^\/task\/\d+$/, (req, res, next) => { if (!sendPage(res, 'task.html')) next(); });
+app.get(/^\/([a-z-]+)$/, (req, res, next) => {
+  if (!sendPage(res, `${req.params[0]}.html`)) next();
+});
+
+// Everything else — /builders/*.css|js assets, /lib/bongos-client.js, diagram
+// PNGs — falls through to the real internal-surface mounting. Our handlers
+// above registered first, so the hall's auth gates in there never fire for
+// the page routes we already served.
+mountInternalSurfaces(app);
+
+// Loopback only — this is a pre-auth preview of hall pages with fixture data;
+// *.localhost resolves to 127.0.0.1 so nothing else is needed.
+app.listen(PORT, '127.0.0.1', () => {
+  console.log(`hall-preview: http://builders.localhost:${PORT}/`);
+  console.log(`  brand: ${BRAND_FILE}${EMPTY ? '  (EMPTY fixtures)' : ''}${MODULES_OFF.length ? `  modules off: ${MODULES_OFF.join(',')}` : ''}`);
+  console.log('  pages:', Object.keys(stamped).map((f) => f.replace(/\.html$/, '')).sort().join(' '));
+});

package/scripts/migrate.sh

@@ -12,18 +12,43 @@ set -euo pipefail
 # alongside the instance, so both resolve to the SAME dir and this is byte-identical to the
 # old `cd "$(dirname "$0")/.."`. Once the core installs from node_modules, resolveCoreRoot()
 # points into the package (core migrations + src/) while resolveInstanceRoot() stays the host
-# repo (env → bongos.config → cwd). We resolve from the SCRIPT-relative dir so the result does
-# not depend on the caller's cwd (preserving the old script-relative behavior), and fail open to
-# that dir if node is unavailable so a deploy never breaks.
+# repo (env → bongos.config → cwd).
+#
+# CORE root is resolved SCRIPT-relative (the package's own files sit next to this script), so it
+# never depends on the caller's cwd. The INSTANCE root is the OPPOSITE: it MUST come from where
+# migrate was INVOKED. `npm run migrate` from the instance sets INIT_CWD (and $PWD) to the
+# instance dir, where bongos.config.json lives. Resolving the instance root script-relative would
+# `cd` into the core PACKAGE first — whose dir has no bongos.config.json — so with no
+# OTB_INSTANCE_ROOT env it falls back to the package dir as the "instance" and reads the core's
+# VANILLA module config, SILENTLY skipping every host + flag-gated module migration (R89 rehearsal
+# F6, task 2180: literal `npm run migrate` applied 115 rows and created no game schema; from the
+# instance cwd it applied 121). So resolve the instance root from the invocation cwd, preferring an
+# EXPLICIT pointer (OTB_INSTANCE_ROOT env, else the invocation cwd's bongos.config.json).
+# resolveInstanceRootExplicit() returns '' (NOT process.cwd()) when neither is present, so we fall
+# back to the script-relative DEFAULT_ROOT — the monolith case (cwd==core==instance), byte-identical
+# to the old behavior, and a stray cwd can never masquerade as the instance. Fail open to
+# DEFAULT_ROOT if node is unavailable so a deploy never breaks.
+INVOKE_CWD="${INIT_CWD:-$PWD}"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 DEFAULT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 CORE_ROOT="$(cd "$DEFAULT_ROOT" && node -e "process.stdout.write(require('./src/instance-config').resolveCoreRoot())" 2>/dev/null || echo "$DEFAULT_ROOT")"
-INSTANCE_ROOT="$(cd "$DEFAULT_ROOT" && node -e "process.stdout.write(require('./src/instance-config').resolveInstanceRoot())" 2>/dev/null || echo "$DEFAULT_ROOT")"
+INSTANCE_ROOT="$(cd "$INVOKE_CWD" && node -e "process.stdout.write(require('$DEFAULT_ROOT/src/instance-config').resolveInstanceRootExplicit() || '')" 2>/dev/null || true)"
+INSTANCE_ROOT="${INSTANCE_ROOT:-$DEFAULT_ROOT}"
 # Run from the instance root so instance-relative paths resolve (the post-deploy art check below)
 # AND so the enabledModules() read finds the instance's config/modules.json (resolveInstanceRoot
 # falls back to cwd).
 cd "$INSTANCE_ROOT"
 
+# Test/ops seam (task 2180): print the resolved roots and exit BEFORE any DB work, so a DB-free
+# unit test (tests/migrate_root_resolution.mjs) can assert the INSTANCE root resolves from the
+# invocation cwd (a consumer's bongos.config.json), not script-relative into the core package —
+# the F6 regression. Also handy in the field: `npm run migrate -- --print-roots` shows what
+# migrate sees.
+if [ "${1:-}" = "--print-roots" ]; then
+  printf 'INVOKE_CWD=%s\nCORE_ROOT=%s\nINSTANCE_ROOT=%s\n' "$INVOKE_CWD" "$CORE_ROOT" "$INSTANCE_ROOT"
+  exit 0
+fi
+
 DB="${PGDATABASE:-amazonprimea}"
 
 # --- Instance-seed policy (task 1704 / ADR 0105) --------------------------

package/src/bongos/auth.js

@@ -230,7 +230,20 @@ async function startDeviceFlow() {
   // 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}` : ''}`);
+    // 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).');

package/src/bongos/optimizer.js

@@ -53,10 +53,45 @@ async function optimizeSession({ builderId, mode, timeBudgetMin, maxParallel })
   // tasks_session_fit (derived fits_session_modes[] + credits_per_minute).
   // Also exclude tasks this builder already has an active claim on, mirroring
   // listClaimableTasks in db.js.
+  // task 2181 (incident, blocker 74): the view bodies (migration core_190) are
+  // inlined so this query takes only ACCESS SHARE on base tables — a detached
+  // backend queued an ACCESS EXCLUSIVE DDL on the views and parked every view
+  // SELECT behind it. Plan-identical (Postgres inlines simple views); change in
+  // lockstep with the views / listClaimableTasks if a migration alters them.
   const { rows } = await pool.query(
     `SELECT ct.*, sf.fits_session_modes, sf.credits_per_minute
-       FROM claimable_tasks ct
-       JOIN tasks_session_fit sf ON sf.id = ct.id
+       FROM (
+         SELECT t.*, pms_calibrated_minutes(t.est_minutes, t.kind) AS est_minutes_calibrated
+           FROM tasks t
+          WHERE t.status = 'ready'
+            AND t.title NOT LIKE '\\_\\_smoke\\_\\_%' ESCAPE '\\'
+            AND NOT EXISTS (SELECT 1 FROM task_blockers tb WHERE tb.task_id = t.id)
+            AND NOT EXISTS (
+              SELECT 1 FROM claims c
+                JOIN tasks t2 ON t2.id = c.task_id
+               WHERE c.released_at IS NULL
+                 AND t2.touches && t.touches
+            )
+       ) ct
+       JOIN (
+         SELECT t.id,
+           CASE
+             WHEN t.automation_tag = 'overnight-safe' AND COALESCE(t.manual_degree, 5) <= 2
+                  AND NOT EXISTS (SELECT 1 FROM task_blockers tb WHERE tb.task_id = t.id)
+               THEN ARRAY['autonomous','check-in','active']
+             WHEN t.automation_tag = 'live-only' OR COALESCE(t.manual_degree, 5) >= 4
+               THEN ARRAY['active']
+             ELSE ARRAY['check-in','active']
+           END AS fits_session_modes,
+           CASE
+             WHEN t.credits_reward > 0
+              AND pms_calibrated_minutes(t.est_minutes, t.kind) IS NOT NULL
+              AND pms_calibrated_minutes(t.est_minutes, t.kind) > 0
+             THEN ROUND(t.credits_reward::numeric / pms_calibrated_minutes(t.est_minutes, t.kind), 3)
+             ELSE NULL
+           END AS credits_per_minute
+           FROM tasks t
+       ) sf ON sf.id = ct.id
       WHERE $1 = ANY(sf.fits_session_modes)
         AND NOT EXISTS (
           SELECT 1 FROM claims c

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/module-api.js

@@ -188,8 +188,19 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         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.1'; // see the changelog above — 1.17.1 republishes the artifact with the task-2121 agent-doc stub (no doorway change) (task 2124)
+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');