@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/cli-lib.js

@@ -0,0 +1,1226 @@
+// Shared helpers for GDS CLI scripts (the things the builder-* slash commands invoke).
+// Renamed from PMS in V3.R01.
+//
+// - Reads / writes the session token at ~/.config/otb/gds-session.json
+//   (resolved via os.homedir(), so this works for any user on any machine).
+//   The legacy path ~/.config/otb/pms-session.json is still accepted on read,
+//   purely so any existing pre-rename session keeps working through the
+//   rollout — that's read-only back-compat, not a personalization.
+// - Provides apiCall(method, path, body) with the auth header
+// - Provides format helpers for terminal output (no deps; this isn't a TTY app,
+//   it's text the slash command consumes)
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { execSync } = require('node:child_process');
+const ic = require('../../src/instance-config');
+
+// Session token filenames, NEWEST FIRST. The WRITE target is the configured
+// instance dir (~/.config/<configDir>/bongos-session.json; OTB → ~/.config/otb,
+// unchanged). On READ we try each name across every config read dir (configured +
+// legacy otb) — so a pre-rename session, or one written by a differently-
+// namespaced instance, still resolves (R61 / task 1200). os.homedir() keeps it
+// per-user on any machine.
+//
+// WHY THE OLD NAMES STAY READABLE. This file is on disk on every builder machine.
+// Renaming it with no fallback signs all of them out at once and every /builder-*
+// command dies with 'no Bongos session'. So a read that resolves through a
+// superseded name MIGRATES forward (see loadSession), and the old file is
+// deliberately LEFT IN PLACE — a builder may roll back to an older CLI, which
+// can only see the old name. Part 4 (task 1003706) deletes it behind a
+// test of its absence. (task 1003704)
+//
+// Order is FILENAME-major, not directory-major: the newest name found in ANY read
+// dir beats an older name in the configured dir. That is the precedence a rename
+// wants, and it is the order the two-name version of this list already used.
+// The list itself lives in instance-config (the lowest module that reads the
+// file, and the only one cli-lib and paste-token.js can both import).
+// Destructured, not read off `ic` as a member: knip cannot trace a namespace-only
+// property access on this module and reports the export dead (the same blind spot
+// task 1003703 closed for two other instance-config exports).
+const { SESSION_FILENAMES } = require('../../src/instance-config');
+const SESSION_PATH = ic.configPath(SESSION_FILENAMES[0]);
+const SESSION_READ_PATHS = SESSION_FILENAMES.flatMap((n) => ic.configReadPaths(n));
+// The API base every CLI call targets, resolved ONCE through the single source of
+// truth in instance-config: <PREFIX>_API_BASE (then legacy GDS_/OTB_/PMS_) → the
+// persisted session's api_base → THIS instance's publicOrigin from the branding
+// pack. Override for local dev / staging:
+//   CLOUDBONGOS_API_BASE=http://localhost:3000 node scripts/bongos/start.js
+// No CLI script hard-codes another instance's URL (task 1002201; pre-ADR-0139 the
+// founder instance's apex was baked in literally at four sites here). The session
+// leg was added at task 1002427 — this const previously stopped at the branding
+// default, so module-level consumers (reauth's Settings URL, the hall links
+// hallBase() prints) named the checkout's own instance instead of the one the
+// builder is signed into.
+const API_BASE = ic.resolveApiBase();
+
+// User-Agent for the GDS CLI's HTTP calls — the branding-derived neutral platform UA
+// from the single source, src/branding.js userAgent() (`<repo.name|envPrefix>-gds/1.0`,
+// neutral fallback `cloud-bongos-gds/1.0`), matching the `cloud-bongos-` convention the
+// hooks use (tests/hook_user_agents.mjs). Was a hardcoded '<founder-instance>-gds-cli/1.0'
+// at both fetch sites — task 1002234. Resolved once so apiCall + cliClient never diverge
+// and branding is read a single time; falls back neutrally if branding is unreadable.
+const CLI_USER_AGENT = (() => {
+  try { return require('../../src/branding').userAgent(); }
+  catch (_) { return 'cloud-bongos-gds/1.0'; }
+})();
+
+// productName() — the instance's product name for user-facing CLI copy, from the
+// branding pack (task 1002428). Was hardcoded as the founder brand at several
+// print sites, so a non-OTB instance told ITS builders about someone else's
+// product. Neutral fallback, never a foreign brand.
+function productName() {
+  try {
+    const id = require('../../src/branding').branding().identity || {};
+    if (id.productName) return id.productName;
+  } catch (_) { /* fall through */ }
+  return 'Cloud Bongos';
+}
+
+// rewardPolicy() — the instance's RESOLVED reward policy (ADR 0146), for CLI copy
+// that prints a task's `credits_reward`. On a `cost-plus-only` instance that
+// number is an advertised GUIDE and is never paid; the cost-plus session reward
+// is the sole stream. Printing it bare reads as a promise, and a builder who
+// then ships and sees `+0` reasonably concludes the payout broke (it cost a real
+// session on 2026-07-26 — task 1002469).
+//
+// PREFER THE SERVER'S ANSWER. The mode is INSTANCE config, and an instance's
+// config/branding.json is NOT in the builder's checkout — a laptop resolving
+// locally sees only config/branding.neutral.json and would report the paying
+// default on the very instance that withholds. So callers pass the `reward`
+// block the server sends (GET /me, POST /claims); the local read is a fallback
+// for an older server that doesn't send one, and the ADR default is the floor.
+// Resolution itself is always economy's (ADR 0146) — never re-derived here.
+function rewardPolicy(fromServer) {
+  if (fromServer && typeof fromServer.mode === 'string') {
+    return { mode: fromServer.mode, perTaskCredit: fromServer.perTaskCredit !== false };
+  }
+  try {
+    // economy's PURE resolver + our own branding read, NOT ./credits (task
+    // 1003676): credits.js imports { pool, branding } from src/module-api at
+    // module scope, so this one fallback require used to drag Postgres + auth +
+    // db-kernel into EVERY CLI subcommand's closure — which is what stopped the
+    // CLI shipping as a public, client-only package. Same resolver, same answer,
+    // no server. The CLI is not a module, so reading src/branding directly here
+    // is allowed where it would not be inside modules/ (ADR 0083).
+    const { rewardPolicy: resolve } = require('../../modules/economy/reward-policy');
+    let raw = {};
+    try { raw = (require('../../src/branding').branding().reward) || {}; } catch (_) { raw = {}; }
+    const p = resolve(raw);
+    if (p && typeof p.mode === 'string') return p;
+  } catch (_) { /* fall through */ }
+  return { mode: 'cost-plus-and-estimate', perTaskCredit: true };
+}
+
+// The one-line builder-facing explanation shown wherever an estimate is
+// displayed on a cost-plus-only instance. Returns null on a paying instance so
+// every call site is a no-op there. Single source for the wording so claim /
+// start / ship say the SAME thing (task 1002469).
+function costPlusOnlyNote(fromServer) {
+  if (rewardPolicy(fromServer).perTaskCredit) return null;
+  return 'This instance pays cost-plus only: you earn real session cost + 20%, not the estimate above.';
+}
+
+// hallBase(base) — the instance's builders' hall root for a given API base, e.g.
+// https://cloudbongos.com/builders. Derived from the RESOLVED base (env → session →
+// branding default), never a hardcoded host — so a CLI-printed link always points at
+// the instance the command is actually talking to, not the founder instance's box
+// (task 1002233; the printed-link twin of the task-1002201 default-base fix). Falls
+// back to `${base}/builders` when base isn't a parseable absolute URL.
+function hallBase(base = API_BASE) {
+  try { return `${new URL(base).origin}/builders`; }
+  catch { return `${String(base || '').replace(/\/+$/, '')}/builders`; }
+}
+
+// Node-24-on-Windows workaround: every CLI invocation here is a short-lived
+// process that makes one or a handful of requests, but a kept-alive socket can
+// still be mid-close when the caller's process.exit() runs, tripping a
+// UV_HANDLE_CLOSING assertion that corrupts piped JSON stdout. Connection reuse
+// buys these one-shot processes nothing, so route requests through a dispatcher
+// with keep-alive effectively disabled. Degrades to the default dispatcher if
+// undici can't be required.
+//
+// task 1002734 — THIS ALONE IS NOT ENOUGH, and the measurements say so: with the
+// dispatcher wired in and undici resolving fine, `node scripts/bongos/api.js GET
+// /tasks/<id>` still aborted 5/5 on Windows 11 / Node 24. The dispatcher removes
+// one contributing handle; the actual trigger is calling process.exit() at all
+// while the request machinery is still tearing down. A minimal synthetic
+// fetch-then-exit does NOT reproduce, so it takes the real stack (the dynamic ESM
+// client import + the Agent + any child spawn / consumed stdin) to line up — which
+// is exactly why hunting the single guilty handle is a dead end.
+//
+// The rule for every CLI here: after a request, DO NOT call process.exit().
+// Set process.exitCode and return, and let the loop drain — see cliExit below.
+// Verified: the pre-push gate went 8/8 aborting to 0/8 on that change alone
+// (task 1002725), and api.js 5/5 to 0/5 (this task).
+let _noKeepAliveDispatcher;
+let _noKeepAliveTried = false;
+function noKeepAliveDispatcher() {
+  if (_noKeepAliveTried) return _noKeepAliveDispatcher;
+  _noKeepAliveTried = true;
+  try {
+    const { Agent } = require('undici');
+    _noKeepAliveDispatcher = new Agent({ keepAliveTimeout: 1, keepAliveMaxTimeout: 1 });
+  } catch { _noKeepAliveDispatcher = undefined; }
+  return _noKeepAliveDispatcher;
+}
+
+// task 1002670 — the vendored Agent above is only valid as a `dispatcher` for
+// Node's built-in fetch when the two undici copies speak the same internal
+// handler protocol. Node 26 bundles undici 8 while package.json overrides pin
+// the vendored copy at ^6, so built-in fetch rejects the v6 Agent with
+// InvalidArgumentError('invalid onError method') / UND_ERR_INVALID_ARG *before
+// any network I/O* — and every CLI then misreported a pure client-side bug as
+// "this instance isn't reachable yet". The pairing can't be predicted from
+// version numbers alone (a v6 Agent works fine under Node 24's undici 7), so
+// the selection is empirical: try the vendored Agent, and on the first
+// incompat rejection drop it for the rest of the process and retry the request
+// once on the default dispatcher.
+function isDispatcherIncompatError(err) {
+  const seen = new Set();
+  for (let e = err; e && typeof e === 'object' && !seen.has(e); e = e.cause) {
+    seen.add(e);
+    if (e.code === 'UND_ERR_INVALID_ARG' || e.name === 'InvalidArgumentError') return true;
+  }
+  return false;
+}
+
+// Test-only: reset the tried-once singleton so tests/cli_dispatcher.mjs can
+// exercise the selection/fallback from a clean slate regardless of what earlier
+// (real) requests did to it on this Node version.
+function _noKeepAliveResetForTest() {
+  _noKeepAliveDispatcher = undefined;
+  _noKeepAliveTried = false;
+}
+
+async function dispatchedFetch(url, init = {}, fetchImpl = fetch) {
+  const injected = init.dispatcher !== undefined && init.dispatcher === _noKeepAliveDispatcher;
+  try {
+    return await fetchImpl(url, init);
+  } catch (err) {
+    if (!injected || !isDispatcherIncompatError(err)) throw err;
+    // The vendored Agent is incompatible with this Node's built-in fetch.
+    // Stop offering it process-wide, then retry on the default dispatcher.
+    _noKeepAliveDispatcher = undefined;
+    const retry = { ...init };
+    delete retry.dispatcher;
+    return fetchImpl(url, retry);
+  }
+}
+
+// cliExit(code) — the post-request replacement for process.exit(code). Records the
+// exit status and lets node exit naturally once the loop drains, which is what
+// keeps the UV_HANDLE_CLOSING abort above from firing. Callers must `return` after
+// calling it: unlike process.exit() it does NOT stop execution.
+//
+// Gotcha (learned in task 1002725): a hard exit MASKS leaked timers/handles. Once a
+// CLI exits naturally, anything still armed — an uncleared setTimeout, an open
+// interval — keeps the process alive. Clear them, or the CLI hangs instead of
+// crashing.
+function cliExit(code = 0) {
+  process.exitCode = code;
+}
+
+async function readSessionFile(p) {
+  try {
+    const raw = await fsp.readFile(p, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+// Copy a session that resolved through a SUPERSEDED path forward to SESSION_PATH,
+// so the next command reads the new name directly instead of walking the fallback
+// list forever. The old file is left in place on purpose (see SESSION_FILENAMES).
+//
+// BEST-EFFORT BY DESIGN: a read-only home, a full disk, or a permissions problem
+// must never turn a working loadSession() into a failing command. The caller
+// already holds a valid session; failing to write the copy changes nothing about
+// this invocation. So every error is swallowed and the session is still returned.
+async function migrateSessionFile(session) {
+  try {
+    await fsp.mkdir(path.dirname(SESSION_PATH), { recursive: true });
+    await fsp.writeFile(SESSION_PATH, JSON.stringify(session, null, 2), { mode: 0o600 });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+async function loadSession() {
+  // Try each read path in priority order (configured dir's bongos-session.json,
+  // legacy otb dir, then each superseded filename across the same dirs). A hit on
+  // anything OTHER than SESSION_PATH is migrated forward — SESSION_READ_PATHS[0]
+  // IS SESSION_PATH (configReadDirs puts the configured dir first), so the common
+  // case writes nothing.
+  for (const p of SESSION_READ_PATHS) {
+    const s = await readSessionFile(p);
+    if (s) {
+      if (p !== SESSION_PATH) await migrateSessionFile(s);
+      return s;
+    }
+  }
+  return null;
+}
+
+// ---- the shared session store (task 1003741, ADR 0269) ---------------------
+// ONE FILE PER INSTANCE, at a FIXED anchor — deliberately NOT configHome().
+//
+// WHY A FIXED ANCHOR. configHome() is brand-derived, and the brand is read out of whatever checkout
+// the process is standing in. That gave the CLI exactly one session slot, and the slot MOVED: run
+// standalone (the then-public @cloudbongos/cli's whole situation; ADR 0324 retired it) the brand
+// cannot resolve, so every
+// instance shared one gds-session.json and signing into a second DESTROYED the first; run from
+// inside an instance repo and the session landed in ~/.config/<slug>/ where the standalone CLI
+// could never find it. The owner's own config dir carries a hand-made `hermeslines-clobber` backup
+// from the first mode.
+//
+// WHY HERE AND NOT instance-config.js. That module is generic config-path machinery shared with the
+// server; a CLI session store is not its concern, and cli-lib already owns SESSION_PATH and
+// SESSION_READ_PATHS. Keeping the two together means one file describes where a session lives.
+function sessionStoreDir() {
+  // Directory name deliberately NOT 'sessions': that is a live module key, and ADR 0083
+  // §Decision #4 forbids naming one in shared machinery. 'instances' is the truer name anyway —
+  // one file per instance is exactly what this holds.
+  return path.join(os.homedir(), '.config', ic.FALLBACK_DIR, 'instances');
+}
+
+// The store's filename for an instance, derived from its api_base host. Returns null when the base
+// names no host — an unkeyable session is simply not stored, never stored under a guessed name.
+function sessionHostKey(apiBase) {
+  const raw = String(apiBase || '').trim();
+  if (!raw) return null;
+  let host = null;
+  try { host = new URL(raw).host; } catch (_) { host = null; }
+  if (!host) return null;
+  // Filename-safe, and collision-free for real hosts: ':' (a port) is the only character a valid
+  // host adds beyond the safe set, and it maps to '_' which cannot otherwise appear in one.
+  const safe = host.replace(/[^A-Za-z0-9._-]/g, '_');
+  return safe && safe !== '.' && safe !== '..' ? safe : null;
+}
+
+function sessionStorePath(apiBase) {
+  const key = sessionHostKey(apiBase);
+  return key ? path.join(sessionStoreDir(), `${key}.json`) : null;
+}
+
+// Write one session into the shared, host-keyed store. No-op when the session names no host —
+// an unkeyable session is skipped, never filed under a guessed name.
+async function writeSessionToStore(session) {
+  const target = session && sessionStorePath(session.api_base);
+  if (!target) return null;
+  await fsp.mkdir(path.dirname(target), { recursive: true });
+  await fsp.chmod(path.dirname(target), 0o700).catch(() => {});
+  await fsp.writeFile(target, JSON.stringify(session, null, 2), { mode: 0o600 });
+  return target;
+}
+
+// Every instance's session is kept, not just the last one (task 1003741).
+//
+// This used to write ONE file, so `bongos login <another-instance>` silently DESTROYED the session
+// you already had — the owner's own config dir carries a hand-made `hermeslines-clobber` backup
+// from exactly that. Three steps now, and the order matters:
+//
+//   1. archive the OUTGOING session first. That is what rescues a session written before the store
+//      existed: it was never in the store, so without this step the very first login after
+//      upgrading would still lose it.
+//   2. store the incoming one under its own host.
+//   3. write the ACTIVE pointer exactly where it has always gone, so every existing reader —
+//      in-repo skills and hooks — behaves identically.
+async function saveSession(session) {
+  const dir = path.dirname(SESSION_PATH);
+  await fsp.mkdir(dir, { recursive: true });
+
+  try {
+    const prev = await loadSession();
+    const prevKey = prev && prev.token ? sessionHostKey(prev.api_base) : null;
+    const nextKey = sessionHostKey(session && session.api_base);
+    if (prevKey && prevKey !== nextKey) await writeSessionToStore(prev);
+  } catch (_) {
+    // Archiving is best-effort — a lost previous session must never block a real sign-in.
+  }
+
+  await writeSessionToStore(session).catch(() => null);
+  await fsp.writeFile(SESSION_PATH, JSON.stringify(session, null, 2), { mode: 0o600 });
+}
+
+// The stored session for one instance, or null. Used by `bongos login` to switch back to an
+// instance you are already signed into without a fresh device flow.
+async function loadStoredSession(apiBase) {
+  const target = sessionStorePath(apiBase);
+  if (!target) return null;
+  return readSessionFile(target);
+}
+
+// Every instance this machine has a stored session for — so the CLI can say which one it is
+// targeting and what else it remembers. Sorted for a stable listing; never throws.
+function listStoredSessions() {
+  let names = [];
+  try { names = fs.readdirSync(sessionStoreDir()); } catch (_) { return []; }
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    try {
+      const j = JSON.parse(fs.readFileSync(path.join(sessionStoreDir(), name), 'utf8'));
+      if (j && j.token) {
+        out.push({
+          host: name.slice(0, -5),
+          api_base: j.api_base || null,
+          login: (j.builder && j.builder.github_login) || null,
+          instance: (j.instance && j.instance.name) || null,
+        });
+      }
+    } catch (_) { /* a corrupt entry is skipped, never fatal */ }
+  }
+  return out.sort((a, b) => a.host.localeCompare(b.host));
+}
+
+function loadSessionSync() {
+  for (const p of SESSION_READ_PATHS) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      return JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch (_) {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+// ---- argv helpers (C11) ---------------------------------------------------
+// One home for the flag parsing every GDS CLI rolled by hand. Two contracts:
+//   arg(name)     → the flag's VALUE ('--out x' or '--out=x'), else null
+//   hasFlag(name) → boolean presence ('--json', '--no-write')
+// Both default `args` to process.argv.slice(2). arg() accepts BOTH the space and
+// `=` forms (the superset — space-only callers gain `=` for free, harmlessly).
+// A presence flag wants hasFlag(), NOT arg() — they are opposite contracts
+// (repo-metrics.js learned this the hard way; do not collapse the two).
+function arg(name, args = process.argv.slice(2)) {
+  const eq = args.find((a) => a.startsWith(`${name}=`));
+  if (eq != null) return eq.slice(name.length + 1);
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+function hasFlag(name, args = process.argv.slice(2)) {
+  return args.includes(name);
+}
+
+// stripBom(s) — remove a leading UTF-8 BOM (U+FEFF), the artifact PowerShell's
+// `Out-File`/`>` redirection writes. JSON.parse does not strip it, so a
+// --body-file written from PS 5.1 fails to parse unless this runs first.
+// Non-string input passes through unchanged. Extracted (rather than left
+// inline in api.js) so it's unit-testable — api.js itself has no exports.
+function stripBom(s) {
+  if (typeof s !== 'string') return s;
+  return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+
+// argText(name, args, io) — resolve prose passed EITHER inline (`--notes "..."`)
+// or from a file (`--notes-file path`, or `-` for stdin). Returns
+// { value, source, error }: `value` is a string ('' when neither flag is
+// present), `source` is 'inline' | 'file' | 'stdin' | 'none', and `error` is a
+// caller-printable string when the request was refused or unreadable.
+//
+// WHY THIS EXISTS (learning 1000197). Prose handed to a CLI inline goes through
+// the SHELL first. A handoff note containing backticks — which technical prose
+// constantly does — is command-substituted by bash before node ever runs: the
+// backticked span executes, its output replaces it, and the rest of the argument
+// list is truncated. That is not a theoretical hazard; it silently shipped a task
+// with EMPTY notes and no summary, so the ledger recorded nothing about a session
+// that had happened. A file argument is the only form the shell cannot rewrite.
+//
+// BOTH-GIVEN IS AN ERROR, never a silent precedence. Picking one would mean the
+// caller's other input vanished without a word — the same class of quiet loss
+// this helper exists to end (the capture.js --spark/--full refusal precedent).
+function argText(name, args = process.argv.slice(2), io = {}) {
+  const readFile = io.readFile || ((f) => require('fs').readFileSync(f, 'utf8'));
+  const readStdin = io.readStdin || (() => require('fs').readFileSync(0, 'utf8'));
+  const fileFlag = `${name}-file`;
+  const inline = arg(name, args);
+  // arg() returns undefined (not null) for a flag present as the LAST token, so
+  // presence must be tested separately — otherwise `--notes-file` with no path
+  // slips past the null check and resolves to an empty string, which is the very
+  // silent-empty outcome this helper exists to prevent.
+  const filePresent = args.includes(fileFlag) || args.some((a) => a.startsWith(`${fileFlag}=`));
+  const file = filePresent ? arg(fileFlag, args) : null;
+
+  if (inline != null && filePresent) {
+    return {
+      value: '', source: 'none',
+      error: `${name} and ${fileFlag} were both given. Pass one — ${fileFlag} is the safe form for prose `
+        + '(a shell rewrites backticks in an inline value before node sees it). Refusing rather than '
+        + 'silently picking one, so nothing you wrote is dropped without a word.',
+    };
+  }
+  if (filePresent) {
+    if (file == null || file === '' || file.startsWith('--')) {
+      return { value: '', source: 'none', error: `${fileFlag} needs a path (or - for stdin).` };
+    }
+    try {
+      const raw = file === '-' ? readStdin() : readFile(file);
+      return { value: stripBom(String(raw)), source: file === '-' ? 'stdin' : 'file', error: null };
+    } catch (err) {
+      return { value: '', source: 'none', error: `could not read ${fileFlag} ${file}: ${err.message}` };
+    }
+  }
+  if (inline != null) return { value: inline, source: 'inline', error: null };
+  return { value: '', source: 'none', error: null };
+}
+
+// resolveQuiet(args, env) — true when api.js's stderr status banner should be
+// suppressed: the --quiet flag or the GDS_QUIET env var. Both default to the
+// live process, matching hasFlag()'s own default-args contract. Default OFF —
+// existing pipelines that scrape the banner off stderr are unaffected.
+function resolveQuiet(args = process.argv.slice(2), env = process.env) {
+  return hasFlag('--quiet', args) || !!env.GDS_QUIET;
+}
+
+// readSessionToken() — the { token, apiBase } a token-only raw fetch needs, read
+// synchronously from the session file. apiBase resolves the one way every base
+// resolution does — <PREFIX>_API_BASE (incl. legacy GDS_/PMS_) || session.api_base
+// || the branding default — via ic.resolveApiBase, passing the session we already
+// loaded so it needs no second disk read (task 1002427). Returns null when not
+// signed in. Callers that must FAIL OPEN (e.g. the sound player) use this + their
+// own fetch rather than apiCall (which exits on 401).
+function readSessionToken() {
+  const j = loadSessionSync();
+  if (!j || !j.token) return null;
+  return {
+    token: j.token,
+    apiBase: ic.resolveApiBase({ session: j }),
+  };
+}
+
+// Track whether we've already surfaced an auth-broken message this process so
+// repeated calls (e.g. a script that fires several apiCalls in a row) only
+// print the helpful guidance once before exiting.
+let _unauthExitInFlight = false;
+
+function printUnauthGuidanceAndExit() {
+  // Stable, single-screen guidance. Builders should see exactly this when
+  // their CLI session breaks — no raw API JSON, no stack trace.
+  console.error('');
+  console.error('✖ Your Bongos CLI session is no longer valid.');
+  console.error('');
+  if (isTerminalSurface()) {
+    // No checkout here, so `node scripts/bongos/*.js` is not a path this reader has (task 1003730).
+    console.error(`  Recover the fast (UI-first) way — run ${surfaceAction('reauth')}`);
+    console.error('  (opens your Settings page; under "CLI Access" click "Re-issue CLI');
+    console.error('   token", copy the one-liner, paste it back — no terminal Device Flow.)');
+    console.error('  Fallback (browser sign-in): npx bongos login <instance-url>');
+  } else {
+    console.error('  Recover the fast (UI-first) way — run /builder-reauth, or:');
+    console.error('    node scripts/bongos/reauth.js');
+    console.error('  (opens your Settings page; under "CLI Access" click "Re-issue CLI');
+    console.error('   token", copy the one-liner, paste it back — no terminal Device Flow.)');
+    console.error('  Fallback (terminal Device Flow): node scripts/bongos/setup.js --force');
+  }
+  console.error('');
+  console.error('  Possible causes:');
+  console.error('    - Your token was revoked — by you ("Sign out everywhere") or by an Archon');
+  console.error('    - A recent deploy applied an auth-changing migration (see deploy banner)');
+  console.error('    - This instance is older than ADR 0294 and still expires idle CLI sessions');
+  console.error('');
+  console.error('  Once re-authed, re-run whichever command you were trying.');
+  // `doctor` is checkout-only — it is not one of the public CLI's verbs (ADR 0258).
+  if (!isTerminalSurface()) console.error('  For a full diagnosis, run: node scripts/bongos/doctor.js');
+  for (const line of plainCardLines('session_invalid')) console.error(line);
+  console.error('');
+  process.exit(2);
+}
+
+
+// ---- fail-closed instance guard (task 2102) --------------------------------
+// A half-configured instance folder used to fail THROUGH: with no local session
+// for ITS OWN origin, the CLI fell back to whatever instance the machine last
+// signed into (session.api_base, else the prod default) and acted THERE. On
+// 2026-07-08 a fresh `demo` clone (config/branding → demo.cloudbongos.com), with
+// no demo session on the machine, borrowed the founder instance's session
+// and offered to write a task into the wrong LIVE backlog. A wrong-instance write
+// is a data-integrity hazard, so we fail CLOSED: if the session we'd authenticate
+// with belongs to a different instance than THIS repo is configured for, refuse
+// and point at the fix. (Inert for a correctly-signed-in instance — OTB's session
+// api_base and branding publicOrigin share a host, so this never fires there.)
+
+function safeBranding() {
+  try { return require('../../src/branding').branding() || {}; }
+  catch { return {}; }
+}
+
+// True when THIS checkout declares an instance identity — i.e. config/branding.json
+// exists. A NEUTRAL checkout (the portable core, or a fresh template carrying only
+// branding.neutral.json) returns false: its resolved publicOrigin is just the neutral
+// placeholder, not a real declared instance, so there is nothing to enforce a session
+// against. Injectable so the pure guard stays unit-testable. (task 1002399, area 2)
+function defaultHasInstanceConfig() {
+  try {
+    const { INSTANCE_PATH } = require('../../src/branding');
+    return !!(INSTANCE_PATH && fs.existsSync(INSTANCE_PATH));
+  } catch { return false; }
+}
+
+// Host of an origin string, or null if unparseable. Comparing HOSTS (not full
+// origins) tolerates scheme / trailing-slash noise between branding + session.
+function instanceOriginHost(origin) {
+  try { return new URL(String(origin)).host || null; }
+  catch { return null; }
+}
+
+// PURE + exported for tests. Decide whether the session we'd use targets a
+// DIFFERENT instance than this repo is configured for. Fails OPEN (no mismatch)
+// when: an explicit <PREFIX>_API_BASE override is set (dev/staging — the operator
+// is deliberately steering the base); OR there is no session (nothing to borrow —
+// the no-session/401 path handles that); OR this checkout is NEUTRAL (no
+// config/branding.json — no declared instance to enforce, so trust the session:
+// this is what lets a neutral core checkout run every /builder-* command with NO
+// <PREFIX>_API_BASE prefix — task 1002399); OR the repo declares no publicOrigin
+// (unknown identity — you can't assert a mismatch you can't define). Otherwise the
+// mismatch is expectedHost !== sessionHost — the guard that still fires for a
+// BRANDED checkout whose session points at a different instance (the 2026-07-08
+// hazard).
+function detectInstanceMismatch({ session, brand = safeBranding(), env = process.env, hasInstanceConfig = defaultHasInstanceConfig } = {}) {
+  if (ic.resolveEnv('API_BASE', { env })) return { mismatch: false };
+  if (!session || !session.api_base) return { mismatch: false };
+  if (!hasInstanceConfig()) return { mismatch: false };
+  const expected = brand && brand.domains && brand.domains.publicOrigin;
+  if (!expected) return { mismatch: false };
+  const expectedHost = instanceOriginHost(expected);
+  const actualHost = instanceOriginHost(session.api_base);
+  if (!expectedHost || !actualHost) return { mismatch: false };
+  return { mismatch: expectedHost !== actualHost, expected, actual: session.api_base };
+}
+
+let _instanceMismatchExitInFlight = false;
+
+function printInstanceMismatchAndExit({ expected, actual }) {
+  const pfx = ic.envPrefix();
+  console.error('');
+  console.error('✖ Wrong instance — refusing to act.');
+  console.error('  This project is configured for one Cloud Bongos instance, but your signed-in');
+  console.error('  session belongs to a different one. Acting would write to the wrong place, so');
+  console.error('  I stop here (a wrong-instance write is worse than doing nothing).');
+  console.error('');
+  console.error(`    This project (config/branding.json):  ${expected}`);
+  console.error(`    Your session is signed in to:         ${actual}`);
+  console.error('');
+  console.error('  Sign in to THIS instance, then re-run your command:');
+  console.error(`    npx bongos login ${expected}`);
+  console.error(`    (or, from a checkout without the bongos bin:  node scripts/bongos/login.js ${expected})`);
+  console.error('');
+  console.error('  Intentionally targeting another instance? Set the base explicitly, e.g.');
+  console.error(`    ${pfx}_API_BASE=${actual} <your command>`);
+  for (const line of plainCardLines('instance_mismatch')) console.error(line);
+  console.error('');
+  process.exit(3); // 3 = instance mismatch (distinct from 2 = unauth)
+}
+
+// Fail-closed instance guard for RAW-fetch READ commands (task 2124 / demo-audit C2).
+// apiCall + cliClient guard themselves, but a command that reaches the API through its
+// OWN fetch bypasses that — the 2026-07-08 demo hit exactly this: `bongos status` used a
+// raw fetch(API_BASE/…) and happily printed the MAIN instance's progress while sitting in
+// the demo repo, giving false confidence, while the write path correctly refused. Such a
+// command must call this first. Inert when there is no session, when API_BASE is overridden,
+// or when the session's instance matches this repo's branding — it only fires on a genuine
+// wrong-instance session. Reuses the same detector + message as the write-side guard.
+async function assertInstanceMatch({ allowInstanceMismatch = false } = {}) {
+  if (allowInstanceMismatch || _instanceMismatchExitInFlight) return;
+  const session = await loadSession();
+  const mm = detectInstanceMismatch({ session });
+  if (mm.mismatch) {
+    _instanceMismatchExitInFlight = true;
+    printInstanceMismatchAndExit(mm);
+  }
+}
+
+/**
+ * Make an authenticated request to the GDS API.
+ *
+ * Default behavior on HTTP 401: print clear actionable guidance and exit(2).
+ * Callers can opt out by passing { allowUnauthenticated: true } when 401 is a
+ * legitimate response they want to handle (e.g. setup.js pre-flighting /me to
+ * decide whether to re-auth automatically).
+ */
+async function apiCall(method, urlPath, body = null, opts = {}) {
+  const { allowUnauthenticated = false, allowInstanceMismatch = false } = opts;
+  const session = await loadSession();
+  // Fail CLOSED (task 2102) if the session we'd authenticate with belongs to a
+  // different instance than this repo is configured for — never silently borrow
+  // another instance's credentials. Opt out with { allowInstanceMismatch: true }
+  // for a deliberate cross-instance caller (login.js talks to other instances via
+  // its own fetch, so it never reaches here).
+  if (!allowInstanceMismatch && !_instanceMismatchExitInFlight) {
+    const mm = detectInstanceMismatch({ session });
+    if (mm.mismatch) {
+      _instanceMismatchExitInFlight = true;
+      printInstanceMismatchAndExit(mm);
+    }
+  }
+  // Instance-agnostic base (V4.R83 / task 1250): `bongos login <instance>` writes
+  // that instance's origin to session.api_base, so every later command targets it.
+  // Precedence mirrors readSessionToken: an explicit <PREFIX>_API_BASE env wins
+  // (local dev / staging override), then the logged-in instance, then prod. OTB
+  // sessions already store the founder instance's api_base, so this is a no-op
+  // for the OTB instance and only bites once someone logs in to a different one.
+  const base = ic.resolveApiBase({ session: session || null });
+  const headers = {
+    'Content-Type': 'application/json',
+    'User-Agent': CLI_USER_AGENT,
+  };
+  if (session && session.token) {
+    headers['Authorization'] = `Bearer ${session.token}`;
+  }
+  // The Anthropic-identity pin was removed (task 1039, idea 258): we no longer
+  // send X-Anthropic-User, because the server no longer cross-checks it. The
+  // reward is a uniform server-side valuation (ADR 0054), not per-Anthropic-
+  // account billing, so identity is not an auth boundary. anthropic_user_id is
+  // still kept in the session as cosmetic attribution; it is simply not
+  // transmitted as a header.
+  // opts.rawBody (a Buffer) + opts.contentType send bytes instead of JSON — a
+  // UAT recording upload (task 1004392), whose route reads a raw video body.
+  if (opts.rawBody) headers['Content-Type'] = opts.contentType || 'application/octet-stream';
+  const res = await dispatchedFetch(`${base}${urlPath}`, {
+    method,
+    headers,
+    body: opts.rawBody ? opts.rawBody : (body ? JSON.stringify(body) : null),
+    dispatcher: noKeepAliveDispatcher(),
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch (_) {
+    data = { raw: text };
+  }
+  if (res.status === 401 && !allowUnauthenticated && !_unauthExitInFlight) {
+    _unauthExitInFlight = true;
+    printUnauthGuidanceAndExit();
+  }
+  return { status: res.status, ok: res.ok, data };
+}
+
+// task 1996 (R09): the ONE HTTP client. cliClient() returns the generated typed
+// client (clients/bongos-client — ADR 0118) configured for the CLI:
+//   • baseUrl  — the session-resolved instance origin + the versioned API prefix
+//                (/api/bongos/v1), so paths are the spec-relative /tasks/… form.
+//   • token    — the session bearer.
+//   • throwOnError:false — every call resolves to { status, ok, data } (never
+//     throws on HTTP status; network errors still reject), so the long-standing
+//     apiCall contract holds and status-inspecting callers port 1:1.
+//   • fetch    — a wrapper that keeps apiCall's behavior: the founder CLI
+//     User-Agent, plus the 401 auto-exit guidance.
+// Named methods (api.tasks.getTasksId({ id })) replace hand-built apiCall paths;
+// api.request(method, path, opts) is the escape hatch for non-spec routes.
+// The generated client is ESM; we import() it once and cache per (base, token,
+// opts) — CommonJS callers just `const api = await cliClient()`.
+let _clientModPromise = null;
+const _clientCache = new Map();
+
+// Generate the typed client into this core's own root when it is missing (task 1004866:
+// gitignored; a fresh clone has no copy). Only when MISSING: an installed core ships its
+// packaged copy and may sit on a read-only path, and a dev checkout's copy is refreshed by
+// `node scripts/bongos/api-artifacts.js`. A failure is left to the import below to report.
+function ensureCliClientFile({ root = path.resolve(__dirname, '..', '..'), exists = fs.existsSync, ensure } = {}) {
+  if (exists(path.join(root, 'clients', 'bongos-client', 'index.mjs'))) return false;
+  try {
+    (ensure || require('./api-artifacts.js').ensureApiArtifacts)({ root });
+    return true;
+  } catch (e) {
+    console.error(`bongos: could not generate the API client (${e.message}) — run \`node scripts/bongos/api-artifacts.js\`.`);
+    return false;
+  }
+}
+async function cliClient(opts = {}) {
+  const { allowUnauthenticated = false, allowInstanceMismatch = false } = opts;
+  const session = await loadSession();
+  // Fail CLOSED (task 2102) — the same guard as apiCall, on the OTHER HTTP entry
+  // point. cliClient() is the typed client (api.js + newer scripts route through
+  // it), and it resolves the base identically, so it can silently target the wrong
+  // instance too. Guard both, or the hole just moves. Opt out with
+  // { allowInstanceMismatch: true } for a deliberate cross-instance caller.
+  if (!allowInstanceMismatch && !_instanceMismatchExitInFlight) {
+    const mm = detectInstanceMismatch({ session });
+    if (mm.mismatch) {
+      _instanceMismatchExitInFlight = true;
+      printInstanceMismatchAndExit(mm);
+    }
+  }
+  const base = ic.resolveApiBase({ session: session || null });
+  const token = (session && session.token) || null;
+  const key = `${base}|${token || ''}|${allowUnauthenticated}`;
+  if (_clientCache.has(key)) return _clientCache.get(key);
+  if (!_clientModPromise) {
+    // task 1004866: the client is gitignored, so a fresh core checkout has none until it
+    // is generated (an installed core carries it — package-core packs it). Build it from
+    // the routes into the core root first; a no-op when it is already current.
+    ensureCliClientFile();
+    _clientModPromise = import('../../clients/bongos-client/index.mjs');
+  }
+  const { createClient } = await _clientModPromise;
+  const authedFetch = async (url, init) => {
+    init = init || {};
+    init.headers = Object.assign({ 'User-Agent': CLI_USER_AGENT }, init.headers);
+    if (init.dispatcher === undefined) init.dispatcher = noKeepAliveDispatcher();
+    const res = await dispatchedFetch(url, init);
+    if (res.status === 401 && !allowUnauthenticated && !_unauthExitInFlight) {
+      _unauthExitInFlight = true;
+      printUnauthGuidanceAndExit();
+    }
+    return res;
+  };
+  const client = createClient({ baseUrl: `${base}/api/bongos/v1`, token, fetch: authedFetch, throwOnError: false });
+  _clientCache.set(key, client);
+  return client;
+}
+
+async function requireSession() {
+  const s = await loadSession();
+  if (!s || !s.token) {
+    console.error(`No Bongos session found at ${SESSION_PATH}.`);
+    console.error(`You're not signed in yet — pick the line that fits:`);
+    if (isTerminalSurface()) {
+      // A terminal reader may have no instance configured at all — naming one is the whole point
+      // of `login`, and `/builder-*` does not exist outside a Claude Code session (task 1003730).
+      console.error(`  • First time here            → run npx bongos login <instance-url>  (sign in with a browser click)`);
+      console.error(`  • Signed in before / expired → run npx bongos reauth                (re-issue your CLI token)`);
+    } else {
+      console.error(`  • First time on the project  → run /builder-setup   (one-time GitHub sign-in that also registers you)`);
+      console.error(`  • Signed in before / expired → run /builder-reauth  (fast UI re-issue of your CLI token)`);
+    }
+    for (const line of plainCardLines('no_session')) console.error(line);
+    process.exit(2);
+  }
+  return s;
+}
+
+// -------------------------------------------------------------------------
+// Output helpers (text, structured for the slash command to relay)
+// -------------------------------------------------------------------------
+
+function fmtMinutes(m) {
+  if (m == null) return '—';
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  const rem = m % 60;
+  return rem ? `${h}h${rem}m` : `${h}h`;
+}
+
+function fmtUsd(n) {
+  if (n == null) return '—';
+  return `$${Number(n).toFixed(2)}`;
+}
+
+function fmtTouches(arr) {
+  if (!arr || arr.length === 0) return '—';
+  if (arr.length <= 3) return arr.join(', ');
+  return `${arr.slice(0, 3).join(', ')} +${arr.length - 3}`;
+}
+
+// Estimate display: prefer the calibrated minutes (per-kind median × raw est).
+// When calibration differs meaningfully from the raw input we show both as
+// `~5m (raw 90m)` so the gap is visible. When raw == calibrated (small task,
+// no historical data, or differs by <20%) we collapse to a single number.
+// Migration 015 added est_minutes_calibrated to /tasks/claimable + getTask.
+function fmtEstimate(t) {
+  const raw = t.est_minutes;
+  const cal = t.est_minutes_calibrated;
+  if (cal == null) return fmtMinutes(raw);
+  if (raw == null || raw === cal) return fmtMinutes(cal);
+  const diff = Math.abs(cal - raw) / raw;
+  if (diff < 0.2) return fmtMinutes(cal);
+  return `~${fmtMinutes(cal)} (raw ${fmtMinutes(raw)})`;
+}
+
+function tableTask(t) {
+  // Version chip — eg `[V1]` / `[PMS-V2]`.
+  const versionChip = `[${t.version_id}]`;
+  return [
+    `#${t.id}`,
+    versionChip,
+    `P${t.priority ?? '?'}`,
+    fmtEstimate(t),
+    `${fmtUsd(t.est_cost_usd)}`,
+    `M${t.manual_degree ?? '?'}`,
+    `${t.credits_reward ?? 0}c`,
+    t.automation_tag ? `[${t.automation_tag}]` : '',
+    t.title,
+  ]
+    .filter(Boolean)
+    .join('  ');
+}
+
+// -------------------------------------------------------------------------
+// Free-text session-request parser
+// -------------------------------------------------------------------------
+//
+// Pure function. Returns { timeBudgetMin, mode, parallel } where each field
+// may be null if not detected. Returns null when *no* fields parsed (so the
+// CLI can fall through to the interactive prompt).
+//
+// Time:     \d+\s*(h|hr|hrs|hour|hours|min|m|minutes?)
+// Mode:     overnight|autonomous|async      → 'autonomous'
+//           active|focused                  → 'active'
+//           check[\s-]?in|intermittent      → 'check-in'
+// Parallel: parallel\s*\d+, \d+\s*sessions?, max\s*\d+
+
+// V3.R13 (#237): one-line "next: <stage>" nudge for newcomers.
+//
+// Given the /api/bongos/me response, print a banner pointing at the next
+// uncleared onboarding stage. Silent when the builder has graduated or has
+// already cleared first_ship (the post-newcomer threshold) — gates lift
+// after the first ship, so the nudge is too. Also silent when the
+// onboarding payload is missing (older API, network glitch) — we'd rather
+// say nothing than print noise.
+//
+// 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/bongos/surface.js (task 1003680). Fail-open: a missing surface module must
+// never break a nudge.
+//
+// Both helpers are `function` declarations so they hoist — the guidance printers above (which run
+// far earlier in the file) call them, and moving them up would churn the nudge block they belong to.
+function surfaceAction(verb, arg) {
+  try { return require('./surface').action(verb, arg); }
+  catch (_) { return `/builder-${verb}${arg == null ? '' : ` ${arg}`}`; }
+}
+
+// Is a person at a console reading this, rather than a Claude Code session? Fails open to AGENT,
+// so a missing/broken surface module leaves the agent contract byte-identical (task 1003730).
+function isTerminalSurface() {
+  try { return require('./surface').isTerminal(); }
+  catch (_) { return false; }
+}
+
+// The same refusal in plain words, for an agent to relay (task 1003989). Same fail-open
+// shape as the two helpers above: a guidance printer must never die on its own footnote.
+function plainCardLines(code) {
+  try { return require('./plain-cards').plainCardLines(code); }
+  catch (_) { return []; }
+}
+
+function nudgeActionForStage(stage) {
+  switch (stage) {
+    case 'auth_complete':
+      return 'Run node scripts/bongos/setup.js to authenticate.';
+    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 ${surfaceAction('start')} to survey what you can claim.`;
+    case 'first_claim':
+      return `Pick a task from ${surfaceAction('start')} and claim it with ${surfaceAction('claim', 'N')}.`;
+    case 'ship_three':
+      return `Carry three tasks through with ${surfaceAction('ship')} — the third makes you a Thetes.`;
+    default:
+      return null;
+  }
+}
+
+function printOnboardingNudge(meBody) {
+  if (!meBody || typeof meBody !== 'object') return;
+  const onboarding = meBody.onboarding;
+  if (!onboarding || typeof onboarding !== 'object') return;
+  if (onboarding.graduated) return;
+  const cleared = new Set(Array.isArray(onboarding.completed_stages) ? onboarding.completed_stages : []);
+  // Reached the ship-three milestone (= graduated to Thetes): no further nagging.
+  if (cleared.has('ship_three')) return;
+  const stage = onboarding.current_stage;
+  if (!stage || stage === 'graduated') return;
+  const action = nudgeActionForStage(stage);
+  if (!action) return;
+  // Use a recognizable prefix so the slash command and any UI surface can
+  // detect/strip the line if needed. Ascii-only — these scripts must work
+  // in low-fidelity terminals.
+  const stages = Array.isArray(onboarding.stages) ? onboarding.stages : [];
+  const stageMeta = stages.find((s) => s.id === stage);
+  const label = (stageMeta && stageMeta.label) || stage;
+  console.log(`Next: ${label} — ${action}`);
+}
+
+// V3.R84 (#302), criterion C3: the CLI-side budget "ping". Prints a prominent
+// soft-cap (warn) or hard-cap (over) line from the /me `cost` object. The CLI is
+// the builder's private surface, so this is where the budget warning reaches
+// them — not Discord (shared mirror). No-op when under budget or when the server
+// didn't return a cost status (older deploy / read error → fail-quiet).
+function printCostWarning(meBody) {
+  const cost = meBody && meBody.cost;
+  if (!cost || typeof cost !== 'object') return;
+  if (cost.level === 'over') {
+    console.log(`⚠ BUDGET EXCEEDED — $${cost.spend_mtd_usd} of $${cost.budget_mtd_usd} this month (${cost.pct_used}%). Cost-incurring actions (ship, art pipeline) are blocked until a Metic or Archon raises your budget.`);
+  } else if (cost.level === 'warn') {
+    console.log(`⚠ Budget at ${cost.pct_used}% — $${cost.spend_mtd_usd} of $${cost.budget_mtd_usd} this month. You'll be blocked from cost-incurring actions at 100%.`);
+  }
+}
+
+// task 1013 / ADR 0073: the CLI half of the consistent "the system needs an input
+// from you" signal. Given the /api/bongos/me response, print a short line for each
+// `needs` item in the action_needed state — the builder's private surface is the
+// right place to tell them an input is missing (mirrors printCostWarning). Silent
+// when nothing needs action (covered / satisfied items don't nag) or when the
+// payload is absent (older API / network glitch). One line per item, with the
+// concrete place to fix it. The hall Standing card renders the same `needs` data.
+const HALL_BASE = hallBase();
+function printNeedsNudge(meBody) {
+  if (!meBody || typeof meBody !== 'object') return;
+  const needs = meBody.needs;
+  if (!needs || !Array.isArray(needs.items)) return;
+  const action = needs.items.filter((n) => n && n.state === 'action_needed');
+  if (action.length === 0) return;
+  const noun = action.length === 1 ? 'thing needs' : 'things need';
+  console.log(`⚠ ${action.length} ${noun} your input:`);
+  for (const n of action) {
+    const where = n.action && n.action.href ? ` — ${HALL_BASE}${n.action.href}` : '';
+    console.log(`  • ${n.title}: ${n.message}${where}`);
+  }
+}
+
+function parseSessionRequest(text) {
+  if (!text || typeof text !== 'string') return null;
+  const s = text.toLowerCase();
+
+  let timeBudgetMin = null;
+  let mode = null;
+  let parallel = null;
+
+  // Parallel — try the most specific patterns first so a "3 sessions" form
+  // doesn't get clobbered by an earlier "\d+\s*h" match on the same digits.
+  let mParallel =
+    s.match(/parallel\s*[:=]?\s*(\d+)/) ||
+    s.match(/(\d+)\s*sessions?\b/) ||
+    s.match(/max\s*[:=]?\s*(\d+)/);
+  if (mParallel) parallel = Number(mParallel[1]);
+
+  // Time — accept hours and minutes in any combination ("6h", "90 min",
+  // "1 hour", "2hr30min"). Sum them. (?![a-z]) instead of \b so digit-suffix
+  // compounds like "2hr30min" still match the hour group.
+  const hourRe = /(\d+)\s*(hours|hour|hrs|hr|h)(?![a-z])/g;
+  const minRe = /(\d+)\s*(minutes|minute|min|m)(?![a-z])/g;
+  let total = 0;
+  let matched = false;
+  // Hours pass first.
+  let m;
+  while ((m = hourRe.exec(s)) !== null) {
+    total += Number(m[1]) * 60;
+    matched = true;
+  }
+  // Minutes pass — but only count "m" alone if it's not eaten by hour.
+  // Strip already-matched hour spans so "2hr30min" doesn't double-count.
+  let minSearch = s.replace(hourRe, ' ');
+  while ((m = minRe.exec(minSearch)) !== null) {
+    total += Number(m[1]);
+    matched = true;
+  }
+  if (matched) timeBudgetMin = total;
+
+  // Mode — most-specific wins. check-in patterns first because they overlap
+  // with nothing; then autonomous (overnight/async), then active.
+  if (/\bcheck[\s-]?in\b|\bintermittent\b/.test(s)) {
+    mode = 'check-in';
+  } else if (/\bovernight\b|\bautonomous\b|\basync\b/.test(s)) {
+    mode = 'autonomous';
+  } else if (/\bactive\b|\bfocused\b/.test(s)) {
+    mode = 'active';
+  }
+
+  if (timeBudgetMin == null && mode == null && parallel == null) return null;
+  return { timeBudgetMin, mode, parallel };
+}
+
+// task 1002809: Git Bash (MSYS) rewrites a leading-slash argument into a Windows
+// path under the Git install root BEFORE node sees it — `/tasks/123` arrives as
+// `C:/Program Files/Git/tasks/123` — unless the builder remembers
+// MSYS_NO_PATHCONV=1. Undo it here so no one needs the env prefix. EXEPATH (set
+// by Git Bash) points INSIDE the install (`…\Git\bin`), while the mangled prefix
+// is the install root (`…\Git`), so we strip the LONGEST ancestor of EXEPATH
+// that prefixes the arg — never the bare drive root (that would "repair"
+// arbitrary Windows paths). Case-insensitive, both slash styles. Pure + exported
+// for tests/api_msys_path_repair.mjs; no-op off win32 or without EXEPATH.
+function repairMsysMangledPath(raw, { exepath = process.env.EXEPATH, platform = process.platform } = {}) {
+  if (!raw || raw.startsWith('/')) return raw;
+  if (platform !== 'win32' || !exepath) return raw;
+  const rawFwd = String(raw).replace(/\\/g, '/');
+  const rawLower = rawFwd.toLowerCase();
+  let ancestor = String(exepath).replace(/\\/g, '/').replace(/\/+$/, '');
+  let best = null;
+  while (ancestor.includes('/')) {
+    // Stop before the bare drive root ("C:" after the last slice).
+    if (/^[a-z]:$/i.test(ancestor)) break;
+    if (rawLower.startsWith(ancestor.toLowerCase() + '/') && (best === null || ancestor.length > best.length)) {
+      best = ancestor;
+    }
+    ancestor = ancestor.slice(0, ancestor.lastIndexOf('/'));
+  }
+  if (best === null) return raw;
+  return rawFwd.slice(best.length);
+}
+
+// detectWorktreeName — which linked git worktree is this process running in?
+// Moved here from claim.js in task 1003767 so the CLAIM and the RESOLVE agree on
+// one answer: the server keys both the one-active-claim guard and (now) the
+// resolve lock on the WORKING TREE rather than the shared auth session, and two
+// copies of this detector drifting apart would strand a ship with a name
+// mismatch. One definition, both callers.
+//
+// Only names a LINKED worktree — git-dir != git-common-dir, i.e. a real
+// `.claude/worktrees/<name>` checkout — using its top-level directory basename
+// (the `<name>` the convention already uses). The MAIN checkout returns null,
+// which the server reads as "no tree named" and falls back to the session
+// compare. Best-effort: any git hiccup yields null, so this can never break a
+// claim or a ship.
+function detectWorktreeName() {
+  try {
+    const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+    const commonDir = execSync('git rev-parse --git-common-dir', { encoding: 'utf8' }).trim();
+    // Same dir → the main checkout, not a linked worktree → leave unnamed.
+    if (path.resolve(gitDir) === path.resolve(commonDir)) return null;
+    const top = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+    const name = path.basename(top);
+    return name || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---- card richness (task 1002518) ------------------------------------------
+//
+// The one place a CLI turns a /me payload into "what should this card look
+// like": three booleans — print the card at all, write the widget, open its
+// summary — that emitCard consumes directly.
+//
+// WHY THIS READS THE PAYLOAD AND NEVER require()s render-prefs.js. The ladder
+// lives in modules/builder-settings/render-prefs.js, and a CLI reaches a
+// module's logic through the server, never by require — the module may be
+// disabled on the instance, and a require would couple every CLI to one
+// module's internals. So the server resolves the rung and ships the answers on
+// `render.flags`; this function only picks them up.
+//
+// TWO SERVER SHAPES, deliberately. `render.flags` is the ladder (task 1002518);
+// `render.widgets_enabled` is the boolean that predates it. A CLI newer than the
+// instance it is pointed at sees only the boolean — the /me payload is not
+// version-negotiated — so the fallback is not defensive padding, it is the
+// supported path against a pinned instance, and it reconstructs exactly what
+// that boolean has always meant: card always, widget iff true, never expanded.
+// An absent or failed /me lands on the same default.
+function cardFlagsFromMe(me) {
+  const render = me && me.data && me.data.render;
+  const f = render && render.flags;
+  if (f && typeof f === 'object') {
+    return {
+      level: typeof f.level === 'string' ? f.level : null,
+      showCard: f.showCard !== false,
+      showWidget: f.showWidget === true,
+      expanded: f.expanded === true,
+    };
+  }
+  const enabled = !render || render.widgets_enabled !== false;
+  return { level: null, showCard: true, showWidget: enabled, expanded: false };
+}
+
+// ---------------------------------------------------------------------------
+// errCode — read the error slug out of an ADR 0116 response envelope.
+// ---------------------------------------------------------------------------
+// ADR 0116 standardised every failure on a NESTED envelope:
+//
+//     { "error": { "code": "task_not_found", "message": "…", "details": … } }
+//
+// so the obvious-looking `r.data.error === 'task_not_found'` compares an OBJECT to a
+// STRING and is never true. That is not a cosmetic bug: each such comparison guards a
+// helpful, specific message, so against a live server every one of those branches is
+// unreachable and the user falls through to the raw `(409): [object Object]` dump —
+// the failure looks like a tooling crash rather than the clear refusal the server sent.
+//
+// Verified live 2026-09-22 against cloudbongos.com:
+//     POST /api/bongos/tasks/1003846/abandon
+//     -> 409 {"error":{"code":"cannot_abandon_shipped","message":"shipped tasks are immutable history"}}
+//
+// The flat-string fallback is deliberate, not defensive padding: some older routes and
+// every non-envelope transport error (a proxy's plain-text body, a pre-0116 instance an
+// upgraded CLI is talking to) still surface `error` as a bare string. Reading both is
+// what makes one helper safe to use everywhere.
+//
+// Fixed in ship.js under task 1002789; extracted here under task 1003658 so the next
+// caller cannot reintroduce the same comparison. Pure — tests/cli_err_code.mjs.
+function errCode(data) {
+  const e = data && data.error;
+  if (typeof e === 'string') return e;
+  if (e && typeof e === 'object' && typeof e.code === 'string') return e.code;
+  return null;
+}
+
+// errDetails — the structured payload beside the slug, same envelope.
+//
+// This matters as much as errCode and is easy to miss: the sibling fields moved WITH
+// the code. demote.js printed `r.data.current_status` beside its message; ADR 0116 put
+// that at `error.details.current_status`, so a fix that changed only the comparison
+// would have restored the branch and then printed "it is 'undefined', not 'ready'" —
+// a half-fix that looks like a whole one. Verified live 2026-09-22:
+//
+//     POST /api/bongos/tasks/1003846/demote
+//     -> 409 {"error":{"code":"cannot_demote","details":{"current_status":"shipped"}}}
+//
+// Falls back to the top-level body so a pre-0116 flat response still resolves.
+function errDetails(data) {
+  const e = data && data.error;
+  if (e && typeof e === 'object' && e.details && typeof e.details === 'object') return e.details;
+  return (data && typeof data === 'object') ? data : {};
+}
+
+module.exports = {
+  errCode,
+  errDetails,
+  API_BASE,
+  detectWorktreeName,
+  hallBase,
+  productName,
+  rewardPolicy,
+  costPlusOnlyNote,
+  SESSION_PATH,
+  SESSION_FILENAMES,
+  SESSION_READ_PATHS,
+  loadSession,
+  loadSessionSync,
+  saveSession,
+  sessionStoreDir,
+  sessionHostKey,
+  sessionStorePath,
+  loadStoredSession,
+  listStoredSessions,
+  arg,
+  argText,
+  hasFlag,
+  stripBom,
+  repairMsysMangledPath,
+  resolveQuiet,
+  readSessionToken,
+  CLI_USER_AGENT,
+  apiCall,
+  cliExit,
+  isDispatcherIncompatError,
+  dispatchedFetch,
+  noKeepAliveDispatcher,
+  _noKeepAliveResetForTest,
+  cliClient,
+  ensureCliClientFile,
+  requireSession,
+  surfaceAction,
+  isTerminalSurface,
+  printUnauthGuidanceAndExit,
+  detectInstanceMismatch,
+  assertInstanceMatch,
+  instanceOriginHost,
+  fmtMinutes,
+  fmtUsd,
+  fmtTouches,
+  fmtEstimate,
+  tableTask,
+  parseSessionRequest,
+  printOnboardingNudge,
+  printCostWarning,
+  printNeedsNudge,
+  cardFlagsFromMe,
+};