@bongos/core 1.18.19 → 1.19.2

package/tests/bongos_downloads.mjs

@@ -9,10 +9,11 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import { requireHostModule } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const { buildBongosDownloads } = require('../src/bongos-downloads.js');
-const committedConfig = require('../config/bongos-cli.json');
+const committedConfig = requireHostModule(require, '../config/bongos-cli.json');
 
 let passed = 0;
 let failed = 0;

package/tests/box_dns_repoint.mjs

@@ -20,6 +20,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { skipUnlessPresent } from './helpers.mjs';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -28,6 +29,7 @@ const require = createRequire(import.meta.url);
 const here = path.dirname(fileURLToPath(import.meta.url));
 const repo = path.resolve(here, '..');
 const HOOK = path.join(repo, 'infra', 'box-dns-cloudflare.sh');
+skipUnlessPresent('infra/box-dns-cloudflare.sh');
 
 // ── a fake `curl` that emulates the Cloudflare API per FAKE_CF_SCENARIO ─────────
 const FAKE_CURL = `#!/usr/bin/env node

package/tests/box_ship_permissions.mjs

@@ -12,9 +12,11 @@ import { strict as assert } from 'node:assert';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { skipUnlessPresent } from './helpers.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const settingsPath = path.join(__dirname, '..', '.claude', 'settings.json');
+skipUnlessPresent('.claude/settings.json');
 
 let passed = 0, failed = 0;
 function test(name, fn) {

package/tests/box_terminal_ssrf.mjs

@@ -5,7 +5,7 @@
 // the WEB TIER fetch it. The old guard (/^https:\/\/[^\s]+$/) accepted ANY https
 // host, so a builder could make the prod server probe internal/metadata
 // endpoints (SSRF). isSafeTerminalUrl(url, login) must allow ONLY the two real
-// tunnel shapes — `term-<login>.…amazonprimea.com` (bound to the caller's login)
+// tunnel shapes — `term-<login>.<apex>` (bound to the caller's login)
 // and `*.trycloudflare.com` — and reject everything else.
 //
 // Pure function, no server/DB/network.
@@ -25,19 +25,25 @@ const test = (name, fn) => {
 };
 
 const LOGIN = 'lars589';
+// The dev-box apex is INJECTED rather than taken from the live instance branding
+// (task 1002470). Two reasons: the neutral core has no amazonprimea.com apex, so the
+// three allow-cases could not pass; and every reject-case below was passing for the
+// WRONG reason — an apex mismatch, not the rule it names. With a pinned apex,
+// 'rejects another builder's term- host' really does prove the login binding.
+const APEX = 'apex.example';
 
 // ---- allowed: the two legitimate tunnel shapes -------------------------------
 test('allows the named-tunnel apex host bound to the caller login', () => {
-  assert.equal(isSafeTerminalUrl('https://term-lars589.amazonprimea.com', LOGIN), true);
+  assert.equal(isSafeTerminalUrl(`https://term-lars589.${APEX}`, LOGIN, APEX), true);
 });
-test('allows the named-tunnel dev-zone host (term-<login>.dev.amazonprimea.com)', () => {
-  assert.equal(isSafeTerminalUrl('https://term-lars589.dev.amazonprimea.com/', LOGIN), true);
+test(`allows the named-tunnel dev-zone host (term-<login>.dev.${APEX})`, () => {
+  assert.equal(isSafeTerminalUrl(`https://term-lars589.dev.${APEX}/`, LOGIN, APEX), true);
 });
 test('allows a Cloudflare quick-tunnel host (*.trycloudflare.com)', () => {
-  assert.equal(isSafeTerminalUrl('https://random-words-1234.trycloudflare.com', LOGIN), true);
+  assert.equal(isSafeTerminalUrl('https://random-words-1234.trycloudflare.com', LOGIN, APEX), true);
 });
 test('login match is case-insensitive (DNS is case-insensitive)', () => {
-  assert.equal(isSafeTerminalUrl('https://term-LarsCode.amazonprimea.com', 'larscode'), true);
+  assert.equal(isSafeTerminalUrl(`https://term-LarsCode.${APEX}`, 'larscode', APEX), true);
 });
 
 // ---- rejected: SSRF targets --------------------------------------------------
@@ -54,36 +60,36 @@ for (const bad of [
   'https://printer.local/',
 ]) {
   test(`rejects SSRF target ${bad}`, () => {
-    assert.equal(isSafeTerminalUrl(bad, LOGIN), false);
+    assert.equal(isSafeTerminalUrl(bad, LOGIN, APEX), false);
   });
 }
 
 // ---- rejected: wrong scheme / shape / cross-login ----------------------------
 test('rejects http (must be https)', () => {
-  assert.equal(isSafeTerminalUrl('http://term-lars589.amazonprimea.com', LOGIN), false);
+  assert.equal(isSafeTerminalUrl(`http://term-lars589.${APEX}`, LOGIN, APEX), false);
 });
 test('rejects embedded credentials (user:pass@host)', () => {
-  assert.equal(isSafeTerminalUrl('https://user:pass@term-lars589.amazonprimea.com', LOGIN), false);
+  assert.equal(isSafeTerminalUrl(`https://user:pass@term-lars589.${APEX}`, LOGIN, APEX), false);
 });
 test('rejects another builder\'s term- host (login binding)', () => {
-  assert.equal(isSafeTerminalUrl('https://term-someoneelse.amazonprimea.com', LOGIN), false);
+  assert.equal(isSafeTerminalUrl(`https://term-someoneelse.${APEX}`, LOGIN, APEX), false);
 });
 test('rejects a non-tunnel host on the project domain', () => {
-  assert.equal(isSafeTerminalUrl('https://api.amazonprimea.com', LOGIN), false);
+  assert.equal(isSafeTerminalUrl(`https://api.${APEX}`, LOGIN, APEX), false);
 });
 test('rejects an arbitrary external host', () => {
-  assert.equal(isSafeTerminalUrl('https://evil.example.com', LOGIN), false);
+  assert.equal(isSafeTerminalUrl('https://evil.example.com', LOGIN, APEX), false);
 });
 test('rejects a lookalike suffix (…trycloudflare.com.evil.com)', () => {
-  assert.equal(isSafeTerminalUrl('https://x.trycloudflare.com.evil.com', LOGIN), false);
+  assert.equal(isSafeTerminalUrl('https://x.trycloudflare.com.evil.com', LOGIN, APEX), false);
 });
 test('rejects garbage / unparseable', () => {
-  assert.equal(isSafeTerminalUrl('not a url', LOGIN), false);
-  assert.equal(isSafeTerminalUrl('', LOGIN), false);
-  assert.equal(isSafeTerminalUrl(null, LOGIN), false);
+  assert.equal(isSafeTerminalUrl('not a url', LOGIN, APEX), false);
+  assert.equal(isSafeTerminalUrl('', LOGIN, APEX), false);
+  assert.equal(isSafeTerminalUrl(null, LOGIN, APEX), false);
 });
 test('rejects when login is empty (cannot bind the term- form)', () => {
-  assert.equal(isSafeTerminalUrl('https://term-lars589.amazonprimea.com', ''), false);
+  assert.equal(isSafeTerminalUrl(`https://term-lars589.${APEX}`, '', APEX), false);
 });
 
 console.log(`\n${pass} passed, ${fail} failed`);

package/tests/claim_error_surface.mjs

@@ -33,6 +33,7 @@ const text = (r) => r.lines.join('\n');
 t('never dumps [object Object] for any known code', () => {
   const codes = [
     'stage_required', 'session_already_has_active_claim', 'session_claim_check_failed',
+    'session_already_has_bound_claim',
     'newcomer_must_ship_first', 'ALREADY_CLAIMED', 'MODULE_CONFLICT',
     'TOUCHES_CONFLICT', 'TASK_NOT_READY', 'TASK_NOT_FOUND', 'DEPS_NOT_SHIPPED',
     'some_unmapped_future_code',
@@ -96,6 +97,28 @@ t('MODULE_CONFLICT + TOUCHES_CONFLICT: list conflicting task titles', () => {
   assert.match(tc, /Baz/);
 });
 
+// task 1002589: migration 180's one-bound-claim-per-session DB index tripped
+// (claimTask now maps that 23505 by err.constraint instead of collapsing it
+// onto ALREADY_CLAIMED). The honest render: the TARGET task is still free —
+// the SESSION holds a bound claim elsewhere. Never blame a phantom rival.
+t('session_already_has_bound_claim: names the in-flight claim, not "another session"', () => {
+  const out = text(formatClaimFailure(
+    envelope('session_already_has_bound_claim', {
+      active_task_id: 77, active_task_title: 'Held elsewhere', what_to_do: 'ship 77 or claim unbound',
+    }), 12));
+  assert.match(out, /#77/, 'should name the in-flight task id');
+  assert.match(out, /Held elsewhere/, 'should name the in-flight task title');
+  assert.match(out, /ship 77 or claim unbound/, 'should relay the server what_to_do');
+  assert.match(out, /still free/i, 'should say the target task is not actually taken');
+  assert.ok(!/claimed by another session/i.test(out), 'must not blame a phantom builder');
+});
+
+t('session_already_has_bound_claim without details still renders honest guidance', () => {
+  const out = text(formatClaimFailure(envelope('session_already_has_bound_claim', {}), 12));
+  assert.match(out, /bound claim/i);
+  assert.match(out, /bind_session|builder-ship|builder-release/, 'fallback should name a way out');
+});
+
 t('unknown code: fallback carries code + message, exit 1', () => {
   const r = formatClaimFailure(envelope('weird_thing', {}, 'boom', 500), 1);
   assert.equal(r.exit, 1);

package/tests/claude_materialize.mjs

@@ -109,6 +109,9 @@ t('materializeClaude: copies + rewrites skills into a fresh instance dir (no lef
 });
 
 t('materializeClaude: materializes scheduled-tasks — bodies→bongos, companions keep _core-resolve (task 2138)', () => {
+  // There is nothing to materialize FROM when the core checkout carries no
+  // .claude/ source tree (package-excluded — task 1002470).
+  if (!existsSync(join(ROOT, '.claude', 'scheduled-tasks'))) return;
   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');
@@ -204,6 +207,7 @@ t('disabledModuleSkills: only skills of DISABLED modules are collected (default
 
 // ---- 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', () => {
+  if (!existsSync(join(ROOT, '.claude', 'hooks'))) return;
   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 });

package/tests/cli_box_scope.mjs

@@ -9,12 +9,20 @@
 //
 // Run:  node tests/cli_box_scope.mjs
 
+// task 1002162: the detector originally compared `res.data.error` to the STRING
+// 'box_scope'. The live server emits the ADR 0116 (R01) envelope, so that field
+// is an OBJECT and the test never matched — both call sites in cli-lib were dead
+// code. The envelope cases below import the server's REAL `envelope()` formatter
+// rather than hand-typing the shape, so if the wire contract changes again this
+// test fails instead of silently drifting back into a no-op.
+
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
 const lib = require('../scripts/gds/cli-lib.js');
 const { isBoxScope } = lib;
+const { envelope } = require('../src/bongos/api-errors.js');
 
 let passed = 0, failed = 0;
 function test(name, fn) {
@@ -47,6 +55,38 @@ test('isBoxScope: false on missing/empty data (no crash)', () => {
   assert.equal(isBoxScope(undefined), false);
 });
 
+// ---------------------------------------------------------------------------
+// task 1002162 — the ADR 0116 envelope. THE REGRESSION: these are the shapes the
+// live server actually sends, built by the server's own formatter.
+// ---------------------------------------------------------------------------
+
+test('isBoxScope: true for the REAL server envelope (the shape that was missed)', () => {
+  assert.equal(isBoxScope({ status: 403, data: envelope('box_scope') }), true);
+});
+
+test('isBoxScope: true for an envelope carrying message + details', () => {
+  const body = envelope('box_scope', 'box-scoped session', { what_to_do: 're-auth' });
+  assert.equal(body.error.code, 'box_scope', 'guard: envelope() still nests under .error.code');
+  assert.equal(isBoxScope({ status: 403, data: body }), true);
+});
+
+test('isBoxScope: false for a DIFFERENT code in envelope form — must not hijack', () => {
+  assert.equal(isBoxScope({ status: 403, data: envelope('not_your_task') }), false);
+  assert.equal(isBoxScope({ status: 403, data: envelope('forbidden') }), false);
+  assert.equal(isBoxScope({ status: 403, data: envelope('rank_forbidden') }), false);
+});
+
+test('isBoxScope: false for the envelope on the WRONG status', () => {
+  assert.equal(isBoxScope({ status: 401, data: envelope('box_scope') }), false);
+  assert.equal(isBoxScope({ status: 200, data: envelope('box_scope') }), false);
+});
+
+test('isBoxScope: no crash on a null/odd error field', () => {
+  assert.equal(isBoxScope({ status: 403, data: { error: null } }), false);
+  assert.equal(isBoxScope({ status: 403, data: { error: {} } }), false);
+  assert.equal(isBoxScope({ status: 403, data: {} }), false);
+});
+
 console.log('');
 console.log(`cli_box_scope: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);

package/tests/cloud_bongos_pack.mjs

@@ -5,11 +5,15 @@
 // the customer-0 pack Cloud Bongos itself runs on.
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
+import { existsSync, writeFileSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import brandingMod from '../src/branding.js';
 import serveInternal from '../src/bongos/serve-internal.js';
 
-const { loadBranding, clientBranding } = brandingMod;
+const { loadBranding, clientBranding, INSTANCE_PATH } = brandingMod;
 const { themeMarkup, injectBrandingGlobal } = serveInternal;
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
 // A standalone/vanilla boot has NO instance config — point the loader at a
 // nonexistent instance path so it resolves the neutral starter alone (the
@@ -65,6 +69,10 @@ test('customer-0: GDS_BRANDING_FILE selects the cloudbongos.com instance pack (t
   // The live dogfood instance runs from the SAME checkout as OTB; the env knob
   // points this process at its own pack (deltas over neutral) instead of OTB's
   // config/branding.json. Proves the brand-switch + the cloudbongos pack content.
+  // Both packs are INSTANCE content — the neutral core ships neither, so this
+  // asserts one deployment's config (task 1002470). The selector MECHANISM is
+  // proven unconditionally by the fixture test below.
+  if (!existsSync(join(ROOT, 'config/branding.cloudbongos.json'))) return;
   const b = loadBranding({ env: { GDS_BRANDING_FILE: 'config/branding.cloudbongos.json' } });
   assert.equal(b.identity.productName, 'Cloud Bongos'); // from neutral
   assert.equal(b.currency.label, 'credits');            // from neutral, not "drachmae"
@@ -77,9 +85,31 @@ test('customer-0: GDS_BRANDING_FILE selects the cloudbongos.com instance pack (t
   assert.equal(b.firstAdmin, 'lars589');
 });
 
-test('customer-0: no GDS_BRANDING_FILE still resolves OTB (default unchanged)', () => {
+test('customer-0: no GDS_BRANDING_FILE still resolves the instance pack (default unchanged)', () => {
   // The OTB process (server.js) sets no GDS_BRANDING_FILE → config/branding.json.
+  // Same instance-content caveat as above: with no instance pack the correct default
+  // IS the neutral starter, which is what the vanilla tests in this file already pin.
+  if (!existsSync(INSTANCE_PATH)) return;
   const b = loadBranding({ env: {} });
-  assert.equal(b.identity.worldName, 'Amazonprimea');
-  assert.equal(b.currency.label, 'drachmae');
+  assert.notDeepEqual(b.identity, vanilla().identity, 'the instance pack must win over neutral by default');
+});
+
+test('GDS_BRANDING_FILE selects a named pack over the default (the selector mechanism)', () => {
+  // The half of the two tests above that must hold on EVERY instance, proven against a
+  // throwaway fixture instead of one deployment's committed pack (task 1002470).
+  const rel = 'config/branding.__fixture-selector-test.json';
+  const abs = join(ROOT, rel);
+  writeFileSync(abs, JSON.stringify({ identity: { productName: 'Fixture Product' }, currency: { label: 'zorkmids' } }));
+  try {
+    const picked = loadBranding({ env: { GDS_BRANDING_FILE: rel } });
+    assert.equal(picked.identity.productName, 'Fixture Product', 'the named pack was selected');
+    assert.equal(picked.currency.label, 'zorkmids', 'its deltas won over neutral');
+    // ...and unspecified keys still fall through to the neutral starter (it is a MERGE,
+    // not a replace) — so a partial pack can never blank out the platform defaults.
+    assert.equal(picked.copy.hallName, vanilla().copy.hallName, 'unspecified keys fall through to neutral');
+    // Counterfactual: without the env knob the fixture must NOT be in play.
+    assert.notEqual(loadBranding({ env: {} }).currency.label, 'zorkmids', 'the selector is what chose it');
+  } finally {
+    rmSync(abs, { force: true });
+  }
 });

package/tests/conductor.mjs

@@ -10,9 +10,10 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import { requireHostModule } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
-const conductor = require('../.claude/hooks/conductor.js');
+const conductor = requireHostModule(require, '../.claude/hooks/conductor.js');
 
 let passed = 0;
 let failed = 0;

package/tests/criterion_authoring_gate.mjs

@@ -29,6 +29,7 @@ const buildDoneWhenRouter = require('../modules/lifecycle/routes/done-when.js');
 const { authorizeCriterionCreate } = buildDoneWhenRouter;
 const { authorizeGoalManagement, isGoalOwnerOrManager } = require('../modules/lifecycle/goal-authz.js');
 const { MODULE_EXPECTED_RANKS } = require('../src/bongos/route-rank-check.js');
+const catalog = require('../modules/governance/catalog.js');
 
 const doneWhenSrc = readFileSync(new URL('../modules/lifecycle/routes/done-when.js', import.meta.url), 'utf8');
 const { test, summary } = makeRunner();
@@ -239,12 +240,19 @@ await test('the gate reuses the SAME owner|manager predicate as routes/goals.js
 
 // ---- route-source + pin contracts (drift catchers) ----
 
+// BV1.R105 migrated this middleware from requireRank('metic','archon') to the
+// `criterion.create` ATOM. The audience assertion did not weaken — it got stricter:
+// the spelling check now runs THROUGH the catalog, so a floor change on the atom
+// reds this test even though the route source is untouched. (Pinning the atom name
+// alone would let `criterion.create` quietly drop to xenos and still pass.)
 await test('the route is gated metic+archon and calls the pure gate', () => {
   assert.match(
     doneWhenSrc,
-    /router\.post\('\/versions\/:id\/done-when',\s*auth\.requireBuilder,\s*auth\.requireRank\('metic',\s*'archon'\)/,
-    'the middleware must be requireRank(metic, archon)'
+    /router\.post\('\/versions\/:id\/done-when',\s*auth\.requireBuilder,\s*auth\.requirePermission\('criterion\.create'\)/,
+    'the middleware must be requirePermission(criterion.create)'
   );
+  assert.equal(catalog.byKey('criterion.create').floor, 'metic',
+    'criterion.create must floor at metic — that floor IS what makes this route metic+archon');
   assert.match(doneWhenSrc, /authorizeCriterionCreate\(\{/, 'the handler must call the pure gate, not inline the decision');
 });
 
@@ -256,13 +264,28 @@ await test('the `// rank:` annotation matches the middleware (gen-api-docs reads
   );
 });
 
-await test('unsatisfy stays ARCHON — the backward ratchet is not part of this grant', () => {
+// ADR 0154 made "unsatisfy stays ARCHON" its safety argument for delegating criterion
+// CREATE to Metic: the forward ratchet moved, the backward one did not. ADR 0157 (owner
+// decision, 2026-08-05) overrides that specific carve-out — `criterion.unsatisfy` is
+// neither rank/identity nor one of the four escalation keys, so it delegated with the rest
+// of the operational block.
+//
+// What this test still guards is the part that never depended on the rank: unsatisfy must
+// remain gated on its OWN dedicated atom, distinct from `criterion.satisfy`. If the two
+// were ever merged, confirming a criterion would silently confer the power to un-confirm
+// one — and THAT is the asymmetry ADR 0154 actually cared about.
+await test('unsatisfy is gated on its OWN atom — the backward ratchet is a separate grant', () => {
   assert.match(
     doneWhenSrc,
-    /router\.post\('\/done-when\/:criterionId\/unsatisfy',\s*auth\.requireBuilder,\s*auth\.requireRank\('archon'\)/,
+    /router\.post\('\/done-when\/:criterionId\/unsatisfy',\s*auth\.requireBuilder,\s*auth\.requirePermission\('criterion\.unsatisfy'\)/,
     'un-flipping a confirmed criterion rewrites shipped scope-truth'
   );
-  assert.equal(MODULE_EXPECTED_RANKS.lifecycle['POST /done-when/:criterionId/unsatisfy'], 'archon');
+  assert.equal(catalog.byKey('criterion.unsatisfy').floor, 'metic',
+    'ADR 0157 delegated the backward ratchet to the working rank');
+  assert.notEqual(catalog.byKey('criterion.unsatisfy').key, catalog.byKey('criterion.satisfy').key,
+    'satisfy and unsatisfy must stay separate atoms, whatever their floors');
+  assert.equal(MODULE_EXPECTED_RANKS.lifecycle['POST /done-when/:criterionId/unsatisfy'],
+    'perm:criterion.unsatisfy');
 });
 
 await test('the route-rank PIN records metic+archon (fitness reds the build on drift)', () => {

package/tests/currency_label.mjs

@@ -55,10 +55,19 @@ test('clientBranding is a SMALL allow-list — no server-only field leaks to the
     db: { database: 'amazonprimea' },
     envPrefix: 'OTB',
   });
-  assert.deepEqual(Object.keys(projected).sort(), ['copy', 'currency', 'identity', 'rankLabels', 'theme']);
+  // `reward` joined the projection in task 1002469 (ADR 0146 follow-up) — the resolved
+  // reward POLICY, so a builder on a cost-plus-only instance isn't shown a per-task
+  // estimate that will never pay. The allow-list was not updated with it, so this guard
+  // had been failing since that landed (task 1002470).
+  assert.deepEqual(Object.keys(projected).sort(), ['copy', 'currency', 'identity', 'rankLabels', 'reward', 'theme']);
   for (const leak of ['domains', 'repo', 'db', 'envPrefix', 'llmProjectName']) {
     assert.equal(projected[leak], undefined, `${leak} must not reach the client`);
   }
+  // The new member is itself held to the same small-surface rule — the point of this
+  // test is that every projected key is a reviewed one, not merely that it is listed.
+  assert.deepEqual(Object.keys(projected.reward).sort(), ['mode', 'perTaskCredit']);
+  assert.equal(typeof projected.reward.mode, 'string');
+  assert.equal(typeof projected.reward.perTaskCredit, 'boolean');
 });
 
 test('R56: injectBrandingGlobal inserts a synchronous window.__BRANDING__ before </head>', () => {

package/tests/deploy_instance.mjs

@@ -14,9 +14,11 @@ import { mkdtempSync, rmSync, existsSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { skipUnlessPresent } from './helpers.mjs';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const SCRIPT = join(ROOT, 'scripts', 'deploy', 'deploy-instance.sh');
+skipUnlessPresent('scripts/deploy/deploy-instance.sh');
 
 let passed = 0;
 let failed = 0;

package/tests/devbox_downloads.mjs

@@ -9,10 +9,11 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import { requireHostModule } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const { buildDevboxDownloads } = require('../src/devbox-downloads.js');
-const committedConfig = require('../config/devbox-app.json');
+const committedConfig = requireHostModule(require, '../config/devbox-app.json');
 
 let passed = 0;
 let failed = 0;

package/tests/display_name.mjs

@@ -1,11 +1,19 @@
 // tests/display_name.mjs
 //
-// Unit smoke for modules/builder-settings/display-name.js (task 1669) — the pure
-// validator behind GET/PATCH /me/display-name (the self-service display-name
-// editor). Covers the rules the route enforces: trim, reject empty /
-// whitespace-only, the length ceiling, and control-character rejection. The DB
-// write + route plumbing are exercised by the prod smoke; here we cover the
-// pure logic without touching pg.
+// Unit smoke for the self-service display-name editor (GET/PATCH
+// /me/display-name), in two parts:
+//
+//   1. modules/builder-settings/display-name.js (task 1669) — the pure
+//      validator. Trim, reject empty / whitespace-only, the length ceiling, and
+//      control-character rejection.
+//   2. The PERSISTENCE guard (task 1002568, ADR 0156) — "your name wins,
+//      always". Only covering the validator is why the bug shipped: the save
+//      worked and then upsertBuilder, which runs on EVERY sign-in, re-set
+//      display_name from the GitHub name. These tests read the REAL SQL both
+//      halves emit and check the conflict branch's behaviour, so deleting the
+//      guard fails here instead of in production.
+//
+// No pg: the shared pool's query() is stubbed to record the SQL.
 //
 // Run:  node tests/display_name.mjs
 
@@ -119,5 +127,86 @@ t('hasControlChar detects control chars and clears normal text', () => {
   assert.equal(d.hasControlChar(`with${BEL}bell`), true);
 });
 
+// ---------------------------------------------------------------------------
+// Persistence: a user-set name survives the next sign-in (task 1002568)
+// ---------------------------------------------------------------------------
+
+// Stub the SHARED pool object before requiring anything that queries it — both
+// db-kernel.js and the module's db.js capture this exact singleton at load.
+const { pool } = require('../src/bongos/pool.js');
+let lastSql = null;
+pool.query = async (sql) => { lastSql = sql; return { rows: [{}] }; };
+
+const kernel = require('../src/bongos/db-kernel.js');
+const settingsDb = require('../modules/builder-settings/db.js');
+
+// Pull one assignment out of an ON CONFLICT ... DO UPDATE SET clause. None of
+// the assignments contain a comma, so splitting on commas is exact.
+function conflictAssignment(sql, column) {
+  const setClause = sql.slice(sql.indexOf('DO UPDATE'), sql.indexOf('RETURNING'));
+  for (const part of setClause.replace(/^[\s\S]*?SET/, '').split(',')) {
+    const [lhs, ...rhs] = part.split('=');
+    if (lhs.trim() === column) return rhs.join('=').trim();
+  }
+  throw new Error(`no "${column} = …" assignment in the conflict branch`);
+}
+
+// Evaluate the display_name assignment for one row, so the tests below read as
+// behaviour ("whose name ends up stored?") rather than string matching. An
+// unguarded assignment — the shape that shipped the bug — is a bare column
+// reference and evaluates to whatever GitHub just sent.
+function resolvedDisplayName(expr, { source, stored, incoming }) {
+  const ref = (token) => {
+    if (/^EXCLUDED\.display_name$/i.test(token)) return incoming;
+    if (/^builders\.display_name$/i.test(token)) return stored;
+    throw new Error(`unrecognised display_name reference: ${token}`);
+  };
+  const norm = expr.replace(/\s+/g, ' ').trim();
+  const m = /^CASE WHEN builders\.display_name_source = '(\w+)' THEN (\S+) ELSE (\S+) END$/i.exec(norm);
+  if (!m) return ref(norm);
+  return source === m[1] ? ref(m[2]) : ref(m[3]);
+}
+
+// Drive both halves once (they're async), then assert on the captured SQL with
+// the same synchronous `t` helper the validator tests use.
+await kernel.upsertBuilder({
+  githubId: 64553469, githubLogin: 'jaxri', displayName: 'GitHub Name', avatarUrl: null,
+});
+const upsertExpr = conflictAssignment(lastSql, 'display_name');
+
+await settingsDb.setBuilderDisplayName(1000095, 'Renée the Builder');
+const setNameSql = lastSql.replace(/\s+/g, ' ');
+
+console.log('\nsign-in persistence (upsertBuilder conflict branch):');
+
+t('the conflict branch keys display_name off display_name_source', () => {
+  assert.ok(
+    /display_name_source/.test(upsertExpr),
+    `upsertBuilder must not re-set display_name unconditionally; got: ${upsertExpr}`
+  );
+});
+
+t('a builder who set their own name keeps it when GitHub sends a different one', () => {
+  const kept = resolvedDisplayName(upsertExpr, {
+    source: 'user', stored: 'Renée the Builder', incoming: 'renee-gh',
+  });
+  assert.equal(kept, 'Renée the Builder');
+});
+
+t('a builder who never renamed still picks up a GitHub rename', () => {
+  const synced = resolvedDisplayName(upsertExpr, {
+    source: 'github', stored: 'Old GitHub Name', incoming: 'New GitHub Name',
+  });
+  assert.equal(synced, 'New GitHub Name');
+});
+
+t('setBuilderDisplayName stamps the name as user-set', () => {
+  assert.match(
+    setNameSql,
+    /display_name_source = 'user'/,
+    'without the stamp the saved name reverts at the next sign-in'
+  );
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);

package/tests/eviction_policy.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 { classifyEviction, estTokens, blockText, stubFor, normalize, readRange, isVolatileBash, salientTokens } = require('../.claude/hooks/eviction-policy.js');
+const { classifyEviction, estTokens, blockText, stubFor, normalize, readRange, isVolatileBash, salientTokens } = requireHostModule(require, '../.claude/hooks/eviction-policy.js');
 
 let passed = 0, failed = 0;
 function test(name, fn) {

package/tests/file_map.mjs

@@ -31,7 +31,12 @@ test('committed file-map sections are current (the Path-C CI gate)', () => {
 test('EVERY skill + scheduled-task dir on disk is listed AND has a note — no silent omission, no ghost', () => {
   const model = gen.buildModel();
   assert.ok(model.length === 2, 'two generated sections');
+  let checked = 0;
   for (const section of model) {
+    // .claude/skills + .claude/scheduled-tasks are INSTANCE-materialized; a neutral
+    // core checkout carries neither (task 1002470). Check the sections that exist.
+    if (!existsSync(path.join(ROOT, section.dir))) continue;
+    checked += 1;
     const onDisk = readdirSync(path.join(ROOT, section.dir), { withFileTypes: true })
       .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
       .map((e) => e.name)
@@ -41,6 +46,11 @@ test('EVERY skill + scheduled-task dir on disk is listed AND has a note — no s
     assert.equal(section.missing.length, 0, `${section.dir}: dirs without a note: ${section.missing.join(', ')}`);
     assert.equal(section.stale.length, 0, `${section.dir}: notes with no dir (ghosts): ${section.stale.join(', ')}`);
   }
+  // Non-vacuity: on an instance that materializes .claude/, this must have checked
+  // something — a skipped-everything run would otherwise pass while asserting nothing.
+  if (existsSync(path.join(ROOT, '.claude'))) {
+    assert.ok(checked > 0, '.claude/ exists but no section was checked — the exhaustiveness guard went vacuous');
+  }
 });
 
 test('the generated blocks live between markers and carry one ← note per entry', () => {

package/tests/first_admin_bootstrap.mjs

@@ -6,16 +6,24 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import auth from '../src/bongos/auth.js';
+import brandingMod from '../src/branding.js';
 
 const { firstAdminLogin, maybeSeatFirstAdmin } = auth;
+const { branding } = brandingMod;
 
 function clearEnv() {
   for (const k of ['OTB_FIRST_ADMIN', 'GDS_FIRST_ADMIN', 'PMS_FIRST_ADMIN', 'CLOUDBONGOS_FIRST_ADMIN']) delete process.env[k];
 }
 
-test('firstAdminLogin: resolves from branding (OTB pack → lars589) when no env override', () => {
+test('firstAdminLogin: resolves from the branding pack when no env override', () => {
+  // Asserts the RESOLUTION, not one instance's owner. This used to hardcode the OTB
+  // founder's login, which both broke on any other instance (the neutral pack sets
+  // firstAdmin: "") and put a founder identity in a test — the thing
+  // scripts/gds/audit-authorship.sh exists to keep out (task 1002470).
   clearEnv();
-  assert.equal(firstAdminLogin(), 'lars589');
+  const configured = (branding().firstAdmin || '').trim() || null;
+  assert.equal(firstAdminLogin(), configured,
+    'with no env override, firstAdminLogin must be exactly what the branding pack configures');
 });
 
 test('firstAdminLogin: env override wins over branding (configured prefix)', () => {

package/tests/first_run_engine_check.mjs

@@ -10,12 +10,13 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import { requireHostModule } from './helpers.mjs';
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 const require = createRequire(import.meta.url);
-const { firstRunEngineCheck } = require('../.claude/hooks/session-start.js');
+const { firstRunEngineCheck } = requireHostModule(require, '../.claude/hooks/session-start.js');
 
 let passed = 0, failed = 0;
 function t(name, fn) {