@bongos/core 1.17.0

package/scripts/gds/ci-grade.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// scripts/gds/ci-grade.js — run the quality grader IN CI as a fail-closed PR
+// gate (#855, ADR 0042). This is the security KEYSTONE for the ci deploy mode.
+//
+// WHY it must run in CI (not "read the recorded grade"):
+//   POST /api/gds/tasks/:id/grade records the grader scores FROM THE REQUEST
+//   BODY — the server does not independently recompute them. In laptop mode the
+//   grader runs on the OPERATOR's trusted machine, so that's fine. In ci mode the
+//   merge trigger moves to an UNTRUSTED builder machine; a tampered local ship.js
+//   could POST a fake passing grade, so a gate that merely READS the recorded
+//   grade is theater. The only tamper-proof gate runs the grader where the
+//   builder can't touch it: here, in GitHub Actions, against the PR diff.
+//
+// It reuses the EXACT production grading path (ship.js runSubagentGrader → the
+// adversarial worker panel / trivial-diff shot), so a CI pass means the same
+// thing a ship-time pass means. Exit 0 = pass, non-zero = fail (FAIL-CLOSED: any
+// grader error also exits non-zero).
+//
+// SKIP-SAFE until armed: if no grader auth is wired (CLAUDE_CODE_OAUTH_TOKEN /
+// ANTHROPIC_API_KEY), it prints SKIP and exits 0 — so merging this workflow
+// changes nothing until the operator (a) adds the auth secret and (b) marks this
+// a REQUIRED check in branch protection. Mirrors the inert-until-cutover pattern
+// of .github/workflows/deploy-prod.yml (#597). See ADR 0042 cutover precondition #1.
+//
+// Inputs (from the workflow env):
+//   GRADE_BASE_REF      base ref to diff against (default origin/main)
+//   GRADE_TASK_ID       the PR's task id (context only; grading is diff-based)
+//   GRADE_TASK_TITLE    the PR title (context for the grader prompt)
+//   GRADE_VALUE_SUMMARY the PR value summary (context for the grader prompt)
+
+const { execFileSync } = require('node:child_process');
+const ship = require('./ship.js');
+
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+(async () => {
+  // Auth presence — the grader spawns the `claude` CLI; without auth it cannot
+  // run. Until the operator wires it, stay green-but-not-gating (see header).
+  const hasAuth = !!(process.env.CLAUDE_CODE_OAUTH_TOKEN || process.env.ANTHROPIC_API_KEY);
+  if (!hasAuth) {
+    console.log(
+      'grade-gate: SKIP — no grader auth (CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY) configured. ' +
+        'This check is green-but-not-gating until the operator wires the secret AND marks it a required check ' +
+        '(ADR 0042 cutover precondition #1). It is NOT a real gate yet.'
+    );
+    process.exit(0);
+  }
+
+  const base = process.env.GRADE_BASE_REF || 'origin/main';
+  let baseline;
+  try {
+    baseline = git(['merge-base', base, 'HEAD']);
+  } catch (_) {
+    baseline = base; // shallow checkout / no common ancestor — diff against the ref directly
+  }
+
+  const changedFiles = ship.computeChangedFiles(baseline);
+  if (!changedFiles.length) {
+    console.log('grade-gate: no changes vs base — pass (nothing to grade).');
+    process.exit(0);
+  }
+
+  const task = {
+    id: process.env.GRADE_TASK_ID || null,
+    title: process.env.GRADE_TASK_TITLE || '(pull request)',
+  };
+  const valueSummary = process.env.GRADE_VALUE_SUMMARY || '';
+
+  console.log(`grade-gate: grading ${changedFiles.length} changed file(s) vs ${baseline.slice(0, 12)} ...`);
+  const result = await ship.runSubagentGrader({ task, valueSummary, baseline, changedFiles });
+
+  console.log(`grade-gate: verdict = ${result.passed ? 'PASS' : 'FAIL'}`);
+  if (result.notes_md) console.log(String(result.notes_md).slice(0, 6000));
+  // Fail-closed: only an explicit pass exits 0.
+  process.exit(result.passed ? 0 : 1);
+})().catch((err) => {
+  // FAIL-CLOSED: a grader error must block the merge, never wave it through.
+  console.error('grade-gate: FAIL (grader error — failing closed):', err && err.message ? err.message : err);
+  process.exit(1);
+});

package/scripts/gds/claim-recall.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// Claim-time recall hits (#956 / V4.R18 — criterion sessions-start-knowing).
+//
+// When a builder claims a task, surface the top project-knowledge sources for it
+// (POST /api/gds/search — the rank/owner-scoped lexical recall layer, ADR 0060) so
+// the work starts already pointed at the relevant ADRs / recipes / session-logs /
+// learnings instead of re-discovering them. This is the claim-time half of the
+// recall surface the V4.R04 context pack (#942) promised; #963 added the
+// resumed-session (SessionStart) half. The two share the same /api/gds/search call
+// and the same title-cleaning, so a session sees the same knowledge whether it
+// claims fresh or resumes.
+//
+// Contract (mirrors printRelevantLearnings in claim.js): best-effort + SILENT on
+// any failure — it must NEVER block or delay a successful claim. The rows are
+// merged with the learnings surface and deduped, so a learning and its indexed
+// search chunk don't echo each other.
+
+const RECALL_LIMIT = 5;
+
+// ---- pure helpers (exported for tests) -------------------------------------
+
+// Build the search query from the claimed task: the title with the decorative
+// "V4.R18 — " rank prefix and any trailing "(...)" aside stripped (same cleaning
+// as the #963 SessionStart hint), plus a short single-line lead from the
+// description — so the query is the substantive phrase, not planning chrome. The
+// description lead is what distinguishes this from #963's title-only hint: a claim
+// happens with the full task in hand, so we use it.
+function claimRecallQuery(task) {
+  const rawTitle = String((task && task.title) || '').trim();
+  let title = rawTitle
+    .replace(/^[A-Za-z0-9.]+\s+[—-]\s+/, '') // leading "V4.R18 — " / "R18 - " (require spaces around the dash so an in-word hyphen like "co-located" isn't eaten)
+    .replace(/\s*\([^)]*\)\s*$/, '')          // trailing parenthetical aside
+    .trim();
+  if (!title) title = rawTitle; // stripping emptied it → fall back to the raw title
+  const descLead = String((task && task.description) || '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 160)
+    .trim();
+  return [title, descLead].filter(Boolean).join(' ').trim();
+}
+
+// The dedup identities for a row (a recall result OR a learning). A row is a
+// duplicate of another surface if ANY of its keys collide — we key on both the
+// source ref and the title because a learning's ref in the `learnings` table and
+// its indexed `search_chunks` ref don't always match, but the titles do.
+function rowKeys(row) {
+  const keys = [];
+  const ref = row
+    && (row.source_ref || row.source || (Array.isArray(row.related_files) && row.related_files[0]));
+  if (ref) keys.push(`ref:${String(ref).toLowerCase()}`);
+  const t = row && (row.title || row.heading_path);
+  if (t) keys.push(`title:${String(t).toLowerCase()}`);
+  return keys;
+}
+
+// Render the top-N recall sources as a printable block, dropping:
+//   - the claimed task's OWN indexed chunk (source_ref `task:<id>`) — the builder
+//     already holds the task; echoing it is noise (same filter as #963);
+//   - any row that collides with an already-shown learning (`excludeKeys`).
+// Returns null when nothing is left to show, so the caller stays silent.
+function formatRecallSources(results, { limit = RECALL_LIMIT, excludeKeys = [], currentTaskId = null } = {}) {
+  const selfKey = currentTaskId != null ? `ref:task:${String(currentTaskId).toLowerCase()}` : null;
+  const seen = new Set((excludeKeys || []).map((k) => String(k).toLowerCase()));
+  if (selfKey) seen.add(selfKey);
+  const rows = [];
+  for (const r of (Array.isArray(results) ? results : [])) {
+    const keys = rowKeys(r);
+    if (keys.length === 0) continue;
+    if (keys.some((k) => seen.has(k))) continue; // self-match or learning dup
+    keys.forEach((k) => seen.add(k));            // also dedup within the recall set
+    rows.push(r);
+    if (rows.length >= limit) break;
+  }
+  if (rows.length === 0) return null;
+  const lines = [`\n🔎 Relevant project knowledge (${rows.length}):`];
+  for (const r of rows) {
+    const where = r.heading_path || r.source_ref || '';
+    const title = r.title || r.source_ref || '(untitled)';
+    lines.push(`  - ${title}${where ? `  — ${where}` : ''}`);
+  }
+  lines.push('  (rank-scoped recall; run /recall <query> to dig further)');
+  return lines.join('\n');
+}
+
+// ---- network leg (fail-open) -----------------------------------------------
+
+// Query the recall layer for the claimed task and print the top sources, deduped
+// against the learnings already printed (`excludeKeys`). Best-effort + silent —
+// never block a claim. Uses the shared client (throwOnError:false → {status, ok,
+// data}; it does NOT exit the process on a non-2xx, so a swallow here is safe).
+async function printClaimRecall(task, { excludeKeys = [] } = {}) {
+  const q = claimRecallQuery(task);
+  if (!q) return;
+  try {
+    // Over-fetch so dropping the self-match + learning dups still leaves a full set.
+    const limit = RECALL_LIMIT + (excludeKeys ? excludeKeys.length : 0) + 3;
+    const { cliClient } = require('./cli-lib');
+    const api = await cliClient();
+    const r = await api.search.postSearch({ body: { q, limit } });
+    if (!r || r.status !== 200 || !r.data || !Array.isArray(r.data.results)) return;
+    const block = formatRecallSources(r.data.results, {
+      excludeKeys,
+      currentTaskId: task && task.id,
+    });
+    if (block) console.log(block);
+  } catch (_) {
+    // swallow — never block a successful claim on a recall lookup
+  }
+}
+
+module.exports = { claimRecallQuery, rowKeys, formatRecallSources, printClaimRecall, RECALL_LIMIT };

package/scripts/gds/claim.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+// Builder claim — atomically claim a task.
+//
+// Usage:
+//   node scripts/gds/claim.js <task-id> [--worktree NAME]
+//
+// On success: prints the claim id, the task title, and the touches[] so the
+// builder knows the parallel-safety boundary they're working within.
+
+const { execSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { cliClient, requireSession, fmtTouches, printOnboardingNudge } = require('./cli-lib');
+const { nextNumbers, padAdr, padMig } = require('./next-number');
+const { CORE_NS } = require('./migration-namespace');
+const { contextPack, formatContextPack } = require('./context-pack');
+const { printClaimRecall } = require('./claim-recall');
+
+// Fetch up to 3 learnings relevant to the task being claimed. touches[] cleanup
+// [3/8] (task 878): key off the task's discipline + title (always present) rather
+// than its predicted touches[] — touches[] is becoming an optional advisory
+// (#882) and is often empty at claim time, which silently emptied the old lookup.
+// Silent on empty result, errors, or missing endpoint — this is a UX nice-to-have
+// and must never break the claim flow.
+// Returns the dedup keys of the learnings it printed, so the claim-time recall
+// surface (#956) can drop any source it would otherwise echo. Empty array on any
+// miss — the caller treats that as "nothing to exclude".
+async function printRelevantLearnings(task) {
+  const discipline = task && task.discipline;
+  const title = task && task.title;
+  if (!discipline && !title) return [];
+  try {
+    const query = {};
+    if (discipline) query.discipline = String(discipline);
+    if (title) query.title = String(title);
+    const api = await cliClient();
+    const r = await api.learnings.getLearnings({ query });
+    if (r.status !== 200 || !r.data || !Array.isArray(r.data.learnings)) return [];
+    const rows = r.data.learnings.slice(0, 3);
+    if (rows.length === 0) return [];
+    console.log(`\n📚 Relevant learnings (${rows.length}):`);
+    const shownKeys = [];
+    for (const L of rows) {
+      const ref = L.source_ref || L.source || (Array.isArray(L.related_files) && L.related_files[0]) || `#${L.id}`;
+      console.log(`  - ${L.title} (${ref})`);
+      shownKeys.push(`ref:${String(ref).toLowerCase()}`);
+      if (L.title) shownKeys.push(`title:${String(L.title).toLowerCase()}`);
+    }
+    return shownKeys;
+  } catch (_) {
+    // swallow — never block a successful claim on a learnings lookup
+    return [];
+  }
+}
+
+// Discipline-fork at claim (task 1267). If the claimed task's `discipline`
+// names an operating-playbook skill in discipline-modes.json, print a directive
+// so the session opens that playbook instead of working the task the default
+// way. This IS the whole fork — one data lookup on the claim the builder already
+// runs; no hook, the Conductor untouched. `discipline` is already a column, so
+// there is no classification step here. Fail-open in every branch: a missing or
+// invalid map, or a discipline with no entry (engineer/artist today), prints
+// nothing and never breaks a successful claim.
+function printDisciplineMode(task) {
+  try {
+    const discipline = task && task.discipline;
+    if (!discipline) return;
+    const raw = fs.readFileSync(path.join(__dirname, 'discipline-modes.json'), 'utf8');
+    const modes = (JSON.parse(raw) || {}).modes || {};
+    const mode = modes[discipline];
+    if (!mode || !mode.directive) return;
+    console.log('');
+    console.log(`▶ ${mode.label || 'Working mode'} — /${mode.skill}`);
+    console.log(`  ${mode.directive}`);
+  } catch (_) {
+    // never let the mode hint break a successful claim
+  }
+}
+
+function captureHeadSha() {
+  try {
+    return execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+// task 1278: nudge (don't block) when this session's build scripts are behind
+// origin/main. The completion cards + skills are CLI-script features that ride
+// the LOCAL checkout, not the deployed server — a worktree branched from a stale
+// main silently lacks them (the root cause behind the missing cards in session
+// 1c1e12d7: claimed/shipped task 1274 on old scripts). Mirrors ship.js's
+// TOOLING_PATHS preflight, but as a NUDGE — claiming on old scripts is fine, you
+// just miss features. Strictly best-effort + fail-open (never break/slow a claim).
+const STALE_TOOLING_DIRS = ['scripts/gds', 'src/bongos', '.claude/skills'];
+function warnIfToolingStale() {
+  try {
+    // Quiet, timed, fail-open fetch so the diff reflects GitHub's main, not a
+    // stale local ref — catching a stale LOCAL main is the whole point.
+    try {
+      execSync('git fetch origin main', { stdio: 'ignore', timeout: 8000 });
+    } catch (_) {
+      return; // offline / no remote / detached — skip the nudge silently
+    }
+    // `...` (symmetric, merge-base) so the builder's OWN edits to these files
+    // don't trip it — only files where origin/main has moved ahead (same as ship.js).
+    const out = execSync(
+      `git diff --name-only HEAD...origin/main -- ${STALE_TOOLING_DIRS.join(' ')}`,
+      { encoding: 'utf8', timeout: 8000 }
+    );
+    const stale = out.trim().split('\n').filter(Boolean);
+    if (stale.length === 0) return;
+    console.log('');
+    console.log(`⚠ Your build scripts are behind origin/main (${stale.length} file${stale.length === 1 ? '' : 's'} in ${STALE_TOOLING_DIRS.join(', ')}).`);
+    console.log('  Run `git merge origin/main` to pick up the latest — newer skills, fixes, and the in-feed completion cards.');
+  } catch (_) {
+    /* a freshness nudge must never break or slow a claim */
+  }
+}
+
+// task 1275: the CLAIMED stage of the deterministic lifecycle card — the SAME
+// card the ship surfaces, here showing the scope (priority / estimate / touches /
+// version) with the brief in the dropdown and the discipline session as the
+// action. Best-effort: a claim card must never break a successful claim.
+function printClaimCard(task, widgetsEnabled = true) {
+  try {
+    const shipCard = require('../../modules/lifecycle/ship-card');
+    const model = shipCard.buildCardModel({
+      stage: 'claimed',
+      taskId: task.id,
+      title: task.title,
+      description: task.description || '',
+      estMinutes: task.est_minutes != null ? Number(task.est_minutes) : null,
+      touchesCount: Array.isArray(task.touches) ? task.touches.length : null,
+      version: task.version_id,
+      kind: task.kind,
+      priority: task.priority,
+      discipline: task.discipline,
+    });
+    // task 1279: when the builder has widgets off, emitCard prints only the
+    // monospace card (no HTML written or relayed).
+    shipCard.emitCard(model, task.id, { widgetsEnabled });
+  } catch (_) { /* never block a claim on the card */ }
+}
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const taskId = Number(args[0]);
+  if (!Number.isFinite(taskId)) {
+    console.error('usage: node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches]');
+    process.exit(2);
+  }
+  const wIdx = args.indexOf('--worktree');
+  const worktree = wIdx >= 0 ? args[wIdx + 1] : null;
+  // touches[] cleanup [5/8] (task 880): touches[] overlap with another active
+  // claim is ADVISORY for an interactive human claim (just a warning — git merge
+  // is the real collision detector). The autonomous --parallel runner passes
+  // --enforce-touches so adjacency becomes a HARD refusal (it fans concurrent
+  // unsupervised agents that could clobber each other on shared files).
+  const enforceTouches = args.includes('--enforce-touches');
+  const headSha = captureHeadSha();
+
+  const api = await cliClient();
+  const r = await api.claims.postClaims({
+    body: {
+      task_id: taskId,
+      worktree_name: worktree,
+      head_sha: headSha,
+      enforce_touches: enforceTouches,
+    },
+  });
+  if (r.status === 201) {
+    const { claim, task } = r.data;
+    console.log(`Claimed task #${task.id}: ${task.title}`);
+    console.log(`Claim id: ${claim.id}`);
+    console.log(`Version: ${task.version_id}  ·  Priority: P${task.priority ?? '?'}  ·  Credit reward: ${task.credits_reward}`);
+    if (task.parallel_safe === true) console.log('Parallel-safe: yes (eligible for a parallel autonomous slot)');
+    // BV1.R53 (task 1422): module_key is the primary scope signal. touches[] is
+    // demoted to derived/advisory for module-keyed tasks; fall back to it for
+    // tasks that predate module affinity.
+    if (task.module_key) {
+      console.log(`Module scope: ${task.module_key}   →  modules/${task.module_key}/`);
+      console.log('  Build within that directory tree. Files outside it will trigger a drift warning at ship time.');
+    } else {
+      console.log(`Touches: ${fmtTouches(task.touches)}`);
+      // touches[] cleanup [7/8] (task 882): the planning field is optional now.
+      // If none was declared, it'll be backfilled from the real diff at ship.
+      if (!Array.isArray(task.touches) || task.touches.length === 0) {
+        console.log('  (no touches declared — backfilled from your committed diff at ship; build where the work leads)');
+      }
+    }
+    // touches[] cleanup [5/8] (task 880): advisory overlap notice. The claim
+    // succeeded; this is a heads-up that another active claim declares
+    // overlapping files. Self-serialize only if it's genuinely the same code.
+    if (Array.isArray(r.data.overlap_warning) && r.data.overlap_warning.length > 0) {
+      console.log(`\n⚠ touches[] overlaps an active claim: ${r.data.overlap_warning.join(', ')}`);
+      console.log('  Advisory only — your claim stands; git merge is the authoritative collision check.');
+    }
+    for (const ach of (r.data.just_unlocked || [])) {
+      const bonus = ach.credit_bonus > 0 ? ` (+${ach.credit_bonus}c bonus)` : '';
+      console.log(`✨ Achievement unlocked: ${ach.name}${bonus}`);
+    }
+    // task 1278: surface a stale-scripts nudge early, so the builder can merge
+    // main before diving in (and pick up newer skills + the completion cards).
+    warnIfToolingStale();
+    // Claim-time context pack (V4.R26 / #964): the AUTHORITATIVE next-free ADR +
+    // migration numbers, computed deterministically from origin/main ∪ the local
+    // working tree (next-number.js). This supersedes blind trust in the drift-prone
+    // claim-time DB counter, which has handed out already-applied numbers and now
+    // sits ahead of the committed files. Best-effort — never break a claim.
+    let nn = null;
+    try { nn = nextNumbers(); } catch { /* fail-open: skip the hint */ }
+    if (nn) {
+      console.log(`\nNext free numbers (from ${nn.source} ∪ local):`);
+      console.log(`  ADR:        ${padAdr(nn.adr)}   →  docs/adr/${padAdr(nn.adr)}-<slug>.md`);
+      // New core migrations are namespaced core_ (ADR 0108 §5) so a stem can't collide with an
+      // instance/module migration across repos; instance seeds stay bare in migrations/instance/.
+      console.log(`  migration:  ${padMig(nn.migration)}   →  migrations/${CORE_NS}_${padMig(nn.migration)}_<slug>.sql   (core; instance seed → migrations/instance/${padMig(nn.migration)}_<slug>.sql bare)`);
+      if (nn.degraded) console.log('  ⚠ origin/main unreachable — recompute with `node scripts/gds/next-number.js` before committing.');
+    }
+    if (claim.reserved_migration_number != null) {
+      const padded = String(claim.reserved_migration_number).padStart(3, '0');
+      // The DB counter still reserves a number (parallel-claim arbitration), but
+      // it can drift; if it disagrees with the file-derived next-free, trust the
+      // file-derived one (it reflects what is actually committed/applied).
+      const driftNote = nn && nn.migration !== claim.reserved_migration_number
+        ? `  ⚠ DB counter reserved ${padded}, but ${padMig(nn.migration)} is the next free on origin/main — use ${padMig(nn.migration)}.`
+        : '  (No other parallel claim can be allocated this number.)';
+      console.log(`\nMigration counter reserved: ${padded}`);
+      console.log(driftNote);
+    }
+    // Claim-time context pack (V4.R04 / #942, criterion sessions-start-knowing).
+    // Fetch /me ONCE here — it gives the builder's currently-held claims for the
+    // pack, and is reused for the onboarding nudge at the end. Best-effort: the
+    // pack is a UX surface and a /me hiccup must never break a successful claim.
+    let meRes = null;
+    try {
+      const api = await cliClient();
+      meRes = await api.me.getMe();
+    } catch (_) { /* fail-open */ }
+    try {
+      const activeClaims = (meRes && meRes.ok && meRes.data)
+        ? (meRes.data.active_claims || (meRes.data.active_claim ? [meRes.data.active_claim] : []))
+        : [];
+      console.log('');
+      console.log(formatContextPack(contextPack({ activeClaims, currentTaskId: task.id })));
+    } catch (_) { /* never block a claim on the pack */ }
+    if (task.description) {
+      console.log('');
+      console.log(task.description);
+    }
+    // Discipline-fork: route ideator (and any future discipline with a mapped
+    // playbook) into its skill. Printed right after the description so it's the
+    // last thing the builder reads before deciding how to work — task 1267.
+    printDisciplineMode(task);
+    if (worktree) console.log(`\nWorktree: ${worktree}`);
+    // Claim-time knowledge (#956 / V4.R18, criterion sessions-start-knowing):
+    // learnings first (curated, short), then the top recall sources for this task
+    // (ADR 0060 search layer), deduped against the learnings just shown. Both are
+    // best-effort and never block the claim.
+    const shownLearningKeys = await printRelevantLearnings(task);
+    await printClaimRecall(task, { excludeKeys: shownLearningKeys });
+    console.log('\nWhen you finish:');
+    console.log(`  node scripts/gds/ship.js ${task.id} --notes "..." --summary "..."`);
+    console.log('Or to abandon:');
+    console.log(`  node scripts/gds/release.js ${task.id}`);
+    // V3.R13 (#237): post-claim nudge — for a newcomer, this becomes
+    // "Next: Ship thy first work" so the path forward is visible. Reuses the
+    // /me fetched above for the context pack (no second round-trip).
+    try {
+      if (meRes && meRes.ok) {
+        console.log('');
+        printOnboardingNudge(meRes.data);
+      }
+    } catch (_) {
+      // never let a UX nudge break a successful claim
+    }
+    // task 1275: the claimed lifecycle card, last so it's the visual anchor.
+    // task 1279: honour the builder's render-widgets knob (resolved from the /me
+    // fetched above; default ON if /me was unavailable).
+    const widgetsEnabled = meRes && meRes.ok ? (meRes.data?.render?.widgets_enabled !== false) : true;
+    printClaimCard(task, widgetsEnabled);
+    return;
+  }
+  // #766: the newcomer claim gate is now just the one-claim-at-a-time rule
+  // below. A generic stage_required (any future onboarding gate) still renders
+  // cleanly rather than as a raw API error.
+  if (r.data?.error === 'stage_required') {
+    console.error(`Task #${taskId} can't be claimed yet.`);
+    console.error(`  ${r.data.what_to_do || `Clear "${r.data.required_stage_label || r.data.required_stage}" first.`}`);
+    process.exit(1);
+  }
+  if (r.data?.error === 'newcomer_must_ship_first') {
+    console.error(`Task #${taskId} can't be claimed yet — your first work isn't shipped.`);
+    console.error(`  You're holding an active claim on #${r.data.active_task_id}: ${r.data.active_task_title}`);
+    console.error(`  ${r.data.what_to_do || 'Ship or release the current claim first.'}`);
+    process.exit(1);
+  }
+  if (r.data?.error === 'ALREADY_CLAIMED') {
+    console.error(`Task #${taskId} was just claimed by another session. Try a different task.`);
+    process.exit(1);
+  }
+  if (r.data?.error === 'MODULE_CONFLICT') {
+    console.error(`Task #${taskId} has module_key='${r.data.module_key}', but another active claim already owns that module:`);
+    for (const t of r.data.conflictTaskTitles || []) console.error(`  - ${t}`);
+    console.error('Two tasks in the same module cannot run concurrently. Ship or release the in-flight claim first.');
+    process.exit(1);
+  }
+  if (r.data?.error === 'TOUCHES_CONFLICT') {
+    console.error(`Task #${taskId} touches files currently in flight on another claim:`);
+    for (const t of r.data.conflictTaskTitles || []) console.error(`  - ${t}`);
+    console.error('Pick a task with disjoint touches[].');
+    process.exit(1);
+  }
+  if (r.data?.error === 'TASK_NOT_READY') {
+    console.error(`Task #${taskId} is not ready (current status: ${r.data.currentStatus}).`);
+    process.exit(1);
+  }
+  if (r.data?.error === 'DEPS_NOT_SHIPPED') {
+    console.error(`Task #${taskId} can't be claimed yet — these dependencies are not shipped:`);
+    for (const d of r.data.deps || []) {
+      console.error(`  - #${d.id}  [${d.status}]  ${d.title}`);
+    }
+    console.error('Ship those first (or release them) and try again.');
+    process.exit(1);
+  }
+  console.error(`Claim failed (${r.status}):`, r.data);
+  process.exit(1);
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});