@bongos/core 1.19.292 → 1.19.294

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.292",
+  "version": "1.19.294",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.292",
+      "version": "1.19.294",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.292",
+  "version": "1.19.294",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/ship.js

@@ -1193,7 +1193,8 @@ function shouldBailOnFetchFailure(fetchedMain, deployMode, via) {
 //                      `n` the command that recovers it.
 // Only landBailed makes the card say NOT landed. Purely additive: no bail site
 // changes what it DOES, only what it now reports back.
-function landed() { return { ok: true, pending: false, reason: null, nextStep: null }; }
+// ADR 0184: an EMPTY ship has no commit to prove, so it must DECLARE itself.
+function landed(o = {}) { return { ok: true, pending: false, reason: null, nextStep: null, noArtifact: o.noArtifact === true, noArtifactReason: o.noArtifactReason || null }; }
 function landPending() { return { ok: false, pending: true, reason: null, nextStep: null }; }
 function landBailed(reason, nextStep = null) { return { ok: false, pending: false, reason, nextStep }; }
 
@@ -2534,7 +2535,7 @@ async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
     if (dbOnly && shellOk('git fetch origin main')
         && zeroCommitVerdict(gitOk('git rev-list origin/main..HEAD --count'), true) === 'db-only') {
       console.log('  auto-merge: deliberate empty ship (--db-only / --allow-empty) from the main checkout - nothing to merge; advancing to shipped without merge/deploy.');
-      return landed();
+      return landed({ noArtifact: true, noArtifactReason: 'empty ship from the main checkout — no commits to merge' });
     }
     console.log(`  auto-merge: skipped (current branch is ${branch})`);
     // The merge source IS the current branch, so on main there is nothing to
@@ -2599,7 +2600,7 @@ async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
   }
   if (verdict === 'db-only') {
     console.log('  auto-merge: deliberate empty ship (--db-only / --allow-empty) - no commits ahead of main; advancing to shipped without merge/deploy.');
-    return landed();
+    return landed({ noArtifact: true, noArtifactReason: 'empty ship — no commits ahead of main' });
   }
 
   // #679 / ADR 0042: in 'ci' deploy mode the operator's machine never merges or
@@ -3236,7 +3237,8 @@ async function mergeAndDeploy({ taskId, summary, advanceToMerge, skipMerge, dbOn
   // task that never landed.
   if (!merged.ok) return merged;
 
-  const ship = await (await cliClient()).tasks.postTasksIdShip({ id: taskId, body: {} });
+  const shipBody = merged.noArtifact ? { no_artifact: true, no_artifact_reason: merged.noArtifactReason || 'deliberate empty ship (--db-only)' } : {}; // ADR 0184
+  const ship = await (await cliClient()).tasks.postTasksIdShip({ id: taskId, body: shipBody });
   if (!ship.ok) {
     // task 1049 / 1002809: the server may have already flipped this task to
     // shipped (reconcile-on-read, or the reconciler racing this call). Verify

package/scripts/gds/strand-watch.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/strand-watch.js — say out loud that a ship got stuck (task 1003163).
+//
+// THE GAP. Nothing watched for a stranded ship. On 2026-08-22 a manual status sweep found
+// task 1002483 parked at `completed` for THREE DAYS carrying 651 lines of tested work on a
+// local branch, task 1002792 parked two days behind it, and task 1002459 sitting at
+// `confirmed` for FOUR DAYS with no artifact anywhere. Not one of the three had produced a
+// single signal; all were found by accident.
+//
+// WHY land-watch.js IS NOT THIS (it looks like it should be). land-watch.js renders the
+// SHIPPED banner after an async CI land (task 1687). It cannot detect a strand: it reads
+// machine-local breadcrumbs that ship.js writes only at CONFIRMED-exit — so a task parked at
+// `completed` never gets one — it DROPS a breadcrumb after 30 minutes by design, and it is
+// per-machine, so a strand on a box nobody reopens is invisible forever.
+//
+// THE SIGNAL ALREADY EXISTS. This is the part worth knowing: the publish-reconciler ALREADY
+// diagnoses the worst case and already writes it down. Task 1002459 has carried
+// `needs_rebase_reason = 'strand:land_not_proven'` since 2026-08-18 — the reconciler probed
+// it, could not prove a land, gave up, and recorded exactly that. Nobody ever read the field.
+// So this module is not a detector. It is the READOUT of a diagnosis the system performs and
+// then discards, which is why it is small.
+//
+// SHAPE COPIED FROM deploy-divergence.js, deliberately. That check was written after the
+// ten-day staleness incident (blocker 1000097 / task 1002521), is wired into SessionStart in
+// .claude/settings.json, and on 2026-08-22 it reported the stale pin in the first message of
+// the session — which is how that whole day's work started. A cheap check, on a path that
+// already runs, reporting loudly, beats a monitoring subsystem that can itself silently stop.
+// So: fail-open, bounded, and SILENT when the board is clean.
+//
+// Usage:
+//   node scripts/gds/strand-watch.js                 # human-readable report
+//   node scripts/gds/strand-watch.js --line          # ONE line, or nothing; always exit 0
+//   node scripts/gds/strand-watch.js --json          # machine shape
+//   node scripts/gds/strand-watch.js --hours N       # override the `completed` threshold
+//
+// Exit codes: 0 always on --line (fail-open). Otherwise 0 clean, 1 strands found, 2 undetermined.
+
+const { apiCall, arg, hasFlag } = require('./cli-lib');
+
+// ---- thresholds -------------------------------------------------------------
+// Reasoned, not magic. Written down because a future reader will want to retune them.
+//
+// `confirmed` means the grade PASSED and only the land is outstanding. The publish-reconciler
+// sweeps every ~5 minutes, so one hour is twelve missed sweeps — already anomalous, while
+// still leaving room for a slow CI queue or a transient GitHub failure.
+const CONFIRMED_STALE_MS = 60 * 60 * 1000;
+// `completed` means the grade did NOT pass. A builder may legitimately be mid-recovery for
+// hours (see the /grade-recover loop), so this is deliberately generous: 12 hours means the
+// strand survived a night, which no active recovery does. The three real cases were 2–3 DAYS.
+const COMPLETED_STALE_MS = 12 * 60 * 60 * 1000;
+
+// A reconciler-recorded strand needs NO threshold. The reconciler already probed every branch
+// convention, failed to prove a land, and wrote the reason down; waiting longer cannot change
+// that verdict, and task 1002459 proves the alternative is sitting for days.
+const STRAND_REASON_PREFIX = 'strand:';
+
+const WATCHED = ['completed', 'confirmed'];
+const DEFAULT_TIMEOUT_MS = 8000;
+// Page size per watched status. A queue past this would silently lose the OLDEST strands —
+// exactly the class of quiet cap this whole check exists to abolish — so a full page is
+// reported as `truncated` rather than passed off as complete. 200 is far above any healthy
+// board (the real numbers were 1 and 2).
+const PAGE_LIMIT = 200;
+
+// ---- classification (pure — this is the unit-testable core) -----------------
+
+// Task ids are numeric and reconciler reasons come from a fixed vocabulary, so both are safe
+// to print. TITLES ARE NOT, and that omission is deliberate — see the trust-boundary note on
+// `line()` below.
+const safeId = (v) => (/^\d{1,19}$/.test(String(v)) ? String(v) : null);
+const safeReason = (v) => (typeof v === 'string' && /^[a-z0-9_:.-]{1,64}$/i.test(v) ? v : null);
+
+function humanAge(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return 'unknown';
+  const h = ms / 3600000;
+  if (h < 1) return `${Math.max(1, Math.round(ms / 60000))}m`;
+  if (h < 48) return `${Math.round(h)}h`;
+  return `${Math.round(h / 24)}d`;
+}
+
+// Decide whether ONE task is a strand, and if so which shape and what fixes it. The two
+// shapes need opposite responses, which is the whole reason to distinguish them:
+//   completed -> the GRADE parked it; re-grade or fix findings (/grade-recover).
+//   confirmed -> the grade passed and the LAND is outstanding (/merge-mode is the fallback).
+// A reconciler-recorded strand is called out separately because it is terminal without a
+// human: the automated healers have already refused it.
+function classifyStrand(task, { nowMs, confirmedStaleMs = CONFIRMED_STALE_MS, completedStaleMs = COMPLETED_STALE_MS } = {}) {
+  const t = task || {};
+  const status = String(t.status || '');
+  if (!WATCHED.includes(status)) return null;
+
+  const id = safeId(t.id);
+  if (!id) return null;
+
+  const updated = Date.parse(t.updated_at || '');
+  const ageMs = Number.isFinite(updated) && Number.isFinite(nowMs) ? nowMs - updated : NaN;
+
+  const reason = safeReason(t.needs_rebase_reason);
+  const reconcilerGaveUp = status === 'confirmed'
+    && t.needs_rebase === true
+    && !!reason
+    && reason.toLowerCase().startsWith(STRAND_REASON_PREFIX);
+
+  if (reconcilerGaveUp) {
+    return {
+      id, status, ageMs, age: humanAge(ageMs), shape: 'unprovable', reason,
+      remedy: 'check whether any artifact exists at all — a confirm with no branch and nothing on main was codeless',
+    };
+  }
+
+  const limit = status === 'confirmed' ? confirmedStaleMs : completedStaleMs;
+  // An unreadable updated_at must not manufacture a strand — fail QUIET on bad data here,
+  // because this text is injected into every session and a false alarm trains people to
+  // scroll past the real one.
+  if (!Number.isFinite(ageMs) || ageMs <= limit) return null;
+
+  return status === 'confirmed'
+    ? { id, status, ageMs, age: humanAge(ageMs), shape: 'unlanded', reason: null,
+        remedy: '/merge-mode is the documented manual fallback' }
+    : { id, status, ageMs, age: humanAge(ageMs), shape: 'ungraded', reason: null,
+        remedy: '/grade-recover diagnoses which of the three shapes parked it' };
+}
+
+// Sort worst-first so a truncated line shows the most urgent: reconciler-refused, then oldest.
+const SHAPE_RANK = { unprovable: 0, unlanded: 1, ungraded: 2 };
+function rankStrands(strands) {
+  return strands.slice().sort((a, b) => {
+    const d = (SHAPE_RANK[a.shape] ?? 9) - (SHAPE_RANK[b.shape] ?? 9);
+    return d !== 0 ? d : (b.ageMs || 0) - (a.ageMs || 0);
+  });
+}
+
+// ---- fetch ------------------------------------------------------------------
+
+async function check({ nowMs = Date.now(), timeoutMs = DEFAULT_TIMEOUT_MS, confirmedStaleMs, completedStaleMs, call = apiCall } = {}) {
+  // CONCURRENT, not sequential. This runs on the SessionStart path beside deploy-divergence,
+  // so a serial loop would double the latency the builder waits through for no reason.
+  const withTimeout = (p, label) => Promise.race([
+    p,
+    new Promise((_, rej) => setTimeout(() => rej(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs)),
+  ]).catch((e) => { throw new Error(`could not read ${label} tasks: ${e.message || e}`); });
+
+  let pages;
+  try {
+    pages = await Promise.all(WATCHED.map(async (status) => {
+      const res = await withTimeout(call('GET', `/api/gds/tasks?status=${status}&limit=${PAGE_LIMIT}`), status);
+      const body = res && (res.data || res);
+      const tasks = body && Array.isArray(body.tasks) ? body.tasks : null;
+      if (!tasks) throw new Error(`unexpected shape from /tasks?status=${status}`);
+      return { status, tasks };
+    }));
+  } catch (e) {
+    return { undetermined: true, reason: e.message || String(e), strands: [], truncated: [] };
+  }
+
+  const strands = [];
+  const truncated = [];
+  for (const { status, tasks } of pages) {
+    if (tasks.length >= PAGE_LIMIT) truncated.push(status);
+    for (const t of tasks) {
+      const s = classifyStrand(t, { nowMs, confirmedStaleMs, completedStaleMs });
+      if (s) strands.push(s);
+    }
+  }
+  return { undetermined: false, ok: strands.length === 0 && !truncated.length, strands: rankStrands(strands), truncated };
+}
+
+// ---- rendering --------------------------------------------------------------
+
+// ONE line for SessionStart, or null. Null IS the silence: a clean board must say nothing,
+// or the line becomes wallpaper and the real warning gets scrolled past.
+//
+// TRUST BOUNDARY — why no task titles. A task title is builder-authored free text, and this
+// string is injected into an agent's context at the start of every session. Interpolating a
+// title raw would hand anyone who can file a task a standing prompt-injection channel, which
+// is the same reasoning deploy-divergence.js applies to the /version response it reads (it
+// accepts only a strict semver for exactly this purpose). Ids and a fixed reason vocabulary
+// carry all the signal that is needed and none of the risk — the agent can GET the task.
+function line(r, { max = 3 } = {}) {
+  if (!r || r.undetermined) return null;
+  const trunc = Array.isArray(r.truncated) && r.truncated.length
+    ? ` (the ${r.truncated.join(' and ')} queue${r.truncated.length > 1 ? 's' : ''} filled a full ${PAGE_LIMIT}-row page, so older strands may be unlisted)`
+    : '';
+  if (!r.strands.length) {
+    // A full page with no strand still means coverage was capped — say so rather than imply
+    // a clean board, which is the silent-cap failure this check is against.
+    return trunc ? `Strand check could not see the whole board${trunc}. Run: node scripts/gds/strand-watch.js` : null;
+  }
+  const shown = r.strands.slice(0, max)
+    .map((s) => `task ${s.id} (${s.status}, ${s.age}${s.reason ? `, ${s.reason}` : ''})`);
+  const more = (r.strands.length > shown.length ? ` +${r.strands.length - shown.length} more` : '') + trunc;
+  const worst = r.strands[0];
+  // Lead with what the WORST shape actually means. "work is finished but not landed" is true
+  // of a confirmed strand and false of a completed one (the grade parked that, so the work may
+  // not be finished at all) — one generic sentence for both would be wrong half the time.
+  const lead = {
+    unprovable: 'the reconciler already probed this and gave up, so it will never self-heal',
+    unlanded: 'the grade passed and only the land is outstanding',
+    ungraded: 'the grade parked this; it is not waiting on a land',
+  }[worst.shape] || 'parked mid-pipeline';
+  return `Stranded ship${r.strands.length === 1 ? '' : 's'}: ${shown.join('; ')}${more}. `
+    + `Worst: ${lead} — ${worst.remedy}. `
+    + 'A strand produces no signal of its own; this line is the only one.';
+}
+
+function report(r) {
+  if (!r) { console.error('strand-watch: no result'); return; }
+  if (r.undetermined) { console.error(`strand-watch: undetermined — ${r.reason}`); return; }
+  console.log('');
+  console.log('  Stranded ships');
+  console.log('  ──────────────────────────────────────────────────────────');
+  if (Array.isArray(r.truncated) && r.truncated.length) {
+    console.log(`  ! coverage capped: the ${r.truncated.join(' and ')} queue(s) returned a full ${PAGE_LIMIT}-row page,`);
+    console.log('    so strands older than the cutoff are NOT listed below.');
+  }
+  if (r.ok) {
+    console.log('  ✓ none — nothing parked at completed or confirmed past its threshold.');
+    console.log('');
+    return;
+  }
+  for (const s of r.strands) {
+    console.log(`  task ${s.id}  ${s.status.padEnd(9)} ${String(s.age).padStart(4)}  ${s.shape}${s.reason ? ` (${s.reason})` : ''}`);
+    console.log(`      ${s.remedy}`);
+  }
+  console.log('');
+  console.log('  "completed" means the grade parked it. "confirmed" means it passed and the');
+  console.log('  land never finished. Neither state produces a signal on its own.');
+  console.log('');
+}
+
+async function main() {
+  const hours = Number(arg('--hours'));
+  const opts = Number.isFinite(hours) && hours > 0 ? { completedStaleMs: hours * 3600000 } : {};
+
+  // --line: the SessionStart shape. FAIL-OPEN — a strand is context for the agent, and an
+  // unreachable API is nothing at all; neither is a failure of the session this rides into.
+  // Note it sets exitCode and RETURNS rather than calling process.exit: an explicit exit here
+  // races libuv's teardown of the request socket and aborts the process on Windows/Node 24
+  // (the documented `UV_HANDLE_CLOSING` assertion — see cli-lib's cliExit note and
+  // deploy-divergence's identical comment).
+  if (hasFlag('--line')) {
+    try {
+      const one = line(await check(opts));
+      if (one) console.log(one);
+    } catch { /* no session, offline, unreadable — all silence */ }
+    process.exitCode = 0;
+    return;
+  }
+
+  const r = await check(opts);
+  if (hasFlag('--json')) console.log(JSON.stringify(r, null, 2));
+  else report(r);
+  process.exitCode = r.undetermined ? 2 : (r.ok ? 0 : 1);
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error('strand-watch: failed —', e.message || e); process.exit(2); });
+}
+
+module.exports = {
+  check, line, report, classifyStrand, rankStrands, humanAge,
+  CONFIRMED_STALE_MS, COMPLETED_STALE_MS, STRAND_REASON_PREFIX, WATCHED, PAGE_LIMIT,
+};

package/src/module-api.js

@@ -1011,8 +1011,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.290 with no explicit bump. run 32580353000. (task 1002620)
 //   1.19.292 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.291 with no explicit bump. run 32582800234. (task 1002620)
+//   1.19.293 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.292 with no explicit bump. run 32586174253. (task 1002620)
+//   1.19.294 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.293 with no explicit bump. run 32588977219. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.292'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.294'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/orphaned_claim_ship.mjs

@@ -79,9 +79,14 @@ const idxOf = (queries, re) => queries.findIndex((q) => re.test(String(q.sql).re
 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'/;
 
+// task 1002483: shipTask now requires a landAssurance and is fail-closed.
+// These tests exercise what happens AFTER the gate, so they pass the same
+// 'proof' shape the reconciler and reconcile-on-read do.
+const LAND_PROOF = { kind: 'proof', reason: 'test fixture: land proven' };
+
 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 });
+  const result = await shipTask({ taskId: TASK_ID, builderId: BUILDER_ID, landAssurance: LAND_PROOF }, { pool });
 
   // the ship itself succeeded and the shipRow is returned
   assert.equal(result.id, TASK_ID);
@@ -95,7 +100,7 @@ await test('ship heals a strand: open claim on the shipped task is closed', asyn
 
 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 });
+  await shipTask({ taskId: TASK_ID, builderId: BUILDER_ID, landAssurance: LAND_PROOF }, { pool });
   const q = pool._client.queries;
 
   const iBegin = idxOf(q, /^BEGIN$/);
@@ -113,7 +118,7 @@ await test('normal ship is a no-op safety net: UPDATE runs, nothing to close', a
   // 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 });
+  const result = await shipTask({ taskId: TASK_ID, builderId: BUILDER_ID, landAssurance: LAND_PROOF }, { pool });
 
   assert.equal(result.status, 'shipped');
   const close = pool._client.queries.find((q) => CLAIMS_CLOSE.test(String(q.sql).replace(/\s+/g, ' ').trim()));
@@ -123,7 +128,7 @@ await test('normal ship is a no-op safety net: UPDATE runs, nothing to close', a
 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 }),
+    () => shipTask({ taskId: TASK_ID, builderId: BUILDER_ID, landAssurance: LAND_PROOF }, { pool }),
     (e) => e.code === 'TASK_NOT_CONFIRMED',
   );
   const q = pool._client.queries;

package/tests/pay_on_land.mjs

@@ -82,12 +82,17 @@ const RECONCILER = 999;  // the builder_id the reconciler passes to shipTask
 const WORKER = 25;       // the claim holder who actually did the work
 const TASK = { id: 660, title: 'fixture task' };
 
+// task 1002483: shipTask now requires a landAssurance and is fail-closed.
+// These tests exercise what happens AFTER the gate, so they pass the same
+// 'proof' shape the reconciler and reconcile-on-read do.
+const LAND_PROOF = { kind: 'proof', reason: 'test fixture: land proven' };
+
 // =========================================================================
 await test('ship: the per-task credit lands at SHIP (reason=task.shipped), attributed to the claim holder', async () => {
   // shipped_by was set to the claim holder at confirm; the reconciler triggers
   // the ship with its own builderId — attribution must still be the worker.
   const pool = fakePool({ claimHolderId: WORKER, shippedBy: WORKER, creditsReward: 15, kind: 'feature' });
-  const out = await shipTask({ taskId: TASK.id, builderId: RECONCILER }, { pool });
+  const out = await shipTask({ taskId: TASK.id, builderId: RECONCILER, landAssurance: LAND_PROOF }, { pool });
 
   assert.equal(out.status, 'shipped', 'task flips to shipped');
   assert.equal(out.creditedBuilderId, WORKER, 'credit attributed to the claim holder, not the reconciler');
@@ -103,14 +108,14 @@ await test('ship: the per-task credit lands at SHIP (reason=task.shipped), attri
 
 await test('ship: idempotent — a prior task.shipped credit means no second INSERT', async () => {
   const pool = fakePool({ claimHolderId: WORKER, shippedBy: WORKER, priorShipCredit: true });
-  const out = await shipTask({ taskId: TASK.id, builderId: RECONCILER }, { pool });
+  const out = await shipTask({ taskId: TASK.id, builderId: RECONCILER, landAssurance: LAND_PROOF }, { pool });
   assert.equal(out.creditsAwarded, 0, 'no fresh credit on a re-ship / reconciler re-sweep');
   assert.equal(all(pool._client.queries, /INSERT INTO credit_log/).length, 0, 'must not double-insert credit');
 });
 
 await test('ship: credits_reward = 0 → no credit_log INSERT', async () => {
   const pool = fakePool({ claimHolderId: WORKER, shippedBy: WORKER, creditsReward: 0 });
-  const out = await shipTask({ taskId: TASK.id, builderId: RECONCILER }, { pool });
+  const out = await shipTask({ taskId: TASK.id, builderId: RECONCILER, landAssurance: LAND_PROOF }, { pool });
   assert.equal(out.creditsAwarded, 0, 'a zero-reward task pays nothing');
   assert.equal(all(pool._client.queries, /INSERT INTO credit_log/).length, 0, 'no INSERT for a 0-reward task');
 });
@@ -118,7 +123,7 @@ await test('ship: credits_reward = 0 → no credit_log INSERT', async () => {
 await test('ship: not in confirmed state → throws TASK_NOT_CONFIRMED, awards nothing', async () => {
   const pool = fakePool({ claimHolderId: WORKER, shippedBy: WORKER, confirmed: false });
   await assert.rejects(
-    () => shipTask({ taskId: TASK.id, builderId: RECONCILER }, { pool }),
+    () => shipTask({ taskId: TASK.id, builderId: RECONCILER, landAssurance: LAND_PROOF }, { pool }),
     (err) => err.code === 'TASK_NOT_CONFIRMED',
     'must throw TASK_NOT_CONFIRMED when the UPDATE matches no confirmed row'
   );

package/tests/ship_assurance.mjs

@@ -0,0 +1,188 @@
+// tests/ship_assurance.mjs — the ship gate (task 1002483, goal 1000024).
+//
+// THE HOLE. db.shipTask is where the ledger says work is delivered AND where the
+// credit is booked (ADR 0120 pays on land). Its only precondition was
+// `WHERE status = 'confirmed'` — nothing about whether any code reached main. The
+// two AUTOMATED paths each proved the land before calling, but the MANUAL route
+// (POST /tasks/:id/ship) called it with nothing. So a task confirmed with no
+// pushed code could be flipped to shipped by its claim holder, or by any Metic+
+// sweeping /merge-mode, and it booked its task.shipped credit.
+//
+// It went untracked for two months because its tracking task (1000900) was closed
+// in June on a rationale asserting task 1001547 had delivered the confirm gate.
+// It had not — blocker 1000047's own final update says so, and the code agreed
+// with the blocker, not the closure note. That is why these tests assert against
+// the CODE and not against anyone's account of it.
+//
+// THE GATE. shipTask now requires a `landAssurance` and is FAIL-CLOSED: no
+// assurance, no ship. Two legitimate kinds:
+//   proof        the caller verified this task's own commit is on main
+//   no_artifact  a deliberate DB-only ship — an explicitly supported shape
+//                (CLAUDE.md, "Direct DB writes are work too") that task 1002478
+//                documents as a dead end below Archon. Naming it as a KIND is
+//                what stops this gate from making 1002478 worse: a no-artifact
+//                ship becomes a recorded answer rather than an absence.
+//
+// DB-free: the validator is pure, and the fail-closed refusal happens before any
+// pool use, so shipTask can be called with no database at all.
+//
+// Run:  node tests/ship_assurance.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.dirname(path.dirname(url.fileURLToPath(import.meta.url)));
+const db = require(path.join(ROOT, 'modules/lifecycle/db.js'));
+const { normalizeShipAssurance, SHIP_ASSURANCE_KINDS } = db;
+
+let passed = 0;
+let failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${e.message}`); }
+}
+
+console.log('the ship assurance — what counts as a shippable reason');
+
+await t('a missing assurance is refused', () => {
+  for (const bad of [undefined, null, '', 0, false, [], 'proof']) {
+    const r = normalizeShipAssurance(bad);
+    assert.equal(r.ok, false, `${JSON.stringify(bad)} must not pass`);
+    assert.equal(r.code, 'ship_assurance_required');
+  }
+});
+
+await t('an unknown kind is refused, and the refusal lists what is allowed', () => {
+  const r = normalizeShipAssurance({ kind: 'trust_me', reason: 'it landed, honest' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'ship_assurance_bad_kind');
+  assert.deepEqual(r.allowed, SHIP_ASSURANCE_KINDS);
+});
+
+await t('a reasonless assurance is refused — the ledger records WHY, not just that', () => {
+  for (const reason of [undefined, null, '', '    ', '\n\t ']) {
+    const r = normalizeShipAssurance({ kind: 'proof', reason });
+    assert.equal(r.ok, false, `${JSON.stringify(reason)} is not a reason`);
+    assert.equal(r.code, 'ship_assurance_reason_required');
+  }
+});
+
+await t('both legitimate kinds pass, and the reason is tidied', () => {
+  const p = normalizeShipAssurance({ kind: 'proof', reason: '  published tip abc1234   in main \n' });
+  assert.equal(p.ok, true);
+  assert.deepEqual(p.value, { kind: 'proof', reason: 'published tip abc1234 in main' });
+
+  const n = normalizeShipAssurance({ kind: 'no_artifact', reason: 'DB-only: widened a goal scope wall' });
+  assert.equal(n.ok, true);
+  assert.equal(n.value.kind, 'no_artifact');
+});
+
+await t('a runaway reason is capped rather than refused', () => {
+  const r = normalizeShipAssurance({ kind: 'proof', reason: 'x'.repeat(5000) });
+  assert.equal(r.ok, true, 'a long reason is still a reason — cap it, do not lose the ship');
+  assert.equal(r.value.reason.length, 500);
+});
+
+console.log('\nshipTask is FAIL-CLOSED, before it touches a database');
+
+await t('shipTask with NO assurance throws ship_assurance_required', async () => {
+  // No DB is configured here on purpose: the gate must refuse before any pool
+  // use, so a caller that cannot account for the ship never even opens a txn.
+  await assert.rejects(
+    () => db.shipTask({ taskId: 1, builderId: 1 }),
+    (e) => e.code === 'ship_assurance_required',
+  );
+});
+
+await t('shipTask with a MALFORMED assurance throws too — not a silent default', async () => {
+  await assert.rejects(
+    () => db.shipTask({ taskId: 1, builderId: 1, landAssurance: { kind: 'proof' } }),
+    (e) => e.code === 'ship_assurance_reason_required',
+  );
+  await assert.rejects(
+    () => db.shipTask({ taskId: 1, builderId: 1, landAssurance: { kind: 'nope', reason: 'x'.repeat(20) } }),
+    (e) => e.code === 'ship_assurance_bad_kind',
+  );
+});
+
+console.log('\nevery call site accounts for its ship');
+
+// Source tripwires. The behavioural tests above prove the gate refuses; these
+// prove nobody routes AROUND it. A new caller that forgets the assurance would
+// fail at runtime — but only on the path someone exercises, which for a ship path
+// can be weeks later and in production.
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+
+await t('all three production call sites pass a landAssurance', () => {
+  const sites = [
+    ['modules/lifecycle/publish-reconciler.js', 'the reconciler sweep'],
+    ['modules/lifecycle/routes/tasks.js', 'the manual ship route + reconcile-on-read'],
+  ];
+  let found = 0;
+  for (const [rel, label] of sites) {
+    const src = read(rel);
+    for (const m of src.matchAll(/db\.shipTask\(\{([\s\S]{0,300}?)\}\)/g)) {
+      found++;
+      assert.match(m[1], /landAssurance/,
+        `${label} (${rel}) calls db.shipTask without a landAssurance — that is the hole reopening`);
+    }
+  }
+  assert.equal(found, 3, `expected 3 production shipTask call sites, found ${found}`);
+});
+
+await t('the manual ship path PROVES the land, and refuses when it cannot', () => {
+  // The derivation lives in ship-assurance.js (a sibling of ship-preflight), not
+  // in the already-oversized route file — so the assertions follow it there.
+  const src = read('modules/lifecycle/ship-assurance.js');
+  assert.match(src, /landProvenForTask/,
+    'the manual path must DERIVE a proof — it is the path that had none');
+  assert.match(src, /ship_land_not_proven/,
+    'and it must REFUSE when there is no proof and no declaration');
+  assert.match(src, /no_artifact/,
+    'with the deliberate no-artifact declaration as the only other way through');
+
+  // ORDER: prove first, declaration second. A declaration must never be able to
+  // override a proof that was available, and someone who pushed real work should
+  // never have to declare anything.
+  assert.ok(src.indexOf('landProvenForTask') < src.indexOf('body.no_artifact === true'),
+    'the proof must be attempted BEFORE the declaration is consulted');
+});
+
+await t('the route wires the derivation and answers its refusal verbatim', () => {
+  const src = read('modules/lifecycle/routes/tasks.js');
+  const i = src.indexOf("router.post('/tasks/:id/ship'");
+  assert.ok(i > -1);
+  const handler = src.slice(i, src.indexOf('router.', i + 20));
+  assert.match(handler, /gateManualShip/, 'the route must call the gate');
+  assert.match(handler, /if \(!landAssurance\) return;/,
+    'and must BAIL when the gate refused — the refusal is already on the wire');
+  // The assurance passed to the write must be the DERIVED value, never an inline
+  // literal — `{ kind: 'proof', reason: 'assumed' }` would satisfy the gate's shape
+  // while asserting a land nobody checked. (Found by injecting exactly that and
+  // watching an earlier draft of this test stay green.)
+  assert.match(handler, /db\.shipTask\(\{[^}]*landAssurance\s*\}\)/,
+    'the route must pass the DERIVED landAssurance variable, not an inline literal');
+});
+
+await t('the no-artifact declaration cannot be made silently', () => {
+  const src = read('modules/lifecycle/ship-assurance.js');
+  assert.match(src, /no_artifact_reason_required/,
+    'declaring "no artifact" without saying what was delivered must be refused');
+});
+
+await t('the CLI carries the declaration through its deliberate-empty path', () => {
+  // Without this, the gate would refuse exactly the --db-only / --allow-empty
+  // flow CLAUDE.md calls a supported shape — turning a correctness fix into a
+  // regression for the builders who rely on it.
+  const src = read('scripts/gds/ship.js');
+  assert.match(src, /no_artifact:\s*true/, 'ship.js must send the declaration on an empty land');
+  assert.match(src, /landed\(\{ noArtifact: true/,
+    'and the deliberate-empty land sites must mark themselves as such');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);