@bongos/core 1.21.115 → 1.21.117

package/scripts/gds/provision-core-upgrade.js

@@ -36,6 +36,7 @@ const { spawnSync } = require('child_process');
 const { CONFIG, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, REPO_ROOT } = require('./provision-config.js');
 const { appUser, dbName, instanceUser, parseTargetRef, resolveOwnerGithubToken, selfInstanceRoot, standaloneRoot } = require('./provision-repo.js');
 const { ensurePinWriteKey, hasOwnAccount, pinKeyPath, pinSshCommand } = require('./provision-pin-key.js');
+const { replayPinCommit } = require('./provision-pin-replay.js'); // GitHub ahead → pin on top (task 1004733)
 const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
 const { RELEASE_NOTES_FILE, RELEASE_NOTES_MAX_BYTES, parseChangeRecords, notesBetween } = require('./release-notes.js');
 const outcome = require('./upgrade-outcome.js'); // how far a failed move got, as a class (task 1004446)
@@ -411,9 +412,13 @@ async function coreUpgradeInstance(inst, deps, intent) {
 // parseRepoNote in modules/provisioning/core-upgrade.js (re-stated there because a
 // module may not require a script; tests/core_upgrade_runner.mjs round-trips the two).
 //
-// NOTHING IS FORCED OR REBASED. When GitHub has commits the box does not, putting the pin
-// on top of them would change what the live box runs with no restart and no health check.
-// That is reported for an operator to reconcile, never resolved here.
+// NOTHING IS FORCED, AND THE LIVE BOX IS NEVER REBASED. When GitHub has commits the box
+// does not, moving the box onto them would change what it runs with no restart and no
+// health check. Since task 1004733 the pin commit ALONE is replayed onto GitHub's history in
+// a scratch worktree and pushed as an ordinary fast-forward (provision-pin-replay.js), so
+// GitHub names the new core and the box stays exactly what the move proved. A conflict in
+// the pin files is reported ("conflict"), never resolved here. The box still does not pick
+// up the owner's other commits — that would be a deploy, not a pin push (ADR 0350 amendment).
 //
 // WHAT MAKES IT DURABLE (task 1004291, ADR 0350). The owner's token is kept for an hour
 // after they sign in with repository access (GITHUB_TOKEN_TTL_MS in src/bongos/db.js — one
@@ -431,6 +436,7 @@ const REPO_NOTES = Object.freeze({
   needs_account: 'The hub could not set up lasting write access to the project\'s GitHub repository: this project needs its own account on the server first. Once it has one, reconnecting GitHub with repository access sets up lasting access.',
   refused: 'GitHub turned down the owner\'s GitHub access — it may have expired, or lack permission to write to the repository.',
   behind: 'GitHub has changes the server does not have, so the new version could not be added on top of them. An operator needs to bring the two back in line; the site itself is running normally.',
+  conflict: 'GitHub has its own changes to the same version files (package.json or package-lock.json), so the new version was not added on top of them and nothing there was overwritten. An operator needs to choose between the two; the site itself is running normally.',
   failed: 'The hub could not save the new version to GitHub.',
 });
 // A branch name that is safe to interpolate. Narrower than git's own ref grammar on
@@ -498,6 +504,14 @@ async function pushUpgradePin(inst, deps, { instanceDir }) {
   const at = `${repo.owner}/${repo.name}@${branch}`;
   const hardened = `git -C ${instanceDir} -c core.hooksPath=/dev/null`;
   const env = { GIT_TERMINAL_PROMPT: '0' };   // a refused credential fails; it never waits at a prompt
+  // GitHub is ahead: replay the pin commit alone on top, over the credential that was just
+  // refused as behind, and push again — never forced (task 1004733, provision-pin-replay.js).
+  const replayed = (via, git, remote) => {
+    const rr = replayPinCommit({ exec, instanceDir, branch, git, remote, env, slug: inst.slug, tmpDir: deps.tmpDir, pushFault, gitLine, log });
+    if (!rr.ok) return miss(rr.code, rr.extra);
+    if (rr.already) log(`  ✓ ${at} already names this version — nothing to add`);
+    return { pushed: true, via, branch, ...(rr.replayed ? { replayed: true } : { already: true }) };
+  };
 
   const token = await resolveOwnerGithubToken(inst, deps, { tag: '[core-upgrade]' });
 
@@ -515,8 +529,9 @@ async function pushUpgradePin(inst, deps, { instanceDir }) {
       return { pushed: true, via: 'write-key', branch };
     }
     const fault = pushFault(r);
-    // The key WORKED and the history stopped it: no other credential changes that.
-    if (fault === 'behind') return miss('behind', gitLine(r));
+    // The key WORKED and the history stopped it: no other credential changes that, so the
+    // pin is replayed on top of GitHub's history over this same key (task 1004733).
+    if (fault === 'behind') return replayed('write-key', `${hardened} -c ${pinSshCommand(keyPath)}`, `git@github.com:${repo.owner}/${repo.name}.git`);
     log(`  • ${inst.slug}: the write key did not push (${fault}) — trying the next credential`);
   }
 
@@ -525,8 +540,11 @@ async function pushUpgradePin(inst, deps, { instanceDir }) {
     let r = null;
     try {
       writeFile(credFile, `https://x-access-token:${token}@github.com\n`, { mode: 0o600 });
-      r = exec(`${hardened} -c credential.helper= -c credential.helper='store --file=${credFile}' push https://x-access-token@github.com/${repo.owner}/${repo.name}.git HEAD:${branch}`,
-        { allowFail: true, env });
+      const viaToken = `${hardened} -c credential.helper= -c credential.helper='store --file=${credFile}'`;
+      const tokenRemote = `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`;
+      r = exec(`${viaToken} push ${tokenRemote} HEAD:${branch}`, { allowFail: true, env });
+      // Behind: replayed while the credential file still exists (the finally removes it).
+      if (failedRun(r) && pushFault(r) === 'behind') return replayed('owner-token', viaToken, tokenRemote);
     } catch (e) {
       return miss('failed', `(could not stage the owner's credential: ${String((e && e.message) || e).slice(0, 160)})`);
     } finally {
@@ -547,6 +565,7 @@ async function pushUpgradePin(inst, deps, { instanceDir }) {
     return { pushed: true, via: 'origin', branch };
   }
   const fault = pushFault(r);
+  if (fault === 'behind') return replayed('origin', hardened, 'origin');
   // A refusal here is not the owner's access being turned down — there was none to turn
   // down. It is the read-only key, which is the no-access case.
   // ...unless the project has no account of its own, in which case no key CAN be minted

package/scripts/gds/provision-pin-replay.js

@@ -0,0 +1,126 @@
+'use strict';
+// provision-pin-replay.js — when GitHub is AHEAD of a hosted project's box, put the core move's
+// pin commit on top of GitHub's history instead of leaving GitHub on the old core (task 1004733,
+// ADR 0350 amendment).
+//
+// WHY. pushUpgradePin pushes the pin commit the move made on the box. For a project the owner
+// works from a laptop, GitHub almost always has commits the box does not, so that push is
+// refused as non-fast-forward ("behind"). Before this file the move then finished `done` with a
+// repo_not_updated note: the box ran the new core, GitHub still named the old one, and the next
+// deploy from GitHub could quietly roll the core back.
+//
+// WHAT IT DOES. Fetch the branch over the SAME credential that was refused, replay ONLY the pin
+// commit (package.json + package-lock.json, and any generated file upgrade.js committed with it)
+// on top of what was fetched, and push that — an ordinary fast-forward, never forced.
+//
+// THE LIVE BOX IS NOT TOUCHED. The replay happens in a scratch worktree (mode 0700, outside the
+// checkout, removed whatever happened). The box's HEAD, files and running site stay exactly what
+// the move's health check proved, which is why the old "nothing is rebased" rule (changing what
+// the box runs with no restart and no health check) still holds.
+//
+// A REAL CONFLICT STOPS. If the owner changed the same lines of those files, choosing between the
+// two is a person's call: the cherry-pick is aborted, nothing is pushed, and the note names the
+// files ("conflict"). Anything else that goes wrong reports, never retries in a loop.
+//
+// OUT OF SCOPE, ON PURPOSE: the box picking up the owner's OTHER commits. Nothing pulls them onto
+// a hosted box after provisioning (standalonePullCmd runs at provision time only, provision.js);
+// merging them into a live checkout here would deploy the owner's code with no install, migrate,
+// restart or health check — a deploy, not a pin push. ADR 0350's amendment records that ruling.
+//
+// NEVER THROWS: the caller turns a throw into a broken instance, and this instance is running.
+
+const crypto = require('node:crypto');
+const os = require('node:os');
+
+// The subject upgrade.js persistPin gives the pin commit. Anything else at HEAD is not ours to
+// replay onto someone's history.
+const PIN_SUBJECT_RE = /^pin @bongos\/core /;
+const PIN_FILES = ['package.json', 'package-lock.json'];
+const SHA_RE = /^[0-9a-f]{40,64}$/;
+// A scratch path the shell may see unquoted (the tmp dir itself is the runner's, but checked).
+const SAFE_PATH_RE = /^[A-Za-z0-9_./:~-]+$/;
+
+const failedRun = (r) => !r || r.softFailed === true || r.ok === false;
+const out = (r) => String((r && r.stdout) || '').trim();
+
+/**
+ * Replay the box's pin commit onto the branch GitHub has, and push it.
+ *
+ * @param {object} o
+ *   exec        the CONTROL PLANE executor (the one pushUpgradePin pushed with)
+ *   instanceDir the project's checkout on the hub
+ *   branch      the branch pushUpgradePin pushed (already BRANCH_RE-checked)
+ *   git         the credentialed, hardened git prefix that was refused as behind
+ *   remote      the remote that same push named
+ *   env         that push's env (GIT_TERMINAL_PROMPT=0)
+ *   slug        the project's (validated) slug, for the scratch path's name
+ *   tmpDir      where the scratch worktree goes (default os.tmpdir())
+ *   pushFault, gitLine  pushUpgradePin's own readers of a git refusal
+ * @returns {{ ok:true, replayed?:true, already?:true } | { ok:false, code:string, extra:string }}
+ */
+function replayPinCommit(o) {
+  try { return replay(o); } catch (e) {
+    return { ok: false, code: 'failed', extra: `(the pin could not be replayed: ${String((e && e.message) || e).slice(0, 160)})` };
+  }
+}
+
+function replay({ exec, instanceDir, branch, git, remote, env, slug, tmpDir, pushFault, gitLine, log = () => {} }) {
+  const plain = `git -C ${instanceDir} -c core.hooksPath=/dev/null`;
+  const run = (cmd, extraEnv) => exec(cmd, { allowFail: true, env: { ...env, ...(extraEnv || {}) } });
+
+  // 1. HEAD must be the move's own pin commit, with one parent, or there is nothing of ours to replay.
+  const head = run(`${plain} log -1 --format=%H%n%P%n%cn%n%ce%n%s HEAD`);
+  const [sha, parents, cn, ce, subject] = out(head).split('\n');
+  if (failedRun(head) || !SHA_RE.test(sha || '') || String(parents || '').split(' ').length !== 1 || !PIN_SUBJECT_RE.test(subject || '')) {
+    return { ok: false, code: 'behind', extra: '(the newest change on the server is not the version change, so it was not added on top)' };
+  }
+
+  // 2. What GitHub has now, over the same credential. Only FETCH_HEAD is written for it.
+  const fetched = run(`${git} fetch --no-tags ${remote} ${branch}`);
+  if (failedRun(fetched)) return { ok: false, code: 'behind', extra: gitLine(fetched) };
+  const upR = run(`${plain} rev-parse FETCH_HEAD`);
+  const up = out(upR);
+  if (failedRun(upR) || !SHA_RE.test(up)) return { ok: false, code: 'behind', extra: '(could not read what GitHub has)' };
+
+  // Already pinned the same way upstream (the owner bumped it by hand): nothing to add.
+  const same = run(`${plain} diff --quiet ${up} ${sha} -- ${PIN_FILES.join(' ')}`);
+  if (!failedRun(same)) return { ok: true, already: true };
+
+  // 3. Replay in a private scratch worktree, so the live checkout never moves.
+  const base = String(tmpDir || os.tmpdir()).replace(/\\/g, '/').replace(/\/+$/, '');
+  const wt = `${base}/bongos-pin-replay-${slug}-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+  if (!SAFE_PATH_RE.test(wt)) return { ok: false, code: 'failed', extra: '(no safe scratch folder to replay the version change in)' };
+  try {
+    const made = run(`umask 077 && mkdir ${wt}`);
+    const added = failedRun(made) ? made : run(`${plain} worktree add --detach ${wt} ${up}`);
+    if (failedRun(added)) return { ok: false, code: 'failed', extra: gitLine(added) };
+    const at = `git -C ${wt} -c core.hooksPath=/dev/null`;
+    // The pin commit keeps its author and message; its committer stays who committed it on the
+    // box (env, not argv — a name is never shell-interpolated).
+    const who = cn && ce ? { GIT_COMMITTER_NAME: cn, GIT_COMMITTER_EMAIL: ce } : {};
+    const picked = run(`${at} cherry-pick ${sha}`, who);
+    if (failedRun(picked)) {
+      const both = out(run(`${at} diff --name-only --diff-filter=U`)).split('\n').filter(Boolean);
+      run(`${at} cherry-pick --abort`);
+      if (both.length) return { ok: false, code: 'conflict', extra: `(changed on both sides: ${both.join(', ').slice(0, 200)})` };
+      return { ok: false, code: 'failed', extra: gitLine(picked) };
+    }
+    const nextR = run(`${at} rev-parse HEAD`);
+    const next = out(nextR);
+    if (failedRun(nextR) || !SHA_RE.test(next)) return { ok: false, code: 'failed', extra: '(the replayed version change could not be read back)' };
+
+    // 4. A plain fast-forward of GitHub's branch to the replayed commit. A second refusal
+    // (someone pushed in between) is reported, not chased.
+    const pushed = run(`${git} push ${remote} ${next}:refs/heads/${branch}`);
+    if (failedRun(pushed)) return { ok: false, code: pushFault(pushed), extra: gitLine(pushed) };
+    log(`  ✓ GitHub had newer commits: the pin was added on top of them (${next.slice(0, 12)})`);
+    return { ok: true, replayed: true };
+  } finally {
+    // Not --force: the abort above leaves it clean, and the rm + prune catch anything left.
+    run(`${plain} worktree remove ${wt}`);
+    run(`rm -rf ${wt}`);
+    run(`${plain} worktree prune`);
+  }
+}
+
+module.exports = { replayPinCommit };

package/scripts/gds/upgrade-migrate.js

@@ -27,7 +27,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { spawnSync } = require('node:child_process');
+const { spawn, spawnSync } = require('node:child_process');
 
 // Relative to the instance root, POSIX on purpose: it is an argument to bash, and it
 // must stay byte-identical to the scaffold's script (tests/upgrade_migrate.mjs pins it
@@ -161,4 +161,64 @@ function preflightDbIdentity({ instanceDir, db, account = null }, run = spawnSyn
   };
 }
 
-module.exports = { migratePlan, preflightDbIdentity, asAccount, ACCOUNT_RE, CORE_MIGRATE_SCRIPT };
+// ── what a FAILED migrate says, so nobody needs SSH to read it (task 1004734) ────────────
+//
+// Seen 2026-10-14: toast's move 1.21.20 → 1.21.115 rolled back and the hub kept exactly
+// "migrate failed (exit 3)". Exit 3 is psql under ON_ERROR_STOP: ONE statement failed on
+// that project's real data. Which file, and which error, reached only the box's journal,
+// because runMigrate spawned with stdio 'inherit'. migrate.sh prints `apply  <version>`
+// before each file, and psql -f prefixes its ERROR with the file too, so the output
+// already names both; it just never came back.
+//
+// teeSpawn: the child's stdout/stderr are piped and WRITTEN THROUGH as they arrive — the
+// journal still reads live, exactly as under 'inherit' — while the last TEE_TAIL chars are
+// kept for migrateFailureDetail. Async, because a sync spawn cannot write through.
+const TEE_TAIL = 64 * 1024;
+function teeSpawn(cmd, args, opts = {}, { spawnImpl = spawn, out = process.stdout, err = process.stderr } = {}) {
+  return new Promise((resolve) => {
+    let output = '';
+    const keep = (c) => { output = (output + c).slice(-TEE_TAIL); };
+    let child;
+    try { child = spawnImpl(cmd, args, { ...opts, stdio: ['inherit', 'pipe', 'pipe'] }); } catch (e) { resolve({ error: e }); return; }
+    for (const [pipe, sink] of [[child.stdout, out], [child.stderr, err]]) {
+      pipe.setEncoding('utf8');
+      pipe.on('data', (c) => { sink.write(c); keep(c); });
+    }
+    child.on('error', (e) => resolve({ error: e }));
+    child.on('close', (status) => resolve({ status, output }));
+  });
+}
+
+// The failing migration and psql's ERROR line, as " at <file>: ERROR: …" — or '' when the
+// output names neither. Secret-scrubbed (the line is stored on the hub and shown to the
+// owner) and capped. The LAST `apply` line is the file it stopped in: migrate.sh stops at
+// the first failure. PURE.
+const DETAIL_MAX = 300;
+function migrateFailureDetail(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const last = (re) => { for (let i = lines.length - 1; i >= 0; i--) { const m = re.exec(lines[i]); if (m) return m; } return null; };
+  const err = last(/\b((?:ERROR|FATAL):\s+.*)$/);
+  const file = (last(/^apply\s+(\S+)\s*$/) || (err && /^psql:(?:.*[\\/])?([^\\/:]+?)(?:\.sql)?:\d+:/.exec(err.input)) || [])[1] || '';
+  let msg = err ? err[1].trim() : '';
+  if (msg) {
+    // No scrubber, no error text: a credential in a psql line must never reach the hub.
+    try { msg = require('../../modules/security/secret-scrub.js').scrubSecrets(msg); } catch { msg = ''; }
+  }
+  const cap = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+  return (file ? ` at ${cap(file, 80)}` : '') + (msg ? `: ${cap(msg, DETAIL_MAX)}` : '');
+}
+
+/** runMigrate's spawn result → { ok, code, detail } | { ok:false, reason }. PURE. */
+function migrateResult(r) {
+  if (!r || r.error) return { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' };
+  if (r.status === 0) return { ok: true, code: 0 };
+  // r.output from teeSpawn; stdout/stderr from a spawnSync-shaped run (tests, any injected run)
+  return { ok: false, code: r.status, detail: migrateFailureDetail([r.output, r.stdout, r.stderr].filter(Boolean).join('\n')) };
+}
+
+/** The sentence runUpgrade fails with; its "migrate failed" prefix is what upgrade-outcome.js keys on. PURE. */
+function migrateError(mig) {
+  return `migrate failed (${mig.reason || `exit ${mig.code}`})${mig.detail || ''}`;
+}
+
+module.exports = { migratePlan, preflightDbIdentity, asAccount, ACCOUNT_RE, CORE_MIGRATE_SCRIPT, teeSpawn, migrateFailureDetail, migrateResult, migrateError };

package/scripts/gds/upgrade-outcome.js

@@ -63,6 +63,9 @@ const REASON_CLASS = Object.freeze({
   npm_install: 'transient',
   integrity_pin: 'unknown',
   migrate: 'unknown',
+  // a migration's CHECK constraint is broken by rows the project already has (task 1004734): a
+  // retry fails identically and no remedy may rewrite the owner's data, so a person decides.
+  migrate_check_violation: 'unknown',
   restart: 'unknown',
   health: 'unknown',
   // the runner's one automatic fix did not clear it, or itself failed (task 1004448)
@@ -86,6 +89,7 @@ const UPGRADE_REASONS = [
   [/^(--registry and --from|--from tarball not found|no core tarball at)/, 'core_source'],
   [/^npm install failed/, 'npm_install'],
   [/^integrity pin/, 'integrity_pin'],
+  [/^migrate failed .*\bERROR: .*check constraint/, 'migrate_check_violation'], // upgrade-migrate.js migrateError (task 1004734)
   [/^migrate failed/, 'migrate'],
   [/^restart failed/, 'restart'],
   [/^(health check failed after restart|served core version did not change)/, 'health'],

package/scripts/gds/upgrade.js

@@ -33,7 +33,7 @@ const { parseSemver, compareSemver, isStable, listAvailableVersions } = require(
 const { checkArtistGate } = require('./upgrade-artist-gate');
 // The database side of a move: which command migrates, as which account, and whether that
 // account can reach the database (tasks 1004274, 1002712, 1004512).
-const { preflightDbIdentity, asAccount, ACCOUNT_RE } = require('./upgrade-migrate');
+const { preflightDbIdentity, asAccount, ACCOUNT_RE, teeSpawn, migrateResult, migrateError } = require('./upgrade-migrate');
 
 const CORE_PKG = '@bongos/core';
 const ARTIFACT = 'bongos-core';
@@ -519,13 +519,13 @@ function npmInstall(instanceDir, run = spawnSync) {
   return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
 }
 
-function runMigrate(instanceDir, run = spawnSync, account = null) {
+async function runMigrate(instanceDir, run = spawnSync, account = null) {
   const { cmd, args, env } = require('./upgrade-migrate').migratePlan(instanceDir); // its own migrate script, else the core's migrate.sh (task 1004274)
   // `account`: the project's own unix+Postgres identity when the move itself is running as
   // the account that owns the CHECKOUT instead (--migrate-as; upgrade-migrate.js, task 1004512).
   const q = asAccount(account, cmd, args, env ? { INIT_CWD: instanceDir } : {});
-  const r = run(q.cmd, q.args, { cwd: instanceDir, stdio: 'inherit', ...(env ? { env } : {}) });
-  return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
+  // TEED, not inherited: still streams live, and a failure names its migration + psql's ERROR line (upgrade-migrate.js, task 1004734)
+  return migrateResult(await (run === spawnSync ? teeSpawn : run)(q.cmd, q.args, { cwd: instanceDir, ...(env ? { env } : {}) }));
 }
 
 // WHICH database will migrate target? (task 1002755)
@@ -1224,9 +1224,9 @@ async function runUpgrade(opts, deps = {}) {
 
   // 4. migrate (additive core_* migrations).
   if (!opts.skipMigrate) {
-    const mig = runMigrate(instanceDir, run, opts.migrateAs || null);
+    const mig = await runMigrate(instanceDir, run, opts.migrateAs || null);
     if (!mig.ok) {
-      const error = `migrate failed (${mig.reason || 'exit ' + mig.code})`;
+      const error = migrateError(mig); // names the failing migration + its ERROR line (task 1004734)
       if (rollbackOnFailure && snapshot) {
         const rb = await doRollback('migrate failed');
         return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.115'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.117'; // 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('discord'); log.info('mounted');

package/tests/core_upgrade_runner.mjs

@@ -1551,6 +1551,21 @@ await t('a real rollback says rolled back', async () => {
   assert.match(r.error, /failed and was rolled back/);
 });
 
+await t('a failed migrate reaches the stored failure with its migration and psql\'s ERROR line (task 1004734)', async () => {
+  // upgrade.js's REAL migrate result → its real error sentence → its real outcome line, in the
+  // frame its main() writes to stderr (pinned by "upgrade.js ends a failed run…" below).
+  const run = () => ({ status: 3, stdout: 'apply  core_998_ok\napply  core_999_x\n',
+    stderr: 'psql:migrations/core_999_x.sql:7: ERROR:  check constraint "tasks_kind_check" of relation "tasks" is violated by some row\n' });
+  const mig = await U.runMigrate(fs.mkdtempSync(path.join(require('node:os').tmpdir(), 'mig-')), run);
+  const res = { ok: false, error: require('../scripts/gds/upgrade-migrate.js').migrateError(mig), rolledBack: true, rollback: {} };
+  const stderr = `\n✖ ${res.error}\n${require('../scripts/gds/upgrade-outcome.js').outcomeLine(res)}`;
+  const r = await R.coreUpgradeInstance(inst(), upgradeThrows(stderr)(makeDeps()), intent());
+  assert.deepEqual(r.failure, { class: 'unknown', reason: 'migrate_check_violation' });
+  assert.match(r.error, /failed and was rolled back/);
+  assert.match(r.error, /core_999_x/, 'the stored sentence names the migration');
+  assert.match(r.error, /ERROR: +check constraint "tasks_kind_check" of relation "tasks" is violated by some row/, 'and psql\'s own error');
+});
+
 await t('a FAILED rollback is its own outcome, and terminal — never retried unattended', async () => {
   const d = upgradeThrows('\n✖ health check failed after restart\nBONGOS_UPGRADE_OUTCOME {"stage":"rollback_failed","reason":"rollback_failed"}\n')(makeDeps());
   const r = await R.coreUpgradeInstance(inst(), d, intent());

package/tests/fitness_installed_core.mjs

@@ -0,0 +1,127 @@
+// tests/fitness_installed_core.mjs — fitness.js in a project that INSTALLS the core
+// (task 1004737).
+//
+// There the core sits at <project>/node_modules/@bongos/core: not a git checkout of its
+// own, just an ignored folder inside the project's repo. Every fitness check guards the
+// core's own source and enumerates it with git, so each scan found nothing and either
+// threw ("docs-entropy: scan defect — enumerated 0 tracked markdown files") or reported
+// a scan defect — `bongos exec scripts/gds/fitness.js` crashed on toast, on 1.21.20 and
+// again on 1.21.115. The core repo's CI already ran this gate before publishing, so in an
+// installed core it steps aside, and says so.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const lib = require(path.join(ROOT, 'scripts', 'gds', 'fitness-lib.js'));
+
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+function tempDir(t) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fitness-installed-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+test('isInstalledCore: yes only for a core under node_modules that is not its own checkout', (t) => {
+  const base = tempDir(t);
+  const repo = path.join(base, 'project');
+  const nested = path.join(repo, 'node_modules', '@bongos', 'core');
+  const vendored = path.join(repo, 'vendor', 'core');
+  const looseInstalled = path.join(base, 'bare', 'node_modules', '@bongos', 'core');
+  const loose = path.join(base, 'loose');
+  for (const d of [nested, vendored, looseInstalled, loose]) fs.mkdirSync(d, { recursive: true });
+  git(repo, 'init', '-q');
+  assert.equal(lib.isInstalledCore(nested), true, 'an installed package inside a project repo is installed');
+  assert.equal(lib.isInstalledCore(looseInstalled), true, 'so is one under node_modules with no repo around it');
+  assert.equal(lib.isInstalledCore(ROOT), false, 'this checkout (main or a worktree) is not — the gate keeps running here');
+  assert.equal(lib.isInstalledCore(repo), false, 'nor is the root of any checkout');
+});
+
+// The grader's finding on the first cut: deciding "installed" from a git FAILURE let any git
+// trouble in the core's own checkout (git off PATH, no .git, a misresolved root) skip the whole
+// gate — rank guards and the core/host boundary included — and go green. Outside node_modules
+// the answer is now no regardless of git, so those trees run every check and fail closed.
+test('isInstalledCore: a git failure or a nested folder OUTSIDE node_modules never reads as installed (fail closed)', (t) => {
+  const base = tempDir(t);
+  const repo = path.join(base, 'project');
+  const vendored = path.join(repo, 'vendor', 'core');
+  const loose = path.join(base, 'loose');
+  fs.mkdirSync(vendored, { recursive: true });
+  fs.mkdirSync(loose);
+  git(repo, 'init', '-q');
+  assert.equal(lib.isInstalledCore(loose), false, 'no repo at all (git fails) outside node_modules: run the checks');
+  assert.equal(lib.isInstalledCore(vendored), false, 'a folder inside another repo but not under node_modules: run the checks');
+  assert.equal(lib.isInstalledCore(path.join(base, 'does-not-exist')), false, 'a misresolved root: run the checks');
+  const savedPath = process.env.PATH;
+  process.env.PATH = '';
+  try {
+    assert.equal(lib.isInstalledCore(ROOT), false, 'git missing from PATH in the core checkout: run the checks');
+  } finally {
+    process.env.PATH = savedPath;
+  }
+});
+
+test('runChecks: in the core\'s own checkout every check runs, and a throw still crashes (fail closed)', () => {
+  const ran = [];
+  const out = lib.runChecks([() => { ran.push(1); return { hardFail: false }; }, () => { ran.push(2); return { hardFail: true }; }], { installed: false });
+  assert.deepEqual(ran, [1, 2]);
+  assert.equal(out.length, 2);
+  assert.throws(() => lib.runChecks([() => { throw new Error('scan defect'); }], { installed: false }), /scan defect/);
+});
+
+test('runChecks: in an installed core no check runs, and one non-failing result says why', () => {
+  let ran = 0;
+  const out = lib.runChecks([() => { ran++; throw new Error('scan defect'); }, () => { ran++; return { hardFail: true }; }], { installed: true });
+  assert.equal(ran, 0, 'no check is run against a tree with no core source in it');
+  assert.equal(out.length, 1);
+  assert.equal(out[0].hardFail, false);
+  assert.match(out[0].name, /skipped/);
+  assert.match(out[0].name, /installed package/);
+  assert.ok(out[0].warnings.length > 0, 'the skip surfaces as a warning, not a silent pass');
+  assert.match(out[0].note, /2 checks/, 'and counts what it did not run');
+});
+
+test('end to end: fitness.js run from <project>/node_modules/@bongos/core exits 0 with the skip, instead of crashing', (t) => {
+  const project = tempDir(t);
+  const core = path.join(project, 'node_modules', '@bongos', 'core');
+  // The working tree as the package would ship it (tracked + new files), copied — not
+  // linked — so git inside it answers for the PROJECT, exactly as on toast.
+  const files = git(ROOT, 'ls-files', '-z', '--cached', '--others', '--exclude-standard').split('\0').filter(Boolean);
+  for (const f of files) {
+    const src = path.join(ROOT, f);
+    let st;
+    try { st = fs.lstatSync(src); } catch { continue; } // deleted in the working tree
+    if (!st.isFile()) continue;
+    fs.mkdirSync(path.dirname(path.join(core, f)), { recursive: true });
+    fs.copyFileSync(src, path.join(core, f));
+  }
+  fs.writeFileSync(path.join(project, '.gitignore'), 'node_modules\n');
+  fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# project\n');
+  git(project, 'init', '-q');
+  git(project, 'add', '-A');
+  git(project, '-c', 'user.email=t@example.com', '-c', 'user.name=t', 'commit', '-qm', 'init');
+
+  let out = '';
+  let status = 0;
+  try {
+    out = execFileSync(process.execPath, [path.join(core, 'scripts', 'gds', 'fitness.js')], {
+      cwd: project,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, NODE_PATH: path.join(ROOT, 'node_modules') },
+    });
+  } catch (e) {
+    status = e.status;
+    out = `${e.stdout || ''}${e.stderr || ''}`;
+  }
+  assert.equal(status, 0, `fitness must not fail an installed core's project:\n${out.slice(0, 2000)}`);
+  assert.match(out, /skipped: the core here is an installed package/);
+  assert.doesNotMatch(out, /scan defect/);
+});

package/tests/instance_db_migrated_on_code_move.mjs

@@ -32,7 +32,7 @@ const tenant = { slug: 'charter', db_name: 'charter_db', hosting_shape: 'co-tena
 
 test('bongos upgrade migrates before it restarts, and only --skip-migrate opts out', () => {
   const src = fs.readFileSync(path.join(ROOT, 'scripts/gds/upgrade.js'), 'utf8');
-  const migrate = src.indexOf('const mig = runMigrate(instanceDir, run, opts.migrateAs || null);');
+  const migrate = src.indexOf('const mig = await runMigrate(instanceDir, run, opts.migrateAs || null);'); // async since task 1004734 (teed output)
   const restart = src.lastIndexOf('restartService({ service: opts.service, restartCmd: opts.restartCmd }');
   assert.ok(migrate > 0, 'the upgrade flow runs migrate');
   assert.ok(restart > migrate, 'the restart that makes new code live comes AFTER migrate');
@@ -47,7 +47,7 @@ test('bongos upgrade migrates before it restarts, and only --skip-migrate opts o
   // provisioned since task 1003369, and the wrong one cannot connect at all: the project's
   // database is owned by its own Postgres login role with CONNECT revoked from PUBLIC.
   // Asserting the CALL SITE, not just the helper — the helper was never the gap.
-  assert.match(src, /const mig = runMigrate\(instanceDir, run, opts\.migrateAs \|\| null\);/,
+  assert.match(src, /const mig = await runMigrate\(instanceDir, run, opts\.migrateAs \|\| null\);/,
     'the migrate step is handed --migrate-as, not left on whoever the move happens to be');
   assert.equal(`bash ${CORE_MIGRATE_SCRIPT}`, INSTANCE_MIGRATE_SCRIPT, 'migrate is the instance scaffold script, i.e. the core migrate.sh');
 });