@bongos/core 1.19.580 → 1.19.581

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.580",
-  "core_contract": "1.19.580",
-  "source_commit": "23d256818bb7470aa5d203825abed34ab13f6fcf",
+  "core_version": "1.19.581",
+  "core_contract": "1.19.581",
+  "source_commit": "03f7d02a4e669a2fa53f34e6375ebb6b7a046a27",
   "source_ref": "HEAD",
-  "built_at": "2026-09-07T18:50:35.452Z",
+  "built_at": "2026-09-07T20:15:39.494Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 453,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2051,
+    "functional_verbatim": 2053,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2528,
-  "tree_sha256": "293d3e0eb2f7b0d375fde65d1b6e75816035857c06a98f69f91d0e213a21f8ad",
+  "file_count": 2530,
+  "tree_sha256": "5c954594f6fc90e5180384a00a4a9cb3258580a0f9df36d629dbf71731a1fd4e",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -367,7 +367,7 @@
     {
       "path": "bin/bongos.js",
       "mode": "0000644",
-      "sha256": "36208a41a60e3a21356ca9f81abdff9203837ff024b3d15c88a26bee9cce371c"
+      "sha256": "d585fc874c0a45f5d02d5753025d4761ca9b817ae9e5c556891b5c5c444cffde"
     },
     {
       "path": "clients/bongos-client/README.md",
@@ -2697,7 +2697,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "dd0684364a3ccd656f8201367e23775d578a84b385f49a901f7fc4205312b344"
+      "sha256": "8b9c303b7cb35b420ff13c0a265fe2e505769c6d1625977eb85c0d077ff1ddf2"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2707,7 +2707,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "2237a99993338a480835d8cf8c62bc0925585d46d01a9859b5ba3afa108af5d1"
+      "sha256": "fad24c9257355302696388602bba42f251696c20d4e2380f668339a823a84558"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7572,12 +7572,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "28db9a2f030a69e041ee0c0d277238e7f5f7be0ba8a9bd370ffc2fc644a3c1d1"
+      "sha256": "06ccc86510eed776b32a243487781c83fefcf48d33053f9f3a313e90b8364a49"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "cbec2151e643d5ff302e5d98166488c6298669395eafe9e037a2f39ea23db5c9"
+      "sha256": "f145cacd4b2198eb4c6f6cd07a1ac30ebe653b3aaf34c7768cf0ad8dc0561db4"
     },
     {
       "path": "public-docs/index.html",
@@ -7777,7 +7777,7 @@
     {
       "path": "scripts/gds/build-cli-package.js",
       "mode": "0000644",
-      "sha256": "4b2428615e3c81c14a3b3144eca35fcb2c4523c4debef0f7d4596e5934857a6b"
+      "sha256": "760dbc00a1d8ed5dfa2184e93f9106383bbb36c7fdd973ddfc67b7e03f3bc2f8"
     },
     {
       "path": "scripts/gds/bump-version.js",
@@ -7837,7 +7837,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "b08ad47b79417816a9f132e8149f78743eefb47b8824edf3380cdea23447e07f"
+      "sha256": "beb9d466f7623cae12788f23d0e30fbf3a520fec769e416ce3ad6458b23ceb2b"
     },
     {
       "path": "scripts/gds/client-baseurl-guard.js",
@@ -8402,7 +8402,7 @@
     {
       "path": "scripts/gds/recall.js",
       "mode": "0000644",
-      "sha256": "8bb682eebeec8738082a2988f59697da6982d7c727e82352c169abc72a623b78"
+      "sha256": "d0ad3b72fd0db0384f0d2212b50650e7e081beb62296ac3ea256047d6c3d8ec0"
     },
     {
       "path": "scripts/gds/redteam-patrol.js",
@@ -8812,7 +8812,7 @@
     {
       "path": "scripts/gds/start.js",
       "mode": "0000644",
-      "sha256": "81c60afdec1b7b05babe1eceaad38e0f27b932bef74e9dcb2cd3782c58524e30"
+      "sha256": "061a477c618ca76aba4f3abfb2d22ad89ceb0bee46bac65b139ad8ee2f30413a"
     },
     {
       "path": "scripts/gds/status.js",
@@ -8824,6 +8824,11 @@
       "mode": "0000644",
       "sha256": "072c493cc549e16c6045abf5bf74a8cfe0004b45844c6f4fe9e846d55d88bf34"
     },
+    {
+      "path": "scripts/gds/surface.js",
+      "mode": "0000644",
+      "sha256": "cc730dc2d59f5d6f06bad92e9c2b69cb7835142deefd31a8dfdd58b300c38e30"
+    },
     {
       "path": "scripts/gds/task.js",
       "mode": "0000644",
@@ -9282,7 +9287,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a3e2c3a0b4099d54d8cd5c309186feb8a0c7073074095c4d10861f71e9f36ce4"
+      "sha256": "b928f49545fb1adb6ce26a620a73083be9d71257e6171a533d672190e86495a6"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9884,6 +9889,11 @@
       "mode": "0000644",
       "sha256": "a57516ed9e904cf1c86fe99688415f834dcae1a19f01b22e986f199fa5473258"
     },
+    {
+      "path": "tests/cli_surface.mjs",
+      "mode": "0000644",
+      "sha256": "589ecc771ab18829049eabc6183939843072160e8476828e246eadd8ff6f0709"
+    },
     {
       "path": "tests/cli_token_reissue.mjs",
       "mode": "0000644",

package/bin/bongos.js

@@ -204,7 +204,16 @@ function main(argv) {
 
   if (COMPILED) return runBundled(verb, def, forwarded);
 
-  const res = spawnSync(process.execPath, [scriptPath, ...forwarded], { stdio: 'inherit' });
+  // A person typed `bongos <verb>`, so this output is for a person: no `[otb-card]` directives
+  // addressed to a model, no `/builder-*` slash commands that exist only inside Claude Code
+  // (task 1003680, scripts/gds/surface.js). The skills and the card-delivery hook run
+  // `node scripts/gds/<verb>.js` DIRECTLY and never pass through here, so the agent card shape
+  // is untouched. `bongos exec` above is deliberately left alone — it is the agent's escape
+  // hatch into a core script.
+  const res = spawnSync(process.execPath, [scriptPath, ...forwarded], {
+    stdio: 'inherit',
+    env: { ...process.env, BONGOS_SURFACE: 'terminal' },
+  });
   if (res.error) {
     process.stderr.write(`bongos: failed to run "${verb}": ${res.error.message}\n`);
     return 1;

package/docs/file-map.md

@@ -168,6 +168,7 @@
 │       ├── ship-visual.js       ← the OPTIONAL `--visual <image> [--visual-alt "…"]` leg of a ship (task 1003109): screens the file BEFORE the claim resolves (bad input costs no claim), uploads it AFTER (a failed picture never fails a ship)
 │       ├── package-core.js      ← package the core as a versioned, installable artifact + pin manifest (`bongos package-core`; R84, ADR 0100 §1, [#1688](https://example.com/builders#/task/1688)): isPublishable() selection + mirror redaction + fail-closed no-leak gate → dist/bongos-core-<version>.{tgz,manifest.json}; version = src/module-api CORE_VERSION. Recipe: docs/recipes/packaging-the-core.md
 │       ├── build-cli-package.js ← generate the PUBLIC, client-only `@cloudbongos/cli` npm package from this repo (task 1003679, ADR 0258): declared FILES manifest (no server/routes/auth/pool/provisioning) + generated dispatcher, README and package.json whose `files` array is DERIVED from the manifest; refuses to emit on a relative `import()` the manifest omits, and on a redaction hit (non-loopback IPv4, token/key shapes, instance domains + owner login read from config/branding.json). Sibling of package-core.js, opposite audience: that one packages the private core for an instance, this one packages the client surface for the public. Proven by tests/cli_package.mjs, which installs the packed tarball into an empty dir and runs every verb. `npm publish` is the OWNER's step, never a builder's → dist/cloudbongos-cli/
+│       ├── surface.js         ← who the CLI output is FOR: agent (default) or terminal (task 1003680). The `bongos` dispatcher sets BONGOS_SURFACE=terminal when a person types a verb; the skills and the card hook run `node scripts/gds/<verb>.js` directly and keep the agent card byte-identical. Never inferred from isTTY — a session's stdout is not a TTY either, so sniffing would invert it. Helpers: action() (/builder-ship N vs bongos ship N), taskRef(), strong()/em()/code(), table() (markdown vs aligned columns). Guarded by tests/cli_surface.mjs
 │       ├── sandbox-stage.js     ← stage the working tree on the live game preview (box OR local) for browser review before ship; resolvePreviewContext picks the context (`/builder-stage`; #927, ADR 0046; local: task 1056)
 │       ├── local-preview.js     ← builder CLI for the LOCAL sandbox: start/stop/status/restart/logs/url of the game-only preview at http://localhost:3100 (`npm run preview`; task 1056)
 │       ├── local-preview-lib.js ← core of the local sandbox launcher (detached `node src/preview-server.js`, pid/health/port mgmt); shared by local-preview.js + sandbox-stage.js (task 1056)

package/docs/module-api-changelog.md

@@ -1609,5 +1609,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.578 with no explicit bump. run 34149317186. (task 1002620)
   1.19.580 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.579 with no explicit bump. run 34153217035. (task 1002620)
+  1.19.581 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.580 with no explicit bump. run 34158683008. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.580",
+  "version": "1.19.581",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.580",
+      "version": "1.19.581",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.580",
+  "version": "1.19.581",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/build-cli-package.js

@@ -35,7 +35,7 @@ const REPO_ROOT = path.join(__dirname, '..', '..');
 
 // The package's OWN version — deliberately independent of the core's. The core moves many times
 // a day (CI auto-patch, ADR 0161); the CLI's public contract should not.
-const PACKAGE_VERSION = '0.1.0';
+const PACKAGE_VERSION = '0.1.1';
 const PACKAGE_NAME = '@cloudbongos/cli';
 
 // ── What the package carries ────────────────────────────────────────────────────────────────
@@ -54,6 +54,7 @@ const FILES = [
   'scripts/gds/onboarding-config.js', // lazy dep of setup.js
   'scripts/gds/install-git-hooks.js', // lazy dep of setup.js
   'scripts/gds/preflight.js',
+  'scripts/gds/surface.js',   // who the output is for: agent vs terminal (task 1003680)
 
   // Read the board and move your own work along.
   'scripts/gds/start.js',
@@ -327,7 +328,12 @@ function main(argv) {
 
   const target = path.join(SCRIPTS_DIR, def.script);
   const spawnArgs = [target, ...(def.prefixArgs || []), ...args.slice(1)];
-  const res = spawnSync(process.execPath, spawnArgs, { stdio: 'inherit' });
+  // Everyone reaching this package is a person at a terminal, so say so: scripts/gds/surface.js
+  // switches off the [otb-card] model directives and the /builder-* slash commands (task 1003680).
+  const res = spawnSync(process.execPath, spawnArgs, {
+    stdio: 'inherit',
+    env: { ...process.env, BONGOS_SURFACE: 'terminal' },
+  });
   if (res.error) {
     process.stderr.write('bongos: could not run ' + def.script + ': ' + res.error.message + '\\n');
     return 1;

package/scripts/gds/cli-lib.js

@@ -749,6 +749,14 @@ function tableTask(t) {
 // Maps stage -> a concrete CLI/web action the builder can take RIGHT NOW.
 // Stage-internal hints (STAGE_HINTS in src/bongos/onboarding-state.js) are
 // the canonical description; the per-CLI commands are the action verbs.
+// The nudges name an action the reader can run. Which spelling is right depends on who is
+// reading — see scripts/gds/surface.js (task 1003680). Fail-open: a missing surface module must
+// never break a nudge.
+function surfaceAction(verb, arg) {
+  try { return require('./surface').action(verb, arg); }
+  catch (_) { return `/builder-${verb}${arg == null ? '' : ` ${arg}`}`; }
+}
+
 function nudgeActionForStage(stage) {
   switch (stage) {
     case 'auth_complete':
@@ -756,11 +764,11 @@ function nudgeActionForStage(stage) {
     case 'pick_disciplines':
       return `Choose the work that calls you — open the hall at ${hallBase()} and pick engineer, artist, ideator, or any mix.`;
     case 'first_start':
-      return 'Run /builder-start to survey what you can claim.';
+      return `Run ${surfaceAction('start')} to survey what you can claim.`;
     case 'first_claim':
-      return 'Pick a task from /builder-start and claim it with /builder-claim N.';
+      return `Pick a task from ${surfaceAction('start')} and claim it with ${surfaceAction('claim', 'N')}.`;
     case 'ship_three':
-      return 'Carry three tasks through with /builder-ship — the third makes you a Thetes.';
+      return `Carry three tasks through with ${surfaceAction('ship')} — the third makes you a Thetes.`;
     default:
       return null;
   }

package/scripts/gds/recall.js

@@ -45,7 +45,7 @@ function truncate(s, n) {
 
 function reportError(r) {
   if (r.status === 401) {
-    console.error('Not signed in. Run /builder-setup (or `node scripts/gds/setup.js`) first — recall searches as you, so it can scope results to your rank.');
+    console.error(`Not signed in. Run ${require('./surface').action('setup')} first — recall searches as you, so it can scope results to your rank.`);
   } else if (r.status === 429) {
     console.error(`Rate limited (${r.data && r.data.retry_after_seconds ? r.data.retry_after_seconds + 's' : 'slow down'}). Recall is capped per builder per minute.`);
   } else {

package/scripts/gds/start.js

@@ -156,7 +156,7 @@ function quietStatusLine(header) {
   if (ideas != null) parts.push(`${ideas} idea${ideas === 1 ? '' : 's'} in inbox`);
   if (blockers != null) parts.push(`${blockers} open blocker${blockers === 1 ? '' : 's'}`);
   if (parts.length === 0) return null;
-  return `_${parts.join('  ·  ')}_`;
+  return surface.em(parts.join('  ·  '));
 }
 
 // Calibrated estimate, compact: ~8m / ~2h / ~1.5h.
@@ -201,6 +201,7 @@ function whatItIs(t) {
 // The claimable table — # / Version / Type / Reward / Est. / What it is.
 // Ids are emitted as hall links (renders as a clean #N) — a bare "#NNN" in a
 // relayed chat message autolinks to GitHub and 404s (CLAUDE.md ref rule).
+const surface = require('./surface');
 const HALL_TASK = `${hallBase()}#/task/`;
 function claimableTable(rows, rewardFromServer) {
   // On a cost-plus-only instance the Reward column is an advertised estimate that
@@ -208,15 +209,18 @@ function claimableTable(rows, rewardFromServer) {
   // and footnote what IS paid below the table (task 1002469).
   const perTask = rewardPolicy(rewardFromServer).perTaskCredit;
   const rewardHead = perTask ? 'Reward' : 'Reward (est.)';
-  const out = [
-    `| # | Version | Type | ${rewardHead} | Est. | What it is |`,
-    '|---|---|---|---|---|---|',
-  ];
-  for (const t of rows) {
-    out.push(`| [#${t.id}](${HALL_TASK}${t.id}) | ${cell(t.version_id || '?')} | ${cell(disciplineLabel(t) || '—')} | ${t.credits_reward ?? 0}c | ${estimateShort(t)} | ${cell(whatItIs(t))} |`);
-  }
+  const headers = ['#', 'Version', 'Type', rewardHead, 'Est.', 'What it is'];
+  const body = rows.map((t) => [
+    surface.taskRef(t.id, HALL_TASK),
+    cell(t.version_id || '?'),
+    cell(disciplineLabel(t) || '—'),
+    `${t.credits_reward ?? 0}c`,
+    estimateShort(t),
+    cell(whatItIs(t)),
+  ]);
+  const out = [surface.table(headers, body)];
   const cpNote = costPlusOnlyNote(rewardFromServer);
-  if (cpNote) out.push('', `_${cpNote}_`);
+  if (cpNote) out.push('', surface.em(cpNote));
   return out.join('\n');
 }
 
@@ -268,7 +272,8 @@ function rebaseWarningModel(needsRebaseTasks) {
 function rebaseWarningMarkdown(needsRebaseTasks) {
   const w = rebaseWarningModel(needsRebaseTasks);
   if (!w) return null;
-  return `⚠️ **Rebase owed — your queue is GATED.** ${w.count} ${w.noun} can't land and block new claims until you rebase + re-ship (or \`/builder-release\`) ${w.pronoun}: ${w.refs}.`;
+  return `⚠️ ${surface.strong('Rebase owed — your queue is GATED.')} ${w.count} ${w.noun} can't land and block new claims`
+    + ` until you rebase + re-ship (or ${surface.code(surface.action('release'))}) ${w.pronoun}: ${w.refs}.`;
 }
 
 // The widget warning block (Tabler alert icon, danger-tinted), or '' when none.
@@ -302,6 +307,9 @@ const CARD_DIRECTIVE = {
   markdown: '[otb-card] stdout is the finished /builder-start card (markdown). Output it verbatim as your reply, then stop — no rebuilt table, recommendation, nudge, or recap.',
 };
 function emitCardDirective(form) {
+  // Addressed to the model, not the reader. A terminal user has no card to relay and no
+  // show_widget to call, so this line is pure confusion there (task 1003680).
+  if (surface.isTerminal()) return;
   process.stderr.write(CARD_DIRECTIVE[form] + '\n');
 }
 
@@ -550,20 +558,20 @@ function isLocalOrigin(origin) {
 // ships inside the PRIVATE @bongos/core package) even exists.
 function instanceNotRunningCard({ origin, depsMissing } = {}) {
   const out = [];
-  out.push(`**builder-start — this instance isn't reachable yet**`);
+  out.push(surface.strong("builder-start — this instance isn't reachable yet"));
   out.push('');
 
   if (!isLocalOrigin(origin)) {
-    out.push(`I couldn't reach \`${origin}\`. That instance is **hosted** — it isn't this machine's server to start, so there's nothing to bring up here.`);
+    out.push(`I couldn't reach ${surface.code(origin)}. That instance is ${surface.strong('hosted')} — it isn't this machine's server to start, so there's nothing to bring up here.`);
     out.push('');
-    out.push(`1. **The board is a website, and it needs nothing installed** — open ${origin}/builders to see and claim work right now.`);
+    out.push(`1. ${surface.strong('The board is a website, and it needs nothing installed')} — open ${origin}/builders to see and claim work right now.`);
     out.push(`2. If that doesn't load either, the instance itself is down: \`curl -sI ${origin}/healthz\` says whether it's answering.`);
-    out.push(`3. Once it answers, re-run \`/builder-start\`.`);
+    out.push(`3. Once it answers, re-run ${surface.code(surface.action('start'))}.`);
     out.push('');
-    out.push(`**Don't run \`bongos dev\` for this.** It stands up a *separate local* instance with its own empty database — it cannot show you this board, and it would hide the outage behind an empty one.`);
+    out.push(`${surface.strong(`Don't run ${surface.code('bongos dev')} for this.`)} It stands up a separate local instance with its own empty database — it cannot show you this board, and it would hide the outage behind an empty one.`);
     if (depsMissing) {
       out.push('');
-      out.push(`(The \`bongos\` CLI isn't installed here. It's optional — the website above is the same board. \`@bongos/core\` is a **private** package, so installing it needs an \`NPM_TOKEN\`; a 404 without one is expected, not a missing version.)`);
+      out.push(`(The ${surface.code('bongos')} CLI isn't installed here. It's optional — the website above is the same board. ${surface.code('@bongos/core')} is a ${surface.strong('private')} package, so installing it needs an ${surface.code('NPM_TOKEN')}; a 404 without one is expected, not a missing version.)`);
     }
     return out.join('\n');
   }
@@ -575,7 +583,7 @@ function instanceNotRunningCard({ origin, depsMissing } = {}) {
     out.push(`${n++}. \`npm install\` — installs the toolchain first (the \`bongos\` CLI ships inside \`@bongos/core\`, so nothing else runs until this does).`);
   }
   out.push(`${n++}. \`bongos dev\` — one command: starts Postgres, builds the tables, runs the server, and signs you in.`);
-  out.push(`${n++}. Re-run \`/builder-start\`.`);
+  out.push(`${n++}. Re-run ${surface.code(surface.action('start'))}.`);
   out.push('');
   out.push(`Meant to work on a *different* instance that's already running? Sign in to it with \`bongos login <url>\` first.`);
   return out.join('\n');
@@ -800,7 +808,7 @@ async function main() {
       ? b.preferred_disciplines.join(' + ')
       : 'all disciplines';
     const credits = Number(b.total_credits || 0).toLocaleString();
-    console.log(`**builder-start** · ${b.github_login} (${rankLabel}) · ${credits} credits · ${discLabel}`);
+    console.log(`${surface.strong('builder-start')} · ${b.github_login} (${rankLabel}) · ${credits} credits · ${discLabel}`);
     const sk = me.data.streak;
     if (sk && Number(sk.current) > 0) {
       console.log(`🔥 ${sk.current}-day streak${Number(sk.longest) > Number(sk.current) ? ` · longest ${sk.longest}` : ''}`);
@@ -847,16 +855,18 @@ async function main() {
   // not block — feedback_parallel_sessions). Ids are hall links (ref rule).
   if (me.ok) {
     const myClaims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
-    const heldActions = (id) => `    → ship: \`/builder-ship ${id}\`  ·  release: \`/builder-release ${id}\`  ·  open: [#${id}](${HALL_TASK}${id})`;
+    const heldActions = (id) => `    → ship: ${surface.code(surface.action('ship', id))}`
+      + `  ·  release: ${surface.code(surface.action('release', id))}`
+      + `  ·  open: ${surface.taskRef(id, HALL_TASK)}`;
     if (myClaims.length === 1) {
       const c = myClaims[0];
-      console.log(`You're holding [#${c.task_id}](${HALL_TASK}${c.task_id}) — ${clip(c.title, 56)}`);
+      console.log(`You're holding ${surface.taskRef(c.task_id, HALL_TASK)} — ${clip(c.title, 56)}`);
       console.log(heldActions(c.task_id));
       console.log('');
     } else if (myClaims.length > 1) {
       console.log(`You're holding ${myClaims.length} claims (parallel sessions OK):`);
       for (const c of myClaims) {
-        console.log(`  [#${c.task_id}](${HALL_TASK}${c.task_id}) — ${clip(c.title, 50)}`);
+        console.log(`  ${surface.taskRef(c.task_id, HALL_TASK)} — ${clip(c.title, 50)}`);
         console.log(heldActions(c.task_id));
       }
       console.log('');
@@ -869,7 +879,7 @@ async function main() {
     console.log(
       `🚦 ${s.versionId} looks ready to close ` +
       `(${s.criteriaSatisfied}/${s.criteriaTotal} criteria, ${s.percentComplete}% weighted; ` +
-      `${s.tasksShipped} shipped, ${s.tasksCarryOver} carry-over). Run /builder-version-close ${s.versionId}.`
+      `${s.tasksShipped} shipped, ${s.tasksCarryOver} carry-over). Run ${surface.action('version-close', s.versionId)}.`
     );
     console.log('');
   }
@@ -882,7 +892,7 @@ async function main() {
     fit && `fit=${fit}`,
   ].filter(Boolean);
   const filterNote = filterBits.length ? ` (${filterBits.join(', ')})` : '';
-  console.log(`**Claim one to start** — ${filtered.length} ready for you right now${matched}${filterNote}:`);
+  console.log(`${surface.strong('Claim one to start')} — ${filtered.length} ready for you right now${matched}${filterNote}:`);
   console.log('');
   if (claimable.length) {
     const cardRows = claimable.slice(0, CARD_ROWS);
@@ -890,10 +900,13 @@ async function main() {
     const moreN = filtered.length - cardRows.length;
     if (moreN > 0) {
       console.log('');
-      console.log(`_…and ${moreN} more — say "show all", or run with --limit 30._`);
+      console.log(surface.em(`…and ${moreN} more — say "show all", or run with --limit 30.`));
     }
   } else {
-    console.log("_Nothing claimable right now — everything is in flight, blocked, or shipped. Run /blocker-review to see what's stuck._");
+    console.log(surface.em(
+      "Nothing claimable right now — everything is in flight, blocked, or shipped."
+      + (surface.isTerminal() ? '' : " Run /blocker-review to see what's stuck.")
+    ));
   }
 
   // Cross-discipline pointer (one line) — only when preference-routed.
@@ -908,7 +921,7 @@ async function main() {
 
   // ---------- next ----------
   console.log('');
-  console.log('→ **Tell me a number** to claim it.');
+  console.log(`→ ${surface.isTerminal() ? `Claim one with ${surface.code('bongos claim <id>')} in a checkout` : `${surface.strong('Tell me a number')} to claim it`}.`);
   if (full) {
     console.log('');
     console.log('Commands:');

package/scripts/gds/surface.js

@@ -0,0 +1,89 @@
+// scripts/gds/surface.js — who is reading this output: an agent, or a person in a terminal?
+// (task 1003680, follow-up to ADR 0258.)
+//
+// WHY THIS EXISTS
+// The CLI's cards were written for exactly one reader: a Claude Code session. They carry
+// `[otb-card]` directives addressed to the model, `/builder-ship N` slash commands, and markdown
+// link syntax — all correct in a chat feed, all wrong in a terminal. That stayed invisible while
+// the CLI lived inside the private core, because the only way to run it was from a session.
+// `@cloudbongos/cli` (ADR 0258) put the same output in front of newcomers on a bare laptop, where
+// the first thing they read is an instruction written to somebody else and a command that does
+// not exist.
+//
+// HOW THE SURFACE IS DECIDED — and why not isTTY
+// AGENT is the default, so nothing about the Claude Code path changes unless something opts out.
+// The opt-out is `BONGOS_SURFACE=terminal`, set by the `bongos` DISPATCHER (bin/bongos.js, and the
+// generated one in the public package) when it spawns a verb. The skills and the card-delivery
+// hook run `node scripts/gds/<verb>.js` DIRECTLY, never through the dispatcher, so they keep the
+// agent shape byte-for-byte.
+//
+// `process.stdout.isTTY` would get this exactly backwards: a Claude Code session's stdout is not a
+// TTY either, so TTY-sniffing would classify every agent run as a terminal and break the card
+// contract the skills depend on. The signal has to be an explicit statement of intent, not a guess.
+
+'use strict';
+
+const AGENT = 'agent';
+const TERMINAL = 'terminal';
+
+// Which reader is this output for? Pure: takes the env, returns a string.
+function resolveSurface(env = process.env) {
+  const raw = String((env && env.BONGOS_SURFACE) || '').trim().toLowerCase();
+  return raw === TERMINAL ? TERMINAL : AGENT;
+}
+
+function isTerminal(env = process.env) {
+  return resolveSurface(env) === TERMINAL;
+}
+
+// A task reference. Agents get a hall link because a bare `#NNN` autolinks to GitHub issues and
+// 404s (the CLAUDE.md ref rule); a terminal reader gets the plain id and the URL beside it, since
+// `[#123](https://…)` is just noise on a console.
+function taskRef(id, url, env = process.env) {
+  return isTerminal(env) ? `#${id}` : `[#${id}](${url}${id})`;
+}
+
+// An action the reader can actually run. In a session that is the slash command; in a terminal it
+// is the `bongos` verb. `/builder-ship 123` does not exist outside Claude Code.
+function action(verb, arg, env = process.env) {
+  const tail = arg == null ? '' : ` ${arg}`;
+  return isTerminal(env) ? `bongos ${verb}${tail}` : `/builder-${verb}${tail}`;
+}
+
+// Markdown emphasis is decoration in a feed and literal asterisks on a console.
+function strong(s, env = process.env) {
+  return isTerminal(env) ? String(s) : `**${s}**`;
+}
+function em(s, env = process.env) {
+  return isTerminal(env) ? String(s) : `_${s}_`;
+}
+function code(s, env = process.env) {
+  return isTerminal(env) ? String(s) : `\`${s}\``;
+}
+
+// A table. Agents get GitHub-flavoured markdown (the feed renders it); a terminal gets columns
+// padded to width with a rule under the header, which is what a console can actually align.
+function table(headers, rows, env = process.env) {
+  if (!isTerminal(env)) {
+    return [
+      `| ${headers.join(' | ')} |`,
+      `|${headers.map(() => '---').join('|')}|`,
+      ...rows.map((r) => `| ${r.join(' | ')} |`),
+    ].join('\n');
+  }
+  const widths = headers.map((h, i) => Math.max(
+    String(h).length,
+    ...rows.map((r) => String(r[i] == null ? '' : r[i]).length),
+  ));
+  const line = (cells) => cells
+    .map((c, i) => String(c == null ? '' : c).padEnd(widths[i]))
+    .join('  ')
+    .replace(/\s+$/, '');
+  return [
+    line(headers),
+    widths.map((w) => '─'.repeat(w)).join('  '),
+    ...rows.map(line),
+  ].join('\n');
+}
+
+module.exports = { AGENT, TERMINAL, resolveSurface, isTerminal, taskRef, action, strong, em, code, table };

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.580'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.581'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/cli_surface.mjs

@@ -0,0 +1,146 @@
+// tests/cli_surface.mjs — the CLI addresses the reader it actually has (task 1003680).
+//
+// Two obligations, and the second is the one that could silently break the whole methodology:
+//
+//  1. A terminal reader never sees output written to a model — no `[otb-card]` directive, no
+//     `/builder-*` slash command (those exist only inside Claude Code), no raw markdown link.
+//
+//  2. The AGENT shape is unchanged. The skills and the card-delivery hook relay `start.js`'s
+//     stdout verbatim and branch on its first character; a stray difference there breaks the card
+//     contract for every session. So the agent cases below assert the exact old strings.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(import.meta.url);
+const surface = require(path.join(REPO_ROOT, 'scripts', 'gds', 'surface.js'));
+
+const AGENT_ENV = {};
+const TERM_ENV = { BONGOS_SURFACE: 'terminal' };
+
+// ── 1. The signal itself ────────────────────────────────────────────────────────────────────
+
+test('agent is the default — nothing changes unless something opts out', () => {
+  assert.equal(surface.resolveSurface({}), 'agent');
+  assert.equal(surface.resolveSurface({ BONGOS_SURFACE: '' }), 'agent');
+  assert.equal(surface.resolveSurface({ BONGOS_SURFACE: 'nonsense' }), 'agent');
+  assert.equal(surface.isTerminal({}), false);
+});
+
+test('terminal is opt-in, case- and space-insensitive', () => {
+  assert.equal(surface.resolveSurface({ BONGOS_SURFACE: 'terminal' }), 'terminal');
+  assert.equal(surface.resolveSurface({ BONGOS_SURFACE: '  TERMINAL  ' }), 'terminal');
+  assert.equal(surface.isTerminal(TERM_ENV), true);
+});
+
+test('the surface is never inferred from isTTY', () => {
+  // A Claude Code session's stdout is not a TTY either, so TTY-sniffing would classify every
+  // agent run as a terminal and break the card contract. The module must not consult it.
+  const src = require('node:fs').readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'surface.js'), 'utf8');
+  const code = src.split('\n').filter((l) => !l.trim().startsWith('//')).join('\n');
+  assert.ok(!/isTTY/.test(code), 'surface.js must not branch on isTTY');
+});
+
+// ── 2. What each reader gets ────────────────────────────────────────────────────────────────
+
+test('actions name a command the reader can actually run', () => {
+  assert.equal(surface.action('ship', 123, AGENT_ENV), '/builder-ship 123');
+  assert.equal(surface.action('ship', 123, TERM_ENV), 'bongos ship 123');
+  assert.equal(surface.action('start', null, AGENT_ENV), '/builder-start');
+  assert.equal(surface.action('start', null, TERM_ENV), 'bongos start');
+});
+
+test('task refs stay hall links for agents and go plain for terminals', () => {
+  const url = 'https://example.com/builders#/task/';
+  assert.equal(surface.taskRef(7, url, AGENT_ENV), '[#7](https://example.com/builders#/task/7)');
+  assert.equal(surface.taskRef(7, url, TERM_ENV), '#7');
+});
+
+test('emphasis is markdown for agents and bare text for terminals', () => {
+  assert.equal(surface.strong('hi', AGENT_ENV), '**hi**');
+  assert.equal(surface.strong('hi', TERM_ENV), 'hi');
+  assert.equal(surface.em('hi', AGENT_ENV), '_hi_');
+  assert.equal(surface.em('hi', TERM_ENV), 'hi');
+  assert.equal(surface.code('x', AGENT_ENV), '`x`');
+  assert.equal(surface.code('x', TERM_ENV), 'x');
+});
+
+test('the agent table is still GitHub-flavoured markdown, byte for byte', () => {
+  const out = surface.table(['#', 'What'], [['a', 'b']], AGENT_ENV);
+  assert.equal(out, '| # | What |\n|---|---|\n| a | b |');
+});
+
+test('the terminal table aligns into columns with no pipe soup', () => {
+  const out = surface.table(['#', 'What'], [['1', 'short'], ['22', 'a longer one']], TERM_ENV);
+  const lines = out.split('\n');
+  assert.ok(!out.includes('|'), `no pipes in a terminal table:\n${out}`);
+  assert.ok(!/\|---/.test(out), 'no markdown separator row');
+  assert.match(lines[1], /^─+ {2}─+$/, 'a rule under the header');
+  // Column two must start at the same offset on every row.
+  const col2 = lines.filter((_, i) => i !== 1).map((l) => l.indexOf(l.trim().split(/\s{2,}/)[1]));
+  assert.equal(new Set(col2).size, 1, `column 2 misaligned:\n${out}`);
+});
+
+test('no trailing whitespace on a terminal row', () => {
+  const out = surface.table(['a', 'bbbb'], [['x', 'y']], TERM_ENV);
+  for (const line of out.split('\n')) assert.ok(!/\s$/.test(line), `trailing space: ${JSON.stringify(line)}`);
+});
+
+// ── 3. The call sites ───────────────────────────────────────────────────────────────────────
+
+test('start.js routes every reader-facing idiom through the surface', () => {
+  const src = require('node:fs').readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'start.js'), 'utf8');
+  const code = src.split('\n').filter((l) => !l.trim().startsWith('//')).join('\n');
+
+  // Two exemptions, both agent-only BY CONSTRUCTION:
+  //   • CARD_DIRECTIVE describes the card TO the model, so naming the slash command is correct.
+  //   • the `--widget` HTML renderer only ever runs for a session with show_widget; its markup
+  //     is identifiable by hesc()/class="bs-" and never reaches a terminal.
+  const scanned = code
+    .replace(/const CARD_DIRECTIVE = \{[\s\S]*?\};/, '')
+    .split('\n')
+    .filter((l) => !l.includes('hesc(') && !l.includes('class="bs-'))
+    .join('\n');
+  const slashes = [...scanned.matchAll(/\/builder-[a-z-]+/g)].map((m) => m[0]);
+  assert.deepEqual(slashes, [], `hard-coded slash commands left in start.js: ${slashes.join(', ')}`);
+
+  // A hall link built by hand would bypass the switch.
+  const rawRefs = [...code.matchAll(/\[#\$\{[^}]+\}\]\(/g)].map((m) => m[0]);
+  assert.deepEqual(rawRefs, [], 'hand-built markdown task links left in start.js');
+});
+
+test('the card directive is suppressed for a terminal reader', () => {
+  const src = require('node:fs').readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'start.js'), 'utf8');
+  assert.match(
+    src,
+    /function emitCardDirective\(form\) \{[\s\S]{0,400}?surface\.isTerminal\(\)\) return;/,
+    'emitCardDirective must return early on a terminal surface',
+  );
+});
+
+test('only the dispatchers declare the terminal surface', () => {
+  const fs = require('node:fs');
+  const dispatcher = fs.readFileSync(path.join(REPO_ROOT, 'bin', 'bongos.js'), 'utf8');
+  assert.match(dispatcher, /BONGOS_SURFACE: 'terminal'/, 'bin/bongos.js must mark verb spawns as terminal');
+
+  // `exec` is the agent's escape hatch into a core script and must NOT be marked.
+  const execLine = dispatcher.split('\n').find((l) => l.includes('args.slice(2)') && l.includes('spawnSync'));
+  assert.ok(execLine, 'could not find the exec spawn');
+  assert.ok(!execLine.includes('BONGOS_SURFACE'), '`bongos exec` must stay on the agent surface');
+
+  const builder = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'build-cli-package.js'), 'utf8');
+  assert.match(builder, /BONGOS_SURFACE: 'terminal'/, 'the generated dispatcher must mark spawns as terminal');
+  assert.match(builder, /'scripts\/gds\/surface\.js'/, 'surface.js must ship in the package');
+});
+
+test('the skills still invoke the scripts directly, which is what keeps agents on the agent surface', () => {
+  // If a skill ever routed through `bongos <verb>`, it would silently inherit the terminal
+  // surface and the card contract would break with no test failing anywhere else.
+  const fs = require('node:fs');
+  const skill = fs.readFileSync(path.join(REPO_ROOT, '.claude', 'skills', 'builder-start', 'SKILL.md'), 'utf8');
+  assert.match(skill, /node scripts\/gds\/start\.js/, 'builder-start must call the script directly');
+});