@bongos/core 1.19.715 → 1.19.724

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');
     }

package/scripts/gds/ship-regen.js

@@ -248,17 +248,49 @@ function regenerateFileMap() {
 // ship-vs-merge-mode and merge-mode-vs-merge-mode races that the in-ship.js
 // lock could not cover. See docs/recipes/multi-builder-merge.md.
 
+// describeMainWorktreeBusy — the PURE verdict. Given the three facts about
+// REPO_ROOT, is it safe to mutate, and if not, why? Returns a human reason string
+// or null.
+//
+// task 1002871: it used to answer only 'a merge is already in progress' or 'the
+// working tree is dirty…', and it runs BEFORE the named-branch diagnostic in
+// ship-merge.js. So the shape of the original incident — a shared main checkout
+// that is BOTH parked on a feature branch AND dirty (2026-07-28: parked on
+// `task-1002503-backfill-recovery` with 2 unpushed commits and 4 modified
+// generated files, blocking the auto-merge leg for 9 confirmed tasks) —
+// short-circuited here and the builder never learned WHICH branch was squatting.
+// The named-branch message was only reachable when the tree was clean, which is
+// the one case where nobody needs to be told twice.
+//
+// Pure + exported so the wording is unit-tested rather than eyeballed: this is the
+// ship hot path, and the whole value of the change is the exact string.
+function describeMainWorktreeBusy({ mergeInProgress, dirty, branch, defaultBranch = 'main' } = {}) {
+  // A branch name is only worth naming when it is NOT the expected one. Saying
+  // "on main" in every bail would be noise that trains the reader to skip the line.
+  const occupant = branch && branch !== defaultBranch && branch !== 'HEAD'
+    ? ` (on \`${branch}\`, not \`${defaultBranch}\`)`
+    : '';
+  if (mergeInProgress) return `a merge is already in progress${occupant}`;
+  if (dirty) return `the working tree is dirty or has unmerged files${occupant}`;
+  return null;
+}
+
 // REPO_ROOT must be on main, not mid-merge, and clean before we mutate it.
-// Returns a human reason string if busy, or null if safe to proceed.
+// Returns a human reason string if busy, or null if safe to proceed. The I/O
+// shell over describeMainWorktreeBusy — gather the facts, let the pure half decide.
 function mainWorktreeBusy() {
-  if (gitOk('git rev-parse -q --verify MERGE_HEAD', { cwd: REPO_ROOT })) {
-    return 'a merge is already in progress';
-  }
+  const mergeInProgress = !!gitOk('git rev-parse -q --verify MERGE_HEAD', { cwd: REPO_ROOT });
+  // Short-circuit the moment the verdict is decided. `describeMainWorktreeBusy`
+  // prefers merge-in-progress over dirty, so once that is true the dirty probe's
+  // answer is discarded — spawning it anyway would be two subprocesses bought for
+  // nothing. The branch IS still needed on this arm: the reason names it either way.
+  const branch = gitOk('git rev-parse --abbrev-ref HEAD', { cwd: REPO_ROOT }) || null;
+  if (mergeInProgress) return describeMainWorktreeBusy({ mergeInProgress: true, branch });
   const dirty = gitOk('git status --porcelain', { cwd: REPO_ROOT });
-  if (dirty && dirty.trim().length > 0) {
-    return 'the working tree is dirty or has unmerged files';
-  }
-  return null;
+  // Best-effort throughout: a probe failure yields null, which the pure half reads
+  // as "no occupant worth naming". A diagnostic must never be the thing that
+  // breaks the bail it is decorating.
+  return describeMainWorktreeBusy({ mergeInProgress: false, dirty: !!(dirty && dirty.length > 0), branch });
 }
 
 // task 391 (idea #37): the verdict for a ship whose branch has no commits ahead
@@ -276,6 +308,7 @@ module.exports = {
   VENDORED_CLIENT_REL,
   apiClientPathspec,
   currentBranch,
+  describeMainWorktreeBusy,
   mainWorktreeBusy,
   regenerateApiClient,
   regenerateApiDocs,

package/scripts/gds/start.js

@@ -272,8 +272,9 @@ function rebaseWarningModel(needsRebaseTasks) {
 function rebaseWarningMarkdown(needsRebaseTasks) {
   const w = rebaseWarningModel(needsRebaseTasks);
   if (!w) return null;
-  return `⚠️ ${surface.strong('Rebase owed — your queue is GATED.')} ${w.count} ${w.noun} can't land and block new claims`
-    + ` until you rebase + re-ship (or ${surface.code(surface.action('release'))}) ${w.pronoun}: ${w.refs}.`;
+  return `⚠️ ${surface.strong('Land owed — your queue is GATED.')} ${w.count} ${w.noun} can't land and block new claims`
+    + ` until you ${surface.code('git merge origin/main')} + re-ship (or ${surface.code(surface.action('release'))}) ${w.pronoun}: ${w.refs}.`
+    + ' Merge, never rebase — a published branch that is rewritten cannot be pushed again (task 1002788).';
 }
 
 // The widget warning block (Tabler alert icon, danger-tinted), or '' when none.
@@ -281,7 +282,7 @@ function rebaseWarningWidget(needsRebaseTasks) {
   const w = rebaseWarningModel(needsRebaseTasks);
   if (!w) return '';
   return `<div class="bs-warn"><i class="ti ti-alert-triangle" aria-hidden="true"></i>`
-    + `<span><strong>Rebase owed — your queue is GATED.</strong> ${w.count} ${w.noun} can't land and block new claims until you rebase + re-ship (or /builder-release) ${w.pronoun}: ${hesc(w.refs)}.</span></div>`;
+    + `<span><strong>Land owed — your queue is GATED.</strong> ${w.count} ${w.noun} can't land and block new claims until you <code>git merge origin/main</code> + re-ship (or /builder-release) ${w.pronoun}: ${hesc(w.refs)}. Merge, never rebase — a published branch that is rewritten cannot be pushed again (task 1002788).</span></div>`;
 }
 
 // Run console.log-based helpers (printCostWarning/printOnboardingNudge) without
@@ -832,7 +833,9 @@ async function main() {
 
   // ADR 0120 part 5: the owed-rebase gate warning — rendered directly under the
   // identity line and before the claimable table, since it BLOCKS new claims
-  // until the builder lands (rebase + re-ship) or releases the flagged tasks.
+  // until the builder lands (`git merge origin/main` + re-ship — task 1002788:
+  // MERGE, because the branch is already published and the server's publish is
+  // append-only, so a rebase makes it permanently un-pushable) or releases them.
   const rebaseLine = rebaseWarningMarkdown(needsRebaseTasks);
   if (rebaseLine) {
     console.log('');

package/scripts/gds/worktree-claim-guard.js

@@ -101,4 +101,30 @@ function decideWorktreeClaim({
   };
 }
 
-module.exports = { decideWorktreeClaim, ESCAPE_FLAG };
+// task 1002871 — the OTHER end of the same failure. decideWorktreeClaim stops a
+// builder parking the main checkout at CLAIM time; this speaks at RELEASE time,
+// when a claim worked under the `--here` hatch is given up and the main checkout
+// is left holding the feature branch. Nobody is watching that tree, and the next
+// ship to reach for it — possibly another builder's — is who pays: the 2026-07-28
+// incident was one parked checkout blocking the auto-merge leg for 9 tasks.
+//
+// IT WARNS AND NEVER RESTORES, deliberately. Switching the tree back to main
+// would be a destructive guess: the parked branch may hold real uncommitted work,
+// and release.js has no way to tell that from debris. Naming it is enough — the
+// person reading has the context to decide.
+//
+// Pure; returns an array of lines (empty when there is nothing to say).
+function parkedMainCheckoutWarning({ branch, defaultBranch = 'main', dirty = false } = {}) {
+  if (!branch || branch === defaultBranch || branch === 'HEAD') return [];
+  return [
+    `⚠ The main checkout is still on \`${branch}\`, not \`${defaultBranch}\`.`,
+    dirty
+      ? '  It also has uncommitted changes, so nothing here will touch it.'
+      : '  Nothing here will touch it — the branch may hold work you still want.',
+    `  While it stays parked, the local auto-merge at ship time has nowhere to merge INTO,`,
+    '  so the next ship on this machine strands at `confirmed` — including someone else\'s.',
+    `  When you are done with it:  git -C <main checkout> checkout ${defaultBranch}`,
+  ];
+}
+
+module.exports = { decideWorktreeClaim, parkedMainCheckoutWarning, ESCAPE_FLAG };

package/scripts/public-mirror-export.js

@@ -95,17 +95,23 @@ function isBinary(buf) {
 // over their latin1 view (so an embedded literal still trips the gate). The gate uses
 // `sensitiveLiterals` (raw substrings), NOT `rules` — stricter than redaction on
 // purpose (see mirror-redact.js). Returns { buf:Buffer, leaks:[{label,sample}], secret:boolean }.
-function redactBlob({ buf, rules, sensitiveLiterals, envSecrets }) {
+function redactBlob({ buf, rules, sensitiveLiterals, envSecrets, knownDocNames }) {
   if (isBinary(buf)) {
     const view = buf.toString('latin1');
     return { buf, leaks: findLeaks(view, sensitiveLiterals), secret: findSecretLeak(view, envSecrets) };
   }
   const redacted = redactText(buf.toString('utf8'), rules);
-  const scrubbed = scrubSecrets(redacted, envSecrets);
+  // task 1002460: the set of filenames THIS publish is shipping. The entropy
+  // sweep mistakes a long doc filename for a secret, and only the caller knows
+  // which names are real files. With no set there is no exemption at all.
+  const scrubbed = scrubSecrets(redacted, envSecrets, { knownDocNames });
   return {
     buf: Buffer.from(scrubbed, 'utf8'),
     leaks: findLeaks(scrubbed, sensitiveLiterals),
-    secret: findSecretLeak(scrubbed, envSecrets),
+    // Same allowlist as the scrub directly above, and it has to be: findSecretLeak is a
+    // differential audit of THAT scrub's output, so an option only one of the two holds
+    // is read as a leak in every doc (task 1003873). Keep these two calls in step.
+    secret: findSecretLeak(scrubbed, envSecrets, { knownDocNames }),
   };
 }
 
@@ -206,6 +212,13 @@ function main() {
 
   // 4. Redact every file IN MEMORY and run the fail-closed no-leak gate. Nothing touches
   //    the mirror filesystem until the ENTIRE set is proven clean (atomic abort).
+  // task 1002460 — the doc-link allowlist, computed for THIS export. Without it the
+  // entropy sweep cannot tell a long ADR filename from a secret and collapses every
+  // one to <redacted>.md. This is the mirror`s own file set, so a name in it is a
+  // FILE and not a guess; anything else, secrets included, redacts exactly as before.
+  const knownDocNames = new Set(
+    publishable.map((e) => e.path.split('/').pop()).filter((n) => /\.(md|sql)$/i.test(n)),
+  );
   const staged = []; // { path, buf, mode }
   const leaks = [];  // { path, label, sample? }
   for (const e of publishable) {
@@ -216,7 +229,7 @@ function main() {
       leaks.push({ path: e.path, label: `read-failed:${err.message}` });
       continue;
     }
-    const { buf, leaks: fileLeaks, secret } = redactBlob({ buf: raw, rules, sensitiveLiterals, envSecrets });
+    const { buf, leaks: fileLeaks, secret } = redactBlob({ buf: raw, rules, sensitiveLiterals, envSecrets, knownDocNames });
     for (const l of fileLeaks) leaks.push({ path: e.path, label: l.label, sample: l.sample });
     if (secret) leaks.push({ path: e.path, label: 'secret-shape' }); // never print the secret sample
     staged.push({ path: e.path, buf, mode: e.mode });

package/src/bongos/api-errors.js

@@ -167,6 +167,15 @@ const OVERRIDES = Object.freeze({
   // --- validation ---
   validation_failed: 'validation_failed',
   schema_error: 'validation_failed',
+
+  // task 1002845: a Postgres CHECK violation surfaced as a 400 that names the
+  // constraint. It needs an explicit entry because the heuristics below would
+  // classify it `internal` (no matching prefix/suffix rule), which is the safe
+  // default for an unknown code but wrong here — the caller CAN fix this by
+  // changing the value they sent, so it must be bad_request and non-retriable.
+  // An unregistered code would still have answered 400 (the call site passes an
+  // explicit status), leaving the category quietly disagreeing with the status.
+  constraint_violation: 'bad_request',
 });
 
 // Suffix/prefix heuristic for the long tail. Order matters — first match wins.