@bongos/core 1.20.28 → 1.20.30

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

@@ -38,6 +38,7 @@ const { appUser, dbName, instanceUser, parseTargetRef, resolveOwnerGithubToken,
 const { ensurePinWriteKey, hasOwnAccount, pinKeyPath, pinSshCommand } = require('./provision-pin-key.js');
 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)
 
 // The shapes whose box this runner can actually reach. Mirrors UPGRADE_SHAPES in the
 // web-tier half, and deliberately EXCLUDES 'dedicated': a dedicated droplet is stood up
@@ -141,6 +142,21 @@ function targetFault(to, available, installed, channel, channelAllows) {
   return null;
 }
 
+// The update channel that bounds a move for THIS instance (task 1004445): the row's own
+// `update_channel`, normalised by update-channel.js so anything unknown or absent (a row
+// read before migration provisioning_029) falls back to DEFAULT_CHANNEL. PURE. One helper
+// for the move and the snapshot, so the button's offer and the runner's refusal cannot
+// disagree about which rule applies.
+function instanceChannel(inst, channelMod) {
+  return channelMod.normalizeChannel(inst && inst.update_channel != null ? inst.update_channel : channelMod.DEFAULT_CHANNEL);
+}
+
+// A classified refusal (task 1004446): the drain loop stores `failure` beside last_error,
+// so the rest of the self-heal chain acts on a class, not on a sentence. PURE.
+function failed(reason, error, extra = {}) {
+  return { ok: false, error, failure: outcome.classifyFailure(reason), ...extra };
+}
+
 // The builder id a queued move is attributed to, from the actor the web tier recorded.
 // PURE. Two doors reach the move (ADR 0339): an Archon (`api:archon:<id>`) and, since
 // task 1004174, the project's own owner (`api:owner:<id>`). Both carry the id, because
@@ -180,7 +196,7 @@ async function coreUpgradeInstance(inst, deps, intent) {
   // anything. The guard's real job is the OTHER actions on the self row, enforced at
   // enqueueIntent where every intent passes.
   if (!UPGRADE_SHAPES.has(inst.hosting_shape)) {
-    return { ok: false, error: `core-upgrade is not automated for a '${inst.hosting_shape}' instance — whoever runs that machine has to upgrade it there` };
+    return failed('shape_not_automated', `core-upgrade is not automated for a '${inst.hosting_shape}' instance — whoever runs that machine has to upgrade it there`);
   }
   if (inst.status !== 'active') {
     // Not an error: a teardown or a stand-up that raced the request must not burn the
@@ -189,7 +205,7 @@ async function coreUpgradeInstance(inst, deps, intent) {
     return { ok: true, noop: true };
   }
   if (!to) {
-    return { ok: false, error: 'core-upgrade intent carries no target_version — refusing to guess which version was meant' };
+    return failed('no_target', 'core-upgrade intent carries no target_version — refusing to guess which version was meant');
   }
   // THE SLUG IS INTERPOLATED INTO A SHELL COMMAND BELOW, so it is re-checked HERE
   // rather than trusted. `isValidSlug` is enforced on the create route, but the
@@ -200,7 +216,7 @@ async function coreUpgradeInstance(inst, deps, intent) {
   // two interpolated values are already constrained — the version by the column's own
   // CHECK and by VERSION_RE, the actor by the digits-only extraction below.
   if (!isValidSlug(inst.slug)) {
-    return { ok: false, error: `instance slug '${inst.slug}' is not a valid slug — refusing to build a command from it` };
+    return failed('bad_slug', `instance slug '${inst.slug}' is not a valid slug — refusing to build a command from it`);
   }
 
   // ---- 2. is the target real, and permitted -----------------------------------------
@@ -209,19 +225,16 @@ async function coreUpgradeInstance(inst, deps, intent) {
   const instanceDir = inst.hosting_shape === 'cloud-host' ? standaloneRoot(inst) : selfRoot();
   const readInstalled = deps.readInstalledCoreVersion || require('./upgrade.js').readInstalledCoreVersion;
   const installed = readInstalled(instanceDir);
-  // THE PLATFORM DEFAULT, NOT A PER-INSTANCE CHANNEL — and saying so beats implying
-  // otherwise. provisioning_instances carries no channel column; the subscription
-  // roster update-channel.js reads is a control-plane file, not a per-row setting. So
-  // this bounds every instance by the same policy (DEFAULT_CHANNEL: patch-only), which
-  // is a real bound — it refuses a prerelease or a major jump — and is the honest one
-  // available today. When a per-instance channel lands, this line is where it is read;
-  // writing `inst.update_channel ||` now would only have created a guard that reads as
-  // present and can never fire, which is the trap the web-tier half already documents.
-  const channel = channelMod.normalizeChannel(channelMod.DEFAULT_CHANNEL);
+  // THIS PROJECT'S OWN UPDATE RULE (task 1004445, migration provisioning_029). Before it
+  // every instance was bounded by DEFAULT_CHANNEL (patch-only), so a step-up release
+  // could reach no project through the door and the refusal's "change the channel first"
+  // pointed at nothing. A row from before the column (undefined) still normalises to that
+  // default, so an old runner schema reads exactly as it always did.
+  const channel = instanceChannel(inst, channelMod);
   const listed = channelMod.listAvailableVersions({ cwd: instanceDir });
   const available = (listed && listed.versions) || [];
   const fault = targetFault(to, available, installed, channel, channelMod.channelAllows);
-  if (fault) return { ok: false, error: fault };
+  if (fault) return failed(outcome.runnerReason(fault), fault);
   if (installed && installed === to) {
     // `bongos upgrade` would no-op on this too, but saying so here keeps a re-drained
     // intent from restarting a healthy service to land exactly where it already is.
@@ -259,10 +272,17 @@ async function coreUpgradeInstance(inst, deps, intent) {
     log(`  [upgrade] (in ${runDir}) ${cmd}`);
     boxExec(cmd, { cwd: runDir });
   } catch (e) {
-    // upgrade.js rolls itself back on a failed health check or an unchanged served
-    // version, so by the time this throws the instance is back on the core it had.
-    // ok:false, never a throw: the instance is healthy and must not be marked broken.
-    return { ok: false, error: `core upgrade to ${to} failed and was rolled back: ${(e && e.message) || e}` };
+    // HOW FAR IT GOT, from upgrade.js's own outcome line (task 1004446) — never assumed.
+    // It used to say "failed and was rolled back" for every exit, including refusals that
+    // fire before the pin moves (nothing changed) and rollbacks that themselves failed
+    // (the project may be down). ok:false, never a throw: the drain loop's catch marks the
+    // INSTANCE broken, which is only ever right for the rollback_failed case, and that one
+    // is reported (and retired, never retried unattended) rather than guessed at here.
+    const text = `${(e && e.stderr) || ''}\n${(e && e.message) || e}`;
+    const o = outcome.parseOutcomeLine(text);
+    const said = (/✖ ([^\n]+)/.exec(text) || [])[1] || String((e && e.message) || e).split('\n')[0];
+    const reason = o ? o.reason : 'unknown';
+    return failed(reason, outcome.describeUpgradeFailure(to, o, said), { stage: o ? o.stage : null, terminal: reason === 'rollback_failed' });
   }
 
   // ---- 4. read back what the BOX serves (ADR 0293 D6) --------------------------------
@@ -281,7 +301,7 @@ async function coreUpgradeInstance(inst, deps, intent) {
   if (served && served !== to) {
     // upgrade.js's own --version-url gate should have caught and reverted this, so
     // reaching here means the two disagree. Report what was SEEN rather than a verdict.
-    return { ok: false, error: `the box is serving core ${served}, not the requested ${to} — the move did not take` };
+    return failed('served_mismatch', `the box is serving core ${served}, not the requested ${to} — the move did not take`);
   }
 
   // ---- 5. the pin reaches the project's own repo, pushed from HERE (task 1004065) ----
@@ -977,7 +997,7 @@ async function snapshotCoreVersions(inst, deps) {
     // admits nothing newer — "already current" and "nothing to take" are the same
     // answer here, and both correctly leave `recommended` NULL.
     const recommended = served
-      ? channelMod.resolveChannelTarget({ installed: served, channel: channelMod.DEFAULT_CHANNEL, available })
+      ? channelMod.resolveChannelTarget({ installed: served, channel: instanceChannel(inst, channelMod), available })
       : null;
     // THE TICK DOES NOT DRY-RUN. The verdict is produced on demand (preflightCoreUpgrade),
     // because a check re-run every tick for a box that has been behind for hours spends a
@@ -1021,4 +1041,4 @@ async function snapshotAllCoreVersions(deps) {
   return { seen };
 }
 
-module.exports = { pushUpgradePin, UPGRADE_SHAPES, CHANGE_CAP, REPO_NOTES, repoNote, requestedByOf, parseChangeRecords, readInstalledNotes, readPackagedNotes, changesBetween, coreCheckoutCandidates, findCoreCheckout, gitFault, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };
+module.exports = { pushUpgradePin, UPGRADE_SHAPES, instanceChannel, CHANGE_CAP, REPO_NOTES, repoNote, requestedByOf, parseChangeRecords, readInstalledNotes, readPackagedNotes, changesBetween, coreCheckoutCandidates, findCoreCheckout, gitFault, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };

package/scripts/gds/provision.js

@@ -1200,8 +1200,10 @@ async function cmdRunIntents(deps) {
           // instance is never marked broken over a domain hiccup, but the card
           // can say why the work stopped.
           await provisioning.setInstanceStatus(db, intent.instance_id, inst.status, { error_note: result.error || 'op failed', error_note_action: intent.action }).catch(() => {});
+          if (result.failure) await recordFailureClass(db, intent.id, result.failure); // WHAT KIND of failure, beside the sentence (task 1004446)
         } else {
           await db.query(`UPDATE provisioning_intents SET state='pending', last_error=$2, updated_at=now() WHERE id=$1`, [intent.id, result.error || 'op failed']);
+          if (result.failure) await recordFailureClass(db, intent.id, result.failure);
         }
         errors++;
       } else { await provisioning.resolveIntent(db, intent.id, 'done', (result && result.doneNote) || null); ok++; } // done WITH a note: it landed, and this is what it could not finish (task 1004065)
@@ -1293,6 +1295,15 @@ box (task 2074). Set PROVISION_CONTROL_PLANE_IP to this box's own public IP so a
 standalone instance's A record points HERE, not at the co-hosting box's PROVISION_PUBLIC_IP.`);
 }
 
+// Store an intent's failure class + reason code (migration provisioning_030, task 1004446),
+// only for a result that carries one. Best-effort: a runner on a schema without the columns
+// must still drain, so a failed write is swallowed — last_error still says it either way. A
+// class left on a row that later lands 'done' is harmless: readers ignore it on a done row.
+async function recordFailureClass(db, intentId, failure) {
+  await db.query('UPDATE provisioning_intents SET failure_class = $2, failure_reason = $3 WHERE id = $1',
+    [intentId, failure ? failure.class : null, failure ? failure.reason : null]).catch(() => {});
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const cmd = args[0];

package/scripts/gds/upgrade-outcome.js

@@ -0,0 +1,155 @@
+'use strict';
+//
+// scripts/gds/upgrade-outcome.js — what a failed core move actually WAS, as a class and a
+// reason code the deploy runner can act on (task 1004446, goal 1000090 deploy self-heal).
+//
+// WHY. Every non-zero exit from `bongos upgrade` reached the owner as "failed and was rolled
+// back", including the refusals that fire BEFORE the pin moves (a dirty tree, the artist
+// gate, a downgrade, the database identity check) — nothing was changed, so nothing was
+// rolled back. And a rollback that itself failed ("manual intervention needed") read exactly
+// like one that worked. The runner could not tell a wait-and-retry from a decision only the
+// owner can make from an outage, so it treated all of them the same: retry, then give up.
+//
+// TWO HALVES, ONE FILE, so the words cannot drift apart:
+//   • upgrade.js ends a failed run with ONE machine-readable stderr line (outcomeLine) saying
+//     how far it got: refused (nothing moved) · rolled_back (moved, restored) ·
+//     rollback_failed (moved, NOT restored). The runner invokes upgrade.js from its own
+//     checkout, so the two halves are always the same version.
+//   • the runner reads it back (parseOutcomeLine) and classifies (classifyFailure).
+//
+// THE FOUR CLASSES the rest of the self-heal chain keys on:
+//   transient       — try again later and it may simply work (registry blip, not published yet)
+//   known_wedge     — a known snag with a known fix the runner may apply itself (dirty tree, full disk)
+//   needs_decision  — a rule the owner set is refusing it; only the owner can change that
+//   unknown         — anything else, and every rollback that failed; a person should look
+//
+// PURE: no I/O, no requires. Reason codes are a fixed vocabulary — never builder text — so
+// they are safe to store, index and show.
+
+const OUTCOME_TAG = 'BONGOS_UPGRADE_OUTCOME';
+const STAGES = Object.freeze(['refused', 'rolled_back', 'rollback_failed']);
+const FAILURE_CLASSES = Object.freeze(['transient', 'known_wedge', 'needs_decision', 'unknown']);
+
+// reason → class. Anything not listed is `unknown`, which is the safe direction: an unknown
+// failure reaches a person; a mislabelled one could be retried or "healed" wrongly.
+const REASON_CLASS = Object.freeze({
+  // the runner's own refusals (provision-core-upgrade.js)
+  registry_unreadable: 'transient',
+  not_published: 'transient',
+  outside_channel: 'needs_decision',
+  shape_not_automated: 'needs_decision',
+  no_target: 'unknown',
+  bad_slug: 'unknown',
+  installed_unreadable: 'unknown',
+  served_mismatch: 'unknown',
+  // upgrade.js refusals, before the pin moves
+  dirty_tree: 'known_wedge',
+  downgrade: 'needs_decision',
+  artist_gate: 'needs_decision',
+  module_incompatible: 'needs_decision',
+  already_on: 'unknown',
+  db_unresolvable: 'unknown',
+  db_identity: 'unknown',
+  health_url_missing: 'unknown',
+  core_source: 'unknown',
+  // after the pin moved (rolled back)
+  disk_full: 'known_wedge',
+  npm_install: 'transient',
+  integrity_pin: 'unknown',
+  migrate: 'unknown',
+  restart: 'unknown',
+  health: 'unknown',
+  // the one that must never be retried unattended
+  rollback_failed: 'unknown',
+});
+
+// upgrade.js error text → reason. Ordered; first match wins. Each pattern is the PREFIX of
+// a message upgrade.js builds itself (runUpgrade), so these track that file, not the world.
+const UPGRADE_REASONS = [
+  [/no space left on device|ENOSPC/i, 'disk_full'],
+  [/^refusing to DOWNGRADE/, 'downgrade'],
+  [/^already on /, 'already_on'],
+  [/^working tree not clean/, 'dirty_tree'],
+  [/^module pre-check failed/, 'module_incompatible'],
+  [/^cannot determine which database/, 'db_unresolvable'],
+  [/^post-restart health check is mandatory/, 'health_url_missing'],
+  [/^(--registry and --from|--from tarball not found|no core tarball at)/, 'core_source'],
+  [/^npm install failed/, 'npm_install'],
+  [/^integrity pin/, 'integrity_pin'],
+  [/^migrate failed/, 'migrate'],
+  [/^restart failed/, 'restart'],
+  [/^(health check failed after restart|served core version did not change)/, 'health'],
+];
+
+/** The reason code for an upgrade.js failure result (runUpgrade's `{ ok:false, … }`). PURE. */
+function upgradeReason(res) {
+  if (!res) return 'unknown';
+  if (res.downgrade) return 'downgrade';
+  if (res.artistGate) return 'artist_gate';
+  const text = String(res.error || '');
+  for (const [re, reason] of UPGRADE_REASONS) if (re.test(text)) return reason;
+  // A database-identity refusal carries preflightDbIdentity's own reason, which has no
+  // fixed prefix; it is the only pre-pin refusal left that names the database.
+  if (!res.rolledBack && /database|PGDATABASE/i.test(text)) return 'db_identity';
+  return 'unknown';
+}
+
+/** How far a failed run got. A rollback counts as failed if ANY of its steps did. PURE. */
+function upgradeStage(res) {
+  if (!res || !res.rolledBack) return 'refused';
+  const rb = res.rollback || {};
+  const broken = rb.restoreOk === false || rb.reinstallOk === false || rb.restartOk === false || rb.healthOk === false;
+  return broken ? 'rollback_failed' : 'rolled_back';
+}
+
+/** The single stderr line upgrade.js ends a failed run with. PURE. */
+function outcomeLine(res) {
+  const stage = upgradeStage(res);
+  const reason = stage === 'rollback_failed' ? 'rollback_failed' : upgradeReason(res);
+  return `${OUTCOME_TAG} ${JSON.stringify({ stage, reason })}\n`;
+}
+
+/** Read the outcome line back out of captured output, or null if there is none. PURE. */
+function parseOutcomeLine(text) {
+  const lines = String(text || '').split(/\r?\n/).filter((l) => l.startsWith(`${OUTCOME_TAG} `));
+  if (!lines.length) return null;
+  try {
+    const o = JSON.parse(lines[lines.length - 1].slice(OUTCOME_TAG.length + 1));
+    if (!STAGES.includes(o.stage) || typeof o.reason !== 'string' || !/^[a-z_]{1,40}$/.test(o.reason)) return null;
+    return { stage: o.stage, reason: o.reason };
+  } catch { return null; }
+}
+
+/** `{ class, reason }` for a reason code; an unlisted code is `unknown`. PURE. */
+function classifyFailure(reason) {
+  const r = typeof reason === 'string' && Object.prototype.hasOwnProperty.call(REASON_CLASS, reason) ? reason : 'unknown';
+  return { class: REASON_CLASS[r] || 'unknown', reason: r };
+}
+
+/** The runner's own refusals (targetFault's sentences) → reason code. PURE. */
+function runnerReason(text) {
+  const s = String(text || '');
+  if (/^could not read the published core versions/.test(s)) return 'registry_unreadable';
+  if (/is not published yet/.test(s)) return 'not_published';
+  if (/could not read the core version installed/.test(s)) return 'installed_unreadable';
+  if (/update channel/.test(s)) return 'outside_channel';
+  return 'unknown';
+}
+
+/**
+ * The sentence the owner reads for a failed upgrade.js run. Says what actually happened,
+ * never more: "rolled back" only when a rollback ran and finished. PURE.
+ */
+function describeUpgradeFailure(to, outcome, detail) {
+  const d = String(detail || '').trim();
+  const tail = d ? `: ${d}` : '';
+  if (!outcome) return `core upgrade to ${to} failed, and the upgrade did not report how far it got — check the project before retrying${tail}`;
+  if (outcome.stage === 'refused') return `core upgrade to ${to} was refused before anything changed — the project is still on its previous core${tail}`;
+  if (outcome.stage === 'rolled_back') return `core upgrade to ${to} failed and was rolled back — the project is back on its previous core${tail}`;
+  return `core upgrade to ${to} failed AND the rollback did not finish — the project may be down or on a half-installed core, and needs a person${tail}`;
+}
+
+module.exports = {
+  OUTCOME_TAG, STAGES, FAILURE_CLASSES, REASON_CLASS,
+  upgradeReason, upgradeStage, outcomeLine, parseOutcomeLine, classifyFailure, runnerReason, describeUpgradeFailure,
+};

package/scripts/gds/upgrade.js

@@ -1480,7 +1480,7 @@ async function main(argv = process.argv.slice(2)) {
     return require('./module').cmdUpgrade(argv);
   }
   const res = await runUpgrade(parseArgs(argv));
-  if (!res.ok) { process.stderr.write(`\n✖ ${res.error || 'upgrade failed'}\n`); return 1; }
+  if (!res.ok) { process.stderr.write(`\n✖ ${res.error || 'upgrade failed'}\n${require('./upgrade-outcome').outcomeLine(res)}`); return 1; } // the outcome line: how far it got, for the deploy runner (task 1004446)
   return 0;
 }
 

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

@@ -18,7 +18,7 @@ import { createRequire } from 'node:module';
 import { readFileSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { parseRepoNote } from '../modules/provisioning/core-upgrade.js';
+import { parseRepoNote, UPDATE_CHANNELS, DEFAULT_UPDATE_CHANNEL, updateChannelOf, makeUpdateChannelHandler as updateChannelHandlerFor } from '../modules/provisioning/core-upgrade.js';
 
 const require = createRequire(import.meta.url);
 const P = require('../modules/provisioning/provisioning.js');
@@ -885,5 +885,93 @@ await t('lastMoveSuperseded computes no version ORDERING — only identity', ()
   assert.equal(CU.lastMoveSuperseded('1.19.921', '1.19.900', '1.19.949'), true);
 });
 
+console.log('\nthe project\'s update rule (task 1004445):');
+
+const channelHandler = (inst, calls) => updateChannelHandlerFor({
+  provisioning: {
+    getInstanceById: async () => inst,
+    recordEvent: async (_db, e) => { calls.push({ event: e.event, detail: e.detail, actor: e.actor }); },
+  },
+  pool: { query: async (sql, params) => { calls.push({ sql, params }); return { rows: [] }; } },
+  parseId: () => 7, validateOrRespond: () => false, log: { error() {} },
+});
+const runChannel = async (inst, body, calls = []) => {
+  let out = null;
+  const res = { json: (b) => { out = b; return res; }, fail: (code, o) => { out = { code, ...o }; return res; } };
+  await channelHandler(inst, calls)({ builder: { id: 42 }, params: { id: '7' }, body }, res);
+  return out;
+};
+
+await t('the web tier\'s channel list is the runner\'s, and the migration\'s CHECK carries the same values', () => {
+  const policy = require('../scripts/gds/update-channel.js');
+  assert.deepEqual([...UPDATE_CHANNELS], policy.VALID_CHANNELS, 're-stated in the module (ADR 0083) — so it must be equal');
+  assert.equal(DEFAULT_UPDATE_CHANNEL, policy.DEFAULT_CHANNEL);
+  const sql = read('modules', 'provisioning', 'migrations', 'provisioning_029_update_channel.sql');
+  assert.match(sql, /DEFAULT 'patch'/);
+  for (const c of policy.VALID_CHANNELS) assert.match(sql, new RegExp(`'${c}'`), `the CHECK admits ${c}`);
+});
+
+await t('updateChannelOf reads the row and falls back to patch for a pre-column row', () => {
+  assert.equal(updateChannelOf({ update_channel: 'minor' }), 'minor');
+  assert.equal(updateChannelOf({}), 'patch');
+  assert.equal(updateChannelOf({ update_channel: 'everything' }), 'patch');
+});
+
+await t('setting the rule writes the row and audits who changed it, from what to what', async () => {
+  const calls = [];
+  const out = await runChannel({ ...ACTIVE, update_channel: 'patch' }, { channel: 'minor' }, calls);
+  assert.equal(out.ok, true);
+  assert.equal(out.update_channel, 'minor');
+  assert.equal(out.changed, true);
+  const w = calls.find((c) => c.sql && /UPDATE provisioning_instances SET update_channel/.test(c.sql));
+  assert.ok(w, 'the row was written');
+  assert.deepEqual(w.params, [7, 'minor']);
+  const ev = calls.find((c) => c.event === 'update-channel-changed');
+  assert.ok(ev, 'and an event recorded');
+  assert.match(ev.detail, /from patch to minor/);
+  assert.equal(ev.actor, 'api:archon:42');
+  assert.ok(!calls.some((c) => c.sql && /provisioning_intents/.test(c.sql)), 'nothing is queued — a rule change moves no core');
+});
+
+await t('an unknown rule is a 400 naming the valid ones, and writes nothing', async () => {
+  const calls = [];
+  const out = await runChannel(ACTIVE, { channel: 'major' }, calls);
+  assert.equal(out.code, 'bad_update_channel');
+  assert.equal(out.status, 400);
+  assert.deepEqual(out.details.valid, ['pinned', 'patch', 'minor']);
+  assert.equal(calls.length, 0);
+});
+
+await t('re-sending the current rule changes nothing and says so', async () => {
+  const calls = [];
+  const out = await runChannel({ ...ACTIVE, update_channel: 'minor' }, { channel: 'MINOR' }, calls);
+  assert.equal(out.ok, true);
+  assert.equal(out.changed, false);
+  assert.equal(calls.length, 0, 'no write, no event');
+});
+
+await t('the preview carries the rule, so the page can say which rule shaped the offer', () => {
+  assert.equal(CU.previewFromSnapshot({ ...ACTIVE, update_channel: 'minor' }, null, null, null).update_channel, 'minor');
+  assert.equal(CU.previewFromSnapshot(ACTIVE, null, null, null).update_channel, 'patch');
+});
+
+await t('the route is gated like the move: the owner door OR core.pin.move', () => {
+  const src = read('modules', 'provisioning', 'routes', 'core-upgrade.js');
+  const i = src.indexOf("'/provisioning/instances/:id/update-channel'");
+  assert.ok(i > 0, 'the route exists');
+  const block = src.slice(i, src.indexOf(');', i));
+  assert.match(block, /api\.requireBuilder/);
+  assert.match(block, /requireOwnProjectOrPin\(\{ pinGate: api\.requirePermission\('core\.pin\.move'\)/);
+});
+
+await t('a failed move carries its class to the page; a move that worked carries none (task 1004446)', () => {
+  const failedMove = { target_version: '1.20.1', state: 'error', last_error: 'x', failure_class: 'needs_decision', failure_reason: 'outside_channel' };
+  assert.deepEqual(CU.previewFromSnapshot(ACTIVE, null, null, failedMove).last_move.failure, { class: 'needs_decision', reason: 'outside_channel' });
+  const done = { ...failedMove, state: 'done' };
+  assert.equal(CU.previewFromSnapshot(ACTIVE, null, null, done).last_move.failure, null);
+  const old = { target_version: '1.20.1', state: 'error', last_error: 'x' };
+  assert.equal(CU.previewFromSnapshot(ACTIVE, null, null, old).last_move.failure, null, 'a row from before the columns');
+});
+
 console.log(`\ncore_upgrade_door: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);

package/tests/core_upgrade_runner.mjs

@@ -31,7 +31,7 @@ import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 // An ESM named import, not R.parseSchemaPending: knip credits a CJS export only when a test imports it this way.
-import { parseSchemaPending, repoNote, REPO_NOTES } from '../scripts/gds/provision-core-upgrade.js';
+import { parseSchemaPending, repoNote, REPO_NOTES, instanceChannel } from '../scripts/gds/provision-core-upgrade.js';
 import { parseRepoNote } from '../modules/provisioning/core-upgrade.js';
 
 const require = createRequire(import.meta.url);
@@ -1396,5 +1396,124 @@ await t('the DRAIN LOOP resolves a done-with-a-note move WITH its note, still as
   assert.equal(statusWrites.length, 0, 'a healthy instance is not marked anything');
 });
 
+console.log('\nthe project\'s own update rule (task 1004445):');
+
+// The REAL policy module, not the stub makeDeps hands every other case: these cases are
+// about which rule the runner applies, so a stub that admits everything would prove nothing.
+const realChannel = require('../scripts/gds/update-channel.js');
+const withRealChannel = (over) => {
+  const d = makeDeps(over);
+  d.updateChannel = { ...realChannel, listAvailableVersions: () => ({ ok: true, versions: over.available }) };
+  return d;
+};
+
+await t('instanceChannel reads the row, and a row from before the column falls back to patch', () => {
+  assert.equal(instanceChannel({ update_channel: 'minor' }, realChannel), 'minor');
+  assert.equal(instanceChannel({ update_channel: 'pinned' }, realChannel), 'pinned');
+  assert.equal(instanceChannel({}, realChannel), 'patch', 'no column yet → the old default');
+  assert.equal(instanceChannel({ update_channel: 'bogus' }, realChannel), 'patch', 'unknown → the default, never a wider rule');
+});
+
+await t('a project on PATCH still refuses a step-up release (1.19 → 1.20)', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1081', available: ['1.19.1081', '1.20.1'] });
+  const r = await R.coreUpgradeInstance(inst({ update_channel: 'patch' }), d, intent({ target_version: '1.20.1' }));
+  assert.equal(r.ok, false);
+  assert.match(r.error, /outside this project's 'patch' update channel/);
+  assert.ok(!d.ran.some((c) => /upgrade\.js/.test(c)), 'and nothing was run');
+});
+
+await t('a project on MINOR takes that same step-up release', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.20.1', available: ['1.19.1081', '1.20.1'] });
+  const r = await R.coreUpgradeInstance(inst({ update_channel: 'minor' }), d, intent({ target_version: '1.20.1' }));
+  assert.ok(!(r.error && /update channel/.test(r.error)), `the channel must not refuse it: ${r.error}`);
+  assert.ok(d.ran.some((c) => /upgrade\.js/.test(c) && /--to 1\.20\.1/.test(c)), 'the upgrade was invoked for 1.20.1');
+});
+
+await t('MINOR still refuses a MAJOR jump — no rule makes 2.0 automatic', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1081', available: ['1.19.1081', '2.0.0'] });
+  const r = await R.coreUpgradeInstance(inst({ update_channel: 'minor' }), d, intent({ target_version: '2.0.0' }));
+  assert.equal(r.ok, false);
+  assert.match(r.error, /outside this project's 'minor' update channel/);
+});
+
+await t('the snapshot OFFERS what the project\'s rule admits — the button and the runner agree', async () => {
+  const available = ['1.19.1081', '1.19.1082', '1.20.1', '1.20.11'];
+  const offered = async (update_channel) => {
+    const queries = [];
+    await R.snapshotCoreVersions(inst({ update_channel }), withRealChannel({ served: '1.19.1081', available, queries }));
+    return queries.find((q) => /provisioning_core_version_snapshot/.test(q.sql)).params[3];
+  };
+  assert.equal(await offered('patch'), '1.19.1082', 'patch offers the newest fix on the same line');
+  assert.equal(await offered('minor'), '1.20.11', 'minor offers the step up');
+  assert.equal(await offered('pinned'), null, 'pinned offers nothing');
+  assert.equal(await offered(undefined), '1.19.1082', 'a pre-column row behaves exactly as before');
+});
+
+console.log('\nwhat a failed upgrade.js run is reported as (task 1004446):');
+
+// execSync's error: message "Command failed: <cmd>\n<stderr>", stderr a Buffer.
+const upgradeThrows = (stderr) => (d) => {
+  const base = d.exec;
+  d.exec = (cmd, opts) => {
+    if (/upgrade\.js/.test(cmd)) { const e = new Error(`Command failed: ${cmd}\n${stderr}`); e.stderr = Buffer.from(stderr); e.status = 1; throw e; }
+    return base(cmd, opts);
+  };
+  return d;
+};
+
+await t('a refusal before the pin moved is classified, and never called "rolled back"', async () => {
+  const d = upgradeThrows('\n✖ working tree not clean — commit/stash first\nBONGOS_UPGRADE_OUTCOME {"stage":"refused","reason":"dirty_tree"}\n')(makeDeps());
+  const r = await R.coreUpgradeInstance(inst(), d, intent());
+  assert.equal(r.ok, false);
+  assert.deepEqual(r.failure, { class: 'known_wedge', reason: 'dirty_tree' });
+  assert.equal(r.stage, 'refused');
+  assert.doesNotMatch(r.error, /rolled back/);
+  assert.match(r.error, /working tree not clean/, 'the upgrade\'s own sentence is kept');
+  assert.ok(!r.terminal);
+});
+
+await t('a real rollback says rolled back', async () => {
+  const d = upgradeThrows('\n✖ migrate failed (exit 3)\nBONGOS_UPGRADE_OUTCOME {"stage":"rolled_back","reason":"migrate"}\n')(makeDeps());
+  const r = await R.coreUpgradeInstance(inst(), d, intent());
+  assert.deepEqual(r.failure, { class: 'unknown', reason: 'migrate' });
+  assert.match(r.error, /failed and was rolled back/);
+});
+
+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());
+  assert.deepEqual(r.failure, { class: 'unknown', reason: 'rollback_failed' });
+  assert.equal(r.stage, 'rollback_failed');
+  assert.equal(r.terminal, true);
+  assert.match(r.error, /rollback did not finish/);
+});
+
+await t('an exit with NO outcome line (sudo refused before node ran) is unknown and claims no rollback', async () => {
+  const d = upgradeThrows('sudo: unknown user bongos-test4\n')(makeDeps());
+  const r = await R.coreUpgradeInstance(inst(), d, intent());
+  assert.deepEqual(r.failure, { class: 'unknown', reason: 'unknown' });
+  assert.doesNotMatch(r.error, /rolled back/);
+});
+
+await t('the runner\'s own refusals are classified too', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1081', available: ['1.19.1081', '1.20.1'] });
+  const r = await R.coreUpgradeInstance(inst({ update_channel: 'patch' }), d, intent({ target_version: '1.20.1' }));
+  assert.deepEqual(r.failure, { class: 'needs_decision', reason: 'outside_channel' });
+  const n = await R.coreUpgradeInstance(inst(), makeDeps({ available: ['1.19.760'] }), intent({ target_version: '1.19.999' }));
+  assert.deepEqual(n.failure, { class: 'transient', reason: 'not_published' });
+  const s = await R.coreUpgradeInstance(inst({ hosting_shape: 'dedicated' }), makeDeps(), intent());
+  assert.deepEqual(s.failure, { class: 'needs_decision', reason: 'shape_not_automated' });
+});
+
+await t('upgrade.js ends a failed run with the outcome line', () => {
+  const src = fs.readFileSync(new URL('../scripts/gds/upgrade.js', import.meta.url), 'utf8');
+  assert.match(src, /if \(!res\.ok\) \{ process\.stderr\.write\([^\n]*outcomeLine\(res\)/);
+});
+
+await t('the drain loop writes the class beside the sentence (behaviour: tests/provision.mjs)', () => {
+  const src = fs.readFileSync(new URL('../scripts/gds/provision.js', import.meta.url), 'utf8');
+  assert.match(src, /SET failure_class = \$2, failure_reason = \$3/);
+});
+
 console.log(`\ncore_upgrade_runner: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);

package/tests/provision.mjs

@@ -2564,6 +2564,40 @@ await ta('F19: a NON-final failure re-pends the intent and writes nothing on the
   assert.equal(statusWrites.length, 0, 'no instance write until the intent actually retires');
 });
 
+// A failed core move stores WHAT KIND of failure beside its sentence (task 1004446).
+const classifiedRun = async (attempts) => {
+  let claims = 0; const resolved = []; const classWrites = [];
+  const deps = {
+    apply: true, log: () => {},
+    db: { query: async (sql, params) => { if (/SET failure_class/.test(sql)) classWrites.push(params); return { rows: [] }; } },
+    provisioning: {
+      claimNextIntent: async () => (claims++ === 0
+        ? { id: 11, instance_id: 18, action: 'core-upgrade', target_version: '1.20.1', attempts } : null),
+      // 'dedicated' is a shape the runner cannot move — a classified refusal, no exec needed.
+      getInstanceById: async () => ({ ...activeStandalone, hosting_shape: 'dedicated' }),
+      resolveIntent: async (_db, id, state) => { resolved.push({ id, state }); },
+      setInstanceStatus: async () => {}, recordEvent: async () => {},
+      claimNextOAuthManifest: async () => null, resolveOAuthManifest: async () => {},
+    },
+    exec: () => ({ ok: true }), writeFile: () => ({ ok: true }),
+    checkDnsTokenScope: async () => ({ reachable: true, zone: 'z' }), checkCaddyWiring: () => null,
+  };
+  await P.cmdRunIntents(deps);
+  return { resolved, classWrites };
+};
+
+await ta('a re-pended core move records its failure class and reason', async () => {
+  const { resolved, classWrites } = await classifiedRun(1);
+  assert.equal(resolved.length, 0);
+  assert.deepEqual(classWrites, [[11, 'needs_decision', 'shape_not_automated']]);
+});
+
+await ta('a RETIRED core move records its failure class and reason too', async () => {
+  const { resolved, classWrites } = await classifiedRun(3); // = MAX_INTENT_ATTEMPTS: the last real attempt, retired after it runs
+  assert.equal(resolved[0].state, 'error');
+  assert.deepEqual(classWrites, [[11, 'needs_decision', 'shape_not_automated']]);
+});
+
 console.log('\nreview-panel hardening (task 1002720 — the loopback/latch/birth-note seams):');
 
 await ta('a PASSING loopback probe on a DOMAIN-bearing instance records NO verdict — the address claim belongs to the sweep', async () => {