@bongos/core 1.19.835 → 1.19.837

package/scripts/gds/cli-lib.js

@@ -528,6 +528,7 @@ function printUnauthGuidanceAndExit() {
   console.error('  Once re-authed, re-run whichever command you were trying.');
   // `doctor` is checkout-only — it is not one of the public CLI's verbs (ADR 0258).
   if (!isTerminalSurface()) console.error('  For a full diagnosis, run: node scripts/gds/doctor.js');
+  for (const line of plainCardLines('session_invalid')) console.error(line);
   console.error('');
   process.exit(2);
 }
@@ -572,6 +573,7 @@ function printBoxScopeGuidanceAndExit() {
   console.error('  YOUR machine — under "CLI Access" click "Re-issue CLI token", copy the one-liner, paste it back.');
   console.error('  No terminal Device Flow. Once re-authed, re-run whichever command you were');
   console.error('  trying — if it had already done work, it resumes from where it stopped (task 941).');
+  for (const line of plainCardLines('box_scope')) console.error(line);
   console.error('');
   process.exit(10); // 10 = "re-auth needed" (matches reauth.js's exit code)
 }
@@ -655,6 +657,7 @@ function printInstanceMismatchAndExit({ expected, actual }) {
   console.error('');
   console.error('  Intentionally targeting another instance? Set the base explicitly, e.g.');
   console.error(`    ${pfx}_API_BASE=${actual} <your command>`);
+  for (const line of plainCardLines('instance_mismatch')) console.error(line);
   console.error('');
   process.exit(3); // 3 = instance mismatch (distinct from 2 = unauth, 10 = box-scope)
 }
@@ -879,6 +882,7 @@ async function requireSession() {
       console.error(`  • First time on the project  → run /builder-setup   (one-time GitHub sign-in that also registers you)`);
       console.error(`  • Signed in before / expired → run /builder-reauth  (fast UI re-issue of your CLI token)`);
     }
+    for (const line of plainCardLines('no_session')) console.error(line);
     process.exit(2);
   }
   return s;
@@ -984,6 +988,13 @@ function isTerminalSurface() {
   catch (_) { return false; }
 }
 
+// The same refusal in plain words, for an agent to relay (task 1003989). Same fail-open
+// shape as the two helpers above: a guidance printer must never die on its own footnote.
+function plainCardLines(code) {
+  try { return require('./plain-cards').plainCardLines(code); }
+  catch (_) { return []; }
+}
+
 function nudgeActionForStage(stage) {
   switch (stage) {
     case 'auth_complete':

package/scripts/gds/doctor.js

@@ -375,12 +375,38 @@ function checkDeployTooling() {
   }
 }
 
+// Intent-runner drift (task 1002722): a runner on a stale core once turned a domain-attach
+// into a teardown (task 1002716). Only a host with *intent-runner* units shows this section,
+// so a builder laptop or dev box sees nothing.
+function runnerDriftRows(results) {
+  return (results || []).map((r) => {
+    const msg = `${r.name}: ${r.reason}`;
+    if (r.status === 'ok') return { status: 'ok', msg };
+    if (r.status === 'drift') return { status: 'fail', msg: `${msg} — repoint the unit's WorkingDirectory + ExecStart at the installed core (a systemd drop-in, as task 1002716 did).` };
+    return { status: 'warn', msg };
+  });
+}
+
+function checkRunnerDrift() {
+  let rows = [];
+  try {
+    const { collectRunnerDrift } = require('./runner-drift.js');
+    rows = runnerDriftRows(collectRunnerDrift({ instanceRoot: process.env.BONGOS_INSTANCE_ROOT || process.cwd() }));
+  } catch (_) {
+    return;
+  }
+  if (!rows.length) return;
+  section('Intent runners');
+  const emit = { ok, warn, fail };
+  for (const row of rows) emit[row.status]('runners', row.msg);
+}
+
 // --------------------------------------------------------------------------
 // main
 // --------------------------------------------------------------------------
 // Guarded so requiring this file for its pure helpers (tests/doctor_hooks.mjs)
 // does not run the checks, which shell out to git and hit the network.
-module.exports = { classifyHooksState };
+module.exports = { classifyHooksState, runnerDriftRows };
 
 if (require.main === module) (async () => {
   console.log(`${C.bold}GDS Doctor${C.reset} — local-machine health check`);
@@ -390,6 +416,7 @@ if (require.main === module) (async () => {
   checkGitPlumbing();
   await checkRepoState();
   checkEnvironment();
+  checkRunnerDrift();
 
   const fails = findings.filter((f) => f.status === 'fail').length;
   const warns = findings.filter((f) => f.status === 'warn').length;

package/scripts/gds/plain-cards.js

@@ -0,0 +1,348 @@
+// scripts/gds/plain-cards.js — the plain-language card for every failure a builder can
+// be parked behind (task 1003989).
+//
+// WHY. The CLIs explain a refusal in engineer prose, and the lifecycle skills told the
+// agent to relay it verbatim — so a non-technical builder met `REBASE_REQUIRED` or
+// `strand:pr_not_landed` raw, at the moment they were most stuck, whatever their
+// interaction profile said. A card says the same thing four ways a person can use:
+// what happened, what the agent will do next, whether a PERSON is needed (and who), and
+// whether this is a rule rather than a fault. That last one is the expensive mistake:
+// an agent that reads a deliberate restriction as breakage goes looking for a way round
+// it (the box session that asked the owner for a personal access token).
+//
+// STATIC TEXT ONLY. A card interpolates nothing — no task title, no server message — so
+// printing it adds no prompt-injection surface (the strand-watch / push-path-brief rule).
+// The engineer text above it keeps the ids. tests/plain_cards.mjs fails when a CLI gains
+// a failure code with no card, and when a card drifts back into the vocabulary it exists
+// to translate (it reuses the accessibility scorer's jargon list, ADR 0291).
+
+'use strict';
+
+const { isTerminal } = require('./surface');
+
+// The line a skill looks for. Agent-surface marker, same family as [otb-confirm].
+const PLAIN_MARKER = '[otb-plain]';
+
+const RULE = true;   // deliberate: never look for a way round it
+const FAULT = false; // something is actually off; diagnosing it is fine
+
+const card = (happened, next, person, byDesign) => Object.freeze({ happened, next, person, by_design: byDesign });
+
+const ONE_TASK_PER_SESSION = card(
+  'This chat session is already working on another task. Each session handles one task at a time, so finished work never gets mixed together.',
+  'I will finish or hand back the task we already have — or tell you how to open a second session for this one.',
+  null, RULE);
+
+const CARDS = Object.freeze({
+  // ── starting a task ─────────────────────────────────────────────────────────
+  stage_required: card(
+    'There is a getting-started step to finish before this task can be started.',
+    'I will show you the step the server named and help you complete it.',
+    null, RULE),
+  session_already_has_active_claim: ONE_TASK_PER_SESSION,
+  session_claim_check_failed: ONE_TASK_PER_SESSION,
+  session_already_has_bound_claim: ONE_TASK_PER_SESSION,
+  newcomer_must_ship_first: card(
+    'New builders finish their first task before starting a second one.',
+    'I will help you finish the task you already have.',
+    null, RULE),
+  REBASE_REQUIRED: card(
+    'An earlier task of yours was approved but has not made it into the project yet, so starting new tasks is paused until it does.',
+    'I will run /strand-fix on the stuck task. That is the supported way to land it and it needs nothing technical from you.',
+    'Only if /strand-fix says it needs the owner.', RULE),
+  ALREADY_CLAIMED: card(
+    'Someone else started this task a moment before us.',
+    'I will pull a fresh list and suggest another task. Trying again would not help.',
+    null, RULE),
+  MODULE_CONFLICT: card(
+    'Another task in progress is changing the same part of the project.',
+    'I will suggest a task in a different area, or we wait for the other one to finish.',
+    null, RULE),
+  TOUCHES_CONFLICT: card(
+    'Another task in progress is changing some of the same files.',
+    'I will suggest a task that does not overlap, or we wait for the other one to finish.',
+    null, RULE),
+  TASK_NOT_READY: card(
+    'This task is not open for work yet — its status says so.',
+    'I will tell you its status and find a task that is ready.',
+    null, RULE),
+  TASK_NOT_FOUND: card(
+    'No task has that number.',
+    'I will list the tasks that exist so we can pick the right one.',
+    null, FAULT),
+  DEPS_NOT_SHIPPED: card(
+    'This task builds on other tasks that are not finished yet.',
+    'I will show which ones. If one of them was cancelled, the link between them needs a person to re-decide it.',
+    'Sometimes — whoever owns the goal, when a task it depends on was cancelled.', RULE),
+  OPEN_BLOCKER: card(
+    'This task is waiting on a decision or some input that was written down as a blocker.',
+    'I will show you the blocker. /blocker-solve can drive it to done.',
+    'Usually the owner, for the decision the blocker names.', RULE),
+  GOAL_MEMBERSHIP_REQUIRED: card(
+    'This task belongs to a goal you have not joined.',
+    'I will offer to join it for you — or apply, if it is private. I will not do either without your yes.',
+    'For a private goal, its owner approves the request.', RULE),
+  archon_approval_required: card(
+    'This goal covers a protected part of the project, so joining it needs an Archon to say yes.',
+    'I will file the request for you and we pick other work while it waits.',
+    'An Archon approves the request.', RULE),
+  goal_private: card(
+    'This goal is private, so joining it is by request.',
+    'I will file the request if you want, and we pick other work while it waits.',
+    'The goal owner approves the request.', RULE),
+  request_pending: card(
+    'Your request to join this goal is already waiting for an answer.',
+    'Nothing more to send. I will suggest other work in the meantime.',
+    'The goal owner, who has the request.', RULE),
+  BUILDER_INACTIVE: card(
+    'Your builder account is switched off, so it cannot start tasks.',
+    'I cannot change that from here. Ask an Archon to switch the account back on.',
+    'An Archon.', RULE),
+  INSUFFICIENT_RANK: card(
+    'This task needs a higher rank than yours.',
+    'I will find tasks open to your rank. I will not look for a way round the rank rule.',
+    'An Archon grants ranks.', RULE),
+  rank_too_low_for_task: card(
+    'Your rank cannot start this kind of task yet.',
+    'I will find tasks open to your rank. I will not look for a way round the rank rule.',
+    'An Archon grants ranks.', RULE),
+  BATCH_DUPLICATE_IDS: card(
+    'The same task was listed twice in one request.',
+    'I will send the list again with each task once.',
+    null, FAULT),
+  BATCH_EMPTY: card(
+    'The request to start several tasks had no tasks in it.',
+    'I will ask which tasks you meant.',
+    null, FAULT),
+  BATCH_FAILED: card(
+    'One of the tasks in the group could not be started, so none of them were.',
+    'I will show which one and why, then retry with the rest if you want.',
+    null, RULE),
+  main_checkout_claim: card(
+    'Tasks are worked on in their own separate copy of the project, and this session is standing in the main copy.',
+    'I will make the separate copy with one command and start the task from there.',
+    null, RULE),
+
+  board_unavailable: card(
+    'The list of tasks could not be loaded — the project answered with an error.',
+    'I will check that the project is reachable and that you are signed in, then try once more.',
+    null, FAULT),
+
+  // ── handing a task back ─────────────────────────────────────────────────────
+  CLAIM_SESSION_MISMATCH: card(
+    'This task was started from a different chat session, so this one is not allowed to hand it back by accident.',
+    'If you are sure it is yours to give up, I will repeat the command with the override it names.',
+    null, RULE),
+  no_active_claim: card(
+    'You are not working on that task right now, so there is nothing to hand back.',
+    'I will show what you do have in progress.',
+    null, FAULT),
+
+  // ── why an approved task has not landed ─────────────────────────────────────
+  'strand:pr_not_landed': card(
+    'Your work was approved and sent for the automatic checks, but it never made it into the project.',
+    'I will look up what stopped it and fix that, then land it.',
+    null, FAULT),
+  'strand:pr_closed_unmerged': card(
+    'The request to add your work was closed without being accepted, so it will never land by waiting.',
+    'I will send the work again. If a check failed, I fix that first.',
+    null, FAULT),
+  'strand:no_branch_no_tip': card(
+    'The task was approved, but its work never left the computer it was written on.',
+    'I will send the work from this computer. If it lives on another machine, it has to be sent from there.',
+    'Only if the work is on a machine I cannot reach.', FAULT),
+  'strand:land_not_proven': card(
+    'The project could not prove that your approved work actually arrived.',
+    'I will check what arrived and send the work again if it did not.',
+    null, FAULT),
+  'strand:unresolvable_conflict': card(
+    'Your work and newer work changed the same lines, and the automatic fix could not choose between them.',
+    'I will bring your work up to date by hand, keeping both changes, and send it again.',
+    null, FAULT),
+  'strand:branch_modifies_executed_code': card(
+    'Your work changes the tools that would be used to update it, so the automatic update was refused on purpose.',
+    'I will bring your work up to date on this computer instead, and send it again.',
+    null, RULE),
+
+  // ── why a request to add work has not been accepted ─────────────────────────
+  failing_check: card(
+    'An automatic test failed on your work, so it has not been added to the project.',
+    'I will run that test here, fix what it found, and send the work again. Sending the same work again would fail the same way.',
+    null, FAULT),
+  non_required_check_failing: card(
+    'An optional automatic test failed on your work.',
+    'I will look at what it found. It does not stop the work being added, but it is usually worth fixing.',
+    null, FAULT),
+  non_required_check_pending: card(
+    'An optional automatic test is still running on your work.',
+    'Nothing to do yet — I will check again shortly.',
+    null, RULE),
+  failing_check_unreadable: card(
+    'An automatic test failed on your work, but this project is not allowed to see which one.',
+    'I will run all the tests here to find it, fix it, and send the work again. Sending the same work again cannot help.',
+    'The owner can switch on the permission that shows which test failed.', FAULT),
+  blocked_required_review_or_pending_check: card(
+    'Your work is waiting on a test that has not finished, or on a review.',
+    'Nothing to do yet — I will check again shortly.',
+    null, RULE),
+  review_required: card(
+    'Your work needs a person to review it before it can be added.',
+    'I will tell you who can review it. I cannot approve my own work.',
+    'A reviewer with the right to approve.', RULE),
+  changes_requested: card(
+    'A reviewer asked for changes before your work can be added.',
+    'I will read what they asked for and make the changes.',
+    null, RULE),
+  merge_conflict: card(
+    'Your work and newer work changed the same lines, so they cannot be combined automatically.',
+    'I will bring your work up to date, keeping both changes, and send it again.',
+    null, FAULT),
+  branch_behind_base: card(
+    'The project moved on while your work was being checked, so your work needs refreshing first.',
+    'The server usually does this by itself. If it has not, I will refresh it and send it again.',
+    null, RULE),
+  draft_pr: card(
+    'Your work was sent as a draft, and drafts are not added to the project.',
+    'I will mark it ready.',
+    null, FAULT),
+  mergeability_computing: card(
+    'The project is still working out whether your work can be added.',
+    'Nothing to do yet — I will check again in a moment.',
+    null, RULE),
+  no_open_pr: card(
+    'There is no open request to add your work to the project.',
+    'I will check whether it was already added, and send it if it was not.',
+    null, FAULT),
+  unknown: card(
+    'The project did not say why your work has not been added.',
+    'I will check again, and look at it directly if the answer stays empty.',
+    null, FAULT),
+
+  // ── sending work from this computer ─────────────────────────────────────────
+  'ship:workflow_scope': card(
+    'Your work changes the project\'s automatic test setup, and the sign-in this computer uses is not allowed to send that kind of change.',
+    'Sending it again will fail the same way. I will show the one-time command that sends it another way.',
+    'You, once, to run that command or refresh the sign-in.', RULE),
+  'ship:protected_branch': card(
+    'Nobody is allowed to put work straight into the project\'s main copy — everything goes through the automatic checks first.',
+    'I will send your work through the checked route instead. I will not try to get round the protection.',
+    null, RULE),
+  'ship:auth': card(
+    'This computer\'s sign-in to the code host was refused.',
+    'I will show you how to sign in again. I will not ask anyone for a password or a key.',
+    'You, to sign in again.', RULE),
+  'ship:stale_branch': card(
+    'The project moved on since your work started, so it has to be refreshed before it can be sent.',
+    'I will refresh it and send it again.',
+    null, FAULT),
+  'ship:unknown': card(
+    'Sending your work failed for a reason I do not recognise.',
+    'I will read the message above, fix what it names, and try again once.',
+    null, FAULT),
+  'ship:main-checkout-on-branch': card(
+    'This task was worked on in the project\'s main copy instead of its own separate copy, so it cannot be added the usual way.',
+    'I will send it through the checked route instead. Next time I will start the task in its own copy.',
+    null, FAULT),
+  'ship:no-task-branch': card(
+    'I could not find the saved work for this task on this computer.',
+    'I will look for where it was saved. If it is on another machine, it has to be sent from there.',
+    'Only if the work is on a machine I cannot reach.', FAULT),
+  land_pending: card(
+    'Your work passed review and is waiting for the automatic tests. The server adds it to the project by itself when they pass.',
+    'Nothing to do. This is normal, not a failure.',
+    null, RULE),
+  reconcile_blocked: card(
+    'Your work was added to the project, but the server could not prove it was this task\'s, so the task is not marked finished yet.',
+    'The server re-checks every few minutes. If it stays stuck I will run the ship command again.',
+    null, FAULT),
+  smoke_failed: card(
+    'A quick health check of the project failed before your work was handed in.',
+    'I will find what the check tripped on and fix it before handing the work in.',
+    null, FAULT),
+  nothing_to_ship: card(
+    'There is no saved work for this task, so there is nothing to hand in.',
+    'I will check whether the work was saved. If the task really needed no changes, I will say so explicitly.',
+    null, RULE),
+  uncommitted_work: card(
+    'Some of your work has not been saved into the project\'s history yet, so handing it in now would leave it behind.',
+    'I will save it, then hand it in.',
+    null, RULE),
+
+  // ── the review of your work ─────────────────────────────────────────────────
+  grade_unavailable: card(
+    'The automatic reviewers could not run. Your work was not judged — this is an outage, not a rejection.',
+    'I will ask for the review again later. There is nothing in your work to fix.',
+    'Only if the outage lasts — an Archon can accept the work by hand.', FAULT),
+  grade_lens_unavailable: card(
+    'One of the automatic reviewers did not run; the others found nothing wrong. Your work was not rejected.',
+    'I will ask for the review again when the reviewers are healthy.',
+    'Only if it keeps happening — an Archon can accept the work by hand.', FAULT),
+  grade_refused_authorization: card(
+    'Your work touches a protected part of the project that your rank may not change, so the server would not accept it.',
+    'Asking again will be refused again. I will take the protected files out and hand in the rest, or we pass the task to someone with the rank.',
+    'A builder with a high enough rank, for the protected part.', RULE),
+  grade_failed: card(
+    'The automatic reviewers found problems in your work, so it is not accepted yet.',
+    'I will fix what they listed, save it, and ask for the review again. That costs nothing extra.',
+    null, FAULT),
+
+  // ── signing in ──────────────────────────────────────────────────────────────
+  no_session: card(
+    'This computer is not signed in to the project yet.',
+    'I will walk you through signing in — it happens in your browser.',
+    'You, to sign in.', RULE),
+  session_invalid: card(
+    'Your sign-in to the project has ended.',
+    'I will walk you through signing in again — Settings, then one copy and paste.',
+    'You, to sign in again.', RULE),
+  box_scope: card(
+    'This sign-in is limited on purpose: it can do the work, but not hand it in.',
+    'I will walk you through the full sign-in, then hand the work in.',
+    'You, to sign in again.', RULE),
+  instance_mismatch: card(
+    'This computer is signed in to a different project than the one this folder belongs to.',
+    'I will show which project each one is, and help you sign in to the right one.',
+    'You, to choose the project.', FAULT),
+  dev_box_unavailable: card(
+    'This project does not offer hosted computers to work from.',
+    'We can work from this computer instead.',
+    null, RULE),
+  no_push_credential: card(
+    'This computer is not allowed to send work to the code host itself. That is deliberate: the server sends it for you.',
+    'I will hand the work in with /builder-ship and read its progress from the server. I will never ask anyone for a password, key or sign-in to work round this.',
+    null, RULE),
+});
+
+// cardFor(code) → the card, or null. Reasons that carry a name or a file list after a
+// colon (`failing_check:unit`, `strand:unresolvable_conflict:a.md,b.md`) resolve on
+// their stem. `XENOS_RESTRICTED` is the legacy spelling of rank_too_low_for_task.
+function cardFor(code) {
+  if (typeof code !== 'string' || !code) return null;
+  if (code === 'XENOS_RESTRICTED') return CARDS.rank_too_low_for_task;
+  if (Object.prototype.hasOwnProperty.call(CARDS, code)) return CARDS[code];
+  const parts = code.split(':');
+  for (let n = parts.length - 1; n >= 1; n--) {
+    const stem = parts.slice(0, n).join(':');
+    if (Object.prototype.hasOwnProperty.call(CARDS, stem)) return CARDS[stem];
+  }
+  return null;
+}
+
+// plainCardLines(code) → the printable card, or [] for a code with none. Never throws:
+// a missing card must not be able to break the refusal it was meant to explain.
+// AGENT SURFACE ONLY: a card is written in the agent's voice ("I will…") for a
+// session to relay. A person running the `bongos` CLI reads the text above it directly,
+// and several cards name slash commands that do not exist there (tests/cli_surface.mjs).
+function plainCardLines(code, env = process.env) {
+  const c = isTerminal(env) ? null : cardFor(code);
+  if (!c) return [];
+  return [
+    `  ${PLAIN_MARKER} in plain words`,
+    `    What happened    ${c.happened}`,
+    `    What I will do   ${c.next}`,
+    `    Needs a person   ${c.person || 'No.'}`,
+    `    By design        ${c.by_design ? 'Yes — this is a rule, not a fault. Do not look for a way round it.' : 'No — something is actually off, so looking into it is right.'}`,
+  ];
+}
+
+module.exports = { CARDS, cardFor, plainCardLines, PLAIN_MARKER };

package/scripts/gds/provision.js

@@ -54,6 +54,7 @@ const { APP_USER, alreadyScaffolded, buildCorePinRefreshCommit, dbCreateCmd, dbN
 const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
 const { caddyBlock, caddySnippetPath, checkDnsTokenScope, classifyZoneScope, dnsReleaseEnv, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, identityCmd, identityVerdict, shouldFederate, zoneForDomain } = require('./provision-net.js');
 const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.js');
+const { installedCoreVersion, runnerBanner } = require('./runner-drift.js');
 const { teardownInstance } = require('./provision-teardown.js');
 const { disconnectInstance } = require('./provision-disconnect.js');
 const { coreUpgradeInstance, snapshotAllCoreVersions } = require('./provision-core-upgrade.js'); // the owner's deploy door, ADR 0293
@@ -1221,6 +1222,8 @@ async function drainOAuthManifests(deps) {
 // ---------------------------------------------------------------------------
 async function cmdRunIntents(deps) {
   const { db, provisioning, log, apply } = deps;
+  const instanceRoot = deps.instanceRoot || process.env.BONGOS_INSTANCE_ROOT || process.cwd();
+  log(runnerBanner({ runnerVersion: coreVersionSafe(), runnerRoot: REPO_ROOT, instanceVersion: installedCoreVersion(instanceRoot), instanceRoot }));
   if (!apply) {
     const { rows } = await db.query(
       `SELECT pi.*, i.slug FROM provisioning_intents pi
@@ -1254,7 +1257,7 @@ async function cmdRunIntents(deps) {
       else if (intent.action === 'restart') result = await restartInstance(inst, deps);
       else if (intent.action === 'disconnect') result = await disconnectInstance(inst, deps);
       else if (intent.action === 'core-upgrade') result = await coreUpgradeInstance(inst, deps, intent); // also reads the INTENT: the version the owner previewed (ADR 0293 D4)
-      else result = { ok: false, error: `unknown intent action '${intent.action}' — refusing to guess` };
+      else result = { ok: false, error: `unknown_action '${intent.action}' — runner core ${coreVersionSafe() || '?'} does not know it (runner too old?); refusing to guess` };
       if (result && result.ok === false) {
         if (intent.attempts >= MAX_INTENT_ATTEMPTS) {
           await provisioning.resolveIntent(db, intent.id, 'error', result.error || 'op failed');

package/scripts/gds/push-path-brief.js

@@ -33,6 +33,7 @@
 // Detection override (tests / forcing): OTB_PUSH_VIA_SERVER=1 (server) / =0 (local).
 
 const { hasFlag } = require('./cli-lib');
+const { plainCardLines } = require('./plain-cards');
 
 // ---- pure core ---------------------------------------------------------------
 
@@ -70,6 +71,7 @@ function report(via) {
   if (via === 'server') {
     console.log('  server-mediated (no authenticated gh — a dev box or credential-less checkout).');
     console.log(`  ${BRIEF}`);
+    for (const line of plainCardLines('no_push_credential')) console.log(line);
   } else if (via === 'local') {
     console.log('  local — this machine pushes with its own git + gh credentials.');
   } else {

package/scripts/gds/release.js

@@ -10,6 +10,7 @@ const { execFileSync } = require('node:child_process');
 const path = require('node:path');
 const { cliClient, requireSession, arg } = require('./cli-lib');
 const { parkedMainCheckoutWarning } = require('./worktree-claim-guard');
+const { plainCardLines } = require('./plain-cards');
 
 // gitAt(args, cwd) — run git with an ARGV ARRAY and no shell.
 //
@@ -73,6 +74,7 @@ function mainCheckoutRoot() {
       console.error(`Your active claims:`);
       for (const c of claims) console.error(`  #${c.task_id}: ${c.title}`);
     }
+    for (const line of plainCardLines('no_active_claim')) console.error(line);
     process.exit(1);
   }
 
@@ -97,6 +99,7 @@ function mainCheckoutRoot() {
       console.error(`This claim was created in a different session${wt ? ` (worktree: ${wt})` : ''}.`);
       console.error('Only the original session can release it.');
       console.error('If that session is gone, re-run with --force to override.');
+      for (const line of plainCardLines('CLAIM_SESSION_MISMATCH')) console.error(line);
     } else {
       console.error(`release failed (${r.status}):`, r.data);
     }