@bongos/core 1.17.0

package/modules/lifecycle/routes/versions.js

@@ -0,0 +1,128 @@
+const express = require('express');
+// Intra-module + the published doorway — a module never requires a core internal.
+const api = require('../../../src/module-api');
+const auth = api;
+const db = require('../db');
+const versionClose = require('../version-close');
+const doneWhen = require('../done-when');
+const { asyncHandler, validateOrRespond } = api;
+
+// versions.status CHECK (migration 003). A new version starts 'planning' or
+// 'building'; 'shipped'/'frozen' are end states reached via the close flow.
+const VALID_VERSION_STATUSES = new Set(['planning', 'building', 'shipped', 'frozen']);
+
+module.exports = function buildVersionsRouter() {
+  const router = express.Router();
+
+  // rank: public — read-only version list; mirrors /public/versions. Preserved
+  // unauthenticated per CRITICAL §1 (matches current production behavior).
+  router.get('/versions', async (req, res) => {
+    // R14 (#2001 / ADR 0119): adopt the shared pagination contract (was unbounded).
+    // The version list is small, so fetch + slice; `page` is additive (readers of
+    // .versions are unchanged).
+    const { limit, offset } = api.parsePagination(req);
+    const all = await db.listVersions();
+    res.json({ versions: all.slice(offset, offset + limit), page: api.pageMeta(limit, offset, all.length) });
+  });
+
+  // rank: public — read-only progress aggregate; mirrors /public/progress.
+  router.get('/versions/progress', async (_req, res) => {
+    const progress = await db.versionProgress();
+    res.json({ progress });
+  });
+
+  // Close-flow gate suggestions for every version still 'building'.
+  // Used by /builder-start to surface the "ready to close" banner.
+  // rank: public — read-only close-flow hints; consumed by /builder-start banner.
+  // Preserved unauthenticated to match current behavior; non-sensitive aggregate.
+  router.get('/versions/close-suggestions', asyncHandler('GET /versions/close-suggestions', async (_req, res) => {
+    const suggestions = await versionClose.getCloseSuggestionsForBuildingVersions();
+    res.json({ suggestions });
+  }, { errorCode: 'close_suggestions_failed' }));
+
+  // Per-criterion progress rollup: each done-when criterion → the tasks that
+  // gate it (task_criteria, migration 055) → live statuses → what remains.
+  // Powers `scripts/gds/status.js` + the /status skill (#435) and is reusable
+  // by the public status dashboard. Registered AFTER the static /versions/*
+  // routes above so ':id' can't swallow them.
+  // rank: public — read-only aggregate, same posture as /versions/:id/done-when.
+  // Public endpoint — asyncHandler logs the detail server-side but, with
+  // message:false, never leaks err.message (SQL/internal text) to unauthenticated
+  // callers (preserves the leak-safe 500 the hand-written catch produced).
+  router.get('/versions/:id/progress', asyncHandler('GET /versions/:id/progress', async (req, res) => {
+    const versionId = String(req.params.id || '').trim();
+    if (!versionId) return res.fail('version_id_required', 400);
+    const progress = await doneWhen.criterionProgress(versionId);
+    res.set('Cache-Control', 'public, max-age=60');
+    res.json(progress);
+  }, { message: false, errorCode: 'progress_failed' }));
+
+  // POST /versions — create a version + its done-when criteria in one call. The
+  // seed primitive `bongos init` (task 1204 / R65) uses so a fresh instance needs
+  // no hand-written seed-*.js script. Archon-only: creating a version is a
+  // plan/scope mutation, same gate as POST /tasks (ADR 0016).
+  // rank: archon — creates a version + its done-when criteria.
+  router.post('/versions', auth.requireBuilder, auth.requireRank('archon'), asyncHandler('POST /versions', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      id: { required: true, type: 'string', maxLength: 64, minLength: 1 },
+      name: { required: true, type: 'string', maxLength: 200, minLength: 1 },
+      status: { type: 'string', maxLength: 32 },
+      done_when: { type: 'string', maxLength: 8000 },
+      scope_doc_path: { type: 'string', maxLength: 256 },
+      criteria: { type: 'array', maxItems: 100 },
+    })) return;
+    const body = req.body || {};
+    const id = String(body.id).trim();
+    const name = String(body.name).trim();
+    if (!id || !name) return res.fail('id_and_name_required', 400);
+
+    const status = body.status || 'planning';
+    if (!VALID_VERSION_STATUSES.has(status)) {
+      return res.fail('bad_status', 400, { valid: Array.from(VALID_VERSION_STATUSES) });
+    }
+
+    if (await db.getVersion(id)) {
+      return res.fail('version_exists', { status: 409, message: `Version '${id}' already exists.` });
+    }
+
+    // Normalize criteria: each { criterion_id, criterion_md } (+ optional sort_order).
+    const rawCriteria = Array.isArray(body.criteria) ? body.criteria : [];
+    const criteria = [];
+    for (let i = 0; i < rawCriteria.length; i++) {
+      const c = rawCriteria[i];
+      if (!c || typeof c !== 'object') return res.fail('bad_criterion', 400, { index: i });
+      const criterionId = String(c.criterion_id || '').trim();
+      const criterionMd = String(c.criterion_md || '').trim();
+      if (!criterionId || !criterionMd) return res.fail('criterion_needs_id_and_md', 400, { index: i });
+      criteria.push({
+        criterion_id: criterionId,
+        criterion_md: criterionMd,
+        sort_order: Number.isFinite(c.sort_order) ? c.sort_order : (i + 1) * 10,
+      });
+    }
+
+    let version, created;
+    try {
+      ({ version, criteria: created } = await db.createVersion({
+        id, name, status,
+        doneWhen: body.done_when ?? null,
+        scopeDocPath: body.scope_doc_path ?? null,
+        criteria,
+      }));
+    } catch (err) {
+      // TOCTOU: the getVersion() pre-check above runs outside the insert
+      // transaction, so two concurrent creates of the same id can both clear it;
+      // the versions primary key is the real guard. Translate the race-loser's
+      // unique-violation (Postgres 23505) into the same clean 409 the pre-check
+      // returns, instead of letting asyncHandler surface a 500 (hacker dispatch,
+      // task 1204).
+      if (err && err.code === '23505') {
+        return res.fail('version_exists', { status: 409, message: `Version '${id}' already exists.` });
+      }
+      throw err;
+    }
+    res.status(201).json({ version, criteria: created });
+  }, { errorCode: 'create_version_failed' }));
+
+  return router;
+};

package/modules/lifecycle/ship-card.js

@@ -0,0 +1,505 @@
+// src/bongos/ship-card.js — the deterministic lifecycle card (tasks 1270 + 1275).
+//
+// The owner's ask: stop the agent writing a fresh, obligatory-to-read prose recap
+// at task boundaries. Replace it with ONE card whose SHAPE is identical every time
+// — only the data swaps — and have the SAME card companion a task through its whole
+// pipeline (claimed → in review → confirmed → shipped, or grade-failed), adapting
+// banner / facts / action to what matters at each stage. Design locked with the
+// owner over a live in-feed mockup pass.
+//
+// ONE generator, two render paths, both PURE:
+//   renderMonospaceCard(model) — alignment-proof left-rule text. The CLIs ALWAYS
+//     print this, so headless / cron / dev-box runs and feeds without the in-feed
+//     visualization tool still get a consistent summary.
+//   renderCardHtml(model)      — the populated, branded HTML the skills render in
+//     the chat feed via the visualization tool (show_widget). Brand tokens come
+//     from config/branding.json via src/branding.js (correct per-instance).
+//
+// buildCardModel() normalizes raw stage data into the model both consume.
+// emitCard() is the one I/O helper the CLIs share (print monospace + write HTML +
+// print the [otb-card-html] marker the skills pick up).
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { branding } = require('../../src/module-api');
+
+// tone -> the widget's banner color family. 'neutral' has no semantic CSS var, so
+// every tone resolves through this map (never `--color-background-${tone}`).
+const TONE = Object.freeze({
+  success: { bg: 'var(--color-background-success)', fg: 'var(--color-text-success)' },
+  info: { bg: 'var(--color-background-info)', fg: 'var(--color-text-info)' },
+  warning: { bg: 'var(--color-background-warning)', fg: 'var(--color-text-warning)' },
+  danger: { bg: 'var(--color-background-danger)', fg: 'var(--color-text-danger)' },
+  neutral: { bg: 'var(--color-background-secondary)', fg: 'var(--color-text-primary)' },
+});
+
+// Per-stage chrome: tone, icon (Tabler outline, loaded in the widget runtime),
+// the monospace status word, and the headline. Every card draws the SAME full
+// lifecycle trail (see PIPELINE) from the get-go; a stage only declares WHERE it
+// sits on it:
+//   `at`          — index of the current node in PIPELINE
+//   `currentKind` — how that current node reads:
+//       'done'   → a finished milestone: checked + past tense (claimed, shipped)
+//       'active' → in progress right now: present continuous (reviewing, shipping)
+//       'failed' → the grade failed here: the word 'grade failed', unchecked
+// Nodes before `at` are always done (checked + past tense); nodes after are
+// always future (dimmed bare verb). The stages never change between cards — only
+// the tense, checks, and boldness move (the design task 1489 locked).
+const STAGES = Object.freeze({
+  claimed: {
+    tone: 'neutral', icon: 'ti-flag-3', statusWord: 'Claimed',
+    headline: (id) => `Task #${id} claimed`,
+    at: 0, currentKind: 'done',
+  },
+  review: {
+    tone: 'warning', icon: 'ti-eye', statusWord: 'In review',
+    headline: (id) => `Task #${id} ready for your review`,
+    at: 2, currentKind: 'active',
+  },
+  confirmed: {
+    tone: 'info', icon: 'ti-progress-check', statusWord: 'Confirmed',
+    headline: (id) => `Task #${id} confirmed — landing`,
+    // confirm is DONE at this stage (credits already awarded); the live step is
+    // landing → ship. The cursor sits on 'ship' (active → 'shipping'), not on
+    // 'confirm', so the trail agrees with the "confirmed — landing" banner:
+    // '…completed ✓ → confirmed ✓ → shipping' (vs the old, contradictory
+    // '…completed ✓ → confirming → ship'). 'shipping' (active) stays distinct
+    // from the shipped stage's checked 'shipped' (done).
+    at: 5, currentKind: 'active',
+  },
+  shipped: {
+    tone: 'success', icon: 'ti-circle-check', statusWord: 'Shipped',
+    headline: (id) => `Task #${id} shipped to production`,
+    at: 5, currentKind: 'done',
+  },
+  failed: {
+    tone: 'danger', icon: 'ti-alert-triangle', statusWord: 'Needs fixes',
+    headline: (id) => `Task #${id} grade failed`,
+    at: 4, currentKind: 'failed',
+  },
+});
+
+// Map a post-grade task status to a ship-family card stage. (claimed/review are
+// set explicitly by their call sites, not derived from a DB status.)
+function stageFor(postGradeStatus) {
+  if (postGradeStatus === 'shipped') return 'shipped';
+  if (postGradeStatus === 'confirmed') return 'confirmed';
+  return 'failed';
+}
+
+// The one canonical journey every card draws, in order. Each node conjugates to
+// three forms — done (past participle), active (present continuous), future (bare
+// verb) — so the same stage reads 'built' / 'building' / 'build' depending on
+// where the task is. 'grade failed' is the failure form shown at the confirm node
+// when the grade doesn't pass.
+const PIPELINE = ['claim', 'build', 'review', 'complete', 'confirm', 'ship'];
+const FORMS = Object.freeze({
+  claim: { done: 'claimed', active: 'claiming', future: 'claim' },
+  build: { done: 'built', active: 'building', future: 'build' },
+  review: { done: 'reviewed', active: 'reviewing', future: 'review' },
+  complete: { done: 'completed', active: 'completing', future: 'complete' },
+  confirm: { done: 'confirmed', active: 'confirming', future: 'confirm' },
+  ship: { done: 'shipped', active: 'shipping', future: 'ship' },
+});
+const GRADE_FAILED = 'grade failed';
+
+// The journey, mapped: one entry per PIPELINE node, conjugated + classified by
+// position relative to the current node (`cfg.at`). Both renderers consume this
+// so the HTML ribbon and the monospace trail can never drift.
+//   { word, state: 'done' | 'current' | 'future', checked, bold }
+// Nodes before `at` are done (checked + past). The current node reads per
+// `cfg.currentKind`: a finished milestone ('done': claimed/shipped) is checked +
+// past tense; an in-progress node ('active') is present continuous; a failed
+// grade ('failed') shows 'grade failed', unchecked. Nodes after `at` are future.
+function trailSteps(cfg) {
+  const at = cfg.at;
+  return PIPELINE.map((key, i) => {
+    const f = FORMS[key];
+    if (i < at) return { word: f.done, state: 'done', checked: true, bold: false };
+    if (i === at) {
+      if (cfg.currentKind === 'failed') return { word: GRADE_FAILED, state: 'current', checked: false, bold: true };
+      if (cfg.currentKind === 'done') return { word: f.done, state: 'current', checked: true, bold: true };
+      return { word: f.active, state: 'current', checked: false, bold: true }; // 'active'
+    }
+    return { word: f.future, state: 'future', checked: false, bold: false };
+  });
+}
+
+// ---- formatters ----
+function fmtInt(n) {
+  if (n == null || !Number.isFinite(Number(n))) return null;
+  return Number(n).toLocaleString('en-US');
+}
+function fmtTokens(n) {
+  if (n == null || !Number.isFinite(Number(n))) return null;
+  n = Number(n);
+  if (n >= 1e6) return (n / 1e6).toFixed(2).replace(/\.?0+$/, '') + 'M';
+  if (n >= 1e3) {
+    // Round to K, but if that rounds up to 1000K (e.g. 999500), promote to M so
+    // the label reads "1M" not "1000K".
+    const k = Math.round(n / 1e3);
+    if (k >= 1000) return (n / 1e6).toFixed(2).replace(/\.?0+$/, '') + 'M';
+    return k + 'K';
+  }
+  return String(Math.round(n));
+}
+function fmtUsd(n) {
+  if (n == null || !Number.isFinite(Number(n))) return null;
+  n = Number(n);
+  if (n > 0 && n < 0.01) return '<$0.01';
+  return '$' + n.toFixed(2);
+}
+function fmtMins(n) {
+  if (n == null || !Number.isFinite(Number(n))) return null;
+  n = Number(n);
+  if (n < 60) return `~${n}m`;
+  const h = Math.floor(n / 60);
+  const m = n % 60;
+  return m ? `~${h}h${m}m` : `~${h}h`;
+}
+
+const DISCIPLINE_SKILL = { engineer: 'dev', artist: 'paint', ideator: 'ideate' };
+
+// The next-action per stage: { kind:'prompt', label, cmd } or { kind:'link', label, url }.
+function nextActionFor(stage, { taskId, discipline, sandboxUrl } = {}) {
+  if (stage === 'shipped') return { kind: 'prompt', label: 'Start next task', cmd: '/builder-start' };
+  if (stage === 'confirmed') return { kind: 'prompt', label: 'Land it', cmd: '/merge-mode' };
+  if (stage === 'failed') return { kind: 'prompt', label: 'Fix & re-grade', cmd: `node scripts/gds/ship.js ${taskId} --regrade` };
+  if (stage === 'review') return { kind: 'link', label: 'Open in sandbox', url: sandboxUrl || '' };
+  if (stage === 'claimed') {
+    const skill = DISCIPLINE_SKILL[discipline] || 'dev';
+    return { kind: 'prompt', label: 'Open the work', cmd: `/${skill}` };
+  }
+  return { kind: 'prompt', label: 'Continue', cmd: '/builder-start' };
+}
+
+function safeBrand() {
+  try {
+    const b = branding();
+    return {
+      productName: (b.identity && b.identity.productName) || 'Cloud Bongos',
+      currency: (b.currency && b.currency.label) || 'credits',
+    };
+  } catch (_) {
+    return { productName: 'Cloud Bongos', currency: 'credits' };
+  }
+}
+
+// ---- model -----------------------------------------------------------------
+// buildCardModel normalizes raw stage data into:
+//   { stage, cfg, brand, taskId, title, value, notes, issues,
+//     rows:  [{ k, v }],                       // monospace kv rows
+//     facts: [{ label, value, mono, cls }],    // html facts-line chunks
+//     action }                                 // { kind, label, cmd|url }
+// Stage-specific field selection lives HERE; the renderers are generic.
+function buildCardModel(input = {}) {
+  const stage = input.stage || stageFor(input.postGradeStatus);
+  const cfg = STAGES[stage] || STAGES.failed;
+  const brand = input.brand || safeBrand();
+  const taskId = input.taskId;
+  const grade = input.grade || {};
+  const credits = input.credits || {};
+  const usage = input.usage || {};
+  const issues = Array.isArray(grade.issues) ? grade.issues : [];
+
+  const rows = [];
+  const facts = [];
+  const addRow = (k, v) => { if (v != null && v !== '') rows.push({ k, v }); };
+  const addFact = (label, value, opts = {}) => { if (value != null && value !== '') facts.push({ label, value, ...opts }); };
+
+  // value summary — shown as a monospace Value row + the dropdown lead (never on
+  // the HTML face, per the locked design).
+  const value = input.valueSummary || '';
+
+  if (stage === 'claimed') {
+    // Pre-work: no diffstat/grade/credits yet — show the scope instead.
+    const est = fmtMins(input.estMinutes);
+    const touches = (input.touchesCount != null)
+      ? `${input.touchesCount} file${Number(input.touchesCount) === 1 ? '' : 's'}`
+      : null;
+    const ver = [input.version, input.kind].filter(Boolean).join(' · ') || null;
+    const prio = input.priority != null ? `P${input.priority}` : null;
+    addRow('Priority', prio); addRow('Estimate', est); addRow('Touches', touches); addRow('Scope', ver);
+    addFact('', prio); addFact('', est); addFact('', touches); addFact('', ver);
+  } else if (stage === 'review') {
+    const changed = changedText(input);
+    addRow('Changed', changed); addRow('Staged', 'on your sandbox');
+    addFact('', changed); addFact('', 'staged on your sandbox'); addFact('', 'review, then approve to ship');
+  } else {
+    // ship family: shipped / confirmed / failed
+    const changed = changedText(input);
+    // Grade: pass · panel N/N | skipped | fail · N issues
+    let gradeText = null;
+    let gradeCls = 'cc-good';
+    if (stage === 'failed') {
+      gradeText = issues.length ? `fail · ${issues.length} issue${issues.length === 1 ? '' : 's'}` : 'fail';
+      gradeCls = 'cc-bad';
+    } else if (grade.skipped) {
+      gradeText = 'skipped'; gradeCls = '';
+    } else if (grade.passed) {
+      gradeText = grade.panel ? `pass · panel ${grade.panel}/${grade.panel}` : 'pass';
+    }
+    // Credits
+    let creditsText = null;
+    if (stage === 'failed') {
+      creditsText = 'none — held at completed';
+    } else if (credits.awarded != null) {
+      const total = fmtInt(credits.total);
+      creditsText = total ? `+${credits.awarded} → ${total} ${brand.currency}` : `+${credits.awarded} ${brand.currency}`;
+    }
+    // Usage — lead with the dollar cost (the honest measure of the work), then
+    // split the token count into 'new' (fresh input + Claude's output + the
+    // first-time cache writes) vs 'cached' re-reads (the same large context
+    // re-read every turn, billed at ~1/10 the input rate). The single all-in
+    // token count reads as alarmingly huge for a tiny change precisely because
+    // cache re-reads dominate it — so we never lead with it. Degrades to
+    // '~$X · NM tokens' when the split is absent (old land-watch breadcrumbs, or
+    // a digest with no per-model usage). Task 1765.
+    const usd = fmtUsd(usage.costUsd);
+    const newTok = fmtTokens(usage.newTokens);
+    const cachedTok = fmtTokens(usage.cachedTokens);
+    const totalTok = fmtTokens(usage.tokens);
+    let usageText = null;
+    let usageTitle = null;
+    if (newTok != null && cachedTok != null) {
+      const split = `${newTok} new + ${cachedTok} cached`;
+      usageText = usd ? `~${usd} · ${split}` : split;
+      usageTitle = 'Cost is the real measure. "new" = fresh input + Claude’s output; '
+        + '"cached" = the same context re-read each turn, billed at ~1/10 the input rate.';
+    } else if (totalTok != null) {
+      usageText = usd ? `~${usd} · ${totalTok} tokens` : `${totalTok} tokens`;
+    } else if (usd) {
+      usageText = `~${usd}`;
+    }
+    // Deploy
+    let deployText;
+    let deployCommit = null;
+    if (stage === 'shipped') {
+      deployCommit = input.deploy && input.deploy.commit ? String(input.deploy.commit) : null;
+      deployText = deployCommit ? `live · ${deployCommit}` : 'live';
+    } else if (stage === 'confirmed') {
+      // The server lands confirmed tasks automatically (publish-reconciler +
+      // merge driver + ADR 0082 resolver); /merge-mode is a rare manual
+      // fallback, kept as the card's optional 'Land it' override — so the fact
+      // states the automatic reality rather than implying a required command.
+      deployText = 'landing automatically';
+    } else {
+      deployText = 'not deployed';
+    }
+
+    addRow('Value', value); addRow('Changed', changed); addRow('Grade', gradeText);
+    addRow('Credits', creditsText); addRow('Usage', usageText); addRow('Deploy', deployText);
+
+    addFact('', changed);
+    if (gradeText) addFact('grade', gradeText, { cls: gradeCls });
+    if (stage === 'shipped') addFact('live', deployCommit, { mono: true });
+    else addFact('', deployText);
+    addFact('', usageText, usageTitle ? { title: usageTitle } : {});
+    if (creditsText) addFact('', creditsText);
+  }
+
+  const action = nextActionFor(stage, { taskId, discipline: input.discipline, sandboxUrl: input.sandboxUrl });
+
+  return {
+    stage, cfg, brand, taskId,
+    title: input.title || '',
+    value,
+    notes: input.notes || '',
+    description: input.description || '',
+    issues,
+    rows, facts, action,
+  };
+}
+
+// Changed: "4 files · +112/−37" (omit the diffstat half when unknown).
+function changedText(input) {
+  if (input.fileCount == null) return null;
+  const files = `${input.fileCount} file${Number(input.fileCount) === 1 ? '' : 's'}`;
+  return (input.added != null && input.removed != null)
+    ? `${files} · +${input.added}/−${input.removed}`
+    : files;
+}
+
+// ---- 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 renderMonospaceCard(model) {
+  const m = model;
+  const out = [];
+  const bar = '  ' + '─'.repeat(MONO_W);
+  const left = `${m.brand.productName} · task #${m.taskId}`;
+  const right = m.cfg.statusWord;
+  const gap = Math.max(2, MONO_W - left.length - right.length);
+  out.push('  ' + left + ' '.repeat(gap) + right);
+  out.push(bar);
+  for (const l of wrap(m.title, MONO_W)) out.push('  ' + l);
+  out.push('');
+  // The journey, in text: done steps get a ✓, and tense carries the state
+  // (present continuous vs bare verb). Pack the steps into lines breaking only at the
+  // " → " joints, so a multi-word step like 'grade failed' never splits.
+  const stepStrs = trailSteps(m.cfg).map((s) => (s.checked ? '✓ ' : '') + s.word);
+  let tline = '';
+  for (const st of stepStrs) {
+    const piece = tline ? ` → ${st}` : st;
+    if (tline && (tline + piece).length > MONO_W) { out.push('  ' + tline); tline = st; }
+    else tline += piece;
+  }
+  if (tline) out.push('  ' + tline);
+  out.push('');
+  const kv = (k, v) => {
+    const lines = wrap(v, MONO_W - 9);
+    out.push('  ' + k.padEnd(9) + lines[0]);
+    for (const c of lines.slice(1)) out.push('  ' + ' '.repeat(9) + c);
+  };
+  for (const r of m.rows) kv(r.k, r.v);
+  out.push(bar);
+  kv('Next →', m.action.kind === 'link' ? (m.action.url || '(sandbox)') : m.action.cmd);
+  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 factHtml(f) {
+  let inner = esc(f.value);
+  if (f.mono) inner = `<span class="cc-mono">${inner}</span>`;
+  else if (f.cls) inner = `<span class="${f.cls}">${inner}</span>`;
+  const title = f.title ? ` title="${esc(f.title)}"` : '';
+  return f.label ? `<span${title}>${esc(f.label)} ${inner}</span>` : `<span${title}>${inner}</span>`;
+}
+function renderCardHtml(model) {
+  const m = model;
+  const { bg, fg } = TONE[m.cfg.tone] || TONE.neutral;
+
+  // Lifecycle ribbon as a real progress trail: done steps are checked + muted,
+  // the current step is bold (present-tense), steps ahead are dimmed bare verbs.
+  const check = '<i class="ti ti-check" style="font-size:11px;vertical-align:-1px;" aria-hidden="true"></i> ';
+  const ribbon = trailSteps(m.cfg).map((s) => {
+    const mark = s.checked ? check : '';
+    if (s.state === 'done') return `<span style="opacity:0.7;">${mark}${esc(s.word)}</span>`;
+    if (s.state === 'current') return `<span style="font-weight:500;">${mark}${esc(s.word)}</span>`;
+    return `<span style="opacity:0.4;">${esc(s.word)}</span>`;
+  }).join('<span style="opacity:0.32;"> → </span>');
+
+  const facts = m.facts.map(factHtml).join('<span class="cc-sep">·</span>');
+
+  // Dropdown body: failed → the issues; otherwise the value summary + notes (or,
+  // pre-work, the task description).
+  let summaryBody;
+  if (m.stage === 'failed' && m.issues.length) {
+    summaryBody = m.issues.map((it) => {
+      const sev = esc(it.severity || '?');
+      const file = it.file ? `<span class="cc-mono">${esc(it.file)}</span> — ` : '';
+      return `<div style="display:flex;gap:7px;margin-bottom:4px;"><span class="cc-pill cc-pill-bad">${sev}</span><span style="color:var(--color-text-secondary);">${file}${esc(it.summary || '')}</span></div>`;
+    }).join('');
+  } else {
+    const lead = m.value || m.description;
+    const leadHtml = lead ? `<div style="color:var(--color-text-secondary);margin-bottom:0.55rem;white-space:pre-wrap;">${esc(lead)}</div>` : '';
+    const notesHtml = m.notes ? `<div style="color:var(--color-text-secondary);white-space:pre-wrap;">${esc(m.notes)}</div>` : '';
+    summaryBody = (leadHtml + notesHtml) || `<div style="color:var(--color-text-tertiary);">No summary recorded.</div>`;
+  }
+
+  // Action: a sendPrompt button, or an Open-in-sandbox link.
+  let actionHtml;
+  if (m.action.kind === 'link') {
+    actionHtml = `<a href="${esc(m.action.url)}" class="cc-link cc-next" style="text-decoration:none;">${esc(m.action.label)} ↗</a>`;
+  } else {
+    const cmd = esc(m.action.cmd).replace(/'/g, "\\'");
+    actionHtml = `<button class="cc-link cc-next" onclick="sendPrompt('${cmd}')">${esc(m.action.label)} ↗</button>`;
+  }
+
+  const factsSr = m.facts.map((f) => `${f.label ? f.label + ' ' : ''}${f.value}`).join('. ');
+  const srText = `${m.cfg.headline(m.taskId)}. ${factsSr}. A collapsible summary expands on click.`;
+
+  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;}
+.cc-sep{color:var(--color-text-tertiary);margin:0 7px;}
+.cc-mono{font-family:var(--font-mono);font-size:12px;}
+.cc-good{color:var(--color-text-success);}
+.cc-bad{color:var(--color-text-danger);}
+.cc-link{background:none;border:none;padding:0;cursor:pointer;font-family:inherit;display:inline-flex;align-items:center;gap:3px;white-space:nowrap;flex:none;}
+.cc-next{font-size:12px;color:var(--color-text-secondary);}
+.cc-next:hover{color:var(--color-text-primary);}
+.cc-sum{font-size:11px;color:var(--color-text-tertiary);}
+.cc-sum:hover{color:var(--color-text-secondary);}
+.cc-chev{transition:transform .12s;display:inline-flex;}
+.cc-pill{font-size:10.5px;font-weight:500;padding:1px 6px;border-radius:4px;white-space:nowrap;height:fit-content;}
+.cc-pill-bad{color:var(--color-text-danger);background:var(--color-background-danger);}
+</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 ${esc(m.cfg.icon)}" 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(m.cfg.headline(m.taskId))}</span>
+    <span style="flex:1;"></span>
+    <span style="font-size:11px;color:${fg};white-space:nowrap;">${ribbon}</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.title)}</span>
+    ${actionHtml}
+  </div>
+  <div style="display:flex;align-items:baseline;gap:10px;">
+    <div style="font-size:13px;color:var(--color-text-secondary);line-height:1.7;flex:1;min-width:0;">${facts}</div>
+    <button class="cc-link cc-sum" aria-label="Toggle task summary" onclick="var s=this.parentElement.nextElementSibling;var o=getComputedStyle(s).display==='none';s.style.display=o?'block':'none';this.querySelector('i').style.transform=o?'rotate(90deg)':'';">Summary <span class="cc-chev"><i class="ti ti-chevron-right" aria-hidden="true"></i></span></button>
+  </div>
+  <div style="display:none;margin-top:0.6rem;padding-top:0.55rem;border-top:0.5px solid var(--color-border-tertiary);font-size:13px;line-height:1.6;">${summaryBody}</div>
+</div>`;
+}
+
+// ---- emitCard: the shared I/O the CLIs call (claim.js, ship.js) -------------
+// Prints the monospace card (always), and — when the builder has widgets ON
+// (the default) — writes the branded HTML to a temp file + prints the
+// [otb-card-html] marker the skills pick up to render it in-feed.
+//
+// widgetsEnabled (task 1279): the builder's per-builder "render widgets" knob,
+// resolved from /me by the caller (claim.js / ship.js). When false, NO HTML is
+// written or referenced — the agent never reads or re-emits widget markup, so
+// turning widgets off is a real token saving, not just a visual change. A
+// distinct [otb-card] marker tells the skill to relay the monospace card as-is
+// and NOT call show_widget.
+//
+// Strictly best-effort — a summary card must never fail or undo a CLI action.
+function emitCard(model, taskId, { log = console.log, widgetsEnabled = true } = {}) {
+  try {
+    log('');
+    log(renderMonospaceCard(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. (Toggle in the hall: Settings → Rendering.)');
+    } catch (_) { /* best-effort */ }
+    return null;
+  }
+  try {
+    const file = path.join(os.tmpdir(), `otb-ship-card-${taskId}.html`);
+    fs.writeFileSync(file, renderCardHtml(model), 'utf8');
+    log('');
+    log(`[otb-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. If that tool is unavailable, the card above IS the summary.');
+    return file;
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = {
+  STAGES, TONE, stageFor, buildCardModel, renderMonospaceCard, renderCardHtml, emitCard,
+  // exported for unit tests:
+  fmtTokens, fmtUsd, fmtInt, fmtMins, nextActionFor, esc, wrap, changedText,
+  PIPELINE, FORMS, trailSteps,
+};