@bongos/core 1.17.0

package/tests/onboarding_state.mjs

@@ -0,0 +1,346 @@
+// tests/onboarding_state.mjs
+//
+// V3.R75 (#294) — Unit tests for the auto-completing onboarding state
+// machine. Exercises the pure helpers (nextStage, shapeForApi, markStage)
+// against a mock pg client. The DB-touching path (real markStage against
+// the table) is covered by post-deploy smoke; this file runs in any
+// environment without a live Postgres.
+//
+// Run:  node tests/onboarding_state.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const onboarding = require('../modules/onboarding/onboarding-state.js');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    const r = fn();
+    if (r && typeof r.then === 'function') {
+      return r.then(
+        () => { passed += 1; console.log(`  ok  ${name}`); },
+        (err) => { failed += 1; console.log(`  FAIL  ${name}\n      ${err.message}`); }
+      );
+    }
+    passed += 1; console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed += 1; console.log(`  FAIL  ${name}\n      ${err.message}`);
+  }
+}
+
+// ---- nextStage ------------------------------------------------------------
+
+test('nextStage: empty completed → first stage', () => {
+  assert.equal(onboarding.nextStage([]), 'auth_complete');
+});
+
+test('nextStage: undefined → first stage (defensive)', () => {
+  assert.equal(onboarding.nextStage(undefined), 'auth_complete');
+});
+
+test('nextStage: only auth → pick_disciplines next', () => {
+  assert.equal(onboarding.nextStage(['auth_complete']), 'pick_disciplines');
+});
+
+test('nextStage: out-of-order set picks first GAP, not last+1', () => {
+  // ship_three cleared but earlier stages not — the canonical "next" is the
+  // earliest uncleared stage, NOT one past the latest cleared. This is what
+  // legacy backfilled rows look like (first_ship_at set without ever firing
+  // first_start), and the UI needs the right "current" highlighting.
+  assert.equal(
+    onboarding.nextStage(['auth_complete', 'first_claim', 'ship_three']),
+    'pick_disciplines'
+  );
+});
+
+test('nextStage: all stages cleared → graduated', () => {
+  assert.equal(onboarding.nextStage(onboarding.STAGES), 'graduated');
+});
+
+// ---- isKnownStage ---------------------------------------------------------
+
+test('isKnownStage: real stages all pass', () => {
+  for (const s of onboarding.ALL_STAGES) {
+    assert.equal(onboarding.isKnownStage(s), true, `expected ${s} to be known`);
+  }
+});
+
+test('isKnownStage: typo rejected', () => {
+  assert.equal(onboarding.isKnownStage('frist_ship'), false);
+  assert.equal(onboarding.isKnownStage(''), false);
+  assert.equal(onboarding.isKnownStage(null), false);
+});
+
+// ---- shapeForApi (displayed checklist, #777) ------------------------------
+//
+// shapeForApi returns the DISPLAYED 5-step "Path into the City"
+// (box_connect, join_discord, pick_disciplines, cli_setup, ship_three) — split
+// from the engine STAGES so NONE of the displayed steps affect graduation.
+// `graduated` and `current_stage` still reflect the engine. box_connect/
+// join_discord/cli_setup are auto-derived from `boxConnected`/`discordLinked`/
+// `cliAuthed` (no manual ticks, #823/#777).
+
+const DISPLAY_ORDER = ['box_connect', 'join_discord', 'pick_disciplines', 'cli_setup', 'ship_three'];
+
+test('shapeForApi: null row → 5-step displayed shape in order', () => {
+  const out = onboarding.shapeForApi(null);
+  assert.equal(out.current_stage, 'auth_complete'); // engine stage still surfaced
+  assert.deepEqual(out.completed_stages, []);
+  assert.equal(out.graduated, false);
+  assert.equal(out.progress.cleared, 0);
+  assert.equal(out.progress.total, 5);
+  assert.deepEqual(out.stages.map((s) => s.id), DISPLAY_ORDER);
+  assert.equal(out.stages[0].is_current, true); // box_connect, first gap
+  assert.equal(out.stages[0].cleared, false);
+  assert.equal(out.stages[0].source, 'box');
+  assert.equal(out.stages[1].source, 'discord'); // join_discord
+  assert.equal(out.stages[2].source, 'stage'); // pick_disciplines is a real stage
+  assert.equal(out.stages[3].source, 'cli'); // cli_setup
+});
+
+test('shapeForApi: partial row → cleared flags + is_current points at first displayed gap', () => {
+  const out = onboarding.shapeForApi({
+    current_stage: 'first_claim',
+    completed_stages: ['auth_complete', 'pick_disciplines', 'first_start'],
+    started_at: '2026-05-01T00:00:00Z',
+    completed_at: null,
+  });
+  assert.equal(out.graduated, false);
+  const byId = Object.fromEntries(out.stages.map((s) => [s.id, s]));
+  // pick_disciplines is the only displayed step the engine has cleared.
+  assert.equal(byId.pick_disciplines.cleared, true);
+  assert.equal(byId.box_connect.cleared, false);   // no box connection
+  assert.equal(byId.cli_setup.cleared, false);     // no cli auth
+  assert.equal(byId.join_discord.cleared, false);  // no link
+  assert.equal(byId.ship_three.cleared, false);
+  // First displayed gap is box_connect (it sorts before the cleared craft step).
+  assert.equal(byId.box_connect.is_current, true);
+  assert.equal(byId.pick_disciplines.is_current, false);
+  assert.equal(out.progress.cleared, 1);
+});
+
+test('shapeForApi: box_connect clears from boxConnected; is_current advances to join_discord', () => {
+  const out = onboarding.shapeForApi(
+    { current_stage: 'auth_complete', completed_stages: ['auth_complete'] },
+    { boxConnected: true }
+  );
+  const byId = Object.fromEntries(out.stages.map((s) => [s.id, s]));
+  assert.equal(byId.box_connect.cleared, true);
+  // Next gap is now join_discord (no link supplied).
+  assert.equal(byId.join_discord.is_current, true);
+});
+
+test('shapeForApi: cli_setup (step 4) clears from cliAuthed; box_connect stays first gap without a connection', () => {
+  const out = onboarding.shapeForApi(
+    { current_stage: 'auth_complete', completed_stages: ['auth_complete'] },
+    { cliAuthed: true }
+  );
+  const byId = Object.fromEntries(out.stages.map((s) => [s.id, s]));
+  assert.equal(byId.cli_setup.cleared, true);
+  assert.equal(byId.box_connect.cleared, false);
+  // box_connect is still the first gap (it precedes the cleared cli step).
+  assert.equal(byId.box_connect.is_current, true);
+});
+
+test('shapeForApi: box_connect and cli_setup are independent signals', () => {
+  // Connected to the box but CLI not yet authenticated — only box_connect ticks.
+  const out = onboarding.shapeForApi(
+    { current_stage: 'auth_complete', completed_stages: ['auth_complete'] },
+    { boxConnected: true, cliAuthed: false }
+  );
+  const byId = Object.fromEntries(out.stages.map((s) => [s.id, s]));
+  assert.equal(byId.box_connect.cleared, true);
+  assert.equal(byId.cli_setup.cleared, false);
+  // box_connect clears, but cli_setup (step 4) stays open on its own signal.
+  assert.equal(byId.box_connect.is_current, false);
+});
+
+test('shapeForApi: join_discord clears from a live Discord link; box_connect stays first gap without a connection', () => {
+  const out = onboarding.shapeForApi(
+    { current_stage: 'auth_complete', completed_stages: ['auth_complete'] },
+    { discordLinked: true }
+  );
+  const byId = Object.fromEntries(out.stages.map((s) => [s.id, s]));
+  assert.equal(byId.join_discord.cleared, true);
+  assert.equal(byId.box_connect.cleared, false);
+  // box_connect is still the first gap (it precedes the cleared discord step).
+  assert.equal(byId.box_connect.is_current, true);
+});
+
+test('shapeForApi: graduated row → all displayed steps cleared, none current (regardless of derived signals)', () => {
+  const out = onboarding.shapeForApi({
+    current_stage: 'graduated',
+    completed_stages: onboarding.STAGES,
+    started_at: '2026-05-01T00:00:00Z',
+    completed_at: '2026-05-05T00:00:00Z',
+  }, { discordLinked: false, boxConnected: false, cliAuthed: false }); // proves display steps don't gate graduation
+  assert.equal(out.graduated, true);
+  assert.equal(out.progress.cleared, 5);
+  assert.equal(out.progress.total, 5);
+  assert.ok(out.stages.every((s) => s.cleared === true));
+  assert.ok(out.stages.every((s) => s.is_current === false));
+});
+
+// ---- shapeForApi ship counter (#766) --------------------------------------
+
+test('shapeForApi: ship_three carries an "N of 3" detail when shipCount given', () => {
+  const out = onboarding.shapeForApi(
+    { current_stage: 'ship_three', completed_stages: ['auth_complete', 'pick_disciplines', 'first_start', 'first_claim'] },
+    { shipCount: 1 }
+  );
+  const byId = Object.fromEntries(out.stages.map((s) => [s.id, s]));
+  assert.equal(byId.ship_three.detail, '1 of 3 works shipped');
+  // Non-terminal displayed steps never carry a detail line.
+  assert.equal(byId.join_discord.detail, '');
+});
+
+test('shapeForApi: ship counter clamps to the 3-ship target and omits when absent', () => {
+  const clamped = onboarding.shapeForApi(
+    { current_stage: 'ship_three', completed_stages: [] },
+    { shipCount: 9 }
+  );
+  assert.equal(clamped.stages.find((s) => s.id === 'ship_three').detail, '3 of 3 works shipped');
+  // No shipCount → no counter rendered (empty detail).
+  const noCount = onboarding.shapeForApi({ current_stage: 'ship_three', completed_stages: [] });
+  assert.equal(noCount.stages.find((s) => s.id === 'ship_three').detail, '');
+});
+
+// ---- markStage (against a mock client) ------------------------------------
+//
+// The mock client mimics enough of pg's query() to drive the markStage
+// branches: SELECT existing → UPDATE existing OR INSERT new. Stores a
+// single in-memory row per builder.
+
+function makeMockClient() {
+  const state = new Map();
+  return {
+    state,
+    async query(sql, params) {
+      if (/^SELECT/i.test(sql)) {
+        const id = params[0];
+        const row = state.get(id);
+        return { rows: row ? [row] : [] };
+      }
+      if (/^UPDATE builder_onboarding_state/i.test(sql)) {
+        const [id, completed, current, justGrad] = params;
+        const existing = state.get(id);
+        const next = {
+          ...existing,
+          completed_stages: completed,
+          current_stage: current,
+          completed_at: justGrad ? new Date().toISOString() : existing.completed_at,
+        };
+        state.set(id, next);
+        return { rows: [next] };
+      }
+      if (/^INSERT INTO builder_onboarding_state/i.test(sql)) {
+        const [id, current, completed] = params;
+        if (state.has(id)) return { rows: [] }; // simulate ON CONFLICT DO NOTHING
+        const row = {
+          builder_id: id,
+          current_stage: current,
+          completed_stages: completed,
+          started_at: new Date().toISOString(),
+          completed_at: null,
+        };
+        state.set(id, row);
+        return { rows: [row] };
+      }
+      throw new Error(`unexpected query: ${sql.slice(0, 60)}`);
+    },
+  };
+}
+
+test('markStage: first call on a fresh builder creates the row', async () => {
+  const c = makeMockClient();
+  const out = await onboarding.markStage(c, 42, 'auth_complete');
+  assert.equal(out.alreadyCleared, false);
+  assert.equal(out.justGraduated, false);
+  assert.equal(out.state.current_stage, 'pick_disciplines');
+  assert.deepEqual(out.state.completed_stages, ['auth_complete']);
+});
+
+test('markStage: repeating the same stage is a no-op (alreadyCleared)', async () => {
+  const c = makeMockClient();
+  await onboarding.markStage(c, 42, 'auth_complete');
+  const second = await onboarding.markStage(c, 42, 'auth_complete');
+  assert.equal(second.alreadyCleared, true);
+  assert.equal(second.justGraduated, false);
+  assert.deepEqual(second.state.completed_stages, ['auth_complete']);
+});
+
+test('markStage: out-of-order events still tick the right stage', async () => {
+  // Skip pick_disciplines entirely — first_start fires anyway (a builder can
+  // run /builder-start without picking a craft first). The state machine
+  // should record first_start but keep current_stage = pick_disciplines.
+  const c = makeMockClient();
+  await onboarding.markStage(c, 7, 'auth_complete');
+  const after = await onboarding.markStage(c, 7, 'first_start');
+  assert.equal(after.state.current_stage, 'pick_disciplines');
+  assert.deepEqual(
+    [...after.state.completed_stages].sort(),
+    ['auth_complete', 'first_start']
+  );
+});
+
+test('markStage: clearing the last stage flips current_stage to graduated', async () => {
+  const c = makeMockClient();
+  const stages = onboarding.STAGES;
+  for (const s of stages.slice(0, -1)) {
+    await onboarding.markStage(c, 9, s);
+  }
+  // Mark the final stage explicitly (ship_three, as of #766).
+  const result = await onboarding.markStage(c, 9, stages[stages.length - 1]);
+  assert.equal(result.justGraduated, true);
+  assert.equal(result.state.current_stage, 'graduated');
+  assert.ok(result.state.completed_at, 'completed_at should be set');
+});
+
+test('markStage: justGraduated only fires on the transition, not re-runs', async () => {
+  const c = makeMockClient();
+  for (const s of onboarding.STAGES) {
+    await onboarding.markStage(c, 11, s);
+  }
+  // Hitting any already-cleared stage afterwards must not re-fire graduation.
+  const echo = await onboarding.markStage(c, 11, 'ship_three');
+  assert.equal(echo.justGraduated, false);
+  assert.equal(echo.alreadyCleared, true);
+});
+
+test('markStage: unknown stage throws', async () => {
+  const c = makeMockClient();
+  await assert.rejects(
+    () => onboarding.markStage(c, 1, 'totally_bogus'),
+    /unknown stage/
+  );
+});
+
+// ---- #692 decoupling regression -------------------------------------------
+
+test('graduation is engine-only (display signals never gate it)', async () => {
+  // Drive the engine through all stages — no Discord link, no CLI auth.
+  const c = makeMockClient();
+  for (const s of onboarding.STAGES) {
+    await onboarding.markStage(c, 60, s);
+  }
+  const state = await onboarding.getState(c, 60);
+  assert.equal(state.current_stage, 'graduated');
+  // graduated:true even with discordLinked/boxConnected/cliAuthed false — proves
+  // the display-only steps never gate the xenos→thetes promotion (#692).
+  const shaped = onboarding.shapeForApi(state, { discordLinked: false, boxConnected: false, cliAuthed: false });
+  assert.equal(shaped.graduated, true);
+  assert.ok(shaped.stages.every((s) => s.cleared === true));
+});
+
+// ---- wrap-up --------------------------------------------------------------
+
+Promise.resolve().then(async () => {
+  // Give async tests a tick — Node will print results as they finish.
+  await new Promise((r) => setTimeout(r, 30));
+  console.log(`\n${passed} passed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+});

package/tests/one_active_claim_per_session.mjs

@@ -0,0 +1,111 @@
+// tests/one_active_claim_per_session.mjs
+//
+// task 1642 — one active claim per session (commingled-ship guard). Working 2+
+// tasks from one worktree lands every commit on the single branch that worktree
+// owns, so /builder-ship publishes the whole branch and drags the other task's
+// work. The cure: a CLI session may hold at most one active claim. This guards
+// the pure session-scoped decision shouldRefuseSessionClaim() — the route wires
+// it as a FAIL-CLOSED middleware; this exercises the decision DB-free.
+//
+// Run:  node tests/one_active_claim_per_session.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { shouldRefuseSessionClaim } = require('../modules/lifecycle/routes/claims.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// (a) A session that already holds an active claim is refused, naming the right
+//     in-flight task.
+t('session with an active claim is refused, correct inFlightTaskId', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-1',
+    activeClaimsForSession: [
+      { claim_id: 10, task_id: 42, creator_session_id: 'sess-1', title: 'Wire the thing' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.inFlightTaskId, 42);
+  assert.equal(d.inFlightTitle, 'Wire the thing');
+});
+
+// (b) A different session (no rows of its own) is allowed. The DB helper only
+//     returns same-session rows, but defence-in-depth: even a stray foreign row
+//     must not block.
+t('a different session is allowed (no own active claim)', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-2',
+    activeClaimsForSession: [],
+  });
+  assert.equal(d.refuse, false);
+  assert.equal(d.inFlightTaskId, null);
+});
+
+t('a foreign-session row never blocks (defence in depth)', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-2',
+    activeClaimsForSession: [
+      { claim_id: 11, task_id: 99, creator_session_id: 'sess-OTHER', title: 'someone else' },
+    ],
+  });
+  assert.equal(d.refuse, false);
+});
+
+// (c) A NULL incoming creator_session_id (web/unbound claim, or session-less CLI
+//     caller) is skipped/allowed — there is nothing to scope to.
+t('NULL incoming session is allowed (web/unbound claim)', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: null,
+    activeClaimsForSession: [],
+  });
+  assert.equal(d.refuse, false);
+});
+
+t('NULL-session rows never count against a bound session', () => {
+  // A pile of session-UNBOUND web claims (creator_session_id=null) must not trip
+  // the block for a bound CLI session that has none of its own.
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-3',
+    activeClaimsForSession: [
+      { claim_id: 20, task_id: 1, creator_session_id: null, title: 'web claim a' },
+      { claim_id: 21, task_id: 2, creator_session_id: null, title: 'web claim b' },
+    ],
+  });
+  assert.equal(d.refuse, false);
+});
+
+// (d) Fail-closed shape: the pure fn never throws on odd input, and the refusal
+//     decision is deterministic. (The route's fail-CLOSED-on-error behaviour is
+//     in the middleware; here we assert the pure fn degrades safely and that a
+//     matching row is always caught — the data the middleware feeds it on the
+//     happy path.)
+t('missing activeClaimsForSession degrades to allow (treated as empty)', () => {
+  const d = shouldRefuseSessionClaim({ creatorSessionId: 'sess-4' });
+  assert.equal(d.refuse, false);
+});
+
+t('non-array activeClaimsForSession is treated as empty (no throw)', () => {
+  const d = shouldRefuseSessionClaim({ creatorSessionId: 'sess-4', activeClaimsForSession: null });
+  assert.equal(d.refuse, false);
+});
+
+t('refusal carries the canonical reason code', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-5',
+    activeClaimsForSession: [
+      { claim_id: 30, task_id: 7, creator_session_id: 'sess-5', title: 'x' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.reason, 'session_already_has_active_claim');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/orphaned_claim_ship.mjs

@@ -0,0 +1,135 @@
+// tests/orphaned_claim_ship.mjs
+//
+// Regression guard for task 1643 — shipTask closes any claim still OPEN on the
+// task, inside the SAME transaction that ships it.
+//
+// THE BUG. A claim is normally closed by resolveClaim (claimed→completed). The
+// confirm paths and shipTask (confirmed→shipped) flip task status + award
+// credits but never touch the claim. So a task that reaches a terminal state
+// without that resolve (strand recovery / direct-SQL fixups) leaves the claim
+// dangling released_at=NULL forever, and every claim-aware view (dashboard,
+// parallel-safety) keeps showing the shipped task as actively claimed. Live
+// repro: task 1300 shipped, claim #1292 still open.
+//
+// Contract under test:
+//   - a successful ship issues the claims-close UPDATE, in-txn (after BEGIN +
+//     after the tasks→shipped UPDATE, before COMMIT), keyed on the task id.
+//   - it heals a strand: an open claim → closedClaimCount reflected (the UPDATE
+//     RETURNING row is consumed); the shipRow is still returned.
+//   - it is a no-op safety net for a normal ship: the UPDATE still runs but
+//     matches nothing — the ship is unaffected.
+//   - a rejected ship (task not 'confirmed') throws TASK_NOT_CONFIRMED, ROLLS
+//     BACK, and NEVER issues the claims-close (we don't close claims for a ship
+//     that didn't happen).
+//
+// shipTask opens its own transaction via withTx(pool.connect()); the #538
+// deps.pool injection seam (honored ONLY when NODE_ENV==='test') lets us drive
+// it with a SQL-aware fakeClient — no live DB — same posture as
+// confirm_attribution.mjs / abandon_task.mjs.
+//
+// Run:  node tests/orphaned_claim_ship.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 { shipTask } = db;
+
+const { test, summary } = makeRunner();
+
+const TASK_ID = 1300;
+const BUILDER_ID = 95;
+
+// SQL-aware fake covering every statement shipTask issues:
+//   confirmed=false  → the tasks→shipped UPDATE matches no row (TASK_NOT_CONFIRMED)
+//   orphanClaimIds   → rows the claims-close UPDATE returns (the strand it heals)
+// rank is forced to 'archon' so maybeAutoGraduateToThetes no-ops after one SELECT,
+// and the onboarding ship-count returns 1 (< 3) so markStage is skipped.
+function fakePool({ confirmed = true, orphanClaimIds = [] } = {}) {
+  return makeSqlAwareClient((s, params) => {
+    if (/^UPDATE tasks SET status = 'shipped'/.test(s)) {
+      return {
+        rows: confirmed
+          ? [{
+              id: params[0], title: 'fixture task', status: 'shipped',
+              shipped_at: '2026-06-27T00:00:00Z', shipped_by: BUILDER_ID,
+              security_sensitive: false, value_summary: null,
+            }]
+          : [],
+      };
+    }
+    if (/^UPDATE claims SET released_at = now\(\), outcome = COALESCE\(outcome, 'shipped'\) WHERE task_id = \$1 AND released_at IS NULL/.test(s)) {
+      return { rows: orphanClaimIds.map((id) => ({ id })) };
+    }
+    if (/^UPDATE builders SET first_ship_at/.test(s)) return { rows: [] };
+    if (/SELECT count\(\*\)::int AS n FROM tasks WHERE shipped_by = \$1 AND status = 'shipped'/.test(s)) {
+      return { rows: [{ n: 1 }] };
+    }
+    if (/^SELECT rank FROM builders WHERE id = \$1/.test(s)) return { rows: [{ rank: 'archon' }] };
+    return { rows: [] }; // BEGIN / COMMIT / ROLLBACK
+  });
+}
+
+// indices of matching statements in the recorded call log
+const idxOf = (queries, re) => queries.findIndex((q) => re.test(String(q.sql).replace(/\s+/g, ' ').trim()));
+const CLAIMS_CLOSE = /^UPDATE claims SET released_at = now\(\), outcome = COALESCE\(outcome, 'shipped'\) WHERE task_id = \$1 AND released_at IS NULL/;
+const SHIP_TASK = /^UPDATE tasks SET status = 'shipped'/;
+
+await test('ship heals a strand: open claim on the shipped task is closed', async () => {
+  const pool = fakePool({ confirmed: true, orphanClaimIds: [1292] });
+  const result = await shipTask({ taskId: TASK_ID, builderId: BUILDER_ID }, { pool });
+
+  // the ship itself succeeded and the shipRow is returned
+  assert.equal(result.id, TASK_ID);
+  assert.equal(result.status, 'shipped');
+
+  // the claims-close UPDATE ran, keyed on the task id
+  const close = pool._client.queries.find((q) => CLAIMS_CLOSE.test(String(q.sql).replace(/\s+/g, ' ').trim()));
+  assert.ok(close, 'shipTask must issue the claims-close UPDATE');
+  assert.deepEqual(close.params, [TASK_ID], 'claims-close is keyed on the task id only');
+});
+
+await test('claims-close runs in-txn: after BEGIN + the ship UPDATE, before COMMIT', async () => {
+  const pool = fakePool({ confirmed: true, orphanClaimIds: [1292] });
+  await shipTask({ taskId: TASK_ID, builderId: BUILDER_ID }, { pool });
+  const q = pool._client.queries;
+
+  const iBegin = idxOf(q, /^BEGIN$/);
+  const iShip = idxOf(q, SHIP_TASK);
+  const iClose = idxOf(q, CLAIMS_CLOSE);
+  const iCommit = idxOf(q, /^COMMIT$/);
+
+  assert.ok(iBegin >= 0 && iShip >= 0 && iClose >= 0 && iCommit >= 0, 'all four statements present');
+  assert.ok(iBegin < iShip, 'BEGIN before the ship UPDATE');
+  assert.ok(iShip < iClose, 'task is shipped before its claims are closed');
+  assert.ok(iClose < iCommit, 'claims are closed before COMMIT (same txn)');
+});
+
+await test('normal ship is a no-op safety net: UPDATE runs, nothing to close', async () => {
+  // resolveClaim already closed the claim on the happy path — the UPDATE matches
+  // zero rows. The ship must still succeed and still issue the (harmless) UPDATE.
+  const pool = fakePool({ confirmed: true, orphanClaimIds: [] });
+  const result = await shipTask({ taskId: TASK_ID, builderId: BUILDER_ID }, { pool });
+
+  assert.equal(result.status, 'shipped');
+  const close = pool._client.queries.find((q) => CLAIMS_CLOSE.test(String(q.sql).replace(/\s+/g, ' ').trim()));
+  assert.ok(close, 'the safety-net UPDATE runs unconditionally on a successful ship');
+});
+
+await test('rejected ship (not confirmed) never closes claims, and rolls back', async () => {
+  const pool = fakePool({ confirmed: false });
+  await assert.rejects(
+    () => shipTask({ taskId: TASK_ID, builderId: BUILDER_ID }, { pool }),
+    (e) => e.code === 'TASK_NOT_CONFIRMED',
+  );
+  const q = pool._client.queries;
+  assert.equal(idxOf(q, CLAIMS_CLOSE), -1, 'no claims-close UPDATE when the ship is rejected');
+  assert.ok(idxOf(q, /^ROLLBACK$/) >= 0, 'the txn rolled back');
+  assert.equal(idxOf(q, /^COMMIT$/), -1, 'no COMMIT on a rejected ship');
+});
+
+summary();