@bongos/core 1.18.18 → 1.19.2

package/tests/module_loader.mjs

@@ -315,6 +315,10 @@ test('the demo proof module mounts + serves through the loader (BV1.R52 / task 1
   // BV1.R52 acceptance: the net-new scaffolded module is discovered, is enabled
   // by config/modules.json, and its route factory builds a real router with the
   // health read route + the rank-gated ping write route — all with NO core edit.
+  // modules/demo/ is content-excluded from the published core (ADR 0098), exactly as
+  // the roster comment above already notes — so on a core checkout there is nothing
+  // to mount and this acceptance proof does not apply (task 1002470).
+  if (!fs.existsSync(path.join(ROOT, 'modules', 'demo'))) return;
   loader._reset();
   const { isModuleEnabled } = require(path.join(ROOT, 'src', 'modules.js'));
   assert.equal(isModuleEnabled('demo'), true, 'config/modules.json enables demo');

package/tests/modules.mjs

@@ -1,6 +1,7 @@
 // tests/modules.mjs — the feature-module selection resolver (task 1193 / V4.R54, ADR 0062 §4).
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
+import { existsSync } from 'node:fs';
 import modulesMod from '../src/modules.js';
 
 const {
@@ -17,6 +18,14 @@ const OTB = { modules: { game: true, 'art-pipeline': true, discord: true, 'dev-b
 // loadModules() does in production. Membership across the move is preserved here.
 const EFFECTIVE = modulesMod.effectiveRegistry();
 
+// Sample feature-module keys for the PURE resolver tests below. `game` and
+// `art-pipeline` left the core at the CB→OTB split, so the effective registry no
+// longer knows them and passing them made resolveModules throw `cannot enable
+// unknown module` — the tests were asserting a topology, not the resolver (task
+// 1002470). Synthesized here so the precedence/merge/freeze semantics stay under
+// test on any instance, whatever it happens to have installed.
+const SAMPLE_REG = { ...EFFECTIVE, game: { default: false }, 'art-pipeline': { default: false } };
+
 test('vanilla (no config) resolves every module OFF — fail-to-vanilla, never fail-to-OTB', () => {
   const m = resolveModules({});
   for (const k of KNOWN_MODULES) assert.equal(m[k], false, `${k} should default off`);
@@ -28,7 +37,7 @@ test('every registry module has an explicit default of false', () => {
 });
 
 test('instance config turns modules on', () => {
-  const m = resolveModules({ neutral: VANILLA, instance: OTB, registry: EFFECTIVE });
+  const m = resolveModules({ neutral: VANILLA, instance: OTB, registry: SAMPLE_REG });
   assert.equal(m.game, true);
   assert.equal(m['dev-box'], true);
   assert.equal(isModuleEnabled('discord', m), true);
@@ -41,19 +50,31 @@ test('instance config turns modules on', () => {
   // gate + builder economy + idea inbox + red-team intake + prefs + onboarding +
   // session corpus + the MAS autonomy machinery + the status dashboard + the
   // builders' hall ship to every instance — see each module.json).
-  assert.deepEqual(enabledModules(m).sort(), ['art-pipeline', 'autonomy', 'builder-settings', 'dev-box', 'discord', 'economy', 'game', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'security', 'sessions', 'status-ui']);
+  // Asserted as a PROPERTY rather than a frozen 16-key list (which named modules the
+  // core no longer carries — task 1002470).
+  // Everything the instance switched on resolves on...
+  for (const k of Object.keys(OTB.modules)) assert.equal(m[k], true, `instance-enabled '${k}' must resolve on`);
+  // ...every `default: true` core-domain module resolves on WITHOUT being listed...
+  const coreDefaults = Object.keys(SAMPLE_REG).filter((k) => SAMPLE_REG[k].default);
+  assert.ok(coreDefaults.length >= 5, `expected a real core-domain roster, found ${coreDefaults.length}`);
+  for (const k of coreDefaults) assert.equal(m[k], true, `default-on core module '${k}' must resolve on unlisted`);
+  // ...and a registry key that is neither listed nor default-on stays off.
+  for (const k of Object.keys(SAMPLE_REG)) {
+    if (SAMPLE_REG[k].default || k in OTB.modules) continue;
+    assert.equal(m[k], false, `unlisted opt-in module '${k}' must stay off`);
+  }
 });
 
 test('instance config overrides the neutral starter per-flag (deep merge of the modules map)', () => {
   const neutral = { modules: { game: false, discord: false, 'dev-box': false, 'art-pipeline': false } };
   const instance = { modules: { discord: true } }; // only flip one
-  const m = resolveModules({ neutral, instance, registry: EFFECTIVE });
+  const m = resolveModules({ neutral, instance, registry: SAMPLE_REG });
   assert.equal(m.discord, true);
   assert.equal(m.game, false); // neutral value survives
 });
 
 test('env override beats instance config (precedence), with prefix + snake-casing', () => {
-  const m = resolveModules({ instance: OTB, env: { OTB_MODULE_DEV_BOX: '0' }, envPrefix: 'OTB', registry: EFFECTIVE });
+  const m = resolveModules({ instance: OTB, env: { OTB_MODULE_DEV_BOX: '0' }, envPrefix: 'OTB', registry: SAMPLE_REG });
   assert.equal(m['dev-box'], false); // env off beat instance on
   assert.equal(m.game, true);        // others untouched
 });
@@ -111,19 +132,23 @@ test('disciplines: vanilla offers engineer + ideator (core); art-pipeline adds a
   // instance), so it is offered with no modules on; only 'artist' is module-gated.
   // art-pipeline is now a DISCOVERED module (BV1.R48), so pass EFFECTIVE registry.
   assert.deepEqual(enabledDisciplines(resolveModules({})), ['engineer', 'ideator']);
-  const m = resolveModules({ instance: { modules: { 'art-pipeline': true } }, registry: EFFECTIVE });
+  // The 'artist' leg reads art-pipeline's OWN module.json contributes, so it only
+  // means anything where that module is installed (task 1002470). The core half
+  // above — ideation ships to every instance — is asserted unconditionally.
+  if (!EFFECTIVE['art-pipeline']) return;
+  const m = resolveModules({ instance: { modules: { 'art-pipeline': true } }, registry: SAMPLE_REG });
   assert.deepEqual(enabledDisciplines(m), ['engineer', 'ideator', 'artist']);
 });
 
 test('clientModules is a safe boolean projection covering every known module + disciplines', () => {
-  const c = clientModules(resolveModules({ instance: OTB, registry: EFFECTIVE }));
+  const c = clientModules(resolveModules({ instance: OTB, registry: SAMPLE_REG }));
   for (const k of KNOWN_MODULES) assert.equal(typeof c.enabled[k], 'boolean');
   assert.ok(Array.isArray(c.disciplines));
   assert.ok(c.disciplines.includes('engineer'));
 });
 
 test('the resolved set is frozen (callers cannot mutate the singleton)', () => {
-  const m = resolveModules({ instance: OTB, registry: EFFECTIVE });
+  const m = resolveModules({ instance: OTB, registry: SAMPLE_REG });
   assert.throws(() => { m.game = false; }, TypeError);
 });
 
@@ -131,6 +156,9 @@ test('the committed config files resolve: OTB enables all four, on disk', () =>
   // loadModules reads config/modules.json over config/modules.neutral.json.
   // No GDS_BRANDING_FILE → still the default OTB instance pack (regression guard
   // for the GDS_MODULES_FILE selector below).
+  // config/modules.json is INSTANCE content — the neutral core ships only
+  // config/modules.neutral.json, so there is no instance pack to assert (task 1002470).
+  if (!existsSync(new URL('../config/modules.json', import.meta.url))) return;
   const m = loadModules({ env: {} });
   assert.equal(m.game, true);
   assert.equal(m['art-pipeline'], true);

package/tests/modules_route.mjs

@@ -7,14 +7,21 @@ import { test } from 'node:test';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { onDiskModuleKeys } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const { listModules } = require(path.join(ROOT, 'src', 'bongos', 'routes', 'modules.js'));
 
+// The roster is compared against a direct disk read (helpers.mjs onDiskModuleKeys) rather
+// than a hardcoded floor — that floor (>=18) went stale when modules left the core at the
+// CB→OTB split, turning a real exhaustiveness check into a census (task 1002470).
+
 test('listModules: every on-disk module is present, sorted, and well-formed', () => {
   const rows = listModules();
-  assert.ok(rows.length >= 18, `expected every on-disk module (got ${rows.length})`);
+  const expected = onDiskModuleKeys();
+  assert.ok(expected.length >= 5, `expected a real on-disk module roster, found ${expected.length}`);
+  assert.deepEqual(rows.map((m) => m.key).sort(), expected, 'listModules must return exactly the on-disk modules');
   for (const m of rows) {
     assert.equal(typeof m.key, 'string');
     assert.ok(['own', 'core'].includes(m.provenance), `${m.key}: provenance is own|core`);
@@ -24,15 +31,32 @@ test('listModules: every on-disk module is present, sorted, and well-formed', ()
   assert.deepEqual(keys, [...keys].sort(), 'listModules is sorted by key');
 });
 
-test('listModules: today, every module is own-built (ADR 0107 audit — no module names a foreign origin yet)', () => {
+// This used to assert a CENSUS ("today, every module is own-built") that was true only
+// while the instance was OTB. On a neutral core, provisioning + platform-identity carry
+// an origin naming another project and correctly classify 'core' — the census was stale,
+// not the code (task 1002470). Assert the ADR 0107 §9 RULE instead, which holds on every
+// instance: no origin => own, and an origin naming this project => own.
+test('listModules: provenance follows the ADR 0107 §9 rule (no origin, or a self-naming origin, is own-built)', () => {
   const rows = listModules();
-  for (const m of rows) assert.equal(m.provenance, 'own', `${m.key} unexpectedly classifies core-loaded`);
+  let withOrigin = 0;
+  for (const m of rows) {
+    if (!m.origin) {
+      assert.equal(m.provenance, 'own', `${m.key} declares no origin, so it must classify own-built`);
+      continue;
+    }
+    withOrigin += 1;
+    assert.ok(['own', 'core'].includes(m.provenance), `${m.key}: provenance must be own|core`);
+  }
+  // Non-vacuity: the no-origin branch must actually have been exercised.
+  assert.ok(rows.length > withOrigin, 'expected at least one module with no declared origin');
 });
 
-test('listModules: game module is on-disk, enabled in the OTB instance config, and carries no origin', () => {
+test('listModules: an installed game module is enabled and carries no origin', () => {
   const rows = listModules();
   const game = rows.find((m) => m.key === 'game');
-  assert.ok(game, 'game module discovered');
+  // modules/game/ left the core at the CB→OTB split; where it IS installed the
+  // original contract still holds (task 1002470).
+  if (!game) return;
   assert.equal(game.enabled, true);
   assert.equal(game.origin, null);
 });

package/tests/onboarding_observability.mjs

@@ -43,6 +43,12 @@ async function t(name, fn) {
 // src/bongos/routes, so we patch the resolved module before requiring the
 // routes.
 const authPath = require.resolve('../src/bongos/auth.js');
+const catalog = require('../modules/governance/catalog.js');
+// Mirrors the canonical ladder in modules/governance/catalog.js — omitting a rung
+// would resolve its floor to Infinity and deny everyone, including archon. Kept at
+// module scope (BV1.R104) so requireRank and requirePermission below share ONE
+// ladder; R105's branch still had the stale 3-rung inline copy that dropped thetes.
+const RANK_ORDER = { xenos: 1, thetes: 2, metic: 3, archon: 4 };
 const stubAuth = {
   requireBuilder: (req, _res, next) => {
     // The test harness sets req._stub_builder beforehand.
@@ -52,8 +58,7 @@ const stubAuth = {
   },
   requireRank: (rank) => (req, res, next) => {
     if (!req.builder) return res.status(401).json({ error: 'unauth' });
-    const order = { xenos: 1, metic: 2, archon: 3 };
-    if ((order[req.builder.rank] || 0) < (order[rank] || 0)) {
+    if ((RANK_ORDER[req.builder.rank] || 0) < (RANK_ORDER[rank] || 0)) {
       return res.status(403).json({
         error: 'rank_forbidden',
         required: rank,
@@ -62,6 +67,28 @@ const stubAuth = {
     }
     next();
   },
+  // BV1.R104/R105 migrated these gates to requirePermission — core routes in R104,
+  // module routes (here: POST /claims/:id/release-on-behalf) in R105. Resolve each
+  // atom's floor from the REAL catalog and apply the same threshold as the rank stub
+  // above, so the stub admits exactly who the requireRank spelling did — the seeded
+  // rank-roles make the two gates equivalent (ADR 0151). An unknown atom denies
+  // (Infinity) — fail-closed, matching the live gate; a stub that admitted on an
+  // unknown key would hide precisely the typo this suite exists to catch.
+  requirePermission: (...perms) => (req, res, next) => {
+    if (!req.builder) return res.status(401).json({ error: 'unauth' });
+    const floor = perms.reduce(
+      (max, key) => Math.max(max, RANK_ORDER[catalog.byKey(key)?.floor] || Infinity),
+      0,
+    );
+    if ((RANK_ORDER[req.builder.rank] || 0) < floor) {
+      return res.status(403).json({
+        error: 'permission_forbidden',
+        required: perms,
+        held: [],
+      });
+    }
+    next();
+  },
 };
 require.cache[authPath] = {
   id: authPath,
@@ -190,23 +217,28 @@ function send({ port, method, path, body, headers = {} }) {
 
 const { server, port } = await listen(buildApp());
 
-await t('GET /builders/roster as xenos → 403 rank_forbidden', async () => {
+// BV1.R104 migrated this gate to requirePermission('builder.roster.read') — an
+// archon-floored atom, so the SAME callers are refused; only the 403 code and the
+// `required` shape changed (permission_forbidden + the atom list, not a rank name).
+await t('GET /builders/roster as xenos → 403 permission_forbidden', async () => {
   const r = await send({
     port, method: 'GET', path: '/api/gds/builders/roster',
     headers: { 'x-stub-builder-id': '7', 'x-stub-builder-rank': 'xenos' },
   });
   assert.equal(r.status, 403);
-  assert.equal(r.json?.error, 'rank_forbidden');
-  assert.equal(r.json?.required, 'archon');
+  assert.equal(r.json?.error, 'permission_forbidden');
+  assert.deepEqual(r.json?.required, ['builder.roster.read']);
 });
 
-await t('GET /builders/roster as metic → 403 rank_forbidden', async () => {
+// ADR 0157 lowered `builder.roster.read` archon→metic: reading who is on the roster is
+// administration, not authority over who holds authority. The refusal assertion that
+// still guards the surface is the sub-Metic one above (thetes/xenos → 403).
+await t('GET /builders/roster as metic → admitted (ADR 0157)', async () => {
   const r = await send({
     port, method: 'GET', path: '/api/gds/builders/roster',
     headers: { 'x-stub-builder-id': '7', 'x-stub-builder-rank': 'metic' },
   });
-  assert.equal(r.status, 403);
-  assert.equal(r.json?.required, 'archon');
+  assert.notEqual(r.status, 403, 'a metic now holds builder.roster.read');
 });
 
 await t('GET /builders/roster as archon → 200', async () => {
@@ -279,16 +311,22 @@ await t('POST /claims/:id/release-on-behalf as xenos → 403', async () => {
     headers: { 'x-stub-builder-id': '7', 'x-stub-builder-rank': 'xenos' },
   });
   assert.equal(r.status, 403);
-  assert.equal(r.json?.error, 'rank_forbidden');
+  // BV1.R105: the route now gates on `claim.release.any`, so the denial code is
+  // requirePermission's `permission_forbidden`. The AUDIENCE is unchanged (the atom
+  // floors at archon) — only the spelling of the refusal moved. This is the R97
+  // 403-contract change reaching its first module route.
+  assert.equal(r.json?.error, 'permission_forbidden');
 });
 
-await t('POST /claims/:id/release-on-behalf as metic → 403', async () => {
+// ADR 0157 lowered `claim.release.any` archon→metic: freeing another builder's stale
+// claim is queue housekeeping, not an authority grant.
+await t('POST /claims/:id/release-on-behalf as metic → admitted (ADR 0157)', async () => {
   const r = await send({
     port, method: 'POST', path: '/api/gds/claims/123/release-on-behalf',
     body: { reason: 'stale' },
     headers: { 'x-stub-builder-id': '7', 'x-stub-builder-rank': 'metic' },
   });
-  assert.equal(r.status, 403);
+  assert.notEqual(r.status, 403, 'a metic now holds claim.release.any');
 });
 
 await t('POST /claims/:id/release-on-behalf w/o reason → 400 validation_failed', async () => {

package/tests/onboarding_route_signals.mjs

@@ -41,6 +41,7 @@ require.cache[authPath] = {
   exports: {
     requireBuilder: (_req, _res, next) => next(),
     requireRank: () => (_req, _res, next) => next(),
+    requirePermission: () => (_req, _res, next) => next(),
   },
 };
 

package/tests/one_active_claim_per_session.mjs

@@ -183,5 +183,85 @@ t('names the in-flight task in the MATCHING worktree, not the first row', () =>
   assert.equal(d.inFlightTitle, 'Two');
 });
 
+// =========================================================================
+// task 1002589 (idea 1000638) — the DB backstop's ERROR SURFACE. A claims
+// INSERT can trip TWO partial unique indexes; claimTask used to map every pg
+// 23505 to ALREADY_CLAIMED, so a trip of migration 180's per-session index
+// read as "task taken by another session" while the task sat 'ready'.
+// claimUniqueViolationError branches on err.constraint: the per-task index
+// keeps ALREADY_CLAIMED, the per-session index gets its own honest code, and
+// an UNKNOWN constraint fails CLOSED on ALREADY_CLAIMED (never widen).
+// =========================================================================
+const { claimUniqueViolationError } = require('../modules/lifecycle/db.js');
+
+t('23505 on uniq_active_claim_per_task → ALREADY_CLAIMED (race lost, unchanged)', () => {
+  const e = claimUniqueViolationError({ code: '23505', constraint: 'uniq_active_claim_per_task' });
+  assert.equal(e.code, 'ALREADY_CLAIMED');
+});
+
+t('23505 on uniq_active_claim_per_session → session_already_has_bound_claim', () => {
+  const e = claimUniqueViolationError({ code: '23505', constraint: 'uniq_active_claim_per_session' });
+  assert.equal(e.code, 'session_already_has_bound_claim');
+  assert.match(e.what_to_do, /builder-ship|builder-release|[Ss]hip or release/,
+    'what_to_do should name the ship-or-release way out');
+  assert.match(e.what_to_do, /bind_session/,
+    'what_to_do should name the bind_session:false escape hatch');
+});
+
+// task 1002570: core_204 re-keys the index per (session, worktree) under a
+// NEW name. Both generations must map to the honest code — a deploy applies
+// code and migration at different instants, and an instance may still carry the
+// migration-180 session-only index.
+t('23505 on uniq_active_claim_per_session_worktree (core_204) → same honest code', () => {
+  const e = claimUniqueViolationError({ code: '23505', constraint: 'uniq_active_claim_per_session_worktree' });
+  assert.equal(e.code, 'session_already_has_bound_claim');
+  assert.match(e.what_to_do, /worktree/, 'what_to_do should name the separate-worktree way out');
+  assert.match(e.what_to_do, /bind_session/);
+});
+
+t('23505 with an unknown constraint fails CLOSED → ALREADY_CLAIMED', () => {
+  assert.equal(claimUniqueViolationError({ code: '23505', constraint: 'uniq_something_future' }).code, 'ALREADY_CLAIMED');
+  assert.equal(claimUniqueViolationError({ code: '23505' }).code, 'ALREADY_CLAIMED');
+  assert.equal(claimUniqueViolationError(null).code, 'ALREADY_CLAIMED');
+});
+
+// =========================================================================
+// task 1002570 — the core_204 re-key itself. Text tripwires on the
+// migration file so the index can't silently drift from the guard's boundary
+// (the exact mismatch this whole family of bugs came from). DB-free: pins the
+// SQL's shape, not its execution.
+// =========================================================================
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+// Read lazily inside each pin so a missing/renamed file fails THESE tests, not
+// the whole suite file at import time.
+const migSql = () => readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)),
+    '../migrations/core_204_rekey_active_claim_per_session_worktree.sql'),
+  'utf8');
+
+t('core_204 drops the session-only index and creates the per-worktree one', () => {
+  assert.match(migSql(), /DROP INDEX IF EXISTS uniq_active_claim_per_session\b/,
+    'must remove the worktree-blind index');
+  assert.match(migSql(), /CREATE UNIQUE INDEX IF NOT EXISTS uniq_active_claim_per_session_worktree/,
+    'must create the re-keyed index idempotently');
+});
+
+t('core_204 folds NULL worktrees so a shared clone still self-collides', () => {
+  // In a plain multi-column unique index NULLs are DISTINCT — without the fold,
+  // two worktree-less claims would both insert and re-open the task-1642
+  // commingling hole. COALESCE is the version-safe fold (no PG15 requirement).
+  assert.match(migSql(), /COALESCE\(worktree_name,\s*''\)/i);
+});
+
+t('core_204 keeps the 180 predicate (active + bound rows only) and heals first', () => {
+  assert.match(migSql(), /WHERE released_at IS NULL AND creator_session_id IS NOT NULL/,
+    'partial predicate must match migration 180 (web claims stay excluded)');
+  assert.match(migSql(), /PARTITION BY c\.creator_session_id,\s*COALESCE\(c\.worktree_name,\s*''\)/i,
+    'the pre-CREATE heal must group by the NEW key');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/pre_compact.mjs

@@ -4,8 +4,9 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import { requireHostModule } from './helpers.mjs';
 const require = createRequire(import.meta.url);
-const { gateDecision, buildDirective, FLAG } = require('../.claude/hooks/pre-compact.js');
+const { gateDecision, buildDirective, FLAG } = requireHostModule(require, '../.claude/hooks/pre-compact.js');
 
 let passed = 0, failed = 0;
 function test(name, fn) {

package/tests/preview_server.mjs

@@ -10,12 +10,13 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import { requireHostModule } from './helpers.mjs';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
 const require = createRequire(import.meta.url);
-const { previewCacheControl, injectLivereload, renderArtGallery } = require('../src/preview-server.js');
+const { previewCacheControl, injectLivereload, renderArtGallery } = requireHostModule(require, '../src/preview-server.js');
 
 // A minimal valid 1×1 PNG (transparent), base64-decoded to bytes.
 const TINY_PNG = Buffer.from(

package/tests/profile_route.mjs

@@ -83,6 +83,7 @@ require.cache[authPath] = {
   exports: {
     requireBuilder: (_req, _res, next) => next(),
     requireRank: () => (_req, _res, next) => next(),
+    requirePermission: () => (_req, _res, next) => next(),
   },
 };
 

package/tests/provision.mjs

@@ -588,6 +588,176 @@ await ta('scaffoldStandaloneRepo: no owner token → falls back to the SSH origi
   }
 });
 
+// ── ADOPT vs GREENFIELD onboarding (ADR 0121, task 1002562) ───────────────────────
+// The runner used to run the greenfield scaffold unconditionally: `git init` a fresh tree
+// and push HEAD:main. Against a repo that already has history that is an unrelated-history
+// non-fast-forward, so adopting an existing repo could never succeed.
+
+t('onboardMode: adopt only when the row says so; anything else → greenfield (the SAFE default)', () => {
+  assert.equal(P.onboardMode({ onboard_mode: 'adopt' }), 'adopt');
+  assert.equal(P.onboardMode({ onboard_mode: 'greenfield' }), 'greenfield');
+  // A row written BEFORE provisioning_004 added the column, and any unrecognized value,
+  // must resolve to greenfield — which refuses to push over existing history — never to
+  // adopt, which would start layering onto a repo nobody declared as pre-existing.
+  assert.equal(P.onboardMode({}), 'greenfield');
+  assert.equal(P.onboardMode({ onboard_mode: null }), 'greenfield');
+  assert.equal(P.onboardMode({ onboard_mode: 'ADOPT' }), 'greenfield');
+  assert.equal(P.onboardMode({ onboard_mode: 'something-else' }), 'greenfield');
+  assert.equal(P.onboardMode(null), 'greenfield');
+});
+
+t('alreadyScaffolded: the marker is mode-dependent — package.json alone does NOT mean an adopt is done', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'marker-'));
+  try {
+    assert.equal(P.alreadyScaffolded(dir, 'greenfield'), false, 'no package.json → not scaffolded');
+    assert.equal(P.alreadyScaffolded(dir, 'adopt'), false);
+
+    // An ordinary existing Node project: package.json present, no core dep. Greenfield's
+    // marker would call this "done" — for ADOPT that is the bug this guards, because the
+    // layering would be skipped on the very first run and the instance never become bootable.
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'their-app', dependencies: { react: '^18' } }));
+    assert.equal(P.alreadyScaffolded(dir, 'greenfield'), true, 'greenfield: package.json IS the marker (unchanged)');
+    assert.equal(P.alreadyScaffolded(dir, 'adopt'), false, 'adopt: an existing project is NOT already adopted');
+
+    // Once the layer has added the core dep, adopt IS done. Both scope aliases count.
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ dependencies: { react: '^18', '@bongos/core': 'file:vendor/x.tgz' } }));
+    assert.equal(P.alreadyScaffolded(dir, 'adopt'), true);
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ dependencies: { '@cloudbongos/core': '^1.0.0' } }));
+    assert.equal(P.alreadyScaffolded(dir, 'adopt'), true, 'the @cloudbongos alias counts too');
+
+    // Unparseable → NOT already done, so the adopt layer runs and reports it, rather than
+    // silently skipping on a file it could not read.
+    writeFileSync(join(dir, 'package.json'), '{ not json');
+    assert.equal(P.alreadyScaffolded(dir, 'adopt'), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// Drive the scaffold in a given mode against a fresh base and return the joined argv.
+async function scaffoldInMode(mode, { token = null, seedRoot = null } = {}) {
+  const base = mkdtempSync(join(tmpdir(), `mode-${mode}-`));
+  const origBase = P.CONFIG.standaloneBase;
+  P.CONFIG.standaloneBase = base;
+  try {
+    if (seedRoot) { mkdirSync(join(base, 'demo'), { recursive: true }); seedRoot(join(base, 'demo')); }
+    const { deps, cmds } = recorder({ apply: true });
+    const writes = [];
+    deps.writeFile = (p, body, opts) => { writes.push({ p, body, opts }); return { ok: true }; };
+    if (token) deps.getGithubToken = async () => ({ token, scope: 'read:user,repo' });
+    await P.scaffoldStandaloneRepo(
+      { slug: 'demo', hosting_shape: 'standalone', target_ref: 'lars589/demo', owner_builder_id: 7, onboard_mode: mode },
+      { ...deps, instanceRoot: base },
+    );
+    return { joined: cmds.join('\n'), cmds, writes, root: join(base, 'demo') };
+  } finally {
+    P.CONFIG.standaloneBase = origBase;
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+await ta('scaffoldStandaloneRepo(adopt): CLONES the existing repo instead of git-init-ing a fresh tree', async () => {
+  const { joined } = await scaffoldInMode('adopt', { token: 'gho_TOK' });
+  assert.match(joined, /clone https:\/\/x-access-token@github\.com\/lars589\/demo\.git/, 'clones over the token URL (covers a PRIVATE repo the shared deploy key cannot read)');
+  assert.ok(!/git -C \S+ init -q/.test(joined), 'never git-inits a fresh tree on the adopt path — that is what produced the unrelated history');
+  assert.ok(!/checkout -B main/.test(joined), 'does not force-create the branch over the cloned one');
+  assert.match(joined, /init\.js --from .* --no-seed --adopt --accept /, 'materializes via init --adopt --accept (layering, accept-gated)');
+  // origin must end up as the SSH remote, like greenfield leaves it: the ongoing deploy
+  // (`git pull --ff-only origin main`, and the box timer's `git reset --hard origin/main`)
+  // reads origin, and the one-shot token URL cannot authenticate once its credential file
+  // is deleted.
+  assert.match(joined, /git -C \S+ remote set-url origin git@github-deploy:lars589\/demo\.git/, 'normalizes origin to the SSH remote after cloning');
+});
+
+// THE SAFETY PROPERTY. Since ADR 0155 this credential can write to EVERY repo the owner
+// owns, so a --force here would be a route to destroying a user's work. A rejected push is
+// the correct, recoverable outcome.
+await ta('scaffoldStandaloneRepo(adopt): NEVER force-pushes and never passes --force to init', async () => {
+  const { joined } = await scaffoldInMode('adopt', { token: 'gho_TOK' });
+  assert.ok(!/--force/.test(joined), 'no --force anywhere in the adopt argv');
+  assert.ok(!/ -f\b/.test(joined.replace(/rm -f /g, '')), 'no -f force shorthand (rm -f of the credential file excepted)');
+  assert.ok(!/\+refs|\+HEAD|:\+/.test(joined), 'no leading-+ refspec (the other way to force a push)');
+  assert.match(joined, /push https:\/\/x-access-token@github\.com\/lars589\/demo\.git HEAD:main/, 'a plain fast-forward push');
+});
+
+await ta('scaffoldStandaloneRepo(greenfield): unchanged — git init + --force, no clone', async () => {
+  const { joined } = await scaffoldInMode('greenfield', { token: 'gho_TOK' });
+  assert.match(joined, /git -C \S+ init -q/, 'still git-inits the empty repo');
+  assert.match(joined, /checkout -B main/);
+  assert.match(joined, /init\.js --from .* --no-seed --force /, 'greenfield keeps --force (safe on an empty repo)');
+  assert.ok(!/--adopt/.test(joined), 'no --adopt on the greenfield path');
+  assert.ok(!/ clone /.test(joined), 'nothing to clone from an empty repo');
+});
+
+await ta('scaffoldStandaloneRepo(adopt): no owner token → clones over the SSH remote (no credential helper)', async () => {
+  const { joined } = await scaffoldInMode('adopt');   // recorder default getGithubToken → null
+  assert.match(joined, /clone git@github-deploy:lars589\/demo\.git/, 'falls back to the SSH remote');
+  assert.ok(!/credential\.helper=/.test(joined), 'no credential helper without a token');
+  assert.match(joined, /push -u origin main/, 'and the SSH origin push');
+});
+
+await ta('scaffoldStandaloneRepo(adopt): does NOT clobber an existing .gitignore — appends only what the deploy needs', async () => {
+  const { writes } = await scaffoldInMode('adopt', {
+    token: 'gho_TOK',
+    seedRoot: (root) => writeFileSync(join(root, '.gitignore'), 'their-secrets/\ncoverage/\n'),
+  });
+  const gi = writes.find((w) => /\.gitignore$/.test(w.p));
+  assert.ok(gi, 'wrote .gitignore');
+  assert.match(String(gi.body), /their-secrets\//, 'the owner’s existing rules survive');
+  assert.match(String(gi.body), /coverage\//);
+  assert.match(String(gi.body), /node_modules\//, 'and the entries `npm ci` + the deploy require are added');
+});
+
+await ta('scaffoldStandaloneRepo(adopt): a default branch that is not `main` fails LOUDLY, not silently', async () => {
+  // The rest of provisioning is main-only (git pull --ff-only origin main; the box deploy
+  // does git reset --hard origin/main), so layering onto another branch would push somewhere
+  // the deploy never reads — a half-working instance with no error.
+  const base = mkdtempSync(join(tmpdir(), 'mode-branch-'));
+  const origBase = P.CONFIG.standaloneBase;
+  P.CONFIG.standaloneBase = base;
+  try {
+    const { deps } = recorder({ apply: true });
+    deps.getGithubToken = async () => ({ token: 'gho_TOK', scope: 'repo' });
+    deps.exec = (cmd) => ({ ok: true, stdout: /rev-parse --abbrev-ref HEAD/.test(cmd) ? 'master\n' : '' });
+    await assert.rejects(
+      () => P.scaffoldStandaloneRepo(
+        { slug: 'demo', hosting_shape: 'standalone', target_ref: 'lars589/demo', owner_builder_id: 7, onboard_mode: 'adopt' },
+        { ...deps, instanceRoot: base },
+      ),
+      /default branch is "master", not "main"/,
+    );
+  } finally {
+    P.CONFIG.standaloneBase = origBase;
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+await ta('scaffoldStandaloneRepo(adopt): the credential file is removed even when a git step THROWS', async () => {
+  const base = mkdtempSync(join(tmpdir(), 'mode-cred-'));
+  const origBase = P.CONFIG.standaloneBase;
+  P.CONFIG.standaloneBase = base;
+  try {
+    const { deps, cmds } = recorder({ apply: true });
+    deps.getGithubToken = async () => ({ token: 'gho_TOK', scope: 'repo' });
+    deps.exec = (cmd) => {
+      cmds.push(cmd);
+      if (/ push /.test(cmd)) throw new Error('remote rejected: non-fast-forward');
+      return { ok: true, stdout: '' };
+    };
+    await assert.rejects(
+      () => P.scaffoldStandaloneRepo(
+        { slug: 'demo', hosting_shape: 'standalone', target_ref: 'lars589/demo', owner_builder_id: 7, onboard_mode: 'adopt' },
+        { ...deps, instanceRoot: base },
+      ),
+      /non-fast-forward/,
+    );
+    assert.match(cmds.join('\n'), /rm -f [^\n]*bongos-gitcred-demo/, 'a failed push must not leave the token on disk');
+  } finally {
+    P.CONFIG.standaloneBase = origBase;
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 await ta('provisionInstance is idempotent: an already-active instance is a no-op', async () => {
   const { deps, cmds } = recorder();
   const r = await P.provisionInstance({ ...coTenant, status: 'active' }, deps);