@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/release-core.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/release-core.js — may this version of @bongos/core be RELEASED? (task 1004298, ADR 0361)
+//
+// Merges publish as candidates (under the `next` label). A version reaches other projects only when
+// the owner presses Release on /deploy, which runs publish.yml's release job, which asks this script
+// and then moves the registry's `latest` label. Every consumer that offers a version to a project
+// other than the platform hall reads `latest` (update-channel.js versionsForFollow), so this label IS
+// the release.
+//
+// WHY A SCRIPT AND NOT A SHELL STEP. The rule has four ways to say no, and a shell `if` chain inside
+// a workflow file is the one place nothing can test it. The decision is pure and unit-tested
+// (tests/release_core.mjs); the workflow only runs it and acts on `go`.
+//
+// THE RULE:
+//   - the version must be a plain x.y.z (it is interpolated into an npm command line);
+//   - it must be PUBLISHED — Release labels a version, it never builds one;
+//   - it must be newer than the current release. Releasing an OLDER version would move every
+//     project's offer backwards, which is a rollback for everyone, not a release; that is a
+//     different act and needs a person at a terminal, not a button.
+//   - releasing the version already released is a no-op, not an error — a double press is harmless.
+//
+// Usage (in publish.yml's release job):
+//   node scripts/bongos/release-core.js --version 1.20.80
+// Prints the decision; writes go=true|false to $GITHUB_OUTPUT when set. Exit 0 for go and no-op,
+// 1 for a refusal.
+
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+const { CORE_PKG, parseSemver, compareSemver, isStable } = require('./update-channel.js');
+
+const VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
+/**
+ * PURE. `versions`: every published version. `latest`: the version the registry labels `latest`
+ * now, or null. Returns { go, noop, reason }.
+ */
+function releaseDecision({ version, versions, latest } = {}) {
+  const v = String(version == null ? '' : version).trim();
+  if (!VERSION_RE.test(v)) return { go: false, noop: false, reason: `"${v}" is not a version (x.y.z)` };
+  const list = Array.isArray(versions) ? versions : [];
+  if (!list.includes(v)) return { go: false, noop: false, reason: `${v} is not published — Release labels a published version, it never builds one` };
+  if (!isStable(v)) return { go: false, noop: false, reason: `${v} is a prerelease` };
+  if (latest && parseSemver(latest)) {
+    const c = compareSemver(v, latest);
+    if (c === 0) return { go: false, noop: true, reason: `${v} is already the release` };
+    if (c < 0) return { go: false, noop: false, reason: `${v} is older than the current release ${latest} — releasing it would move every project backwards` };
+  }
+  return { go: true, noop: false, reason: latest ? `release ${v} (was ${latest})` : `release ${v} (no release yet)` };
+}
+
+function readRegistry({ pkg = CORE_PKG, run = spawnSync } = {}) {
+  const res = run('npm', ['view', pkg, 'versions', 'dist-tags', '--json'], { encoding: 'utf8', timeout: 60000 });
+  if (!res || res.status !== 0) return { ok: false, error: String((res && res.stderr) || 'npm view failed').trim().split('\n')[0] };
+  try {
+    const doc = JSON.parse(String(res.stdout || '{}'));
+    const versions = Array.isArray(doc.versions) ? doc.versions : (typeof doc.versions === 'string' ? [doc.versions] : []);
+    const tags = doc['dist-tags'] || {};
+    return { ok: true, versions, latest: typeof tags.latest === 'string' ? tags.latest : null };
+  } catch (e) {
+    return { ok: false, error: `unparseable npm output: ${e.message}` };
+  }
+}
+
+function main(argv = process.argv.slice(2), { env = process.env, read = readRegistry, log = console.log, err = console.error } = {}) {
+  const i = argv.indexOf('--version');
+  const version = i >= 0 ? argv[i + 1] : '';
+  const out = (go) => { if (env.GITHUB_OUTPUT) fs.appendFileSync(env.GITHUB_OUTPUT, `go=${go}\n`); };
+  const reg = read();
+  if (!reg.ok) { err(`release-core: could not read the registry (${reg.error})`); out(false); return 1; }
+  const d = releaseDecision({ version, versions: reg.versions, latest: reg.latest });
+  out(d.go);
+  if (d.go || d.noop) { log(`release-core: ${d.reason}`); return 0; }
+  err(`release-core: refused — ${d.reason}`);
+  return 1;
+}
+
+if (require.main === module) process.exit(main());
+
+module.exports = { releaseDecision, main };

package/scripts/bongos/release-notes.js

@@ -0,0 +1,271 @@
+'use strict';
+
+// scripts/bongos/release-notes.js — what each core release brought in, as the summaries its
+// ships wrote, generated when the core is PACKED and shipped inside the package as
+// release-notes.json (task 1004218).
+//
+// WHY INSIDE THE PACKAGE. The Deploy page's "what this brings in" list used to be read out
+// of a core git checkout on the machine asking (task 1004173), and no tenant box will ever
+// have one: every project the wizard creates is a checkout of its OWN repo with the core
+// vendored in at node_modules. The one machine that always has the full history is the one
+// that builds the package — publish.yml checks out at fetch-depth 0 because package-core
+// archives from git — so that is where the notes are written down, once, and every project
+// that can download a core version can read what it carries.
+//
+// THREE PARTS, NO I/O OF ITS OWN. The PARSER (parseChangeRecords, moved here from
+// provision-core-upgrade.js so there is exactly one), the GENERATOR (package-core.js hands
+// it the ref's history), and the RANGE READER (the upgrade runner asks it for from→to).
+// Git is injected, never required, so loading this costs package-core nothing.
+//
+// THE SHAPE. `{ "<version>": [ { id?, text }, … ] }`, ascending by version, one key per
+// release — including a release whose merges were all housekeeping, which keeps an EMPTY
+// list. That is the difference between "nothing landed" and "not covered": a range is
+// answerable only when its target is a key, so a missing key can never be read as silence.
+
+const CHANGE_TEXT_MAX = 400;
+
+// The file's name at the package root, beside package.json.
+const RELEASE_NOTES_FILE = 'release-notes.json';
+
+// THE BOUND. The whole history to 1.19.1029 is ~400 KB pretty-printed (1,033 releases,
+// 1,399 summaries, measured 2026-09-25), growing roughly 200 KB a month at 20–30 releases a
+// day. Nothing needs trimming today; the bound exists so the file cannot grow unwatched.
+// Past it, the OLDEST releases are dropped — the ranges an owner asks about are recent ones
+// — and the reader then says those older ranges are not covered, rather than guessing.
+const RELEASE_NOTES_MAX_BYTES = 1024 * 1024;
+
+// A release commit's subject — the lane's own carrier AND a human release both begin this
+// way. The same marker findCoreCheckout's probe uses to recognise core history.
+const RELEASE_SUBJECT_RE = /^release: core (\d+\.\d+\.\d+) /;
+const CORE_VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
+// One record per commit: sha, parents, subject, body. `--topo-order` is load-bearing — see
+// buildReleaseNotes for why the order releases are visited in must be topological.
+const LOG_ARGS = ['log', '--topo-order', '--format=%H%x1f%P%x1f%s%x1f%b%x1e'];
+
+/**
+ * The merge summaries in a `git log --merges --format=%s%x1f%b%x1e` dump. PURE.
+ *
+ * TWO MERGE SHAPES CARRY A SUMMARY AND THE SECOND IS THE COMMON ONE. A hand-landed ship
+ * writes `Merge <branch>: <summary>`; the CI auto-merge writes `Merge pull request #N
+ * from <owner>/<branch>` with `task <id>: <summary>` in the BODY. Measured over
+ * 1.19.881→1.19.972: 114 usable summaries, of which 98 were the second shape. A parser
+ * that read subjects only would have found eleven of them and quietly called that the
+ * release.
+ *
+ * EVERYTHING ELSE IS DROPPED, and the drops are the majority: `Merge origin/main into
+ * <branch> (pre-stage freshness…)`, `Merge remote-tracking branch…`, a regen chore. Those
+ * are the mechanics of landing work, not the work, and listing them would bury the
+ * eleven sentences the owner actually wants under a hundred they do not.
+ */
+function parseChangeRecords(stdout) {
+  const out = [];
+  const seen = new Set();
+  for (const rec of String(stdout || '').split('\x1e')) {
+    const r = rec.trim();
+    if (!r) continue;
+    const i = r.indexOf('\x1f');
+    const subject = (i < 0 ? r : r.slice(0, i)).trim();
+    const body = i < 0 ? '' : r.slice(i + 1);
+    let text = null;
+    let id = null;
+    // The negative lookahead is what keeps the two housekeeping shapes out: both begin
+    // "Merge " and both would otherwise match a `<token>:` somewhere later in the line.
+    let m = /^Merge\s+(?!pull request\b|remote-tracking\b)([^\s:]+):\s*(\S.*)$/.exec(subject);
+    if (m) {
+      text = m[2];
+    } else {
+      const first = body.split('\n').map((l) => l.trim()).find(Boolean) || '';
+      m = /^task\s+(\d+):\s*(\S.*)$/.exec(first);
+      if (m) { id = m[1]; text = m[2]; }
+    }
+    if (!text) continue;
+    // It reaches a DOM, and a ship summary is occasionally a paragraph.
+    text = boundText(text);
+    if (seen.has(text)) continue;   // a branch merged twice says its sentence once
+    seen.add(text);
+    out.push(id ? { id, text } : { text });
+  }
+  return out;
+}
+
+function boundText(text) {
+  return text.length > CHANGE_TEXT_MAX ? `${text.slice(0, CHANGE_TEXT_MAX - 1)}…` : text;
+}
+
+/** Order two three-number core versions. PURE; both must already match CORE_VERSION_RE. */
+function compareCoreVersions(a, b) {
+  const x = String(a).split('.').map(Number);
+  const y = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
+  return 0;
+}
+
+/** Split a LOG_ARGS dump into `{ sha, parents, subject, body }` records, in log order. PURE. */
+function parseLogRecords(stdout) {
+  const out = [];
+  for (const rec of String(stdout || '').split('\x1e')) {
+    const r = rec.replace(/^\n+/, '');   // git terminates each record with a newline
+    if (!r.trim()) continue;
+    const [sha, parents, subject, ...body] = r.split('\x1f');
+    out.push({
+      sha: sha.trim(),
+      parents: String(parents || '').split(' ').filter(Boolean),
+      subject: subject || '',
+      body: body.join('\x1f'),
+    });
+  }
+  return out;
+}
+
+function uniqueByText(entries) {
+  const seen = new Set();
+  return entries.filter((e) => (seen.has(e.text) ? false : seen.add(e.text)));
+}
+
+/**
+ * What each release brought in, from a whole history. PURE.
+ *
+ * `commits` is every commit the packed ref reaches, NEWEST FIRST in topological order (what
+ * LOG_ARGS asks git for). Returns `{ notes, releases, tail }`.
+ *
+ * EXACTLY `git log --merges <previous release>..<release>`, FOR EVERY RELEASE AT ONCE — the
+ * range the checkout-based reader asks for one pair at a time. Splitting the log wherever a
+ * release subject appears would be simpler and is wrong: a PR branch's commits are not
+ * ordered against main's by the log, so a merge made on a branch before one release but
+ * landed after it would be credited to the earlier release. So each release, oldest first,
+ * claims everything it can reach that no earlier release reached. The visiting order has to
+ * be topological for that to be the previous-release range — hence `--topo-order`.
+ *
+ * THE UNRELEASED TAIL — commits the ref reaches that no release commit does — belongs to the
+ * version being packed when that version has no release commit of its own yet (a pack of a
+ * hand-declared version), and to nobody otherwise: on a work merge the tail is the NEXT
+ * release's, whose number does not exist yet.
+ */
+function buildReleaseNotes(commits, { version = null } = {}) {
+  const bySha = new Map(commits.map((c) => [c.sha, c]));
+  const position = new Map(commits.map((c, i) => [c.sha, i]));
+  const claimed = new Set();
+  const claim = (tip) => {
+    const mine = [];
+    const stack = [tip];
+    while (stack.length) {
+      const sha = stack.pop();
+      if (claimed.has(sha) || !bySha.has(sha)) continue;
+      claimed.add(sha);
+      const c = bySha.get(sha);
+      mine.push(c);
+      for (const p of c.parents) if (!claimed.has(p)) stack.push(p);
+    }
+    return mine;
+  };
+  // Newest first within a release, as `git log` itself would list them.
+  const summarize = (segment) => parseChangeRecords(segment
+    .filter((c) => c.parents.length > 1)
+    .sort((a, b) => position.get(a.sha) - position.get(b.sha))
+    .map((c) => `${c.subject}\x1f${c.body}\x1e`)
+    .join(''));
+
+  const byVersion = new Map();
+  let releases = 0;
+  for (let i = commits.length - 1; i >= 0; i--) {
+    const m = RELEASE_SUBJECT_RE.exec(commits[i].subject);
+    if (!m) continue;
+    releases++;
+    // A version released twice keeps both halves; the second claims only what the first
+    // could not reach.
+    byVersion.set(m[1], uniqueByText([...(byVersion.get(m[1]) || []), ...summarize(claim(commits[i].sha))]));
+  }
+  const tail = commits.filter((c) => !claimed.has(c.sha));
+  if (version && CORE_VERSION_RE.test(version) && !byVersion.has(version)
+      && [...byVersion.keys()].every((v) => compareCoreVersions(v, version) < 0)) {
+    byVersion.set(version, summarize(tail));
+  }
+  const notes = {};
+  for (const v of [...byVersion.keys()].sort(compareCoreVersions)) notes[v] = byVersion.get(v);
+  return { notes, releases, tail: tail.length };
+}
+
+/**
+ * Read a ref's history through an injected `git(args) → stdout` and build its notes.
+ * Returns `{ notes, releases, tail }`, or `{ skipped }` saying why there are none — never
+ * a partial answer presented as a whole one.
+ */
+function generateReleaseNotes({ git, ref, version }) {
+  let shallow;
+  try { shallow = String(git(['rev-parse', '--is-shallow-repository'])).trim() === 'true'; }
+  catch (e) { return { skipped: `could not ask git about this clone (${firstLine(e)})` }; }
+  // A depth-limited clone reaches a handful of commits, and notes built from it would
+  // credit the newest release with everything the clone happens to hold.
+  if (shallow) return { skipped: 'this is a shallow clone, so it carries no release history' };
+  let out;
+  try { out = git([...LOG_ARGS, ref]); }
+  catch (e) { return { skipped: `could not read the history of ${ref} (${firstLine(e)})` }; }
+  const built = buildReleaseNotes(parseLogRecords(out), { version });
+  if (!built.releases) return { skipped: 'this history holds no release commits' };
+  return built;
+}
+
+function firstLine(e) {
+  return String((e && e.message) || e || '').trim().split('\n')[0].slice(0, 160);
+}
+
+/** The file's bytes: the same pretty-printed JSON the package's other generated files use. */
+function serializeReleaseNotes(notes) {
+  return Buffer.from(`${JSON.stringify(notes, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Hold the file under `maxBytes` by dropping the OLDEST releases. PURE.
+ * Returns `{ notes, dropped }`; the newest release is always kept.
+ */
+function boundReleaseNotes(notes, maxBytes = RELEASE_NOTES_MAX_BYTES) {
+  const versions = Object.keys(notes);
+  const keep = (from) => Object.fromEntries(versions.slice(from).map((v) => [v, notes[v]]));
+  const fits = (from) => serializeReleaseNotes(keep(from)).length <= maxBytes;
+  if (versions.length <= 1 || fits(0)) return { notes, dropped: [] };
+  // The fewest drops that fit, by bisection — the size only shrinks as more are dropped.
+  let lo = 1;
+  let hi = versions.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (fits(mid)) hi = mid; else lo = mid + 1;
+  }
+  return { notes: keep(lo), dropped: versions.slice(0, lo) };
+}
+
+/**
+ * The entries for every release in `(from, to]`, newest release first. PURE.
+ *
+ * Returns `{ entries }` or `{ uncovered }` — a phrase saying why these notes cannot answer,
+ * worded to follow "the release notes …". NEVER an empty list for a range the notes do not
+ * reach: an empty list reads as "nothing changed", which is exactly what a restart must not
+ * be sold as. They reach a range when they list its target and begin at or before its
+ * start: the oldest release they hold is where their knowledge begins.
+ *
+ * The file may have come off the network, so every entry is re-checked here, not trusted.
+ */
+function notesBetween(notes, from, to) {
+  if (!notes || typeof notes !== 'object' || Array.isArray(notes)) return { uncovered: 'are not a list of releases' };
+  const versions = Object.keys(notes)
+    .filter((v) => CORE_VERSION_RE.test(v) && Array.isArray(notes[v]))
+    .sort(compareCoreVersions);
+  if (!versions.includes(to)) return { uncovered: `do not list core ${to}` };
+  if (compareCoreVersions(versions[0], from) > 0) return { uncovered: `begin at core ${versions[0]}, after ${from}` };
+  const inRange = versions.filter((v) => compareCoreVersions(v, from) > 0 && compareCoreVersions(v, to) <= 0);
+  const entries = [];
+  for (const v of inRange.reverse()) {
+    for (const e of notes[v]) {
+      if (!e || typeof e.text !== 'string' || !e.text.trim()) continue;
+      const text = boundText(e.text.trim());
+      entries.push(/^\d+$/.test(String(e.id || '')) ? { id: String(e.id), text } : { text });
+    }
+  }
+  return { entries: uniqueByText(entries) };
+}
+
+module.exports = {
+  RELEASE_NOTES_FILE, RELEASE_NOTES_MAX_BYTES,
+  parseChangeRecords, parseLogRecords, buildReleaseNotes,
+  generateReleaseNotes, serializeReleaseNotes, boundReleaseNotes, notesBetween,
+};

package/scripts/bongos/release.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// Builder release — cancel an active claim without shipping. No credits awarded.
+//
+// Usage:
+//   node scripts/bongos/release.js <task-id> [--reason "..."]
+//
+// The task returns to 'ready' status and is claimable by another session.
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+const { errCode, errDetails, cliClient, requireSession, arg } = require('./cli-lib');
+const { parkedMainCheckoutWarning } = require('./worktree-claim-guard');
+const { plainCardLines } = require('./plain-cards');
+
+// gitAt(args, cwd) — run git with an ARGV ARRAY and no shell.
+//
+// Deliberately not `execSync('git -C "<path>" …')`. A resolved filesystem path is
+// not trusted input: a directory name containing a quote, backtick or `$()` would
+// break out of the quoting and execute under cmd.exe/sh. execFileSync never
+// spawns a shell, so the path cannot be interpreted as anything but a path — a
+// stronger guarantee than the `{ cwd }` form, which still shells the command
+// string. (Found by the grader on this task, and it was right: the first cut
+// interpolated the path into a shell string.)
+//
+// Kept local rather than imported from ship-git.js. The original reason was that
+// release.js shipped in the public @cloudbongos/cli package, which carried no ship-*
+// file, so an import from that family crashed at require time — that is how this file
+// broke once already. That package was retired (ADR 0324), so the constraint is no
+// longer enforced by anything; the duplication is left as-is rather than quietly
+// re-coupled inside a packaging change. Re-joining them is now a free choice, not a
+// forbidden one.
+function gitAt(args, cwd) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+// The MAIN checkout, not this worktree — from a linked worktree they differ, and
+// the parked-tree warning is only ever about the main one.
+//
+// Resolved with git rather than by importing ship-state's REPO_ROOT for the same
+// packaging reason: ship-state pulls in modules/lifecycle/ship-preflight, which
+// would drag server-side lifecycle code into a client-only package.
+// `--git-common-dir` is the shared .git of the whole worktree family, so its
+// parent is the main checkout from anywhere.
+function mainCheckoutRoot() {
+  const common = gitAt(['rev-parse', '--path-format=absolute', '--git-common-dir'], process.cwd());
+  return common ? path.dirname(common) : null;
+}
+
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const taskId = Number(args[0]);
+  if (!Number.isFinite(taskId)) {
+    console.error('usage: node scripts/bongos/release.js <task-id> [--reason "..."]');
+    process.exit(2);
+  }
+  const reason = arg('--reason', args) || '';
+  const force = args.includes('--force');
+
+  const api = await cliClient();
+  const me = await api.me.getMe();
+  if (!me.ok) {
+    console.error('failed to load profile:', me.data);
+    process.exit(1);
+  }
+  const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
+  const ac = claims.find((c) => Number(c.task_id) === taskId);
+  if (!ac) {
+    console.error(`You don't have an active claim on task #${taskId}.`);
+    if (claims.length > 0) {
+      console.error(`Your active claims:`);
+      for (const c of claims) console.error(`  #${c.task_id}: ${c.title}`);
+    }
+    for (const line of plainCardLines('no_active_claim')) console.error(line);
+    process.exit(1);
+  }
+
+  if (force) {
+    console.error('');
+    console.error('WARNING: --force bypasses the session lock. Only use this if the original');
+    console.error('session is gone and you cannot ship or release normally.');
+    console.error('');
+  }
+
+  const r = await api.claims.postClaimsIdResolve({
+    id: ac.claim_id,
+    body: {
+      outcome: 'abandoned',
+      notes_md: reason ? `Released without shipping. Reason: ${reason}` : 'Released without shipping.',
+      force,
+    },
+  });
+  if (!r.ok) {
+    // ADR 0116 nests the slug at error.code AND its payload at error.details — see the
+    // note in abandon.js (task 1003658). claimWorktree reaches the wire through
+    // `res.fail(err.code, status, { ...err })` in modules/lifecycle/routes/claims.js:612,
+    // so it lands in details, not at the top level. Reading it off r.data directly made
+    // `wt` undefined and silently dropped the worktree name from the message — the exact
+    // half-fix this task exists to avoid, caught by the grader on the first round.
+    const code = errCode(r.data);
+    const details = errDetails(r.data);
+    if (code === 'CLAIM_SESSION_MISMATCH') {
+      const wt = details.claimWorktree;
+      console.error(`This claim was created in a different session${wt ? ` (worktree: ${wt})` : ''}.`);
+      console.error('Only the original session can release it.');
+      console.error('If that session is gone, re-run with --force to override.');
+      for (const line of plainCardLines('CLAIM_SESSION_MISMATCH')) console.error(line);
+    } else {
+      console.error(`release failed (${r.status}):`, r.data);
+    }
+    process.exit(1);
+  }
+  console.log(`Released task #${r.data.taskId}: ${r.data.taskTitle}`);
+  console.log(`Status returned to 'ready'. No credits awarded.`);
+  // task 1002871: a claim worked under the `--here` hatch leaves the MAIN
+  // checkout on the feature branch, and giving the claim up is exactly when that
+  // tree stops being watched. Warn, never restore — the branch may hold real
+  // uncommitted work, and release.js cannot tell that from debris. Strictly
+  // best-effort: a diagnostic must never fail a release that already succeeded.
+  try {
+    const root = mainCheckoutRoot();
+    const branch = root && gitAt(['rev-parse', '--abbrev-ref', 'HEAD'], root);
+    // gitAt already trims, so a non-empty string IS dirt.
+    const dirty = root && gitAt(['status', '--porcelain'], root);
+    const lines = parkedMainCheckoutWarning({ branch, dirty: !!dirty });
+    if (lines.length) {
+      console.log('');
+      for (const line of lines) console.log(line);
+    }
+  } catch (_) { /* never let a warning break a successful release */ }
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/bongos/rename-goals.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// scripts/bongos/rename-goals.js — apply the goal-names.js mapping (task 1003225).
+//
+// Usage:
+//   node scripts/bongos/rename-goals.js            # DRY RUN — prints the diff, writes nothing
+//   node scripts/bongos/rename-goals.js --apply    # writes, via PATCH /goals/:id
+//
+// Writes go through PATCH /goals/:id, never SQL: that route is authorized
+// (owner|manager|Archon) and records prose-edit deltas, so a rename of somebody's
+// goal is audit-trailed. A prod UPDATE would be invisible.
+//
+// THE GUARD THAT MATTERS: it refuses to run when the server does not return
+// `subtitle`. Renaming a title against a server that cannot store the subtitle
+// would DELETE the explanation — the exact data loss this task exists to avoid.
+// core_224 ships the column; a live instance one release behind does not have it.
+
+'use strict';
+
+const { cliClient, requireSession, hasFlag } = require('./cli-lib');
+const { GOAL_NAMES, SEPARATOR } = require('./goal-names.js');
+
+// Nothing to do when the goal already reads the way the mapping wants.
+function planFor(goal, want) {
+  const patch = {};
+  if ((goal.title || '') !== want.title) patch.title = want.title;
+  if ((goal.subtitle || '') !== want.subtitle) patch.subtitle = want.subtitle;
+  return patch;
+}
+
+async function main() {
+  await requireSession();
+  const apply = hasFlag('--apply');
+  const api = await cliClient();
+
+  const res = await api.goals.getGoals({ query: { version: 'BONGOS-V1' } });
+  if (!res.ok) {
+    console.error(`could not list goals: ${res.status}`);
+    process.exit(1);
+  }
+  const goals = (res.data.goals || []).filter((g) => g.status === 'open');
+  if (!goals.length) {
+    console.error('no open goals returned — refusing to act on an empty read.');
+    process.exit(1);
+  }
+
+  // The refusal above all others.
+  if (!Object.prototype.hasOwnProperty.call(goals[0], 'subtitle')) {
+    console.error('REFUSING: this server does not return `subtitle`, so it cannot store one.');
+    console.error('Renaming titles now would drop every explanation on the floor.');
+    console.error('core_224 adds the column — wait for the release carrying it to DEPLOY, then re-run.');
+    process.exit(2);
+  }
+
+  let changed = 0; let already = 0; let missing = 0; let failed = 0;
+  for (const g of goals.sort((a, b) => Number(a.id) - Number(b.id))) {
+    const want = GOAL_NAMES[Number(g.id)];
+    if (!want) {
+      // Not an error: goals whose titles were already names are deliberately absent.
+      if (SEPARATOR.test(g.title || '')) {
+        console.error(`!  ${g.id} has a jammed title but no mapping entry: ${g.title}`);
+        missing += 1;
+      }
+      continue;
+    }
+    const patch = planFor(g, want);
+    if (!Object.keys(patch).length) { already += 1; continue; }
+    console.log(`${apply ? '→' : '·'}  ${g.id}`);
+    if (patch.title) console.log(`     title    ${JSON.stringify(g.title)}  ->  ${JSON.stringify(patch.title)}`);
+    if (patch.subtitle !== undefined) console.log(`     subtitle ${JSON.stringify(g.subtitle || '')}  ->  ${JSON.stringify(patch.subtitle)}`);
+    if (!apply) { changed += 1; continue; }
+    const r = await api.goals.patchGoalsId({ id: g.id, body: patch });
+    if (!r.ok) {
+      console.error(`     FAILED ${r.status} ${JSON.stringify(r.data)}`);
+      failed += 1;
+    } else {
+      changed += 1;
+    }
+  }
+
+  console.log('');
+  console.log(`${apply ? 'applied' : 'would change'}: ${changed} · already correct: ${already}`
+    + `${missing ? ` · UNMAPPED jammed titles: ${missing}` : ''}${failed ? ` · FAILED: ${failed}` : ''}`);
+  if (!apply) console.log('dry run — re-run with --apply to write.');
+
+  // THE POST-CONDITION, CHECKED AGAINST REAL DATA — not against the mapping.
+  // The task's deliverable is a STATE of the live goal set ("no open goal's title
+  // contains a dash-appended subtitle"), and unit tests over the mapping's internal
+  // consistency cannot witness that: they would pass just as happily if --apply had
+  // never been run. This re-reads what the server actually holds now and reports it,
+  // so the claim is falsifiable by anyone re-running the command.
+  //
+  // SCOPED TO THIS VERSION, deliberately. The read above is `version: BONGOS-V1`;
+  // CB-V1 carries jammed titles of its own (id 4, 1000043, 1000066, 1000079) which
+  // are ANOTHER version's work, and sweeping them in here would rename goals this
+  // task never reviewed.
+  const stillJammed = goals.filter((g) => SEPARATOR.test(g.title || ''));
+  console.log('');
+  console.log(`post-condition (BONGOS-V1 open goals): ${goals.length} checked · `
+    + `${stillJammed.length} still carrying an explanation in the title`);
+  for (const g of stillJammed) console.log(`  ! ${g.id} ${JSON.stringify(g.title)}`);
+
+  process.exit(failed || missing ? 1 : 0);
+}
+
+if (require.main === module) {
+  main().catch((err) => { console.error('fatal:', err); process.exit(1); });
+}
+
+module.exports = { planFor };