@bongos/core 1.19.714 → 1.19.724

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.

package/src/bongos/artist-gate.js

@@ -0,0 +1,204 @@
+'use strict';
+
+// src/bongos/artist-gate.js — the artist gate: what an unresolved artist review
+// holds, and what releases it (ADR 0241, task 1003575).
+//
+// WHAT IT ANSWERS: "an artist review task is open — does anything stop?" One
+// value, read from one place, so the cascade that FILES those reviews and the
+// deploy that they HOLD cannot disagree about the project's own policy:
+//
+//   off        no artist review tasks are filed at all; nothing is held
+//   advisory   reviews are filed; nothing is held
+//   strict     reviews are filed, and an unresolved one holds the DEPLOY
+//
+// THE TWO THINGS THAT MAKE THIS ADMISSIBLE, both from ADR 0241 and neither
+// optional — a gate that loses either one is the gate ADR 0162 retired:
+//
+//  1. IT READS A STATE, NEVER A VERDICT. The blocking condition is "is there an
+//     unresolved artist review attached to this work?", never "did the artist
+//     approve it?". An artist saying the copy is bad stops nothing by itself, and
+//     an artist saying it is fine releases nothing by itself; what moves is the
+//     review task's STATUS, by the ordinary means (shipped, or dismissed in
+//     triage). That is what keeps the gate rank-consistent and machine-checkable
+//     instead of pinned to one person being available.
+//
+//  2. IT HOLDS THE DEPLOY, NOT THE SHIP. A builder's work still grades, merges,
+//     credits and lands on CI alone. Nothing here may ever reach the ship or land
+//     path — the wave-4 strand class that forced ADR 0162 is exactly what that
+//     separation prevents. The only thing this can delay is a pin move, which is
+//     already deliberate, already owner-initiated, and reversible by doing it
+//     later.
+//
+// PURE HALF / READ HALF. Everything below `unresolvedArtistReviews` is pure — a
+// list of task-shaped objects in, a verdict out — so the halt matrix tests with no
+// pack, no env and no database. Only `artistGateMode` touches the branding pack,
+// and it defers that require to call time for the same reason project-door.js
+// does.
+
+const log = require('./logger').logger.child({ src: 'artist-gate' });
+
+// The three levels, ORDERED loosest → strictest (ADR 0241 §2's table).
+const ARTIST_GATE_LEVELS = Object.freeze(['off', 'advisory', 'strict']);
+
+// A task status is RESOLVED when the work it asks for is done or the board has
+// decided it will not be — 'shipped' and 'abandoned' are the two ways a task
+// leaves the board, and 'abandoned' is what triage's dismiss writes. Everything
+// else (backlog, ready, active, completed, confirmed) is an open request, which
+// is the state ADR 0241 §1 says the gate reads. A row merged into another is
+// resolved too: its successor carries the work.
+const RESOLVED_REVIEW_STATUSES = Object.freeze(['shipped', 'abandoned']);
+
+// The (source, source_ref-prefix) pair every cascade-filed artist review carries.
+// Mirrored from modules/lifecycle/cascade.js rather than imported: core must not
+// reach into a module (the fitness boundary), and a review's identity on the wire
+// is a two-field fact, not a behaviour. The cascade's own test pins the spelling.
+const ARTIST_REVIEW_SOURCE = 'cascade';
+const ARTIST_REVIEW_REF_PREFIX = 'cascade-artist-review-on-ship-';
+
+// ---------------------------------------------------------------------------
+// The pure half
+// ---------------------------------------------------------------------------
+
+// Is this task row a cascade-filed artist review? PURE and total.
+function isArtistReview(task) {
+  if (!task) return false;
+  return String(task.source || '') === ARTIST_REVIEW_SOURCE
+    && String(task.source_ref || '').startsWith(ARTIST_REVIEW_REF_PREFIX);
+}
+
+// Is this review still an open request? PURE and total. A merged row counts as
+// resolved even at an open status — the merge moved the work, and holding a
+// deploy on a row nobody will ever action again is the stall this gate must not
+// have.
+function isReviewResolved(task) {
+  if (!task) return true;
+  if (task.merged_into_task_id != null) return true;
+  return RESOLVED_REVIEW_STATUSES.includes(String(task.status || ''));
+}
+
+// The reviews that actually HOLD, out of every review row handed in. PURE.
+//
+// Two filters, and the second is ADR 0241 §5 — tightening is not retroactive. A
+// project that raises its gate to 'strict' must not inherit a backlog of reviews
+// for work nobody remembers, so a review filed BEFORE the raise never holds. An
+// absent or unparseable `since` means no cutoff, which is the right answer for a
+// project that has been strict since it stood up (the default) — it is not a
+// licence to ignore reviews, so it must not read as one.
+//
+// A review with no readable created_at is KEPT: the cutoff exists to spare a
+// project work it never chose, not to let an unreadable row slip the gate.
+function unresolvedArtistReviews(tasks, { since = null } = {}) {
+  const cutoff = since ? Date.parse(since) : NaN;
+  const list = Array.isArray(tasks) ? tasks : [];
+  return list.filter((t) => {
+    if (!isArtistReview(t) || isReviewResolved(t)) return false;
+    if (Number.isNaN(cutoff)) return true;
+    const filed = Date.parse(t.created_at);
+    if (Number.isNaN(filed)) return true;
+    return filed >= cutoff;
+  });
+}
+
+// Does the gate hold, and if so WHAT holds it and WHICH control releases it?
+// Returns null when nothing is held, else a halt-shaped object. PURE.
+//
+// The sentence is the point, not decoration. ADR 0241 §4's second guard is
+// explicit: the refusal must name what holds the deploy and which control
+// releases it, in one line, because ADR 0162's incident was made worse by a
+// blocked state that did not explain itself. So the detail names the review ids
+// AND both real ways out — resolve them, or the project OWNER releases past with
+// an override-request (rationale required, audit-logged; a self-release is
+// permitted and recorded as such, ADR 0241 §3).
+//
+// Keep this sentence TRUE to the mechanism, not merely to the ADR's prose. The
+// first cut of this gate described an escape hatch the code did not wire, which
+// is worse than no sentence: a refusal that names a control nobody can actually
+// use is a stall with extra steps. The release lives in
+// modules/lifecycle/db-overrides.js (the gate-release class) and the gate reads
+// it through db-tasks.listOpenArtistReviews — change one, re-read the other two.
+// `truncated` says the caller's read hit its scan cap, so `reviews` is a floor
+// rather than the whole queue. It cannot change the VERDICT — every row handed in
+// is a holder, so one is enough — only the count, which is then reported as a
+// floor ("200+") instead of a number the sentence cannot stand behind.
+function artistGateHalt({ mode, reviews = [], truncated = false } = {}) {
+  if (mode !== 'strict') return null;
+  const open = Array.isArray(reviews) ? reviews : [];
+  if (!open.length) return null;
+  // Named as `task N`, never a bare `#N`: this sentence is copied into chat, commit
+  // messages and session logs, where a bare hash autolinks to a GitHub issue that
+  // does not exist (the kernel's linkify rule).
+  const ids = open.slice(0, 5).map((t) => String(t.id));
+  const more = open.length - ids.length;
+  const named = ids.map((id) => `task ${id}`).join(', ');
+  return {
+    code: 'ARTIST_REVIEW_UNRESOLVED',
+    message: `${open.length}${truncated ? '+' : ''} unresolved artist review${open.length === 1 && !truncated ? '' : 's'} hold this deploy — the project runs artist_gate 'strict'`,
+    detail: `Held by ${named}${more > 0 ? ` and ${more} more` : ''}. `
+      + 'Two ways out, both ordinary: resolve or dismiss those reviews on the board, '
+      + 'or release one — POST /tasks/:id/override-request with a rationale, then the PROJECT OWNER '
+      + 'approves it at POST /override-requests/:id/decide (owner only, not an Archon; a self-release '
+      + 'is allowed and is audit-logged as a self-override). A released review stays open on the board; '
+      + "what it stops doing is holding the pin. Setting this project's artist_gate to 'advisory' "
+      + 'stops reviews holding deploys at all.',
+    reviewIds: open.map((t) => String(t.id)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The read half
+// ---------------------------------------------------------------------------
+
+// artistGateMode — this project's stored artist strictness, and ONLY that. The
+// one reader for the knob, so the cascade, the deploy gate and any surface that
+// reports the policy cannot disagree about what the owner set.
+//
+// An unreadable pack, or a value this core cannot read, resolves to 'strict'. That
+// is fail-closed in the direction ADR 0241 §4 already chose as the DEFAULT, so an
+// instance whose pack went missing behaves like a fresh one rather than silently
+// dropping a policy the owner set — and 'strict' holds only a pin, which the owner
+// can always release. `read` is injectable for the unit tests only (the pack is
+// memoized for the process lifetime, which is why applying a change restarts the
+// instance).
+let warnedUnknownArtistGate = false;
+function artistGateMode(read) {
+  const readPack = read || require('../branding').branding; // eslint-disable-line global-require
+  let v;
+  try { v = readPack().project?.artistGate; } catch (err) {
+    log.error('[artist-gate] branding pack unreadable — treating the project as strict:', err.message);
+    return 'strict';
+  }
+  if (ARTIST_GATE_LEVELS.includes(v)) return v;
+  // Absent is the honest case for a self-hosted instance that has never been
+  // pushed a setting, and for the neutral pack before a value was written. It
+  // takes the default rather than a warning.
+  if (v === undefined || v === null || v === '') return 'strict';
+  if (!warnedUnknownArtistGate) {
+    warnedUnknownArtistGate = true;
+    log.error(`[artist-gate] unrecognised artistGate ${JSON.stringify(v)} — treating the project as strict`);
+  }
+  return 'strict';
+}
+
+// The moment this project's gate was last RAISED to 'strict', or null. Written by
+// the platform when the owner tightens the setting (provisioning.artistGateStamp)
+// and carried in on <PREFIX>_ARTIST_GATE_SINCE. null = no cutoff (ADR 0241 §5).
+function artistGateSince(read) {
+  const readPack = read || require('../branding').branding; // eslint-disable-line global-require
+  let v;
+  try { v = readPack().project?.artistGateSince; } catch { return null; }
+  if (typeof v !== 'string' || !v) return null;
+  return Number.isNaN(Date.parse(v)) ? null : v;
+}
+
+module.exports = {
+  ARTIST_GATE_LEVELS,
+  RESOLVED_REVIEW_STATUSES,
+  ARTIST_REVIEW_SOURCE,
+  ARTIST_REVIEW_REF_PREFIX,
+  isArtistReview,
+  isReviewResolved,
+  unresolvedArtistReviews,
+  artistGateHalt,
+  artistGateMode,
+  artistGateSince,
+};

package/src/branding.js

@@ -69,6 +69,14 @@ const ENV_OVERRIDES = [
   // view | apply | full. The ceiling on the visibility axis that JOINABILITY may
   // only narrow; composed into one door by src/bongos/project-door.js.
   ['JOIN_GRANT', ['project', 'joinGrant']],
+  // The artist gate (ADR 0241, task 1003575) — off | advisory | strict. `off`
+  // generates no artist review tasks; `strict` lets an unresolved one hold this
+  // instance's DEPLOY (never a builder's ship). Its companion stamp says when the
+  // gate was last raised, so the hold is not retroactive (ADR 0241 §5); empty is
+  // skipped by the loop below, which reads as "no cutoff" — correct for a project
+  // that has been strict since it stood up.
+  ['ARTIST_GATE', ['project', 'artistGate']],
+  ['ARTIST_GATE_SINCE', ['project', 'artistGateSince']],
 ];
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
@@ -250,6 +258,13 @@ function clientBranding(b = branding()) {
       // stranger's client should be able to say what THIS door does before knocking.
       // `full` = this axis narrows nothing, so an un-pushed instance is unchanged.
       joinGrant: b.project?.joinGrant || 'full',
+      // The artist gate (ADR 0241, task 1003575). Public for the read-back reason
+      // its neighbours are: a manage page has to be able to tell a SAVED setting
+      // from a LIVE one, and this instance's own manifest is the only honest
+      // answer to "what did it restart with?". The fallback is the platform
+      // DEFAULT, which for this one key is 'strict' rather than today's behaviour
+      // — the owner's ruling, ADR 0241 §4.
+      artistGate: b.project?.artistGate || 'strict',
     },
   };
 }

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.714'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.724'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');
@@ -164,6 +164,13 @@ module.exports = {
   //     db.js into the bounded src/bongos/db-kernel.js, which this surface resolves
   //     through — so loading a kernel accessor no longer drags in the monolith.
   getBuilderById: (...a) => require('./bongos/db-kernel').getBuilderById(...a),
+  // getFoundingBuilder — the instance's PROJECT OWNER: its first admitted human
+  //     builder (task 1002739). Kernel identity like getBuilderById beside it, and
+  //     published because ADR 0241 §3 gives the artist gate's one escape hatch to
+  //     "the project owner only — not the builder, not any Metic+, not the artist",
+  //     which a module cannot enforce without being able to ask who that is. It is
+  //     a READ of an existing row; it grants nothing by itself.
+  getFoundingBuilder: (...a) => require('./bongos/db-kernel').getFoundingBuilder(...a),
   insertAuditLog: (...a) => require('./bongos/db-kernel').insertAuditLog(...a),
   get LIVE_RANK_LADDER() { return require('./bongos/db-kernel').LIVE_RANK_LADDER; },
   // The ladder as the canonical 1-based rank → tier map (BV1.R108) — modules
@@ -303,6 +310,32 @@ module.exports = {
   //     the other two had closed. Optional `{ publishable }` for a caller that
   //     holds a publish verdict — see src/bongos/project-door.js.
   projectJoinDoor: (opts) => require('./bongos/project-door').effectiveJoinDoor(opts),
+  // artistGate — the project's artist strictness and the pure verdict helpers
+  //     that read it (ADR 0241, task 1003575): 'off' | 'advisory' | 'strict'.
+  //     `off` is what tells the lifecycle cascade not to file artist reviews at
+  //     all, and `strict` is what lets an unresolved one hold a DEPLOY (never a
+  //     ship). Published as the whole small surface rather than one call because
+  //     two different modules ask two different questions of it — "should I file
+  //     this?" and "does anything hold?" — and both must resolve the knob through
+  //     this one reader, never from branding().project directly: the fail-closed
+  //     default and the non-retroactivity cutoff live in there.
+  //     The members are named ONE BY ONE rather than re-exported wholesale: a
+  //     `return require(…)` would publish whatever that file happens to export
+  //     next, which is how a doorway stops being a contract.
+  get artistGate() {
+    const g = require('./bongos/artist-gate'); // eslint-disable-line global-require
+    return Object.freeze({
+      ARTIST_REVIEW_SOURCE: g.ARTIST_REVIEW_SOURCE,
+      ARTIST_REVIEW_REF_PREFIX: g.ARTIST_REVIEW_REF_PREFIX,
+      RESOLVED_REVIEW_STATUSES: g.RESOLVED_REVIEW_STATUSES,
+      isArtistReview: g.isArtistReview,
+      isReviewResolved: g.isReviewResolved,
+      unresolvedArtistReviews: g.unresolvedArtistReviews,
+      artistGateHalt: g.artistGateHalt,
+      artistGateMode: g.artistGateMode,
+      artistGateSince: g.artistGateSince,
+    });
+  },
   // readApplicantProfileFromHub(githubId) — the reviewer queue's LIVE per-render
   //     read of one applicant's hub profile view (privacy spec D7, task
   //     1002972). Published as a NARROW port on purpose: the underlying call is

package/tests/api_path_404.mjs

@@ -144,5 +144,33 @@ t('rebaseRequiredHint: says waiting is correct when CI is merely backed up', ()
   assert.match(rebaseRequiredHint([{ id: 7 }]), /waiting is correct/);
 });
 
+// task 1002788 — the menu must not name the move that deadlocks the reader.
+//
+// This hint fires on a branch that is ALREADY PUBLISHED, and server-mediated
+// publish is append-only by deliberate design (github-push.js: "Refuse
+// non-fast-forward implicitly (no --force, ever)"). The old wording — "rebase
+// the branch and re-ship" — rewrites history the server already holds, so every
+// later publish is rejected non-fast-forward and the builder is left gated from
+// new claims AND unable to land the one they hold. Reproduced end-to-end on task
+// 1002485. ship-land.js's recovery text already says "Do NOT reset or re-rebase";
+// this is the same advice given BEFORE the deadlock rather than after it.
+t('rebaseRequiredHint: prescribes MERGE, and never instructs a rebase', () => {
+  const hint = rebaseRequiredHint([{ id: 7 }]);
+  assert.ok(hint.includes('git merge origin/main'),
+    'must name the fast-forward-safe command, not just forbid the other one');
+  // Narrow on purpose: bans INSTRUCTING a rebase, not the word — "never rebase"
+  // is the sentence that carries the lesson and must keep working.
+  for (const re of [/\brebase\s*\+\s*re-ship\b/i, /\brebase (the|its|your) branch\b/i, /\brebases it\b/i]) {
+    assert.ok(!re.test(hint), `must not instruct a rebase (matched ${re}): ${hint}`);
+  }
+  assert.match(hint, /never rebase/i, 'and must say why, so the next reader does not re-add it');
+});
+
+t('rebaseRequiredHint: still leads with /strand-fix — merge is the manual fallback, not the first offer', () => {
+  const hint = rebaseRequiredHint([{ id: 7 }]);
+  assert.ok(hint.indexOf('/strand-fix') < hint.indexOf('git merge origin/main'),
+    'the command that works on any machine must still come first (task 1003768)');
+});
+
 console.log(`\napi_path_404: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);