@bongos/core 1.18.3 → 1.18.19

package/tests/box_sync.mjs

@@ -0,0 +1,55 @@
+// tests/box_sync.mjs
+//
+// BV1.R96 (goal 1000051) — "sync now": box-sync.js locates the box source-fetch
+// script (so re-running it re-scopes the box to the active claim) and degrades
+// cleanly off a box. Pure + hermetic: resolveFetchScript threads {env, repoRoot}
+// to the shared resolveBoxInfraDir (ADR 0150 / R98); temp dirs stand in for a real
+// box infra/ tree. NO DB, NO network, NO box.
+//
+// Run:  node tests/box_sync.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const boxSync = require('../scripts/gds/box-sync.js');
+
+const { test, summary } = makeRunner();
+
+const tmps = [];
+function makeInfra({ template = true, fetch = true } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'boxsync-'));
+  tmps.push(root);
+  const infra = path.join(root, 'infra');
+  fs.mkdirSync(infra, { recursive: true });
+  // resolveBoxInfraDir validates an infra/ by the presence of the cloud-init template.
+  if (template) fs.writeFileSync(path.join(infra, 'builder-box-cloud-init.yaml'), '#cloud-config\n');
+  if (fetch) fs.writeFileSync(path.join(infra, boxSync.FETCH_SCRIPT), '#!/usr/bin/env bash\necho fetch\n');
+  return { root, infra };
+}
+
+await test('resolves the box source-fetch script when it is present on the box', () => {
+  const { infra } = makeInfra();
+  const got = boxSync.resolveFetchScript({ env: { CLOUDBONGOS_BOX_INFRA_DIR: infra }, repoRoot: '/nope' });
+  assert.equal(got, path.join(infra, boxSync.FETCH_SCRIPT));
+});
+
+await test('→ null when the infra/ has no source-fetch script (template present, fetch absent)', () => {
+  const { infra } = makeInfra({ fetch: false });
+  const got = boxSync.resolveFetchScript({ env: { CLOUDBONGOS_BOX_INFRA_DIR: infra }, repoRoot: '/nope' });
+  assert.equal(got, null);
+});
+
+await test('→ null when there is no infra/ at all (i.e. NOT on a box)', () => {
+  const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'boxsync-bare-'));
+  tmps.push(bare);
+  const got = boxSync.resolveFetchScript({ env: {}, repoRoot: path.join(bare, 'node_modules', '@bongos', 'core') });
+  assert.equal(got, null);
+});
+
+for (const d of tmps) { try { fs.rmSync(d, { recursive: true, force: true }); } catch { /* best-effort */ } }
+summary();

package/tests/box_task_scope.mjs

@@ -0,0 +1,99 @@
+// tests/box_task_scope.mjs
+//
+// R95 (goal 1000051, ADR 0148) — the end-to-end PURE decision for task-scoped
+// source access, composing the two halves shipped in R92 + R93:
+//   lifecycle.moduleScopeForActiveClaims (claims → tasks → goals.scope_modules)
+//     → box-access.decideSourceAccess({ scopeKeys, moduleScopeMap })
+// Proves R95's done-when as named behavior: 0 active claims → BASE-only; N active
+// claims → BASE ∪ the union of ALL N goals' module scopes.
+//
+// DB-free: moduleScopeForActiveClaims honours the #538 deps.pool seam
+// (NODE_ENV==='test'), so a SQL-aware fake pool stands in for Postgres — we hand it
+// the rows the DISTINCT-union query would return (the union itself is Postgres's
+// job, shape-proven in module_scope_active_claims.mjs) and assert the WHOLE chain
+// down to the sparse-checkout paths. The real module-scope-map (a pure core module)
+// is the map the route passes in.
+//
+// Run:  node tests/box_task_scope.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 db = require('../modules/lifecycle/db.js');
+const access = require('../modules/dev-box/box-access.js');
+const scopeMap = require('../src/bongos/module-scope-map.js');
+
+const { test, summary } = makeRunner();
+const BASE = access.BASE_SPARSE_PATHS;
+
+// Fake pool: the resolver issues ONE query (claims→tasks→goals, unnest
+// scope_modules); return the module-key rows a builder's active claims would
+// produce (already DISTINCT-unioned + ORDER BY m, as Postgres would).
+function poolReturning(moduleKeyRows) {
+  const c = makeSqlAwareClient((s) =>
+    (/FROM claims c/.test(s) && /unnest\(g\.scope_modules\)/.test(s)) ? { rows: moduleKeyRows } : null);
+  return { query: (sql, params) => c._client.query(sql, params), connect: c.connect, queries: c._client.queries };
+}
+
+// The full chain a box-fetch runs: resolve the active-claim scope, then decide the
+// source spec from it (rank still gates ALLOW/DENY).
+async function specForClaims({ builderId = 3, rank = 'metic', status = 'active', moduleKeyRows }) {
+  const pool = poolReturning(moduleKeyRows);
+  const scopeKeys = await db.moduleScopeForActiveClaims(builderId, { pool });
+  return { scopeKeys, decision: access.decideSourceAccess({ rank, status, scopeKeys, moduleScopeMap: scopeMap }) };
+}
+
+// =========================================================================
+// 0 active claims → BASE-only (the pre-existing Bongos instance, nothing extra)
+// =========================================================================
+await test('0 active claims → base-only spec', async () => {
+  const { scopeKeys, decision } = await specForClaims({ moduleKeyRows: [] });
+  assert.deepEqual(scopeKeys, [], 'no active claim → no scope keys');
+  assert.equal(decision.allowed, true);
+  assert.equal(decision.scope, 'base');
+  assert.deepEqual(decision.spec.sparsePaths, [...BASE], 'the box carries only BASE');
+});
+
+// =========================================================================
+// N active claims across goals → BASE ∪ the UNION of all N goals' scopes
+// =========================================================================
+await test('N active claims → base ∪ the union of all their goals’ module scopes', async () => {
+  // Two claims: goal A scoped {dev-box, status-ui}, goal B scoped {hall-ui}.
+  // Postgres DISTINCT-unions + ORDER BY m to this key set:
+  const { scopeKeys, decision } = await specForClaims({
+    moduleKeyRows: [{ module_key: 'dev-box' }, { module_key: 'hall-ui' }, { module_key: 'status-ui' }],
+  });
+  assert.deepEqual(scopeKeys, ['dev-box', 'hall-ui', 'status-ui'], 'union across the active claims');
+  assert.equal(decision.scope, 'task');
+  // BASE ∪ each module's DIRECTORY globs (dev-box's box-CLI FILE globs cone-filtered out).
+  assert.deepEqual(
+    decision.spec.sparsePaths,
+    [...BASE, 'devbox-app', 'modules/dev-box', 'modules/hall-ui', 'modules/status-ui'],
+    'every claimed goal’s module dirs are materialized, deduped + sorted',
+  );
+  assert.ok(!decision.spec.sparsePaths.includes('scripts/gds/box.js'), 'file globs never enter the sparse set');
+});
+
+// =========================================================================
+// One claim, one goal → BASE ∪ that goal's scope (the single-claim base case)
+// =========================================================================
+await test('a single claim → base ∪ that one goal’s module scope', async () => {
+  const { decision } = await specForClaims({ moduleKeyRows: [{ module_key: 'status-ui' }] });
+  assert.equal(decision.scope, 'task');
+  assert.deepEqual(decision.spec.sparsePaths, [...BASE, 'modules/status-ui']);
+});
+
+// =========================================================================
+// Rank/status STILL gate ALLOW/DENY ahead of any task scope (ADR 0148 C4 posture)
+// =========================================================================
+await test('an inactive builder is denied even with claims in scope', async () => {
+  const inactive = await specForClaims({ status: 'inactive', moduleKeyRows: [{ module_key: 'dev-box' }] });
+  assert.equal(inactive.decision.allowed, false);
+  assert.equal(inactive.decision.reason, 'BUILDER_INACTIVE');
+});
+
+summary();

package/tests/branding.mjs

@@ -66,6 +66,15 @@ test('provisioningOrigin: optional, passes through config, env-overridable (task
   assert.equal(env.domains.provisioningOrigin, 'https://get.acme.example');
 });
 
+test('landing.postLogin: config passes through, <PREFIX>_POST_LOGIN_LANDING overrides (task 1002240)', () => {
+  // Set in the instance pack, it survives the deep-merge.
+  const inst = resolveBranding({ neutral: NEUTRAL, instance: { ...SAMPLE, landing: { postLogin: '/gate/' } } });
+  assert.equal(inst.landing.postLogin, '/gate/');
+  // And the env override beats config (same precedence as the origins).
+  const env = resolveBranding({ neutral: NEUTRAL, instance: { ...SAMPLE, landing: { postLogin: '/builders' } }, env: { ACME_POST_LOGIN_LANDING: '/gate/' } });
+  assert.equal(env.landing.postLogin, '/gate/');
+});
+
 test('missing required field throws', () => {
   assert.throws(() => resolveBranding({ neutral: { identity: { productName: 'X' } } }), /missing required field/);
 });
@@ -91,6 +100,9 @@ test('the committed neutral pack loads + resolves to the neutral identity (the t
   assert.equal(b.identity.productName, 'Cloud Bongos');
   assert.equal(b.identity.worldName, 'Cloud Bongos');
   assert.ok(b.domains.publicOrigin.startsWith('http://localhost'));
+  // The portable post-login landing default is the hall — never a /gate/ orbs
+  // site (which only a platform-home instance ships). Task 1002240.
+  assert.equal(b.landing.postLogin, '/builders');
 });
 
 test('resolveBranding does not freeze its input objects (no shared refs)', () => {

package/tests/cf_ruleset_preflight.mjs

@@ -0,0 +1,142 @@
+// tests/cf_ruleset_preflight.mjs — DB-free, network-free unit tests for the
+// Cloudflare RULESET scope preflight (scripts/gds/cf-tunnel.js
+// classifyRulesetScope + checkRulesetScope, task 1002511).
+//
+// WHY ITS OWN FILE: `cf_tunnel` is in run-unit-tests.js's INTEGRATION exclusion
+// set, so anything added only to tests/cf_tunnel.mjs never runs in the default
+// DB-free unit gate that /builder-ship smokes. This file is auto-discovered by
+// that gate, so the preflight's behaviour is actually enforced on every ship.
+//
+// Run:  node tests/cf_ruleset_preflight.mjs
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const cf = require('../scripts/gds/cf-tunnel.js');
+
+const PHASE = 'http_request_late_transform';
+
+// ── the constants the rule + the preflight share ────────────────────────────
+test('the cookie-strip rule constants are exported for callers + this test', () => {
+  assert.equal(cf.COOKIE_STRIP_PHASE, PHASE);
+  assert.match(cf.COOKIE_STRIP_RULE_DESC, /Cookie/);
+  assert.match(cf.COOKIE_STRIP_EXPRESSION, /term-/);
+  assert.match(cf.COOKIE_STRIP_EXPRESSION, /sandbox-/);
+});
+
+// ── classifyRulesetScope: PURE, and a NEGATIVE detector only ────────────────
+test('classifyRulesetScope: 403 → NOT readable + guidance naming the zone and Transform Rules', () => {
+  const r = cf.classifyRulesetScope({
+    status: 403,
+    body: { success: false, errors: [{ message: 'Actor does not have permission' }] },
+    phase: PHASE,
+    zone: 'cloudbongos.com',
+  });
+  assert.equal(r.readable, false);
+  assert.match(r.guidance, /Transform Rules/);
+  assert.match(r.guidance, /Cache Rules/);
+  assert.match(r.guidance, /cloudbongos\.com/);
+  assert.match(r.guidance, /API Tokens/i);
+});
+
+test('classifyRulesetScope: 401 → NOT readable (definitively no scope)', () => {
+  const r = cf.classifyRulesetScope({ status: 401, body: null, phase: PHASE, zone: 'cloudbongos.com' });
+  assert.equal(r.readable, false);
+  assert.match(r.reason, /401/);
+});
+
+test('classifyRulesetScope: 200 → readable, and NEVER claims edit scope is confirmed', () => {
+  const r = cf.classifyRulesetScope({
+    status: 200,
+    body: { success: true, result: { id: 'rs1', rules: [] } },
+    phase: PHASE,
+    zone: 'cloudbongos.com',
+  });
+  assert.equal(r.readable, true);
+  // HONESTY GATE: a GET proves READ, not EDIT. There must be no `editable` field,
+  // and the human-readable text must not read as a confirmed security control.
+  assert.equal('editable' in r, false, 'a read probe must never report an `editable` verdict');
+  assert.doesNotMatch(`${r.reason} ${r.guidance || ''}`, /scope confirmed|edit scope (is )?(confirmed|verified|present)/i);
+  assert.match(r.reason, /not proven|read/i, 'the reason must say edit scope is unproven');
+});
+
+test('classifyRulesetScope: 404 entrypoint → readable (an empty phase is legitimate)', () => {
+  const r = cf.classifyRulesetScope({
+    status: 404,
+    body: { success: false, errors: [{ message: 'ruleset not found' }] },
+    phase: PHASE,
+    zone: 'cloudbongos.com',
+  });
+  assert.equal(r.readable, true);
+});
+
+test('classifyRulesetScope: 500 → NOT readable, reported as inconclusive (never a pass)', () => {
+  const r = cf.classifyRulesetScope({ status: 500, body: null, phase: PHASE, zone: 'cloudbongos.com' });
+  assert.equal(r.readable, false);
+  assert.match(r.reason, /inconclusive|failed/i);
+});
+
+// ── checkRulesetScope: its OWN raw fetch, injectable, never a real call ─────
+test('checkRulesetScope: probes the phase entrypoint (NOT /user/tokens/verify) and reports readable', async () => {
+  const calls = [];
+  const fetchImpl = async (url, opts = {}) => {
+    calls.push({ url, auth: opts.headers.Authorization });
+    if (url.includes('/zones?name=')) return { status: 200, json: async () => ({ success: true, result: [{ id: 'zoneA', name: 'cloudbongos.com' }] }) };
+    return { status: 200, json: async () => ({ success: true, result: { id: 'rs1', rules: [] } }) };
+  };
+  const r = await cf.checkRulesetScope({ zone: 'cloudbongos.com', phase: PHASE, token: 'tok_1', fetchImpl });
+  assert.equal(r.readable, true);
+  assert.equal(r.zone, 'cloudbongos.com');
+  const probe = calls[calls.length - 1];
+  assert.match(probe.url, new RegExp(`/zones/zoneA/rulesets/phases/${PHASE}/entrypoint$`));
+  assert.equal(probe.auth, 'Bearer tok_1');
+  // An IP-locked token returns "Invalid API Token" from verify (builder-box-lifecycle
+  // learning) — the preflight must probe the real operation instead.
+  assert.ok(!calls.some((c) => /tokens\/verify/.test(c.url)), 'must not use /user/tokens/verify');
+});
+
+test('checkRulesetScope: 403 on the entrypoint → NOT readable + actionable guidance', async () => {
+  const fetchImpl = async (url) => {
+    if (url.includes('/zones?name=')) return { status: 200, json: async () => ({ success: true, result: [{ id: 'zoneA', name: 'cloudbongos.com' }] }) };
+    return { status: 403, json: async () => ({ success: false, errors: [{ message: 'Actor does not have permission' }] }) };
+  };
+  const r = await cf.checkRulesetScope({ zone: 'cloudbongos.com', phase: PHASE, token: 'tok_1', fetchImpl });
+  assert.equal(r.readable, false);
+  assert.match(r.guidance, /Transform Rules/);
+  assert.match(r.guidance, /cloudbongos\.com/);
+});
+
+test('checkRulesetScope: a known zoneId skips the zone lookup (one call only)', async () => {
+  const calls = [];
+  const fetchImpl = async (url) => {
+    calls.push(url);
+    return { status: 200, json: async () => ({ success: true, result: { id: 'rs1', rules: [] } }) };
+  };
+  const r = await cf.checkRulesetScope({ zone: 'cloudbongos.com', phase: PHASE, token: 'tok_1', zoneId: 'zoneGiven', fetchImpl });
+  assert.equal(r.readable, true);
+  assert.equal(calls.length, 1);
+  assert.match(calls[0], /\/zones\/zoneGiven\/rulesets\//);
+});
+
+test('checkRulesetScope: no token → NOT readable, and ZERO network calls', async () => {
+  let called = false;
+  const fetchImpl = async () => { called = true; return { status: 200, json: async () => ({}) }; };
+  const r = await cf.checkRulesetScope({ zone: 'cloudbongos.com', phase: PHASE, token: '', fetchImpl });
+  assert.equal(r.readable, false);
+  assert.match(r.reason, /no CLOUDFLARE_API_TOKEN/);
+  assert.equal(called, false);
+});
+
+test('checkRulesetScope: a thrown fetch is caught → NOT readable, never throws', async () => {
+  const fetchImpl = async () => { throw new Error('ENETUNREACH'); };
+  const r = await cf.checkRulesetScope({ zone: 'cloudbongos.com', phase: PHASE, token: 'tok', fetchImpl });
+  assert.equal(r.readable, false);
+  assert.match(r.reason, /failed/i);
+});
+
+test('checkRulesetScope: the zone lookup rejecting the token → NOT readable', async () => {
+  const fetchImpl = async () => ({ status: 403, json: async () => ({ success: false, errors: [{ message: 'Invalid API Token' }] }) });
+  const r = await cf.checkRulesetScope({ zone: 'cloudbongos.com', phase: PHASE, token: 'tok', fetchImpl });
+  assert.equal(r.readable, false);
+  assert.match(r.guidance, /CLOUDFLARE_API_TOKEN/);
+});

package/tests/cf_tunnel.mjs

@@ -373,6 +373,10 @@ await ta('ensureCookieStripRule failure does NOT block ensureNamedTunnel (best-e
   const r = await cf.ensureNamedTunnel({ login: 'carol', zone: 'amazonprimea.com', terminalZone: 'amazonprimea.com' });
   assert.equal(r.token, 'tokZ', 'provisioning completes despite the cookie-strip rule failing');
   assert.equal(r.hostname, 'term-carol.amazonprimea.com');
+  // task 1002511: the failure is reported STRUCTURALLY, not only logged, so box.js
+  // can surface it in the provision summary instead of burying it mid-run.
+  assert.equal(r.edgeRules.cookieStrip.applied, false, 'a failed cookie-strip PUT must never report applied');
+  assert.ok(r.edgeRules.cookieStrip.error, 'the failure reason is captured');
 });
 
 console.log('edge cache bypass (#1065):');
@@ -446,6 +450,39 @@ await ta('ensureCacheBypassRule failure does NOT block ensureNamedTunnel (best-e
   const cf = new CfTunnelApi({ dryRun: false, token: TOKEN, accountId: ACCT, fetchImpl });
   const r = await cf.ensureNamedTunnel({ login: 'carol', zone: 'amazonprimea.com', terminalZone: 'amazonprimea.com' });
   assert.equal(r.token, 'tokZ', 'provisioning completes despite the cache rule failing');
+  assert.equal(r.edgeRules.cacheBypass.applied, false);
+  assert.ok(r.edgeRules.cacheBypass.error, 'the cache-rule failure reason is captured');
+});
+
+await ta('ensureNamedTunnel reports edgeRules.applied on the success path (both legs land)', async () => {
+  const RS = '/zones/zoneZ/rulesets/phases/http_request_late_transform/entrypoint';
+  const CS = '/zones/zoneZ/rulesets/phases/http_request_cache_settings/entrypoint';
+  const { fetchImpl } = makeFetch({
+    'GET /accounts/acct123/cfd_tunnel': () => [],
+    'POST /accounts/acct123/cfd_tunnel': ({ body }) => ({ id: 'tunZ', name: body.name }),
+    'PUT /accounts/acct123/cfd_tunnel/tunZ/configurations': ({ body }) => ({ config: body.config }),
+    'GET /accounts/acct123/cfd_tunnel/tunZ/token': () => 'tokZ',
+    'GET /zones': () => [{ id: 'zoneZ' }],
+    'GET /zones/zoneZ/dns_records': () => [],
+    'POST /zones/zoneZ/dns_records': ({ body }) => ({ id: `rec-${body.name}`, ...body }),
+    [`GET ${RS}`]: () => ({ id: 'rs1', rules: [] }),
+    [`PUT ${RS}`]: ({ body }) => ({ id: 'rs1', rules: body.rules }),
+    [`GET ${CS}`]: () => ({ id: 'rs2', rules: [] }),
+    [`PUT ${CS}`]: ({ body }) => ({ id: 'rs2', rules: body.rules }),
+  });
+  const cf = new CfTunnelApi({ dryRun: false, token: TOKEN, accountId: ACCT, fetchImpl });
+  const r = await cf.ensureNamedTunnel({ login: 'carol', zone: 'amazonprimea.com', terminalZone: 'amazonprimea.com' });
+  assert.equal(r.edgeRules.cookieStrip.applied, true);
+  assert.equal(r.edgeRules.cookieStrip.error, null);
+  assert.equal(r.edgeRules.cacheBypass.applied, true);
+  assert.equal(r.token, 'tokZ', 'the bake values still come back');
+});
+
+await ta('ensureNamedTunnel in DRY-RUN reports applied:false (a plan never applied anything)', async () => {
+  const cf = new CfTunnelApi({ accountId: ACCT, fetchImpl: () => { throw new Error('should not fetch'); } });
+  const r = await cf.ensureNamedTunnel({ login: 'alice', zone: 'amazonprimea.com', terminalZone: 'amazonprimea.com' });
+  assert.equal(r.edgeRules.cookieStrip.applied, false, 'dry-run must not read as "the security rule is in place"');
+  assert.equal(r.edgeRules.cacheBypass.applied, false);
 });
 
 console.log('name helpers:');

package/tests/claim_gate_rebase.mjs

@@ -0,0 +1,98 @@
+// tests/claim_gate_rebase.mjs — ADR 0120 part 3 (real DB).
+//
+// The needs_rebase claim gate: a builder who owes a rebase on an un-landed
+// confirmed task is refused NEW claims (409 REBASE_REQUIRED, naming the
+// offending task) until they land or release it. claimTask runs a real
+// BEGIN/FOR UPDATE transaction with many queries, so this is a real-DB
+// integration test (self-skips without a reachable Postgres; also in the
+// INTEGRATION set so the default DB-free lane never runs it).
+//
+// Run:  DATABASE_URL=... node tests/claim_gate_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 });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`claim_gate_rebase.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  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-CG', WORKER = 90000201, STALLED = 90000201, FRESH = 90000202;
+const q = (sql, params) => pool.query(sql, params).then((r) => r.rows);
+
+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 = ANY($2::bigint[])`, [WORKER, [STALLED, FRESH]]).catch(() => {});
+  await q(`DELETE FROM claims WHERE task_id = ANY($1::bigint[])`, [[STALLED, FRESH]]).catch(() => {});
+  await q(`DELETE FROM tasks WHERE id = ANY($1::bigint[])`, [[STALLED, FRESH]]).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,'cg','planning','internal') ON CONFLICT (id) DO NOTHING`, [VER]);
+  // Archon so no rank/newcomer gate interferes; the gate under test is REBASE_REQUIRED.
+  await q(`INSERT INTO builders (id,github_id,github_login,display_name,rank) VALUES ($1,'cg-w','cg-worker','CG Worker','archon')`, [WORKER]);
+  // STALLED: a confirmed task owned by WORKER, flagged needs_rebase.
+  await q(`INSERT INTO tasks (id,version_id,title,status,credits_reward,kind,shipped_by) VALUES ($1,$2,'stalled','confirmed',10,'feature',$3)`, [STALLED, VER, WORKER]);
+  await q(`INSERT INTO claims (task_id,builder_id,claimed_at) VALUES ($1,$2, now())`, [STALLED, WORKER]);
+  await db.flagTaskNeedsRebase(String(STALLED), 'strand:no_branch_no_tip');
+  // FRESH: a ready, claimable task the worker will try to pick up.
+  await q(`INSERT INTO tasks (id,version_id,title,status,credits_reward,kind) VALUES ($1,$2,'fresh','ready',10,'feature')`, [FRESH, VER]);
+
+  // 1) With STALLED flagged, claiming FRESH is refused with REBASE_REQUIRED.
+  let threw = null;
+  try {
+    await db.claimTask({ taskId: String(FRESH), builderId: String(WORKER), worktreeName: 'cg-fresh' });
+  } catch (e) { threw = e; }
+  ok(threw && threw.code === 'REBASE_REQUIRED', `claim refused with REBASE_REQUIRED (got ${threw && (threw.code || threw.message)})`);
+  ok(Array.isArray(threw.rebaseTasks) && threw.rebaseTasks.some((t) => Number(t.id) === STALLED),
+    'the 409 names the offending stalled task');
+  // FRESH must be untouched (still ready, unclaimed).
+  const freshStatus = (await q(`SELECT status FROM tasks WHERE id=$1`, [FRESH]))[0].status;
+  ok(freshStatus === 'ready', 'the refused task stays ready (no partial claim)');
+
+  // ADR 0120 part 5: the SAME owed-rebase read, reached through the `lifecycle`
+  // kernel PORT — the exact wire the /me route resolves so the CLI (/builder-start)
+  // + the hall can surface the gate. Proves the port delegates to db and returns
+  // the fields those surfaces render.
+  const lifecycle = require('../modules/lifecycle/lifecycle.js');
+  const owedViaPort = await lifecycle.needsRebaseTasksForBuilder(String(WORKER));
+  ok(owedViaPort.some((t) => Number(t.id) === STALLED),
+    'the lifecycle port surfaces the owed rebase (the /me → CLI/hall read path)');
+  ok(owedViaPort.every((t) => 'title' in t && 'needs_rebase_reason' in t && 'needs_rebase_at' in t),
+    'each owed row carries the fields the CLI + hall render');
+
+  // 2) Landing the stalled task clears the flag → the gate opens.
+  await db.shipTask({ taskId: String(STALLED), builderId: String(WORKER) });
+  const stalledFlag = (await q(`SELECT needs_rebase FROM tasks WHERE id=$1`, [STALLED]))[0].needs_rebase;
+  ok(stalledFlag === false, 'shipping the stalled task cleared needs_rebase');
+
+  // 3) Now the claim succeeds.
+  const claim = await db.claimTask({ taskId: String(FRESH), builderId: String(WORKER), worktreeName: 'cg-fresh' });
+  ok(claim && claim.id && Number(claim.task_id) === FRESH, 'claim succeeds once the rebase chore is cleared');
+  const activeClaim = (await q(`SELECT builder_id FROM claims WHERE task_id=$1 AND released_at IS NULL`, [FRESH]))[0];
+  ok(activeClaim && Number(activeClaim.builder_id) === WORKER, 'the worker now holds an active claim on the task');
+
+  console.log(`\nclaim_gate_rebase (ADR 0120 part 3): ${pass} passed, 0 failed`);
+} catch (e) {
+  console.error('claim_gate_rebase.mjs FAILED:', e.stack || e.message);
+  process.exitCode = 1;
+} finally {
+  await cleanup();
+  await pool.end();
+}

package/tests/clawback_confirmed_backlog.mjs

@@ -0,0 +1,103 @@
+// tests/clawback_confirmed_backlog.mjs — ADR 0120 part 4 (real DB).
+//
+// Runs the ACTUAL migration SQL (migrations/core_194_confirmed_backlog_clawback.sql)
+// against seeded fixtures and asserts the one-time clawback + re-gate:
+//   • each STILL-CONFIRMED task's task.confirmed credit is reversed (a negative
+//     task.confirmed_reversal row) and builders.total_credits nets back down,
+//   • those tasks are flagged needs_rebase='clawback:confirmed_backlog',
+//   • a SHIPPED task (legitimately landed) is left completely untouched,
+//   • the migration is idempotent (a second run books nothing new).
+//
+// Real-DB integration test: self-skips without a reachable Postgres; also in the
+// INTEGRATION set so the default DB-free lane never runs it.
+//
+// Run:  DATABASE_URL=... node tests/clawback_confirmed_backlog.mjs
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MIGRATION_SQL = readFileSync(join(here, '..', 'migrations', 'core_194_confirmed_backlog_clawback.sql'), 'utf8');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`clawback_confirmed_backlog.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const VER = 'ZZZ-CB', A = 90000301, B = 90000302, T_A = 90000301, T_B = 90000302, T_S = 90000303;
+const q = (sql, params) => pool.query(sql, params).then((r) => r.rows);
+const total = async (id) => Number((await q(`SELECT total_credits FROM builders WHERE id=$1`, [id]))[0]?.total_credits ?? 0);
+const reversals = async (taskId) => q(`SELECT delta FROM credit_log WHERE task_id=$1 AND reason='task.confirmed_reversal'`, [taskId]);
+const flag = async (taskId) => (await q(`SELECT needs_rebase, needs_rebase_reason FROM tasks WHERE id=$1`, [taskId]))[0];
+
+async function cleanup() {
+  await q(`DELETE FROM builder_achievements WHERE builder_id = ANY($1::bigint[])`, [[A, B]]).catch(() => {});
+  await q(`DELETE FROM credit_log WHERE builder_id = ANY($1::bigint[]) OR task_id = ANY($2::bigint[])`, [[A, B], [T_A, T_B, T_S]]).catch(() => {});
+  await q(`DELETE FROM tasks WHERE id = ANY($1::bigint[])`, [[T_A, T_B, T_S]]).catch(() => {});
+  await q(`DELETE FROM builders WHERE id = ANY($1::bigint[])`, [[A, B]]).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,'cb','planning','internal') ON CONFLICT (id) DO NOTHING`, [VER]);
+  await q(`INSERT INTO builders (id,github_id,github_login,display_name,rank) VALUES
+           ($1,'cb-a','cb-a','CB A','thetes'), ($2,'cb-b','cb-b','CB B','thetes')`, [A, B]);
+  // Two still-confirmed tasks (unlanded) + one legitimately shipped task.
+  await q(`INSERT INTO tasks (id,version_id,title,status,credits_reward,kind,shipped_by) VALUES
+           ($1,$4,'confirmed A','confirmed',20,'feature',$2),
+           ($5,$4,'confirmed B','confirmed',15,'feature',$3),
+           ($6,$4,'shipped legit','shipped',30,'feature',$2)`, [T_A, A, B, VER, T_B, T_S]);
+  // Seed the credits the OLD confirm-time rule would have paid (credit_log INSERT
+  // fires the total_credits trigger, exactly like a real award).
+  await q(`INSERT INTO credit_log (builder_id,task_id,delta,reason,description) VALUES
+           ($1,$2,20,'task.confirmed','seed A'),
+           ($3,$4,15,'task.confirmed','seed B'),
+           ($1,$5,30,'task.shipped','seed shipped-legit')`, [A, T_A, B, T_B, T_S]);
+
+  ok(await total(A) === 50, 'seed: builder A total_credits = 50 (20 confirmed + 30 shipped)');
+  ok(await total(B) === 15, 'seed: builder B total_credits = 15 (confirmed)');
+
+  // ---- run the ACTUAL migration ----
+  await pool.query(MIGRATION_SQL);
+
+  // 1. Reversals booked for the confirmed tasks, NOT the shipped one.
+  const rA = await reversals(T_A), rB = await reversals(T_B), rS = await reversals(T_S);
+  ok(rA.length === 1 && Number(rA[0].delta) === -20, 'confirmed task A: one -20 reversal');
+  ok(rB.length === 1 && Number(rB[0].delta) === -15, 'confirmed task B: one -15 reversal');
+  ok(rS.length === 0, 'the SHIPPED task is NOT clawed back (legitimately landed)');
+
+  // 2. total_credits netted back down by the reversed amounts.
+  ok(await total(A) === 30, 'builder A total_credits 50 → 30 (confirmed credit reversed, shipped kept)');
+  ok(await total(B) === 0, 'builder B total_credits 15 → 0');
+
+  // 3. Confirmed tasks re-gated; shipped task untouched.
+  ok((await flag(T_A)).needs_rebase === true && (await flag(T_A)).needs_rebase_reason === 'clawback:confirmed_backlog', 'task A flagged needs_rebase (clawback)');
+  ok((await flag(T_B)).needs_rebase === true, 'task B flagged needs_rebase');
+  ok((await flag(T_S)).needs_rebase === false, 'the shipped task is NOT flagged');
+
+  // 4. Idempotent — a second run books nothing new.
+  await pool.query(MIGRATION_SQL);
+  ok((await reversals(T_A)).length === 1, 'idempotent: still exactly one reversal for task A after a second run');
+  ok(await total(A) === 30, 'idempotent: builder A total_credits unchanged on re-run');
+
+  console.log(`\nclawback_confirmed_backlog (ADR 0120 part 4): ${pass} passed, 0 failed`);
+} catch (e) {
+  console.error('clawback_confirmed_backlog.mjs FAILED:', e.stack || e.message);
+  process.exitCode = 1;
+} finally {
+  await cleanup();
+  await pool.end();
+}

package/tests/cli_lib_formatters.mjs

@@ -46,6 +46,26 @@ test('fmtUsd: two-decimal dollar string', () => {
   assert.equal(cli.fmtUsd(1.239), '$1.24');      // rounds via toFixed
 });
 
+// hallBase(base) — the builders'-hall root for a given API base (task 1002233).
+// Pass an explicit base so the test never depends on the module-load env.
+test('hallBase: derives the hall root from the base URL origin (path/query dropped)', () => {
+  assert.equal(cli.hallBase('https://cloudbongos.com'), 'https://cloudbongos.com/builders');
+  assert.equal(cli.hallBase('https://cloudbongos.com/'), 'https://cloudbongos.com/builders');
+  assert.equal(cli.hallBase('https://inst.example/api/gds'), 'https://inst.example/builders');
+  assert.equal(cli.hallBase('http://localhost:3000'), 'http://localhost:3000/builders');
+});
+
+test('hallBase: reflects whatever base it is given — no hardcoded founder host', () => {
+  const out = cli.hallBase('https://staging.example.org');
+  assert.equal(out, 'https://staging.example.org/builders');
+  assert.ok(!/amazonprimea/.test(out), 'must not reintroduce a hardcoded amazonprimea host');
+});
+
+test('hallBase: a non-URL base falls back to `${base}/builders` (never throws)', () => {
+  assert.equal(cli.hallBase('not a url'), 'not a url/builders');
+  assert.equal(cli.hallBase(''), '/builders');
+});
+
 test('fmtUsd: null renders the em-dash placeholder (edge)', () => {
   assert.equal(cli.fmtUsd(null), '—');
 });