@bongos/core 1.19.835 → 1.19.837

package/scripts/gds/runner-drift.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// scripts/gds/runner-drift.js — do the intent-runner units run the core this instance installed? (task 1002722)
+//
+// WHY. For weeks the prod intent runners ran core 1.19.2 from a retired clone while the
+// instance served a current core, so an owner's domain-attach click executed as a TEARDOWN
+// (task 1002716). The hotfix repointed the units with systemd drop-ins; nothing noticed the
+// drift, and the only tell was a PWD in sudo logs. This reads each `*intent-runner*` unit the
+// way systemd does (a drop-in overrides the base file), finds the core package the ExecStart
+// script lives in, and compares its version to the instance's installed @bongos/core.
+//
+// A unit whose version cannot be read — a shell wrapper that picks the core at runtime, a
+// missing package — is UNRESOLVED, never ok: a gate that guesses green is the incident again.
+//
+//   node scripts/gds/runner-drift.js [--instance-root <dir>] [--json]
+//     exit 0 = every unit resolved and matched (or no systemd here), 1 = drift, 2 = bad usage.
+//     Unresolved units are listed but do not fail the run. `bongos doctor` runs the same check.
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const CORE_NAMES = ['@bongos/core', '@cloudbongos/core'];
+const P = path.posix;   // unit files describe the Linux control plane, whatever runs the tests
+
+// The effective WorkingDirectory + ExecStart lines from `systemctl cat` output. Later files
+// are drop-ins: a later WorkingDirectory wins, an empty `ExecStart=` clears the list, and a
+// drop-in that only ADDS one leaves the base command running too (oneshot runs them all).
+function effectiveUnit(catText) {
+  let workingDirectory = null;
+  let execs = [];
+  for (const raw of String(catText || '').split(/\r?\n/)) {
+    const line = raw.trim();
+    const m = line.match(/^(WorkingDirectory|ExecStart)=(.*)$/);
+    if (!m) continue;
+    const value = m[2].trim();
+    if (m[1] === 'WorkingDirectory') workingDirectory = value.replace(/^-/, '') || null;
+    else if (value === '') execs = [];
+    else execs.push(value);
+  }
+  return { workingDirectory, execStarts: execs };
+}
+
+// The absolute path of the .js script an ExecStart runs, or null when its first argument is
+// not one (a shell wrapper decides at runtime which core it loads).
+function runnerScriptPath({ workingDirectory, execStart }) {
+  const tokens = String(execStart || '').trim().split(/\s+/).filter(Boolean);
+  if (!tokens.length) return null;
+  let i = 0;
+  if (P.basename(tokens[i].replace(/^[@\-:+!]+/, '')) === 'env') {
+    i++;
+    while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
+  }
+  const script = tokens.slice(i + 1).find((tok) => !tok.startsWith('-'));
+  if (!script || !/\.[cm]?js$/.test(script)) return null;
+  if (script.startsWith('/')) return script;
+  return workingDirectory ? P.join(workingDirectory, script) : null;
+}
+
+function readJson(p, fsImpl) {
+  try { return JSON.parse(fsImpl.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+// The core version a script belongs to: the nearest enclosing @bongos/core package, or a
+// source checkout's CORE_VERSION. Null when neither is found.
+function coreVersionFor(scriptPath, { fsImpl = fs } = {}) {
+  let dir = P.dirname(String(scriptPath || ''));
+  for (;;) {
+    const pkg = readJson(P.join(dir, 'package.json'), fsImpl);
+    if (pkg && CORE_NAMES.includes(pkg.name) && pkg.version) return String(pkg.version);
+    try {
+      const m = String(fsImpl.readFileSync(P.join(dir, 'src', 'module-api.js'), 'utf8')).match(/CORE_VERSION\s*=\s*['"]([^'"]+)['"]/);
+      if (m) return m[1];
+    } catch { /* not a checkout root */ }
+    const up = P.dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+function installedCoreVersion(instanceRoot, { fsImpl = fs } = {}) {
+  if (!instanceRoot) return null;
+  for (const name of CORE_NAMES) {
+    const pkg = readJson(P.join(instanceRoot, 'node_modules', name, 'package.json'), fsImpl);
+    if (pkg && pkg.version) return String(pkg.version);
+  }
+  return null;
+}
+
+function assessExecStart({ workingDirectory, execStart, instanceVersion, instanceRoot, fsImpl }) {
+  const scriptPath = runnerScriptPath({ workingDirectory, execStart });
+  const base = { scriptPath, runnerVersion: null, instanceVersion };
+  if (!scriptPath) return { ...base, status: 'unresolved', reason: `ExecStart does not run a .js script directly (${execStart}) — cannot tell which core it loads` };
+  const runnerVersion = coreVersionFor(scriptPath, { fsImpl });
+  const found = { ...base, runnerVersion };
+  if (!runnerVersion) return { ...found, status: 'unresolved', reason: `no core version found above ${scriptPath}` };
+  if (!instanceVersion) return { ...found, status: 'unresolved', reason: `no installed @bongos/core under ${instanceRoot}` };
+  if (runnerVersion === instanceVersion) return { ...found, status: 'ok', reason: `runs core ${runnerVersion}` };
+  return { ...found, status: 'drift', reason: `runs core ${runnerVersion} (${scriptPath}) but the instance installed ${instanceVersion} at ${instanceRoot}` };
+}
+
+// One verdict per unit, from its WORST ExecStart: drift, then unresolved, then ok.
+function assessRunnerUnit({ name, catText, instanceRoot, fsImpl = fs }) {
+  const { workingDirectory, execStarts } = effectiveUnit(catText);
+  const instanceVersion = installedCoreVersion(instanceRoot, { fsImpl });
+  if (!execStarts.length) return { name, status: 'unresolved', reason: 'no ExecStart in the unit', scriptPath: null, runnerVersion: null, instanceVersion };
+  const all = execStarts.map((execStart) => assessExecStart({ workingDirectory, execStart, instanceVersion, instanceRoot, fsImpl }));
+  const worst = ['drift', 'unresolved', 'ok'].map((s) => all.find((r) => r.status === s)).find(Boolean);
+  return { name, ...worst };
+}
+
+function parseUnitList(stdout) {
+  return String(stdout || '').split(/\r?\n/).map((l) => l.trim().split(/\s+/)[0]).filter((n) => n && n.endsWith('.service'));
+}
+
+// The first line of every run-intents, so a journal grep shows a stale runner at once.
+function runnerBanner({ runnerVersion, runnerRoot, instanceVersion, instanceRoot }) {
+  const tail = instanceVersion ? `instance core ${instanceVersion} at ${instanceRoot}` : `no installed core at ${instanceRoot}`;
+  const line = `runner core ${runnerVersion || '?'} from ${runnerRoot} (${tail})`;
+  return runnerVersion && instanceVersion && runnerVersion !== instanceVersion ? `⚠ DRIFT: ${line}` : line;
+}
+
+// Every intent-runner unit on this host, assessed. Null when there is no systemd to ask.
+function collectRunnerDrift({ instanceRoot }) {
+  const run = (args) => spawnSync('systemctl', args, { encoding: 'utf8', timeout: 15000 });
+  const list = run(['list-units', '--all', '--plain', '--no-legend', '--no-pager', '--type=service', '*intent-runner*']);
+  if (list.error || list.status !== 0) return null;
+  return parseUnitList(list.stdout).map((name) => {
+    const cat = run(['cat', '--no-pager', name]);
+    return assessRunnerUnit({ name, catText: cat.status === 0 ? cat.stdout : '', instanceRoot });
+  });
+}
+
+function main(argv) {
+  const at = argv.indexOf('--instance-root');
+  const instanceRoot = (at >= 0 ? argv[at + 1] : null) || process.env.BONGOS_INSTANCE_ROOT;
+  if (!instanceRoot) {
+    console.error('runner-drift: name the instance root — --instance-root <dir> or BONGOS_INSTANCE_ROOT');
+    return 2;
+  }
+  const results = collectRunnerDrift({ instanceRoot });
+  if (argv.includes('--json')) console.log(JSON.stringify({ instanceRoot, systemd: results !== null, units: results || [] }, null, 2));
+  else if (results === null) console.log('runner-drift: no systemd on this host — nothing to check');
+  else if (!results.length) console.log('runner-drift: no *intent-runner* units on this host');
+  else for (const r of results) console.log(`${r.status === 'ok' ? '✓' : r.status === 'drift' ? '✖' : '?'} ${r.name}: ${r.reason}`);
+  return results && results.some((r) => r.status === 'drift') ? 1 : 0;
+}
+
+module.exports = { effectiveUnit, runnerScriptPath, coreVersionFor, installedCoreVersion, assessRunnerUnit, parseUnitList, runnerBanner, collectRunnerDrift };
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));

package/scripts/gds/ship-flow.js

@@ -10,6 +10,7 @@
 
 const { cliClient, requireSession, arg, detectWorktreeName, cardFlagsFromMe } = require('./cli-lib');
 const { resolveProse, markShipProgress, smokeGateMessages, proseFlagPresent, regradeNotesRefusal, staleSummaryNotice } = require('./ship-honesty.js');
+const { plainCardLines } = require('./plain-cards.js');
 const { classifyEmptyShip } = require('../../modules/lifecycle/ship-preflight');
 const { isModuleKey, scopeForModule, moduleDriftFiles: computeModuleDrift } = require('../../src/bongos/module-scope-map');
 const { runShipGate } = require('./sandbox-stage');
@@ -251,12 +252,14 @@ async function shipMain() {
       console.error('');
       console.error('Your work was never committed — shipping now would mark the task "shipped" with NO artifact on main (the ledger would lie).');
       console.error('Stage + commit your work (e.g. `git add -A && git commit`), then re-run /builder-ship. Your claim is still active.');
+      for (const line of plainCardLines('uncommitted_work')) console.error(line);
       process.exit(1);
     }
     if (verdict.reason === 'nothing-to-ship') {
       console.error(`Nothing to ship: the committed diff vs ${graderBaseline || 'baseline'} is empty and the working tree is clean.`);
       console.error('The grader reads committed history, not the working tree — commit your work on this branch, then re-run /builder-ship. Your claim is still active.');
       console.error('If this task legitimately has no code/doc artifact (a pure DB-only or no-op task), re-run with --allow-empty.');
+      for (const line of plainCardLines('nothing_to_ship')) console.error(line);
       process.exit(1);
     }
     // verdict.reason === 'allow-empty': a deliberate no-artifact / DB-only ship.
@@ -425,6 +428,7 @@ async function shipMain() {
   if (!passed && !allowSmokeFail) {
     console.error('');
     for (const line of smokeGateMessages(taskId).abort) console.error(line);
+    for (const line of plainCardLines('smoke_failed')) console.error(line);
     process.exit(1);
   }
 

package/scripts/gds/ship-grade-steps.js

@@ -14,6 +14,7 @@ const os = require('node:os');
 const { cliClient, rewardPolicy } = require('./cli-lib');
 const { gitOk } = require('./ship-git.js');
 const { resolveInstanceBase } = require('./ship-deploy-target.js');
+const { plainCardLines } = require('./plain-cards.js');
 // task 1003313: the shared onboarding/doctor preflight — reused (not duplicated)
 // so the grader outage explains itself with the same `claude CLI` verdict doctor
 // gives, and the two can never drift.
@@ -294,6 +295,7 @@ function formatGradeOutcome(g, taskId, cliFinding = null) {
     out.push(`  node scripts/gds/ship.js ${taskId} --regrade`);
     out.push('Or land it now via manual-confirm:');
     out.push(`  curl -X POST -H "Authorization: Bearer <token>" ${resolveInstanceBase() || '<instance-origin>'}/api/bongos/tasks/${taskId}/confirm`);
+    out.push(...plainCardLines('grade_unavailable'));
     return out.join('\n');
   }
 
@@ -324,6 +326,7 @@ function formatGradeOutcome(g, taskId, cliFinding = null) {
     out.push('  - Split the protected files out of your diff and re-ship the rest, or');
     out.push('  - hand this task to a builder at/above the floor the refusal names.');
     out.push(`(--regrade re-runs the same server check and will refuse again unless the diff changes.)`);
+    out.push(...plainCardLines('grade_refused_authorization'));
     return out.join('\n');
   }
 
@@ -351,6 +354,7 @@ function formatGradeOutcome(g, taskId, cliFinding = null) {
     out.push(`  node scripts/gds/ship.js ${taskId} --regrade`);
     out.push('Or land it now via manual-confirm:');
     out.push(`  curl -X POST -H "Authorization: Bearer <token>" ${resolveInstanceBase() || '<instance-origin>'}/api/bongos/tasks/${taskId}/confirm`);
+    out.push(...plainCardLines('grade_lens_unavailable'));
     return out.join('\n');
   }
 
@@ -378,6 +382,7 @@ function formatGradeOutcome(g, taskId, cliFinding = null) {
     out.push(`  node scripts/gds/ship.js ${taskId} --regrade`);
     out.push('Last resort (only if the grade was wrong):');
     out.push(`  curl -X POST -H "Authorization: Bearer <token>" ${resolveInstanceBase() || '<instance-origin>'}/api/bongos/tasks/${taskId}/confirm`);
+    out.push(...plainCardLines('grade_failed'));
   }
   return out.join('\n');
 }

package/scripts/gds/ship-land.js

@@ -15,6 +15,7 @@ const { cliClient, isBoxScope } = require('./cli-lib');
 const { gitArgvOk, gitOk, sanitizeGitHubRefs, shellOk } = require('./ship-git.js');
 const { buildPrCreateArgv, buildPrMergeArgv, deployRunSucceeded, deployedCommitStatus, fetchDeployedVersion, ghArgvOk, ghJson, pushVia, resolveInstanceBase } = require('./ship-deploy-target.js');
 const { normalizeApiError } = require('./ship-io.js');
+const { plainCardLines } = require('./plain-cards.js');
 
 // ---------- the land outcome (task 1002541, part 1) ----------
 //
@@ -311,6 +312,7 @@ function landPendingLines(taskId, { merged } = {}) {
 function printLandPending(taskId, opts = {}) {
   console.log('');
   for (const line of landPendingLines(taskId, opts)) console.log(line);
+  for (const line of plainCardLines('land_pending')) console.log(line);
 }
 
 // task 1002645 — the honest close-out when the PR MERGED but the server refused the
@@ -349,6 +351,14 @@ function redPrLine(md) {
   return named ? `  ci-land: the PR is RED — the \`${named[1]}\` check failed; ${fix}` : null;
 }
 
+// redPrLines — the red line followed by the same reason in plain words (task 1003989).
+// The card is keyed on the merge reason; when the failing tests were readable that
+// reason is `failing_check:<name>`, which resolves to the failing_check card.
+function redPrLines(md) {
+  const red = redPrLine(md);
+  return red ? [red, ...plainCardLines((md && md.reason) || 'failing_check')] : [];
+}
+
 // One module-scope sleep command shared by both poll loops (task 1093 / C9). A
 // child `node -e setTimeout` is used (not `await new Promise`) so it blocks
 // identically in the SYNCHRONOUS pollCiDeploy and the async pollServerPublish —
@@ -377,7 +387,7 @@ async function pollServerPublish(taskId, branch) {
       const red = redPrLine(r.data.merge_driver);
       if (red && red !== redLine) {
         redLine = red;
-        console.log(red);
+        for (const line of redPrLines(r.data.merge_driver)) console.log(line);
       }
       const outcome = classifyLandOutcome(r.data);
       if (outcome === 'shipped') {
@@ -401,6 +411,7 @@ async function pollServerPublish(taskId, branch) {
   if (blockedReason) {
     console.log('');
     for (const line of reconcileBlockedLines(taskId, blockedReason)) console.log(line);
+    for (const line of plainCardLines('reconcile_blocked')) console.log(line);
     return landBailed(`the PR merged but the server could not prove the land is this task's: ${blockedReason}`, `node scripts/gds/ship.js ${taskId}`);
   }
   printLandPending(taskId);
@@ -562,6 +573,7 @@ async function ciLandLocal(taskId, branch, valueSummary) {
     } else {
       console.log(`  ci-land: to retry — ${d.fix}`);
     }
+    for (const line of plainCardLines(`ship:${d.id}`)) console.log(line);
     return landBailed(
       `could not push ${branch} to origin (${d.id})`,
       d.terminal ? d.fix.split('\n')[0] : `node scripts/gds/ship.js ${taskId}`,
@@ -713,6 +725,7 @@ module.exports = {
   pickStaleGateReviewRun,
   reconcileBlockedLines,
   redPrLine,
+  redPrLines,
   reconciledCardStatus,
   strandCommand,
   strandNextStep,

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.835'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.837'; // 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

@@ -1219,6 +1219,21 @@ await ta('cmdRunIntents (dry-run) lists the pending queue, runs nothing', async
   assert.equal(r.ran, 0);
 });
 
+await ta('cmdRunIntents opens with the runner core version + path, so a journal grep shows a stale runner (task 1002722)', async () => {
+  for (const apply of [false, true]) {
+    const lines = [];
+    const deps = {
+      apply, log: (l) => lines.push(l), instanceRoot: '/no/such/instance',
+      db: { query: async () => ({ rows: [] }) },
+      provisioning: { claimNextIntent: async () => null, claimNextOAuthManifest: async () => null },
+      exec: () => ({ ok: true }), writeFile: () => ({ ok: true }),
+    };
+    await P.cmdRunIntents(deps);
+    const { REPO_ROOT } = require('../scripts/gds/provision-config.js');
+    assert.equal(lines[0], `runner core ${P.coreVersionSafe()} from ${REPO_ROOT} (no installed core at /no/such/instance)`, `apply=${apply}`);
+  }
+});
+
 await ta('cmdRunIntents (--apply) claims → provisions → resolves the intent done', async () => {
   let claims = 0; const resolved = [];
   const deps = {
@@ -2240,6 +2255,9 @@ await ta('cmdRunIntents (--apply): an UNKNOWN intent action never falls through
   assert.equal(resolved.length, 1);
   assert.equal(resolved[0].state, 'error');
   assert.ok(!cmds.some((c) => /systemctl (stop|disable)/.test(c)), 'no teardown commands ran');
+  // task 1002722 (the refusal itself landed in task 1002692): the error names the action AND
+  // the runner's core, so a stale runner is diagnosable from the intent row alone.
+  assert.equal(resolved[0].err, `unknown_action 'oauth-manifest' — runner core ${P.coreVersionSafe()} does not know it (runner too old?); refusing to guess`);
 });
 
 console.log('\nprovisioning truthfulness (task 1002720 — QA-walk F15/F16/F19):');