@bongos/core 1.17.2 → 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/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/tests/criterion_suggest.mjs

@@ -0,0 +1,106 @@
+// tests/criterion_suggest.mjs
+//
+// Unit tests for suggestCriteria() — the pure criterion RECOMMENDER
+// (modules/lifecycle/criterion-suggest.js, task 2165). Given a goal's criteria
+// and a candidate task's title/description, it ranks the criteria by weighted
+// lexical overlap so task-create can suggest which done-when criterion to link
+// (the author confirms — nothing is auto-linked). No DB, so it runs in the
+// DB-free suite.
+//
+// Run:  node tests/criterion_suggest.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { suggestCriteria, tokenize } = require('../modules/lifecycle/criterion-suggest.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+const crit = (id, criterion_id, criterion_md, satisfied = false) =>
+  ({ id, criterion_id, criterion_md, satisfied });
+
+// A small, realistic goal-25-flavoured criterion set.
+const CRITERIA = [
+  crit(138, 'bx-hall', 'Core task actions work in the builders hall without invoking the LLM.'),
+  crit(139, 'bx-identity', 'A builder can view and edit their own profile and read a leaderboard.'),
+  crit(140, 'bx-onramp', 'Newcomers never dead-end: auth and re-auth are browser-clickable.'),
+  crit(141, 'bx-box', 'A builder dev box and sandbox is robust: uncommitted work is not lost.'),
+];
+
+test('ranks the most lexically-relevant criterion first', () => {
+  const out = suggestCriteria(CRITERIA, {
+    title: 'In-hall confirm button for criteria',
+    description: 'Let builders confirm a criterion in the hall without the LLM.',
+  });
+  assert.ok(out.length >= 1, 'expected at least one suggestion');
+  assert.equal(out[0].criterion_id, 'bx-hall', `expected bx-hall first, got ${out[0].criterion_id}`);
+  assert.ok(out[0].matched_terms.includes('hall'), 'should report the matched term');
+});
+
+test('title terms weigh more than description terms', () => {
+  // "profile" only in the title → should beat a body-only "hall" match.
+  const out = suggestCriteria(CRITERIA, {
+    title: 'Edit your profile',
+    description: 'Shown in the hall.',
+  });
+  assert.equal(out[0].criterion_id, 'bx-identity', `title term should win, got ${out[0].criterion_id}`);
+  const identity = out.find((c) => c.criterion_id === 'bx-identity');
+  const hall = out.find((c) => c.criterion_id === 'bx-hall');
+  assert.ok(hall === undefined || identity.score > hall.score, 'title match must outscore body match');
+});
+
+test('returns [] when nothing overlaps (no low-confidence noise)', () => {
+  const out = suggestCriteria(CRITERIA, {
+    title: 'Migrate the Postgres backup vendor to object storage',
+    description: 'Nightly encrypted dumps to a bucket.',
+  });
+  assert.deepEqual(out, [], 'no shared vocabulary → no suggestion');
+});
+
+test('never suggests an already-satisfied criterion', () => {
+  const satisfiedHall = [crit(138, 'bx-hall', 'Core task actions work in the builders hall.', true)];
+  const out = suggestCriteria(satisfiedHall, { title: 'hall task actions' });
+  assert.deepEqual(out, [], 'satisfied criteria are excluded');
+});
+
+test('respects the limit and is stable (id tiebreak on equal scores)', () => {
+  const tied = [
+    crit(20, 'b', 'builder profile'),
+    crit(10, 'a', 'builder profile'),
+    crit(30, 'c', 'builder profile'),
+  ];
+  const out = suggestCriteria(tied, { title: 'builder profile' }, { limit: 2 });
+  assert.equal(out.length, 2, 'limit caps the result');
+  assert.deepEqual(out.map((c) => c.id), [10, 20], 'equal scores break ties by ascending id');
+});
+
+test('includeZero returns all unsatisfied criteria in score order', () => {
+  const out = suggestCriteria(CRITERIA, { title: 'profile' }, { includeZero: true, limit: 10 });
+  assert.equal(out.length, 4, 'includeZero keeps the zero-overlap criteria');
+  assert.equal(out[0].criterion_id, 'bx-identity', 'best match still leads');
+});
+
+test('empty / malformed inputs are safe', () => {
+  assert.deepEqual(suggestCriteria([], { title: 'x' }), []);
+  assert.deepEqual(suggestCriteria(null, { title: 'x' }), []);
+  assert.deepEqual(suggestCriteria(CRITERIA, {}), [], 'no candidate terms → no suggestion');
+});
+
+test('tokenize drops stopwords, short tokens, and singularizes', () => {
+  const toks = tokenize('The builders can edit profiles and tasks.');
+  assert.ok(!toks.includes('the'), 'stopword dropped');
+  assert.ok(!toks.includes('can'), 'stopword dropped');
+  assert.ok(toks.includes('builder'), 'builders → builder');
+  assert.ok(toks.includes('profile'), 'profiles → profile');
+  assert.ok(toks.includes('task'), 'tasks → task');
+});
+
+console.log('');
+console.log(`criterion-suggest recommender tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/migrate_root_resolution.mjs

@@ -0,0 +1,97 @@
+// tests/migrate_root_resolution.mjs
+//
+// R89 rehearsal F6 (task 2180): after the core→consumer split, scripts/migrate.sh
+// must resolve the INSTANCE root from the INVOCATION cwd (OTB_INSTANCE_ROOT env,
+// else the invocation cwd's bongos.config.json), NOT script-relative into the
+// installed @bongos/core package. The old script-relative resolve `cd`'d into the
+// package dir first — which has no bongos.config.json — so it silently picked the
+// package as the "instance" and read the core's VANILLA module config, skipping
+// every host + flag-gated module migration (rehearsal: `npm run migrate` applied
+// 115 rows and created NO game schema; from the instance cwd it applied 121).
+//
+// This exercises migrate.sh's `--print-roots` seam (DB-free: it prints the resolved
+// roots and exits before any DB work), so no Postgres is needed. CORE_ROOT must stay
+// script-relative in every case; INSTANCE_ROOT must follow the invocation cwd.
+//
+// Run:  node tests/migrate_root_resolution.mjs
+
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const MIGRATE = path.join(REPO_ROOT, 'scripts', 'migrate.sh');
+const REPO_REAL = realpathSync(REPO_ROOT);
+
+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}`); }
+}
+
+// Run `migrate.sh --print-roots` with a controlled cwd + INIT_CWD, and an env that
+// carries NO *_INSTANCE_ROOT override, so we test cwd-based resolution alone.
+function printRoots({ cwd, initCwd } = {}) {
+  const env = { ...process.env };
+  for (const k of Object.keys(env)) if (/_INSTANCE_ROOT$/.test(k)) delete env[k];
+  delete env.INIT_CWD;
+  if (initCwd) env.INIT_CWD = initCwd;
+  const out = execFileSync('bash', [MIGRATE, '--print-roots'], { cwd, env, encoding: 'utf8' });
+  const roots = {};
+  for (const line of out.split('\n')) {
+    const m = /^(INVOKE_CWD|CORE_ROOT|INSTANCE_ROOT)=(.*)$/.exec(line);
+    if (m) roots[m[1]] = m[2];
+  }
+  return roots;
+}
+
+// A synthetic consumer: a dir with a bongos.config.json pointing at itself, exactly
+// as the post-split amazonprimea repo carries (bongos.config.json { instanceRoot: "." }).
+function makeConsumer() {
+  const dir = realpathSync(mkdtempSync(path.join(tmpdir(), 'r89-consumer-')));
+  writeFileSync(path.join(dir, 'bongos.config.json'), JSON.stringify({ instanceRoot: '.' }));
+  return dir;
+}
+// A dir with NO bongos.config.json — stands in for the monolith / a stray cwd.
+function makeBare() {
+  return realpathSync(mkdtempSync(path.join(tmpdir(), 'r89-bare-')));
+}
+
+// ---- the F6 regression: instance root follows the invocation cwd ----------
+t('consumer run from its own dir: INSTANCE_ROOT resolves to the consumer (not the core)', () => {
+  const consumer = makeConsumer();
+  const r = printRoots({ cwd: consumer });
+  assert.equal(realpathSync(r.INSTANCE_ROOT), consumer, 'instance root must be the consumer dir');
+  assert.notEqual(realpathSync(r.INSTANCE_ROOT), REPO_REAL, 'must NOT fall back to the script-relative core root');
+});
+
+t('consumer via npm from elsewhere: INIT_CWD wins over the spawn cwd', () => {
+  const consumer = makeConsumer();
+  const elsewhere = makeBare();
+  // npm sets INIT_CWD to where `npm run` was invoked (the instance), even if a
+  // wrapper cd'd somewhere else first.
+  const r = printRoots({ cwd: elsewhere, initCwd: consumer });
+  assert.equal(realpathSync(r.INSTANCE_ROOT), consumer, 'INIT_CWD (the instance) must win');
+});
+
+// ---- the monolith / no-pointer fallback stays script-relative -------------
+t('no bongos.config + no env: INSTANCE_ROOT falls back to the script-relative repo root', () => {
+  const bare = makeBare();
+  const r = printRoots({ cwd: bare });
+  assert.equal(realpathSync(r.INSTANCE_ROOT), REPO_REAL, 'a stray cwd must NOT masquerade as the instance');
+});
+
+// ---- CORE root is always script-relative, regardless of cwd ---------------
+t('CORE_ROOT is always the script-relative repo root, independent of the invocation cwd', () => {
+  const consumer = makeConsumer();
+  const bare = makeBare();
+  assert.equal(realpathSync(printRoots({ cwd: consumer }).CORE_ROOT), REPO_REAL);
+  assert.equal(realpathSync(printRoots({ cwd: bare }).CORE_ROOT), REPO_REAL);
+});
+
+console.log(`\nmigrate_root_resolution: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);