@bongos/core 1.19.834 → 1.19.836

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-repo.js

@@ -512,6 +512,8 @@ async function scaffoldStandaloneRepo(inst, deps) {
     throw new Error(`standalone instance ${inst.slug}: target_ref "${inst.target_ref || '(unset)'}" is not an owner/repo — set it (e.g. <owner>/${inst.slug}) so the scaffold knows which repo to clone + push.`);
   }
   if (alreadyScaffolded(root, mode)) {
+    const resumed = deps.apply ? await resumeUnpushedScaffold(inst, deps, { root, repo, mode }) : null;
+    if (resumed) return resumed;
     log(`  [scaffold] ${root} already scaffolded (mode=${mode}) — skipping`);
     return { already: true };
   }
@@ -541,13 +543,8 @@ async function scaffoldStandaloneRepo(inst, deps) {
   // command or makeExec's env (makeExec surfaces both), and is removed in a `finally` so a
   // failed git op can't leave it on disk. No token (org-owned repo, or secret-box off) →
   // fall back to the SSH `origin` remote.
-  const ownerToken = await resolveOwnerGithubToken(inst, deps, { tag: '[scaffold]' });
-  // The credential-store file + the credential-LESS URL git resolves against it. The URL
-  // carries only the `x-access-token` username (no secret), so it is safe in a logged argv.
-  const credFile = ownerToken ? path.join(os.tmpdir(), `bongos-gitcred-${inst.slug}-${process.pid}`) : null;
-  const httpsUrl = `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`;
-  const credOpt = credFile ? `-c credential.helper='store --file=${credFile}' ` : '';
-  if (credFile) writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
+  const cred = await scaffoldCredential(inst, repo, deps, writeFile);
+  const { credFile, httpsUrl, credOpt } = cred;
 
   try {
     // 1. Materialize the working tree.
@@ -680,13 +677,7 @@ async function scaffoldStandaloneRepo(inst, deps) {
     // destroying their work. Adopt's commit is a descendant of the tip it cloned, so an
     // ordinary push fast-forwards; if the remote moved underneath us the rejection is the
     // correct outcome and a re-run picks up the new tip.
-    if (credFile) {
-      exec(`git -C ${root} ${credOpt}push ${httpsUrl} HEAD:main`);
-      log(`  [scaffold] ${mode === 'adopt' ? 'pushed the adopt layer' : 'pushed'} to ${repo.owner}/${repo.name}@main via the owner's GitHub token (task 1002317)`);
-    } else {
-      exec(`git -C ${root} push -u origin main`);
-      log(`  [scaffold] pushed ${mode === 'adopt' ? 'the adopt layer' : 'initial scaffold'} to ${repo.owner}/${repo.name}@main (SSH origin)`);
-    }
+    pushScaffold({ exec, log, root, repo, mode, cred });
     return { ok: true, scaffolded: true, mode };
   } finally {
     // Always remove the credential file — a failed clone/push must not leave it on disk.
@@ -694,6 +685,54 @@ async function scaffoldStandaloneRepo(inst, deps) {
   }
 }
 
+// The owner-token credential the scaffold's git network ops ride (rationale at the call site in
+// scaffoldStandaloneRepo). The URL carries only the `x-access-token` username, so it is safe in a
+// logged argv. credFile null → no token → SSH origin fallback; the caller `rm -f`s it in a finally.
+async function scaffoldCredential(inst, repo, deps, writeFile) {
+  const ownerToken = await resolveOwnerGithubToken(inst, deps, { tag: '[scaffold]' });
+  const credFile = ownerToken ? path.join(os.tmpdir(), `bongos-gitcred-${inst.slug}-${process.pid}`) : null;
+  const httpsUrl = `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`;
+  const credOpt = credFile ? `-c credential.helper='store --file=${credFile}' ` : '';
+  if (credFile) writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
+  return { credFile, httpsUrl, credOpt };
+}
+
+function pushScaffold({ exec, log, root, repo, mode, cred }) {
+  if (cred.credFile) {
+    exec(`git -C ${root} ${cred.credOpt}push ${cred.httpsUrl} HEAD:main`);
+    log(`  [scaffold] ${mode === 'adopt' ? 'pushed the adopt layer' : 'pushed'} to ${repo.owner}/${repo.name}@main via the owner's GitHub token (task 1002317)`);
+  } else {
+    exec(`git -C ${root} push -u origin main`);
+    log(`  [scaffold] pushed ${mode === 'adopt' ? 'the adopt layer' : 'initial scaffold'} to ${repo.owner}/${repo.name}@main (SSH origin)`);
+  }
+}
+
+// alreadyScaffolded is a LOCAL marker, and a scaffold whose push failed leaves it behind: the
+// re-run skipped the never-done push, then wedged at step 2's `git pull --ff-only` against the
+// still-empty remote (task 1002718, F12). Only a remote that ANSWERS with no main re-pushes — an
+// unreachable one keeps the old skip, as it can't tell "never pushed" from "offline". Returns
+// null when there is nothing to resume.
+async function resumeUnpushedScaffold(inst, deps, { root, repo, mode }) {
+  const exec = deps.controlExec || deps.exec;
+  const writeFile = deps.controlWriteFile || deps.writeFile;
+  let cred = null;
+  let probe = { softFailed: true };
+  try {
+    // This runs on every re-provision of a LIVE instance, so a probe that cannot even start
+    // (token lookup, credential write) must keep the skip — never fail a healthy instance.
+    try {
+      cred = await scaffoldCredential(inst, repo, deps, writeFile);
+      probe = exec(`git -C ${root} ${cred.credOpt}ls-remote --heads ${cred.credFile ? cred.httpsUrl : 'origin'} main`, { allowFail: true });
+    } catch { deps.log(`  [scaffold] could not probe ${repo.owner}/${repo.name} for main — keeping the skip`); }
+    if (probe.softFailed || String(probe.stdout || '').trim()) return null;
+    deps.log(`  [scaffold] ${root} is scaffolded but ${repo.owner}/${repo.name} has no main — re-pushing the scaffold that never landed`);
+    pushScaffold({ exec, log: deps.log, root, repo, mode, cred });
+    return { ok: true, resumed: true, mode };
+  } finally {
+    if (cred && cred.credFile) exec(`rm -f ${cred.credFile}`, { allowFail: true });
+  }
+}
+
 // ── private-repo deploy key (ADR 0176, task 1002735; walk finding N4) ────────────
 
 function deployKeyTitle(inst) { return `cloudbongos-deploy-${inst.slug}`; }

package/scripts/gds/provision-teardown.js

@@ -43,7 +43,7 @@ async function teardownInstance(inst, deps) {
     // Left for an operator (data is precious), naming ONLY what this row created —
     // teardown now takes 'requested'/'error'. `port` + `domain` stay held: ADR 0181.
     if (inst.db_name) log(`  (left for the operator: dropdb ${dbName(inst)}, prune ${CONFIG.backupDir}/${dbName(inst)}-*.sql.gz)`);
-  } else if (apply && deps.doApi && inst.droplet_id) {
+  } else if (apply && inst.droplet_id && deps.doApi) {
     await deps.doApi.deleteDroplet(inst.droplet_id);
   }
   parkAddress(inst, { controlExec, log, apply });

package/scripts/gds/provision.js

@@ -1393,12 +1393,14 @@ async function main() {
   if (CONFIG.remoteHost && !CONFIG.remoteCwd) { console.error('PROVISION_REMOTE_HOST is set but PROVISION_REMOTE_CHECKOUT is not — name the co-hosting box\'s checkout dir (the old hardcoded default was removed, task 1002756).'); process.exit(2); }
   const exec = makeExec({ apply, remoteHost: CONFIG.remoteHost, remoteCwd: CONFIG.remoteCwd, sshOpts: CONFIG.sshOpts });
   const controlExec = makeExec({ apply });
+  let doApiClient = null;
   const deps = {
     db: pool, provisioning, apply, privileged: CONFIG.privileged, log: console.log,
     exec, controlExec,
     writeFile: makeWriteFile({ apply, privileged: CONFIG.privileged, exec, remoteHost: CONFIG.remoteHost }),
     controlWriteFile: makeWriteFile({ apply, privileged: CONFIG.privileged, exec: controlExec }),
-    doApi: DoApi ? new DoApi({ dryRun: !apply, token: CONFIG.doToken, log: (m) => console.log('    ' + m) }) : null,
+    // Built on first READ (task 1002718 F6): an --apply tick whose intents never call DO needs no DO_API_TOKEN.
+    get doApi() { return DoApi ? (doApiClient = doApiClient || new DoApi({ dryRun: !apply, token: CONFIG.doToken, log: (m) => console.log('    ' + m) })) : null; },
     // Cross-site identity (ADR 0141 §4). Null on a non-hub control plane → federation
     // dormant; shouldFederate() then skips and the instance owns its auth (as today).
     platformIdentity, hubKeys,

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);
     }

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,