@bongos/core 1.19.715 → 1.19.724

package/modules/ui-design/styles/README.md

@@ -1,6 +1,6 @@
 # `modules/ui-design/styles/` — the style library: looks as branding packs
 
-A **look** is something a builder or an instance owner picks for a new surface or a whole instance. The library ships looks as **branding packs** ([task 1003323](https://cloudbongos.com/builders#/task/1003323), [ADR 0219](../../../docs/adr/<redacted>.md)): the thirteen colours and the two font stacks of `theme.ui` (the fifteen host-overridable tokens, [ADR 0062 §3](../../../docs/adr/<redacted>.md) / [ADR 0196](../../../docs/adr/<redacted>.md)), a `DESIGN.md` of the look's derived recipes in the frontmatter shape the chrome world uses, and one specimen mock. **Never a fork of a sheet.** The drift tests already prove every served sheet reads only the contract, so a look that needs a sixteenth token is a contract change and an ADR, not a style.
+A **look** is something a builder or an instance owner picks for a new surface or a whole instance. The library ships looks as **branding packs** ([task 1003323](https://cloudbongos.com/builders#/task/1003323), [ADR 0219](../../../docs/adr/0219-a-look-is-a-branding-pack-the-style-library.md)): the thirteen colours and the two font stacks of `theme.ui` (the fifteen host-overridable tokens, [ADR 0062 §3](../../../docs/adr/0062-medusa-instance-model-decoupling.md) / [ADR 0196](../../../docs/adr/0196-chrome-world-token-contract-and-the-landing-sheets.md)), a `DESIGN.md` of the look's derived recipes in the frontmatter shape the chrome world uses, and one specimen mock. **Never a fork of a sheet.** The drift tests already prove every served sheet reads only the contract, so a look that needs a sixteenth token is a contract change and an ADR, not a style.
 
 ## The catalogue
 
@@ -8,7 +8,7 @@ A **look** is something a builder or an instance owner picks for a new surface o
 |---|---|---|---|
 | `chrome-world` | the neutral pack, byte for byte | The canonical entry: one iridescent chrome sculpture in a black void, pale grey paper in light, one warm salmon that lights only the pressable and the live. Its recipes are the repo-root [`DESIGN.md`](../../../DESIGN.md); [`chrome-world/DESIGN.md`](chrome-world/DESIGN.md) points there. | the world round's pick (task 1003296 → 1003298) |
 | `expedition` | warm paper, lamp yellow, Archivo | A printed field journal: a halftone screen over the paper, hairline frames instead of a grid, big heavy uppercase headlines, the yellow as a fill only. [`expedition/DESIGN.md`](expedition/DESIGN.md) | `docs/design/mocks/world/natgeo-editorial` (kept in round 1) |
-| `blueprint` | cool grey-blue paper, cyanotype blue, slate green, IBM Plex Sans | A drafting table under north light: a faint graph lattice on the ground, compartments registered to the board with a crosshair tick at a 2px cut edge, the display voice in sentence case, every figure mono and tabular, one cyanotype blue on what is pressable, a slate green for what was measured and a rust pencil for what went wrong. The library's first cool look. [`blueprint/DESIGN.md`](blueprint/DESIGN.md) | authored through the `/style` session ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../docs/adr/<redacted>.md)) |
+| `blueprint` | cool grey-blue paper, cyanotype blue, slate green, IBM Plex Sans | A drafting table under north light: a faint graph lattice on the ground, compartments registered to the board with a crosshair tick at a 2px cut edge, the display voice in sentence case, every figure mono and tabular, one cyanotype blue on what is pressable, a slate green for what was measured and a rust pencil for what went wrong. The library's first cool look. [`blueprint/DESIGN.md`](blueprint/DESIGN.md) | authored through the `/style` session ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../docs/adr/0231-the-style-session-an-owner-authors-a-look-inside-the-contract.md)) |
 | `grove` | pale sage, tan, sea green, Nunito | A sculpted paper garden: soft corners on everything that holds content, tinted shadows, the sea as a slab a whole band sits on, the tan as the one lit thing. [`grove/DESIGN.md`](grove/DESIGN.md) | `docs/design/mocks/world/organic-cards` (kept in round 1) |
 
 The owner looked at both alternates on the sheet on 2026-09-01 and kept them ("styles look good for a start"). Both alternates were **retuned against the contract**, which is a measurement and not a taste: a pack's thirteen are laid through three sheets that already exist (the landing's `world.css`, the hub's `cosmos.css`, the hall's `style.css`) and every pair those sheets paint must clear AA under it. The grove's sage ground lifted and its inks deepened until the hub's fixed status vocabulary and the hall's chips cleared; the expedition's `ink-faint` deepened one step. What a pack cannot carry is **dark**: the contract is light values only, and every sheet's dark tier is its own black, which a look reaches through its accent and its faces. So the grove's green dark ground stays in the world round's mock and does not travel.
@@ -51,7 +51,7 @@ SURFACE=modules/ui-design/styles/expedition STYLE=expedition node modules/ui-des
 
 ## Adding a look
 
-The steps below are the manual path. The **`/style` session** ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../docs/adr/<redacted>.md)) walks them with an owner instead: it renders the nearest entries before it asks anything, drafts inside the contract, retunes against the same measurements below with a failure-to-fix table, and hands over the one-step adoption without taking it. `blueprint` was authored that way.
+The steps below are the manual path. The **`/style` session** ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../docs/adr/0231-the-style-session-an-owner-authors-a-look-inside-the-contract.md)) walks them with an owner instead: it renders the nearest entries before it asks anything, drafts inside the contract, retunes against the same measurements below with a failure-to-fix table, and hands over the one-step adoption without taking it. `blueprint` was authored that way.
 
 1. Make the dir with the three files; start from the alternate nearest to it.
 2. `node modules/ui-design/kit/contrast.js --pack <name>` until the floor is clean; then `node --test tests/ui_design_styles.mjs`, which runs the world / cosmos / hall suites under the pack and tells you the exact pair that fails. Tune the thirteen, never the sheets.

package/modules/ui-design/styles/blueprint/DESIGN.md

@@ -75,7 +75,7 @@ components:
 
 # Style: The Blueprint
 
-**Origin.** Authored through the `/style` session ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../../docs/adr/<redacted>.md)) from a two-line brief: *"a drafting table under north light, cool paper and graphite; one cyanotype blue on what is pressable, a rust pencil for what went wrong."* The library's three existing looks are all warm and all carry a warm accent (salmon, lamp yellow, tan), so the search step found no near neighbour and the session drafted rather than adapted. The retune against the contract took one pass: the pack floor and all three token suites cleared on the first measurement, which is what a cool ground and a deep graphite ink buy you. The candidate's own dark ground does not travel, as with every look: a pack carries light values only.
+**Origin.** Authored through the `/style` session ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../../docs/adr/0231-the-style-session-an-owner-authors-a-look-inside-the-contract.md)) from a two-line brief: *"a drafting table under north light, cool paper and graphite; one cyanotype blue on what is pressable, a rust pencil for what went wrong."* The library's three existing looks are all warm and all carry a warm accent (salmon, lamp yellow, tan), so the search step found no near neighbour and the session drafted rather than adapted. The retune against the contract took one pass: the pack floor and all three token suites cleared on the first measurement, which is what a cool ground and a deep graphite ink buy you. The candidate's own dark ground does not travel, as with every look: a pack carries light values only.
 
 ## Overview
 

package/modules/ui-design/styles/chrome-world/DESIGN.md

@@ -30,7 +30,7 @@ rounded:
 
 # Style: The Chrome World (the canonical look)
 
-This is the look Cloud Bongos itself runs on and the **first entry** of the style library ([task 1003323](https://cloudbongos.com/builders#/task/1003323)). It is the canonical one in a precise sense: its `pack.json` is byte-for-byte the `theme.ui` block of [`config/branding.neutral.json`](../../../../config/branding.neutral.json), the neutral pack every instance resolves over, and its recipes are **not restated here**. The world's derived tiers, faces, materials, motion grammar, components, Do's and Don'ts and accessibility floors are the repo-root [`DESIGN.md`](../../../../DESIGN.md), recorded from the built landing ([ADR 0196](../../../../docs/adr/<redacted>.md)). Read that file; this one only holds the thirteen so the catalogue's lockstep test has something to hold.
+This is the look Cloud Bongos itself runs on and the **first entry** of the style library ([task 1003323](https://cloudbongos.com/builders#/task/1003323)). It is the canonical one in a precise sense: its `pack.json` is byte-for-byte the `theme.ui` block of [`config/branding.neutral.json`](../../../../config/branding.neutral.json), the neutral pack every instance resolves over, and its recipes are **not restated here**. The world's derived tiers, faces, materials, motion grammar, components, Do's and Don'ts and accessibility floors are the repo-root [`DESIGN.md`](../../../../DESIGN.md), recorded from the built landing ([ADR 0196](../../../../docs/adr/0196-chrome-world-token-contract-and-the-landing-sheets.md)). Read that file; this one only holds the thirteen so the catalogue's lockstep test has something to hold.
 
 ## What this entry is for
 

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.715",
+  "version": "1.19.724",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.715",
+      "version": "1.19.724",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.715",
+  "version": "1.19.724",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/audit-rank-roles.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// scripts/gds/audit-rank-roles.js — does the live builder roster hold ONLY the
+// four live ranks? (task 1002873)
+//
+// WHY. `migrations/023`'s CHECK on `builders.rank` still admits twelve legacy
+// values beyond the four live ranks. `governance_002_seed_and_backfill.sql`
+// backfills roles with an INNER JOIN from `builders.rank` to the four seeded
+// `governance_roles`, so a builder sitting on a legacy rank gets NO role row and
+// resolves to ZERO permissions: admitted by threshold under `requireRank`, locked
+// out of everything under the resolver. They are not told why, and nothing about
+// their account looks wrong.
+//
+// That divergence is deliberate — ADR 0151 chose fail-closed, and
+// `tests/governance_parity.mjs` asserts it is strictly a tightening. What was
+// missing is the VERIFICATION. governance_002's comment says "none exist today —
+// verified", a point-in-time manual check that nothing re-runs; the parity test
+// is DB-free by necessity (the unit gate has no Postgres) and says so in the
+// repo; and R114's live proof ran on a scratch DB holding only the four seeded
+// rank-roles, so the production roster was never queried.
+//
+// THIS IS THE RE-RUNNABLE HALF, and it is deliberately NOT fatal at boot. Idea
+// 1000622 records that trap: an assertion that throws on startup turns a data
+// problem on one instance into an outage. This is a standalone read-only script
+// for a nightly/deploy-time caller — it exits 1 so a caller can act, and nothing
+// in the server's boot path requires it.
+//
+// It reports rather than repairs, and that is a decision, not an omission:
+// rewriting somebody's rank is an authority change, and it belongs to an operator
+// who can see who the account is — not to a sweep.
+//
+//   node scripts/gds/audit-rank-roles.js [--json] [--file-idea]
+//
+// Exit codes:
+//   0  every builder holds a live rank
+//   1  at least one builder holds a rank the governance backfill cannot match
+//   2  could not read the roster (no session / network / route absent)
+//
+// `--file-idea` is what makes this a SURFACE rather than another thing nobody
+// runs — the same shape diagram-drift/check.js uses, spawning capture.js so idea
+// filing has one implementation. Without it a nightly deterministic run that exits
+// 1 reports into a log nobody reads, which is the exact criticism this task makes
+// of the status quo.
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const { cliClient, requireSession, cliExit } = require('./cli-lib');
+const { LIVE_RANK_LADDER } = require('../../src/bongos/db-kernel.js');
+
+// findRanksWithoutRoles — the PURE half. Given roster rows and the live ladder,
+// which builders hold a rank that `governance_002`'s INNER JOIN cannot match?
+//
+// Pure + exported because this is the only altitude the repo can test: the unit
+// gate has no Postgres, which is exactly why the gap this script closes went
+// unverified for so long. A DB-free test of the decision is not a consolation
+// prize here — it is the thing that can actually run in CI.
+//
+// A row with NO rank at all counts: NULL fails the INNER JOIN the same way a
+// legacy value does, and reads as "fine" in every UI that renders a blank.
+function findRanksWithoutRoles(rows, liveRanks = LIVE_RANK_LADDER) {
+  const live = new Set(liveRanks);
+  return (Array.isArray(rows) ? rows : [])
+    .filter((b) => b && !live.has(b.rank))
+    .map((b) => ({
+      id: b.id != null ? String(b.id) : null,
+      // The login is what an operator needs to act; it is already visible to any
+      // caller authorised to read the roster, so this adds no exposure.
+      github_login: b.github_login || null,
+      rank: b.rank === undefined ? null : b.rank,
+      status: b.status || null,
+    }));
+}
+
+// summarize — the rank histogram, so a CLEAN run still says what it looked at.
+// A green check that prints nothing is indistinguishable from one that read
+// nothing, which is the failure mode this whole task is about.
+function summarize(rows) {
+  const counts = new Map();
+  for (const b of Array.isArray(rows) ? rows : []) {
+    const key = b && b.rank ? b.rank : '(none)';
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]);
+}
+
+// Spawn capture.js rather than POSTing here, so idea filing keeps one
+// implementation (the diagram-drift/check.js precedent). Best-effort: a failure to
+// file must not turn a successful audit into a crash — the exit code and stdout
+// still carry the finding.
+function fileIdea(offenders) {
+  const body = [
+    `${offenders.length} builder(s) hold a rank with no matching governance_roles row.`,
+    '',
+    'They resolve to ZERO permissions — admitted by rank threshold under requireRank,',
+    'refused by the permission resolver, and given no reason (ADR 0151 fail-closed).',
+    '',
+    ...offenders.map((o) => `- builder ${o.id}${o.github_login ? ` (${o.github_login})` : ''} rank=${o.rank === null ? '(none)' : o.rank} status=${o.status || '?'}`),
+    '',
+    'Fix: move each to a live rank through the normal rank-change path, which rotates',
+    'the governance role in the same transaction. Not auto-repaired: changing a rank is',
+    'an authority decision, and a sweep is the wrong actor for it.',
+    '',
+    'Filed by scripts/gds/audit-rank-roles.js (task 1002873).',
+  ].join('\n');
+  const tmp = path.join(os.tmpdir(), `rank-roles-audit-${process.pid}.md`);
+  try {
+    fs.writeFileSync(tmp, body, 'utf8');
+    const r = spawnSync(
+      process.execPath,
+      [path.join(__dirname, 'capture.js'),
+        `[rank-roles] ${offenders.length} builder(s) on a rank with no governance role`,
+        '--kind', 'bug', '--body-file', tmp],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 }
+    );
+    if (r.status !== 0) console.error('audit-rank-roles: capture.js failed to file the idea — the exit code above still carries the finding.');
+  } catch (e) {
+    console.error(`audit-rank-roles: could not file the idea (${(e && e.message) || e}) — the exit code above still carries the finding.`);
+  } finally {
+    try { fs.rmSync(tmp, { force: true }); } catch (_) { /* best-effort */ }
+  }
+}
+
+async function main() {
+  const json = process.argv.includes('--json');
+  await requireSession();
+  const api = await cliClient();
+  const r = await api.request('GET', '/builders/roster');
+  if (!r.ok) {
+    console.error(`audit-rank-roles: could not read the roster (HTTP ${r.status}).`);
+    console.error('  Needs a session with builder.roster.read. Nothing was checked — do NOT read this as a pass.');
+    return cliExit(2);
+  }
+  // The roster query has no WHERE on `builders`, so this covers every row,
+  // INACTIVE ONES INCLUDED. That matters: a deactivated builder on a legacy rank
+  // is exactly the row a future CHECK-narrowing migration would fail to apply over.
+  const rows = (r.data && (r.data.builders || r.data.roster || r.data)) || [];
+  const offenders = findRanksWithoutRoles(rows);
+  const histogram = summarize(rows);
+
+  if (json) {
+    console.log(JSON.stringify({ checked: rows.length, live_ranks: LIVE_RANK_LADDER, histogram, offenders }, null, 2));
+    return cliExit(offenders.length ? 1 : 0);
+  }
+
+  console.log(`audit-rank-roles: ${rows.length} builder row(s) checked against the live ladder [${LIVE_RANK_LADDER.join(', ')}]`);
+  for (const [rank, n] of histogram) console.log(`  ${String(rank).padEnd(12)} ${n}`);
+  if (!offenders.length) {
+    console.log('\n✓ every builder holds a live rank — the governance backfill can match all of them.');
+    return cliExit(0);
+  }
+  console.log(`\n✗ ${offenders.length} builder(s) hold a rank with no matching governance role.`);
+  console.log('  They resolve to ZERO permissions: admitted by rank threshold, refused by the resolver,');
+  console.log('  and nothing tells them why (ADR 0151 fail-closed).');
+  for (const o of offenders) {
+    console.log(`  - builder ${o.id}${o.github_login ? ` (${o.github_login})` : ''} rank=${o.rank === null ? '(none)' : o.rank} status=${o.status || '?'}`);
+  }
+  console.log('\n  This is a BUILDER NEED, not an outage: move each to a live rank with the normal');
+  console.log('  rank-change path so the governance role rotates in the same transaction.');
+  console.log('  Deliberately not repaired here — changing a rank is an authority decision.');
+  if (process.argv.includes('--file-idea')) fileIdea(offenders);
+  return cliExit(1);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('audit-rank-roles:', (err && err.message) || err);
+    cliExit(2);
+  });
+}
+
+module.exports = { findRanksWithoutRoles, summarize };

package/scripts/gds/build-cli-package.js

@@ -64,6 +64,7 @@ const FILES = [
   'scripts/gds/recall.js',
   'scripts/gds/cost.js',
   'scripts/gds/release.js',
+  'scripts/gds/worktree-claim-guard.js', // release.js warns through it; pure, zero requires
 
   // Get onto a real environment without installing one: the cloud dev box.
   'scripts/gds/shell.js',

package/scripts/gds/claim.js

@@ -10,7 +10,7 @@
 const { execSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
-const { cliClient, requireSession, fmtTouches, printOnboardingNudge, rewardPolicy, costPlusOnlyNote, detectWorktreeName } = require('./cli-lib');
+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');
@@ -147,10 +147,44 @@ function enforceWorktreeClaim(taskId, { allowMainCheckout }) {
     allowMainCheckout,
     taskId,
   });
-  if (d.verdict === 'allow') return;
+  if (d.verdict === 'allow') return tree;
   for (const line of d.lines) console.error(line);
   if (d.verdict === 'refuse') 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/gds/claim.js ${taskId} --worktree <name>`,
+  ];
 }
 
 function captureHeadSha() {
@@ -247,7 +281,25 @@ function claimErrorInfo(r) {
 // 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 }.
-function formatClaimFailure(r, taskId) {
+//
+// 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;
+function clip(s, max = 160) {
+  if (s == null) return '';
+  // eslint-disable-next-line no-control-regex
+  const flat = String(s).replace(/[--Ÿ]+/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 lines = [];
   const { code, message, d } = claimErrorInfo(r);
 
@@ -271,6 +323,7 @@ function formatClaimFailure(r, taskId) {
       ? `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') {
@@ -294,6 +347,26 @@ function formatClaimFailure(r, taskId) {
     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') {
+    const owed = (d.rebaseTasks || d.rebase_tasks || []).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)}`);
+    }
+    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: 1 };
+  }
   if (code === 'ALREADY_CLAIMED') {
     lines.push(`Task #${taskId} was just claimed by another session. Try a different task.`);
     return { lines, exit: 1 };
@@ -356,6 +429,11 @@ function formatClaimFailure(r, taskId) {
   }
   // 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 };
 }
 
@@ -488,7 +566,7 @@ async function main() {
   // 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.
-  enforceWorktreeClaim(taskId, { allowMainCheckout: args.includes(ESCAPE_FLAG) });
+  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
@@ -527,7 +605,7 @@ async function main() {
     if (outcome === 'retry') {
       r = await postClaim();
     } else if (outcome === 'stop') {
-      process.exit(1); // everything already printed; no claim landed
+      return cliExit(1); // everything already printed; no claim landed
     }
   }
   if (r.status === 201) {
@@ -651,9 +729,16 @@ async function main() {
   }
   // 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);
+  const failure = formatClaimFailure(r, taskId, {
+    worktree,
+    isMainCheckout: tree ? tree.isMainCheckout : null,
+  });
   for (const line of failure.lines) console.error(line);
-  process.exit(failure.exit);
+  // 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
@@ -661,8 +746,8 @@ async function main() {
 if (require.main === module) {
   main().catch((err) => {
     console.error('fatal:', err);
-    process.exit(1);
+    cliExit(1);
   });
 }
 
-module.exports = { formatClaimFailure, claimErrorInfo, goalMembershipOfferPlan, materializeModeSkills };
+module.exports = { formatClaimFailure, claimErrorInfo, goalMembershipOfferPlan, materializeModeSkills, worktreeDetectionNote };

package/scripts/gds/fitness.js

@@ -520,17 +520,17 @@ const KERNEL_FILES = [
   // KERNEL (already in the module-scope-map kernel key) and imports only the
   // kernel (instance-config) + node built-ins, so it joins the roster cleanly.
   'src/bongos/repo-info.js',
-  // task 1002331 (ADR 0182 D6 / ADR 0247): the project's composed join/apply door —
-  // a deterministic classifier over three policy values, the same category as
+  // task 1002331 (ADR 0182 D6 / ADR 0247): the project's composed join/apply door — a
+  // deterministic classifier over three policy values, the same category as
   // route-rank-check.js and goal-scope-check.js above (a trust decision the doorway
   // hands to modules so no module re-derives it). The doorway re-exports it, so
   // leaving it off this roster reads as a kernel->non-kernel leak; it imports only
-  // branding.js, instance-config.js and logger.js — all on this roster — so
-  // joining costs nothing and buys the import-direction guarantee on the file that
-  // decides who may knock. (Task 1003579 removed its require of auth-admission.js
-  // and moved joinabilityMode the other way: the gate now reads the composed door,
-  // so the reader had to sit with the composer or the two files would have cycled.)
-  'src/bongos/project-door.js',
+  // branding.js, instance-config.js and logger.js — all on this roster — so joining
+  // costs nothing and buys the import-direction guarantee on the file that decides
+  // who may knock. (Task 1003579 moved joinabilityMode the other way: the gate reads
+  // the composed door, so reader and composer had to sit together or the two would
+  // cycle.) The ARTIST GATE joins for the same reason — task 1003575, ADR 0241.
+  'src/bongos/project-door.js', 'src/bongos/artist-gate.js',
 ];
 
 // Kernel files exempt from the no-module-keys scan (Check 10) because naming a