@bongos/core 1.17.0

package/scripts/gds/release.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Builder release — cancel an active claim without shipping. No credits awarded.
+//
+// Usage:
+//   node scripts/gds/release.js <task-id> [--reason "..."]
+//
+// The task returns to 'ready' status and is claimable by another session.
+
+const { cliClient, requireSession, arg } = 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/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}`);
+    }
+    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) {
+    if (r.data?.error === 'CLAIM_SESSION_MISMATCH') {
+      const wt = r.data.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.');
+    } 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.`);
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/gds/render-ideas.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Renders generative-ideas.md from the GDS idea_inbox table.
+//
+// Reads via GET /api/gds/inbox (authenticated). Writes a generated markdown
+// view to the repo's top-level generative-ideas.md. The file is overwritten
+// on every run — manual edits will not survive. Capture via /builder-capture
+// or `node scripts/gds/capture.js`; triage via /builder-triage or the API.
+//
+// Note (2026-05-10): the current GET /api/gds/inbox endpoint returns open
+// ideas only (see src/bongos/inbox.js listOpenIdeas). The "Recently Promoted",
+// "Recently Discarded", and "Merged" sections will be empty until the API
+// is extended to expose those statuses. The script is forward-compatible:
+// when /inbox starts returning non-open rows, those sections populate
+// automatically.
+//
+// Usage:
+//   node scripts/gds/render-ideas.js            # writes generative-ideas.md
+//   node scripts/gds/render-ideas.js --dry-run  # prints to stdout instead
+
+const path = require('node:path');
+const fsp = require('node:fs/promises');
+const { cliClient, requireSession } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const OUT_PATH = path.join(REPO_ROOT, 'generative-ideas.md');
+const RECENT_DAYS = 30;
+
+const HEADER = `<!-- GENERATED FILE — Edit via /builder-capture or /builder-triage. Manual edits will be overwritten. -->
+
+# Generative ideas
+
+> **This file is a read-only view of the GDS \`idea_inbox\` table.** It is regenerated by \`scripts/gds/render-ideas.js\`. Do not edit by hand.
+>
+> **Capture an idea:** \`node scripts/gds/capture.js "short title"\` (or the \`/builder-capture\` slash command).
+>
+> **Triage open ideas:** \`/idea-triage\` (or \`PATCH /api/gds/inbox/<id>\` with \`{ status: 'promoted' | 'discarded' | 'merged', promoted_to_task_id: N }\`).
+`;
+
+function fmtTimestamp(iso) {
+  if (!iso) return '—';
+  try {
+    return new Date(iso).toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
+  } catch (_) {
+    return String(iso);
+  }
+}
+
+function daysAgo(iso) {
+  if (!iso) return Infinity;
+  const ms = Date.now() - new Date(iso).getTime();
+  return ms / (1000 * 60 * 60 * 24);
+}
+
+function renderIdea(idea) {
+  const lines = [];
+  const titleSuffix = idea.kind ? ` _(${idea.kind})_` : '';
+  lines.push(`### #${idea.id} — ${idea.title}${titleSuffix}`);
+  lines.push('');
+  const meta = [];
+  meta.push(`captured ${fmtTimestamp(idea.captured_at)}`);
+  if (idea.reviewed_at) meta.push(`reviewed ${fmtTimestamp(idea.reviewed_at)}`);
+  if (idea.suggested_version) meta.push(`suggested → ${idea.suggested_version}`);
+  if (idea.suggested_priority != null) meta.push(`P${idea.suggested_priority}`);
+  if (idea.promoted_to_task_id != null) meta.push(`→ task #${idea.promoted_to_task_id}`);
+  lines.push(`_${meta.join(' · ')}_`);
+  lines.push('');
+  if (idea.body_md && idea.body_md.trim()) {
+    lines.push(idea.body_md.trim());
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function renderSection(heading, ideas, emptyMsg) {
+  const out = [`## ${heading}`, ''];
+  if (!ideas.length) {
+    out.push(`_${emptyMsg}_`);
+    out.push('');
+    return out.join('\n');
+  }
+  for (const idea of ideas) {
+    out.push(renderIdea(idea));
+  }
+  return out.join('\n');
+}
+
+async function fetchAllIdeas() {
+  // GET /api/gds/inbox currently returns open ideas only. We request the max
+  // limit so this works as the inbox grows. When the API is extended to
+  // return other statuses, this script will pick them up automatically.
+  const api = await cliClient();
+  const { ok, status, data } = await api.inbox.getInbox({ query: { limit: 500 } });
+  if (!ok) {
+    throw new Error(`GET /api/gds/inbox failed: HTTP ${status} ${JSON.stringify(data)}`);
+  }
+  return data.ideas || [];
+}
+
+function partition(ideas) {
+  const open = [];
+  const promoted = [];
+  const discarded = [];
+  const merged = [];
+  for (const idea of ideas) {
+    if (idea.status === 'open') {
+      open.push(idea);
+      continue;
+    }
+    // Recency uses reviewed_at when present, otherwise captured_at.
+    const ref = idea.reviewed_at || idea.captured_at;
+    if (daysAgo(ref) > RECENT_DAYS) continue;
+    if (idea.status === 'promoted') promoted.push(idea);
+    else if (idea.status === 'discarded') discarded.push(idea);
+    else if (idea.status === 'merged') merged.push(idea);
+  }
+  // Newest first within each bucket.
+  const byCapturedDesc = (a, b) =>
+    new Date(b.captured_at).getTime() - new Date(a.captured_at).getTime();
+  open.sort(byCapturedDesc);
+  promoted.sort(byCapturedDesc);
+  discarded.sort(byCapturedDesc);
+  merged.sort(byCapturedDesc);
+  return { open, promoted, discarded, merged };
+}
+
+function render(ideas) {
+  const { open, promoted, discarded, merged } = partition(ideas);
+  const renderedAt = new Date().toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
+
+  const parts = [
+    HEADER,
+    `_Last rendered: ${renderedAt} · ${open.length} open · ${promoted.length} promoted (last ${RECENT_DAYS}d) · ${discarded.length} discarded (last ${RECENT_DAYS}d) · ${merged.length} merged (last ${RECENT_DAYS}d)_`,
+    '',
+    '---',
+    '',
+    renderSection('Open', open, 'No open ideas. Inbox zero — capture one with /builder-capture.'),
+    renderSection(
+      `Recently Promoted (last ${RECENT_DAYS} days)`,
+      promoted,
+      'Nothing promoted in the window.'
+    ),
+    renderSection(
+      `Recently Discarded (last ${RECENT_DAYS} days)`,
+      discarded,
+      'Nothing discarded in the window.'
+    ),
+    renderSection(
+      `Merged (last ${RECENT_DAYS} days)`,
+      merged,
+      'Nothing merged in the window.'
+    ),
+  ];
+
+  return parts.join('\n') + '\n';
+}
+
+async function main() {
+  await requireSession();
+  const dryRun = process.argv.includes('--dry-run');
+  const ideas = await fetchAllIdeas();
+  const md = render(ideas);
+  if (dryRun) {
+    process.stdout.write(md);
+    return;
+  }
+  await fsp.writeFile(OUT_PATH, md, 'utf8');
+  console.log(`Wrote ${OUT_PATH} (${ideas.length} idea${ideas.length === 1 ? '' : 's'} fetched)`);
+}
+
+main().catch((err) => {
+  console.error(err.stack || err.message || err);
+  process.exit(1);
+});

package/scripts/gds/repo-metrics.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+// repo-metrics.js — the shared measurement substrate for repo cleanliness
+// (V3.R91 / #352, Layer 0 of the code-simplification plan).
+//
+// "You can't manage what you don't measure." This dependency-free CLI shells
+// out to git / wc / knip and emits a JSON snapshot of repo health, then upserts
+// it into repo_health_snapshots (idempotent on calendar date — rerun same day
+// = upsert, not a new row). The latest row feeds /api/gds/public/repo-health,
+// which renders a trend tile on status.amazonprimea.com.
+//
+// What the snapshot contains:
+//   - total_loc + loc_by_dir   — tracked JS/MJS line counts, per watched dir
+//   - largest_files            — top-N files by line count
+//   - dead_exports / dead_files — knip unused-export / unused-file counts
+//                                 (NULL when knip is unavailable — graceful)
+//   - stale_branches + max_branch_age_days — unmerged claude/* branch hygiene
+//   - confirmed_unshipped      — tasks verified but not yet on main (the
+//                                merge-mode backlog made visible)
+//
+// Usage:
+//   node scripts/gds/repo-metrics.js                 # compute + persist + print
+//   node scripts/gds/repo-metrics.js --json          # print snapshot JSON, persist too
+//   node scripts/gds/repo-metrics.js --no-write       # compute + print, do NOT touch the DB
+//
+// Exit codes:
+//   0  snapshot computed (and persisted unless --no-write)
+//   1  fatal local error
+//
+// Follow-up (scheduling): the design (plan "Layer 3 — janitor") calls for a
+// WEEKLY scheduled routine (.claude/scheduled-tasks/repo-simplify-sweep/) that
+// runs this script, stores the snapshot, and files findings to idea_inbox.
+// That routine is a separate task; until it lands, run this manually or via
+// any cron that can reach the configured DB. It is safe to run any number of
+// times per day — the upsert collapses to one row per date.
+
+const { execSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { hasFlag } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const TOP_N_LARGEST = 15;
+
+// Directories whose net LOC we track explicitly (matches the plan).
+const WATCHED_DIRS = ['src/', 'public/game/', 'scripts/gds/', 'modules/art-pipeline/pipeline/'];
+
+
+// Shell helper that never throws — returns trimmed stdout, or null on failure.
+function sh(cmd, opts = {}) {
+  try {
+    return execSync(cmd, {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 32 * 1024 * 1024,
+      ...opts,
+    }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---------- per-file size + LOC by directory ----------
+
+// List tracked JS/MJS files via git so untracked scratch + node_modules never
+// leak in. Counts lines with wc-equivalent (read + split) so there is no
+// dependency on `wc` argv-length limits across thousands of files.
+function gatherFileSizes() {
+  const listed = sh("git ls-files '*.js' '*.mjs'");
+  const files = listed ? listed.split('\n').map((s) => s.trim()).filter(Boolean) : [];
+  const sizes = [];
+  for (const rel of files) {
+    const abs = path.join(REPO_ROOT, rel);
+    let lines = 0;
+    try {
+      const buf = fs.readFileSync(abs, 'utf8');
+      // Line count = number of newline-separated segments. An empty file is 0;
+      // a file with content but no trailing newline still counts its last line.
+      lines = buf.length === 0 ? 0 : buf.split('\n').length - (buf.endsWith('\n') ? 1 : 0);
+    } catch (_) {
+      continue; // file listed by git but unreadable (deleted mid-run) — skip
+    }
+    sizes.push({ path: rel, lines });
+  }
+  return sizes;
+}
+
+function summarizeSizes(sizes) {
+  const totalLoc = sizes.reduce((acc, f) => acc + f.lines, 0);
+
+  const locByDir = {};
+  for (const dir of WATCHED_DIRS) locByDir[dir] = 0;
+  for (const f of sizes) {
+    for (const dir of WATCHED_DIRS) {
+      if (f.path.startsWith(dir)) {
+        locByDir[dir] += f.lines;
+        break;
+      }
+    }
+  }
+
+  const largest = [...sizes]
+    .sort((a, b) => b.lines - a.lines)
+    .slice(0, TOP_N_LARGEST)
+    .map((f) => ({ path: f.path, lines: f.lines }));
+
+  return { totalLoc, locByDir, largest, fileCount: sizes.length };
+}
+
+// ---------- dead-code / unused-export scan (knip) ----------
+//
+// Depends on R90 having configured knip. We degrade gracefully: if knip is not
+// installed / not configured / errors, dead_exports + dead_files come back
+// NULL and `knip_status` records why, so the rest of the substrate still works.
+function scanDeadCode() {
+  // Is knip even configured? R90 should have added a `knip` block to
+  // package.json and the devDependency. If neither is present, don't even try.
+  let configured = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8'));
+    configured =
+      !!pkg.knip ||
+      fs.existsSync(path.join(REPO_ROOT, 'knip.json')) ||
+      fs.existsSync(path.join(REPO_ROOT, 'knip.jsonc'));
+  } catch (_) {
+    configured = false;
+  }
+  if (!configured) {
+    return { dead_exports: null, dead_files: null, knip_status: 'unconfigured' };
+  }
+
+  // knip --reporter json emits a machine-readable report. Use the locally
+  // installed binary when present; otherwise npx (which may download on first
+  // run). Either way, failures degrade to NULL rather than throwing.
+  const localBin = path.join(REPO_ROOT, 'node_modules', '.bin', 'knip');
+  const runner = fs.existsSync(localBin) ? JSON.stringify(localBin) : 'npx --yes knip';
+  // knip exits non-zero whenever it finds issues, which is the normal case.
+  // Append `|| true` so the shell exit is 0 and sh() returns the JSON stdout;
+  // sh() then only yields null on a genuine spawn failure (knip truly absent).
+  const out = sh(`${runner} --reporter json --no-progress || true`);
+  if (out == null || out === '') {
+    return { dead_exports: null, dead_files: null, knip_status: 'unavailable' };
+  }
+
+  let report;
+  try {
+    report = JSON.parse(out);
+  } catch (_) {
+    return { dead_exports: null, dead_files: null, knip_status: 'unparseable' };
+  }
+
+  // knip v6 JSON shape: { issues: [{ file, files (bool: whole file unused),
+  // exports:[...], types:[...], ... }] }. A top-level `files` array exists in
+  // some reporter modes; handle both. dead_exports sums unused exports+types
+  // across issues; dead_files counts issues whose whole file is unused.
+  let deadFiles = null;
+  let deadExports = null;
+  try {
+    if (Array.isArray(report.issues)) {
+      deadExports = report.issues.reduce((acc, issue) => {
+        const ex = Array.isArray(issue.exports) ? issue.exports.length : 0;
+        const ty = Array.isArray(issue.types) ? issue.types.length : 0;
+        return acc + ex + ty;
+      }, 0);
+      deadFiles = report.issues.reduce(
+        (acc, issue) => acc + (issue.files === true ? 1 : 0),
+        0
+      );
+    }
+    // Some reporter modes additionally surface a flat unused-file list.
+    if (Array.isArray(report.files)) {
+      deadFiles = (deadFiles ?? 0) + report.files.length;
+    }
+    if (deadExports == null && deadFiles == null) {
+      return { dead_exports: null, dead_files: null, knip_status: 'unexpected_shape' };
+    }
+  } catch (_) {
+    return { dead_exports: null, dead_files: null, knip_status: 'unexpected_shape' };
+  }
+  return { dead_exports: deadExports, dead_files: deadFiles, knip_status: 'ok' };
+}
+
+// ---------- branch hygiene ----------
+//
+// Unmerged claude/* branches (local + remote-tracking), counted distinct by
+// short name, plus the age (in days) of the oldest one's last commit.
+function scanBranchHygiene() {
+  sh('git fetch origin --prune'); // best-effort freshen; null on no network
+
+  // All claude/* refs (local heads + origin remotes), with each ref's last
+  // commit unix timestamp. `for-each-ref` is one cheap call.
+  const raw = sh(
+    "git for-each-ref --format='%(refname:short)|%(committerdate:unix)' refs/heads/claude refs/remotes/origin/claude"
+  );
+  if (raw == null || raw === '') {
+    return { stale_branches: 0, max_branch_age_days: null };
+  }
+
+  // Names already merged into main aren't "unmerged" — compute the merged set
+  // once (two cheap calls) rather than per-branch inside the loop.
+  const mergedSet = new Set();
+  for (const cmd of ['git branch --remotes --merged origin/main', 'git branch --merged origin/main']) {
+    for (const b of (sh(cmd) || '').split('\n')) {
+      const n = b.trim().replace(/^\*?\s*/, '').replace(/^origin\//, '');
+      if (n) mergedSet.add(n);
+    }
+  }
+
+  const now = Date.now() / 1000;
+  const byName = new Map(); // short name (origin/ stripped) → newest commit ts
+  for (const line of raw.split('\n')) {
+    const [ref, tsStr] = line.split('|');
+    if (!ref) continue;
+    const name = ref.replace(/^origin\//, '');
+    if (!name.startsWith('claude/')) continue;
+    const ts = Number(tsStr);
+    if (!Number.isFinite(ts)) continue;
+    if (mergedSet.has(name)) continue; // already on main — not unmerged
+    const prev = byName.get(name);
+    if (prev == null || ts > prev) byName.set(name, ts);
+  }
+
+  if (byName.size === 0) return { stale_branches: 0, max_branch_age_days: null };
+
+  let oldestTs = Infinity;
+  for (const ts of byName.values()) oldestTs = Math.min(oldestTs, ts);
+  const maxAgeDays = Number.isFinite(oldestTs)
+    ? Math.round(((now - oldestTs) / 86400) * 10) / 10
+    : null;
+
+  return { stale_branches: byName.size, max_branch_age_days: maxAgeDays };
+}
+
+// ---------- confirmed-but-unshipped task count ----------
+//
+// Reads directly from the DB (same pool the other scripts/gds/*.js writers use
+// — peer auth via the local socket on the droplet, PG* env vars elsewhere).
+async function countConfirmedUnshipped(pool) {
+  try {
+    const { rows } = await pool.query(
+      `SELECT COUNT(*)::int AS n FROM tasks WHERE status = 'confirmed'`
+    );
+    return rows[0]?.n ?? 0;
+  } catch (_) {
+    return 0; // DB unreachable (e.g. off-droplet local run without PG*) — 0
+  }
+}
+
+// ---------- persistence ----------
+
+async function upsertSnapshot(pool, snap) {
+  const { rows } = await pool.query(
+    `INSERT INTO repo_health_snapshots
+       (snapshot_date, total_loc, loc_by_dir, largest_files,
+        dead_exports, dead_files, stale_branches, max_branch_age_days,
+        confirmed_unshipped, raw, created_at)
+     VALUES (CURRENT_DATE, $1, $2, $3, $4, $5, $6, $7, $8, $9, now())
+     ON CONFLICT (snapshot_date) DO UPDATE SET
+        total_loc           = EXCLUDED.total_loc,
+        loc_by_dir          = EXCLUDED.loc_by_dir,
+        largest_files       = EXCLUDED.largest_files,
+        dead_exports        = EXCLUDED.dead_exports,
+        dead_files          = EXCLUDED.dead_files,
+        stale_branches      = EXCLUDED.stale_branches,
+        max_branch_age_days = EXCLUDED.max_branch_age_days,
+        confirmed_unshipped = EXCLUDED.confirmed_unshipped,
+        raw                 = EXCLUDED.raw,
+        created_at          = now()
+     RETURNING id, snapshot_date`,
+    [
+      snap.total_loc,
+      JSON.stringify(snap.loc_by_dir),
+      JSON.stringify(snap.largest_files),
+      snap.dead_exports,
+      snap.dead_files,
+      snap.stale_branches,
+      snap.max_branch_age_days,
+      snap.confirmed_unshipped,
+      JSON.stringify(snap),
+    ]
+  );
+  return rows[0];
+}
+
+// ---------- main ----------
+
+(async () => {
+  const args = process.argv.slice(2);
+  const asJson = hasFlag('--json', args);
+  const noWrite = hasFlag('--no-write', args);
+
+  const sizes = gatherFileSizes();
+  const { totalLoc, locByDir, largest, fileCount } = summarizeSizes(sizes);
+  const dead = scanDeadCode();
+  const branches = scanBranchHygiene();
+
+  // Lazy-require the DB so --no-write can run with no Postgres reachable.
+  let confirmedUnshipped = 0;
+  let pool = null;
+  if (!noWrite) {
+    try {
+      ({ pool } = require('../../src/bongos/pool'));
+      confirmedUnshipped = await countConfirmedUnshipped(pool);
+    } catch (_) {
+      pool = null;
+    }
+  }
+
+  const snap = {
+    total_loc: totalLoc,
+    file_count: fileCount,
+    loc_by_dir: locByDir,
+    largest_files: largest,
+    dead_exports: dead.dead_exports,
+    dead_files: dead.dead_files,
+    knip_status: dead.knip_status,
+    stale_branches: branches.stale_branches,
+    max_branch_age_days: branches.max_branch_age_days,
+    confirmed_unshipped: confirmedUnshipped,
+  };
+
+  let written = null;
+  if (!noWrite && pool) {
+    try {
+      written = await upsertSnapshot(pool, snap);
+    } catch (err) {
+      console.error('failed to persist snapshot:', err.message);
+    } finally {
+      await pool.end().catch(() => {});
+    }
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify({ ...snap, persisted: written }, null, 2));
+  } else {
+    console.log('Repo health snapshot');
+    console.log('────────────────────');
+    console.log(`  total tracked JS/MJS LOC : ${totalLoc} across ${fileCount} files`);
+    for (const dir of WATCHED_DIRS) console.log(`    ${dir.padEnd(16)} ${locByDir[dir]} LOC`);
+    console.log(
+      `  dead exports / files     : ${dead.dead_exports ?? '—'} / ${dead.dead_files ?? '—'}  (knip: ${dead.knip_status})`
+    );
+    console.log(
+      `  unmerged claude/* branches: ${branches.stale_branches}` +
+        (branches.max_branch_age_days != null ? ` (oldest ${branches.max_branch_age_days}d)` : '')
+    );
+    console.log(`  confirmed-but-unshipped  : ${confirmedUnshipped}`);
+    console.log(`  top files:`);
+    for (const f of largest.slice(0, 5)) console.log(`    ${String(f.lines).padStart(5)}  ${f.path}`);
+    if (written) {
+      console.log(`\n  ✓ persisted snapshot for ${written.snapshot_date} (row #${written.id})`);
+    } else if (noWrite) {
+      console.log('\n  (--no-write: snapshot not persisted)');
+    } else {
+      console.log('\n  (DB unreachable — snapshot computed but not persisted)');
+    }
+  }
+
+  process.exit(0);
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/gds/resolve-skill-model.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Resolve the effective model token for a skill invocation.
+//
+// Usage:
+//   node scripts/gds/resolve-skill-model.js <skill-name>
+//
+// Prints one of: opus | sonnet | haiku | script
+//
+// Each SKILL.md that spawns an Agent tool call should invoke this helper
+// at the top to honour the builder's per-skill model preferences (V3.R85
+// / ADR #304). Without this, the skill-model-preferences matrix is
+// honest but inert — the builder sets a preference, but every Agent call
+// still uses whatever model the parent session inherits.
+//
+// Exit 0 + prints the model token on success.
+// Exit 1 + prints an error on failure (network, no session, unknown
+// skill). Callers should treat exit 1 as "fall back to opus" rather
+// than aborting — a failure in preference resolution should not block
+// the skill itself.
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+(async () => {
+  await requireSession();
+  const skillName = process.argv[2];
+  if (!skillName) {
+    console.error('usage: node scripts/gds/resolve-skill-model.js <skill-name>');
+    process.exit(1);
+  }
+
+  const api = await cliClient();
+  const r = await api.me.getMeSkillPrefs();
+  if (!r.ok) {
+    console.error(`resolve-skill-model: GET /me/skill-prefs failed (${r.status})`);
+    process.exit(1);
+  }
+
+  const effective = r.data?.effective;
+  if (!Array.isArray(effective)) {
+    console.error('resolve-skill-model: unexpected response shape');
+    process.exit(1);
+  }
+
+  const row = effective.find((e) => e.skill === skillName);
+  if (!row) {
+    // Unknown skill — not in KNOWN_SKILLS. Fall back to opus so the
+    // caller can proceed; stderr surfaces the gap for the builder.
+    console.error(`resolve-skill-model: '${skillName}' is not in the known-skills list — defaulting to opus`);
+    console.log('opus');
+    process.exit(0);
+  }
+
+  console.log(row.effective_model);
+})().catch((err) => {
+  console.error('resolve-skill-model: fatal:', err.message || err);
+  process.exit(1);
+});