@bongos/core 1.18.3 → 1.18.19

package/tests/instance_release_config.mjs

@@ -0,0 +1,104 @@
+// tests/instance_release_config.mjs
+//
+// serve-internal mounts /downloads/devbox/* and /downloads/bongos/* only when the
+// instance ships the matching RELEASE config (config/devbox-app.json,
+// config/bongos-cli.json). Those configs are boundary-EXCLUDED from the packaged core,
+// so they live at the INSTANCE root — which on a vendored instance (@bongos/core in
+// node_modules, ADR 0108) is a DIFFERENT directory from the core package dir
+// serve-internal.js sits in. The old core-relative `require('../../config/…')` looked
+// only in node_modules/@bongos/core/config/, so a vendored instance's Dev Box download
+// routes never mounted (task 1002371; ADR 0145 papered over it by copying the config
+// into node_modules — lost on the next npm ci). Same class as ADR 0144's vendored
+// infra/ path bug.
+//
+// The first test is THE regression: a config present ONLY at the instance root must be
+// found. It fails against the old resolution (which could not see the instance root at
+// all) and passes against the instance-root-first ladder.
+//
+// serve-internal is DB-free (the pg pool connects lazily), so the end-to-end case mounts
+// it on a throwaway express app over loopback — same pattern as tests/docs_openapi_route.mjs.
+//
+// Run:  node --test tests/instance_release_config.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+// A minimal but VALID release config — buildDevboxDownloads rejects a bad
+// releases_repo/version at boot, so the end-to-end mount below proves real parsing.
+const DEVBOX_CFG = {
+  releases_repo: 'example-owner/example-devbox',
+  version: '9.9.9',
+  assets: { 'mac-arm64': 'Example-Dev-Box-9.9.9-arm64.dmg' },
+  aliases: { mac: 'mac-arm64' },
+};
+
+// Write config/<name> under a fresh temp dir and return the dir (a stand-in root).
+function makeRoot(name, contents) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-root-'));
+  if (name) {
+    fs.mkdirSync(path.join(dir, 'config'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'config', name), contents);
+  }
+  return dir;
+}
+
+// Point the process at a temp INSTANCE root BEFORE serve-internal loads, so the default
+// (uninjected) resolution runs the vendored shape: config at the instance root, absent
+// from the core package dir. This checkout ships no config/devbox-app.json — it is
+// instance-only — so the core tier genuinely has nothing to find, exactly like a
+// freshly-vendored box.
+const INSTANCE_ROOT = makeRoot('devbox-app.json', JSON.stringify(DEVBOX_CFG));
+process.env.CLOUDBONGOS_INSTANCE_ROOT = INSTANCE_ROOT;
+const { tryLoadInstanceConfig, mountInternalSurfaces } = require('../src/bongos/serve-internal.js');
+
+test('finds a release config that exists ONLY at the instance root (the vendored bug)', () => {
+  const instance = makeRoot('devbox-app.json', '{"version":"1.0.0"}');
+  const core = makeRoot(null);
+  assert.deepEqual(tryLoadInstanceConfig('devbox-app.json', [instance, core]), { version: '1.0.0' });
+});
+
+test('the instance root wins over the core package dir when both carry a copy', () => {
+  const instance = makeRoot('devbox-app.json', '{"from":"instance"}');
+  const core = makeRoot('devbox-app.json', '{"from":"core"}');
+  assert.equal(tryLoadInstanceConfig('devbox-app.json', [instance, core]).from, 'instance');
+});
+
+test('falls back to the core package dir (single checkout + the copied-in workaround)', () => {
+  const instance = makeRoot(null);
+  const core = makeRoot('bongos-cli.json', '{"from":"core"}');
+  assert.equal(tryLoadInstanceConfig('bongos-cli.json', [instance, core]).from, 'core');
+});
+
+test('absent from every root → null, so the download surface just does not mount', () => {
+  assert.equal(tryLoadInstanceConfig('devbox-app.json', [makeRoot(null), makeRoot(null)]), null);
+  assert.equal(tryLoadInstanceConfig('devbox-app.json', []), null);
+});
+
+test('a MALFORMED config still throws — only a MISSING file is tolerated', () => {
+  const bad = makeRoot('devbox-app.json', '{ this is not valid json ');
+  assert.throws(() => tryLoadInstanceConfig('devbox-app.json', [bad]), SyntaxError);
+});
+
+test('/downloads/devbox/version mounts from an INSTANCE-root config (end to end)', async () => {
+  const express = require('express');
+  const app = express();
+  mountInternalSurfaces(app);
+  const server = await new Promise((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  try {
+    const res = await fetch(`http://127.0.0.1:${server.address().port}/downloads/devbox/version`);
+    assert.equal(res.status, 200, 'the route must mount when only the INSTANCE root has the config');
+    const body = await res.json();
+    assert.equal(body.version, DEVBOX_CFG.version);
+    assert.match(body.assets['mac-arm64'], /^https:\/\/github\.com\/example-owner\/example-devbox\//);
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+});

package/tests/linkify_refs.mjs

@@ -252,12 +252,25 @@ t('a known idea link is never unwrapped by the past-mislink pass', () => {
   assert.equal(runIds(s, ids), s);
 });
 
-t('discoverDocs finds CLAUDE.md + session logs, only .md, skips the generated ideas file', () => {
+t('discoverDocs finds CLAUDE.md, recurses docs/ subdirs (only .md), skips the generated ideas file', () => {
   const docs = discoverDocs();
   assert.ok(docs.includes('CLAUDE.md'), 'includes CLAUDE.md');
-  assert.ok(docs.some((d) => d.startsWith('docs/session-logs/')), 'includes session logs');
   assert.ok(docs.every((d) => d.endsWith('.md')), 'only markdown files');
   assert.ok(!docs.includes('generative-ideas.md'), 'excludes the generated ideas file');
+  // Recurses into docs/ subdirectories. docs/adr/*.md is the always-present nested
+  // case; assert recursion against it (task 1002234). Session logs are the canonical
+  // nested example the linkifier targets, but the neutral core carries none (they're
+  // instance-specific / not committed), so that stricter check is conditional — it
+  // still verifies them on an instance whose docs/session-logs/ is populated.
+  assert.ok(docs.some((d) => d.startsWith('docs/') && d.split('/').length >= 3),
+    'recurses into docs/ subdirectories (e.g. docs/adr/*.md)');
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const logsDir = path.resolve(process.cwd(), 'docs/session-logs');
+  const hasSessionLogMd = fs.existsSync(logsDir) && fs.readdirSync(logsDir).some((f) => f.endsWith('.md'));
+  if (hasSessionLogMd) {
+    assert.ok(docs.some((d) => d.startsWith('docs/session-logs/')), 'includes session logs when present');
+  }
 });
 
 console.log(`\nlinkify_refs: ${passed} passed, ${failed} failed`);

package/tests/migrate_root_resolution.mjs

@@ -17,7 +17,9 @@
 
 import { strict as assert } from 'node:assert';
 import { execFileSync } from 'node:child_process';
-import { mkdtempSync, mkdirSync, writeFileSync, realpathSync } from 'node:fs';
+import {
+  mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, symlinkSync, realpathSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
@@ -93,5 +95,126 @@ t('CORE_ROOT is always the script-relative repo root, independent of the invocat
   assert.equal(realpathSync(printRoots({ cwd: bare }).CORE_ROOT), REPO_REAL);
 });
 
+// ==========================================================================
+// A CORE ROOT WHOSE PATH CONTAINS A SPACE (task 1002611)
+// ==========================================================================
+// `for f in $MIGRATIONS` word-split the newline-separated migration list on IFS — which includes
+// space — so a checkout at "/Users/.../Hermeslines Marketing/..." fragmented every path, the
+// `[ -e "$f" ]` guard dropped all of them, and ZERO core migrations ran. Reproduced on
+// @bongos/core@1.18.18: 117 files listed, 234 iterations, 234 -e failures, schema_migrations empty.
+//
+// These exercise migrate.sh's `--print-migrations` seam, which walks the REAL loop and reports each
+// path instead of applying it (DB-free, like --print-roots). Reporting through the real loop is the
+// point: a copy of the loop inside this test would not catch a revert of the loop in the script.
+
+// A synthetic CORE root: `scripts/migrate.sh` SYMLINKED to the real script (so the fixture can never
+// drift from it), a stub instance-config that names the fixture as both roots, and n migration files.
+// `spaced` puts a space in the fixture's own directory name — the whole point of the fixture.
+function makeCore({ spaced, files = ['001_a.sql', '002_b.sql', '006_pms_v2.sql', '019_c.sql'] } = {}) {
+  const prefix = spaced ? 'r89 spaced core-' : 'r89-plain-core-';
+  const dir = realpathSync(mkdtempSync(path.join(tmpdir(), prefix)));
+  mkdirSync(path.join(dir, 'scripts'));
+  mkdirSync(path.join(dir, 'migrations'));
+  mkdirSync(path.join(dir, 'src'));
+  symlinkSync(MIGRATE, path.join(dir, 'scripts', 'migrate.sh'));
+  // Pin both roots to the fixture explicitly, so the test does not lean on migrate.sh's
+  // node-unavailable fallback to decide what CORE_ROOT is.
+  writeFileSync(path.join(dir, 'src', 'instance-config.js'), [
+    "const path = require('node:path');",
+    "const ROOT = path.resolve(__dirname, '..');",
+    'module.exports = {',
+    '  resolveCoreRoot: () => ROOT,',
+    '  resolveInstanceRootExplicit: () => ROOT,',
+    '};',
+    '',
+  ].join('\n'));
+  for (const f of files) writeFileSync(path.join(dir, 'migrations', f), '-- probe\n');
+  return dir;
+}
+
+// Run `<core>/scripts/migrate.sh --print-migrations` and parse the seam's output.
+// Returns { applied: [paths], listed, unreadable, status, stderr }.
+function printMigrations(coreDir, { script = 'migrate.sh' } = {}) {
+  const env = { ...process.env };
+  for (const k of Object.keys(env)) if (/_INSTANCE_ROOT$/.test(k)) delete env[k];
+  delete env.INIT_CWD;
+  let stdout = '';
+  let stderr = '';
+  let status = 0;
+  try {
+    stdout = execFileSync('bash', [path.join(coreDir, 'scripts', script), '--print-migrations'],
+      { cwd: coreDir, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (e) {
+    status = e.status ?? 1;
+    stdout = e.stdout ?? '';
+    stderr = e.stderr ?? '';
+  }
+  const applied = [];
+  let listed = null;
+  let unreadable = null;
+  for (const line of stdout.split('\n')) {
+    const a = /^would-apply\t(.*)$/.exec(line);
+    if (a) { applied.push(a[1]); continue; }
+    const s = /^listed=(\d+) unreadable=(\d+)$/.exec(line);
+    if (s) { listed = Number(s[1]); unreadable = Number(s[2]); }
+  }
+  return { applied, listed, unreadable, status, stderr, stdout };
+}
+
+t('core root containing a space: every migration is listed as ONE whole, readable path', () => {
+  const core = makeCore({ spaced: true });
+  assert.ok(core.includes(' '), 'fixture path must contain a space to be meaningful');
+  const r = printMigrations(core);
+  assert.equal(r.status, 0, `migrate.sh --print-migrations must succeed; stderr:\n${r.stderr}`);
+  assert.equal(r.listed, 4, 'all four migrations must be listed');
+  assert.equal(r.unreadable, 0, 'no listed path may fail the -e test (fragmentation)');
+  assert.equal(r.applied.length, 4, 'all four must reach apply_migration');
+  for (const f of r.applied) {
+    assert.ok(existsSync(f), `listed path must exist on disk, got fragment: ${f}`);
+    assert.ok(f.startsWith(core), `listed path must be whole and under the core root: ${f}`);
+  }
+});
+
+t('core root containing a space: applies in basename order, unaffected by the space', () => {
+  const core = makeCore({ spaced: true });
+  const r = printMigrations(core);
+  assert.deepEqual(
+    r.applied.map((f) => path.basename(f)),
+    ['001_a.sql', '002_b.sql', '006_pms_v2.sql', '019_c.sql'],
+    'the merge-and-sort-by-basename order must survive a spaced path',
+  );
+});
+
+t('a space-free core root behaves identically (the fixture itself is not what passes)', () => {
+  const spaced = printMigrations(makeCore({ spaced: true }));
+  const plain = printMigrations(makeCore({ spaced: false }));
+  assert.equal(plain.status, spaced.status);
+  assert.equal(plain.listed, spaced.listed);
+  assert.equal(plain.unreadable, spaced.unreadable);
+  assert.deepEqual(plain.applied.map((f) => path.basename(f)), spaced.applied.map((f) => path.basename(f)));
+});
+
+// The no-op guard, proven against the ACTUAL pre-fix code. Re-introducing the unquoted loop into a
+// copy of the script must now FAIL LOUDLY rather than skip every core migration in silence and let
+// the module loop below report a misleading `relation "achievements" does not exist`.
+t('the pre-fix unquoted loop now fails loudly instead of silently skipping', () => {
+  const core = makeCore({ spaced: true });
+  const src = readFileSync(MIGRATE, 'utf8');
+  const mutant = src
+    .replace('while IFS= read -r f; do', 'for f in $MIGRATIONS; do')
+    .replace('done <<< "$MIGRATIONS"', 'done');
+  assert.notEqual(mutant, src, 'the mutation must apply — has the core loop been reshaped?');
+  assert.ok(mutant.includes('for f in $MIGRATIONS'), 'mutant must carry the unquoted loop');
+  writeFileSync(path.join(core, 'scripts', 'mutant.sh'), mutant);
+
+  const r = printMigrations(core, { script: 'mutant.sh' });
+  assert.notEqual(r.status, 0, 'the unquoted loop on a spaced path must NOT exit 0');
+  assert.match(r.stderr, /FATAL/, 'the failure must be loud');
+  assert.match(r.stderr, /applied 0 and found 0 already applied/, 'it must name the real cause');
+  assert.match(r.stderr, /Refusing to continue to module migrations/,
+    'it must say it stopped before the module loop — the misleading-error path');
+  assert.equal(r.applied.length, 0, 'the unquoted loop applies nothing (that was the bug)');
+});
+
 console.log(`\nmigrate_root_resolution: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/module_contributions.mjs

@@ -146,3 +146,58 @@ test('settings-panel seam: ABSENT → empty; REGISTERED → present, sorted by o
   assert.throws(() => OTB.contributeSettingsPanel({ id: 'x' }), /requires id \+ mount/);
   delete global.window;
 });
+
+// --- hall-widget placement governance (task 2177) ----------------------------
+// Home grew unbounded once; contributeHallWidget now refuses the registrations
+// that let it. Rejections are console.error + null (NOT a throw) so one bad
+// third-party widget can't blank the hall — so these assert the RETURN VALUE and
+// that the widget never reached the registry.
+
+test('hall-widget registry: placement rules reject bad registrations, accept good ones', () => {
+  global.window = {};
+  // The settings-panel test above already required dom-utils.js, and the IIFE
+  // assigns window.OTB exactly once at load — so re-requiring a cached module
+  // would leave window.OTB undefined. Evict it to get a fresh registry.
+  const domUtils = path.join(ROOT, 'modules', 'hall-ui', 'public', 'dom-utils.js');
+  delete require.cache[require.resolve(domUtils)];
+  require(domUtils);
+  const OTB = global.window.OTB;
+
+  const errors = [];
+  const realError = console.error;
+  console.error = (msg) => errors.push(String(msg));
+  const reg = (o) => OTB.contributeHallWidget({ label: 'L', mount() {}, ...o });
+
+  try {
+    // the structural contract still THROWS (first-party programmer error)
+    assert.throws(() => reg({ label: 'no id' }), /requires id \+ label \+ mount/);
+
+    // unknown zone / unknown view — a typo used to mount the widget on Home
+    // silently, which read as "my widget vanished"
+    assert.equal(reg({ id: 'a', view: 'home', zone: 'home-sidebar' }), null);
+    assert.match(errors.at(-1), /unknown zone "home-sidebar"/);
+    assert.equal(reg({ id: 'b', view: 'dashboard', zone: 'home-main', summary: true }), null);
+    assert.match(errors.at(-1), /unknown view "dashboard"/);
+
+    // a Home widget must NAME its zone — there is no home-main fallback any more
+    assert.equal(reg({ id: 'c' }), null);
+    assert.match(errors.at(-1), /must declare a zone/);
+
+    // a non-core home-main widget must be summary or collapsed
+    assert.equal(reg({ id: 'd', view: 'home', zone: 'home-main' }), null);
+    assert.match(errors.at(-1), /summary:true .* or collapsedByDefault:true/);
+
+    // …and the escapes from that rule work
+    assert.ok(reg({ id: 'e', view: 'home', zone: 'home-main', summary: true }));
+    assert.ok(reg({ id: 'f', view: 'home', zone: 'home-main', collapsedByDefault: true }));
+    assert.ok(reg({ id: 'g', view: 'home', zone: 'home-main', core: true }));
+    // a non-Home view needs no zone (Standing widgets carry `group` instead)
+    assert.ok(reg({ id: 'h', view: 'standing', group: 'work' }));
+
+    // only the accepted four reached the registry
+    assert.deepEqual(OTB.hallWidgetIds(), ['e', 'f', 'g', 'h']);
+  } finally {
+    console.error = realError;
+    delete global.window;
+  }
+});

package/tests/module_loader.mjs

@@ -168,13 +168,18 @@ test('the live tree discovers the extracted modules cleanly (BV1.R43/R48/R47/R49
   // onboarding (R81) + sessions (R82) + autonomy (R83 — conductor/architect/gate
   // + the routine-timers poller) are the tranche-2 core-domain carves (ADR 0093),
   // then status-ui (R84) + hall-ui (R85) the two web-surface carves; and
-  // provisioning (ADR 0111 / task 1942) — a net-new feature module (instance hosting).
-  // All are discovered; none has validation errors or coreVersion mismatches.
-  // Membership stays byte-identical via src/modules.js (each leaves MODULE_REGISTRY
-  // and reappears here as discovered). Order is the readdir sort.
+  // provisioning (ADR 0111 / task 1942) — a net-new feature module (instance hosting);
+  // platform-identity (ADR 0141) the hub IdP; and governance (ADR 0151 / BV1.R94) the
+  // configurable roles/permissions module. All are discovered; none has validation
+  // errors or coreVersion mismatches. Order is the readdir sort.
+  //
+  // NB this is the CORE package tree: game / art-pipeline / character-anim / demo are
+  // instance/content-excluded from the published core (ADR 0098) so they are not
+  // present here — the discovered set is the 17 always-shipped core-domain + feature
+  // modules below.
   loader._reset();
   const snap = loader.loaderSnapshot();
-  assert.deepEqual(snap.loaded, ['art-pipeline', 'autonomy', 'builder-settings', 'character-anim', 'demo', 'dev-box', 'discord', 'economy', 'game', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'provisioning', 'security', 'sessions', 'status-ui']);
+  assert.deepEqual(snap.loaded, ['autonomy', 'builder-settings', 'dev-box', 'discord', 'economy', 'governance', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'platform-identity', 'provisioning', 'security', 'sessions', 'status-ui']);
   assert.deepEqual(snap.errors, []);
   assert.deepEqual(snap.skipped, []);
   loader._reset();

package/tests/module_scope_active_claims.mjs

@@ -0,0 +1,94 @@
+// tests/module_scope_active_claims.mjs
+//
+// Unit guard for db.moduleScopeForActiveClaims (goal 1000051 / R92, ADR 0148 §2) —
+// the lifecycle-port resolver the dev-box source-access path (R93/R94) reads to
+// derive a builder's TASK-scoped sparse-checkout: the union of module KEYS across
+// the builder's active claims' goals (claims → tasks → goals.scope_modules).
+//
+// DB-free, same posture as goal_achievement.mjs: the function honours the #538
+// deps.pool injection seam (ONLY when NODE_ENV==='test'), so a SQL-aware fake
+// client drives it with no live Postgres. We assert the query SHAPE (joins
+// claims→tasks→goals, unnests scope_modules, filters ACTIVE claims), the bound
+// params, the rows→keys mapping, and the numeric-input guard. The actual
+// set-union/dedup is Postgres's DISTINCT (exercised end-to-end once box-access is
+// wired — R95); here we prove the port method's contract.
+//
+// Run:  node tests/module_scope_active_claims.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const { moduleScopeForActiveClaims } = require('../modules/lifecycle/db.js');
+
+const { test, summary } = makeRunner();
+
+function fakePool(handler) {
+  const c = makeSqlAwareClient(handler);
+  return { query: (sql, params) => c._client.query(sql, params), connect: c.connect, queries: c._client.queries };
+}
+const norm = (s) => String(s).replace(/\s+/g, ' ').trim();
+const find = (queries, re) => queries.find((q) => re.test(norm(q.sql)));
+
+// The one read this function issues: claims → tasks → goals, unnest scope_modules,
+// active claims only. The fake returns whatever module-key rows we hand it (the
+// DISTINCT/ORDER BY is Postgres's job — here we just prove the plumbing).
+function scopeHandler(rows) {
+  return (s) => {
+    if (/FROM claims c/.test(s) && /JOIN goals g/.test(s) && /unnest\(g\.scope_modules\)/.test(s)) {
+      return { rows };
+    }
+    return null;
+  };
+}
+
+// =========================================================================
+// Happy path — active claims put N goals' scope_modules in scope
+// =========================================================================
+await test('returns the module keys the active claims scope, in DB order', async () => {
+  const pool = fakePool(scopeHandler([{ module_key: 'dev-box' }, { module_key: 'kernel' }, { module_key: 'lifecycle' }]));
+  const keys = await moduleScopeForActiveClaims(3, { pool });
+  assert.deepEqual(keys, ['dev-box', 'kernel', 'lifecycle'], 'maps rows → module_key list');
+
+  const q = find(pool.queries, /FROM claims c JOIN tasks t .* JOIN goals g/);
+  assert.ok(q, 'issues the claims→tasks→goals scope read');
+  assert.match(norm(q.sql), /c\.builder_id = \$1 AND c\.released_at IS NULL/, 'active claims only, keyed on builder');
+  assert.match(norm(q.sql), /unnest\(g\.scope_modules\)/, 'unnests the goal scope_modules array');
+  assert.match(norm(q.sql), /SELECT DISTINCT/, 'DISTINCT dedupes the union across claims');
+  assert.deepEqual(q.params, [3], 'binds the builder id');
+});
+
+// =========================================================================
+// No active claim (or no scoped goal) → base-only signal ([])
+// =========================================================================
+await test('no active claim / no scoped goal → empty array (box falls back to BASE-only)', async () => {
+  const pool = fakePool(scopeHandler([]));
+  const keys = await moduleScopeForActiveClaims(3, { pool });
+  assert.deepEqual(keys, [], 'zero rows → []');
+});
+
+// =========================================================================
+// Input guard — a non-numeric builder id never reaches SQL
+// =========================================================================
+await test('non-numeric builderId throws before any query', async () => {
+  const pool = fakePool(scopeHandler([{ module_key: 'dev-box' }]));
+  await assert.rejects(() => moduleScopeForActiveClaims('not-a-number', { pool }), /must be numeric/);
+  await assert.rejects(() => moduleScopeForActiveClaims(NaN, { pool }), /must be numeric/);
+  assert.equal(pool.queries.length, 0, 'guard trips before the pool is touched');
+});
+
+// =========================================================================
+// The #538 deps.pool test seam is actually wired (we ARE in NODE_ENV==='test')
+// =========================================================================
+await test('honours the deps.pool test seam', async () => {
+  let touched = false;
+  const pool = fakePool((s) => { touched = true; return /unnest/.test(s) ? { rows: [{ module_key: 'game' }] } : null; });
+  const keys = await moduleScopeForActiveClaims(7, { pool });
+  assert.ok(touched, 'the injected pool was used');
+  assert.deepEqual(keys, ['game']);
+});
+
+summary();

package/tests/needs_rebase.mjs

@@ -0,0 +1,92 @@
+// tests/needs_rebase.mjs — ADR 0120 part 2 (real DB).
+//
+// Exercises db.flagTaskNeedsRebase + the flag-clearing on ship against a live
+// Postgres (DATABASE_URL). The fake-client harness can't cover the actual
+// WHERE-clause guards (status='confirmed' AND needs_rebase=false) or the
+// migration-093 columns, so this is a real-DB integration test. It SELF-SKIPS
+// (exit 0) when no DB is reachable, so it is safe on a bare worktree; it is also
+// listed in run-unit-tests.js's INTEGRATION set so the default DB-free lane
+// never runs it.
+//
+// Run:  DATABASE_URL=... node tests/needs_rebase.mjs
+
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+
+// Reachability probe — skip cleanly if there's no local Postgres.
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`needs_rebase.mjs SKIPPED — no reachable Postgres (${e.code || e.message}). Set DATABASE_URL to run.`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+const db = require('../modules/lifecycle/db.js');
+
+const VER = 'ZZZ-NR', WORKER = 90000101, TASK = 90000101;
+const q = (sql, params) => pool.query(sql, params).then((r) => r.rows);
+const taskRow = async () => (await q(`SELECT status, needs_rebase, needs_rebase_reason, needs_rebase_at FROM tasks WHERE id=$1`, [TASK]))[0];
+
+async function cleanup() {
+  await q(`DELETE FROM builder_achievements WHERE builder_id=$1`, [WORKER]).catch(() => {});
+  await q(`DELETE FROM credit_log WHERE builder_id=$1 OR task_id=$2`, [WORKER, TASK]).catch(() => {});
+  await q(`DELETE FROM claims WHERE task_id=$1`, [TASK]).catch(() => {});
+  await q(`DELETE FROM tasks WHERE id=$1`, [TASK]).catch(() => {});
+  await q(`DELETE FROM builders WHERE id=$1`, [WORKER]).catch(() => {});
+  await q(`DELETE FROM versions WHERE id=$1`, [VER]).catch(() => {});
+}
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); console.log(`  ok  ${msg}`); pass++; };
+
+try {
+  await cleanup();
+  await q(`INSERT INTO versions (id,name,status,track) VALUES ($1,'nr','planning','internal') ON CONFLICT (id) DO NOTHING`, [VER]);
+  await q(`INSERT INTO builders (id,github_id,github_login,display_name,rank) VALUES ($1,'nr-w','nr-worker','NR Worker','thetes')`, [WORKER]);
+  await q(`INSERT INTO tasks (id,version_id,title,status,credits_reward,kind,shipped_by) VALUES ($1,$2,'nr fixture','confirmed',10,'feature',$3)`, [TASK, VER, WORKER]);
+  await q(`INSERT INTO claims (task_id,builder_id,claimed_at) VALUES ($1,$2,now())`, [TASK, WORKER]);
+
+  // 1) flag a CONFIRMED task → flagged, reason + at set, returns true.
+  const first = await db.flagTaskNeedsRebase(String(TASK), 'strand:no_branch_no_tip');
+  ok(first === true, 'flagTaskNeedsRebase returns true when it newly flags a confirmed task');
+  let t = await taskRow();
+  ok(t.needs_rebase === true, 'tasks.needs_rebase is true after flagging');
+  ok(t.needs_rebase_reason === 'strand:no_branch_no_tip', 'reason recorded');
+  ok(t.needs_rebase_at != null, 'needs_rebase_at timestamp set');
+
+  // 2) idempotent — a second flag is a no-op (returns false, at unchanged).
+  const atWas = t.needs_rebase_at;
+  const second = await db.flagTaskNeedsRebase(String(TASK), 'strand:different');
+  ok(second === false, 'a re-flag of an already-flagged task returns false (idempotent)');
+  t = await taskRow();
+  ok(t.needs_rebase_reason === 'strand:no_branch_no_tip', 'reason NOT overwritten on re-flag');
+  ok(String(t.needs_rebase_at.getTime?.() ?? t.needs_rebase_at) === String(atWas.getTime?.() ?? atWas), 'needs_rebase_at unchanged on re-flag');
+
+  // 3) shipping the task CLEARS the flag (the land completed).
+  await db.shipTask({ taskId: String(TASK), builderId: String(WORKER) });
+  t = await taskRow();
+  ok(t.status === 'shipped', 'task shipped');
+  ok(t.needs_rebase === false, 'needs_rebase cleared on ship');
+  ok(t.needs_rebase_reason === null && t.needs_rebase_at === null, 'reason + at cleared on ship');
+
+  // 4) a NON-confirmed task cannot be flagged (guard: WHERE status='confirmed').
+  const onShipped = await db.flagTaskNeedsRebase(String(TASK), 'should-not-apply');
+  ok(onShipped === false, 'flagTaskNeedsRebase is a no-op on a non-confirmed (shipped) task');
+  t = await taskRow();
+  ok(t.needs_rebase === false, 'a shipped task stays unflagged');
+
+  console.log(`\nneeds_rebase (ADR 0120 part 2): ${pass} passed, 0 failed`);
+} catch (e) {
+  console.error('needs_rebase.mjs FAILED:', e.message);
+  process.exitCode = 1;
+} finally {
+  await cleanup();
+  await pool.end();
+}

package/tests/one_active_claim_per_session.mjs

@@ -107,5 +107,81 @@ t('refusal carries the canonical reason code', () => {
   assert.equal(d.reason, 'session_already_has_active_claim');
 });
 
+// =========================================================================
+// Worktree-keying fix — the real commingle boundary is the WORKING TREE, not
+// the shared auth session. A builder's concurrent worktrees share ONE auth
+// session_id (the CLI token lives in ~/.config), so keying on the session alone
+// wrongly blocked the second parallel worktree. Refusal must scope to the SAME
+// worktree_name; a different worktree is a different branch → allowed.
+// =========================================================================
+
+// (e) THE FIX: same auth session, DIFFERENT worktree → ALLOWED (the parallel
+//     worktrees the code's own comment promised "must keep working").
+t('same session, different worktree → ALLOWED (parallel worktrees)', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-1',
+    worktreeName: 'wt-feature-b',
+    activeClaimsForSession: [
+      { claim_id: 40, task_id: 50, creator_session_id: 'sess-1', worktree_name: 'wt-feature-a', title: 'A' },
+    ],
+  });
+  assert.equal(d.refuse, false);
+  assert.equal(d.inFlightTaskId, null);
+});
+
+// (f) Same auth session, SAME worktree → refused (a real commingle: one tree,
+//     one branch, two tasks).
+t('same session, same worktree → refused', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-1',
+    worktreeName: 'wt-feature-a',
+    activeClaimsForSession: [
+      { claim_id: 41, task_id: 51, creator_session_id: 'sess-1', worktree_name: 'wt-feature-a', title: 'A' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.inFlightTaskId, 51);
+  assert.equal(d.reason, 'session_already_has_active_claim');
+});
+
+// (g) Both worktree-less (a plain clone, no --worktree): the single branch really
+//     would commingle → still refused (the safe default, unchanged behaviour).
+t('same session, both worktree-less (null) → refused (shared clone)', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-1',
+    worktreeName: null,
+    activeClaimsForSession: [
+      { claim_id: 42, task_id: 52, creator_session_id: 'sess-1', worktree_name: null, title: 'A' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.inFlightTaskId, 52);
+});
+
+// (h) A worktree-bound existing claim must NOT block a later worktree-less claim
+//     (they are genuinely different trees), and vice-versa.
+t('worktree-bound claim does not block a worktree-less claim (different trees)', () => {
+  const held = { claim_id: 43, task_id: 53, creator_session_id: 'sess-1', worktree_name: 'wt-x', title: 'X' };
+  assert.equal(shouldRefuseSessionClaim({ creatorSessionId: 'sess-1', worktreeName: null, activeClaimsForSession: [held] }).refuse, false);
+  const heldNull = { claim_id: 44, task_id: 54, creator_session_id: 'sess-1', worktree_name: null, title: 'N' };
+  assert.equal(shouldRefuseSessionClaim({ creatorSessionId: 'sess-1', worktreeName: 'wt-y', activeClaimsForSession: [heldNull] }).refuse, false);
+});
+
+// (i) Correct in-flight task is named when MULTIPLE claims exist across worktrees
+//     — the block points at the one in the SAME tree, not just the first row.
+t('names the in-flight task in the MATCHING worktree, not the first row', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-1',
+    worktreeName: 'wt-two',
+    activeClaimsForSession: [
+      { claim_id: 45, task_id: 60, creator_session_id: 'sess-1', worktree_name: 'wt-one', title: 'One' },
+      { claim_id: 46, task_id: 61, creator_session_id: 'sess-1', worktree_name: 'wt-two', title: 'Two' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.inFlightTaskId, 61);
+  assert.equal(d.inFlightTitle, 'Two');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);