@bongos/core 1.17.0

package/scripts/gds/cost.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Log a cost entry (API spend, infra, art, etc.).
+//
+// Usage:
+//   node scripts/gds/cost.js <amount-usd> <category> [--task-id N] [--description "..."] [--source "..."] [--skill <name>]
+//
+// Categories: api | compute | infra | domain | art | other
+
+const { cliClient, requireSession, arg } = require('./cli-lib');
+
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const amount = Number(args[0]);
+  const category = args[1];
+  if (!Number.isFinite(amount) || !category) {
+    console.error('usage: node scripts/gds/cost.js <amount-usd> <category> [--task-id N] [--description "..."]');
+    console.error('categories: api | compute | infra | domain | art | other');
+    process.exit(2);
+  }
+  const taskIdStr = arg('--task-id', args);
+  const taskId = taskIdStr ? Number(taskIdStr) : null;
+  const description = arg('--description', args);
+  const source = arg('--source', args) || 'manual';
+  const skillName = arg('--skill', args) || null;
+
+  const api = await cliClient();
+  const r = await api.cost.postCost({
+    body: {
+      task_id: taskId,
+      amount_usd: amount,
+      category,
+      description,
+      source,
+      skill_name: skillName,
+    },
+  });
+  if (!r.ok) {
+    console.error(`cost log failed (${r.status}):`, r.data);
+    process.exit(1);
+  }
+  console.log(`Logged $${amount.toFixed(2)} (${category})${taskId ? ` for task #${taskId}` : ''}${skillName ? ` [skill: ${skillName}]` : ''}`);
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/gds/db-backup-nightly.sh

@@ -0,0 +1,160 @@
+#!/bin/bash
+# Nightly pg_dump of the GDS Postgres DB.
+#
+# Runs as user `lars` via the gds-db-backup.timer systemd unit (see
+# scripts/gds/gds-db-backup.timer + .service in this repo). Output lands
+# in /var/backups/gds/ as YYYY-MM-DD-HHMMSS.sql.gz (UTC timestamp), and
+# files older than 30 days are pruned.
+#
+# Authentication: peer auth via the local Unix socket. The user `lars`
+# owns the `amazonprimea` Postgres role; pg_dump finds the socket at
+# /var/run/postgresql with no password needed. Matches the model in
+# src/db.js.
+#
+# Filed by #412 (V3.R62-precondition) — closes the "GDS DB has no
+# nightly backup" gap surfaced by ADR 0024. The OFFSITE copy of these
+# dumps is filed separately as #415 (V3.R62-offsite); this script only
+# handles the local-on-droplet half.
+#
+# Caveat: dumps land on the same physical disk as the live database
+# (/dev/vda1). That protects against corruption, accidental DROP, bad
+# migrations, and "oops I deleted a row" — but NOT whole-droplet loss.
+# #415 closes that remaining gap with a weekly offsite archive.
+#
+# Manual one-shot:
+#   /usr/local/sbin/gds-db-backup.sh
+#
+# Systemd:
+#   sudo systemctl start gds-db-backup.service   # one-shot
+#   sudo systemctl status gds-db-backup.timer    # check schedule
+#   journalctl -u gds-db-backup.service          # see history
+
+set -euo pipefail
+
+# ---- configuration ----------------------------------------------------------
+
+# Destination directory for dumps. Owned by lars:lars, mode 0750.
+BACKUP_DIR="${GDS_BACKUP_DIR:-/var/backups/gds}"
+
+# Database to dump (default: production GDS).
+DB_NAME="${GDS_BACKUP_DB:-amazonprimea}"
+
+# Retention in days. Files older than this (by mtime) are deleted at the
+# end of each successful run. 30 days = 30 daily dumps retained.
+RETENTION_DAYS="${GDS_BACKUP_RETENTION_DAYS:-30}"
+
+# Timestamp format. UTC so dumps sort sanely regardless of TZ.
+TS=$(date -u +"%Y-%m-%dT%H%M%SZ")
+OUT="${BACKUP_DIR}/${DB_NAME}-${TS}.sql.gz"
+
+# ---- preconditions ----------------------------------------------------------
+
+if [ ! -d "$BACKUP_DIR" ]; then
+  echo "ERROR: backup dir $BACKUP_DIR does not exist." >&2
+  echo "       Create it with:" >&2
+  echo "         sudo install -d -o lars -g lars -m 0750 $BACKUP_DIR" >&2
+  exit 2
+fi
+
+if [ ! -w "$BACKUP_DIR" ]; then
+  echo "ERROR: backup dir $BACKUP_DIR is not writable by $(whoami)." >&2
+  exit 2
+fi
+
+# Confirm pg_dump is reachable. Cheap fail-loudly so a missing pg or a
+# misconfigured PATH doesn't silently skip a night.
+if ! command -v pg_dump >/dev/null 2>&1; then
+  echo "ERROR: pg_dump not on PATH." >&2
+  exit 2
+fi
+
+# ---- the dump ---------------------------------------------------------------
+
+echo "[$(date -u +%FT%TZ)] gds-db-backup: dumping ${DB_NAME} → ${OUT}"
+
+# -Fc would give a custom-format dump (recommended for selective restore),
+# but plain SQL + gzip is easier for an Archon to eyeball and easier for the
+# restore-drill to verify.
+#
+# We dump everything with --clean so a restore into a fresh DB drops
+# existing objects first. --if-exists tolerates the no-existing-objects
+# case. --no-owner + --no-privileges keep the dump portable across role
+# names (useful if we ever restore into staging under a different user).
+#
+# --exclude-table-data=search_chunks (#973 review): search_chunks (migration
+# 103, the /recall lexical index) is REGENERABLE derived data — chunked copies
+# of DB prose (already dumped as tasks/learnings/… rows) and repo markdown
+# (already in git). Dumping its rows roughly duplicates the prose corpus and
+# was the dump's dominant growth vector as docs accumulated. Excluding only its
+# DATA keeps the CREATE TABLE + GIN indexes in the dump, so a restore recreates
+# the table empty and the index rebuilds from source: search-ingest-md.js on the
+# next deploy (doc chunks) + search-ingest-db.js nightly (DB prose) — or run both
+# by hand for immediate recall (see docs/recipes/gds-db-backup.md restore drill).
+# The tsv column is GENERATED (never dumped) and the GIN indexes are CREATE-INDEX
+# statements (not data), so the only thing dropped is the duplicated body text.
+#
+# stderr is deliberately NOT filtered (incident 2026-07-02, task 1711). A prior
+# `--verbose 2> >(grep -v "^pg_dump:" >&2)` threw away pg_dump's OWN error lines
+# too (they are `pg_dump: error:`-prefixed) — so a `permission denied` on one
+# orphaned table (credit_log_backup_task1317) failed EVERY dump silently for 12
+# days. Let pg_dump's stderr flow straight to journald; `set -o pipefail` still
+# aborts on a real failure, now visibly in `systemctl status` /
+# `journalctl -u gds-db-backup.service`.
+pg_dump \
+  --dbname="$DB_NAME" \
+  --format=plain \
+  --clean \
+  --if-exists \
+  --no-owner \
+  --no-privileges \
+  --exclude-table-data=search_chunks \
+  | gzip -9 > "$OUT.partial"
+
+# Atomic rename — only flip to the real filename once gzip finishes.
+# A SIGKILL mid-stream leaves a .partial that the next run will overwrite.
+mv "$OUT.partial" "$OUT"
+
+BYTES=$(stat -c '%s' "$OUT")
+echo "[$(date -u +%FT%TZ)] gds-db-backup: wrote ${OUT} (${BYTES} bytes)"
+
+# Min-size sanity guard (incident 2026-07-02, task 1711). pipefail already aborts
+# on a pg_dump error, but this is belt-and-suspenders: a real dump is ~12-20 MB
+# gzipped, so a sub-1-MiB file means an empty/truncated dump slipped through.
+# Fail loudly and delete it so a broken dump can never masquerade as a good one.
+MIN_BYTES="${GDS_BACKUP_MIN_BYTES:-1048576}"
+if [ "$BYTES" -lt "$MIN_BYTES" ]; then
+  echo "[$(date -u +%FT%TZ)] gds-db-backup: ERROR latest dump is only ${BYTES} bytes (< ${MIN_BYTES} floor) — treating as FAILED." >&2
+  rm -f "$OUT"
+  exit 1
+fi
+
+# Size-threshold guard (#973 review). With search_chunks data excluded above the
+# dump stays sub-MB, so a gzipped dump past this threshold means something else
+# grew unexpectedly (a new large table, or the exclusion silently stopped
+# matching after a rename). WARN loudly to journald — never fail the backup, just
+# flag it for a review. Generous default (25 MiB gzipped vs the current sub-1 MB);
+# tune via GDS_BACKUP_WARN_BYTES once real post-exclusion sizes are observed.
+WARN_BYTES="${GDS_BACKUP_WARN_BYTES:-26214400}"
+if [ "$BYTES" -gt "$WARN_BYTES" ]; then
+  echo "[$(date -u +%FT%TZ)] gds-db-backup: WARN latest dump is ${BYTES} bytes (> ${WARN_BYTES} threshold) — review what grew; is it a regenerable table excludable like search_chunks?" >&2
+fi
+
+# ---- retention prune --------------------------------------------------------
+
+# Delete dumps older than RETENTION_DAYS. -mtime +N means strictly older
+# than N days (so RETENTION_DAYS=30 keeps the most recent ~30 dumps).
+# Done AFTER the new dump lands so a streak of failed runs can't erase
+# everything: we never delete on a day we didn't successfully dump.
+PRUNED=$(find "$BACKUP_DIR" -maxdepth 1 -type f \
+    -name "${DB_NAME}-*.sql.gz" \
+    -mtime +"${RETENTION_DAYS}" \
+    -print -delete | wc -l)
+
+if [ "$PRUNED" -gt 0 ]; then
+  echo "[$(date -u +%FT%TZ)] gds-db-backup: pruned ${PRUNED} dump(s) older than ${RETENTION_DAYS}d"
+fi
+
+# ---- emit a one-line summary for journald + monitoring ---------------------
+
+REMAINING=$(find "$BACKUP_DIR" -maxdepth 1 -type f -name "${DB_NAME}-*.sql.gz" | wc -l)
+echo "[$(date -u +%FT%TZ)] gds-db-backup: ok · ${REMAINING} dump(s) retained · ${BYTES} bytes latest"

package/scripts/gds/db-backup-offsite.sh

@@ -0,0 +1,152 @@
+#!/bin/bash
+# Weekly OFFSITE archive of the GDS Postgres dumps.
+#
+# Filed by #415 (V3.R62-offsite) — closes the whole-droplet-loss gap that
+# the local nightly backup (#412, scripts/gds/db-backup-nightly.sh) leaves
+# open. This script does NOT take its own pg_dump: it copies the most
+# recent local dump produced by db-backup-nightly.sh up to a DigitalOcean
+# Space (S3-compatible object storage, off the droplet's disk).
+#
+# Vendor decision: DigitalOcean Spaces over Backblaze B2 — see ADR 0025.
+#
+# Runs as user `lars` via the gds-db-offsite.timer systemd unit (see
+# scripts/gds/gds-db-offsite.service + .timer). Weekly cadence.
+#
+# Authentication: S3-style credentials for the Space live OUTSIDE the repo
+# in /etc/amazonprimea/spaces.env (chmod 600, owned by lars), per ADR 0022.
+# The systemd unit injects them via EnvironmentFile; a manual run sources
+# the same file. Required vars:
+#   SPACES_KEY SPACES_SECRET SPACES_BUCKET SPACES_REGION SPACES_ENDPOINT
+#
+# Manual one-shot:
+#   /home/lars/amazonprimea/scripts/gds/db-backup-offsite.sh
+#
+# Systemd:
+#   sudo systemctl start gds-db-offsite.service   # one-shot
+#   sudo systemctl status gds-db-offsite.timer    # check schedule
+#   journalctl -u gds-db-offsite.service          # see history
+
+set -euo pipefail
+
+# ---- configuration ----------------------------------------------------------
+
+# Where the local nightly dumps land (must match db-backup-nightly.sh).
+BACKUP_DIR="${GDS_BACKUP_DIR:-/var/backups/gds}"
+DB_NAME="${GDS_BACKUP_DB:-amazonprimea}"
+
+# How many weekly offsite copies to retain in the Space before pruning the
+# oldest. 4 = ~1 month of weekly snapshots (Archon decision, #415 claim 338).
+KEEP="${GDS_OFFSITE_KEEP:-4}"
+
+# Key prefix inside the bucket. Keeps offsite dumps namespaced and lets the
+# prune logic scope its list to exactly our objects (and not, say, the dead
+# pg_dump_* objects the retired #7 cron would have written).
+PREFIX="${GDS_OFFSITE_PREFIX:-gds-offsite/}"
+
+# Credentials file. Read only if the SPACES_* vars aren't already set
+# (systemd injects them via EnvironmentFile; this covers manual runs).
+ENV_FILE="${GDS_SPACES_ENV:-/etc/amazonprimea/spaces.env}"
+
+# ---- load credentials -------------------------------------------------------
+
+# Load the env file WITHOUT executing it. We deliberately do NOT `source` it:
+# sourcing runs arbitrary shell if ENV_FILE ever points at hostile content
+# (e.g. a manual run with an attacker-controlled GDS_SPACES_ENV). Instead we
+# extract only the five expected KEY=VALUE lines. `read -r k v` with IFS='='
+# splits on the FIRST '=' only, so base64 secrets containing '/', '+' or '='
+# survive intact.
+if [ -z "${SPACES_KEY:-}" ] && [ -f "$ENV_FILE" ]; then
+  while IFS='=' read -r _k _v; do
+    case "$_k" in
+      SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT)
+        export "$_k=$_v" ;;
+    esac
+  done < <(grep -E '^(SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT)=' "$ENV_FILE" || true)
+fi
+
+missing=()
+for v in SPACES_KEY SPACES_SECRET SPACES_BUCKET SPACES_REGION SPACES_ENDPOINT; do
+  if [ -z "${!v:-}" ]; then missing+=("$v"); fi
+done
+if [ "${#missing[@]}" -gt 0 ]; then
+  echo "ERROR: missing Spaces credentials: ${missing[*]}" >&2
+  echo "       Set them in $ENV_FILE (chmod 600, owned by lars). See ADR 0022 + 0025." >&2
+  exit 2
+fi
+
+# ---- preconditions ----------------------------------------------------------
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "ERROR: python3 not on PATH (needed for the boto3 S3 client)." >&2
+  exit 2
+fi
+if ! python3 -c "import boto3" >/dev/null 2>&1; then
+  echo "ERROR: python3 'boto3' module not installed." >&2
+  echo "       Install with: pip3 install --user boto3   (or: apt install python3-boto3)" >&2
+  exit 2
+fi
+
+# Pick the most recent local dump. We rely on db-backup-nightly.sh having
+# run; if there are no dumps, fail loudly rather than archive nothing.
+LATEST=$(ls -1t "${BACKUP_DIR}/${DB_NAME}-"*.sql.gz 2>/dev/null | head -1 || true)
+if [ -z "$LATEST" ]; then
+  echo "ERROR: no local dumps found in ${BACKUP_DIR} (${DB_NAME}-*.sql.gz)." >&2
+  echo "       The local nightly backup (#412) must run before the offsite copy." >&2
+  exit 2
+fi
+
+BASENAME=$(basename "$LATEST")
+KEY="${PREFIX}${BASENAME}"
+BYTES=$(stat -c '%s' "$LATEST")
+
+echo "[$(date -u +%FT%TZ)] gds-db-offsite: archiving ${LATEST} (${BYTES} bytes) → s3://${SPACES_BUCKET}/${KEY}"
+
+# ---- upload + prune (single boto3 session) ----------------------------------
+
+GDS_OFFSITE_LOCAL="$LATEST" \
+GDS_OFFSITE_KEY="$KEY" \
+GDS_OFFSITE_KEEP="$KEEP" \
+GDS_OFFSITE_PREFIX="$PREFIX" \
+python3 - <<'PYEOF'
+import os, sys
+import boto3
+
+key      = os.environ["SPACES_KEY"]
+secret   = os.environ["SPACES_SECRET"]
+bucket   = os.environ["SPACES_BUCKET"]
+region   = os.environ["SPACES_REGION"]
+endpoint = os.environ["SPACES_ENDPOINT"]
+
+local    = os.environ["GDS_OFFSITE_LOCAL"]
+objkey   = os.environ["GDS_OFFSITE_KEY"]
+prefix   = os.environ["GDS_OFFSITE_PREFIX"]
+keep     = int(os.environ["GDS_OFFSITE_KEEP"])
+
+s3 = boto3.client(
+    "s3",
+    region_name=region,
+    endpoint_url=endpoint,
+    aws_access_key_id=key,
+    aws_secret_access_key=secret,
+)
+
+# Upload. Idempotent: re-running on the same day overwrites the same key.
+s3.upload_file(local, bucket, objkey)
+print(f"[gds-db-offsite] uploaded {objkey}")
+
+# Prune: keep the newest `keep` objects under our prefix, delete the rest.
+resp = s3.list_objects_v2(Bucket=bucket, Prefix=prefix)
+objects = sorted(
+    [o for o in resp.get("Contents", []) if o["Key"].endswith(".sql.gz")],
+    key=lambda o: o["LastModified"],
+)
+to_delete = objects[:-keep] if len(objects) > keep else []
+for obj in to_delete:
+    s3.delete_object(Bucket=bucket, Key=obj["Key"])
+    print(f"[gds-db-offsite] pruned {obj['Key']}")
+
+kept = min(len(objects), keep)
+print(f"[gds-db-offsite] ok · {kept} offsite dump(s) retained · pruned {len(to_delete)}")
+PYEOF
+
+echo "[$(date -u +%FT%TZ)] gds-db-offsite: done"

package/scripts/gds/demote.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Builder demote — the inverse of promote: move a task ready -> backlog.
+//
+// Usage:
+//   node scripts/gds/demote.js <task-id>
+//
+// Use case: a dependency-gated task that was wrongly promoted to `ready` needs to
+// go back to `backlog` (so it stops appearing as claimable) without hand-SQL on
+// prod. Strictly ready -> backlog — the server refuses any other status (a
+// claimed/active task, or a later lifecycle state). Metic+ only (mirrors promote).
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const taskId = Number(args[0]);
+  if (!Number.isFinite(taskId)) {
+    console.error('usage: node scripts/gds/demote.js <task-id>');
+    process.exit(2);
+  }
+
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdDemote({ id: taskId });
+  if (!r.ok) {
+    if (r.data?.error === 'cannot_demote') {
+      console.error(`Cannot demote task #${taskId}: it is '${r.data.current_status}', not 'ready'.`);
+      console.error("demote only moves a task ready -> backlog (the inverse of promote).");
+    } else if (r.data?.error === 'task_not_found') {
+      console.error(`No task #${taskId}.`);
+    } else {
+      console.error(`demote failed (${r.status}):`, r.data);
+    }
+    process.exit(1);
+  }
+  console.log(`Demoted task #${taskId}: status returned to 'backlog'.`);
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/gds/design-sync.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Build a Claude Design token-preview bundle from the repo's design system.
+//
+// Usage:
+//   node scripts/gds/design-sync.js           — build bundle, print manifest JSON
+//   node scripts/gds/design-sync.js --surface <id>  — limit to one surface
+//
+// Output (stdout, JSON):
+//   { bundlePath, files, surfaceIds, summary }
+//
+// The /design-sync skill calls this, then uses the DesignSync MCP tool
+// to push the bundle to a Claude Design project.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { resolveInstanceRoot } = require(path.resolve(__dirname, '..', '..', 'src', 'instance-config'));
+
+// ADR 0108 §1: the design system (src/ui/, config/design-tokens.json) is host
+// content. resolveInstanceRoot() returns the repo root today, so this is
+// byte-identical for the live instance.
+const REPO_ROOT = resolveInstanceRoot();
+
+function arg(flag, args) {
+  const i = args.indexOf(flag);
+  return i !== -1 ? args[i + 1] : null;
+}
+
+(async () => {
+  const args = process.argv.slice(2);
+  const targetSurface = arg('--surface', args) || undefined;
+
+  const adapter = require(path.join(REPO_ROOT, 'src', 'ui', 'adapters', 'claude-design', 'index.js'));
+
+  const result = await adapter.import({
+    repoRoot: REPO_ROOT,
+    ...(targetSurface ? { surfaces: [{ id: targetSurface, path: path.join(REPO_ROOT, 'src', 'ui', targetSurface) }] } : {}),
+  });
+
+  // Build the file list from the bundle dir for the skill to pass to finalize_plan
+  const { bundlePath, surfaceIds, summary } = result;
+  const files = collectFiles(bundlePath, bundlePath);
+
+  const manifest = { bundlePath, files, surfaceIds, summary };
+  process.stdout.write(JSON.stringify(manifest, null, 2) + '\n');
+})().catch(err => {
+  process.stderr.write(`design-sync: ${err.message}\n`);
+  process.exit(1);
+});
+
+function collectFiles(dir, root) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...collectFiles(full, root));
+    } else {
+      out.push(path.relative(root, full));
+    }
+  }
+  return out;
+}

package/scripts/gds/diagnose-achievements.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+'use strict';
+
+// diagnose-achievements.js — for each builder, evaluate every achievement
+// against CURRENT state and compare to what's actually unlocked. A row where the
+// builder is eligible but the achievement is locked is a bug (a missed unlock).
+//
+// The eligibility predicates are NOT redefined here. They live ONCE in
+// modules/economy/achievements.js (STATE_EVALUATORS) and are imported below, so
+// this diagnostic, the backfill (--apply), and the live reconcile-at-ship can
+// never drift apart — the exact failure that silently broke gds-shipper when the
+// rename left stale `src/pms/` copies in three places (idea 44 / idea 50).
+//
+// Must run on the droplet (uses local Postgres via peer auth) — or with PG*
+// env vars set to point at a remote host. A CLI may require a module directly
+// (the memory/grading-carve precedent).
+//
+// Usage:
+//   # report only (exit 1 if any builder has a missed unlock — a smoke check):
+//   ssh lars@104.236.254.243 'cd ~/amazonprimea && node scripts/gds/diagnose-achievements.js'
+//   # backfill: actually unlock every missed achievement (idempotent), then report:
+//   ssh lars@104.236.254.243 'cd ~/amazonprimea && node scripts/gds/diagnose-achievements.js --apply'
+
+const { pool } = require('../../src/bongos/pool');
+const {
+  STATE_EVALUATORS,
+  reconcileBuilderAchievements,
+} = require('../../modules/economy/achievements');
+
+const APPLY = process.argv.includes('--apply');
+
+// --apply: backfill missed unlocks for every builder, reusing the SAME
+// reconcile the ship path runs. Each builder in its own txn so one odd builder
+// can't roll back the rest. Idempotent — re-running unlocks nothing new.
+async function backfill() {
+  const builders = await pool.query('SELECT id, github_login FROM builders ORDER BY id');
+  let totalUnlocked = 0;
+  for (const builder of builders.rows) {
+    const builderId = Number(builder.id);
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      const unlocked = await reconcileBuilderAchievements(client, builderId, {});
+      await client.query('COMMIT');
+      if (unlocked.length > 0) {
+        totalUnlocked += unlocked.length;
+        console.log(
+          `#${builderId} ${builder.github_login}: unlocked ${unlocked.map((u) => u.id).join(', ')}`
+        );
+      }
+    } catch (err) {
+      await client.query('ROLLBACK').catch(() => {});
+      console.error(`#${builderId} ${builder.github_login}: reconcile failed — ${err.message}`);
+    } finally {
+      client.release();
+    }
+  }
+  console.log('');
+  console.log(`Backfill complete. Newly unlocked: ${totalUnlocked}`);
+}
+
+async function main() {
+  if (APPLY) {
+    await backfill();
+  }
+
+  const builders = await pool.query('SELECT id, github_login FROM builders ORDER BY id');
+  let mismatchCount = 0;
+  const rows = [];
+
+  for (const builder of builders.rows) {
+    const builderId = Number(builder.id);
+    const unlocked = await pool.query(
+      'SELECT achievement_id FROM builder_achievements WHERE builder_id = $1',
+      [builderId]
+    );
+    const unlockedSet = new Set(unlocked.rows.map((r) => r.achievement_id));
+
+    for (const ev of STATE_EVALUATORS) {
+      const wouldFire = await ev.fn(pool, builderId);
+      const currentlyUnlocked = unlockedSet.has(ev.id);
+      const mismatch = wouldFire && !currentlyUnlocked;
+      if (mismatch) mismatchCount++;
+      rows.push({
+        builder_id: builderId,
+        github_login: builder.github_login,
+        achievement_id: ev.id,
+        would_fire: wouldFire,
+        currently_unlocked: currentlyUnlocked,
+        mismatch,
+      });
+    }
+  }
+
+  // Tabular output
+  const w = (s, n) => String(s).padEnd(n);
+  console.log(w('builder', 12), w('achievement', 24), w('would_fire', 11), w('unlocked', 9), 'mismatch');
+  console.log('-'.repeat(72));
+  for (const r of rows) {
+    console.log(
+      w(`#${r.builder_id} ${r.github_login}`, 12),
+      w(r.achievement_id, 24),
+      w(r.would_fire ? 'yes' : 'no', 11),
+      w(r.currently_unlocked ? 'yes' : 'no', 9),
+      r.mismatch ? 'BUG' : '-',
+    );
+  }
+  console.log('');
+  console.log(`Mismatch count: ${mismatchCount}`);
+
+  await pool.end();
+  process.exit(mismatchCount === 0 ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error('diagnose-achievements failed:', err);
+  process.exit(2);
+});