@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/paste-token.js

@@ -1,212 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/paste-token.js — V3.R91 / #401.
-//
-// Accept a CLI bearer minted by the builders' hall (POST /api/bongos/auth/cli-token/issue)
-// and write it into ~/.config/otb/bongos-session.json. Preserves any existing
-// fields (notably gemini_api_key registered via /builder-setup) so a token
-// paste never silently un-registers a builder's Gemini key.
-//
-// Usage:
-//   bongos paste-token <token>          # what the hall hands you (task 1003961)
-//   node scripts/gds/paste-token.js <token>   # equivalent, inside a core checkout
-//
-// The portal returns the exact invocation as the "paste_command" field, so a
-// builder can copy + paste a single line.
-//
-// Safety contract:
-//   1. The token is verified against /api/bongos/me BEFORE the session file is
-//      touched. A bad paste exits non-zero with a clear message and leaves
-//      the existing session intact.
-//   2. The file is written with mode 0600, same as setup.js.
-//   3. Any pre-existing fields in the session file are merged through
-//      (gemini_api_key, future per-builder prefs, etc.) so this script never
-//      regresses state captured by other flows.
-
-const fs = require('node:fs');
-const path = require('node:path');
-const ic = require('../../src/instance-config');
-// Destructured for the same reason as cli-lib: a namespace-only `ic.X` read is
-// invisible to knip, which then calls the export dead code.
-const { SESSION_FILENAMES, readSessionConfigSync } = require('../../src/instance-config');
-// SESSIONS ARE PER INSTANCE (ADR 0269), and saveSession is what makes that true — see
-// step 4. Requiring cli-lib here was weighed rather than assumed: it costs ~13ms and
-// prints nothing at load (undici and the surface machinery are all lazy), and login.js
-// — the sibling pre-session flow, shipped in the same standalone on-ramp bundle as this
-// script — already requires it. So this adds no module to the package and no visible
-// cost to a paste. (task 1004003)
-const { saveSession } = require('./cli-lib');
-
-// WRITE the session to the configured instance dir (OTB → ~/.config/otb,
-// unchanged; a fresh instance → its neutral dir). R61 / task 1200.
-const SESSION_PATH = ic.configPath(SESSION_FILENAMES[0]);
-
-// `--api-base <url>` / `--api-base=<url>`, plus the positional token. Hand-rolled
-// because this script has no arg parser and one flag does not earn a dependency.
-function parseArgs(argv) {
-  const out = { token: null, apiBase: null };
-  for (let i = 0; i < argv.length; i += 1) {
-    const a = String(argv[i]);
-    if (a === '--api-base') { out.apiBase = argv[i + 1] === undefined ? '' : String(argv[i + 1]); i += 1; continue; }
-    if (a.startsWith('--api-base=')) { out.apiBase = a.slice('--api-base='.length); continue; }
-    if (out.token === null && !a.startsWith('-')) out.token = a;
-  }
-  return out;
-}
-
-// WHICH INSTANCE IS THIS TOKEN FOR? (task 1003722)
-//
-// The old order was env → the EXISTING session's api_base → branding default, on the
-// reasoning that a re-auth already knows which instance the builder is on. That holds
-// right up until the builder uses a SECOND instance: the stale api_base then wins over
-// the instance that actually minted the token, so the paste is verified against — and
-// written as — the wrong host. The reported symptom was a token from this instance
-// landing as a token for an unrelated one, after which every /builder-* command
-// authenticated somewhere unintended.
-//
-// A token is minted BY an instance, so the issuer is a property of the token, not of
-// the machine. The hall now stamps it into the paste command, and an explicit flag
-// outranks every inferred source: it is per-invocation, it came from the minting
-// instance, and it is the only source that is right by construction.
-//
-// Below the flag the old order is untouched, so an older instance whose paste command
-// carries no flag behaves exactly as before — and so does the founder-host regression
-// this file already guards (task 1002427: hardcoding a host here rejected a valid
-// token with a 401).
-function resolveBaseForPaste({ flag, resolve = () => ic.resolveApiBase() } = {}) {
-  const f = typeof flag === 'string' ? flag.trim() : '';
-  if (!f) return { base: resolve(), source: 'resolved' };
-  if (!/^https?:\/\/[^\s/]+/i.test(f)) return { base: null, source: 'invalid' };
-  return { base: f.replace(/\/+$/, ''), source: 'flag' };
-}
-
-const ARGS = parseArgs(process.argv.slice(2));
-const RESOLVED = resolveBaseForPaste({ flag: ARGS.apiBase });
-const API_BASE = RESOLVED.base;
-
-function usage(extra) {
-  if (extra) console.error(extra);
-  console.error('');
-  console.error('Usage: npx bongos paste-token <token> [--api-base <url>]');
-  console.error('   (inside a core checkout: node scripts/gds/paste-token.js <token>)');
-  console.error('');
-  // Fall back to the inferred base for this hint when --api-base was the thing that
-  // was malformed — otherwise the error message that explains the bad flag would
-  // itself print "null/builders/settings".
-  const hintBase = API_BASE || ic.resolveApiBase();
-  console.error('Get a token on your Settings page: ' + hintBase + '/builders/settings');
-  console.error('— under "CLI Access" click "Re-issue CLI token" (you must be signed in).');
-  console.error('The page prints the exact paste-command — just run that line.');
-}
-
-async function main() {
-  if (RESOLVED.source === 'invalid') {
-    usage(`--api-base must be an http(s) URL, got: ${ARGS.apiBase}`);
-    process.exit(2);
-  }
-  const token = ARGS.token;
-  if (!token) {
-    usage('No token argument provided.');
-    process.exit(2);
-  }
-  // Tokens are hex-encoded crypto.randomBytes(32) → 64 lowercase hex chars.
-  // Accept a slightly broader set to tolerate future token formats; reject
-  // anything with whitespace or shell metacharacters.
-  if (!/^[A-Za-z0-9_-]{16,256}$/.test(token)) {
-    usage('Token format looks wrong (expected a long alphanumeric string).');
-    process.exit(2);
-  }
-
-  // 1. Verify the token by calling /me. Refuse to touch the session file if
-  //    the token is bad — that protects the existing valid session that the
-  //    paste was meant to REPLACE, not destroy.
-  let me;
-  try {
-    const res = await fetch(`${API_BASE}/api/bongos/me`, {
-      headers: { Authorization: `Bearer ${token}` },
-    });
-    if (res.status === 401) {
-      console.error('Token rejected by ' + API_BASE + ' (HTTP 401).');
-      console.error('Double-check you copied the full paste-command from the portal.');
-      console.error('Existing session at ' + SESSION_PATH + ' was NOT modified.');
-      process.exit(3);
-    }
-    if (!res.ok) {
-      console.error(`Verification call failed (HTTP ${res.status}).`);
-      console.error('Existing session was NOT modified.');
-      process.exit(4);
-    }
-    me = await res.json();
-  } catch (err) {
-    console.error('Could not reach ' + API_BASE + ': ' + err.message);
-    console.error('Existing session was NOT modified.');
-    process.exit(5);
-  }
-
-  // 2. Read existing session (if any) so we can preserve fields like
-  //    gemini_api_key. Failure to read = file missing or unparseable; either
-  //    way, treat as a fresh write.
-  let existing = {};
-  try {
-    // Read across config dirs (configured + legacy otb) AND across every accepted
-    // filename, so a session written the old way still has its fields preserved on
-    // the next paste. This is the re-auth path: a miss here does not fail loudly,
-    // it silently drops the builder's gemini_api_key (task 1003704).
-    const raw = readSessionConfigSync();
-    if (raw) existing = JSON.parse(raw);
-  } catch (_) {
-    /* fresh session; nothing to merge */
-  }
-
-  // 3. Compose the new session row. Token + builder + api_base are
-  //    authoritative-from-server; everything else (gemini_api_key et al.)
-  //    rides through unchanged.
-  const next = {
-    ...existing,
-    token,
-    builder: me.builder,
-    api_base: API_BASE,
-  };
-
-  // 4. Ensure dir exists with safe perms, then save 0600 THROUGH saveSession.
-  //
-  // WHY NOT A BARE writeFileSync HERE (task 1004003). This used to write SESSION_PATH
-  // directly, which is the ACTIVE POINTER and nothing else. Under ADR 0269 a machine has
-  // several instances, and saveSession is the only writer that knows it: it archives the
-  // OUTGOING session into the host-keyed store before overwriting the pointer, and files
-  // the incoming one there too. Writing the pointer directly skipped both, so pasting a
-  // token for instance B while signed in to instance A destroyed A's session with no
-  // archive — and `bongos login <A>`, which exists to switch back without a device flow,
-  // reads that store and found nothing, so the switch back cost a full re-auth. The state
-  // was unrecoverable, because the pointer is the file that was overwritten.
-  try {
-    fs.mkdirSync(path.dirname(SESSION_PATH), { recursive: true, mode: 0o700 });
-    await saveSession(next);
-    // chmod again in case the file already existed with looser perms (writeFile's
-    // mode arg is ignored when the file already exists on some platforms).
-    fs.chmodSync(SESSION_PATH, 0o600);
-  } catch (err) {
-    console.error('Failed to write ' + SESSION_PATH + ': ' + err.message);
-    process.exit(6);
-  }
-
-  const builder = me.builder || {};
-  console.log(`Authenticated as ${builder.github_login || '?'} (#${builder.id || '?'})`);
-  if (builder.display_name) console.log(`Display name: ${builder.display_name}`);
-  if (builder.rank) console.log(`Rank: ${builder.rank}`);
-  console.log(`Session saved to ${SESSION_PATH}`);
-  if (existing.gemini_api_key) {
-    console.log('Gemini API key preserved.');
-  }
-}
-
-// Run only as a script. Exporting the two pure helpers lets the decision that caused
-// task 1003722 — WHICH instance a pasted token belongs to — be tested directly, rather
-// than inferred from a text scan of this file.
-if (require.main === module) {
-  main().catch((err) => {
-    console.error('paste-token failed:', err && err.message ? err.message : err);
-    process.exit(1);
-  });
-}
-
-module.exports = { parseArgs, resolveBaseForPaste };
+// scripts/gds/paste-token.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/paste-token.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'paste-token.js');

package/scripts/gds/plain-cards.js

@@ -1,351 +1,6 @@
-// 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 agent 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).
-
+// scripts/gds/plain-cards.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/plain-cards.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 '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),
-  // task 1004289: the tests never ran at all (the account cannot run them right now).
-  ci_not_started: card(
-    'The automatic tests never ran on your work: the code host did not start them, because the account has run out of test time or has a payment problem. Nothing was tested, so nothing needs fixing.',
-    'I will not change the work. Once the owner restores the test time, I will start the tests again on the same work and it will be added on its own.',
-    'The project owner, to restore the account\'s test time on the code host.', 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_unbacked_score: card(
-    'One of the automatic reviewers gave your work a low mark without saying what is wrong, so there is nothing listed to fix. It is not accepted yet, but it was not turned down for a named problem either.',
-    'I will ask for the review again. If the low mark comes back still without a reason, I will ask for your work to be accepted by hand, with an explanation.',
-    'Only if it keeps happening — an Archon decides whether to accept it by hand.', FAULT),
-  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),
-  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),
-  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).
-// The labels below are READ BACK by .claude/hooks/stuck-detector.js as its failure
-// signature (task 1003990); tests/stuck_detector.mjs reds if they drift.
-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 };
+require('../bongos/forwarder.js').forward(module, 'plain-cards.js');