@bongos/core 1.19.714 → 1.19.724

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

package/scripts/gds/go-live.js

@@ -44,7 +44,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
-const { arg, hasFlag } = require('./cli-lib');
+const { arg, hasFlag, apiCall } = require('./cli-lib');
 const divergence = require('./deploy-divergence.js');
 
 const ROOT = path.resolve(__dirname, '..', '..');
@@ -370,6 +370,57 @@ function refreshMain({ run = spawnSync } = {}) {
   return { ok: true };
 }
 
+// Ask the LIVE instance about its own artist gate (ADR 0241, task 1003575).
+//
+// The instance answers because it is the only party that can: the policy arrives
+// in its web.env and its board holds the reviews. This script only decides what to
+// do with the answer, and the refusal sentence is composed there rather than here
+// so one wording serves every caller.
+//
+// NEVER THROWS. Every failure — no session, a 401, an instance too old to carry
+// the route, a network error — resolves to { unread: <why> }, which renders as a
+// note. See artistGateEntries for why an unread gate is not a halt.
+// The FULL path, not a bare `/artist-gate`. cli-lib's apiCall composes
+// `${base}${urlPath}` verbatim and `base` is the instance ORIGIN — every other
+// caller in this repo spells `/api/bongos/…` by hand for the same reason. Getting
+// this wrong is silent in the worst way: the request lands on the origin's
+// catch-all, the gate reports itself unread on every instance including the ones
+// that fully support it, and the deploy check never fires. Exported so a test can
+// pin it against the route's REAL mount point in the generated OpenAPI spec.
+const ARTIST_GATE_PATH = '/api/bongos/artist-gate';
+// The levels a real answer can carry — mirrored from src/bongos/artist-gate.js
+// rather than imported, because this script also runs from an INSTALLED core on a
+// box where that path is inside the package, and a require of it here would make
+// the deploy tool depend on the server's own tree. Pinned by the same test that
+// pins the path.
+const ARTIST_GATE_LEVELS = ['off', 'advisory', 'strict'];
+
+async function readArtistGate(call = apiCall) {
+  try {
+    const res = await call('GET', ARTIST_GATE_PATH, null, { allowUnauthenticated: true, allowBoxScope: true });
+    if (res.status === 404) return { unread: `this instance does not serve ${ARTIST_GATE_PATH} — it predates ADR 0241` };
+    // A 5xx is a gate that EXISTS and BROKE, which is not the same class of
+    // unknown as "no session" or "too old to have the route". The gate is
+    // fail-closed by design, so the one case where we know it is there and
+    // cannot get an answer from it HALTS rather than degrading to a note —
+    // otherwise a broken read is a quieter way past the gate than the owner's
+    // own override, which is the asymmetry worth refusing.
+    if (res.status >= 500) return { broken: `GET ${ARTIST_GATE_PATH} returned ${res.status}` };
+    if (!res.ok) return { unread: `GET ${ARTIST_GATE_PATH} returned ${res.status}` };
+    const d = res.data || {};
+    // A 200 that is not this route's answer — an SPA index.html served by a
+    // catch-all, a proxy's own page — must read as UNREAD, never as a gate that
+    // holds nothing. "I got a 200 from something" is the one failure that would
+    // wave a deploy through in silence, which is worse than any halt.
+    if (!ARTIST_GATE_LEVELS.includes(d.mode)) {
+      return { unread: `GET ${ARTIST_GATE_PATH} answered ${res.status} but not with a gate — got mode ${JSON.stringify(d.mode)}` };
+    }
+    return { mode: d.mode, since: d.since || null, holds: !!d.holds, reviews: d.reviews || [], halt: d.halt || null };
+  } catch (e) {
+    return { unread: (e && e.message) || 'request failed' };
+  }
+}
+
 // Parse a `key=value` marker into its parts. Kept pure + exported: the marker is
 // the answer to the trap that the release current when your fix merges usually
 // does NOT contain your fix (ADR 0161 carriers bump on their own cadence).
@@ -394,12 +445,68 @@ const HALTS = {
   MARKER_UNCHECKED: 'could not inspect the target version — the content proof did not run',
   BOX_TREE_DIRTY: 'the instance repo on the box has uncommitted changes',
   LIVE_AHEAD: 'live is AHEAD of the target',
+  ARTIST_REVIEW_UNRESOLVED: 'an unresolved artist review holds this deploy (ADR 0241)',
+  ARTIST_GATE_UNREADABLE: 'the artist gate is there and answering with an error — this deploy cannot tell whether a review holds it',
 };
 
-function planGoLive({ div, target, targetVersion, dirtyCheckout, allowUnreleased = false }) {
+// The artist gate (ADR 0241, task 1003575). This is the ONE place in the deploy
+// path that the artist's authority touches, and the boundary is the whole point:
+// `strict` may delay a PIN MOVE and nothing else. Nothing in the ship, grade,
+// merge or land path consults this — a builder's work is credited and on `main`
+// long before a go-live runs, which is what lets this gate coexist with ADR 0162
+// instead of recreating the strand it retired.
+//
+// It reads a STATE, not a verdict: the instance reports which artist review tasks
+// are still open, never whether an artist approved anything. See
+// src/bongos/artist-gate.js, which composes the refusal sentence this renders.
+// The halt and/or note one gate read contributes. Shared by planGoLive and by the
+// gitless (on-box, no checkout) path, so a lane that skips the git-derived checks
+// does not also silently skip the gate — the deploy is the same deploy either way.
+// PURE.
+function artistGateEntries(gate) {
+  const halts = [];
+  const notes = [];
+  if (gate && gate.halt) {
+    halts.push({ code: 'ARTIST_REVIEW_UNRESOLVED', message: gate.halt.message, detail: gate.halt.detail });
+  }
+  // A gate that is THERE and BROKEN halts. This is the fail-closed half: we know
+  // the instance has the route, so "it 500s" is a gate we cannot get an answer
+  // from, not a gate that does not apply. Its remedy is the instance's own logs,
+  // and it is named as such rather than as an artist problem.
+  if (gate && gate.broken) {
+    halts.push({
+      code: 'ARTIST_GATE_UNREADABLE',
+      message: HALTS.ARTIST_GATE_UNREADABLE,
+      detail: `${gate.broken}. The route exists, so this is a fault on the instance, not a missing feature — read its logs for the GET /artist-gate failure. Deploying past it would mean moving the pin without knowing whether a review holds it.`,
+    });
+  }
+  // NOT KNOWING is a different thing again, and it must not render as "nothing
+  // holds". It is a note rather than a halt on purpose: a go-live is already
+  // deliberate and reversible, and halting every deploy because there is no CLI
+  // session — or because the instance predates the route entirely — would brick
+  // the pin with no task id to release against, which is the blocked-state-that-
+  // does-not-explain-itself failure ADR 0241 §4 names.
+  if (gate && gate.unread) {
+    notes.push({
+      code: 'ARTIST_GATE_UNREAD',
+      message: `could not read this instance's artist gate (${gate.unread}) — if the project runs artist_gate 'strict', an unresolved artist review may be holding this deploy and this plan cannot see it`,
+    });
+  }
+  return { halts, notes };
+}
+
+function planGoLive({ div, target, targetVersion, dirtyCheckout, allowUnreleased = false, artistGate = null }) {
   const halts = [];
   const notes = [];
 
+  // Evaluated FIRST, before the git-derived checks, because it is the halt whose
+  // remedy takes longest: a review someone has to do is not a thing you fix in the
+  // next ten seconds, and finding it out after the other five checks passed is
+  // strictly worse than finding it out now.
+  const gate = artistGateEntries(artistGate);
+  halts.push(...gate.halts);
+  notes.push(...gate.notes);
+
   if (dirtyCheckout) halts.push({ code: 'DIRTY_CHECKOUT', message: HALTS.DIRTY_CHECKOUT, detail: dirtyCheckout });
 
   if (!div || div.undetermined) {
@@ -446,6 +553,13 @@ function renderPlan(p, { targetName, configPath } = {}) {
   L.push(`  target        ${p.targetVersion || '(unresolved)'}`);
   if (p.marker) L.push(`  verify        ${p.marker.path} contains "${p.marker.needle}"`);
   if (p.registry) L.push(`  registry      ${p.registry.ok ? `carries ${p.targetVersion}` : 'MISSING'}`);
+  // The gate's state is worth a line even when it holds nothing: "artist gate
+  // advisory" is the answer to "why did nothing stop?", and a reader who cannot
+  // see the level has to go and find it.
+  if (p.artistGate && p.artistGate.mode) {
+    const open = (p.artistGate.reviews || []).length;
+    L.push(`  artist gate   ${p.artistGate.mode}${open ? ` · ${open} unresolved review${open === 1 ? '' : 's'}` : ' · nothing open'}`);
+  }
   L.push('');
   for (const n of p.notes || []) L.push(`  ⚠ ${n.code} — ${n.message}`);
   if (!p.halts.length) {
@@ -790,9 +904,28 @@ async function runGoLive({ target, targetName, configPath, json, apply, allowUnr
   const dirtyRes = gitless ? { status: 1 } : spawnSync('git', ['status', '--porcelain'], { cwd: ROOT, encoding: 'utf8' });
   const dirtyCheckout = dirtyRes.status === 0 && (dirtyRes.stdout || '').trim() ? (dirtyRes.stdout || '').trim().split('\n').slice(0, 5).join(', ') : null;
 
+  // Always read, and deliberately NOT skippable by a flag. ADR 0241 §3 names one
+  // escape hatch — the project OWNER's override-request, rationale required and
+  // audit-logged — and a `--skip` here would be a second authority path that any
+  // builder with the shell could take silently, which is exactly the shape that
+  // ADR rejects. An unread gate already degrades to a note; that is the only
+  // by-pass, and it says so on screen.
+  const artistGate = await readArtistGate();
+
+  const gitlessGate = artistGateEntries(artistGate);
   const plan = gitless
-    ? { halts: [], notes: [{ code: 'NO_CORE_CHECKOUT', message: `no core git checkout here — target ${targetVersion} was given explicitly, so the git-derived checks (unreleased-on-main, dirty tree) are skipped` }], from: null, targetVersion, target }
-    : planGoLive({ div, target, targetVersion, dirtyCheckout, allowUnreleased });
+    ? {
+      halts: gitlessGate.halts,
+      notes: [
+        { code: 'NO_CORE_CHECKOUT', message: `no core git checkout here — target ${targetVersion} was given explicitly, so the git-derived checks (unreleased-on-main, dirty tree) are skipped` },
+        ...gitlessGate.notes,
+      ],
+      from: null,
+      targetVersion,
+      target,
+    }
+    : planGoLive({ div, target, targetVersion, dirtyCheckout, allowUnreleased, artistGate });
+  plan.artistGate = artistGate;
   plan.marker = marker;
   if (!fetched.ok && !fetched.skipped) {
     // Say so rather than silently planning off a ref of unknown age.
@@ -860,7 +993,8 @@ if (require.main === module) {
 }
 
 module.exports = {
-  loadConfig, selectTarget, validateTarget, planGoLive, parseMarker, parseMarkerHits,
+  loadConfig, selectTarget, validateTarget, planGoLive, artistGateEntries, readArtistGate, ARTIST_GATE_PATH, ARTIST_GATE_LEVELS,
+  parseMarker, parseMarkerHits,
   renderPlan, renderReport, failureExcerpt, asOwner, isSafeToken, NPM_AUTH_PREAMBLE, refreshMain, isLocalTarget, gitRefExists, SUDO_PREAMBLE,
   applyGoLive, upgradeCommand, pinStep, pinModeOf,
   CONFIG_TEMPLATE, HALTS, SEMVER_RE, PIN_MODES, DEFAULT_PIN_MODE,

package/scripts/gds/land-watch.js

@@ -21,7 +21,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { SESSION_PATH, cliClient } = require('./cli-lib');
+const { SESSION_PATH, cliClient, cliExit } = require('./cli-lib');
 const shipCard = require('../../modules/lifecycle/ship-card');
 
 // Breadcrumbs live beside the session token (per-machine, per-instance config dir —
@@ -174,14 +174,22 @@ module.exports = {
 if (require.main === module) {
   const hookMode = process.argv.includes('--hook');
   (async () => {
+    // task 1002592: every exit below routes through cliExit (task 1002734's rule).
+    // This script exits 0 on ALL paths on purpose — it is hook-invoked and must
+    // never report failure — but on Windows the post-request teardown aborted with
+    // "Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)" and handed the hook
+    // 127, which conventionally reads as "command not found". Measured 3/3 before
+    // this change: the one script written never to fail always reported failure.
+    // Draining also lets the --hook stdout write flush, which a hard exit can cut
+    // mid-JSON — the card hook parses that stdout.
     // Cheap idle fast-path: no breadcrumbs → do nothing (no network).
-    if (readBreadcrumbs().length === 0) { if (!hookMode) console.error('land-watch: no pending lands.'); process.exit(0); }
+    if (readBreadcrumbs().length === 0) { if (!hookMode) console.error('land-watch: no pending lands.'); return cliExit(0); }
     const envelope = await watch();
     if (hookMode) {
       if (envelope) process.stdout.write(JSON.stringify(envelope));
-      process.exit(0);
+      return cliExit(0);
     }
     console.error(envelope ? `land-watch: a task landed — shipped card ready (${envelope.title}).` : 'land-watch: nothing landed this pass.');
-    process.exit(0);
-  })().catch(() => process.exit(0)); // never throw from a hook-invoked script
+    return cliExit(0);
+  })().catch(() => cliExit(0)); // never throw from a hook-invoked script
 }

package/scripts/gds/mirror-redact.js

@@ -286,9 +286,20 @@ function findLeaks(text, sensitiveLiterals) {
 // findSecretLeak — true if the generic secret scrubber WOULD change this text, i.e. a
 // secret shape is present. The export gate runs this in addition to findLeaks so a
 // stray credential in an old commit fails the publish closed rather than leaking.
-function findSecretLeak(text, extraSecrets = []) {
+//
+// `opts` MUST be whatever the scrub being audited was given (task 1003873). Unlike
+// findLeaks — which is deliberately STRICTER than redaction, and independent of it by
+// design — this one is DIFFERENTIAL: it re-scrubs and asks "did anything change?". An
+// option the audit does not share therefore makes it disagree with its own subject by
+// construction, and reads that disagreement as a leak. That is not a safety margin, it
+// is a false positive: task 1002460's knownDocNames allowlist spares a long ADR
+// filename from the entropy sweep, an audit without the allowlist re-redacts it, the
+// text differs, and EVERY published doc reports a phantom secret shape. Because the
+// gate is fail-closed the packager then produces nothing — it took the publish lane
+// down for seven consecutive core releases before anyone read past the symptom.
+function findSecretLeak(text, extraSecrets = [], opts = undefined) {
   if (typeof text !== 'string' || text.length === 0) return false;
-  return scrubSecrets(text, extraSecrets) !== text;
+  return scrubSecrets(text, extraSecrets, opts) !== text;
 }
 
 module.exports = {

package/scripts/gds/package-core.js

@@ -193,7 +193,7 @@ function functionalSecretLeaks(view, envSecrets) {
 //   * FUNCTIONAL: VERBATIM buffer. `leaks` = exact live-credential matches only (FATAL).
 //     `advisories` = brand-identity substrings + public IPs that ship as-is (non-fatal, for
 //     human awareness) — REUSES findLeaks so the detector is defined once.
-function processCoreFile({ pathRel, raw, rules, sensitiveLiterals, envSecrets }) {
+function processCoreFile({ pathRel, raw, rules, sensitiveLiterals, envSecrets, knownDocNames }) {
   // An auto-loaded agent doc (CLAUDE.md/AGENTS.md) → ship a brand-free stub, never the
   // core's own project memory (task 2121). The stub is brand-free by construction, so it
   // needs no redaction and can never leak — it short-circuits ahead of the doc path.
@@ -201,7 +201,7 @@ function processCoreFile({ pathRel, raw, rules, sensitiveLiterals, envSecrets })
     return { buf: Buffer.from(CORE_AGENT_DOC_STUB, 'utf8'), leaks: [], advisories: [], kind: 'stub' };
   }
   if (isDocPath(pathRel)) {
-    const r = redactBlob({ buf: raw, rules, sensitiveLiterals, envSecrets });
+    const r = redactBlob({ buf: raw, rules, sensitiveLiterals, envSecrets, knownDocNames });
     const leaks = r.leaks.map((l) => ({ label: `doc:${l.label}`, sample: l.sample }));
     if (r.secret) leaks.push({ label: 'doc:secret-shape' });
     return { buf: r.buf, leaks, advisories: [], kind: 'doc' };
@@ -817,6 +817,14 @@ function main() {
   // 4. Process every file IN MEMORY (processCoreFile: docs redacted, functional verbatim)
   //    + the fail-closed no-leak gate. Nothing touches dist/ until the ENTIRE set is proven
   //    clean (atomic abort). Brand/topology in functional files are non-fatal ADVISORIES.
+  // task 1002460 — the doc-link allowlist. The entropy sweep cannot tell a long
+  // ADR filename from a secret by shape, so it collapsed every one of them to
+  // <redacted>.md on the way out. This is the set of names actually being
+  // published, so a name in it is a FILE and not a guess; anything else, secrets
+  // included, is redacted exactly as before.
+  const knownDocNames = new Set(
+    publishable.map((e) => e.path.split('/').pop()).filter((n) => /\.(md|sql)$/i.test(n)),
+  );
   const staged = []; // { name, mode, buf }  (name includes TAR_ROOT)
   const filesMeta = []; // { path, mode, sha256 }  (source files only — the pin domain)
   const leaks = [];
@@ -829,7 +837,7 @@ function main() {
     try { raw = gitBuf(['cat-file', 'blob', e.sha]); }
     catch (err) { leaks.push({ path: e.path, label: `read-failed:${err.message}` }); continue; }
     const { buf, leaks: fileLeaks, advisories: fileAdvisories, kind } =
-      processCoreFile({ pathRel: e.path, raw, rules, sensitiveLiterals, envSecrets });
+      processCoreFile({ pathRel: e.path, raw, rules, sensitiveLiterals, envSecrets, knownDocNames });
     for (const l of fileLeaks) leaks.push({ path: e.path, label: l.label, sample: l.sample });
     for (const a of fileAdvisories) advisories.push({ path: e.path, label: a.label, sample: a.sample });
     if (kind === 'doc') docCount++; else if (kind === 'stub') stubCount++; else funcCount++;

package/scripts/gds/release.js

@@ -6,7 +6,46 @@
 //
 // The task returns to 'ready' status and is claimable by another session.
 
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
 const { cliClient, requireSession, arg } = require('./cli-lib');
+const { parkedMainCheckoutWarning } = require('./worktree-claim-guard');
+
+// gitAt(args, cwd) — run git with an ARGV ARRAY and no shell.
+//
+// Deliberately not `execSync('git -C "<path>" …')`. A resolved filesystem path is
+// not trusted input: a directory name containing a quote, backtick or `$()` would
+// break out of the quoting and execute under cmd.exe/sh. execFileSync never
+// spawns a shell, so the path cannot be interpreted as anything but a path — a
+// stronger guarantee than the `{ cwd }` form, which still shells the command
+// string. (Found by the grader on this task, and it was right: the first cut
+// interpolated the path into a shell string.)
+//
+// Kept local rather than imported from ship-git.js on purpose: release.js ships
+// in the PUBLIC client-only @cloudbongos/cli package, and nothing in the ship-*
+// family is in that manifest. tests/cli_package.mjs installs the tarball and RUNS
+// every verb, so an import from outside it is a crash at require time, not a
+// lint-level nit — that is exactly how this file broke once already.
+function gitAt(args, cwd) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+// The MAIN checkout, not this worktree — from a linked worktree they differ, and
+// the parked-tree warning is only ever about the main one.
+//
+// Resolved with git rather than by importing ship-state's REPO_ROOT for the same
+// packaging reason: ship-state pulls in modules/lifecycle/ship-preflight, which
+// would drag server-side lifecycle code into a client-only package.
+// `--git-common-dir` is the shared .git of the whole worktree family, so its
+// parent is the main checkout from anywhere.
+function mainCheckoutRoot() {
+  const common = gitAt(['rev-parse', '--path-format=absolute', '--git-common-dir'], process.cwd());
+  return common ? path.dirname(common) : null;
+}
 
 
 (async () => {
@@ -65,6 +104,22 @@ const { cliClient, requireSession, arg } = require('./cli-lib');
   }
   console.log(`Released task #${r.data.taskId}: ${r.data.taskTitle}`);
   console.log(`Status returned to 'ready'. No credits awarded.`);
+  // task 1002871: a claim worked under the `--here` hatch leaves the MAIN
+  // checkout on the feature branch, and giving the claim up is exactly when that
+  // tree stops being watched. Warn, never restore — the branch may hold real
+  // uncommitted work, and release.js cannot tell that from debris. Strictly
+  // best-effort: a diagnostic must never fail a release that already succeeded.
+  try {
+    const root = mainCheckoutRoot();
+    const branch = root && gitAt(['rev-parse', '--abbrev-ref', 'HEAD'], root);
+    // gitAt already trims, so a non-empty string IS dirt.
+    const dirty = root && gitAt(['status', '--porcelain'], root);
+    const lines = parkedMainCheckoutWarning({ branch, dirty: !!dirty });
+    if (lines.length) {
+      console.log('');
+      for (const line of lines) console.log(line);
+    }
+  } catch (_) { /* never let a warning break a successful release */ }
 })().catch((err) => {
   console.error('fatal:', err);
   process.exit(1);

package/scripts/gds/ship-land.js

@@ -11,7 +11,7 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { cliClient } = require('./cli-lib');
+const { cliClient, isBoxScope } = require('./cli-lib');
 const { gitArgvOk, gitOk, sanitizeGitHubRefs, shellOk } = require('./ship-git.js');
 const { buildPrCreateArgv, buildPrMergeArgv, deployRunSucceeded, deployedCommitStatus, fetchDeployedVersion, ghArgvOk, ghJson, pushVia, resolveInstanceBase } = require('./ship-deploy-target.js');
 const { normalizeApiError } = require('./ship-io.js');
@@ -184,7 +184,15 @@ async function ciLandServer(taskId, branch, valueSummary) {
       id: taskId,
       body: { branch, head_sha: headSha, value_summary: valueSummary, bundle_b64: bundleB64 },
     });
-    if (r.status === 403 && normalizeApiError(r.data).code === 'box_scope') {
+    // task 1002593: ONE definition of "is this a box-scope refusal". This site used
+    // to hand-roll the comparison, which is how it silently died when routes moved
+    // to the object error envelope — `r.data.error` stopped being the bare string
+    // and the branch could never fire. Normalizing here fixed the symptom but left
+    // a SECOND predicate for the same question, and two copies of a predicate are
+    // how one of them gets a fix the other never sees (migration 177 dropping 176's
+    // blocker clause is the same shape). cli-lib's isBoxScope is the one every
+    // other caller already uses; this is the last site that did not.
+    if (isBoxScope(r)) {
       console.log('  ci-land: this session is BOX-SCOPED — run /builder-reauth (browser, no terminal) to mint a real session, then re-ship. Task stays at confirmed.');
       return landBailed('this CLI session is box-scoped', '/builder-reauth');
     }