@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/start.js

@@ -0,0 +1,1090 @@
+#!/usr/bin/env node
+// Builder start — what can I claim right now?
+//
+// Usage:
+//   node scripts/bongos/start.js [--version V1|PMS-V1] [--discipline engineer|artist|ideator|unclassified] [--all-disciplines] [--fit autonomous|parallel] [--limit N] [--full] [--widget] [--json]
+//
+// --fit narrows the claimable list to what the autonomous overnight
+// session-runner (#358) may pick up:
+//   autonomous — overnight-safe + manual_degree<=2 + unblocked (canonical
+//                tasks_session_fit 'autonomous' mode). The runner takes
+//                claimable[0] as the next task by priority.
+//   parallel   — autonomous AND tasks.parallel_safe = true (safe to run
+//                alongside other tasks). The runner fills its parallel slots
+//                from the top of this list.
+//
+// Output is a deterministic "card" (task 1273): one quiet status line, the
+// builder's identity, their holdings, a clean claimable table (# / Version /
+// Type / Reward / Est. / What it is), and a next-step line — identical every session.
+//   --widget : emit the card as self-contained HTML on stdout (private warnings
+//              to stderr) for the app's widget renderer (show_widget). This is
+//              the surface the /builder-start skill renders — BUT it honours the
+//              builder's per-builder "render widgets" knob (task 1279): if that
+//              builder has widgets off, --widget degrades to the markdown card so
+//              no HTML is ever emitted/relayed. Default ON. The skill detects
+//              which form it got (HTML starts with '<') and renders accordingly.
+//   (default): the markdown form of the same card — the fallback when the
+//              client can't draw widgets (raw terminal, cron, other tools).
+//   --full   : add the detailed ambient widgets + context pack (markdown).
+//   --json   : unchanged machine interface the autonomous runner reads.
+//
+// --discipline filters the claimable list by builder interest area
+// (orthogonal to kind). engineer = code/infra/gameplay/bugs; artist =
+// pixel art / sprites / the art pipeline; ideator = scoping/research/
+// docs/narrative/lore.
+//
+// DISCIPLINE ROUTING (V3.R81 / #299): by default — when no explicit
+// --discipline is passed — the claimable list is narrowed to the builder's
+// preferred_disciplines (builders.preferred_disciplines, set via
+// /me/disciplines per migrations 027 + 086). An artist shouldn't be shown
+// only engineer tasks. Two escape hatches:
+//   --all-disciplines  — ignore preferences, show every lane.
+//   --discipline X      — explicit single-lane filter (overrides preferences).
+// A builder with no stated preference (empty preferred_disciplines) sees
+// everything by default — there is no lane to narrow to.
+//
+// Below the main list, a "You might enjoy" section surfaces up to 3 claimable
+// tasks OUTSIDE the builder's disciplines, ranked by relevance. The ranking
+// mirrors rankCrossDisciplineRecommendations in modules/lifecycle/db-tasks.js
+// (the canonical server-side home for this logic — kept in sync deliberately;
+// start.js is a pure HTTP client and cannot import the server db module).
+//
+//
+// Returns JSON if --json is passed (for the slash command to parse cleanly).
+
+const { cliClient, errCode, errDetails, requireSession, fmtUsd, printOnboardingNudge, printCostWarning, printNeedsNudge, hallBase, API_BASE, rewardPolicy, costPlusOnlyNote, isDispatcherIncompatError, cardFlagsFromMe } = require('./cli-lib');
+const { plainCardLines } = require('./plain-cards');
+const { contextPack, formatContextPackCompact } = require('./context-pack');
+const { depsFinding } = require('./preflight');
+
+// task 1284: the card shows only the top N claimable rows. The table is the bulk
+// of the widget HTML the model relays verbatim, so fewer rows = fewer tokens +
+// faster render; the true total sits in the header and a "N more — show all"
+// affordance covers the rest. --json is unchanged (full list for the runner).
+const CARD_ROWS = 5;
+
+// ---------- header widget helpers ----------
+
+// Compact ascii progress bar. Width 10. Filled = █, empty = ░.
+function progressBar(percent, width = 10) {
+  const p = Math.max(0, Math.min(100, Number(percent) || 0));
+  const filled = Math.round((p / 100) * width);
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+function formatVersionsRow(progress) {
+  if (!Array.isArray(progress) || progress.length === 0) return null;
+  // Only show versions currently building (status==='building').
+  // Fall back to non-shipped if none are flagged building.
+  let active = progress.filter((v) => v.status === 'building');
+  if (active.length === 0) active = progress.filter((v) => v.status !== 'shipped');
+  if (active.length === 0) return null;
+  const parts = active.map((v) => `${v.version_id} ${progressBar(v.percent_complete)} ${v.percent_complete}%`);
+  return parts.join('  ·  ');
+}
+
+function formatCostRow(cost) {
+  if (!cost || typeof cost !== 'object') return null;
+  const spent = Number(cost.total_usd) || 0;
+  const credits = Number(cost.total_value_credits) || 0;
+  // No verdict. The old line computed `credits >= spent` and printed
+  // "value > cost ✓" — comparing unitless reward drachmae against USD, so it
+  // was green by unit mismatch, not by economics (spike #482 audit, F2). It was
+  // also resting on an incomplete cost figure: cost_log captures almost no LLM
+  // spend (audit F1; api category was $0.60). Until spend is captured honestly
+  // (#483/#486) and given a real value basis, we show the two ledgers plainly
+  // and labelled for what they are — logged spend vs reward credits — and let
+  // them stand without a manufactured ✓/✗.
+  return `${fmtUsd(spent)} logged spend  ·  ${credits}c reward shipped`;
+}
+
+// inboxOpenCount — how many ideas are OPEN in the inbox, from a GET /inbox response.
+//
+// WHY THIS IS NOT ideas.length (task 1003454). GET /inbox answers
+// { ideas, open_count }, where `ideas` is a PAGE (default 50 rows) and
+// `open_count` is the real total, counted server-side under the same rank gate
+// as the rows. Reading the array length therefore reported the page size: the
+// card said "50 ideas in inbox" while the payload said 99, and once the queue
+// passed one page the figure pinned at exactly 50 forever — a number that looks
+// plausible, never moves, and understates the backlog the card exists to make
+// visible. capture.js already destructured open_count correctly, which is what
+// made this an oversight rather than a convention.
+//
+// The page length stays as a FALLBACK so an older core that predates open_count
+// still renders a figure rather than "N/A". Returns null when neither is
+// readable, which the callers render as "ideas: N/A".
+function inboxOpenCount(inboxRes) {
+  if (!inboxRes || !inboxRes.ok) return null;
+  const data = inboxRes.data;
+  if (data && typeof data.open_count === 'number') return data.open_count;
+  if (data && Array.isArray(data.ideas)) return data.ideas.length;
+  if (data && typeof data.count === 'number') return data.count;
+  return null;
+}
+
+function formatRecentRow({ recentShipped, inboxCount, blockerCount }) {
+  const bits = [];
+  // "1 ship in last 24h" — recent_shipped returns tasks shipped within
+  // a recent window; we re-filter to strictly <24h for the header.
+  if (Array.isArray(recentShipped)) {
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    const last24 = recentShipped.filter((t) => {
+      const ts = t.shipped_at ? Date.parse(t.shipped_at) : 0;
+      return ts && ts >= cutoff;
+    }).length;
+    bits.push(`${last24} ship${last24 === 1 ? '' : 's'} in last 24h`);
+  } else {
+    bits.push('ships: N/A');
+  }
+  bits.push(inboxCount == null ? 'ideas: N/A' : `${inboxCount} idea${inboxCount === 1 ? '' : 's'} in inbox`);
+  bits.push(blockerCount == null ? 'blockers: N/A' : `${blockerCount} open blocker${blockerCount === 1 ? '' : 's'}`);
+  return bits.join('  ·  ');
+}
+
+// ---------- card helpers (task 1273) ----------
+// The default /builder-start view is a single deterministic "card" rendered as
+// markdown: a quiet status line, identity, holdings, a clean claimable table,
+// and a next-step line. Same shape every session — the skill relays this stdout
+// verbatim, which is what removes the per-session re-summarizing drift.
+
+// Shared status selection — single source of truth for what the quiet status
+// line shows, so the markdown line and the widget render the same thing.
+// Surfaces the versions with real momentum: drop not-yet-started (0%) ones,
+// lead with the most-progressed, so a dormant planning version doesn't crowd
+// out the one actually being built.
+function statusParts({ progress, recentShipped, inboxCount, blockerCount }) {
+  let versions = [];
+  if (Array.isArray(progress) && progress.length) {
+    let active = progress.filter((v) => v.status === 'building');
+    if (active.length === 0) active = progress.filter((v) => v.status !== 'shipped');
+    versions = active
+      .filter((v) => Number(v.percent_complete) > 0)
+      .sort((a, b) => Number(b.percent_complete) - Number(a.percent_complete))
+      .slice(0, 2)
+      .map((v) => ({ id: v.version_id, pct: Number(v.percent_complete) }));
+  }
+  let ships24 = null;
+  if (Array.isArray(recentShipped)) {
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    ships24 = recentShipped.filter((t) => t.shipped_at && Date.parse(t.shipped_at) >= cutoff).length;
+  }
+  return { versions, ships24, ideas: inboxCount, blockers: blockerCount };
+}
+
+// One muted line of ambient status (markdown). Italic so the feed renders it
+// quiet. null if empty.
+function quietStatusLine(header) {
+  const { versions, ships24, ideas, blockers } = statusParts(header);
+  const parts = [];
+  for (const v of versions) parts.push(`${v.id} ${progressBar(v.pct, 8)} ${v.pct}%`);
+  if (ships24 != null) parts.push(`${ships24} ship${ships24 === 1 ? '' : 's'}/24h`);
+  if (ideas != null) parts.push(`${ideas} idea${ideas === 1 ? '' : 's'} in inbox`);
+  if (blockers != null) parts.push(`${blockers} open blocker${blockers === 1 ? '' : 's'}`);
+  if (parts.length === 0) return null;
+  return surface.em(parts.join('  ·  '));
+}
+
+// Calibrated estimate, compact: ~8m / ~2h / ~1.5h.
+function estimateShort(t) {
+  const m = t.est_minutes_calibrated != null ? t.est_minutes_calibrated : t.est_minutes;
+  if (m == null) return '—';
+  if (m < 60) return `~${m}m`;
+  const h = m / 60;
+  return Number.isInteger(h) ? `~${h}h` : `~${h.toFixed(1)}h`;
+}
+
+function clip(s, n) {
+  s = String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+  return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+
+// Escape pipes so a title can't break the markdown table.
+function cell(s) {
+  return String(s == null ? '' : s).replace(/\|/g, '\\|');
+}
+
+// Per-column values, shared by the markdown table and the widget. Version
+// (V2 / GDS-V4) is its own column; Type is the work lane (Engineer / Artist /
+// Ideator), its own column rather than baked into the title.
+// task 1003936: ONE word for this axis — Role, per ADR 0174 Decision 5. The hall's
+// copy of this lives in modules/hall-ui/public/dom-utils.js (OTB.roleLabel); this
+// card is a separate runtime and cannot read it, so the word is restated here and
+// nowhere else in this file. 'ui' keeps its upper case, as the hall's does.
+const ROLE_AXIS_LABEL = 'Role';
+function roleLabel(t) {
+  const d = t.discipline;
+  if (!d || d === 'unclassified') return '';
+  return d === 'ui' ? 'UI' : d.charAt(0).toUpperCase() + d.slice(1);
+}
+// Per-lane accent — the OTB palette (sea / terracotta / olive); mid-ramp hexes
+// that read in both light and dark. Colours the Type column so the work lane
+// reads at a glance (task 1273 follow-up: "spice up the view").
+function disciplineColor(d) {
+  if (d === 'engineer') return '#1D9E75'; // sea-teal
+  if (d === 'artist') return '#D85A30';   // terracotta
+  if (d === 'ideator') return '#639922';  // olive
+  return '#888780';                        // unclassified — neutral gray
+}
+function whatItIs(t) {
+  return clip(t.title, 64);
+}
+
+// The claimable table — # / Version / Type / Reward / Est. / What it is.
+// Ids are emitted as hall links (renders as a clean #N) — a bare "#NNN" in a
+// relayed chat message autolinks to GitHub and 404s (CLAUDE.md ref rule).
+const surface = require('./surface');
+const startGoals = require('./start-goals');
+const HALL_TASK = `${hallBase()}#/task/`;
+function claimableTable(rows, rewardFromServer, goals) {
+  // On a cost-plus-only instance the Reward column is an advertised estimate that
+  // is never paid — say so in the header so the column can't read as a promise,
+  // and footnote what IS paid below the table (task 1002469).
+  const perTask = rewardPolicy(rewardFromServer).perTaskCredit;
+  const rewardHead = perTask ? 'Reward' : 'Reward (est.)';
+  const headers = ['#', 'Version', ROLE_AXIS_LABEL, rewardHead, 'Est.', 'What it is'];
+  const rowCells = (t) => [
+    surface.taskRef(t.id, HALL_TASK),
+    cell(t.version_id || '?'),
+    cell(roleLabel(t) || '—'),
+    `${t.credits_reward ?? 0}c`,
+    estimateShort(t),
+    cell(whatItIs(t)),
+  ];
+  // task 1002852: one table per goal, each under its goal's name; goal-less work
+  // last under "Other work". An empty goal list (a failed read) still groups by id.
+  const out = [];
+  for (const g of startGoals.groupByGoal(rows, goals)) {
+    if (out.length) out.push('');
+    out.push(surface.strong(g.title) + (g.joined ? ' · your goal' : ''), surface.table(headers, g.rows.map(rowCells)));
+  }
+  const cpNote = costPlusOnlyNote(rewardFromServer);
+  if (cpNote) out.push('', surface.em(cpNote));
+  return out.join('\n');
+}
+
+// ---------- widget renderer (task 1273) ----------
+// `--widget` emits this self-contained HTML on stdout; the skill pipes it
+// straight to the app's widget renderer (show_widget). Script-owned markup =
+// the same card every time, app-native. Falls back to the markdown card when
+// the client can't draw widgets. Design system: flat, 0.5px borders, CSS
+// theme vars (light/dark), Tabler icons, no emoji.
+const hesc = (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const jsq = (s) => String(s == null ? '' : s).replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, ' ');
+
+function miniBar(pct) {
+  // Fill tinted OTB sea-teal so the status line carries a little of the brand.
+  // Class-based (task 1279 efficiency pass): the .bs-* rules live in WIDGET_STYLE,
+  // so this markup is only meaningful inside the widget renderWidget emits.
+  return `<span class="bs-bar"><span class="bs-barfill" style="width:${pct}%;"></span></span>`;
+}
+
+// ---------- owed-rebase warning (ADR 0120 part 5) ----------
+// The builder's un-landed confirmed tasks the publish-reconciler flagged
+// needs_rebase (part 2). They GATE new claims (part 3: claimTask refuses with
+// REBASE_REQUIRED) and their per-task reward now lands only on ship (part 1),
+// so this is the single most urgent thing to show at session start — rendered
+// prominently, before the claimable table, in both the markdown card and the
+// widget. /me carries them as `needs_rebase_tasks` (each { id, title, … }).
+// Refs use the `task N` form, NEVER a bare "#N" (a bare #N in relayed chat
+// autolinks to GitHub issues and 404s — the CLAUDE.md linkify rule).
+
+// Normalize the /me list into a small render model, or null when nothing is
+// owed. Shared by the markdown + widget renderers and unit-tested directly
+// (no live server needed).
+function rebaseWarningModel(needsRebaseTasks) {
+  const owed = Array.isArray(needsRebaseTasks)
+    ? needsRebaseTasks.filter((t) => t && t.id != null)
+    : [];
+  if (owed.length === 0) return null;
+  const n = owed.length;
+  return {
+    count: n,
+    refs: owed.map((t) => `task ${t.id}`).join(', '),
+    noun: n === 1 ? 'task' : 'tasks',
+    pronoun: n === 1 ? 'it' : 'them',
+  };
+}
+
+// The markdown warning line (prominent, before the claimable table), or null
+// when nothing is owed.
+function rebaseWarningMarkdown(needsRebaseTasks) {
+  const w = rebaseWarningModel(needsRebaseTasks);
+  if (!w) return null;
+  return `⚠️ ${surface.strong('Land owed — your queue is GATED.')} ${w.count} ${w.noun} can't land and block new claims`
+    + ` until you ${surface.code('git merge origin/main')} + re-ship (or ${surface.code(surface.action('release'))}) ${w.pronoun}: ${w.refs}.`
+    + ' Merge, never rebase — a published branch that is rewritten cannot be pushed again (task 1002788).';
+}
+
+// The widget warning block (Tabler alert icon, danger-tinted), or '' when none.
+function rebaseWarningWidget(needsRebaseTasks) {
+  const w = rebaseWarningModel(needsRebaseTasks);
+  if (!w) return '';
+  return `<div class="bs-warn"><i class="ti ti-alert-triangle" aria-hidden="true"></i>`
+    + `<span><strong>Land owed — your queue is GATED.</strong> ${w.count} ${w.noun} can't land and block new claims until you <code>git merge origin/main</code> + re-ship (or /builder-release) ${w.pronoun}: ${hesc(w.refs)}. Merge, never rebase — a published branch that is rewritten cannot be pushed again (task 1002788).</span></div>`;
+}
+
+// Run console.log-based helpers (printCostWarning/printOnboardingNudge) without
+// polluting stdout (which must be pure HTML in --widget mode); return the lines.
+function captureLog(fn) {
+  const orig = console.log;
+  const lines = [];
+  console.log = (...a) => lines.push(a.join(' '));
+  try { fn(); } finally { console.log = orig; }
+  return lines;
+}
+
+// task 1282: reinforce the relay contract IN-BAND, not just in the skill. The
+// rule — render/print the card verbatim, then stop; don't rebuild it into prose
+// + tables + a recommendation — used to live ONLY in SKILL.md (advisory), so a
+// model in old habits (or a stale checkout's old skill) reverted to hand-built
+// tables. This emits a one-line `[otb-card]` directive on STDERR (stdout stays
+// pure HTML/markdown, so the show_widget pipe + the skill's first-char branch
+// are untouched). The skill treats `[otb-card]` stderr lines as instructions
+// for itself and never relays them to the user. Mirrors the ship card.
+const CARD_DIRECTIVE = {
+  html: '[otb-card] stdout is the finished /builder-start card (HTML). Render it verbatim via show_widget, then stop — no extra tables, recommendation, nudge, or recap.',
+  markdown: '[otb-card] stdout is the finished /builder-start card (markdown). Output it verbatim as your reply, then stop — no rebuilt table, recommendation, nudge, or recap.',
+};
+function emitCardDirective(form) {
+  // Addressed to the model, not the reader. A terminal user has no card to relay and no
+  // show_widget to call, so this line is pure confusion there (task 1003680).
+  if (surface.isTerminal()) return;
+  process.stderr.write(CARD_DIRECTIVE[form] + '\n');
+}
+
+// task 1279 efficiency pass: the /builder-start widget used to inline a full
+// style="…" on every one of its ~30+ elements — the 7×N claimable grid was the
+// bulk — making the HTML the agent must relay verbatim ~18.7KB. Hoisting the
+// repeated rules into one class block (the pattern the ship card already uses)
+// cuts that markup substantially with byte-identical rendering. Classes are
+// `.bs-*` (builder-start) so they can't collide with the ship card's `.cc-*`.
+const WIDGET_STYLE = `<style>
+.bs-sr{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;}
+.bs-card{background:var(--color-background-primary);border:0.5px solid var(--color-border-tertiary);border-radius:var(--border-radius-lg);padding:1rem 1.25rem;font-family:var(--font-sans);}
+.bs-head{display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap;}
+.bs-brand{display:inline-flex;align-items:center;gap:8px;}
+.bs-title{font-size:16px;font-weight:500;}
+.bs-title i{font-size:16px;vertical-align:-2px;margin-right:6px;color:#D85A30;}
+.bs-meta{font-size:13px;color:var(--color-text-secondary);}
+.bs-status{font-size:13px;color:var(--color-text-secondary);margin-top:8px;display:flex;flex-wrap:wrap;gap:4px 12px;align-items:center;}
+.bs-dot{color:var(--color-text-tertiary);}
+.bs-bar{display:inline-block;width:34px;height:5px;border-radius:3px;background:var(--color-border-tertiary);overflow:hidden;vertical-align:middle;}
+.bs-barfill{display:block;height:100%;background:#1D9E75;}
+.bs-warn{display:flex;gap:8px;align-items:flex-start;font-size:13px;margin-top:8px;padding:8px 10px;border-radius:var(--border-radius-md);background:var(--color-background-danger);color:var(--color-text-danger);}
+.bs-warn i{font-size:15px;flex:none;margin-top:1px;}
+.bs-line{font-size:13px;color:var(--color-text-secondary);margin-top:8px;}
+.bs-line i{font-size:14px;vertical-align:-2px;margin-right:4px;}
+.bs-holditem{margin-top:4px;padding-left:18px;}
+.bs-link{color:var(--color-text-secondary);}
+.bs-menuh{font-size:13px;color:var(--color-text-primary);margin-top:14px;margin-bottom:2px;font-weight:500;}
+.bs-table{width:100%;border-collapse:collapse;table-layout:fixed;font-size:13px;margin-top:4px;}
+.bs-thead{text-align:left;color:var(--color-text-tertiary);font-size:12px;}
+.bs-th{padding:0 6px 4px;font-weight:400;}
+.bs-tr{cursor:pointer;}
+.bs-group td{padding:10px 0 4px;font-size:12px;font-weight:500;color:var(--color-text-secondary);}
+.bs-td{padding:7px 6px;border-top:0.5px solid var(--color-border-tertiary);}
+.bs-id{color:var(--color-text-secondary);font-family:var(--font-mono);font-size:12px;}
+.bs-nowrap{white-space:nowrap;}
+.bs-ellip{white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
+.bs-ellip-sub{color:var(--color-text-secondary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
+.bs-sub{color:var(--color-text-secondary);}
+.bs-lane{display:inline-block;width:7px;height:7px;border-radius:50%;margin-right:6px;vertical-align:middle;}
+.bs-foot{font-size:13px;color:var(--color-text-tertiary);margin-top:12px;}
+</style>`;
+
+function renderWidget({ builder, claims, claimable, total, streak, recommendations, header, routingByPreference, preferred, filters, readyToClose, needsRebaseTasks, goals, yourGoals }) {
+  const b = builder || {};
+  // ADR 0120 part 5: the owed-rebase gate warning, rendered at the top of the
+  // card (before status/holdings) since it blocks new claims. '' when none owed.
+  const rebaseRow = rebaseWarningWidget(needsRebaseTasks);
+  // Streak badge — warm amber, the one bold pop of colour + the motivational
+  // stat. Shown only on an active (>0) streak; tooltip carries the record.
+  // (Singular element — left inline; the savings live in the repeated grid.)
+  const streakBadge = (streak && Number(streak.current) > 0)
+    ? `<span title="Longest streak: ${Number(streak.longest) || 0} days" style="display:inline-flex;align-items:center;gap:4px;background:var(--color-background-warning);color:var(--color-text-warning);font-size:12px;font-weight:500;padding:2px 8px;border-radius:var(--border-radius-md);"><i class="ti ti-flame" aria-hidden="true" style="font-size:13px;"></i>${Number(streak.current)}-day streak</span>`
+    : '';
+  const rank = b.rank ? b.rank[0].toUpperCase() + b.rank.slice(1) : 'Thetes';
+  const disc = (b.preferred_disciplines && b.preferred_disciplines.length) ? b.preferred_disciplines.join(' + ') : 'all disciplines';
+  const credits = Number(b.total_credits || 0).toLocaleString();
+  const TH = (label) => `<th class="bs-th">${label}</th>`;
+  const TD = (inner, cls = '') => `<td class="bs-td${cls ? ' ' + cls : ''}">${inner}</td>`;
+
+  // status line
+  const { versions, ships24, ideas, blockers } = statusParts(header);
+  const sBits = [];
+  for (const v of versions) sBits.push(`${hesc(v.id)} ${miniBar(v.pct)} ${v.pct}%`);
+  if (ships24 != null) sBits.push(`${ships24} ship${ships24 === 1 ? '' : 's'}/24h`);
+  if (ideas != null) sBits.push(`${ideas} idea${ideas === 1 ? '' : 's'}`);
+  if (blockers != null) sBits.push(`${blockers} blocker${blockers === 1 ? '' : 's'}`);
+  const statusRow = sBits.length
+    ? `<div class="bs-status">${sBits.join('<span class="bs-dot">·</span>')}</div>`
+    : '';
+
+  // holdings — each held task gets quick actions off it (ship / release /
+  // open). Parallel sessions under one builder are normal, so this informs.
+  const hallUrl = (id) => `${hallBase()}#/task/${encodeURIComponent(id)}`;
+  const dot = '<span class="bs-dot"> · </span>';
+  const act = (label, msg) => `<a href="#" onclick="event.preventDefault();sendPrompt('${jsq(msg)}')" class="bs-link">${label} ↗</a>`;
+  const actionsFor = (c) => `${act('Ship', 'Ship task ' + c.task_id)}${dot}${act('Release', 'Release task ' + c.task_id)}${dot}<a href="${hesc(hallUrl(c.task_id))}" class="bs-link">Open ↗</a>`;
+  let holdings = '';
+  if (claims.length === 1) {
+    const c = claims[0];
+    holdings = `<div class="bs-line"><i class="ti ti-bookmark" aria-hidden="true"></i>Holding #${hesc(c.task_id)} — ${hesc(clip(c.title, 44))}${dot}${actionsFor(c)}</div>`;
+  } else if (claims.length > 1) {
+    const items = claims.map((c) => `<div class="bs-holditem">#${hesc(c.task_id)} — ${hesc(clip(c.title, 38))}${dot}${actionsFor(c)}</div>`).join('');
+    holdings = `<div class="bs-line"><i class="ti ti-bookmark" aria-hidden="true"></i>Holding ${claims.length} claims (parallel sessions OK):${items}</div>`;
+  }
+
+  // version-close banner (rare, Archon action)
+  const closeBanner = (readyToClose || []).map((s) =>
+    `<div class="bs-line"><i class="ti ti-flag" aria-hidden="true"></i>${hesc(s.versionId)} looks ready to close (${s.criteriaSatisfied}/${s.criteriaTotal} criteria, ${s.percentComplete}%) — <a href="#" onclick="event.preventDefault();sendPrompt('${jsq('/builder-version-close ' + s.versionId)}')" class="bs-link">close it ↗</a></div>`
+  ).join('');
+
+  // menu header note
+  const matched = routingByPreference ? ` matched to ${hesc(preferred.join(' + '))}` : '';
+  const fBits = [
+    filters.version && `in ${filters.version}`,
+    filters.discipline && `discipline=${filters.discipline}`,
+    filters.fit && `fit=${filters.fit}`,
+  ].filter(Boolean);
+  const fNote = fBits.length ? ` (${hesc(fBits.join(', '))})` : '';
+
+  // rows — click to claim. Columns: # / Version / Type / Reward /
+  // Est. / What it is (the work lane is its own column, not baked into the title).
+  const taskRow = (t) => {
+    const claimMsg = jsq(`Claim task ${t.id}`);
+    const titleAttr = hesc(`Claim #${t.id}: ${t.title || ''}`);
+    const d = t.discipline;
+    const laneDot = (d && d !== 'unclassified')
+      ? `<span class="bs-lane" style="background:${disciplineColor(d)};"></span>`
+      : '';
+    return `<tr class="bs-tr" role="button" tabindex="0" title="${titleAttr}" onclick="sendPrompt('${claimMsg}')" onkeydown="if(event.key==='Enter'||event.key===' '){event.preventDefault();sendPrompt('${claimMsg}')}">`
+      + TD(`#${hesc(t.id)}`, 'bs-id')
+      + TD(hesc(t.version_id || '?'), 'bs-nowrap')
+      + TD(`${laneDot}${hesc(roleLabel(t) || '—')}`, 'bs-ellip-sub')
+      + TD(hesc((t.credits_reward ?? 0) + 'c'))
+      + TD(hesc(estimateShort(t)), 'bs-sub')
+      + TD(hesc(t.title || ''), 'bs-ellip')
+      + `</tr>`;
+  };
+  // task 1002852: the same rows, grouped under each task's goal ("Other work" last).
+  const rows = startGoals.groupByGoal(claimable, goals).map((g) =>
+    `<tr class="bs-group"><td colspan="6">${hesc(g.title)}${g.joined ? '<span class="bs-sub"> · your goal</span>' : ''}</td></tr>`
+    + g.rows.map(taskRow).join('')).join('');
+  // task 1002852: the goals this builder joined, ABOVE the table (never instead of it).
+  const goalsBlock = yourGoals.goals.length
+    ? `<div class="bs-menuh">Your goals</div>${yourGoals.goals.map((g) =>
+      `<div class="bs-line"><i class="ti ti-target" aria-hidden="true"></i>${hesc(clip(g.title, 60))}<span class="bs-dot"> · </span><span class="bs-sub">${hesc(startGoals.claimableWord(g.claimable))}</span></div>`).join('')}${yourGoals.more ? `<div class="bs-line bs-sub">and ${yourGoals.more} more</div>` : ''}`
+    : '';
+
+  const menu = claimable.length
+    ? `<table class="bs-table">
+    <colgroup><col style="width:44px;"><col style="width:52px;"><col style="width:68px;"><col style="width:48px;"><col style="width:44px;"><col></colgroup>
+    <thead><tr class="bs-thead">${TH('#')}${TH('Version')}${TH(ROLE_AXIS_LABEL)}${TH('Reward')}${TH('Est.')}${TH('What it is')}</tr></thead>
+    <tbody>${rows}</tbody>
+  </table>`
+    : `<div class="bs-line">Nothing claimable right now — everything is in flight, blocked, or shipped. <a href="#" onclick="event.preventDefault();sendPrompt('Run blocker-review')" class="bs-link">See what's stuck ↗</a></div>`;
+
+  // footer actions: a "more" link when the list was capped, then the
+  // cross-lane pointer. (The old "just exploring" link was dropped — not
+  // picking is already "not claiming"; task 1273 follow-up.)
+  const moreCount = Math.max(0, (total || claimable.length) - claimable.length);
+  const moreLink = moreCount > 0
+    ? ` · <a href="#" onclick="event.preventDefault();sendPrompt('${jsq('Show me all ' + (total || '') + ' claimable tasks, not just the top ' + claimable.length)}')" class="bs-link">${moreCount} more — show all ↗</a>`
+    : '';
+  let crossLane = '';
+  if (recommendations.length > 0) {
+    const ids = recommendations.map((t) => '#' + t.id).join(', ');
+    crossLane = ` · <a href="#" onclick="event.preventDefault();sendPrompt('${jsq('Show me the tasks outside my disciplines: ' + ids)}')" class="bs-link">Outside your roles: ${hesc(ids)} ↗</a>`;
+  } else if (routingByPreference) {
+    crossLane = ` · <a href="#" onclick="event.preventDefault();sendPrompt('Show me every role, not just mine')" class="bs-link">Show all roles ↗</a>`;
+  }
+
+  const summary = `builder-start: ${claimable.length} task${claimable.length === 1 ? '' : 's'} you can claim now, plus your current build status. Click a task to claim it.`;
+  return `${WIDGET_STYLE}
+<h2 class="bs-sr">${hesc(summary)}</h2>
+<div class="bs-card">
+  <div class="bs-head">
+    <span class="bs-brand"><span class="bs-title"><i class="ti ti-player-play" aria-hidden="true"></i>builder-start</span>${streakBadge}</span>
+    <span class="bs-meta">${hesc(b.github_login)} · ${hesc(rank)} · ${hesc(credits)} credits · ${hesc(disc)}</span>
+  </div>
+  ${rebaseRow}
+  ${statusRow}
+  ${holdings}
+  ${closeBanner}
+  ${goalsBlock}
+  <div class="bs-menuh">Claim one to start — ${total || claimable.length} ready for you right now${matched}${fNote}</div>
+  ${menu}
+  <div class="bs-foot">Click a task to claim it${moreLink}${crossLane}</div>
+</div>`;
+}
+
+// Cross-discipline recommendations — mirror of
+// rankCrossDisciplineRecommendations in modules/lifecycle/db-tasks.js (the
+// canonical copy; it moved there from src/bongos/db.js in the twelve-unit
+// carve). Given the full claimable list and the builder's
+// preferred_disciplines, return up to `limit` tasks whose discipline is OUTSIDE
+// the builder's preferences, ranked:
+//   priority ASC (unset last), credits/min DESC, est_minutes ASC, id ASC.
+// Priority 1 is the MOST urgent — the DB's own convention (CHECK (priority
+// BETWEEN 1 AND 5), weighted 6 - COALESCE(priority, 5)); an unset priority
+// sorts after an explicit P5, never ahead of a P1.
+// 'unclassified' tasks are excluded (un-triaged, not a real lane). Empty
+// preferences → [] (everything is already in the main list; nothing outside).
+// This copy and the canonical one are pinned together by
+// tests/cross_discipline_priority_direction.mjs — change one, change the other.
+function rankCrossDisciplineRecommendations(claimable, preferredDisciplines, limit = 3) {
+  const rows = Array.isArray(claimable) ? claimable : [];
+  const prefs = Array.isArray(preferredDisciplines) ? preferredDisciplines : [];
+  if (prefs.length === 0) return [];
+  const prefSet = new Set(prefs);
+  const cpm = (t) => {
+    const credits = Number(t.credits_reward) || 0;
+    const mins = Number(t.est_minutes_calibrated ?? t.est_minutes) || 0;
+    return mins > 0 ? credits / mins : 0;
+  };
+  // `ASC NULLS LAST` in JS — an absent/blank/non-numeric priority sorts after
+  // every explicit 1..5. Not `Number(t.priority) || 0`: that maps NULL to 0,
+  // which under an ascending sort outranks a P1.
+  const prio = (t) => {
+    if (t.priority === null || t.priority === undefined || t.priority === '') return Infinity;
+    const n = Number(t.priority);
+    return Number.isFinite(n) ? n : Infinity;
+  };
+  const outside = rows.filter(
+    (t) => t.discipline && t.discipline !== 'unclassified' && !prefSet.has(t.discipline)
+  );
+  outside.sort((a, b) => {
+    const pa = prio(a);
+    const pb = prio(b);
+    if (pa !== pb) return pa - pb;
+    const ca = cpm(a);
+    const cb = cpm(b);
+    if (cb !== ca) return cb - ca;
+    const ma = Number(a.est_minutes_calibrated ?? a.est_minutes) || Infinity;
+    const mb = Number(b.est_minutes_calibrated ?? b.est_minutes) || Infinity;
+    if (ma !== mb) return ma - mb;
+    return (Number(a.id) || 0) - (Number(b.id) || 0);
+  });
+  return outside.slice(0, Math.max(0, limit));
+}
+
+// ---------- environment guard (task 1002403 / goal 1000052) ----------
+// /builder-start is often the FIRST command run in a freshly-cloned instance —
+// before the local server has ever been brought up. When the API can't be
+// reached, guide the builder to the one-command bring-up instead of dying with a
+// raw fetch stack trace (the old failure). The generated client REJECTS on a
+// network error even under throwOnError:false (see clients/bongos-client), so the
+// Promise.all in main() throws into the guard below. Wrong-instance (exit 3) and
+// no-session (exit 2) are handled upstream in cliClient()/apiCall, and the
+// builder-start skill routes those + the pre-install "bongos not found" case.
+function isConnectionError(err) {
+  if (!err) return false;
+  // task 1002670: a dispatcher/argument bug (e.g. a vendored undici Agent the
+  // built-in fetch rejects with UND_ERR_INVALID_ARG) throws before any network
+  // I/O. That is a CLIENT bug — never present it as "instance isn't reachable".
+  if (isDispatcherIncompatError(err)) return false;
+  const codes = ['ECONNREFUSED', 'ENOTFOUND', 'ECONNRESET', 'EAI_AGAIN', 'ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET'];
+  const code = err.code || (err.cause && err.cause.code) || '';
+  if (codes.includes(code)) return true;
+  const msg = `${err.message || ''} ${(err.cause && err.cause.message) || ''}`;
+  return /fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|network|socket hang up/i.test(msg);
+}
+
+// isLocalOrigin — does this origin name a server THIS MACHINE is supposed to run?
+// The whole shape of the unreachable-instance advice turns on it, so it is its own
+// named predicate rather than an inline regex (task 1003675). Anything that is not
+// recognisably loopback is treated as REMOTE: guessing "local" for a hosted board
+// is the failure this exists to prevent, and the remote branch degrades gracefully
+// (it points at a URL) while the local branch would tell someone to stand up a
+// second, empty instance.
+function isLocalOrigin(origin) {
+  if (!origin) return true; // nothing to go on → the old local-first wording
+  let host;
+  try { host = new URL(origin).hostname.toLowerCase(); } catch (_) { return false; }
+  return host === 'localhost' || host.endsWith('.localhost')
+    || host === '127.0.0.1' || host.startsWith('127.') || host === '::1' || host === '[::1]';
+}
+
+// The guided "instance isn't running" card. Markdown (never leads with `<`), so
+// the builder-start skill relays it verbatim even in --widget mode.
+//
+// It branches on WHERE THE BOARD LIVES, because the same words are actively
+// harmful in the two cases (task 1003675 — the owner hit this twice on a hosted
+// instance). A HOSTED instance is not this machine's server to start: `bongos dev`
+// would stand up a separate LOCAL instance with its OWN EMPTY DATABASE, so a
+// builder who follows it obediently arrives at a board that is not theirs and the
+// real outage stays hidden behind it. The hosted branch therefore leads with the
+// thing that needs nothing installed — the board is a website — and offers the
+// health probe instead of a bring-up.
+//
+// The local branch is unchanged, and still tailors its first step to whether deps
+// are installed: a fresh clone needs `npm install` before the `bongos` CLI (which
+// ships inside the PRIVATE @bongos/core package) even exists.
+function instanceNotRunningCard({ origin, depsMissing } = {}) {
+  const out = [];
+  out.push(surface.strong("builder-start — this instance isn't reachable yet"));
+  out.push('');
+
+  if (!isLocalOrigin(origin)) {
+    out.push(`I couldn't reach ${surface.code(origin)}. That instance is ${surface.strong('hosted')} — it isn't this machine's server to start, so there's nothing to bring up here.`);
+    out.push('');
+    out.push(`1. ${surface.strong('The board is a website, and it needs nothing installed')} — open ${origin}/builders to see and claim work right now.`);
+    out.push(`2. If that doesn't load either, the instance itself is down: \`curl -sI ${origin}/healthz\` says whether it's answering.`);
+    out.push(`3. Once it answers, re-run ${surface.code(surface.action('start'))}.`);
+    out.push('');
+    out.push(`${surface.strong(`Don't run ${surface.code(surface.cli('dev'))} for this.`)} It stands up a separate local instance with its own empty database — it cannot show you this board, and it would hide the outage behind an empty one.`);
+    if (depsMissing) {
+      out.push('');
+      out.push(`(The ${surface.code('bongos')} CLI isn't installed here. It's optional — the website above is the same board. ${surface.code('@bongos/core')} is ${surface.strong('public')} on npm, so ${surface.code('npm install @bongos/core')} needs no token or login; a failure here is a real error, not the expected tokenless 404 it used to be.)`);
+    }
+    return out.join('\n');
+  }
+
+  out.push(`I couldn't reach the Cloud Bongos instance${origin ? ` at \`${origin}\`` : ''}. On a freshly-cloned project that almost always just means it hasn't been brought up yet. To start it locally:`);
+  out.push('');
+  let n = 1;
+  if (depsMissing) {
+    out.push(`${n++}. \`npm install\` — installs the toolchain first (the \`bongos\` CLI ships inside \`@bongos/core\`, so nothing else runs until this does).`);
+  }
+  out.push(`${n++}. ${surface.code(surface.cli('dev'))} — one command: starts Postgres, builds the tables, runs the server, and signs you in.`);
+  out.push(`${n++}. Re-run ${surface.code(surface.action('start'))}.`);
+  out.push('');
+  out.push(`Meant to work on a *different* instance that's already running? Sign in to it with ${surface.code(surface.cli('login <url>'))} first.`);
+  return out.join('\n');
+}
+function emitInstanceNotRunningCard(opts) {
+  console.log(instanceNotRunningCard(opts));
+}
+
+async function main() {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const versionIdx = args.indexOf('--version');
+  const version = versionIdx >= 0 ? args[versionIdx + 1] : null;
+  const disciplineIdx = args.indexOf('--discipline');
+  const discipline = disciplineIdx >= 0 ? args[disciplineIdx + 1] : null;
+  const allDisciplines = args.includes('--all-disciplines');
+  const fitIdx = args.indexOf('--fit');
+  const fit = fitIdx >= 0 ? args[fitIdx + 1] : null;
+  const limitIdx = args.indexOf('--limit');
+  const limit = limitIdx >= 0 ? Number(args[limitIdx + 1]) : 10;
+  // --full restores the detailed ambient widgets + context pack that the lean
+  // card omits (task 1273). Default is the lean card.
+  const full = args.includes('--full');
+  // --widget emits the card as self-contained HTML on stdout for the app's
+  // widget renderer (task 1273). Private warnings go to stderr so stdout stays
+  // pure HTML the skill can pipe verbatim.
+  const widget = args.includes('--widget');
+  // --hook (task 1288): machine envelope for the builder-start-card hook — both
+  // card forms (HTML + markdown) + the private warnings from a single fetch, so
+  // the hook can hand the model a finished card it only has to render. Not a
+  // user surface; stdout is the JSON envelope only.
+  const hookMode = args.includes('--hook');
+
+  // Server-side filtering: only push an explicit --discipline (single-lane
+  // override). Preference-based routing is done client-side below, because
+  // (a) a builder can prefer BOTH disciplines and the server filter takes a
+  // single value, and (b) the "You might enjoy" section needs the full
+  // claimable set (across all disciplines) to compute recommendations from.
+  const claimableQuery = {};
+  if (version) claimableQuery.version = version;
+  if (discipline) claimableQuery.discipline = discipline;
+  if (fit) claimableQuery.fit = fit;
+
+  // Fire everything in parallel. Header widgets are non-critical — if any
+  // endpoint fails, that widget degrades to "N/A" rather than killing
+  // /builder-start.
+  const api = await cliClient();
+  let me, r, closeRes, progressRes, costRes, recentRes, inboxRes, blockersRes, goalsRes;
+  try {
+    [me, r, closeRes, progressRes, costRes, recentRes, inboxRes, blockersRes, goalsRes] = await Promise.all([
+      api.me.getMe(),
+      api.tasks.getTasksClaimable({ query: claimableQuery }),
+      api.versions.getVersionsCloseSuggestions(),
+      api.public.getPublicProgress(),
+      api.public.getPublicCostSummary(),
+      api.public.getPublicRecentShipped(),
+      api.inbox.getInbox({ query: { status: 'open' } }),
+      api.blockers.getBlockers(),
+      // task 1002852: best-effort — a failed goals read leaves the table flat-grouped by id.
+      api.goals.getGoals({ query: { status: 'open' } }).catch(() => ({ ok: false })),
+    ]);
+  } catch (err) {
+    // A fresh-clone instance that was never brought up refuses the connection.
+    // Human modes get a guided bring-up card + clean exit; machine modes (--json,
+    // --hook) keep the throw so the autonomous runner still sees the failure.
+    if (isConnectionError(err) && !json && !hookMode) {
+      let depsMissing = false;
+      try { depsMissing = depsFinding({ repoRoot: process.cwd() }).level !== 'ok'; } catch (_) { /* best-effort */ }
+      let origin = '';
+      try { origin = new URL(API_BASE).origin; } catch (_) { origin = API_BASE || ''; }
+      emitInstanceNotRunningCard({ origin, depsMissing });
+      process.exit(0);
+    }
+    throw err;
+  }
+  // #766: the primer-read gate on the claimable endpoint was removed, so a
+  // newcomer no longer gets a 403 stage_required here. A generic stage_required
+  // (any future onboarding gate) still renders cleanly rather than crashing.
+  // ADR 0116 nests the slug and its payload — see the note in cli-lib errCode (task
+  // 1003658). The onboarding copy lives in error.details, so reading it off the top
+  // level rendered an empty prompt even when the branch fired.
+  if (r.status === 403 && errCode(r.data) === 'stage_required') {
+    const d = errDetails(r.data);
+    console.log('');
+    console.log(d.what_to_do || `Clear "${d.required_stage_label || d.required_stage}" before the work queue opens.`);
+    for (const line of plainCardLines('stage_required')) console.log(line);
+    console.log('');
+    process.exit(0);
+  }
+  if (!r.ok) {
+    console.error(`failed (${r.status}):`, r.data);
+    for (const line of plainCardLines('board_unavailable')) console.error(line);
+    process.exit(1);
+  }
+
+  // Full claimable set as returned by the server (already filtered for
+  // touches[] safety, version/fit, and any explicit --discipline).
+  const rawClaimable = r.data.claimable || [];
+
+  // Discipline routing (V3.R81 / #299). preferred_disciplines lives on the
+  // builder row (migration 027), surfaced via /api/bongos/me.
+  const preferred = (me.ok && Array.isArray(me.data?.builder?.preferred_disciplines))
+    ? me.data.builder.preferred_disciplines
+    : [];
+  // Apply preference narrowing unless the builder explicitly opted out
+  // (--all-disciplines), explicitly chose a single lane (--discipline X,
+  // already applied server-side), or stated no preference.
+  const routingByPreference = !allDisciplines && !discipline && preferred.length > 0;
+  const filtered = routingByPreference
+    ? rawClaimable.filter((t) => preferred.includes(t.discipline))
+    : rawClaimable;
+  // task 1002852: goal-first. The open goals (with the server's viewer_is_member)
+  // group the table and put the builder's joined goals' rows ahead of the cap.
+  const goals = goalsRes && goalsRes.ok && Array.isArray(goalsRes.data?.goals) ? goalsRes.data.goals : [];
+  const claimable = startGoals.joinedFirst(filtered, goals).slice(0, limit);
+
+  // "You might enjoy" — up to 3 claimable tasks outside the builder's lanes.
+  // Computed from the FULL set so it can reach across disciplines. Suppressed
+  // when an explicit single-lane --discipline filter is in play (the builder
+  // asked to see exactly one lane) — but shown for --all-disciplines and the
+  // default preference-routed view.
+  const recommendations = discipline
+    ? []
+    : rankCrossDisciplineRecommendations(rawClaimable, preferred, 3);
+
+  // Close-suggestions endpoint is non-critical; if it fails (e.g. older
+  // server without the route), surface no banner rather than blowing up.
+  const closeSuggestions = closeRes.ok && Array.isArray(closeRes.data?.suggestions)
+    ? closeRes.data.suggestions
+    : [];
+  const readyToClose = closeSuggestions.filter((s) => s.ready);
+  const yourGoals = startGoals.yourGoals(goals, filtered);
+
+  // Header widget data (each independently optional).
+  const progress = progressRes.ok && Array.isArray(progressRes.data?.progress) ? progressRes.data.progress : null;
+  const cost = costRes.ok ? costRes.data : null;
+  const recentShipped = recentRes.ok && Array.isArray(recentRes.data?.tasks) ? recentRes.data.tasks : null;
+  const inboxCount = inboxOpenCount(inboxRes);
+  const blockerCount = blockersRes.ok && Array.isArray(blockersRes.data?.blockers)
+    ? blockersRes.data.blockers.filter((b) => b.status === 'open' || !b.status).length
+    : null;
+
+  // ADR 0120 part 5: the confirmed tasks this builder owes a rebase on (they
+  // GATE new claims; the reward lands only on ship). Shared by every card form;
+  // already present verbatim in --json via me.data.needs_rebase_tasks below.
+  const needsRebaseTasks = me.ok && Array.isArray(me.data?.needs_rebase_tasks)
+    ? me.data.needs_rebase_tasks
+    : [];
+
+  if (json) {
+    console.log(JSON.stringify(
+      {
+        me: me.data,
+        claimable,
+        recommendations,
+        your_goals: yourGoals.goals,
+        discipline_routing: {
+          preferred_disciplines: preferred,
+          applied: routingByPreference,
+          all_disciplines: allDisciplines,
+          explicit_discipline: discipline || null,
+        },
+        close_suggestions: closeSuggestions,
+        header: {
+          progress,
+          cost,
+          recent_shipped: recentShipped,
+          inbox_count: inboxCount,
+          blocker_count: blockerCount,
+        },
+      },
+      null, 2
+    ));
+    return;
+  }
+
+  // ---------- widget (HTML for the app renderer) ----------
+  // task 1279 / 1002518: the per-builder card-richness level. Below the widget
+  // rung, even an explicit --widget request degrades to the markdown card below
+  // — so no HTML is emitted, read, or re-relayed (a real token saving, not just
+  // a visual change). /me carries the resolved level; an older instance carries
+  // only the boolean and cardFlagsFromMe reads either. Headless/cron callers
+  // don't pass --widget at all (no renderer), so they're unaffected.
+  //
+  // The `minimal` rung lands on the markdown card here rather than on nothing:
+  // the lifecycle card has a guaranteed one-line confirmation to fall back to,
+  // and this card — the list of what you can claim — has no such floor. Dropping
+  // it would leave a session opening with no answer to the question it asked.
+  const widgetsPref = me.ok ? cardFlagsFromMe(me).showWidget : true;
+  if (widget && widgetsPref) {
+    const myClaims = me.ok ? (me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : [])) : [];
+    // Private warnings (budget / onboarding next-stage) → stderr, so stdout
+    // stays pure HTML the skill can pipe straight into show_widget.
+    if (me.ok) {
+      const warnings = captureLog(() => { printOnboardingNudge(me.data); printCostWarning(me.data); printNeedsNudge(me.data); });
+      for (const w of warnings) process.stderr.write(w + '\n');
+    }
+    emitCardDirective('html');
+    process.stdout.write(renderWidget({
+      builder: me.ok ? me.data.builder : {},
+      claims: myClaims,
+      claimable: claimable.slice(0, CARD_ROWS),
+      total: filtered.length,
+      streak: me.ok ? me.data.streak : null,
+      recommendations,
+      header: { progress, recentShipped, inboxCount, blockerCount },
+      routingByPreference,
+      preferred,
+      filters: { version, discipline, fit },
+      readyToClose,
+      needsRebaseTasks,
+      goals,
+      yourGoals,
+    }) + '\n');
+    return;
+  }
+
+  // ---------- the card (default) ----------
+  // task 1288: the markdown card body, lifted into a closure so the --hook
+  // envelope can capture it (via captureLog) next to the widget HTML from the
+  // single fetch above; the normal markdown path just calls it below. The body
+  // is kept VERBATIM (same indentation) so this stays a pure wrap+call with zero
+  // change to the shipped card. Closes over the locals computed above. (task
+  // 1273: relaying this verbatim is what keeps the card identical every session;
+  // `--full` adds the ambient widgets + context pack.)
+  const emitMarkdownCard = () => {
+  // V3.R13 (#237): one-line "next stage" nudge for newcomers. Silent for
+  // graduated builders and anyone past first_ship.
+  if (me.ok) printOnboardingNudge(me.data);
+  // task 1013 / ADR 0073: flag any input the system needs from the builder
+  // (e.g. their own image-generation key once free coverage ends). Silent unless
+  // something is in the action_needed state.
+  if (me.ok) printNeedsNudge(me.data);
+
+  // identity line
+  if (me.ok) {
+    const b = me.data.builder;
+    const rankLabel = b.rank ? b.rank.charAt(0).toUpperCase() + b.rank.slice(1) : 'Thetes';
+    const discLabel = Array.isArray(b.preferred_disciplines) && b.preferred_disciplines.length
+      ? b.preferred_disciplines.join(' + ')
+      : 'all disciplines';
+    const credits = Number(b.total_credits || 0).toLocaleString();
+    console.log(`${surface.strong('builder-start')} · ${b.github_login} (${rankLabel}) · ${credits} credits · ${discLabel}`);
+    const sk = me.data.streak;
+    if (sk && Number(sk.current) > 0) {
+      console.log(`🔥 ${sk.current}-day streak${Number(sk.longest) > Number(sk.current) ? ` · longest ${sk.longest}` : ''}`);
+    }
+  }
+
+  // ADR 0120 part 5: the owed-rebase gate warning — rendered directly under the
+  // identity line and before the claimable table, since it BLOCKS new claims
+  // until the builder lands (`git merge origin/main` + re-ship — task 1002788:
+  // MERGE, because the branch is already published and the server's publish is
+  // append-only, so a rebase makes it permanently un-pushable) or releases them.
+  const rebaseLine = rebaseWarningMarkdown(needsRebaseTasks);
+  if (rebaseLine) {
+    console.log('');
+    console.log(rebaseLine);
+  }
+
+  // ambient status: one quiet line by default; the full widgets + context pack
+  // under --full.
+  if (full) {
+    const rows = [
+      formatVersionsRow(progress),
+      formatCostRow(cost),
+      formatRecentRow({ recentShipped, inboxCount, blockerCount }),
+    ].filter(Boolean);
+    if (rows.length) console.log(rows.join('\n'));
+    // Worktree root (the #1 wrong-path footgun) + API prefix/enums. Also printed
+    // at /builder-claim, where it matters most; here it's --full-only detail.
+    try {
+      console.log('');
+      console.log(formatContextPackCompact(contextPack()));
+    } catch (_) { /* fail-open */ }
+  } else {
+    const status = quietStatusLine({ progress, recentShipped, inboxCount, blockerCount });
+    if (status) console.log(status);
+  }
+  console.log('');
+
+  // V3.R84 (#302), criterion C3: private session-start budget ping. The CLI is
+  // the builder's private channel, so the soft-cap (80%) warning / hard-cap
+  // (100%) refusal surface here rather than via Discord (a shared mirror).
+  if (me.ok) printCostWarning(me.data);
+
+  // your holdings — calm + factual, with quick actions off each held task.
+  // Parallel sessions under one builder are normal, so this informs (it does
+  // not block — feedback_parallel_sessions). Ids are hall links (ref rule).
+  if (me.ok) {
+    const myClaims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
+    const heldActions = (id) => `    → ship: ${surface.code(surface.action('ship', id))}`
+      + `  ·  release: ${surface.code(surface.action('release', id))}`
+      + `  ·  open: ${surface.taskRef(id, HALL_TASK)}`;
+    if (myClaims.length === 1) {
+      const c = myClaims[0];
+      console.log(`You're holding ${surface.taskRef(c.task_id, HALL_TASK)} — ${clip(c.title, 56)}`);
+      console.log(heldActions(c.task_id));
+      console.log('');
+    } else if (myClaims.length > 1) {
+      console.log(`You're holding ${myClaims.length} claims (parallel sessions OK):`);
+      for (const c of myClaims) {
+        console.log(`  ${surface.taskRef(c.task_id, HALL_TASK)} — ${clip(c.title, 50)}`);
+        console.log(heldActions(c.task_id));
+      }
+      console.log('');
+    }
+  }
+
+  // Version-close gate banner — informational; fires rarely (an Archon action)
+  // when a building version is >= 80% weighted AND every criterion is satisfied.
+  for (const s of readyToClose) {
+    console.log(
+      `🚦 ${s.versionId} looks ready to close ` +
+      `(${s.criteriaSatisfied}/${s.criteriaTotal} criteria, ${s.percentComplete}% weighted; ` +
+      `${s.tasksShipped} shipped, ${s.tasksCarryOver} carry-over). Run ${surface.action('version-close', s.versionId)}.`
+    );
+    console.log('');
+  }
+
+  // ---------- the menu ----------
+  const matched = routingByPreference ? ` matched to ${preferred.join(' + ')}` : '';
+  const filterBits = [
+    version && `in ${version}`,
+    discipline && `discipline=${discipline}`,
+    fit && `fit=${fit}`,
+  ].filter(Boolean);
+  const filterNote = filterBits.length ? ` (${filterBits.join(', ')})` : '';
+  // task 1002852: the goals this builder joined, above the table (never instead of it).
+  if (yourGoals.goals.length) {
+    console.log(surface.strong('Your goals'));
+    for (const g of yourGoals.goals) console.log(`  ${clip(g.title, 60)} · ${startGoals.claimableWord(g.claimable)}`);
+    if (yourGoals.more) console.log(`  and ${yourGoals.more} more`);
+    console.log('');
+  }
+  console.log(`${surface.strong('Claim one to start')} — ${filtered.length} ready for you right now${matched}${filterNote}:`);
+  console.log('');
+  if (claimable.length) {
+    const cardRows = claimable.slice(0, CARD_ROWS);
+    console.log(claimableTable(cardRows, me.ok ? me.data?.reward : null, goals));
+    const moreN = filtered.length - cardRows.length;
+    if (moreN > 0) {
+      console.log('');
+      console.log(surface.em(`…and ${moreN} more — say "show all", or run with --limit 30.`));
+    }
+  } else {
+    console.log(surface.em(
+      "Nothing claimable right now — everything is in flight, blocked, or shipped."
+      + (surface.isTerminal() ? '' : " Run /blocker-review to see what's stuck.")
+    ));
+  }
+
+  // Cross-discipline pointer (one line) — only when preference-routed.
+  if (recommendations.length > 0) {
+    const ids = recommendations.map((t) => `#${t.id}`).join(', ');
+    console.log('');
+    console.log(`Outside your roles: ${ids} — say the word to see them, or run with \`--all-disciplines\`.`);
+  } else if (routingByPreference) {
+    console.log('');
+    console.log('_Showing your roles — run with `--all-disciplines` to see every role._');
+  }
+
+  // ---------- next ----------
+  console.log('');
+  console.log(`→ ${surface.isTerminal() ? `Claim one with ${surface.code(surface.cli('claim <id>'))} in a checkout` : `${surface.strong('Tell me a number')} to claim it`}.`);
+  if (full) {
+    console.log('');
+    console.log('Commands:');
+    console.log('  claim:    node scripts/bongos/claim.js <task-id> [--worktree NAME]');
+    console.log('  ship:     node scripts/bongos/ship.js  <task-id> --notes "..." --summary "..."');
+    console.log('  release:  node scripts/bongos/release.js <task-id>');
+  }
+  };
+
+  // --hook (task 1288): a UserPromptSubmit hook can neither render UI, call
+  // show_widget, nor detect whether that tool exists — only the model can. So
+  // the hook runs THIS script and injects the finished card + a one-step
+  // directive; the model's only remaining job is to emit it. Emit BOTH forms
+  // (+ the private budget/onboarding warnings) from the single fetch above as a
+  // machine envelope; stdout carries nothing else.
+  if (hookMode) {
+    const myClaims = me.ok ? (me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : [])) : [];
+    const html = widgetsPref
+      ? renderWidget({
+        builder: me.ok ? me.data.builder : {},
+        claims: myClaims,
+        claimable: claimable.slice(0, CARD_ROWS),
+        total: filtered.length,
+        streak: me.ok ? me.data.streak : null,
+        recommendations,
+        header: { progress, recentShipped, inboxCount, blockerCount },
+        routingByPreference,
+        preferred,
+        filters: { version, discipline, fit },
+        readyToClose,
+        needsRebaseTasks,
+        goals,
+        yourGoals,
+      })
+      : null;
+    const markdown = captureLog(emitMarkdownCard).join('\n');
+    const warnings = me.ok
+      ? captureLog(() => { printOnboardingNudge(me.data); printCostWarning(me.data); printNeedsNudge(me.data); })
+      : [];
+    process.stdout.write(JSON.stringify({ widgets_enabled: widgetsPref, html, markdown, warnings }) + '\n');
+    return;
+  }
+
+  // Markdown card path — default invocation, `--full`, or `--widget` with the
+  // widgets knob off. The relay directive goes to stderr (task 1282); the card
+  // body to stdout.
+  emitCardDirective('markdown');
+  emitMarkdownCard();
+}
+
+// Only auto-run when invoked directly (`node start.js …`); a `require()` (the
+// unit test) imports the pure render helpers without executing the fetch flow —
+// the claim.js precedent. The owed-rebase warning helpers (ADR 0120 part 5) are
+// exported so they can be unit-tested without a live server, and so is
+// rankCrossDisciplineRecommendations — the mirror test executes THIS copy
+// alongside the canonical one rather than pattern-matching the source.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  inboxOpenCount,
+  rankCrossDisciplineRecommendations,
+  rebaseWarningModel,
+  rebaseWarningMarkdown,
+  rebaseWarningWidget,
+  isConnectionError,
+  instanceNotRunningCard,
+  isLocalOrigin,
+};