@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/backlog-review.js

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+// /backlog-review — walk the tasks sitting at status='backlog' and give each one
+// the nod, the axe, or a reset clock (task 1003746).
+//
+// WHY THIS EXISTS. `backlog` is the PRE-WORKABLE state: a task lands there when
+// the system will not put it in the claimable queue without a human saying go
+// (`modules/ideas/routing.js` — "'backlog' means a human still says go"), and
+// ADR 0234 §2 records why: a feature/cleanup/refactor filing "reshape[s] what
+// gets built and a filer should not be able to set the queue's agenda alone".
+// Every OTHER queue in the methodology has a walkable cadence — /idea-triage for
+// idea_inbox, /blocker-review for blockers, /bug-triage for kind=bug,
+// /goal-review for criteria. The backlog had none. Its only pull surfaces were
+// the nod queue (`GET /inbox/awaiting-nod`, scoped `WHERE origin='route'`, so it
+// sees only filings that came through the idea inbox) and the 30-day rot timer.
+// This is the missing walk.
+//
+// Usage:
+//   node scripts/bongos/backlog-review.js [--limit N] [--goal ID] [--all]
+//
+// THE FOUR BUCKETS, AND WHY ONLY TWO GET WALKED. One read
+// (`GET /tasks?status=backlog&include=deps`) partitions into four populations,
+// and conflating them is the whole trap this script exists to avoid — a row
+// waiting on a TRIGGER is not a row waiting on a PERSON, and asking a human to
+// verdict the former wastes the cadence on rows it cannot move:
+//
+//   stranded   — dep-gated, but at least one dependency is ABANDONED. That edge
+//                can never satisfy, so the migration-163 auto-promote trigger
+//                will NEVER fire: the row is stuck, not waiting. WALKED FIRST,
+//                because it is the only bucket that gets worse by being left.
+//   nod        — no unsatisfied dependency: nothing is gating it but a human.
+//                THE REVIEW SUBJECT. This is what "review the backlog" means.
+//   dep-gated  — an unsatisfied dependency that is still alive. COUNTED, NEVER
+//                WALKED: shipping the dependency auto-promotes it (migration
+//                163), so a human verdict here is noise at best and, if it
+//                promotes, races the trigger.
+//   spikes     — kind='spike' rows live at backlog BY CONVENTION (migration 020:
+//                "Spikes stay in backlog by convention"), so they are not
+//                un-nodded work. COUNTED, NEVER WALKED.
+//
+// THE VERBS ARE STATUS-DERIVED, NOT A FIXED LIST. The rot card publishes four
+// task verbs (prioritise/prune/kill/water — `modules/lifecycle/rot.js`), but two
+// of them are status-conditional at the route: `POST /tasks/:id/promote` accepts
+// only backlog|blocked|abandoned, and `POST /tasks/:id/demote` accepts only
+// 'ready' (`modules/lifecycle/routes/tasks.js`). So on a BACKLOG row "prune" is
+// a guaranteed 409 `cannot_demote` — it is already at the bottom. `verbsFor`
+// below derives the offer from the row's actual status instead of hardcoding a
+// list, so this walk can never offer a button the server will refuse.
+//
+// Prompts per row:
+//   [p]romote   → POST /tasks/:id/promote  (backlog → ready; the nod. Also the
+//                 point the reward gate auto-assigns credits_reward if it is
+//                 0/NULL — ADR 0096 — so the assigned price is echoed back)
+//   [k]ill      → POST /tasks/:id/abandon {reason} (it is not going to happen)
+//   [w]ater     → POST /tasks/:id/water (leave it; reset the rot clock. The one
+//                 verb that changes no status and destroys nothing)
+//   [s]kip      → no write; the row surfaces again next review
+//   [q]uit      → exit early, print the partial summary
+//
+// Exit codes:
+//   0  walked cleanly (incl. an empty queue)
+//   1  api / network error
+//   2  no session
+
+const readline = require('node:readline');
+const { cliClient, requireSession, cliExit, hasFlag, arg } = require('./cli-lib');
+
+// The API caps ?limit at 1000 (`routes/tasks.js` — "limit must be a positive
+// integer up to 1000"). Spelled here rather than passed larger-and-hoped:
+// scripts/bongos/audit-deps.js asks for 3000 and every run of it dies on a 400,
+// which is exactly how the stranded rows below went unnoticed.
+const MAX_API_LIMIT = 1000;
+
+// How many rows one sitting offers by default. The queue is routinely in the
+// hundreds; a walk that demands all of them gets abandoned halfway, which is
+// worse than a walk that reliably clears twenty. --all overrides.
+const DEFAULT_WALK_LIMIT = 20;
+
+// A dependency in one of these statuses can never satisfy, so anything gated on
+// it is stranded rather than waiting. Mirrors modules/lifecycle/dead-deps.js
+// DEAD_DEP_STATUSES — kept as its own constant because this script must run from
+// a plain checkout without loading the server's module tree.
+const DEAD_DEP_STATUSES = new Set(['abandoned']);
+
+function prompt(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+function trim(s, n) {
+  const str = String(s || '');
+  return str.length > n ? `${str.slice(0, n - 1)}…` : str;
+}
+
+// unsatisfiedDeps(task) — the dependency edges still holding this row down.
+// `include=deps` returns blocked_by[] with a per-edge `satisfied` flag already
+// computed server-side (modules/lifecycle/db-deps-criteria.js), so this trusts
+// that flag rather than re-deriving "shipped" from a status string here.
+function unsatisfiedDeps(task) {
+  return (task.blocked_by || []).filter((d) => d && !d.satisfied);
+}
+
+function deadDeps(task) {
+  return (task.blocked_by || []).filter((d) => d && DEAD_DEP_STATUSES.has(String(d.status)));
+}
+
+// partitionBacklog(tasks) — the four buckets, from one list of backlog rows.
+// Pure and exported: tests/backlog_review.mjs pins the bucket rules without
+// standing up Postgres, and the ordering below IS the review's priority claim.
+//
+// Order of tests matters and is deliberate: a stranded row is reported as
+// stranded even though it is also dep-gated, because "your gate is dead" is the
+// actionable fact and "you have a gate" is not.
+function partitionBacklog(tasks) {
+  const out = { stranded: [], nod: [], depGated: [], spikes: [] };
+  for (const t of Array.isArray(tasks) ? tasks : []) {
+    if (!t || String(t.status) !== 'backlog') continue;
+    const dead = deadDeps(t);
+    if (dead.length) { out.stranded.push({ ...t, dead_deps: dead }); continue; }
+    if (String(t.kind) === 'spike') { out.spikes.push(t); continue; }
+    if (unsatisfiedDeps(t).length) { out.depGated.push(t); continue; }
+    out.nod.push(t);
+  }
+  // Oldest first in both walked buckets: the row that has waited longest for a
+  // human is the one the cadence exists to catch, and a stable order means an
+  // interrupted walk resumes roughly where it stopped.
+  const byAge = (a, b) => String(a.created_at || '').localeCompare(String(b.created_at || '')) || Number(a.id) - Number(b.id);
+  out.stranded.sort(byAge);
+  out.nod.sort(byAge);
+  return out;
+}
+
+// groupByGoal(rows) — cluster rows into goal groups so the walk is presented
+// goal-by-goal instead of as one flat list.
+//
+// WHY GROUP AT ALL. The nod decision is mostly a SCOPE judgment — "does this goal
+// want this work next" — and that judgment is made once per goal, not once per
+// row. Walking a flat age-ordered list makes the reviewer rebuild the same goal
+// context every few rows and re-decide the same question; clustering lets one
+// context answer five rows in a row.
+//
+// The ORDER still honours oldest-first, one level up: goals are ordered by their
+// own oldest waiting row, and rows inside a goal by age. So the goal that has
+// been ignored longest comes first, and nothing is buried by a chatty neighbour.
+// Returns [{ goal_id, rows }] — pure, exported, and the shape the walk iterates.
+function groupByGoal(rows) {
+  const byAge = (a, b) => String(a.created_at || '').localeCompare(String(b.created_at || '')) || Number(a.id) - Number(b.id);
+  const groups = new Map();
+  for (const t of Array.isArray(rows) ? rows : []) {
+    if (!t) continue;
+    // A goal-less row is its own group rather than being dropped or merged into
+    // some other goal's context. ADR 0250 D4 makes goal_id required on new tasks,
+    // so this is the legacy/system-created tail — small, but it must still be
+    // walkable or the queue would quietly retain rows the walk never offers.
+    const key = t.goal_id == null ? '(no goal)' : String(t.goal_id);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(t);
+  }
+  const out = [];
+  for (const [goal_id, groupRows] of groups) {
+    groupRows.sort(byAge);
+    out.push({ goal_id, rows: groupRows });
+  }
+  // Goals ordered by their oldest row — the age rule, lifted one level.
+  out.sort((a, b) => byAge(a.rows[0], b.rows[0]));
+  return out;
+}
+
+// verbsFor(task) — what the server will ACTUALLY accept on this row, derived
+// from its status. See the header note: promote and demote are each valid for
+// disjoint status sets, so a fixed four-verb list is wrong for every row.
+function verbsFor(task) {
+  const status = String(task && task.status);
+  const verbs = [];
+  if (status === 'backlog' || status === 'blocked' || status === 'abandoned') verbs.push('promote');
+  if (status === 'ready') verbs.push('demote');
+  if (status !== 'shipped' && status !== 'abandoned') verbs.push('kill');
+  verbs.push('water');
+  return verbs;
+}
+
+async function listBacklog({ goalId } = {}) {
+  const api = await cliClient();
+  const query = { status: 'backlog', include: 'deps', limit: MAX_API_LIMIT };
+  if (goalId) query.goal_id = goalId;
+  const r = await api.tasks.getTasks({ query });
+  if (!r.ok) throw new Error(`GET /tasks?status=backlog failed (${r.status}): ${JSON.stringify(r.data)}`);
+  // GET /tasks responds { tasks: [...] }, not a bare array — the same shape trap
+  // that made bug-triage.js throw before listing anything (see its listOpenBugTasks).
+  return r.data?.tasks ?? [];
+}
+
+// Goal id -> title, for the walk's group headers. Fails OPEN: a header that shows
+// a bare id is a cosmetic loss, and a review that refuses to start because the
+// goal list did not load would be a much worse trade.
+async function fetchGoalTitles() {
+  try {
+    const api = await cliClient();
+    const r = await api.goals.getGoals({ query: { limit: 200 } });
+    if (!r.ok) return new Map();
+    return new Map((r.data?.goals ?? []).map((g) => [String(g.id), g.title]));
+  } catch (_) {
+    return new Map();
+  }
+}
+
+async function promoteTask(id) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdPromote({ id, body: {} });
+  if (!r.ok) throw Object.assign(new Error(`promote failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+async function killTask(id, reason) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdAbandon({ id, body: { reason: reason || '' } });
+  if (!r.ok) throw Object.assign(new Error(`kill failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+// The gentlest verb: it changes no status and destroys nothing (routes/rot.js).
+// Its route is `requireBuilder` plus an ownership-or-atom check in the handler —
+// authorized iff you CREATED the task or you hold the see-all-rot atom — so it is
+// not unconditionally open, and a caller who is neither gets a 403 naming both
+// paths. Every caller of THIS script is already Metic+ (the skill's rank gate), who
+// hold that atom per ADR 0157, so in practice it always passes here; the 403 is
+// surfaced verbatim rather than swallowed in case that ever stops being true.
+async function waterTask(id) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdWater({ id, body: {} });
+  if (!r.ok) throw Object.assign(new Error(`water failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+function printCounts(buckets) {
+  const { stranded, nod, depGated, spikes } = buckets;
+  const total = stranded.length + nod.length + depGated.length + spikes.length;
+  console.log(`\nBacklog: ${total} rows`);
+  console.log(`  ${nod.length} awaiting a nod        — a human is the only thing gating these (walked)`);
+  console.log(`  ${stranded.length} stranded              — gated by an ABANDONED dependency; the auto-promote trigger can never fire (walked first)`);
+  console.log(`  ${depGated.length} waiting on a dependency — shipping the dep auto-promotes them (migration 163); not a human decision, not walked`);
+  console.log(`  ${spikes.length} spikes                — live at backlog by convention (migration 020); not walked`);
+}
+
+function printRow(task, idx, total, label) {
+  console.log(`\n[${idx + 1}/${total}] ${label} #${task.id}  ${task.title}`);
+  if (task.description) console.log(`  ${trim(task.description, 300)}`);
+  const bits = [];
+  if (task.goal_id) bits.push(`goal ${task.goal_id}`);
+  if (task.kind) bits.push(task.kind);
+  if (task.discipline && task.discipline !== 'unclassified') bits.push(task.discipline);
+  if (task.est_minutes) bits.push(`~${task.est_minutes}m`);
+  bits.push(task.credits_reward ? `${task.credits_reward} credits` : 'no reward set — promote assigns one');
+  if (task.created_at) bits.push(`filed ${String(task.created_at).slice(0, 10)}`);
+  console.log(`  ${bits.join(' · ')}`);
+  for (const d of task.dead_deps || []) {
+    console.log(`  ⚠ dependency ${d.id} is ${d.status}: "${trim(d.title, 60)}" — this edge can NEVER satisfy.`);
+  }
+  if (task.dead_deps && task.dead_deps.length) {
+    const first = task.dead_deps[0].id;
+    console.log('  → Resolve it deliberately: DROP the dead edge (DELETE /api/bongos/dependencies '
+      + `{"from_kind":"task","from_id":${task.id},"to_kind":"task","to_id":${first}}) `
+      + `or RESTORE the dependency (POST /api/bongos/tasks/${first}/promote returns an abandoned task to backlog).`);
+  }
+}
+
+// The per-row walk. Mutates `state.summary`; returns false when the user quits.
+async function walkRow(rl, task, idx, total, label, state) {
+  printRow(task, idx, total, label);
+  for (;;) {
+    const offer = verbsFor(task).includes('promote')
+      ? '  [p]romote (make claimable) / [k]ill / [w]ater (leave it, reset the clock) / [s]kip / [q]uit > '
+      : '  [k]ill / [w]ater / [s]kip / [q]uit > ';
+    const ans = (await prompt(rl, offer)).trim().toLowerCase();
+
+    if (ans === 'q' || ans === 'quit') return false;
+    if (ans === 's' || ans === 'skip' || ans === '') { state.summary.skipped++; return true; }
+
+    if (ans === 'p' || ans === 'promote') {
+      if (!verbsFor(task).includes('promote')) { console.log(`  ? #${task.id} is '${task.status}' — promote does not apply`); continue; }
+      try {
+        const data = await promoteTask(task.id);
+        state.summary.promoted++;
+        const assigned = data && data.assigned_credits_reward;
+        console.log(`  ✓ #${task.id} → ready${assigned ? ` (reward gate assigned ${assigned} credits)` : ''}`);
+      } catch (err) { console.error(`  ! #${task.id}: ${err.message}`); }
+      return true;
+    }
+
+    if (ans === 'k' || ans === 'kill') {
+      const reason = (await prompt(rl, '  reason (optional, enter to skip): ')).trim();
+      try {
+        await killTask(task.id, reason || 'retired during /backlog-review — not going to happen');
+        state.summary.killed++;
+        console.log(`  ✖ #${task.id} abandoned (restorable: POST /tasks/${task.id}/promote returns it to backlog)`);
+      } catch (err) { console.error(`  ! #${task.id}: ${err.message}`); }
+      return true;
+    }
+
+    if (ans === 'w' || ans === 'water') {
+      try {
+        await waterTask(task.id);
+        state.summary.watered++;
+        console.log(`  ~ #${task.id} watered — the rot clock is reset; nothing else changed`);
+      } catch (err) { console.error(`  ! #${task.id}: ${err.message}`); }
+      return true;
+    }
+
+    console.log('  ? unknown — type p, k, w, s, or q');
+  }
+}
+
+async function main() {
+  await requireSession();
+
+  const goalId = arg('--goal');
+  const walkAll = hasFlag('--all');
+  const limitRaw = Number(arg('--limit'));
+  const walkLimit = walkAll ? Infinity : (Number.isFinite(limitRaw) && limitRaw > 0 ? limitRaw : DEFAULT_WALK_LIMIT);
+
+  let rows;
+  try {
+    rows = await listBacklog({ goalId });
+  } catch (err) {
+    console.error(`backlog-review: ${err.message}`);
+    return cliExit(1);
+  }
+
+  const buckets = partitionBacklog(rows);
+  printCounts(buckets);
+
+  // Goal titles for the group headers — one extra read so a header names the goal
+  // instead of showing a bare id the reviewer has to go look up.
+  const goalTitles = await fetchGoalTitles();
+
+  // Stranded first, then the nod queue — see partitionBacklog's header. Each
+  // bucket is walked goal-by-goal (groupByGoal), and the flattened result keeps
+  // that grouping so the walk's own loop stays a simple sequence.
+  const queue = [];
+  for (const [bucket, label] of [[buckets.stranded, 'STRANDED'], [buckets.nod, 'awaiting a nod']]) {
+    for (const group of groupByGoal(bucket)) {
+      queue.push(...group.rows.map((t, i) => ({
+        task: t,
+        label,
+        // The header rides on the FIRST row of each group, so it prints exactly
+        // once even after the --limit slice cuts the queue mid-group.
+        groupHeader: i === 0
+          ? `${label === 'STRANDED' ? 'Stranded in' : 'Goal'} ${group.goal_id}${goalTitles.get(group.goal_id) ? ` — ${goalTitles.get(group.goal_id)}` : ''} (${group.rows.length} row${group.rows.length === 1 ? '' : 's'})`
+          : null,
+      })));
+    }
+  }
+
+  if (!queue.length) {
+    console.log('\nNothing to review — no backlog row is waiting on a person today.');
+    return cliExit(0);
+  }
+
+  const slice = queue.slice(0, walkLimit === Infinity ? queue.length : walkLimit);
+  if (slice.length < queue.length) {
+    console.log(`\nWalking the ${slice.length} oldest of ${queue.length} (--limit N or --all for more).`);
+  }
+
+  const state = { summary: { promoted: 0, killed: 0, watered: 0, skipped: 0 } };
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (let i = 0; i < slice.length; i++) {
+      if (slice[i].groupHeader) {
+        console.log(`\n${'─'.repeat(72)}\n${slice[i].groupHeader}\n${'─'.repeat(72)}`);
+      }
+      const keepGoing = await walkRow(rl, slice[i].task, i, slice.length, slice[i].label, state);
+      if (!keepGoing) { console.log('\n(quit early)'); break; }
+    }
+  } finally {
+    rl.close();
+  }
+
+  const s = state.summary;
+  console.log(`\nReviewed: ${s.promoted} promoted · ${s.killed} killed · ${s.watered} watered · ${s.skipped} skipped`);
+  const left = queue.length - (s.promoted + s.killed + s.watered);
+  if (left > 0) console.log(`${left} row(s) still awaiting a human — run /backlog-review again to continue.`);
+  return cliExit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`backlog-review: ${err && err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  groupByGoal,
+  partitionBacklog,
+  verbsFor,
+  unsatisfiedDeps,
+  deadDeps,
+  DEAD_DEP_STATUSES,
+  MAX_API_LIMIT,
+  DEFAULT_WALK_LIMIT,
+};

package/scripts/bongos/backup-dropin-sweep.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# scripts/bongos/backup-dropin-sweep.sh — retire the TEMPORARY task-1003925 backup drop-ins
+# once a project's pinned core carries the fix (task 1003930, ADR 0285 follow-up).
+#
+# WHY. Before the nightly-backup fix (task 1003925, core 1.19.750) reached any
+# project, the 10 live project backup units on the control plane got a systemd
+# drop-in — /etc/systemd/system/<slug>-db-backup.service.d/task-1003925-min-bytes.conf
+# (the backup script's min-bytes override, `*_BACKUP_MIN_BYTES=4096`) — so their
+# small-but-valid dumps stopped being rejected.
+# That workaround lives outside every repo, nothing removes it, and while it stays it
+# hides whether the shipped fix actually works per project. Projects move to the fixed
+# core one pin at a time, so this is a SWEEP to re-run after each pin moves, not a
+# one-shot: each run retires only the drop-ins whose project can prove it no longer
+# needs one (a backup run succeeds without it), and names the rest.
+#
+# Run on the control plane as a sudoer:
+#   bash scripts/bongos/backup-dropin-sweep.sh            # survey only — read-only, no sudo writes
+#   bash scripts/bongos/backup-dropin-sweep.sh --apply    # retire the eligible drop-ins + clear ghosts
+#
+# --apply, per eligible project (pinned core >= FIX_VERSION and drop-in present):
+#   rm the drop-in, daemon-reload, `systemctl start <slug>-db-backup.service`, wait for it,
+#   and require exit 0 AND a new dump under /var/backups/gds — else the drop-in is put back
+#   and the project is reported, so a project is never left with no backup at all.
+# Then: `systemctl reset-failed` on any *-db-backup unit whose files are gone (a torn-down
+# project's ghost; teardown removes the files but not the failed state — task 1003940).
+set -uo pipefail
+
+FIX_VERSION="${FIX_VERSION:-1.19.750}"
+DROPIN=task-1003925-min-bytes.conf
+BACKUP_DIR=/var/backups/gds
+APPLY=0; [ "${1:-}" = "--apply" ] && APPLY=1
+
+# The safety copies of retired drop-ins live in a root-owned, mode-0700, mktemp-named
+# dir for the length of one run — never a predictable /tmp/<slug> path a lower-privileged
+# local account could pre-stage a symlink at (CWE-377 / CWE-367 on a shared box). Created
+# only under --apply; removed on exit whatever happened.
+WORK=""
+if [ "$APPLY" = 1 ]; then
+  WORK=$(sudo -n mktemp -d /var/tmp/backup-dropin-sweep.XXXXXX) || { echo "cannot create a root-owned work dir"; exit 1; }
+  trap 'sudo -n rm -rf "$WORK"' EXIT
+fi
+
+# The project's pinned core version: the installed inner manifest under its own checkout.
+core_of() {
+  local slug=$1 pj
+  for pj in "/srv/cloudbongos/$slug/node_modules/@bongos/core/package.json" "/home/lars/$slug/node_modules/@bongos/core/package.json"; do
+    if sudo -n test -r "$pj"; then sudo -n node -e "console.log(require(process.argv[1]).version)" "$pj" 2>/dev/null && return; fi
+  done
+  echo "unknown"
+}
+# semver-ish: is $1 >= $2 ? (sort -V puts the smaller first)
+at_least() { [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | head -1)" = "$2" ]; }
+# The slug rides as a positional argument, never interpolated into the sh -c string.
+dump_count() { sudo -n sh -c 'ls "$1"-*.sql.gz 2>/dev/null | wc -l' _ "$BACKUP_DIR/$1"; }
+
+retired=(); kept=(); failed=()
+echo "== drop-ins vs pinned core (fix = $FIX_VERSION) =="
+for d in /etc/systemd/system/*-db-backup.service.d; do
+  [ -f "$d/$DROPIN" ] || continue
+  unit=$(basename "$d" .service.d); slug=${unit%-db-backup}
+  core=$(core_of "$slug")
+  if [ "$core" != "unknown" ] && at_least "$core" "$FIX_VERSION"; then verdict="ELIGIBLE"; else verdict="keeps drop-in"; fi
+  printf '  %-24s core=%-10s %s\n' "$slug" "$core" "$verdict"
+  if [ "$verdict" != "ELIGIBLE" ]; then kept+=("$slug ($core)"); continue; fi
+  [ "$APPLY" = 1 ] || { retired+=("$slug (would retire)"); continue; }
+  before=$(dump_count "$slug")
+  sudo -n cp "$d/$DROPIN" "$WORK/$slug.conf"
+  sudo -n rm -f "$d/$DROPIN"; sudo -n rmdir "$d" 2>/dev/null || true
+  sudo -n systemctl daemon-reload
+  # Type=oneshot (provision-units.js backupService): `start` blocks until the dump script exits.
+  sudo -n systemctl start "$unit.service"
+  after=$(dump_count "$slug")
+  if systemctl show -p Result --value "$unit.service" | grep -qx success && [ "$after" -gt "$before" ]; then
+    retired+=("$slug ($core; dumps $before→$after)")
+  else
+    sudo -n install -D -m 0644 "$WORK/$slug.conf" "$d/$DROPIN"; sudo -n systemctl daemon-reload
+    failed+=("$slug ($core; backup did not succeed without it — drop-in restored)")
+  fi
+done
+
+echo; echo "== failed *-db-backup units (ghosts of torn-down projects) =="
+ghosts=$(systemctl --failed --no-legend 2>/dev/null | awk '/db-backup/ {print $1 == "●" ? $2 : $1}')
+if [ -z "$ghosts" ]; then echo "  (none)"; else
+  for u in $ghosts; do
+    if [ -e "/etc/systemd/system/$u" ]; then echo "  $u: unit file still present — a real failure, not a ghost; left alone"; continue; fi
+    if [ "$APPLY" = 1 ]; then sudo -n systemctl reset-failed "$u" && echo "  $u: ghost cleared"; else echo "  $u: ghost (would reset-failed)"; fi
+  done
+fi
+
+echo; echo "== summary =="
+echo "  retired (${#retired[@]}): ${retired[*]:-none}"
+echo "  kept    (${#kept[@]}): ${kept[*]:-none}"
+echo "  failed  (${#failed[@]}): ${failed[*]:-none}"
+[ "$APPLY" = 1 ] || echo "  (survey only — re-run with --apply to act)"
+[ "${#failed[@]}" -eq 0 ]

package/scripts/bongos/backup.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Check backup status or trigger a fresh local dump.
+//
+// Usage:
+//   node scripts/bongos/backup.js             — show latest dump info
+//   node scripts/bongos/backup.js --trigger   — fire a fresh dump, then poll until it lands
+//
+// Rank gate: metic+archon.
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+function fmtBytes(n) {
+  if (n == null) return '(unknown size)';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+async function fetchStatus() {
+  const api = await cliClient();
+  const r = await api.backup.getBackupStatus();
+  if (!r.ok) {
+    console.error(`backup status failed (${r.status}):`, r.data);
+    process.exit(1);
+  }
+  return r.data;
+}
+
+function fmtAge(hours) {
+  if (hours == null) return '(unknown age)';
+  if (hours < 48) return `${hours.toFixed(1)}h old`;
+  return `${Math.floor(hours / 24)} days old`;
+}
+
+function printStatus(data) {
+  const d = data.latest_dump;
+  if (!d) {
+    console.log(`Backup dir: ${data.backup_dir}`);
+    console.log('No dumps found yet.');
+    console.log('');
+    console.log('  ⚠️  NO BACKUP EXISTS. There is no restore point for this database.');
+    return;
+  }
+  console.log(`Backup dir:  ${data.backup_dir}`);
+  console.log(`Latest dump: ${d.filename}`);
+  console.log(`  Timestamp: ${d.timestamp}  (${fmtAge(d.age_hours)})`);
+  console.log(`  Size:      ${fmtBytes(d.size_bytes)}`);
+  console.log(`  Retained:  ${d.count} dump(s)`);
+  if (data.trigger_running) console.log('  ⏳ A backup is currently running.');
+  // Loud on purpose. A stale backup previously showed as an ordinary timestamp
+  // the reader had to date themselves — which is how 13 days of failure went
+  // unnoticed on cloudbongos (task 1002479).
+  if (d.stale) {
+    console.log('');
+    console.log(`  ⚠️  STALE — the newest dump is ${fmtAge(d.age_hours)}, past the ${d.stale_after_hours}h threshold.`);
+    console.log('      The nightly backup is probably failing. Check the unit:');
+    console.log('        systemctl status gds-db-backup.service');
+    console.log('        journalctl -u gds-db-backup.service -n 50 --no-pager');
+    console.log('      A 203/EXEC there means the script lost its exec bit — the unit');
+    console.log('      should invoke it via `/usr/bin/env bash <script>`.');
+  } else {
+    console.log(`  ✅ Fresh (threshold ${d.stale_after_hours}h).`);
+  }
+}
+
+async function trigger() {
+  console.log('Requesting fresh backup…');
+  const api = await cliClient();
+  const r = await api.backup.postBackupTrigger();
+  if (r.status === 409) {
+    console.log('A backup is already in progress — polling for it to land…');
+  } else if (!r.ok) {
+    console.error(`trigger failed (${r.status}):`, r.data);
+    process.exit(1);
+  } else {
+    console.log(r.data.message);
+  }
+
+  // Capture the filename of the current latest dump (before the new one lands).
+  const before = await fetchStatus();
+  const beforeFile = before.latest_dump && before.latest_dump.filename;
+
+  // Poll until a newer dump appears (up to ~60 s).
+  const deadline = Date.now() + 60_000;
+  let landed = false;
+  while (Date.now() < deadline) {
+    await new Promise(resolve => setTimeout(resolve, 3_000));
+    const status = await fetchStatus();
+    const nowFile = status.latest_dump && status.latest_dump.filename;
+    if (nowFile && nowFile !== beforeFile) {
+      console.log('\n✅ New dump landed:');
+      printStatus(status);
+      landed = true;
+      break;
+    }
+    process.stdout.write('.');
+  }
+  if (!landed) {
+    console.log('\nTimed out waiting for dump. Check server logs or run again to see status.');
+    process.exit(1);
+  }
+}
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+  if (args.includes('--trigger')) {
+    await trigger();
+  } else {
+    const status = await fetchStatus();
+    printStatus(status);
+  }
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});