@bongos/core 1.18.0 → 1.18.18

package/tests/branding.mjs

@@ -19,12 +19,15 @@ const NEUTRAL = {
   envPrefix: 'CLOUDBONGOS',
 };
 
-const OTB = {
-  identity: { productName: 'Off the Boats', worldName: 'Amazonprimea', company: { name: 'Hermeslines', site: 'https://hermeslines.com' } },
-  llmProjectName: 'Off the Boats',
-  domains: { publicOrigin: 'https://amazonprimea.com', cookieDomain: '.amazonprimea.com' },
-  currency: { label: 'drachmae' },
-  envPrefix: 'OTB',
+// A GENERIC sample instance pack — exercises the resolver's override/merge/precedence logic
+// without baking any real instance's identity into the (published) test. (task 1002219 / audit H5:
+// swept the former customer-1 sample — Off the Boats / amazonprimea / Hermeslines — to neutral.)
+const SAMPLE = {
+  identity: { productName: 'Acme Rockets', worldName: 'Acme', company: { name: 'Acme Corp', site: 'https://acme.example' } },
+  llmProjectName: 'Acme Rockets',
+  domains: { publicOrigin: 'https://acme.example', cookieDomain: '.acme.example' },
+  currency: { label: 'tokens' },
+  envPrefix: 'ACME',
 };
 
 test('neutral starter resolves to the plain identity (no host leak)', () => {
@@ -34,33 +37,42 @@ test('neutral starter resolves to the plain identity (no host leak)', () => {
 });
 
 test('instance config overrides the neutral starter, deep-merged', () => {
-  const b = resolveBranding({ neutral: NEUTRAL, instance: OTB });
-  assert.equal(b.identity.worldName, 'Amazonprimea');
-  assert.equal(b.identity.company.name, 'Hermeslines');
-  assert.equal(b.domains.cookieDomain, '.amazonprimea.com');
+  const b = resolveBranding({ neutral: NEUTRAL, instance: SAMPLE });
+  assert.equal(b.identity.worldName, 'Acme');
+  assert.equal(b.identity.company.name, 'Acme Corp');
+  assert.equal(b.domains.cookieDomain, '.acme.example');
   // a field present only in neutral survives the merge:
   assert.equal(b.domains.buildersOrigin, 'http://localhost:3000');
 });
 
 test('env override beats instance config (precedence)', () => {
-  const b = resolveBranding({ neutral: NEUTRAL, instance: OTB, env: { OTB_PUBLIC_ORIGIN: 'https://staging.example.com' } });
+  const b = resolveBranding({ neutral: NEUTRAL, instance: SAMPLE, env: { ACME_PUBLIC_ORIGIN: 'https://staging.example.com' } });
   assert.equal(b.domains.publicOrigin, 'https://staging.example.com');
 });
 
 test('env override is ignored when empty', () => {
-  const b = resolveBranding({ neutral: NEUTRAL, instance: OTB, env: { OTB_PUBLIC_ORIGIN: '' } });
-  assert.equal(b.domains.publicOrigin, 'https://amazonprimea.com');
+  const b = resolveBranding({ neutral: NEUTRAL, instance: SAMPLE, env: { ACME_PUBLIC_ORIGIN: '' } });
+  assert.equal(b.domains.publicOrigin, 'https://acme.example');
 });
 
 test('provisioningOrigin: optional, passes through config, env-overridable (task 2101)', () => {
   // Not required — unset resolves to undefined, and callers fall back to publicOrigin.
-  assert.equal(resolveBranding({ neutral: NEUTRAL, instance: OTB }).domains.provisioningOrigin, undefined);
+  assert.equal(resolveBranding({ neutral: NEUTRAL, instance: SAMPLE }).domains.provisioningOrigin, undefined);
   // Set in the instance pack, it survives the deep-merge.
-  const inst = resolveBranding({ neutral: NEUTRAL, instance: { ...OTB, domains: { ...OTB.domains, provisioningOrigin: 'https://get.cloudbongos.com' } } });
-  assert.equal(inst.domains.provisioningOrigin, 'https://get.cloudbongos.com');
+  const inst = resolveBranding({ neutral: NEUTRAL, instance: { ...SAMPLE, domains: { ...SAMPLE.domains, provisioningOrigin: 'https://get.acme.example' } } });
+  assert.equal(inst.domains.provisioningOrigin, 'https://get.acme.example');
   // And <PREFIX>_PROVISIONING_ORIGIN beats config (same precedence as the other origins).
-  const env = resolveBranding({ neutral: NEUTRAL, instance: OTB, env: { OTB_PROVISIONING_ORIGIN: 'https://get.cloudbongos.com' } });
-  assert.equal(env.domains.provisioningOrigin, 'https://get.cloudbongos.com');
+  const env = resolveBranding({ neutral: NEUTRAL, instance: SAMPLE, env: { ACME_PROVISIONING_ORIGIN: 'https://get.acme.example' } });
+  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', () => {
@@ -80,16 +92,22 @@ test('deepMerge does not mutate its inputs', () => {
   assert.deepEqual(out, { a: { x: 1, y: 2 } });
 });
 
-test('the committed neutral + OTB packs load and resolve (this repo = customer 1)', () => {
+test('the committed neutral pack loads + resolves to the neutral identity (the trunk carries no instance branding.json)', () => {
+  // The neutral trunk ships config/branding.neutral.json only — no config/branding.json — so
+  // loadBranding resolves to the plain Cloud Bongos identity (task 1002219 / audit H5: this used to
+  // assert the customer-1 OTB identity, stale since the amazonprimea→cloudbongos rebrand, ADR 0139/0140).
   const b = loadBranding({ env: {} });
-  assert.equal(b.identity.productName, 'Off the Boats');
-  assert.ok(b.domains.publicOrigin.startsWith('https://amazonprimea.com'));
-  assert.equal(b.identity.worldName, 'Amazonprimea');
+  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)', () => {
   const neutral = structuredClone(NEUTRAL);
-  const instance = structuredClone(OTB);
+  const instance = structuredClone(SAMPLE);
   resolveBranding({ neutral, instance });
   assert.equal(Object.isFrozen(neutral), false);
   assert.equal(Object.isFrozen(neutral.domains), false);

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), '—');
 });