@bongos/core 1.21.13 → 1.21.15

package/scripts/gds/autobongos-run.js

@@ -207,10 +207,22 @@ async function pickTask(goals, deps = {}) {
     // AFTER ordering, so a dependent of one is still halted by its own unmet
     // dependency rather than promoted by the task's absence.
     const exclude = deps.exclude || null;
-    const open = exclude && exclude.size ? order.filter((t) => !exclude.has(String(t.id))) : order;
+    const unexcluded = exclude && exclude.size ? order.filter((t) => !exclude.has(String(t.id))) : order;
+    // Work this machine structurally cannot do — SSH, root, systemd on a live
+    // host (task 1004537) — is skipped BEFORE the claim, and listed with its
+    // reason. It is decided here and not in sequence.js's matrix because the
+    // matrix also serves /builder-sequence, where the builder may well hold the
+    // host access an unattended runner never has.
+    const hostSkipped = [];
+    const open = unexcluded.filter((t) => {
+      const host = fence.needsHostAccess(t);
+      if (!host.needs) return true;
+      hostSkipped.push({ id: t.id, title: t.title, reasons: [{ code: 'needs_host_access', detail: `${fence.REFUSALS.needs_host_access} (${host.signals.join('; ')})` }] });
+      return false;
+    });
     const { next, skipped } = seq.pickNext(open, { rank, claimableIds });
-    if (next) return { task: next, goalId, skipped };
-    for (const sk of skipped) allSkipped.push({ ...sk, goal_id: goalId });
+    if (next) return { task: next, goalId, skipped: [...hostSkipped, ...skipped] };
+    for (const sk of [...hostSkipped, ...skipped]) allSkipped.push({ ...sk, goal_id: goalId });
   }
   return { none: true, skipped: allSkipped };
 }

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

@@ -319,8 +319,8 @@ async function coreUpgradeInstance(inst, deps, intent) {
   // The preview probes; the move must probe identically or the two commands diverge on
   // the one field task 1004121 exists to keep identical. Skipped when !apply, where the
   // command is printed and never run — a plan should not spend a subprocess per tick.
-  const { runAs } = resolveRunAs(inst, deps, { probe: apply });
-  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, requestedBy, selfRoot, runAs });
+  const { runAs, migrateAs } = resolveRunAs(inst, deps, { probe: apply });
+  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, requestedBy, selfRoot, runAs, migrateAs });
 
   if (!apply) {
     // A --dry-run runner tick used to only PRINT this command. It now runs the CLI's own
@@ -571,7 +571,24 @@ function parsePreflight(out) {
 }
 
 /**
- * Which unix account should this instance's upgrade run as? Asks the box (task 1004128).
+ * Which unix accounts does this instance's upgrade need? Asks the box (task 1004128).
+ *
+ * TWO ANSWERS, NOT ONE (task 1004512). Task 1004128 asked a single question — "which
+ * account does this instance run as?" — and ran the WHOLE move as it. That is right for
+ * the database and wrong for the files, and the two have different owners on every
+ * project provisioned since task 1003369:
+ *
+ *   • `runAs` — the account that owns the CHECKOUT, which is the app user on every
+ *     hosting shape (provision-repo.js scaffolds /srv/<base>/<slug> as the runner, and
+ *     grantInstanceRepoReadCmd gives the project's own account group READ, nothing more).
+ *     Everything the move writes — the pin, node_modules, .claude/, the pin commit — and
+ *     the `git status` it starts with, belong to this account. Running them as the
+ *     project's account is what made every such move die on `fatal: detected dubious
+ *     ownership in repository` and report a dirty tree that did not exist.
+ *   • `migrateAs` — the project's OWN account, which is also its Postgres login role
+ *     (provision-repo.js instanceDbRole); its database is owned by that role with CONNECT
+ *     revoked from PUBLIC, so this is the only identity that can migrate it. That is where
+ *     the isolation of task 1003369 actually lives, and it is kept.
  *
  * The fleet is heterogeneous: instances provisioned before task 1003369 run as the
  * shared app user, instances provisioned after run as their own `bongos-<slug>`. Neither
@@ -580,13 +597,15 @@ function parsePreflight(out) {
  * tenant leg has been broken.
  *
  * Falling back is NOT a privilege escalation: an instance with no account of its own is
- * already running as the app user (its unit says so), so this runs the upgrade as precisely
- * the account that owns the files and the database it is about to touch. It IS reported,
- * because a missing per-instance account is a provisioning gap someone should close, and
- * a silent fallback would hide it forever.
+ * already running as the app user (its unit says so), so this migrates as precisely the
+ * account that owns the database it is about to touch. It IS reported, because a missing
+ * per-instance account is a provisioning gap someone should close, and a silent fallback
+ * would hide it forever. On that shape the two answers coincide and the move is byte-for-
+ * byte what it was before this task.
  */
 function resolveRunAs(inst, deps, { probe: allowProbe = true } = {}) {
-  if (inst.hosting_shape === 'control-plane') return { runAs: appUser(), fellBack: false };
+  const owner = appUser(); // owns the checkout on every shape — see above
+  if (inst.hosting_shape === 'control-plane') return { runAs: owner, migrateAs: owner, fellBack: false };
   // Re-checked HERE rather than left to instanceUser()'s own throw, for the reason
   // upgradeInvocation states about itself: a call site whose safety depends on a
   // helper's internals is one refactor away from a shell-interpolation path.
@@ -594,7 +613,7 @@ function resolveRunAs(inst, deps, { probe: allowProbe = true } = {}) {
     throw new Error(`resolveRunAs: refusing to probe an account for invalid slug ${JSON.stringify(inst && inst.slug)}`);
   }
   const wanted = instanceUser(inst);
-  if (!allowProbe) return { runAs: wanted, fellBack: false };
+  if (!allowProbe) return { runAs: owner, migrateAs: wanted, fellBack: false };
   // THE SAME EXECUTOR THE UPGRADE ITSELF WILL USE. Every sibling here picks
   // `standalone ? (controlExec || exec) : exec`, because under PROVISION_REMOTE_HOST
   // (ADR 0130) `exec` is the REMOTE ssh executor while `controlExec` stays local. A
@@ -604,7 +623,7 @@ function resolveRunAs(inst, deps, { probe: allowProbe = true } = {}) {
   const boxExec = inst.hosting_shape === 'cloud-host' ? (deps.controlExec || deps.exec) : deps.exec;
   const r = boxExec(`id -u ${wanted}`, { allowFail: true });
   const failed = !r || r.softFailed === true || r.ok === false;
-  if (!failed) return { runAs: wanted, fellBack: false };
+  if (!failed) return { runAs: owner, migrateAs: wanted, fellBack: false };
   // ONLY A DEFINITIVE "no such user" JUSTIFIES THE FALLBACK. A probe that could not
   // answer — an exec timeout, an NSS hiccup — must not silently narrow the per-instance
   // isolation of task 1003369 for this operation. So an inconclusive probe keeps the
@@ -612,9 +631,9 @@ function resolveRunAs(inst, deps, { probe: allowProbe = true } = {}) {
   // task a failure now carries the reason instead of "the dry run did not complete".
   const said = `${(r && r.stdout) || ''}\n${(r && r.stderr) || ''}`;
   if (!/no such user|unknown user/i.test(said)) {
-    return { runAs: wanted, fellBack: false, probeInconclusive: true };
+    return { runAs: owner, migrateAs: wanted, fellBack: false, probeInconclusive: true };
   }
-  return { runAs: appUser(), fellBack: true, wanted };
+  return { runAs: owner, migrateAs: owner, fellBack: true, wanted };
 }
 
 // ONE BUILDER FOR BOTH LEGS (task 1004121).
@@ -630,7 +649,7 @@ function resolveRunAs(inst, deps, { probe: allowProbe = true } = {}) {
 // HERE rather than left to instanceUser()'s own throw: that throw is correct today, but
 // a call site whose safety depends on a helper's internals is one refactor away from a
 // shell-injection path (and the apply leg's own guard sits at the route, not here).
-function upgradeInvocation(inst, to, { privileged = false, dryRun = false, requestedBy = '', selfRoot = selfInstanceRoot, runAs = null } = {}) {
+function upgradeInvocation(inst, to, { privileged = false, dryRun = false, requestedBy = '', selfRoot = selfInstanceRoot, runAs = null, migrateAs = null } = {}) {
   if (!isValidSlug(inst && inst.slug)) {
     throw new Error(`upgradeInvocation: refusing to build a shell command from an invalid slug ${JSON.stringify(inst && inst.slug)}`);
   }
@@ -665,11 +684,22 @@ function upgradeInvocation(inst, to, { privileged = false, dryRun = false, reque
   // (resolveRunAs below) instead of either side assuming. Passing it in keeps this
   // builder pure; the default preserves the old derivation for callers that have not
   // probed.
-  const account = runAs || (inst.hosting_shape === 'control-plane' ? appUser() : instanceUser(inst));
+  //
+  // AND WHICH ACCOUNT DOES WHAT (task 1004512). `account` runs the move; `dbAccount` runs
+  // its three database steps. They differ on exactly the projects that have an account of
+  // their own, because the checkout is the app user's and the database is theirs —
+  // resolveRunAs above argues the split. `--migrate-as` is emitted ONLY when they differ,
+  // so a control plane and a pre-1003369 project produce the command they always did.
+  const account = runAs || appUser();
+  const dbAccount = migrateAs || (inst.hosting_shape === 'control-plane' ? appUser() : instanceUser(inst));
   const sudoP = privileged ? `sudo -u ${account} env PGDATABASE=${dbName(inst)} ` : '';
   const cli = path.posix.join('scripts', 'gds', 'upgrade.js');
   const shared = [`${sudoP}node ${cli}`, '--registry', `--to ${to}`,
-    instanceDir === REPO_ROOT ? '' : `--instance ${instanceDir}`];  // REPO_ROOT is where the CLI runs (runDir below)
+    instanceDir === REPO_ROOT ? '' : `--instance ${instanceDir}`,  // REPO_ROOT is where the CLI runs (runDir below)
+    // SHARED, not in the tail: the dry run's own database pre-check connects as this
+    // account too, so a preview that omitted it would test a different identity than the
+    // move — the exact drift one builder for both legs exists to prevent.
+    dbAccount === account ? '' : `--migrate-as ${dbAccount}`];
   const tail = dryRun
     ? ['--dry-run']
     : [`--service ${inst.slug}`,
@@ -681,7 +711,7 @@ function upgradeInvocation(inst, to, { privileged = false, dryRun = false, reque
       hubPushesPin(inst) ? '--pin-no-push' : '',
       requestedBy ? `--requested-by ${requestedBy}` : '',
       requestedBy ? '--upgrade-source owner-control' : ''];
-  return { cmd: [...shared, ...tail].filter(Boolean).join(' '), runDir: REPO_ROOT, instanceDir, runAs: account };
+  return { cmd: [...shared, ...tail].filter(Boolean).join(' '), runDir: REPO_ROOT, instanceDir, runAs: account, migrateAs: dbAccount };
 }
 
 // Ask the upgrade CLI what it WOULD do, changing nothing. `allowFail` because a refusal
@@ -692,8 +722,8 @@ function preflightUpgrade(inst, to, deps) {
   // A distinct local name: `deps.selfInstanceRoot || selfInstanceRoot` with a const of
   // the same name would TDZ-shadow the import and crash every uninjected call.
   const selfRoot = deps.selfInstanceRoot || selfInstanceRoot;
-  const { runAs, fellBack, wanted } = resolveRunAs(inst, deps);
-  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, dryRun: true, selfRoot, runAs });
+  const { runAs, migrateAs, fellBack, wanted } = resolveRunAs(inst, deps);
+  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, dryRun: true, selfRoot, runAs, migrateAs });
   const r = boxExec(cmd, { cwd: runDir, allowFail: true });
   const out = `${(r && r.stdout) || ''}\n${(r && r.stderr) || ''}`;
   const { checks, error } = parsePreflight(out);
@@ -709,10 +739,12 @@ function preflightUpgrade(inst, to, deps) {
   const raw = out.trim().split('\n').filter(Boolean).slice(-4).join('\n').slice(0, 600);
   const why = error || (raw || null);
   const note = fellBack
-    ? `ran as ${runAs} — this instance has no ${wanted} account yet (it predates the per-instance account model)`
+    ? `migrated as ${migrateAs} — this instance has no ${wanted} account yet (it predates the per-instance account model)`
     : null;
   return {
-    target: to, ok, lines: checks, ran_as: runAs, account_note: note,
+    // Both accounts, because since task 1004512 there are two and "which user did this run
+    // as" has no single answer: `ran_as` writes the files, `migrated_as` touches the database.
+    target: to, ok, lines: checks, ran_as: runAs, migrated_as: migrateAs, account_note: note,
     error: ok ? null : (why || 'the dry run did not complete, and said nothing this could report'),
   };
 }

package/scripts/gds/upgrade-migrate.js

@@ -1,8 +1,9 @@
 'use strict';
 
-// scripts/gds/upgrade-migrate.js — WHICH command `bongos upgrade` migrates an instance
-// with (task 1004274, found preparing the task 1004047 catch-up pass). Kept out of
-// upgrade.js, which sits at the 1500-line cap.
+// scripts/gds/upgrade-migrate.js — the DATABASE side of a core move: which command
+// migrates this instance (task 1004274, found preparing the task 1004047 catch-up pass),
+// WHICH ACCOUNT that command runs as, and whether that account can reach the database at
+// all (task 1004512). Kept out of upgrade.js, which sits at the 1500-line cap.
 //
 // THE GAP. upgrade.js migrated with `npm run migrate`, and that only works where the
 // instance's package.json DECLARES a migrate script. A greenfield scaffold always does
@@ -26,6 +27,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { 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
@@ -64,4 +66,99 @@ function migratePlan(instanceDir, { fsImpl = fs, env = process.env } = {}) {
   };
 }
 
-module.exports = { migratePlan, CORE_MIGRATE_SCRIPT };
+// ---- which ACCOUNT the database work runs as (task 1004512) -----------------
+//
+// THE BUG THIS EXISTS FOR. A core move on a project provisioned since task 1003369 ran
+// the WHOLE of upgrade.js as the project's own `bongos-<slug>` account. That account only
+// READS the checkout (provision-repo.js grantInstanceRepoReadCmd adds it to the app user's
+// group; /srv/<base>/<slug> is owned by the app user), so the move died at its very first
+// step: `git status` refused with `fatal: detected dubious ownership in repository`, the
+// clean-tree pre-flight reported "working tree not clean", and the self-heal chain
+// committed a tree that was never dirty and retried into the identical failure. Every move
+// on such a project ended in a blocker, and the dirt it named did not exist. Had git been
+// appeased, `npm install`, the pin commit and the .claude materialization — all WRITES to a
+// checkout that account cannot write — would have failed next.
+//
+// SO THE MOVE IS SPLIT, rather than papered over with a `safe.directory` entry:
+//   • everything that touches the CHECKOUT runs as the account that owns it (the app
+//     user) — that is also what pushUpgradePin and the wedge remedy's `git` already do;
+//   • everything that touches the DATABASE runs as the project's own account, which is
+//     where the isolation actually lives: it is the project's Postgres login role
+//     (provision-repo.js instanceDbRole), the database is owned by it, and CONNECT is
+//     revoked from PUBLIC — so the app user cannot reach it even by accident.
+//
+// The runner passes `--migrate-as <account>` ONLY when the two differ. A control plane and
+// a project old enough to still run as the app user emit no flag and behave exactly as
+// they did before, which is the half of the fleet that was already working.
+//
+// Narrower than a unix account name may legally be, on purpose: the value arrives on a
+// command line and is refused rather than quoted if it falls outside. ONE copy for the
+// upgrade CLI — wedge-remedy.js imports this rather than re-declaring it, because two
+// copies of a security predicate drift one edit at a time. provision-repo.js keeps its own
+// UNIX_ACCOUNT_RE: that file is the control-plane provisioner and nothing it does should
+// depend on the upgrade CLI, so the duplication there buys a layer boundary.
+const ACCOUNT_RE = /^[a-z_][a-z0-9_-]{0,31}$/;
+
+/**
+ * `cmd args` as `account`, or unchanged when there is no account to drop to. PURE.
+ *
+ * argv form, never a shell string, so nothing here is quoted or interpolated. `sudo -n`
+ * because a sudoers rule that would PROMPT must fail fast: an upgrade runs unattended and
+ * a password prompt nobody can answer would hang the deploy rather than fail it.
+ *
+ * sudo resets the environment, so the variables migrate genuinely needs are re-stated as
+ * `env K=V` arguments: PGDATABASE (migrate.sh defaults to production when it is unset, so
+ * it is always passed and never inherited) and, for the core-script fallback, INIT_CWD
+ * (which is how migrate.sh finds the instance — task 2180).
+ */
+function asAccount(account, cmd, args, extraEnv = {}, env = process.env) {
+  if (!account) return { cmd, args };
+  if (!ACCOUNT_RE.test(String(account))) throw new Error(`asAccount: ${JSON.stringify(account)} is not a unix account name`);
+  const carry = { ...(env.PGDATABASE ? { PGDATABASE: env.PGDATABASE } : {}), ...extraEnv };
+  const pairs = Object.entries(carry).map(([k, v]) => `${k}=${v}`);
+  return { cmd: 'sudo', args: ['-n', '-u', account, 'env', ...pairs, cmd, ...args] };
+}
+
+// migrate.sh reaches Postgres over the local socket as the CURRENT OS USER (peer
+// auth) — so running an upgrade under `sudo` connects as `root`, which usually has
+// no Postgres role. The failure surfaces mid-run as a raw
+// `FATAL: role "root" does not exist`, AFTER the pin has already moved, which then
+// triggers the whole auto-rollback dance for what is really an operator mistake.
+// This names it up front instead (task 1002712). `account` (task 1004512) makes the
+// probe connect as whoever migrate will, so the pre-flight and the migration cannot
+// disagree about which role is being tested.
+function preflightDbIdentity({ instanceDir, db, account = null }, run = spawnSync) {
+  const q = asAccount(account, 'psql', ['-tAc', 'select 1'], db ? { PGDATABASE: db } : {});
+  const r = run(q.cmd, q.args, {
+    cwd: instanceDir, encoding: 'utf8',
+    env: { ...process.env, ...(db ? { PGDATABASE: db } : {}) },
+  });
+  if (!r || r.error) return { ok: true, skipped: 'psql not on PATH — leaving it to migrate' };
+  if (r.status === 0) return { ok: true };
+
+  const out = `${r.stderr || ''}${r.stdout || ''}`;
+  // The escalation itself not working is this pre-flight's business, not migrate's (task
+  // 1004512). Soft-skipping it would let the pin move and then fail at migrate for the one
+  // reason that was knowable up front, costing a full rollback — the exact shape the
+  // role-does-not-exist check below exists to avoid. Only ever reachable with an account.
+  if (account && /^sudo:/m.test(out)) {
+    return { ok: false, reason: `the database steps cannot run as "${account}" — sudo refused.\n`
+      + `    ${out.trim().split('\n').find((l) => l.startsWith('sudo:')) || ''}\n`
+      + `    The move writes files as the account that owns the checkout and hands only the\n`
+      + `    database to the project's own account (--migrate-as), so the first needs\n`
+      + `    passwordless sudo to the second. Checked BEFORE the pin moves.` };
+  }
+  const m = out.match(/role "([^"]+)" does not exist/i);
+  if (!m) return { ok: true, skipped: 'psql failed for another reason — leaving it to migrate' };
+  return {
+    ok: false,
+    role: m[1],
+    reason: `Postgres has no role "${m[1]}" — migrate would fail after the pin moved.\n`
+      + `    migrate.sh connects over the local socket as the CURRENT OS USER. Running the\n`
+      + `    upgrade under sudo connects as root, which is almost never a Postgres role.\n`
+      + `    Re-run as the user that owns the instance (e.g. sudo -u <owner> …), passing the\n`
+      + `    npm token through if the core comes from the registry.`,
+  };
+}
+
+module.exports = { migratePlan, preflightDbIdentity, asAccount, ACCOUNT_RE, CORE_MIGRATE_SCRIPT };

package/scripts/gds/upgrade-outcome.js

@@ -45,6 +45,11 @@ const REASON_CLASS = Object.freeze({
   schema_pending: 'known_wedge', // the database is behind the code it runs NOW (task 1004448)
   // upgrade.js refusals, before the pin moves
   dirty_tree: 'known_wedge',
+  // git REFUSED to read the checkout, so nothing is known about the tree (task 1004512).
+  // Deliberately NOT known_wedge: the dirty_tree remedy commits whatever git reports, and
+  // here git reported nothing — the live shape is `detected dubious ownership`, a tree that
+  // was never dirty. The fix is which ACCOUNT the move runs as, which no remedy can apply.
+  git_unreadable: 'unknown',
   downgrade: 'needs_decision',
   artist_gate: 'needs_decision',
   module_incompatible: 'needs_decision',
@@ -73,6 +78,7 @@ const UPGRADE_REASONS = [
   [/no space left on device|ENOSPC/i, 'disk_full'],
   [/^refusing to DOWNGRADE/, 'downgrade'],
   [/^already on /, 'already_on'],
+  [/^git could not read the working tree/, 'git_unreadable'],
   [/^working tree not clean/, 'dirty_tree'],
   [/^module pre-check failed/, 'module_incompatible'],
   [/^cannot determine which database/, 'db_unresolvable'],

package/scripts/gds/upgrade.js

@@ -31,6 +31,9 @@ const { spawnSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
 const { parseSemver, compareSemver, isStable, listAvailableVersions } = require('./update-channel');
 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 CORE_PKG = '@bongos/core';
 const ARTIFACT = 'bongos-core';
@@ -130,7 +133,14 @@ function restorePin(instanceDir, depString, fsImpl = fs) {
 // `ignore` is waived (it comes from — and is argued for in — claude-materialize.js materializeWillRewrite, task 1004122); every OTHER dirty path still halts the bump. -uall (task 1004188): a bare status collapses a NEW untracked dir to one '?? dir/' entry the file-path waiver never matches.
 function gitTreeClean(instanceDir, run = spawnSync, ignore = []) {
   const r = run('git', ['status', '--porcelain', '-uall'], { cwd: instanceDir, encoding: 'utf8' });
-  if (!r || r.error || r.status !== 0) return { ok: false, reason: 'git status failed (not a git repo?)' };
+  // git's OWN words, not a guess at them (task 1004512). `not a git repo?` was the only
+  // explanation ever offered, and the failure that actually happens in the field is
+  // `detected dubious ownership` — a repo git can see perfectly well and refuses to read
+  // for the account asking. Swallowing the reason is what let that read as dirt.
+  if (!r || r.error || r.status !== 0) {
+    const said = String((r && (r.stderr || r.stdout)) || (r && r.error && r.error.message) || '').trim().split('\n').slice(0, 4).join('\n');
+    return { ok: false, reason: said || 'git status failed (not a git repo?)' };
+  }
   const skip = new Set(ignore), all = (r.stdout || '').split('\n').filter((l) => l.trim());
   const kept = all.filter((l) => !skip.has(l.slice(3).trim()));
   return { ok: !kept.length, dirty: kept.join('\n'), ignored: all.length - kept.length };
@@ -509,37 +519,12 @@ 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 };
 }
 
-// migrate.sh reaches Postgres over the local socket as the CURRENT OS USER (peer
-// auth) — so running an upgrade under `sudo` connects as `root`, which usually has
-// no Postgres role. The failure surfaces mid-run as a raw
-// `FATAL: role "root" does not exist`, AFTER the pin has already moved, which then
-// triggers the whole auto-rollback dance for what is really an operator mistake.
-// This names it up front instead (task 1002712).
-function preflightDbIdentity({ instanceDir, db }, run = spawnSync) {
-  const r = run('psql', ['-tAc', 'select 1'], {
-    cwd: instanceDir, encoding: 'utf8',
-    env: { ...process.env, ...(db ? { PGDATABASE: db } : {}) },
-  });
-  if (!r || r.error) return { ok: true, skipped: 'psql not on PATH — leaving it to migrate' };
-  if (r.status === 0) return { ok: true };
-
-  const out = `${r.stderr || ''}${r.stdout || ''}`;
-  const m = out.match(/role "([^"]+)" does not exist/i);
-  if (!m) return { ok: true, skipped: 'psql failed for another reason — leaving it to migrate' };
-  return {
-    ok: false,
-    role: m[1],
-    reason: `Postgres has no role "${m[1]}" — migrate would fail after the pin moved.\n`
-      + `    migrate.sh connects over the local socket as the CURRENT OS USER. Running the\n`
-      + `    upgrade under sudo connects as root, which is almost never a Postgres role.\n`
-      + `    Re-run as the user that owns the instance (e.g. sudo -u <owner> …), passing the\n`
-      + `    npm token through if the core comes from the registry.`,
-  };
-}
-
-function runMigrate(instanceDir, run = spawnSync) {
+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)
-  const r = run(cmd, args, { cwd: instanceDir, stdio: 'inherit', ...(env ? { env } : {}) });
+  // `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 };
 }
 
@@ -787,7 +772,7 @@ function ledgerInsert({ fromVersion, toVersion, sourceCommit, note, requestedByB
 // Skips silently only when NEITHER is present (a local rehearsal with no DB pointed at) — the bump's
 // verification never depends on the ledger. An attempted-but-failed insert returns skipped:false so
 // the caller can surface it (the manual-INSERT footgun from 1976), never lose it.
-async function recordLedger({ fromVersion, toVersion, sourceCommit, note, requestedByBuilderId, source }, deps = {}) {
+async function recordLedger({ fromVersion, toVersion, sourceCommit, note, requestedByBuilderId, source, account = null }, deps = {}) {
   const url = deps.databaseUrl !== undefined ? deps.databaseUrl : process.env.DATABASE_URL;
   const database = deps.pgDatabase !== undefined ? deps.pgDatabase : process.env.PGDATABASE;
   if (!url && !database) return { ok: false, skipped: true, reason: 'no DATABASE_URL or PGDATABASE' };
@@ -828,12 +813,11 @@ async function recordLedger({ fromVersion, toVersion, sourceCommit, note, reques
   const sql = `${stmt.sql.slice(0, stmt.sql.indexOf(' VALUES '))}\n  VALUES (${stmt.cols.map(psqlValue).join(', ')});\n`;
   const sets = [];
   for (let i = 0; i < stmt.cols.length; i++) sets.push('--set', `${stmt.cols[i]}=${stmt.vals[i] == null ? '' : stmt.vals[i]}`);
-  const r = run('psql', [
-    '-d', database,
-    '-v', 'ON_ERROR_STOP=1',
-    '-q', '--no-psqlrc',
-    ...sets,
-  ], { encoding: 'utf8', input: sql });
+  // Through the project's own account when the move is not running as it (task 1004512):
+  // this psql peer-auths exactly as migrate does, so it must be the same identity or the
+  // ledger row silently stops being written on every own-account project.
+  const q = asAccount(account, 'psql', ['-d', database, '-v', 'ON_ERROR_STOP=1', '-q', '--no-psqlrc', ...sets]);
+  const r = run(q.cmd, q.args, { encoding: 'utf8', input: sql });
   if (!r || r.error) {
     const enoent = !!(r && r.error && r.error.code === 'ENOENT');
     return { ok: false, skipped: enoent, reason: enoent ? 'psql not found' : (r && r.error ? r.error.message : 'psql spawn failed') };
@@ -1065,7 +1049,7 @@ async function rollback({ instanceDir, snapshot, fromVersion, toVersion, opts },
   // 5. record the reversal in the ledger via the always-present `note` column (no schema
   //    dependency — so it records even when a FAILED migrate means a newer column wouldn't exist).
   const note = `rolled_back: ${reason} (attempted ${fromVersion || '(none)'} → ${toVersion}, restored ${snapshot.prevVersion || 'previous'})`;
-  const ledger = await recordLedger({ fromVersion, toVersion, sourceCommit: opts.sourceCommit, note, requestedByBuilderId: opts.requestedBy, source: opts.upgradeSource }, deps);
+  const ledger = await recordLedger({ fromVersion, toVersion, sourceCommit: opts.sourceCommit, note, requestedByBuilderId: opts.requestedBy, source: opts.upgradeSource, account: opts.migrateAs || null }, deps);
   if (ledger.ok) log('  ✓ recorded rollback in core_upgrades ledger');
   else if (ledger.skipped) log(`  • rollback ledger skipped (${ledger.reason})`);
   else err(`  ! rollback ledger insert failed (${ledger.reason}) — record it manually`);
@@ -1094,6 +1078,9 @@ async function runUpgrade(opts, deps = {}) {
   // failure AFTER that point (install / migrate / health) can revert. null until then = nothing to undo.
   let snapshot = null;
   if (!targetVersion) return { ok: false, error: 'missing --to <version> (the target core version)' };
+  // Checked once, here, rather than at each of the three places it is spent: an account
+  // name that reaches `sudo` is refused outright, never quoted into shape (task 1004512).
+  if (opts.migrateAs && !ACCOUNT_RE.test(opts.migrateAs)) return { ok: false, error: `--migrate-as ${JSON.stringify(opts.migrateAs)} is not a unix account name` };
 
   const pinnedVersion = readPinnedCoreVersion(instanceDir, fsImpl);
   const fromVersion = readInstalledCoreVersion(instanceDir, fsImpl) || pinnedVersion;
@@ -1118,7 +1105,13 @@ async function runUpgrade(opts, deps = {}) {
     // Step 5's own output is not dirt (task 1004122) — but only when step 5 is going to run.
     const preview = opts.skipMaterialize ? () => [] : (deps.willRewrite || require('./claude-materialize').materializeWillRewrite);
     const tree = gitTreeClean(instanceDir, run, preview({ instanceDir, materialize }, err));
-    if (!tree.ok) return { ok: false, error: `working tree not clean — commit/stash first, or pass --force.\n${tree.dirty || tree.reason || ''}` };
+    // TWO DIFFERENT FAILURES, TWO DIFFERENT SENTENCES (task 1004512). git ANSWERING with a
+    // list of dirty paths is a dirty tree, which the self-heal chain knows how to fix. git
+    // REFUSING to answer is not: committing anything would be committing a guess. They used
+    // to share one message, so a `dubious ownership` refusal was classified dirty_tree, the
+    // runner committed a tree that was never dirty, and the retry failed identically.
+    if (!tree.ok && tree.reason) return { ok: false, error: `git could not read the working tree in ${instanceDir} — the clean-tree pre-flight never ran, so this is NOT a report of uncommitted work.\n${tree.reason}` };
+    if (!tree.ok) return { ok: false, error: `working tree not clean — commit/stash first, or pass --force.\n${tree.dirty || ''}` };
     if (tree.ignored) log(`  • pre-flight: ignored ${tree.ignored} dirty path(s) this upgrade rewrites from the core (.claude/ materialization)${opts.commitPin ? ' — they are committed with the pin' : ' — pass --commit-pin to commit them'}.`);
   }
   const mods = preflightModules({ instanceDir, targetVersion }, deps);
@@ -1139,10 +1132,10 @@ async function runUpgrade(opts, deps = {}) {
         + '    Checked BEFORE the pin moves: migrate runs after the install, so a name that\n'
         + '    cannot be resolved there costs a full rollback to discover (task 1002755).' };
     }
-    const dbId = (deps.preflightDbIdentity || preflightDbIdentity)({ instanceDir, db }, run);
+    const dbId = (deps.preflightDbIdentity || preflightDbIdentity)({ instanceDir, db, account: opts.migrateAs || null }, run);
     if (!dbId.ok) return { ok: false, error: dbId.reason };
     if (dbId.skipped) log(`  • db identity pre-check${db ? ` (${db})` : ''}: ${dbId.skipped}`);
-    else log(`  ✓ pre-flight: database${db ? ` "${db}"` : ''} reachable as the current user`);
+    else log(`  ✓ pre-flight: database${db ? ` "${db}"` : ''} reachable as ${opts.migrateAs || 'the current user'}`);
     const { note: migrateNote } = require('./upgrade-migrate').migratePlan(instanceDir); if (migrateNote) log(`  ✓ pre-flight: ${migrateNote}`);
   }
 
@@ -1231,7 +1224,7 @@ async function runUpgrade(opts, deps = {}) {
 
   // 4. migrate (additive core_* migrations).
   if (!opts.skipMigrate) {
-    const mig = runMigrate(instanceDir, run);
+    const mig = runMigrate(instanceDir, run, opts.migrateAs || null);
     if (!mig.ok) {
       const error = `migrate failed (${mig.reason || 'exit ' + mig.code})`;
       if (rollbackOnFailure && snapshot) {
@@ -1366,7 +1359,7 @@ async function runUpgrade(opts, deps = {}) {
     return { ok: false, error: `${why} — rolled back to ${snapshot.prevVersion || 'the previous core'}`, fromVersion, toVersion: targetVersion, versionOk, healthOk, servedOk, servedVersion, rolledBack: true, rollback: rb };
   }
 
-  const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: isDowngrade ? `downgrade (--allow-downgrade)${opts.note ? `: ${opts.note}` : ''}` : opts.note, requestedByBuilderId: opts.requestedBy, source: opts.upgradeSource }, deps);
+  const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: isDowngrade ? `downgrade (--allow-downgrade)${opts.note ? `: ${opts.note}` : ''}` : opts.note, requestedByBuilderId: opts.requestedBy, source: opts.upgradeSource, account: opts.migrateAs || null }, deps);
   if (ledger.ok) log('  ✓ recorded in core_upgrades ledger');
   else if (ledger.skipped) log(`  • ledger skipped (${ledger.reason})`);
   else err(`  ! ledger insert failed (${ledger.reason}) — record it manually`);
@@ -1422,6 +1415,7 @@ function parseArgs(argv) {
     requestedBy: arg('--requested-by', argv),
     upgradeSource: arg('--upgrade-source', argv),
     pinPath: arg('--pin-path', argv),
+    migrateAs: arg('--migrate-as', argv), // task 1004512: the project's own unix+Postgres identity, when the move itself runs as the account that owns the checkout
     registry: hasFlag('--registry', argv), // ADR 0134: pull @bongos/core@<--to> from the npm registry instead of vendoring
     commitPin: hasFlag('--commit-pin', argv), // task 1002712: commit + push package.json/-lock so a pull-deploy reset cannot revert the bump
     pinNoPush: hasFlag('--pin-no-push', argv), // task 1003521 co-tenant mode: commit the pin but leave the customer's own remote alone
@@ -1458,6 +1452,7 @@ async function main(argv = process.argv.slice(2)) {
       '  --version-url <url>  read the RUNNING process\'s coreVersion back after restart and require it to equal --to (default: /version on the --health-url origin). A health check alone cannot tell a new core from an old one that never went down.',
       '  --no-health-check    explicitly skip the post-restart health confirmation (default: the check is ON — a bump that restarts the service must confirm it serves); also skips the served-version read-back',
       '  --skip-migrate       do not migrate (the default runs the instance\'s `migrate` script, else the core\'s scripts/migrate.sh)',
+      '  --migrate-as <user>  run the database steps (identity pre-check, migrate, ledger) as this unix account via `sudo -n -u`. For a project whose checkout is owned by the operator account but whose database is owned by its OWN account: the move needs the first to write files, the migration needs the second to connect. Omit it and everything runs as the current user, as before',
       '  --skip-materialize   do not refresh .claude/',
       '  --skip-regen-docs    do not regenerate the OpenAPI spec + typed client from the new core',
       '  --skip-pin-verify    do not verify the integrity pin (tree_sha256 + tarball.sha256) after install',

package/scripts/gds/wedge-remedy.js

@@ -34,7 +34,7 @@
 
 const { CONFIG } = require('./provision-config.js');
 const { dbName, selfInstanceRoot, standaloneRoot } = require('./provision-repo.js');
-const { migratePlan, CORE_MIGRATE_SCRIPT } = require('./upgrade-migrate.js');
+const { migratePlan, CORE_MIGRATE_SCRIPT, ACCOUNT_RE } = require('./upgrade-migrate.js');
 const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
 const outcome = require('./upgrade-outcome.js');
 const { DEFAULT_RETRY_DELAY_MS } = require('./intent-retry.js');
@@ -48,7 +48,10 @@ const REMEDY_EVENT = 'core-upgrade-remedy';
 // purpose: anything outside it is refused, never quoted.
 const SHELL_SAFE_RE = /^[A-Za-z0-9._/-]{1,200}$/;
 const DB_NAME_RE = /^[A-Za-z0-9_-]{1,63}$/;
-const ACCOUNT_RE = /^[a-z_][a-z0-9_-]{0,31}$/;
+// ACCOUNT_RE is imported, not re-declared: this file and upgrade-migrate.js check the same
+// value for the same reason (it reaches `sudo -u`), and two copies of a security predicate
+// drift one edit at a time. provision-repo.js keeps its own UNIX_ACCOUNT_RE deliberately —
+// importing from here would point the provisioner at the upgrade CLI, the wrong direction.
 
 /**
  * The fix for one known snag, as a command to run on the box. PURE.
@@ -105,9 +108,12 @@ function planRemedy(inst, reason, o = {}) {
   return { reason, cwd: dir, env: { PGDATABASE: db, ...(initCwd ? { INIT_CWD: dir } : {}) }, cmd: run, describe: `migrated ${db} to match the code it is running` };
 }
 
-// The account the project runs as, probed the way the move itself probes (task 1004128).
+// The account the project's DATABASE belongs to, probed the way the move itself probes
+// (task 1004128). `migrateAs`, not `runAs`: since task 1004512 those are two different
+// answers, and this remedy is a migration — it needs the Postgres login role, which the
+// account that owns the checkout is not.
 function runAsFor(inst, deps) {
-  try { return require('./provision-core-upgrade.js').resolveRunAs(inst, deps).runAs; } catch { return null; }
+  try { return require('./provision-core-upgrade.js').resolveRunAs(inst, deps).migrateAs; } catch { return null; }
 }
 
 /**

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.13'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.15'; // 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');