@bongos/core 1.19.834 → 1.19.836

package/scripts/gds/start.js

@@ -68,6 +68,7 @@ const { checkTree: _checkTree } = require('./tree-preflight.js');
 }
 
 const { cliClient, requireSession, fmtUsd, printOnboardingNudge, printCostWarning, printNeedsNudge, hallBase, API_BASE, rewardPolicy, costPlusOnlyNote, isDispatcherIncompatError, cardFlagsFromMe } = require('./cli-lib');
+const { plainCardLines } = require('./plain-cards');
 const { contextPack, formatContextPackCompact } = require('./context-pack');
 const { depsFinding } = require('./preflight');
 
@@ -719,11 +720,13 @@ async function main() {
   if (r.status === 403 && r.data && r.data.error === 'stage_required') {
     console.log('');
     console.log(r.data.what_to_do || `Clear "${r.data.required_stage_label || r.data.required_stage}" before the work queue opens.`);
+    for (const line of plainCardLines('stage_required')) console.log(line);
     console.log('');
     process.exit(0);
   }
   if (!r.ok) {
     console.error(`failed (${r.status}):`, r.data);
+    for (const line of plainCardLines('board_unavailable')) console.error(line);
     process.exit(1);
   }
 

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.834'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.836'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/claim_gate_rebase.mjs

@@ -28,13 +28,15 @@ if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../m
 const db = require('../modules/lifecycle/db.js');
 
 const VER = 'ZZZ-CG', WORKER = 90000201, STALLED = 90000201, FRESH = 90000202;
+// task 1003294 — the unprovable-strand cases below use their own rows.
+const AGED = 90000203, FRESH2 = 90000204, AGED_OTHER = 90000205;
 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 credit_log WHERE builder_id=$1 OR task_id = ANY($2::bigint[])`, [WORKER, [STALLED, FRESH, AGED, FRESH2, AGED_OTHER]]).catch(() => {});
+  await q(`DELETE FROM claims WHERE task_id = ANY($1::bigint[])`, [[STALLED, FRESH, AGED, FRESH2, AGED_OTHER]]).catch(() => {});
+  await q(`DELETE FROM tasks WHERE id = ANY($1::bigint[])`, [[STALLED, FRESH, AGED, FRESH2, AGED_OTHER]]).catch(() => {});
   await q(`DELETE FROM builders WHERE id=$1`, [WORKER]).catch(() => {});
   await q(`DELETE FROM versions WHERE id=$1`, [VER]).catch(() => {});
 }
@@ -88,6 +90,55 @@ try {
   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');
 
+  // ---------------------------------------------------------------------------
+  // task 1003294 — a strand the builder CANNOT clear stops BLOCKING, without
+  // stopping being REPORTED.
+  //
+  // 'strand:no_branch_no_tip' means no branch in the core repo and no published
+  // tip. That is either "never pushed" (their chore, the gate is working) or
+  // "delivered into the INSTANCE repo" (task 1003253 — real, complete, deployed,
+  // and structurally invisible to this reconciler). Indistinguishable here, so the
+  // gate keeps its teeth for a bounded window and then lets go. These cases prove
+  // the SQL actually does that, which the DB-free suite cannot.
+  // ---------------------------------------------------------------------------
+  await q(`UPDATE claims SET released_at = now() WHERE task_id = $1 AND released_at IS NULL`, [FRESH]);
+
+  const seedStrand = async (id, reason, ageHours) => {
+    await q(`INSERT INTO tasks (id,version_id,title,status,credits_reward,kind,shipped_by) VALUES ($1,$2,'aged','confirmed',10,'feature',$3)`, [id, VER, WORKER]);
+    await q(`INSERT INTO claims (task_id,builder_id,claimed_at) VALUES ($1,$2, now())`, [id, WORKER]);
+    await db.flagTaskNeedsRebase(String(id), reason);
+    await q(`UPDATE tasks SET needs_rebase_at = now() - ($2::bigint * interval '1 hour') WHERE id = $1`, [id, ageHours]);
+  };
+
+  await q(`INSERT INTO tasks (id,version_id,title,status,credits_reward,kind) VALUES ($1,$2,'fresh2','ready',10,'feature')`, [FRESH2, VER]);
+
+  // 4) An unprovable strand AGED past the grace no longer refuses a claim.
+  await seedStrand(AGED, 'strand:no_branch_no_tip', 48);
+  const claim2 = await db.claimTask({ taskId: String(FRESH2), builderId: String(WORKER), worktreeName: 'cg-fresh2' });
+  ok(claim2 && Number(claim2.task_id) === FRESH2,
+    'an unprovable strand past the grace no longer freezes the queue');
+
+  // 5) …and it is STILL owed and STILL surfaced. This is the half that must not
+  //    be lost: releasing the gate is not resolving the strand.
+  const stillOwed = await db.needsRebaseTasksForBuilder(String(WORKER));
+  ok(stillOwed.some((t) => Number(t.id) === AGED),
+    'the ungated strand is still reported to its builder (me.js / hall / CLI)');
+  const agedFlag = (await q(`SELECT needs_rebase FROM tasks WHERE id=$1`, [AGED]))[0].needs_rebase;
+  ok(agedFlag === true, 'the flag is untouched — the row is still owed, just not blocking');
+
+  // 6) A strand with a DIFFERENT reason, equally aged, still gates: this release is
+  //    scoped to the one ambiguous reason, not to age in general.
+  await q(`UPDATE claims SET released_at = now() WHERE task_id = $1 AND released_at IS NULL`, [FRESH2]);
+  await q(`UPDATE tasks SET status='shipped', needs_rebase=false WHERE id=$1`, [AGED]);
+  await seedStrand(AGED_OTHER, 'strand:pr_not_landed', 48);
+  await q(`UPDATE tasks SET status='ready' WHERE id=$1`, [FRESH2]);
+  let threw2 = null;
+  try {
+    await db.claimTask({ taskId: String(FRESH2), builderId: String(WORKER), worktreeName: 'cg-fresh2b' });
+  } catch (e) { threw2 = e; }
+  ok(threw2 && threw2.code === 'REBASE_REQUIRED',
+    'an aged pr_not_landed strand still gates — the builder CAN fix that one');
+
   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);

package/tests/plain_cards.mjs

@@ -0,0 +1,221 @@
+// tests/plain_cards.mjs — every failure a builder can be parked behind has a
+// plain-language card (task 1003989).
+//
+// WHY. The CLIs explain a refusal in engineer prose and the lifecycle skills said
+// "relay verbatim", so a non-technical builder met REBASE_REQUIRED or
+// strand:pr_not_landed raw, at exactly the moment they were stuck. The registry in
+// scripts/gds/plain-cards.js says the same thing in plain words. This file holds
+// three lines: a new failure code cannot ship without a card, a card cannot drift
+// back into jargon, and the deliberate restrictions stay marked as deliberate.
+//
+// Run:  node tests/plain_cards.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { CARDS, cardFor, plainCardLines, PLAIN_MARKER } from '../scripts/gds/plain-cards.js';
+import * as shipLand from '../scripts/gds/ship-land.js';
+
+const require = createRequire(import.meta.url);
+const { JARGON_TERMS } = require('../modules/sessions/accessibility.js');
+const { formatClaimFailure } = require('../scripts/gds/claim.js');
+const { formatGradeOutcome } = require('../scripts/gds/ship-grade-steps.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+const read = (rel) => fs.readFileSync(new URL(`../${rel}`, import.meta.url), 'utf8').replace(/\r\n/g, '\n');
+const missing = (codes) => [...new Set(codes)].filter((c) => !cardFor(c)).sort();
+
+// ── completeness: the codes are read out of the code that raises them ──────────
+
+test('every refusal claim.js renders has a card', () => {
+  const src = read('scripts/gds/claim.js');
+  const body = src.slice(src.indexOf('function claimFailureGuidance'), src.indexOf('function goalMembershipOfferPlan'));
+  const codes = [...body.matchAll(/code === '([A-Za-z_]+)'/g)].map((m) => m[1]);
+  assert.ok(codes.length >= 12, `expected the claim ladder, found ${codes.length}`);
+  assert.deepEqual(missing(codes), []);
+});
+
+test('every refusal the claim ladder can throw server-side has a card', () => {
+  const src = read('modules/lifecycle/db-claims.js');
+  const codes = [...src.matchAll(/\bcode: '([A-Za-z_]+)'/g), ...src.matchAll(/\.code = '([A-Za-z_]+)'/g)].map((m) => m[1]);
+  assert.ok(codes.includes('REBASE_REQUIRED'), 'the ladder was not found — has db-claims.js moved?');
+  assert.deepEqual(missing(codes), []);
+});
+
+test('every reason a confirmed task can be flagged with has a card', () => {
+  // The reconciler composes `strand:${reason}` at runtime, so read both halves: the
+  // literal tokens, and the four values the `reason` ternary can take.
+  const src = read('modules/lifecycle/publish-reconciler.js');
+  const ternary = src.slice(src.indexOf('const reason = prClosedUnmerged'));
+  const reasons = [...ternary.slice(0, ternary.indexOf(';')).matchAll(/'([a-z_]+)'/g)].map((m) => `strand:${m[1]}`);
+  const literals = [...src.matchAll(/strand:([a-z_]{3,})/g)].map((m) => `strand:${m[1]}`);
+  assert.equal(reasons.length, 4, `the reason ternary moved: ${reasons.join(',')}`);
+  assert.ok(literals.length >= 2, 'the conflict strand literals were not found');
+  assert.deepEqual(missing([...reasons, ...literals]), []);
+  assert.ok(cardFor('strand:unresolvable_conflict:docs/a.md,docs/b.md'), 'a reason carrying file names still resolves');
+});
+
+test('every reason an open pull request has not merged has a card', () => {
+  const src = read('modules/lifecycle/github-push.js');
+  const body = src.slice(src.indexOf('function mergeBlockReason'), src.indexOf('async function mergeIfGreen'));
+  const tokens = [...body.matchAll(/return [`']([a-z_]+)/g)].map((m) => m[1]);
+  assert.ok(tokens.includes('merge_conflict') && tokens.includes('failing_check_unreadable'), tokens.join(','));
+  assert.deepEqual(missing(tokens), []);
+  assert.ok(cardFor('failing_check:unit') && cardFor('non_required_check_failing:e2e'), 'named-check reasons resolve by prefix');
+});
+
+test('every push diagnosis and land bail has a card', () => {
+  const ids = [...shipLand.PUSH_DIAGNOSES.map((d) => d.id), 'unknown',
+    shipLand.LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH, shipLand.LAND_BAIL_NO_TASK_BRANCH];
+  assert.deepEqual(missing(ids.map((id) => `ship:${id}`)), []);
+});
+
+// ── the words ─────────────────────────────────────────────────────────────────
+
+// Beyond the scorer's list: the git/GitHub nouns these particular failures are
+// made of, which is exactly what the card exists to keep out of the first line.
+const GIT_NOUNS = ['branch', 'pull request', 'commit', 'merge conflict', 'CI', 'SHA', 'diff', 'PAT', 'origin'];
+
+test('no card speaks in the vocabulary it exists to translate', () => {
+  const banned = [...JARGON_TERMS, ...GIT_NOUNS];
+  const hits = [];
+  for (const [code, card] of Object.entries(CARDS)) {
+    for (const field of ['happened', 'next', 'person']) {
+      for (const term of banned) {
+        const re = new RegExp(`(^|[^A-Za-z])${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^A-Za-z]|$)`, /^[A-Z+-]+$/.test(term) ? '' : 'i');
+        if (re.test(card[field] || '')) hits.push(`${code}.${field}: "${term}"`);
+      }
+    }
+  }
+  assert.deepEqual(hits, []);
+});
+
+test('every card is complete, and short enough to be read', () => {
+  for (const [code, card] of Object.entries(CARDS)) {
+    assert.ok(card.happened && card.next, `${code} needs happened + next`);
+    assert.equal(typeof card.by_design, 'boolean', `${code}.by_design`);
+    assert.ok(card.person === null || typeof card.person === 'string', `${code}.person is null or who`);
+    for (const f of ['happened', 'next']) assert.ok(card[f].length <= 230, `${code}.${f} is ${card[f].length} chars`);
+  }
+});
+
+test('the restrictions that must never be worked around are marked by_design', () => {
+  for (const code of ['REBASE_REQUIRED', 'INSUFFICIENT_RANK', 'rank_too_low_for_task', 'session_already_has_active_claim',
+    'main_checkout_claim', 'ship:protected_branch', 'ship:auth', 'box_scope', 'no_push_credential', 'grade_refused_authorization']) {
+    assert.equal(cardFor(code)?.by_design, true, code);
+  }
+  assert.match(cardFor('no_push_credential').next, /never ask/i);
+});
+
+// ── the rendering, and the seams that print it ────────────────────────────────
+
+test('plainCardLines renders four labelled lines under the marker, and nothing for an unknown code', () => {
+  const lines = plainCardLines('ALREADY_CLAIMED');
+  assert.ok(lines[0].includes(PLAIN_MARKER));
+  assert.equal(lines.length, 5);
+  assert.deepEqual(plainCardLines('never_heard_of_it'), []);
+  assert.deepEqual(plainCardLines(undefined), []);
+});
+
+test('a card interpolates nothing — it is static text, so it adds no injection surface', () => {
+  for (const card of Object.values(CARDS)) assert.ok(!/\$\{|%s|<[a-z_]+>/.test(JSON.stringify(card)));
+});
+
+test('a refused claim prints the engineer text first and the card after it', () => {
+  const r = { status: 409, data: { error: { code: 'REBASE_REQUIRED', message: 'x', details: { rebaseTasks: [{ id: 7, reason: 'strand:pr_not_landed' }] } } } };
+  const { lines, exit } = formatClaimFailure(r, 42);
+  assert.equal(exit, 1);
+  assert.match(lines[0], /queue is gated/);
+  const at = lines.findIndex((l) => l.includes(PLAIN_MARKER));
+  assert.ok(at > 0, 'card follows the existing guidance');
+  assert.ok(lines.slice(at).join('\n').includes(CARDS.REBASE_REQUIRED.happened));
+  assert.ok(lines.join('\n').includes(CARDS['strand:pr_not_landed'].happened), 'the flagged reason is translated too');
+});
+
+test('an unmapped claim code still renders, just without a card', () => {
+  const { lines } = formatClaimFailure({ status: 500, data: { error: { code: 'SOMETHING_NEW', message: 'm' } } }, 1);
+  assert.ok(lines.length >= 1 && !lines.join('\n').includes(PLAIN_MARKER));
+});
+
+test('a grader outage and a failed grade each carry their own card', () => {
+  const outage = formatGradeOutcome({ passed: false, signals: { panel_outcome: 'unavailable' } }, 9);
+  assert.ok(outage.includes(CARDS.grade_unavailable.happened));
+  const fail = formatGradeOutcome({ passed: false, score: 4, threshold: 7, issues: [] }, 9);
+  assert.ok(fail.includes(CARDS.grade_failed.happened));
+  assert.ok(!formatGradeOutcome({ passed: true, score: 9, threshold: 7 }, 9).includes(PLAIN_MARKER), 'a pass needs no card');
+});
+
+test('a red pull request line is followed by its card', () => {
+  const lines = shipLand.redPrLines({ reason: 'failing_check_unreadable', checks_unreadable: true });
+  assert.ok(lines[0].includes('RED') && lines.join('\n').includes(CARDS.failing_check_unreadable.happened));
+  assert.deepEqual(shipLand.redPrLines({ reason: 'review_required' }), []);
+});
+
+test('a person at a terminal gets no card — it is written in the agent\'s voice', () => {
+  assert.deepEqual(plainCardLines('REBASE_REQUIRED', { BONGOS_SURFACE: 'terminal' }), []);
+  assert.equal(plainCardLines('REBASE_REQUIRED', {}).length, 5);
+});
+
+test('the sign-in printers, the release refusals and the claim guard each print their card', () => {
+  const wired = {
+    'scripts/gds/cli-lib.js': ['session_invalid', 'box_scope', 'no_session'],
+    'scripts/gds/release.js': ['no_active_claim', 'CLAIM_SESSION_MISMATCH'],
+    'scripts/gds/claim.js': ['main_checkout_claim'],
+    'scripts/gds/ship-land.js': ['land_pending', 'reconcile_blocked'],
+    'scripts/gds/push-path-brief.js': ['no_push_credential'],
+  };
+  for (const [file, codes] of Object.entries(wired)) {
+    const src = read(file);
+    for (const code of codes) {
+      assert.ok(src.includes(`plainCardLines('${code}')`), `${file} should print the ${code} card`);
+      assert.ok(cardFor(code), `${code} has no card`);
+    }
+  }
+});
+
+test('every way start.js can refuse or fail prints a card', () => {
+  const src = read('scripts/gds/start.js');
+  const codes = [...src.matchAll(/\.error === '([A-Za-z_]+)'/g)].map((m) => m[1]);
+  assert.ok(codes.includes('stage_required'), 'start.js no longer names its refusal — has the branch moved?');
+  assert.deepEqual(missing(codes), []);
+  for (const code of [...new Set(codes)]) assert.ok(src.includes(`plainCardLines('${code}')`), `start.js never prints the ${code} card`);
+  // The generic non-ok exit is the last way out; it must not be the one mute path.
+  const generic = src.slice(src.indexOf('if (!r.ok) {'));
+  assert.ok(generic.slice(0, generic.indexOf('process.exit(1)')).includes("plainCardLines('board_unavailable')"));
+});
+
+test('no card is an orphan — each is printed by name, or belongs to a family a seam prints by code', () => {
+  const scripts = fs.readdirSync(new URL('../scripts/gds/', import.meta.url)).filter((f) => f.endsWith('.js') && f !== 'plain-cards.js');
+  const printed = new Set();
+  for (const f of scripts) for (const m of read(`scripts/gds/${f}`).matchAll(/plainCardLines\('([^']+)'\)/g)) printed.add(m[1]);
+  // Families reach plainCardLines through a variable: the claim refusal code, the
+  // flagged strand reason, the merge reason on a red pull request, `ship:${d.id}`.
+  const claimSrc = read('scripts/gds/claim.js') + read('modules/lifecycle/db-claims.js') + read('modules/lifecycle/routes/claims.js') + read('modules/lifecycle/goal-authz.js');
+  const mergeSrc = read('modules/lifecycle/github-push.js');
+  const byFamily = (code) => code.startsWith('strand:') || code.startsWith('ship:')
+    || claimSrc.includes(`'${code}'`) || mergeSrc.includes(`'${code}'`) || mergeSrc.includes(`\`${code}:`);
+  const orphans = Object.keys(CARDS).filter((code) => !printed.has(code) && !byFamily(code));
+  assert.deepEqual(orphans, []);
+});
+
+test('the four lifecycle skills tell the agent how to use the card', () => {
+  for (const skill of ['builder-claim', 'builder-ship', 'builder-start', 'builder-release']) {
+    const md = read(`.claude/skills/${skill}/SKILL.md`);
+    assert.ok(md.includes(PLAIN_MARKER), `${skill} never mentions the ${PLAIN_MARKER} card`);
+    assert.match(md, /interaction profile/, `${skill} does not tie the card to the builder's profile`);
+  }
+  assert.match(read('.claude/skills/builder-claim/SKILL.md'), /never look for a way round it/);
+});
+
+test('the public CLI package ships the card file its scripts require', () => {
+  assert.ok(read('scripts/gds/build-cli-package.js').includes("'scripts/gds/plain-cards.js'"));
+});
+
+console.log(`\nplain cards (task 1003989) tests: ${passed} passed, ${failed} failed`);
+process.exitCode = failed > 0 ? 1 : 0;

package/tests/provision.mjs

@@ -566,15 +566,79 @@ await ta('scaffoldStandaloneRepo: idempotent — a repo that already carries pac
     mkdirSync(join(tmp, 'demo'), { recursive: true });
     writeFileSync(join(tmp, 'demo', 'package.json'), '{}\n');   // sign of a completed scaffold
     const { deps, cmds } = recorder({ apply: true });
+    deps.exec = (cmd) => { cmds.push(cmd); return { ok: true, stdout: /ls-remote/.test(cmd) ? 'abc123\trefs/heads/main\n' : '' }; };
     const res = await P.scaffoldStandaloneRepo({ slug: 'demo', hosting_shape: 'standalone', target_ref: 'example-owner/demo' }, deps);
     assert.equal(res.already, true);
-    assert.equal(cmds.length, 0, 'no init/build/push when already scaffolded');
+    assert.deepEqual(cmds.filter((c) => !/ls-remote/.test(c)), [], 'no init/build/push when already scaffolded AND the remote carries main');
   } finally {
     P.CONFIG.standaloneBase = origBase;
     rmSync(tmp, { recursive: true, force: true });
   }
 });
 
+// F12 (task 1002718): package.json is a LOCAL marker, so a scaffold whose push failed left it
+// behind — the re-run skipped the never-done push and wedged at step 2's `git pull --ff-only`
+// on the empty remote. The runner now asks the remote before skipping.
+async function rerunScaffold({ apply = true, lsRemote, token = null, credWriteThrows = false }) {
+  const tmp = mkdtempSync(join(tmpdir(), 'scaffold-resume-'));
+  const origBase = P.CONFIG.standaloneBase;
+  P.CONFIG.standaloneBase = tmp;
+  try {
+    mkdirSync(join(tmp, 'demo'), { recursive: true });
+    writeFileSync(join(tmp, 'demo', 'package.json'), '{}\n');
+    const { deps, cmds } = recorder({ apply });
+    const writes = [];
+    deps.exec = (cmd) => { cmds.push(cmd); return /ls-remote/.test(cmd) ? lsRemote : { ok: true, stdout: '' }; };
+    deps.writeFile = (p, body, opts) => {
+      if (credWriteThrows && /bongos-gitcred/.test(p)) throw new Error('EACCES: tmp not writable');
+      writes.push({ p, body, opts }); return { ok: true };
+    };
+    if (token) deps.getGithubToken = async () => ({ token, scope: 'repo' });
+    const res = await P.scaffoldStandaloneRepo({ slug: 'demo', hosting_shape: 'standalone', target_ref: 'example-owner/demo', owner_builder_id: 7 }, deps);
+    return { res, cmds, writes };
+  } finally {
+    P.CONFIG.standaloneBase = origBase;
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+await ta('scaffoldStandaloneRepo: a scaffold whose push never landed RE-PUSHES on re-run (remote has no main) — F12, task 1002718', async () => {
+  const { res, cmds } = await rerunScaffold({ lsRemote: { ok: true, stdout: '' } });
+  const joined = cmds.join('\n');
+  assert.equal(res.resumed, true);
+  assert.match(joined, /ls-remote --heads [^\n]*origin main/, 'asks the remote whether main exists');
+  assert.match(joined, /git -C [^\n]* push -u origin main/, 're-pushes the scaffold commit');
+  assert.ok(!/init\.js|package-core|commit -m|--force/.test(joined), 'does NOT re-scaffold, re-commit or force — only the owed push');
+});
+
+await ta('scaffoldStandaloneRepo: the resume push rides the owner token and removes its credential file (F12)', async () => {
+  const { cmds, writes } = await rerunScaffold({ lsRemote: { ok: true, stdout: '' }, token: 'gho_RESUME_SECRET' });
+  const joined = cmds.join('\n');
+  assert.ok(!joined.includes('gho_RESUME_SECRET'), 'token never appears in a command string');
+  assert.match(joined, /credential\.helper='store --file=[^']*bongos-gitcred-demo[^']*' ls-remote --heads https:\/\/x-access-token@github\.com\/example-owner\/demo\.git main/);
+  assert.match(joined, /credential\.helper='store --file=[^']*bongos-gitcred-demo[^']*' push https:\/\/x-access-token@github\.com\/example-owner\/demo\.git HEAD:main/);
+  assert.equal(writes.find((w) => /bongos-gitcred-demo/.test(w.p)).opts.mode, 0o600);
+  assert.match(cmds[cmds.length - 1], /rm -f [^\n]*bongos-gitcred-demo/, 'credential file removed last');
+});
+
+await ta('scaffoldStandaloneRepo: an UNREACHABLE remote keeps the old skip — only a confirmed-empty remote re-pushes (F12)', async () => {
+  const { res, cmds } = await rerunScaffold({ lsRemote: { ok: true, stdout: '', softFailed: true } });
+  assert.equal(res.already, true);
+  assert.ok(!cmds.some((c) => /push/.test(c)), cmds.join(' | '));
+});
+
+await ta('scaffoldStandaloneRepo: a probe that cannot start (credential write throws) keeps the skip — a live instance is never failed by it (F12)', async () => {
+  const { res, cmds } = await rerunScaffold({ lsRemote: { ok: true, stdout: '' }, token: 'gho_X', credWriteThrows: true });
+  assert.equal(res.already, true);
+  assert.ok(!cmds.some((c) => /push|ls-remote/.test(c)), cmds.join(' | '));
+});
+
+await ta('scaffoldStandaloneRepo: dry-run of an already-scaffolded repo probes nothing (F12)', async () => {
+  const { res, cmds } = await rerunScaffold({ apply: false, lsRemote: { ok: true, stdout: '' } });
+  assert.equal(res.already, true);
+  assert.deepEqual(cmds, []);
+});
+
 // ── ADR 0134 (task 2090): registry core-install path + fail-soft to vendored ──
 // Runs the scaffold against a FRESH standaloneBase (no package.json → it proceeds) with
 // an injected env, and asserts which core-resolution shape it chose from the commands.
@@ -1499,6 +1563,30 @@ await ta('teardownInstance(dedicated): no systemd steps at all, so no reset-fail
   assert.ok(!cmds.some((c) => /reset-failed|daemon-reload|disable --now/.test(c)), cmds.join(' | '));
 });
 
+// F6 (task 1002718): main() builds deps.doApi on first READ, so a caller must only read it
+// on a path that really calls DigitalOcean — a throwing getter proves the others never do.
+function doApiTripwire(deps) {
+  Object.defineProperty(deps, 'doApi', { get() { throw new Error('read deps.doApi on a path that makes no DO call'); } });
+  return deps;
+}
+
+await ta('teardownInstance(dedicated, no droplet_id) under --apply never reads deps.doApi (F6)', async () => {
+  const { deps } = recorder({ apply: true });
+  await P.teardownInstance({ ...coTenant, hosting_shape: 'dedicated', droplet_id: null }, doApiTripwire(deps));
+});
+
+await ta('provisionInstance(co-tenant) under --apply never reads deps.doApi (F6)', async () => {
+  const { deps } = recorder({ apply: true });
+  const r = await P.provisionInstance(coTenant, doApiTripwire(deps));
+  assert.ok(!/deps\.doApi/.test(String(r && r.error)), String(r && r.error));
+});
+
+t('main() constructs the DO client lazily — no DO_API_TOKEN needed until a DO call (F6)', () => {
+  const src = readFileSync(new URL('../scripts/gds/provision.js', import.meta.url), 'utf8');
+  assert.match(src, /get doApi\(\)/, 'deps.doApi is a getter');
+  assert.ok(!/doApi:\s*DoApi \? new DoApi/.test(src), 'no eager construction at deps build');
+});
+
 await ta('teardownInstance(default): NO sudo (bare, unchanged)', async () => {
   const { deps, cmds } = recorder();
   await P.teardownInstance(coTenant, deps);

package/tests/rebase_gate_unprovable.mjs

@@ -0,0 +1,134 @@
+// tests/rebase_gate_unprovable.mjs — a strand the builder CANNOT clear must stop
+// blocking their queue without stopping being reported (task 1003294).
+//
+// THE BUG. publish-reconciler proves a land by looking for a branch / published tip
+// in the CORE repo. A task that legitimately delivers into the INSTANCE repo (task
+// 1003253 — a real, complete, deployed commit on the instance host) can never be
+// proven here, so the sweep writes needs_rebase_reason='strand:no_branch_no_tip'.
+// ADR 0120 part 3 then refuses that builder EVERY new claim until they land or
+// release it — and they can do neither, because there is nothing in this repository
+// to land. The recorded remedy was a hand-run SQL UPDATE on the droplet.
+//
+// THE SHAPE OF THE FIX, and what these tests are really protecting: the gate and the
+// SURFACING were one function. "Stop blocking" must not become "stop telling them",
+// so the fix SPLITS them — gatingRebaseTasksForBuilder may release a strand past the
+// grace, needsRebaseTasksForBuilder keeps answering in full for me.js / the hall /
+// the CLI. Re-collapsing the two is the regression this file exists to catch.
+//
+// SQL SEMANTICS ARE NOT TESTED HERE — they need a real Postgres and live in
+// tests/claim_gate_rebase.mjs (INTEGRATION set). What is testable DB-free is the
+// wiring, the parameters, and the NULL-handling SHAPE of the predicate, and a
+// fail-open in that shape is the dangerous mistake, so it is asserted directly.
+//
+// Run:  node tests/rebase_gate_unprovable.mjs
+
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const { test, summary } = makeRunner();
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => readFileSync(path.join(REPO_ROOT, rel), 'utf8');
+
+const shipMod = require('../modules/lifecycle/db-ship.js');
+const CLAIMS = read('modules/lifecycle/db-claims.js');
+const SHIP = read('modules/lifecycle/db-ship.js');
+const RECON = read('modules/lifecycle/publish-reconciler.js');
+
+// A client that records what it was asked, so the query can be inspected without a DB.
+const spyClient = () => {
+  const seen = [];
+  return { seen, query: async (sql, params) => { seen.push({ sql, params }); return { rows: [] }; } };
+};
+
+await test('the CLAIM GATE asks the gating query, not the surfacing one', async () => {
+  assert.match(CLAIMS, /gatingRebaseTasksForBuilder\(builderId, client\)/,
+    'claimTask must consult the gating subset');
+  assert.doesNotMatch(CLAIMS, /needsRebaseTasksForBuilder\(/,
+    'the gate must NOT use the unfiltered surfacing query — that is the bug, restored');
+});
+
+await test('the SURFACING query still returns everything — no exclusion at all', () => {
+  const body = SHIP.slice(
+    SHIP.indexOf('async function needsRebaseTasksForBuilder'),
+    SHIP.indexOf('// The ship gate (task 1002483')
+  );
+  assert.ok(body.length > 0, 'needsRebaseTasksForBuilder must still exist');
+  assert.doesNotMatch(body, /interval '1 millisecond'/,
+    'the surfacing query must not inherit the gate grace — the builder still sees the strand');
+  assert.doesNotMatch(body, /no_branch_no_tip/,
+    'the surfacing query must not filter on the strand reason');
+});
+
+await test('the gating query is parameterised with the grace and the reason', async () => {
+  const c = spyClient();
+  await shipMod.gatingRebaseTasksForBuilder(4242, c);
+  assert.equal(c.seen.length, 1);
+  const { sql, params } = c.seen[0];
+  assert.equal(params[0], 4242, 'builder id');
+  assert.equal(params[1], shipMod.UNPROVABLE_GATE_GRACE_MS, 'the grace is passed, not inlined');
+  assert.equal(params[2], 'strand:no_branch_no_tip',
+    'the reason is passed in the SPELLING announceStrand stores (strand:<reason>)');
+  assert.match(sql, /needs_rebase = true AND status = 'confirmed' AND shipped_by = \$1/,
+    'it must still be the same set of owed rebases, only narrowed');
+});
+
+await test('an explicit grace overrides the default — the window is tunable', async () => {
+  const c = spyClient();
+  await shipMod.gatingRebaseTasksForBuilder(1, c, 5_000);
+  assert.equal(c.seen[0].params[1], 5_000);
+});
+
+await test('a negative or junk grace degrades to 0, never to a negative interval', async () => {
+  // A negative interval would make `needs_rebase_at < now() + X` true for FRESH
+  // strands — releasing the gate immediately, the exact inversion of the intent.
+  for (const bad of [-1, NaN, undefined, 'nonsense']) {
+    const c = spyClient();
+    await shipMod.gatingRebaseTasksForBuilder(1, c, bad);
+    assert.ok(c.seen[0].params[1] >= 0, `grace ${String(bad)} must not go negative`);
+  }
+});
+
+await test('the predicate is FAIL-CLOSED on NULLs — an unknown keeps the gate', () => {
+  const body = SHIP.slice(SHIP.indexOf('async function gatingRebaseTasksForBuilder'));
+  const q = body.slice(0, body.indexOf('return rows;'));
+  // A bare `needs_rebase_reason = $3` yields NULL for a NULL reason, and
+  // NOT(NULL AND true AND true) is NULL, which drops the row from the WHERE —
+  // releasing the gate for a row we know nothing about. COALESCE removes the NULL.
+  assert.match(q, /COALESCE\(needs_rebase_reason, ''\) = \$3/,
+    'the reason comparison must not be able to produce NULL');
+  assert.match(q, /needs_rebase_at IS NOT NULL/,
+    'a NULL timestamp must not participate in the age comparison');
+  assert.match(q, /AND NOT \(/, 'the exclusion is expressed as NOT over non-NULL operands');
+});
+
+await test('the reconciler ESCALATES past the grace instead of going quiet', () => {
+  assert.match(RECON, /UNPROVABLE_GATE_GRACE_MS/,
+    'the sweep must use the SAME constant as the gate, not a second number that can drift');
+  assert.match(RECON, /require\('\.\/db-ship\.js'\)/, 'imported rather than restated');
+  assert.match(RECON, /UNPROVABLE task \$\{r\.task_id\}/,
+    'an ungated strand must still be named on every sweep');
+  assert.match(RECON, /still confirmed and still unlanded/,
+    'the log must say this is not a resolution');
+});
+
+await test('releasing the gate does NOT clear the flag — the row stays owed', () => {
+  // The fix must not touch needs_rebase/needs_rebase_reason. If a future change
+  // "tidied up" by clearing the flag past the grace, the strand would vanish from
+  // every surfacing and the task would silently sit confirmed forever.
+  const body = SHIP.slice(SHIP.indexOf('async function gatingRebaseTasksForBuilder'));
+  const q = body.slice(0, body.indexOf('return rows;'));
+  assert.doesNotMatch(q, /UPDATE|SET /, 'the gating query must be a pure read');
+});
+
+await test('the grace is bounded and sane by default', () => {
+  assert.ok(shipMod.UNPROVABLE_GATE_GRACE_MS > 0, 'a zero default would never gate at all');
+  assert.ok(shipMod.UNPROVABLE_GATE_GRACE_MS >= 60 * 60_000,
+    'too short and case (a) — the builder who simply never pushed — escapes the gate that exists for them');
+});
+
+summary();