@bongos/core 1.19.715 → 1.19.725

package/scripts/gds/device-flow-help.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/device-flow-help.js — the one explanation of a Device-Flow refusal, shared
+// by `bongos setup` and `bongos login` (task 1003400).
+//
+// WHY IT EXISTS AT ALL. GitHub creates an App from a manifest with Device Flow OFF and
+// exposes no API to switch it on — only a checkbox in the App's settings. So on every
+// wizard-born instance the documented terminal sign-in is hard-broken from birth, for
+// every builder, until the owner ticks that box. Nothing in the product can do it for
+// them; the least we can do is say so precisely, and name a route that works meanwhile.
+//
+// WHY IT IS ITS OWN FILE. setup.js grew the detector + the guidance first; login.js threw
+// a bare "could not start sign-in (HTTP 424)" — a dead end sitting directly downstream of
+// the CLI's OWN wrong-instance advice to run `bongos login`. setup.js already requires
+// login.js for runDeviceFlow, so having login.js require setup.js back would close a
+// require cycle. Both now depend on this leaf instead: one source of truth, no cycle.
+//
+// PURE — no fs, no network, no process state; both functions unit-test standalone.
+
+// Does this /auth/device/start response carry GitHub's device_flow_disabled refusal?
+//
+// Matches on TEXT, not status, deliberately: the CLI talks to many core versions, and the
+// server envelope moved from 502 to 424 (a 502 body was being eaten by the CDN). Both
+// register. Must NOT match auth_not_configured or any other upstream failure — those have
+// different cures, and a wrong cure is worse than a generic error.
+function isDeviceFlowDisabled(start) {
+  if (!start || start.ok) return false;
+  const err = start.data && start.data.error;
+  const text = [
+    typeof err === 'string' ? err : '',
+    err && typeof err === 'object' ? `${err.code || ''} ${err.message || ''}` : '',
+    start.data && start.data.message ? String(start.data.message) : '',
+  ].join(' ');
+  return /device_flow_disabled/i.test(text);
+}
+
+// The plain-language guidance: what happened, the web route that works RIGHT NOW, and the
+// owner's one-checkbox repair. Returns an array of lines (the callers join them).
+//
+// `finish` names the caller, because only the closing move differs: setup prompts for the
+// token inline ("paste it below"), login has no such prompt and must tell you to run the
+// one-liner instead. Everything above that step is genuinely shared and stays shared.
+function deviceFlowFallbackLines(base, { finish = 'setup' } = {}) {
+  const settings = `${base}/builders/settings`;
+  const close = finish === 'login'
+    ? [
+      '  3. Copy the one-liner it shows and run it in this shell — that writes',
+      '     the same session `bongos login` would have.',
+    ]
+    : [
+      '  3. Copy the token it shows and paste it below (or run the printed',
+      '     one-liner in another shell, then re-run setup).',
+    ];
+  return [
+    '',
+    "This project's GitHub App has Device Flow switched off, so terminal sign-in",
+    'cannot start. Apps created by the one-click setup begin this way — GitHub',
+    'only offers the switch as a checkbox in the App settings; no setup flow can',
+    'tick it automatically.',
+    '',
+    'Sign in through the web instead (works right now):',
+    `  1. Open ${settings} and sign in with GitHub.`,
+    '  2. Under "CLI Access", click "Re-issue CLI token".',
+    ...close,
+    '',
+    'To repair terminal sign-in for everyone (the project owner, once):',
+    '  GitHub → Settings → Developer settings → GitHub Apps → your app →',
+    '  check "Enable Device Flow" → Save. Web sign-in is unaffected either way.',
+  ];
+}
+
+module.exports = { isDeviceFlowDisabled, deviceFlowFallbackLines };

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/init.js

@@ -525,6 +525,62 @@ function buildReadme(branding = {}) {
   ].join('\n');
 }
 
+// The START-HERE content as an APPENDABLE section, for a repo that already has a
+// README of its own. Fenced by a stable marker so re-running init is idempotent and so
+// an owner can find (and delete) the block we added.
+//
+// WHY this is not just buildReadme: an ADOPTED repo always has a README, and the
+// write-if-absent rule below therefore skipped the first-run guide on every single adopt
+// — silently, logging "already present — left untouched" as though nothing were owed.
+// That removed the one human-facing instruction to run `npm install`, without which the
+// repo has no `bongos` command at all. Appending mirrors how the adopt path already
+// treats .gitignore: keep what the owner wrote, add only what the instance needs.
+const README_MARKER = '<!-- cloud-bongos:start-here -->';
+
+function buildReadmeSection(branding = {}) {
+  const guide = buildReadme(branding);
+  // Reuse the canonical guide, demoted one heading level so it nests under the owner's
+  // own README, and drop its H1 title (their README already has one).
+  const body = guide
+    .split('\n')
+    .slice(1)                                   // drop "# <product>"
+    .join('\n')
+    .replace(/^## /gm, '### ')
+    .trim();
+  return `${README_MARKER}\n\n## Working on this project (Cloud Bongos)\n\n${body}\n`;
+}
+
+// Append the START-HERE section to an existing README unless it is already there.
+// PURE (text in → text out) so the idempotence is unit-testable without fs.
+// Returns { text, action } where action is 'appended' | 'present'.
+function appendReadmeSection(existing, section) {
+  const prev = String(existing == null ? '' : existing);
+  if (prev.includes(README_MARKER)) return { text: prev, action: 'present' };
+  return { text: `${prev.replace(/\n*$/, '\n')}\n---\n\n${section}`, action: 'appended' };
+}
+
+// Put the first-run guide in the repo's README whichever state it is in: mint the whole
+// guide when there is no README, else append the marked section. Shared by the greenfield
+// and adopt paths so neither can silently owe it. Returns the action taken.
+function layerReadme(branding, { dir, dryRun, log = console.log } = {}) {
+  const readmePath = path.join(dir, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    if (dryRun) { log(`  [dry-run] would write README.md (first-run START-HERE)`); return 'created'; }
+    fs.writeFileSync(readmePath, buildReadme(branding));
+    log(`  ✓ wrote README.md (first-run START-HERE)`);
+    return 'created';
+  }
+  const { text, action } = appendReadmeSection(fs.readFileSync(readmePath, 'utf8'), buildReadmeSection(branding));
+  if (action === 'present') {
+    log('  • README.md already carries the Cloud Bongos start-here section — left untouched.');
+    return 'present';
+  }
+  if (dryRun) { log('  [dry-run] would append the Cloud Bongos start-here section to the existing README.md'); return 'appended'; }
+  fs.writeFileSync(readmePath, text);
+  log('  ✓ appended the Cloud Bongos start-here section to README.md (your own content is untouched)');
+  return 'appended';
+}
+
 function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log }) {
   const configDir = path.join(dir, 'config');
   const brandingPath = path.join(configDir, 'branding.json');
@@ -572,14 +628,9 @@ function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log })
   log(`  ✓ wrote ${path.relative(dir, modulesPath)}`);
   log(`  ✓ wrote ${path.relative(dir, hierarchyPath)}`);
   log(`  ✓ wrote ${path.relative(dir, pkgPath)} (pins ${CORE_PKG} → ${pinNote})`);
-  // README START-HERE (task 1002404): write-if-absent so a --force re-init or an
-  // owner's own README is never clobbered.
-  if (!fs.existsSync(readmePath)) {
-    fs.writeFileSync(readmePath, buildReadme(branding));
-    log(`  ✓ wrote ${path.relative(dir, readmePath)} (first-run START-HERE)`);
-  } else {
-    log(`  • ${path.relative(dir, readmePath)} already present — left untouched`);
-  }
+  // README START-HERE (task 1002404): mint it when absent, else APPEND the marked
+  // section. Never a blind overwrite — an owner's own README content always survives.
+  layerReadme(branding, { dir, dryRun: false, log });
   return { brandingPath, modulesPath, hierarchyPath, pkgPath, readmePath, wrote: true };
 }
 
@@ -816,6 +867,10 @@ async function runAdopt(spec, { dir, dryRun, noSeed = false, accept = false, cor
 
   const cfg = layerConfigs(spec, { dir, dryRun, log });
   const pkg = layerPackageJson(spec, { dir, dryRun, log, ...(coreDep ? { coreRange: coreDep } : {}) });
+  // The first-run guide, which adopt used to skip entirely: an adopted repo always has a
+  // README, so the greenfield write-if-absent rule never fired and the one instruction to
+  // run `npm install` was silently owed on every adopt.
+  layerReadme(buildBrandingConfig(spec), { dir, dryRun, log });
 
   // Vendor the pinned core tarball + generate the lockfile, mirroring the greenfield
   // --vendor-core steps, so the adopted repo is `npm ci --omit=dev`-installable (ADR 0108).
@@ -1061,6 +1116,7 @@ module.exports = {
   provisioningSlug, provisioningRequest, productionTopologyKickoff,
   // --adopt (brownfield layering, ADR 0121 / task 2042)
   mergeCoreDependency, coreDepRange, layerConfigs, layerPackageJson, runAdopt,
+  buildReadmeSection, appendReadmeSection, layerReadme, README_MARKER,
   KNOWN_MODULES, HOSTING_SHAPES, CORE_PKG,
   // greenfield installability (ADR 0108 gap 1/4, task 2053)
   buildInstancePackageJson, coreVersionSafe, INSTANCE_START_SCRIPT, INSTANCE_MIGRATE_SCRIPT,

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/login.js

@@ -23,6 +23,10 @@
 const readline = require('node:readline');
 const { spawnSync } = require('node:child_process');
 const { saveSession, loadStoredSession, listStoredSessions } = require('./cli-lib');
+// The device-flow refusal detector + its plain-language cure (task 1003400). A leaf
+// module, NOT setup.js: setup requires this file for runDeviceFlow, so requiring it
+// back would close a require cycle. Both callers depend on the leaf instead.
+const { isDeviceFlowDisabled, deviceFlowFallbackLines } = require('./device-flow-help');
 const { branding } = require('../../src/branding');
 
 // --- pure helpers (unit-tested) ---------------------------------------------
@@ -102,6 +106,20 @@ async function runDeviceFlow(base, { log, idp = null }) {
   if (start.status === 503 || (start.data && (start.data.error === 'auth_not_configured' || (start.data.error && start.data.error.code === 'idp_signing_unconfigured')))) {
     throw new Error('that instance has no sign-in configured yet — ask its Archon to set it up.');
   }
+  // Device Flow is OFF on every GitHub App born from a manifest, and GitHub exposes no
+  // API to enable it — so terminal sign-in is broken from birth on a fresh instance,
+  // for everyone, until its owner ticks one checkbox. This threw a bare
+  // "could not start sign-in (HTTP 424)", which is where the CLI's OWN wrong-instance
+  // refusal sends every multi-project user: a dead end at the end of our own advice.
+  // In federated mode the device flow runs against the HUB, so the cure is on the hub's
+  // app — point the guidance at whichever origin actually refused.
+  if (isDeviceFlowDisabled(start)) {
+    const refusedBy = idp ? idp.origin : base;
+    throw new Error([
+      'GitHub refused the device-code request for this project.',
+      ...deviceFlowFallbackLines(refusedBy, { finish: 'login' }),
+    ].join('\n'));
+  }
   if (!start.ok || !start.data || !start.data.device_code) {
     throw new Error(`could not start sign-in (HTTP ${start.status}).`);
   }

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