@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/install-git-hooks.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// scripts/bongos/install-git-hooks.js — activate the project's git hooks (SEC #863).
+//
+// The hooks are TRACKED, committed files under .husky/ — this repo ships
+// .husky/pre-push (the ADR 0043 Layer 1 permission gate, task 1002608); an
+// instance may add more (e.g. a pre-commit secrets guard). Git only runs them
+// when the clone has core.hooksPath pointed at .husky — easy to forget, which
+// means a builder could run with NO push gate.
+//
+// This script makes activation automatic (called by /builder-setup). It does
+// NOT write any hook file — the hooks ship via git. It only ensures
+// core.hooksPath is set so whatever hooks .husky/ tracks actually fire.
+//
+// Idempotent and cross-platform. Runnable standalone:
+//   node scripts/bongos/install-git-hooks.js
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync, execFileSync } = require('node:child_process');
+
+function git(args) {
+  return execSync(`git ${args}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+// The regenerating merge driver declared in .gitattributes (task 1243). Without
+// this per-clone config, git ignores the `merge=otb-regen` attribute and falls back
+// to a normal conflict — so registering it here is what makes `git merge` auto-heal
+// the generated files (docs/repo-map.md + the nested CLAUDE.md blocks).
+const MERGE_DRIVER_NAME = 'otb-regen';
+
+// ORDER MATTERS, and the wrong order is worse than not registering at all (task 1003846).
+//
+// These are two git-config writes, not one atomic operation. If the first succeeds and
+// the second throws, the half-written section SURVIVES — and git does not treat a named
+// driver with no command as "fall back to a text merge". It treats it as fatal:
+//
+//     fatal: custom merge driver otb-regen lacks command line.
+//
+// exit 128, no unmerged paths, nothing that looks like a merge conflict. Every merge
+// touching any `merge=otb-regen` path then dies — which is now the root CLAUDE.md, the
+// file/session-log maps, two nested CLAUDE.md files, the copy-registry pair and the nine
+// generated API artifacts. So the failure mode of the old order was "no merge in this
+// clone can complete", where not registering at all merely yields an ordinary conflict.
+//
+// Both halves of the fix are verified, not assumed (see tests/merge_driver_register.mjs):
+//   - `.driver` alone IS a valid section — git runs it and the merge succeeds.
+//   - `.name` alone is the fatal state above.
+// So writing `.driver` FIRST makes the intermediate state safe, and removing the whole
+// section on failure makes even a mid-write abort leave no trace.
+//
+// `driverScript` (task 1003368, audit B2) pins the command to an ABSOLUTE path. The default
+// is the RELATIVE `scripts/bongos/git-merge-regen.js`, which git resolves against the merge's
+// cwd — the checked-out tree — so on a clone of a builder's branch it names the BRANCH's copy
+// of the script. The server's conflict resolver passes its own checkout's copy so the command
+// git runs is never one the branch could have written. Only the server-side caller may pass
+// it; a builder's own clone keeps the relative form, which is what they want to run.
+function mergeDriverCommand(driverScript) {
+  if (!driverScript) return 'node scripts/bongos/git-merge-regen.js %O %A %B %P';
+  // Forward slashes + double quotes: git hands this to `sh -c`, and a path with spaces or a
+  // Windows backslash would otherwise split or be eaten as an escape.
+  const abs = path.resolve(driverScript).replace(/\\/g, '/');
+  if (/["$`]/.test(abs)) throw new Error(`unsafe merge driver path: ${abs}`);
+  return `node "${abs}" %O %A %B %P`;
+}
+
+function registerMergeDriver(root, { run = execFileSync, driverScript } = {}) {
+  // execFileSync (arg array, no shell) so the literal %O/%A/%B/%P placeholders and
+  // the spaces in the command survive verbatim on every platform (a shell would
+  // mangle %VARS on Windows cmd).
+  try {
+    // .driver FIRST — a section carrying only .driver is valid and works.
+    run('git', ['config', `merge.${MERGE_DRIVER_NAME}.driver`,
+      mergeDriverCommand(driverScript)], { cwd: root, stdio: 'ignore' });
+    // .name SECOND — cosmetic (it is what `git config --list` shows); if this throws,
+    // the section left behind is the safe driver-only one.
+    run('git', ['config', `merge.${MERGE_DRIVER_NAME}.name`,
+      `${require('./cli-lib').productName()} generated-file regenerator (task 1243)`], { cwd: root, stdio: 'ignore' });
+    return { ok: true };
+  } catch (e) {
+    // Belt and braces: leave NO trace rather than a possibly-partial section. A missing
+    // section is a normal textual conflict; a partial one can be the exit-128 wedge.
+    // This removal is itself best-effort — if it throws (e.g. no section to remove, which
+    // git reports as an error) the original failure is still what we report.
+    try {
+      run('git', ['config', '--remove-section', `merge.${MERGE_DRIVER_NAME}`], { cwd: root, stdio: 'ignore' });
+    } catch (_) { /* nothing to clean up, or we cannot — report the original failure */ }
+    return { ok: false, error: e.message };
+  }
+}
+
+// The doctor-facing verdict for an already-registered driver, pure so it is testable
+// without a git repo (the classifyHooksState precedent in doctor.js).
+//
+// The wedge state is INVISIBLE until the next merge dies, which is exactly why doctor
+// should say so: a builder who hits `fatal: custom merge driver ... lacks command line`
+// has no reason to connect it to a setup step that ran days earlier.
+function classifyMergeDriverState({ name, driver }) {
+  const hasName = Boolean(name && String(name).trim());
+  const hasDriver = Boolean(driver && String(driver).trim());
+  const installer = 'node scripts/bongos/install-git-hooks.js';
+
+  if (hasDriver) {
+    return {
+      status: 'ok',
+      code: 'registered',
+      message: `merge driver '${MERGE_DRIVER_NAME}' registered — generated-file conflicts auto-regenerate on merge.`,
+    };
+  }
+  if (hasName) {
+    return {
+      status: 'fail',
+      code: 'name-without-driver',
+      message:
+        `merge.${MERGE_DRIVER_NAME}.name is set but .driver is MISSING. Git treats this as fatal, not as a `
+        + `fallback: every merge touching a \`merge=${MERGE_DRIVER_NAME}\` path will die with `
+        + `"fatal: custom merge driver ${MERGE_DRIVER_NAME} lacks command line" (exit 128, no conflict shown). `
+        + `Repair with: ${installer}  — or clear it with: git config --remove-section merge.${MERGE_DRIVER_NAME}`,
+    };
+  }
+  return {
+    status: 'warn',
+    code: 'unregistered',
+    message:
+      `merge driver '${MERGE_DRIVER_NAME}' is not registered, so generated-file merges will raise ordinary `
+      + `text conflicts instead of auto-regenerating (ship.js still self-heals). Register with: ${installer}`,
+  };
+}
+
+// Resolve the configured hooks dir (absolute) for reporting / verification.
+function configuredHooksDir() {
+  try {
+    const rel = git('rev-parse --git-path hooks');
+    const root = git('rev-parse --show-toplevel');
+    return path.isAbsolute(rel) ? rel : path.join(root, rel);
+  } catch (_) {
+    return null;
+  }
+}
+
+function activate() {
+  const root = git('rev-parse --show-toplevel');
+  const huskyDir = path.join(root, '.husky');
+  if (!fs.existsSync(huskyDir)) {
+    return { status: 'no-husky-dir',
+      message: `.husky/ not found at ${huskyDir}; nothing to activate (older checkout?).` };
+  }
+
+  // Always (re)register the regenerating merge driver — idempotent, and existing
+  // clones pick it up on any re-run of this script.
+  const mergeDriver = registerMergeDriver(root);
+
+  const hooks = fs.readdirSync(huskyDir).filter((f) => !f.startsWith('.') && !f.startsWith('_'));
+
+  let current = '';
+  try { current = git('config --get core.hooksPath'); } catch (_) { current = ''; }
+
+  // Already pointed at a .husky dir (relative or absolute) → leave it; both the
+  // tracked pre-commit and pre-push live there. Don't fight an operator who set
+  // an absolute path on purpose (e.g. to share hooks across worktrees).
+  const points = configuredHooksDir();
+  const alreadyHusky = current && points && path.basename(points) === '.husky';
+  if (alreadyHusky) {
+    return { status: 'already-active', hooksPath: current, dir: points, mergeDriver, hooks };
+  }
+
+  // Not set (or set elsewhere): activate the project hooks. Relative '.husky'
+  // is husky-standard and resolves per-worktree.
+  git('config core.hooksPath .husky');
+  return { status: 'activated', hooksPath: '.husky', dir: huskyDir, mergeDriver, hooks };
+}
+
+if (require.main === module) {
+  try {
+    const r = activate();
+    if (r.status === 'no-husky-dir') {
+      console.error(`⚠ ${r.message}`);
+      process.exit(0);
+    }
+    const live = (r.hooks && r.hooks.length) ? r.hooks.join(', ') : 'none tracked';
+    if (r.status === 'already-active') {
+      console.log(`✓ git hooks already active (core.hooksPath=${r.hooksPath}); live hooks: ${live}`);
+    } else {
+      console.log(`✓ git hooks activated (core.hooksPath=.husky); live hooks: ${live}`);
+    }
+    if (r.mergeDriver && r.mergeDriver.ok) {
+      console.log(`✓ merge driver '${MERGE_DRIVER_NAME}' registered; generated-file conflicts (docs/repo-map.md, nested CLAUDE.md) auto-regenerate on merge`);
+    } else if (r.mergeDriver) {
+      console.error(`⚠ could not register the '${MERGE_DRIVER_NAME}' merge driver: ${r.mergeDriver.error} (generated-file merges will conflict normally; ship.js still self-heals)`);
+    }
+    process.exit(0);
+  } catch (e) {
+    // Never let activation fail a setup hard — warn and move on.
+    console.error(`⚠ could not activate git hooks: ${e.message} (you can run: git config core.hooksPath .husky)`);
+    process.exit(0);
+  }
+}
+
+module.exports = { activate, classifyMergeDriverState, configuredHooksDir, registerMergeDriver, MERGE_DRIVER_NAME };

package/scripts/bongos/instance-apex.js

@@ -0,0 +1,38 @@
+'use strict';
+// instance-apex.js — the instance's own registrable apex + the addresses derived
+// from it, read from its branding pack (task 1002757).
+//
+// WHY THIS EXISTS. Operator-plane defaults used to carry the founder's apex as a
+// literal (box DNS zones, the Cloudflare zone, the provisioner's git identity),
+// so another operator's fleet pointed at the founder's DNS and its commits were
+// attributed to the hub. These resolvers return NULL rather than guessing when the
+// pack names no public origin: every caller treats null as "not configured" and
+// refuses, which fails loudly instead of minting an unreachable host.
+function instanceApex() {
+  try {
+    const host = new URL(require('../../src/branding').branding().domains.publicOrigin).hostname;
+    return host && !/^localhost$/i.test(host) ? host : null;
+  } catch { return null; }
+}
+
+// The git identity a provisioner commits scaffold/pin changes as: explicit env →
+// bot@<instance apex> → a neutral, deliberately-undeliverable platform address
+// (never a live inbox by accident).
+function provisionerBotEmail(env = process.env) {
+  const explicit = String(env.PROVISION_BOT_EMAIL || '').trim();
+  if (explicit) return explicit;
+  const apex = instanceApex();
+  return apex ? `bot@${apex}` : 'bot@cloud-bongos.invalid';
+}
+
+// The name that identity commits under: the pack's product name, else the platform's
+// (task 1002719). Every caller builds `git config user.name "<name>"`, so a name the
+// shell cannot carry inside double quotes falls back instead of being interpolated.
+function brandProductName() {
+  try { return String(require('../../src/branding').branding().identity.productName || '').trim(); } catch { return ''; }
+}
+function provisionerBotName(name = brandProductName()) {
+  return name && !/["`$\\\r\n]/.test(name) ? name : 'Cloud Bongos';
+}
+
+module.exports = { instanceApex, provisionerBotEmail, provisionerBotName };

package/scripts/bongos/intent-retry.js

@@ -0,0 +1,52 @@
+'use strict';
+//
+// scripts/bongos/intent-retry.js — when a failed provisioning intent is tried again, and when it
+// is retired instead (task 1004447, goal 1000090 deploy self-heal).
+//
+// WHY. The drain loop re-pended a failure with no delay and claims the oldest pending row, so
+// one tick ran the same failing move up to MAX_INTENT_ATTEMPTS times back to back — seconds
+// apart, restarting the service after every pin move — and then gave up. That is the wrong
+// answer for each kind of failure upgrade-outcome.js now names:
+//   transient       — the registry blipped, the release is still publishing: WAIT, then retry
+//                     (about 15 minutes, 1 hour, 6 hours), which is what a person would do.
+//   known_wedge, needs_decision, unknown — trying the same thing again cannot change the
+//                     answer, so the intent is RETIRED at once and the failure left standing
+//                     for the next step (a fix, the owner, a person) to act on.
+// A failure with no class (every action other than a core move) keeps its old attempt budget,
+// but each retry now waits DEFAULT_RETRY_DELAY_MS — at least the next tick, never the same one.
+//
+// PURE: no I/O. The drain loop (scripts/bongos/provision.js cmdRunIntents) asks and obeys.
+
+const MINUTE = 60 * 1000;
+const TRANSIENT_BACKOFF_MS = Object.freeze([15 * MINUTE, 60 * MINUTE, 6 * 60 * MINUTE]);
+const DEFAULT_RETRY_DELAY_MS = MINUTE;
+
+/**
+ * What to do with an intent whose run just failed. PURE.
+ * @param {object} p
+ * @param {number} p.attempts     the attempt that just ran (claimNextIntent increments first)
+ * @param {object} [p.failure]    `{ class, reason }` from the result, when classified
+ * @param {boolean} [p.terminal]  the leg said it must not be retried unattended
+ * @param {number} p.maxAttempts  the runner's budget for unclassified failures
+ * @returns {{ action: 'retire' } | { action: 'retry', delayMs: number }}
+ */
+function retryDecision({ attempts, failure, terminal, maxAttempts }) {
+  if (terminal) return { action: 'retire' };
+  if (failure && failure.class) {
+    if (failure.class !== 'transient') return { action: 'retire' };
+    const i = Math.max(0, (attempts || 1) - 1);
+    return i < TRANSIENT_BACKOFF_MS.length ? { action: 'retry', delayMs: TRANSIENT_BACKOFF_MS[i] } : { action: 'retire' };
+  }
+  return (attempts || 0) >= maxAttempts ? { action: 'retire' } : { action: 'retry', delayMs: DEFAULT_RETRY_DELAY_MS };
+}
+
+/**
+ * The attempt ceiling checked BEFORE an intent runs. A row waiting out a transient backoff
+ * has one attempt per backoff step plus the first, so the pre-run guard must not retire it
+ * on the default budget before its last scheduled try. PURE.
+ */
+function maxAttemptsFor(intent, maxAttempts) {
+  return intent && intent.failure_class === 'transient' ? Math.max(maxAttempts, TRANSIENT_BACKOFF_MS.length + 1) : maxAttempts;
+}
+
+module.exports = { TRANSIENT_BACKOFF_MS, DEFAULT_RETRY_DELAY_MS, retryDecision, maxAttemptsFor };

package/scripts/bongos/key-card.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// scripts/bongos/key-card.js — the "key needed" visual callout (task 1391).
+//
+// The problem: a builder session that hits a missing API key today gets a
+// buried multi-line text error (see modules/art-pipeline/pipeline/gen_api.py's
+// "No image-generation key found" RuntimeError). The owner's ask: render a
+// VISUAL callout instead — same pattern as the ship/claim lifecycle card
+// (modules/lifecycle/ship-card.js) — naming which key + what it's for, a
+// primary "Add it in Settings ↗" action, and the rule "don't paste keys in
+// chat — add via Settings; it syncs to your box automatically."
+//
+// ONE generator, two render paths, both PURE (mirrors ship-card.js):
+//   renderMonospaceKeyCard(model) — the CLI/headless form.
+//   renderKeyCardHtml(model)      — the branded HTML the skills render via
+//     show_widget. Brand tokens come from src/branding.js.
+//
+// buildKeyCardModel() normalizes raw input into the model both consume.
+// emitKeyCard() is the shared I/O helper: prints the monospace card, and (when
+// widgets are on) writes the HTML to a temp file + prints the
+// `[otb-key-card-html] <path>` marker — the PostToolUse lifecycle-card hook
+// (.claude/hooks/lifecycle-card.js) picks this marker up from ANY Bash tool
+// output (it doesn't need to be a node invocation — the art pipeline calls
+// this file as a subprocess from Python) and injects the render directive.
+//
+// This is the FIRST integration (the art pipeline's Gemini key); the model is
+// deliberately key-agnostic (`keyId`/`keyLabel`/`forWhat`/`settingsAnchor` are
+// all caller-supplied) so a future key just calls emitKeyCard with different
+// strings — no new card code.
+//
+// CLI usage (what gen_api.py shells out to):
+//   node scripts/bongos/key-card.js --key gemini --label "Image-generation key" \
+//     --for "the art pipeline" --anchor art-key
+//
+// Never throws past main() — a card failure must never mask the real
+// missing-key error the caller is about to raise.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const ic = require('../../src/instance-config');
+
+// NOTE the require path: this file lives in scripts/bongos/, so branding is two
+// levels up. It read '../src/branding' (= scripts/src/branding, which does not
+// exist) until task 1002428 — so the require ALWAYS threw, safeBrand ALWAYS took
+// the catch, and every key card told the builder to visit the hardcoded founder
+// host regardless of which instance they were signed into.
+//
+// The settings URL now comes from the session-aware base (task 1002427), so it
+// names the instance the builder is actually on; the neutral productName default
+// is kept for the genuinely-unreadable-branding case.
+function safeBrand() {
+  const settingsUrl = `${ic.resolveApiBase()}/builders/settings`;
+  try {
+    const b = require('../../src/branding').branding();
+    return {
+      productName: (b.identity && b.identity.productName) || 'Cloud Bongos',
+      settingsUrl,
+    };
+  } catch (_) {
+    return { productName: 'Cloud Bongos', settingsUrl };
+  }
+}
+
+// ---- model ------------------------------------------------------------
+// { keyId, keyLabel, forWhat, settingsUrl, brand }
+function buildKeyCardModel(input = {}) {
+  const brand = input.brand || safeBrand();
+  const anchor = input.settingsAnchor ? `#${input.settingsAnchor}` : '';
+  const settingsUrl = input.settingsUrl || `${brand.settingsUrl}${anchor}`;
+  return {
+    keyId: input.keyId || 'key',
+    keyLabel: input.keyLabel || 'API key',
+    forWhat: input.forWhat || '',
+    settingsUrl,
+    brand,
+  };
+}
+
+// ---- monospace renderer (alignment-proof, no right border) -------------
+const MONO_W = 58;
+function wrap(text, width) {
+  const words = String(text == null ? '' : text).split(/\s+/).filter(Boolean);
+  const lines = [];
+  let cur = '';
+  for (const w of words) {
+    if (!cur) cur = w;
+    else if ((cur + ' ' + w).length <= width) cur += ' ' + w;
+    else { lines.push(cur); cur = w; }
+  }
+  if (cur) lines.push(cur);
+  return lines.length ? lines : [''];
+}
+function renderMonospaceKeyCard(model) {
+  const m = model;
+  const out = [];
+  const bar = '  ' + '─'.repeat(MONO_W);
+  const left = `${m.brand.productName} · key needed`;
+  const right = 'Action needed';
+  const gap = Math.max(2, MONO_W - left.length - right.length);
+  out.push('  ' + left + ' '.repeat(gap) + right);
+  out.push(bar);
+  const headline = m.forWhat ? `${m.keyLabel} — needed for ${m.forWhat}` : m.keyLabel;
+  for (const l of wrap(headline, MONO_W)) out.push('  ' + l);
+  out.push('');
+  for (const l of wrap("Don't paste keys in chat — add it in Settings; it syncs to your box automatically.", MONO_W)) {
+    out.push('  ' + l);
+  }
+  out.push('');
+  out.push(bar);
+  for (const l of wrap(`Next → Add it in Settings: ${m.settingsUrl}`, MONO_W)) out.push('  ' + l);
+  return out.join('\n');
+}
+
+// ---- HTML renderer (the in-feed branded card) ---------------------------
+function esc(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) =>
+    ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+function renderKeyCardHtml(model) {
+  const m = model;
+  const bg = 'var(--color-background-warning)';
+  const fg = 'var(--color-text-warning)';
+  const headline = m.forWhat ? `${m.keyLabel} needed for ${m.forWhat}` : `${m.keyLabel} needed`;
+  const srText = `${headline}. Don't paste keys in chat — add it in Settings, it syncs to your box automatically.`;
+
+  return `<h2 class="cc-sr">${esc(srText)}</h2>
+<style>
+.cc-sr{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0;}
+</style>
+<div style="background:var(--color-background-primary);border:0.5px solid var(--color-border-tertiary);border-radius:var(--border-radius-lg);padding:0.8rem 1.05rem;">
+  <div style="display:flex;align-items:center;gap:8px;background:${bg};border-radius:var(--border-radius-md);padding:7px 12px;margin-bottom:0.65rem;">
+    <i class="ti ti-key" style="font-size:18px;color:${fg};" aria-hidden="true"></i>
+    <span style="font-size:15px;font-weight:500;color:${fg};min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;">${esc(headline)}</span>
+  </div>
+  <div style="display:flex;align-items:center;gap:12px;margin-bottom:7px;">
+    <span style="font-family:var(--font-serif);font-size:16.5px;font-weight:500;line-height:1.3;flex:1;min-width:0;">${esc(m.keyLabel)}</span>
+    <a href="${esc(m.settingsUrl)}" class="cc-link cc-next" style="text-decoration:none;background:none;border:none;padding:0;cursor:pointer;font-family:inherit;display:inline-flex;align-items:center;gap:3px;white-space:nowrap;flex:none;font-size:12px;color:var(--color-text-secondary);">Add it in Settings ↗</a>
+  </div>
+  <div style="font-size:13px;color:var(--color-text-secondary);line-height:1.5;">Don't paste keys in chat — add it in Settings; it syncs to your box automatically.</div>
+</div>`;
+}
+
+// ---- emitKeyCard: the shared I/O helper ----------------------------------
+// Prints the monospace card (always), and — when widgetsEnabled — writes the
+// branded HTML to a temp file + prints the [otb-key-card-html] marker.
+// Strictly best-effort: a card failure must never mask the caller's real error.
+function emitKeyCard(model, { log = console.log, widgetsEnabled = true } = {}) {
+  try {
+    log('');
+    log(renderMonospaceKeyCard(model));
+  } catch (_) { return null; }
+  if (!widgetsEnabled) {
+    try {
+      log('');
+      log('[otb-card] widgets are off for this builder — the card above IS the summary; relay it as plain text and do NOT call show_widget.');
+    } catch (_) { /* best-effort */ }
+    return null;
+  }
+  try {
+    const file = path.join(os.tmpdir(), `otb-key-card-${model.keyId}.html`);
+    fs.writeFileSync(file, renderKeyCardHtml(model), 'utf8');
+    log('');
+    log(`[otb-key-card-html] ${file}`);
+    log('[otb-card] render the HTML at the path above in the chat feed via the visualization tool (show_widget), then stop — no prose recap. Never ask the builder to paste the key in chat; point them at the Settings link. If that tool is unavailable, the card above IS the summary.');
+    return file;
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---- CLI ------------------------------------------------------------------
+function arg(flag, argv) {
+  const i = argv.indexOf(flag);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
+}
+
+async function resolveWidgetsEnabled() {
+  // Best-effort: read the builder's render-widgets knob from /me (task 1279
+  // precedent — claim.js/ship.js do the same). ANY failure (no session,
+  // offline, timeout, non-200) defaults to widgets ON — the common case for an
+  // interactive session — rather than blocking the card on a network call.
+  try {
+    const { loadSession, API_BASE } = require('./cli-lib');
+    const session = await loadSession();
+    if (!session || !session.token) return true;
+    const base = session.api_base || API_BASE;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 3000);
+    try {
+      const res = await fetch(`${base}/api/bongos/me`, {
+        headers: { Authorization: `Bearer ${session.token}`, 'User-Agent': require('../../src/branding').userAgent() },
+        signal: ctrl.signal,
+      });
+      if (!res.ok) return true;
+      const data = await res.json();
+      return data?.render?.widgets_enabled !== false;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (_) {
+    return true;
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const model = buildKeyCardModel({
+    keyId: arg('--key', argv) || 'key',
+    keyLabel: arg('--label', argv) || 'API key',
+    forWhat: arg('--for', argv) || '',
+    settingsAnchor: arg('--anchor', argv) || null,
+    settingsUrl: arg('--settings-url', argv) || null,
+  });
+  const widgetsEnabled = await resolveWidgetsEnabled();
+  emitKeyCard(model, { widgetsEnabled });
+}
+
+if (require.main === module) {
+  main().then(() => process.exit(0)).catch(() => process.exit(0)); // best-effort — never fail the caller
+}
+
+module.exports = { buildKeyCardModel, renderMonospaceKeyCard, renderKeyCardHtml, emitKeyCard, wrap, esc, safeBrand };

package/scripts/bongos/key-status.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// scripts/bongos/key-status.js — the /builder-key backing script (task 1391, part B).
+//
+// Lists which API keys are set/unset for the calling builder, renders the
+// "key needed" visual callout (scripts/bongos/key-card.js) for any that are
+// missing, and — after the builder adds one via Settings — re-syncs the local
+// session file (scripts/bongos/fetch-art-key.js) and confirms it resolved.
+//
+// HARD RULE (idea 347 + the UI-first auth-flow rule): a key is NEVER accepted
+// as a CLI argument or pasted into chat — the only place a key is ever
+// written is PUT /me/art-key/own, driven by the browser Settings page
+// (modules/hall-ui/public/settings.js). If a builder pastes a key-looking
+// string as an argument anyway, this script refuses and points back to
+// Settings instead of silently ignoring or forwarding it.
+//
+// Usage:
+//   node scripts/bongos/key-status.js              # list status; render callout if missing
+//   node scripts/bongos/key-status.js --recheck     # re-sync + confirm after adding a key
+
+'use strict';
+
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { cliClient, requireSession } = require('./cli-lib');
+const keyCard = require('./key-card');
+
+// The known keys this script reports on. One entry today (the art pipeline's
+// Gemini key); a future key adds an entry here, not a new script (mirrors
+// key-card.js's deliberately key-agnostic model).
+const KEYS = [
+  {
+    id: 'gemini',
+    label: 'Image-generation key (Google AI Studio / Gemini)',
+    forWhat: 'the art pipeline',
+    settingsAnchor: 'art-key',
+    fetchStatus: async () => {
+      const api = await cliClient();
+      const r = await api.me.getMeArtKey();
+      if (r.status !== 200 || !r.data) return { known: false };
+      const d = r.data;
+      if (d.own_key_set) return { known: true, set: true, detail: `your own key, ending ${d.own_key_last4 || '????'}` };
+      if (d.entitled && d.configured) return { known: true, set: true, detail: 'the shared newcomer key (floor coverage)' };
+      return { known: true, set: false };
+    },
+  },
+];
+
+// A pasted-secret guard (part 3 of the done-when): refuse any argument that
+// looks like a credential rather than a flag, instead of silently accepting
+// or forwarding it. Google AI Studio keys are ~39 chars of [A-Za-z0-9_-];
+// this is deliberately loose (catches "looks like a key", not just Google's
+// exact shape) since the whole point is to never guess-forward a secret.
+const KEY_LIKE_RE = /^[A-Za-z0-9_-]{20,}$/;
+
+function refuseIfKeyPasted(argv) {
+  const suspect = argv.find((a) => !a.startsWith('--') && KEY_LIKE_RE.test(a));
+  if (!suspect) return false;
+  console.log('');
+  console.log('✖ That looks like an API key — this tool never accepts one as an argument,');
+  console.log('  and keys are never pasted into chat (the transcript is uploaded).');
+  console.log('  Add it in Settings instead — it syncs to your box automatically:');
+  console.log(`    ${require('./cli-lib').hallBase()}/settings#art-key`);
+  return true;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (refuseIfKeyPasted(argv)) { process.exit(1); return; }
+
+  const recheck = argv.includes('--recheck');
+  await requireSession();
+
+  if (recheck) {
+    try { execFileSync(process.execPath, [path.join(__dirname, 'fetch-art-key.js')], { stdio: 'ignore' }); }
+    catch (_) { /* best-effort re-sync */ }
+  }
+
+  console.log('');
+  console.log('Key status:');
+  let anyMissing = false;
+  for (const k of KEYS) {
+    let status;
+    try { status = await k.fetchStatus(); } catch (_) { status = { known: false }; }
+    if (!status.known) {
+      console.log(`  ? ${k.label} — couldn't check (offline or API error)`);
+      continue;
+    }
+    if (status.set) {
+      console.log(`  ✓ ${k.label} — set (${status.detail})`);
+    } else {
+      console.log(`  ✖ ${k.label} — not set`);
+      anyMissing = true;
+      const model = keyCard.buildKeyCardModel({
+        keyId: k.id, keyLabel: k.label, forWhat: k.forWhat, settingsAnchor: k.settingsAnchor,
+      });
+      keyCard.emitKeyCard(model, { widgetsEnabled: await resolveWidgetsEnabled() });
+    }
+  }
+
+  if (recheck) {
+    console.log('');
+    console.log(anyMissing
+      ? 'Re-synced — still missing a key above. Add it in Settings, then run --recheck again.'
+      : 'Re-synced — all keys resolved.');
+  }
+}
+
+async function resolveWidgetsEnabled() {
+  try {
+    const api = await cliClient({ allowUnauthenticated: true });
+    const r = await api.me.getMe();
+    if (r.status !== 200 || !r.data) return true;
+    return r.data?.render?.widgets_enabled !== false;
+  } catch (_) {
+    return true;
+  }
+}
+
+if (require.main === module) {
+  main().then(() => process.exit(0)).catch((err) => {
+    console.error(err && err.message ? err.message : String(err));
+    process.exit(1);
+  });
+}
+
+module.exports = { KEYS, KEY_LIKE_RE, refuseIfKeyPasted };