@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/paste-token.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// scripts/bongos/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/bongos/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/bongos/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 };

package/scripts/bongos/plain-cards.js

@@ -0,0 +1,351 @@
+// scripts/bongos/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).
+
+'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 };

package/scripts/bongos/portability-smoke-art.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# C8 portability smoke — ART PIPELINE (#280 / V3.R61).
+#
+# Certifies the C8 promise that the art pipeline runs end-to-end on a fresh
+# checkout with the builder's OWN Gemini key — no Archon-only handoff.
+#
+# Two modes:
+#   * default (cheap, free, nightly-safe): the pinned deps import and the
+#     Gemini key resolves via gen_api's own resolution chain. This is exactly
+#     what would break on a bad fresh checkout (missing deps, no key), so it
+#     certifies "fresh clone + own key → pipeline is runnable" for $0.
+#   * full (ART_SMOKE_FULL=1): additionally runs the orchestrator on a single
+#     tile and asserts it produces output. Costs real Gemini spend (~$0.20-0.45)
+#     so it is OFF by default and must be opted into explicitly.
+#
+# In CI the job's own `actions/checkout` + `pip install -r requirements.txt`
+# IS the fresh clone; this script then proves the pipeline loads there.
+#
+# Usage:
+#   bash scripts/bongos/portability-smoke-art.sh            # cheap mode
+#   ART_SMOKE_FULL=1 bash scripts/bongos/portability-smoke-art.sh   # + paid 1-tile run
+
+set -uo pipefail
+cd "$(dirname "$0")/../.."   # repo root
+
+# Defense-in-depth: suppress gen_api's key-source announcement (which prints
+# the key's last 4 chars to stderr) regardless of how we were invoked, so a
+# dropped caller-side env var can never leak a key fragment into CI logs.
+export OTB_QUIET_KEY_RESOLUTION=1
+
+PASS=0; FAIL=0
+ok()  { echo "PASS  $1"; PASS=$((PASS+1)); }
+bad() { echo "FAIL  $1"; FAIL=$((FAIL+1)); }
+
+echo "=== C8 portability smoke: ART PIPELINE ==="
+
+# --- 0. key present? (skip cleanly if not — same shape as the memory smoke) --
+if ! python3 - <<'PY' >/dev/null 2>&1
+import sys; sys.path.insert(0, "modules/art-pipeline/pipeline")
+import gen_api; gen_api._load_key()
+PY
+then
+  echo "SKIP: no Gemini key resolvable (set GOOGLE_AI_STUDIO_KEY or ~/.config/otb/env). Art portability not certified this run."
+  exit 0
+fi
+
+# --- 1. pinned deps import on this checkout ----------------------------------
+if python3 -c "import PIL, numpy, scipy, sklearn, certifi" 2>/dev/null; then
+  ok "art pipeline deps import (Pillow, numpy, scipy, scikit-learn, certifi)"
+else
+  bad "art pipeline deps failed to import — run: pip install -r modules/art-pipeline/pipeline/requirements.txt"
+fi
+
+# --- 2. Gemini key resolves via gen_api's own chain --------------------------
+SRC=$(python3 - <<'PY' 2>/dev/null
+import sys; sys.path.insert(0, "modules/art-pipeline/pipeline")
+import gen_api; gen_api._load_key(); print(gen_api._API_KEY_SOURCE or "?")
+PY
+)
+if [ -n "$SRC" ]; then ok "Gemini key resolves (source: $SRC)"; else bad "Gemini key did not resolve via gen_api"; fi
+
+# --- 3. orchestrator is invokable (import-level; no generation) --------------
+if python3 -c "import sys; sys.path.insert(0,'modules/art-pipeline/pipeline'); import orchestrator" 2>/dev/null; then
+  ok "orchestrator.py imports cleanly"
+else
+  bad "orchestrator.py failed to import"
+fi
+
+# --- 4. FULL (opt-in, paid): run one tile through the pipeline ---------------
+if [ "${ART_SMOKE_FULL:-0}" = "1" ]; then
+  echo "  ART_SMOKE_FULL=1 — running orchestrator on a single tile (paid)..."
+  BEFORE=$(python3 modules/art-pipeline/pipeline/cost_ledger.py status 2>/dev/null | tail -1 || echo "")
+  if python3 modules/art-pipeline/pipeline/orchestrator.py A 2>&1 | tail -20; then
+    ok "orchestrator completed a generation run (priority A)"
+  else
+    bad "orchestrator run failed"
+  fi
+  echo "  cost before: $BEFORE"
+  python3 modules/art-pipeline/pipeline/cost_ledger.py status 2>/dev/null | tail -1 | sed 's/^/  cost after:  /' || true
+else
+  echo "  (full paid 1-tile run skipped — set ART_SMOKE_FULL=1 to certify a real generation)"
+fi
+
+echo "=== art portability: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]