@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/claim.js

@@ -0,0 +1,789 @@
+#!/usr/bin/env node
+// Builder claim — atomically claim a task.
+//
+// Usage:
+//   node scripts/bongos/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join] [--here]
+//
+// 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 path = require('node:path');
+const { cliClient, requireSession, fmtTouches, printOnboardingNudge, rewardPolicy, costPlusOnlyNote, detectWorktreeName, cliExit } = require('./cli-lib');
+const { nextNumbers, padAdr, padMig } = require('./next-number');
+const { CORE_NS } = require('./migration-namespace');
+const { contextPack, formatContextPack, resolveWorktreeRoot } = require('./context-pack');
+const { printClaimRecall } = require('./claim-recall');
+const { decideWorktreeClaim, ESCAPE_FLAG } = require('./worktree-claim-guard');
+const { plainCardLines } = require('./plain-cards');
+// task 1003153 — the DEAD dependency edge, one definition shared with the route
+// and the detector. A lifecycle CLI may require the lifecycle module directly
+// (the documented exception in modules/lifecycle/CLAUDE.md).
+const { splitDeadDeps, deadDepHint } = require('../../modules/lifecycle/dead-deps.js');
+const { visualReviewNudge } = require('./visual-review-nudge');
+
+// 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 [];
+  }
+}
+
+// The claimed task's craft (task 1267; pack-aware since 1002990; INJECTED since
+// 1002992). The directive itself — which role pack or skill this craft works
+// from — no longer prints here: GET /me carries it on the active claim and the
+// Conductor relays it on the session's next prompt (src/bongos/craft-mode.js), so
+// it reaches the session whether or not anyone read the claim output. What stays
+// is ONE role indicator line, and the side effect that must happen where the claim
+// happens: landing the mode's module-owned skills (materializeModeSkills below).
+//
+// Reads the registry beside this CLI (the file fitness.js hard-fails on when a
+// pack is missing), through the same helper the server uses. Fail-open in every
+// branch: a missing or invalid map, or a discipline with no entry, prints nothing
+// and never breaks a successful claim.
+function printRoleLine(task) {
+  let mode = null;
+  try {
+    const discipline = task && task.discipline;
+    if (!discipline) return;
+    const { readModes, roleLine } = require('../../src/bongos/craft-mode');
+    mode = readModes(path.join(__dirname, 'discipline-modes.json'))[discipline] || null;
+    if (!mode || !mode.directive) return;
+    console.log('');
+    console.log(roleLine(mode));
+  } catch (_) {
+    // never let the role line break a successful claim
+    return;
+  }
+  materializeModeSkills(mode);
+}
+
+// A task brings its own tools (task 1003486). A mode whose entry opts in with
+// `materializeModuleSkills` lands the module-owned skills its playbook names — for
+// `ui`, the ui-design taste kit /design sends the session to use — into THIS
+// checkout's .claude/skills/, as the untracked, self-ignored copies ADR 0224 defined.
+// Without it a builder is routed to /design, reads that impeccable and minimalist-ui
+// are the tools, and finds none of them on the machine with no error saying why.
+// Carried by the claim rather than a hook or a session start because a workbench is
+// not re-provisioned every session (owner decision 2026-09-02): it runs only when
+// someone actually claims work of that discipline.
+//
+// Fail-open in every branch, like the hint above it: the server already granted the
+// claim, so nothing here may throw past this point — a failure prints the one command
+// that does it by hand. The require is lazy so a claim of any other discipline never
+// pays for loading the materialiser (and a broken materialiser cannot stop a claim).
+function materializeModeSkills(mode) {
+  if (!mode || mode.materializeModuleSkills !== true) return;
+  try {
+    const { materializeModuleSkillsIntoCore, isCoreCheckoutRoot } = require('./claude-materialize');
+    const coreRoot = path.resolve(__dirname, '..', '..');
+    if (!isCoreCheckoutRoot(coreRoot)) return; // a scaffolded instance already has them from `bongos init`
+    const s = materializeModuleSkillsIntoCore({ coreRoot });
+    const n = s.materialized.length;
+    if (n) console.log(`  ✓ ${n} module-owned skill(s) for this mode are in .claude/skills/ (untracked copies — ADR 0224).`);
+  } catch (e) {
+    console.log(`  ⚠ could not land this mode's module-owned skills — run \`node scripts/bongos/claude-materialize.js --module-skills-only\` (${e && e.message}).`);
+  }
+}
+
+// task 1002579 — the I/O half of the worktree-per-claim guard. Probes the tree
+// with resolveWorktreeRoot (the same signal the context pack and skill-preflight
+// read, so there is one answer to "is this the main checkout") plus the current
+// branch, hands both to the pure decision, prints it, and exits 2 on a refusal.
+// Every probe failure degrades to isMainCheckout=null, which the decision treats
+// as allow — a guard that cannot see the tree must never block a real claim.
+function enforceWorktreeClaim(taskId, { allowMainCheckout }) {
+  let tree = { isMainCheckout: null };
+  let branch = null;
+  try {
+    const runGit = (a) => execSync(`git ${a.join(' ')}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    tree = resolveWorktreeRoot({ runGit, cwd: process.cwd() });
+    branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD']).trim() || null;
+  } catch (_) {
+    /* fail-open: an unclassifiable tree is allowed through */
+  }
+  const d = decideWorktreeClaim({
+    isMainCheckout: tree.isMainCheckout,
+    branch,
+    allowMainCheckout,
+    taskId,
+  });
+  if (d.verdict === 'allow') return tree;
+  for (const line of d.lines) console.error(line);
+  if (d.verdict === 'refuse') {
+    for (const line of plainCardLines('main_checkout_claim')) console.error(line);
+    process.exit(2);
+  }
+  console.error('');
+  return tree;
+}
+
+// task 1002592 — a failed worktree DETECTION reaches the builder disguised as a
+// claim CONFLICT, and that disguise is the whole of the original bug report.
+// When detectWorktreeName() yields nothing the claim goes up with
+// worktree_name: null; the server's one-active-claim guard keys on the WORKING
+// TREE, so an unnamed claim falls back to the per-session compare and a
+// genuinely-parallel worktree is refused as a duplicate. The builder then hunts
+// for a claim conflict that does not exist.
+//
+// Only speak when null is WRONG. In the main checkout null is the documented
+// correct answer and the refusal is genuine, so a note there would send the next
+// reader down precisely the wrong path — that distinction is the fix, not a
+// detail of it.
+function worktreeDetectionNote(ctx, taskId) {
+  // The caller must have actually PROBED the tree. Without that this cannot tell
+  // "detection failed" from "nobody looked", and guessing would hang a worktree
+  // warning on every refusal rendered by a caller that never had tree info —
+  // including every pre-existing one. Absence of knowledge is not evidence.
+  if (!ctx || !('worktree' in ctx)) return [];
+  const { worktree, isMainCheckout } = ctx;
+  if (worktree) return [];                // named fine — the refusal is genuine
+  if (isMainCheckout === true) return [];  // null is correct here
+  const why = isMainCheckout === false
+    ? 'this IS a linked worktree, so a name was expected'
+    : 'this tree is not recognisable as the main checkout either';
+  return [
+    `  ⚠ This session could not name its worktree — auto-detect returned nothing, and ${why}.`,
+    '     An unnamed claim is compared per-SESSION instead of per-worktree, so a real parallel',
+    '     worktree is refused as a duplicate. That is very likely what you are looking at, and',
+    '     it is a path-detection problem, not a claim conflict. Name it explicitly to rule it out:',
+    `       node scripts/bongos/claim.js ${taskId} --worktree <name>`,
+  ];
+}
+
+function captureHeadSha() {
+  try {
+    return execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+// Auto-detect this claim's worktree name when --worktree is omitted, so the
+// server's one-active-claim guard (keyed on the WORKING TREE, not the shared auth
+// session) can tell genuinely-parallel worktrees apart. The detector moved to
+// cli-lib.js in task 1003767 — the ship path now needs the SAME answer to satisfy
+// the resolve lock, and two copies drifting apart would strand a ship.
+
+// 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 the ship's
+// TOOLING_PATHSPECS preflight (ship-preflight-steps.js), 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/bongos', '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 */ }
+}
+
+// task 1003138: the envelope/flat normalization from formatClaimFailure, pulled
+// out so the goal-join flow reads the same { code, message, d } regardless of
+// response shape. Pure + exported (tested through both consumers).
+function claimErrorInfo(r) {
+  const errRaw = r && r.data ? r.data.error : undefined;
+  const isEnvelope = errRaw !== null && typeof errRaw === 'object';
+  return {
+    code: isEnvelope ? errRaw.code : errRaw,
+    message: isEnvelope ? errRaw.message : undefined,
+    // Structured fields live under .details in the envelope; fall back to the
+    // top-level body for the legacy flat shape (so both keep working).
+    d: { ...(r && r.data ? r.data : {}), ...((isEnvelope && errRaw.details) || {}) },
+  };
+}
+
+// task 1476: render a failed claim as GUIDANCE, not a raw object dump. The API
+// returns the R01 error envelope (ADR 0116): { error: { code, message, details } }.
+// Older paths returned a flat { error: 'CODE', ...fields } shape. claimErrorInfo
+// normalizes BOTH — without it `r.data.error` is now an object (never === a
+// string), so every branch below silently missed and the refusal printed as
+// `[object Object]`. Pure (no console / no process.exit) + exported so it can be
+// unit-tested against the real envelope shapes. Returns { lines, exit }.
+//
+// task 1002592: server-supplied prose (a task title, a flag reason, a hint) is
+// echoed to the operator's terminal by the branches below. It is our own API, so
+// this is hygiene rather than a live threat — but an unbounded string can carry
+// control characters that repaint a terminal, and a runaway one can bury the
+// guidance it was meant to add. Clip to one line, strip C0/C1 controls, cap length.
+const MAX_LISTED_TASKS = 20;
+
+// QUEUE_GATED_EXIT — the one refusal that is about the QUEUE, not the task
+// (task 1004396). REBASE_REQUIRED refuses every claim until a stranded confirmed
+// task lands, so an unattended caller that reads it as "this task is refused"
+// sets aside task after task for a fault none of them has. Every other refusal
+// keeps exit 1. The autobongos runner is the consumer and pins the same value
+// in a test.
+const QUEUE_GATED_EXIT = 4;
+function clip(s, max = 160) {
+  if (s == null) return '';
+  // eslint-disable-next-line no-control-regex
+  const flat = String(s).replace(/[\u0000--Ÿ]+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+// task 1002592: `ctx` carries what the CALLER knows about the tree
+// ({ worktree, isMainCheckout }) so the session-claim branch can tell a real
+// conflict apart from a failed worktree detection. Optional and defaulted — the
+// function stays pure and every existing caller/test keeps working.
+function formatClaimFailure(r, taskId, ctx) {
+  const info = claimErrorInfo(r);
+  const { lines, exit } = claimFailureGuidance(info, r, taskId, ctx);
+  // task 1003989: the same refusal in plain words, AFTER the curated text so nothing
+  // an engineer relies on moves. The owed-task gate names a flagged reason per task;
+  // the first one is translated too, because that token is what a builder is stuck on.
+  const { code, d } = info;
+  const owed = code === 'REBASE_REQUIRED' ? (d.rebaseTasks || d.rebase_tasks || []) : [];
+  const flagged = owed.length ? plainCardLines(String(owed[0].reason || '')) : [];
+  return { lines: [...lines, ...plainCardLines(code), ...flagged], exit };
+}
+
+function claimFailureGuidance({ code, message, d }, r, taskId, ctx) {
+  const lines = [];
+
+  // #766: a generic onboarding stage gate (kept rendering cleanly, not as raw JSON).
+  if (code === 'stage_required') {
+    lines.push(`Task #${taskId} can't be claimed yet.`);
+    lines.push(`  ${d.what_to_do || `Clear "${d.required_stage_label || d.required_stage}" first.`}`);
+    return { lines, exit: 1 };
+  }
+  // task 1476 (the core case): a session may hold at most ONE active claim
+  // (task 1642 / ADR 0097). This is the most common refusal and previously fell
+  // straight through to the raw dump — the exact "reads like you can't hold more
+  // than one task" complaint from idea 218. Surface it as guidance AND teach how
+  // to parallelize (a separate worktree/session per task, or the hall bulk-claim).
+  if (code === 'session_already_has_active_claim' || code === 'session_claim_check_failed') {
+    const n = d.active_task_id;
+    lines.push(n
+      ? `This session already holds task #${n}${d.active_task_title ? `: ${d.active_task_title}` : ''}.`
+      : 'This session already holds an active claim.');
+    lines.push(`  ${d.what_to_do || (n
+      ? `Run /builder-ship ${n} (or /builder-release ${n}) first, or open a fresh worktree/session for this task.`
+      : 'Ship or release the in-flight claim, or start a fresh worktree/session.')}`);
+    lines.push('  One claim per session keeps each ship isolated (task 1642). To work tasks in PARALLEL, open a separate worktree/session per task — each holds its own single claim — or use the hall work board’s multi-select bulk-claim.');
+    lines.push(...worktreeDetectionNote(ctx, taskId));
+    return { lines, exit: 1 };
+  }
+  if (code === 'newcomer_must_ship_first') {
+    lines.push(`Task #${taskId} can't be claimed yet — your first work isn't shipped.`);
+    lines.push(`  You're holding an active claim on #${d.active_task_id}: ${d.active_task_title}`);
+    lines.push(`  ${d.what_to_do || 'Ship or release the current claim first.'}`);
+    return { lines, exit: 1 };
+  }
+  // task 1002589: the per-session DB backstop index tripped. Distinct from
+  // session_already_has_active_claim (the route guard's own refusal): since
+  // core_204 (task 1002570) the index keys per (session, worktree) —
+  // matching the guard — so this mainly surfaces the same-tree race the guard
+  // couldn't see, or fires on a DB still carrying the migration-180
+  // session-only index. Either way the target task itself is NOT taken — never
+  // render this as "claimed by another session".
+  if (code === 'session_already_has_bound_claim') {
+    const n = d.active_task_id;
+    lines.push(n
+      ? `Task #${taskId} is still free — but this session already holds a bound claim on #${n}${d.active_task_title ? `: ${d.active_task_title}` : ''}.`
+      : `Task #${taskId} is still free — but this session already holds a bound claim on another task.`);
+    lines.push(`  ${d.what_to_do || `Run /builder-ship ${n || '<task>'} (or /builder-release ${n || '<task>'}) first, claim from a separate worktree, or claim with {"bind_session":false} (an unbound claim always coexists).`}`);
+    return { lines, exit: 1 };
+  }
+  // task 1002592: ADR 0120 part 3's owed-rebase gate refuses EVERY new claim, so
+  // it is the refusal a builder is most stuck behind — and it was the only one
+  // with no branch here, printing as a bare `[REBASE_REQUIRED]: REBASE_REQUIRED`
+  // code echo. The server builds a full way-forward menu for it
+  // (rebaseRequiredHint, task 1003768 — /strand-fix leads because it is the one
+  // exit that works with no GitHub push credential, the DOCUMENTED default
+  // posture) and this surface dropped it on the floor. Name the owed tasks, then
+  // print the server's menu.
+  if (code === 'REBASE_REQUIRED') {
+    // task 1004788: only the fixable ones gate; set-aside ones are listed apart.
+    const all = (d.rebaseTasks || d.rebase_tasks || []);
+    const owed = all.filter((t) => !t.waiting).slice(0, MAX_LISTED_TASKS);
+    const waiting = all.filter((t) => t.waiting).slice(0, MAX_LISTED_TASKS);
+    lines.push(owed.length
+      ? `Your queue is gated — ${owed.length} confirmed task(s) are waiting on your rebase:`
+      : 'Your queue is gated — a confirmed task is waiting on your rebase.');
+    for (const t of owed) {
+      lines.push(`  - task ${t.id}${t.title ? `  ${clip(t.title)}` : ''}`);
+      if (t.reason) lines.push(`      flagged: ${clip(t.reason)}`);
+    }
+    if (waiting.length) lines.push('  Waiting, not on you (set aside; they land on their own):');
+    for (const t of waiting) lines.push(`  - task ${t.id}${t.title ? `  ${clip(t.title)}` : ''} — ${clip(t.waits_on || t.reason || 'outside you')}`);
+    lines.push(`  ${clip(d.hint, 600) || 'Clear it with /strand-fix N, or rebase the branch and re-ship — or /builder-release it to give up on one.'}`);
+    return { lines, exit: QUEUE_GATED_EXIT };
+  }
+  if (code === 'ALREADY_CLAIMED') {
+    lines.push(`Task #${taskId} was just claimed by another session. Try a different task.`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'MODULE_CONFLICT') {
+    lines.push(`Task #${taskId} has module_key='${d.module_key}', but another active claim already owns that module:`);
+    for (const t of d.conflictTaskTitles || []) lines.push(`  - ${t}`);
+    lines.push('Two tasks in the same module cannot run concurrently. Ship or release the in-flight claim first.');
+    return { lines, exit: 1 };
+  }
+  if (code === 'TOUCHES_CONFLICT') {
+    lines.push(`Task #${taskId} touches files currently in flight on another claim:`);
+    for (const t of d.conflictTaskTitles || []) lines.push(`  - ${t}`);
+    lines.push('Pick a task with disjoint touches[], or run it in a separate session once the other ships.');
+    return { lines, exit: 1 };
+  }
+  if (code === 'TASK_NOT_READY') {
+    lines.push(`Task #${taskId} is not ready (current status: ${d.currentStatus}).`);
+    if (d.hint) lines.push(`  ${d.hint}`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'TASK_NOT_FOUND') {
+    lines.push(`Task #${taskId} not found — check the id (run /builder-start to list claimable tasks).`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'DEPS_NOT_SHIPPED') {
+    // task 1003153: an ABANDONED dependency can never ship, so "ship those
+    // first" was impossible advice — the task is STRANDED, not waiting. Mark the
+    // dead edges in the list and relay the server's hint (deadDepHint), which
+    // names the two real remedies. Falls back to the original wording when every
+    // unmet dep is genuinely still pending.
+    const dead = new Set(splitDeadDeps(d.deps).dead.map((x) => String(x.id)));
+    lines.push(dead.size
+      ? `Task #${taskId} is STRANDED — a dependency was abandoned and can never satisfy:`
+      : `Task #${taskId} can't be claimed yet — these dependencies are not shipped:`);
+    for (const dep of d.deps || []) {
+      const flag = dead.has(String(dep.id)) ? '  ← ABANDONED: this edge will never satisfy' : '';
+      lines.push(`  - #${dep.id}  [${dep.status}]  ${dep.title}${flag}`);
+    }
+    lines.push(d.hint || deadDepHint(d.deps, taskId) || 'Ship those first (or release them) and try again.');
+    return { lines, exit: 1 };
+  }
+  if (code === 'OPEN_BLOCKER') {
+    // task 1002650: the same rule the claimable feed enforces, spoken at the gate.
+    lines.push(`Task #${taskId} is waiting on an open blocker:`);
+    for (const b of d.blockers || []) lines.push(`  - blocker ${b.id}  ${b.title}`);
+    lines.push('Resolve it first (/blocker-solve N drives one to done; resolving auto-promotes its linked tasks) — or pick another task from /builder-start.');
+    return { lines, exit: 1 };
+  }
+  if (code === 'GOAL_MEMBERSHIP_REQUIRED') {
+    // task 1003138: the non-interactive rendering of the membership refusal —
+    // the interactive offer (runGoalJoinFlow) normally intercepts this code
+    // before it gets here; this branch covers a retry that re-refused, an
+    // unexpected body, or a decline.
+    lines.push(`Task #${taskId} lives in goal ${d.goal_id}${d.goal_title ? ` ("${d.goal_title}")` : ''}${d.visibility ? ` (${d.visibility})` : ''} — you are not a member.`);
+    lines.push(d.action === 'apply'
+      ? `  Apply to join (POST /api/bongos/goals/${d.goal_id}/requests) — nothing can be claimed until an owner approves. Re-run with --join to file the application from here.`
+      : `  Join and claim in one command:  node scripts/bongos/claim.js ${taskId} --join`);
+    return { lines, exit: 1 };
+  }
+  // Fallback — still readable: the message + code, never a raw [object Object].
+  lines.push(`Claim failed (${r ? r.status : '?'})${code ? ` [${code}]` : ''}${message ? `: ${message}` : ''}.`);
+  // task 1002592: whatever the code, if the server sent a way forward, PRINT it.
+  // REBASE_REQUIRED sat in this fallback with a fully-formed hint in its body and
+  // nothing rendered it. The branches above stay the curated wording; this is the
+  // floor, so the next unmapped code can never be mute the same way.
+  if (d && d.hint) lines.push(`  ${clip(d.hint, 600)}`);
+  return { lines, exit: 1 };
+}
+
+// task 1003138 (owner ask, verbatim: 'claude should offer to join so they dont
+// need to go through the ui') — the goal-membership refusal (403
+// GOAL_MEMBERSHIP_REQUIRED, the task-1003137 gate) is resolvable in-session.
+// goalMembershipOfferPlan is the PURE half: given the refusal details it names
+// the offer to make. Exported for unit tests; the I/O lives in runGoalJoinFlow.
+// Returns null when the body is missing the fields the flow needs (falls back
+// to formatClaimFailure), else { action, headerLines, question }.
+function goalMembershipOfferPlan(d, taskId) {
+  if (!d || d.goal_id == null || (d.action !== 'join' && d.action !== 'apply')) return null;
+  const g = d.goal_id;
+  if (d.action === 'join') {
+    return {
+      action: 'join',
+      headerLines: [
+        `✗ Task ${taskId} lives in goal ${g}`,
+        ...(d.goal_title ? [`    "${d.goal_title}" (${d.visibility || 'public'})`] : []),
+        '    You are not a member.',
+      ],
+      question: `Join goal ${g} and claim? [Y/n] `,
+    };
+  }
+  // 'apply' — a private goal, or a public one whose scope is Archon-mediated
+  // (the server folds both to apply; a pending request grants nothing yet).
+  return {
+    action: 'apply',
+    headerLines: d.visibility === 'private'
+      ? [`✗ Goal ${g} is private.`]
+      : [
+        `✗ Task ${taskId} lives in goal ${g}${d.goal_title ? ` ("${d.goal_title}")` : ''} — joining needs approval (Archon-mediated scope).`,
+      ],
+    question: 'Apply to join? [Y/n] ',
+  };
+}
+
+// One yes/no on the real terminal (default yes — the owner-approved [Y/n]
+// shape). Returns null when there is no TTY to ask — the caller then prints
+// the --join re-run hint instead of hanging a non-interactive session.
+async function promptYesNo(question) {
+  if (!process.stdin.isTTY) return null;
+  const readline = require('node:readline/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const a = (await rl.question(question)).trim().toLowerCase();
+    return a === '' || a === 'y' || a === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+// The I/O half of the offer. Outcomes: 'retry' (joined — re-POST the claim),
+// 'stop' (declined / filed / blocked — everything already printed, exit 1),
+// 'unhandled' (fall through to formatClaimFailure). Never joins or files
+// without a yes: --join is the standing yes for non-interactive sessions.
+async function runGoalJoinFlow({ api, d, taskId, assumeYes }) {
+  const plan = goalMembershipOfferPlan(d, taskId);
+  if (!plan) return 'unhandled';
+  const goalId = d.goal_id;
+  for (const line of plan.headerLines) console.error(line);
+
+  const yes = assumeYes ? true : await promptYesNo(plan.question);
+  if (yes === null) {
+    // Non-interactive (an agent session): make the one-command path explicit.
+    console.error(plan.action === 'join'
+      ? `  To join goal ${goalId} and claim in one command:  node scripts/bongos/claim.js ${taskId} --join`
+      : `  To file the application from here:  node scripts/bongos/claim.js ${taskId} --join   (nothing claimable until approved)`);
+    return 'stop';
+  }
+  if (!yes) {
+    // The owner chose the explicit-join model — declining leaves NO membership
+    // row and NO request.
+    console.error(plan.action === 'join'
+      ? '  Declined — nothing joined, nothing claimed.'
+      : '  Declined — no application filed, nothing claimed.');
+    return 'stop';
+  }
+
+  if (plan.action === 'join') {
+    const jr = await api.goals.postGoalsIdJoin({ id: goalId, body: {} });
+    if (jr.status === 200 || jr.status === 201) {
+      console.error(`+ joined goal ${goalId} (member)`);
+      return 'retry';
+    }
+    const j = claimErrorInfo(jr);
+    if (j.code === 'archon_approval_required') {
+      // The third branch, handled honestly (routes/goals.js:615): a PUBLIC goal
+      // with protected scope is not self-joinable — don't loop, name the path.
+      console.error(`✗ Goal ${goalId}'s scope is Archon-mediated — self-join is not allowed.`);
+      console.error(`  Request to join instead:  node scripts/bongos/claim.js ${taskId} --join  (after the server re-offers apply), or ask an Archon to add you.`);
+      return 'stop';
+    }
+    if (j.code === 'goal_private') {
+      // Visibility flipped between refusal and join — report, don't loop.
+      console.error(`✗ Goal ${goalId} is private now — request to join (POST /api/bongos/goals/${goalId}/requests) and wait for approval.`);
+      return 'stop';
+    }
+    console.error(`✗ join failed (${jr.status})${j.code ? ` [${j.code}]` : ''}${j.message ? `: ${j.message}` : ''}.`);
+    return 'stop';
+  }
+
+  // 'apply' — file the request; a pending row grants nothing, so never retry
+  // the claim here.
+  const ar = await api.goals.postGoalsIdRequests({ id: goalId, body: {} });
+  if (ar.status === 201) {
+    console.error('+ request filed — pending owner approval');
+    console.error('  (nothing to claim until approved)');
+    return 'stop';
+  }
+  const a = claimErrorInfo(ar);
+  if (a.code === 'request_pending') {
+    // The core_188 partial-unique: one pending ask per goal per builder —
+    // re-running reports, it does not error.
+    console.error('• already pending — your earlier request for this goal awaits owner approval.');
+    console.error('  (nothing to claim until approved)');
+    return 'stop';
+  }
+  console.error(`✗ application failed (${ar.status})${a.code ? ` [${a.code}]` : ''}${a.message ? `: ${a.message}` : ''}.`);
+  return 'stop';
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const taskId = Number(args[0]);
+  if (!Number.isFinite(taskId)) {
+    console.error('usage: node scripts/bongos/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join] [--here]');
+    process.exit(2);
+  }
+  // task 1002579: worktree-per-claim, enforced BEFORE anything happens — before
+  // the session check, before the POST. The whole point is that the builder
+  // learns at claim time, not from a stranded ship hours later.
+  const tree = enforceWorktreeClaim(taskId, { allowMainCheckout: args.includes(ESCAPE_FLAG) });
+  await requireSession();
+  const wIdx = args.indexOf('--worktree');
+  // Explicit --worktree always wins; otherwise auto-detect a linked worktree so
+  // parallel worktrees off one login each hold their own claim (the server guard
+  // keys on this). null in the main checkout → unchanged one-claim behaviour.
+  const worktree = (wIdx >= 0 ? args[wIdx + 1] : null) || detectWorktreeName();
+  // 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');
+  // task 1003138: --join is the standing yes to the goal-membership offer —
+  // join (public) or file the application (private/protected) and, for a join,
+  // retry the claim, all in one command. Without it an interactive session is
+  // asked [Y/n]; a non-TTY session is shown the --join re-run line.
+  const assumeYes = args.includes('--join');
+  const headSha = captureHeadSha();
+
+  const api = await cliClient();
+  const postClaim = () => api.claims.postClaims({
+    body: {
+      task_id: taskId,
+      worktree_name: worktree,
+      head_sha: headSha,
+      enforce_touches: enforceTouches,
+      // --auto-pickup (task 1004679, ADR 0371 D5): the Autobongos tweak lane's mark.
+      ...(args.includes('--auto-pickup') ? { auto_pickup: true } : {}),
+    },
+  });
+  let r = await postClaim();
+  // task 1003138: a goal-membership refusal (the task-1003137 gate) is
+  // resolvable in-session — offer the join/application, and on a successful
+  // join retry the claim ONCE (a second refusal falls through to the plain
+  // rendering; never loop).
+  if (r.status !== 201 && claimErrorInfo(r).code === 'GOAL_MEMBERSHIP_REQUIRED') {
+    const outcome = await runGoalJoinFlow({ api, d: claimErrorInfo(r).d, taskId, assumeYes });
+    if (outcome === 'retry') {
+      r = await postClaim();
+    } else if (outcome === 'stop') {
+      return cliExit(1); // everything already printed; no claim landed
+    }
+  }
+  if (r.status === 201) {
+    const { claim, task } = r.data;
+    console.log(`Claimed task #${task.id}: ${task.title}`);
+    console.log(`Claim id: ${claim.id}`);
+    // The reward figure is the task's ADVERTISED estimate. On a cost-plus-only
+    // instance it is never paid, so label it as an estimate and name the real
+    // payer right here — this line is where the expectation forms (task 1002469).
+    const rewardLabel = rewardPolicy(r.data.reward).perTaskCredit ? 'Credit reward' : 'Credit reward (est. only)';
+    console.log(`Version: ${task.version_id}  ·  Priority: P${task.priority ?? '?'}  ·  ${rewardLabel}: ${task.credits_reward}`);
+    const cpNote = costPlusOnlyNote(r.data.reward);
+    if (cpNote) console.log(`  ${cpNote}`);
+    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.');
+    }
+    // task 1001741: goal-aware — an unclaimed OPEN sibling in the same goal
+    // declares overlapping files. Same advisory posture as above.
+    if (Array.isArray(r.data.sibling_overlap_warning) && r.data.sibling_overlap_warning.length > 0) {
+      console.log('\n⚠ touches[] overlaps open sibling task(s) in this goal:');
+      for (const s of r.data.sibling_overlap_warning) {
+        console.log(`  #${s.task_id} ${s.title} — ${s.overlapping_paths.join(', ')}`);
+      }
+      console.log('  Advisory only — a goal owner can sequence or rescope these from the goal page.');
+    }
+    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/bongos/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);
+    }
+    // The craft's role line (and, for a mode that opts in, its module-owned
+    // skills). The full directive reaches the session through the Conductor —
+    // task 1002992.
+    printRoleLine(task);
+    // task 1004202: a task that changes a page is told to use /design and get its
+    // human's OK on the before/after. A nudge, never a gate: gating on that OK would
+    // put a person's approval in the land path, which ADR 0162 retired.
+    try {
+      const nudge = visualReviewNudge(task);
+      if (nudge) console.log(`\n${nudge.join('\n')}`);
+    } catch (_) { /* never let a hint break a successful claim */ }
+    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/bongos/ship.js ${task.id} --notes "..." --summary "..."`);
+    console.log('Or to abandon:');
+    console.log(`  node scripts/bongos/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;
+  }
+  // Any non-201 comes here. formatClaimFailure normalizes the R01 error envelope
+  // and renders the refusal as guidance (task 1476) — one place, unit-tested.
+  const failure = formatClaimFailure(r, taskId, {
+    worktree,
+    isMainCheckout: tree ? tree.isMainCheckout : null,
+  });
+  for (const line of failure.lines) console.error(line);
+  // task 1002592: this exit runs immediately after the claim request, which is
+  // exactly where Windows aborts teardown — "Assertion failed: !(handle->flags &
+  // UV_HANDLE_CLOSING)" — turning a refusal's intended exit 1 into 127. Measured
+  // 3/3 aborting before this change. Set the code, let the loop drain (1002734).
+  cliExit(failure.exit);
+}
+
+// Only auto-run when invoked directly (`node claim.js …`); a `require()` (the
+// unit test) just imports formatClaimFailure without executing the claim flow.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    cliExit(1);
+  });
+}
+
+module.exports = { formatClaimFailure, claimErrorInfo, goalMembershipOfferPlan, materializeModeSkills, printRoleLine, worktreeDetectionNote, QUEUE_GATED_EXIT };