@bongos/core 1.20.29 → 1.20.30

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.29",
-  "core_contract": "1.20.29",
-  "source_commit": "c6152c075da2e7e656381b46f3f9b561cf65f457",
+  "core_version": "1.20.30",
+  "core_contract": "1.20.30",
+  "source_commit": "b56a05d974ae5208394507078971bf8e22f415f3",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T20:49:43.614Z",
+  "built_at": "2026-09-30T21:06:55.806Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 562,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2660,
+    "functional_verbatim": 2663,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3248,
-  "tree_sha256": "91a5ebee3fc044967031c6f7dbb8e2a86b98fe305e68353f39c023c5ab042df9",
+  "file_count": 3251,
+  "tree_sha256": "3b45f4c67302ad870157396c60f693712b46bcdc86a9236e964c914418657c35",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "7fab447c04933dbbe8ee8f154f854f15eb834163ae656799e5ff3c8f3756fdfc"
+      "sha256": "fca494d7f518bc42742fde6c5ba2e45cfbf0605d5a7a79024bba190ec4c3c1da"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7282,7 +7282,7 @@
     {
       "path": "modules/provisioning/core-upgrade.js",
       "mode": "0000644",
-      "sha256": "8adf8842f6058224aeac88f54202cf4e7ed26f0021c44cf9bf1f94098b12ce07"
+      "sha256": "7604ea4c137c5c1cedca41329cfd6fce49458d454f2e956944f7fb8d0c4ab10a"
     },
     {
       "path": "modules/provisioning/cost-ledger.js",
@@ -7459,6 +7459,11 @@
       "mode": "0000644",
       "sha256": "b667ec5165e611bd6f0d86b09465c5d9e632de853becce139bac49f5a88e5c1e"
     },
+    {
+      "path": "modules/provisioning/migrations/provisioning_030_intent_failure_class.sql",
+      "mode": "0000644",
+      "sha256": "7287181b4b42d3e391cd97e19ffa5fbc76026e81ad6f54648eb12a69dfea55a1"
+    },
     {
       "path": "modules/provisioning/module.json",
       "mode": "0000644",
@@ -8977,12 +8982,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "eb1cd0418a763ae11ad580a788df78980c6f19e4953d543e2111f4543d53a8ac"
+      "sha256": "872b4c6ad6eacb09cbcd5698c892fc798ce6e632b505304b5665c7f04ea99325"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "3aefd305535d6f2fc5f8a09ca30b7a6ae323e7f120008618e01d1c772198a363"
+      "sha256": "6c29a554265b6c3e6fa7f29fbf9b334c3a73e30b240b393498b89304876b5495"
     },
     {
       "path": "public-docs/index.html",
@@ -9002,7 +9007,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "84ae8d8349b19fc436952c1455536f608f5804eca0a4b934d0b66555f72baef0"
+      "sha256": "1ce998432070110f9c3a9b128145bf8d44c032aa2ff55437207ecaf5efe8943a"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9962,7 +9967,7 @@
     {
       "path": "scripts/gds/provision-core-upgrade.js",
       "mode": "0000644",
-      "sha256": "3adfb1d93ac59f1a057bcfc55fbeb1ac1cfcb6b8148c4ce6551de9bf743c878b"
+      "sha256": "58599968201f98723a531c19f77985c0b26b9afa6d6448ae4803074497a6f2ad"
     },
     {
       "path": "scripts/gds/provision-disconnect.js",
@@ -10017,7 +10022,7 @@
     {
       "path": "scripts/gds/provision.js",
       "mode": "0000644",
-      "sha256": "8f03f6c0e043ba7d80e6c4543cc0d6abc8b2ccb8d4a7e40e814a6a14d6859440"
+      "sha256": "0f7a9cd81a78ef3ed30a40e9f048f8905b6a88e99a930f7cbdcdcd5c1661f71d"
     },
     {
       "path": "scripts/gds/publish-credential-check.js",
@@ -10629,10 +10634,15 @@
       "mode": "0000644",
       "sha256": "1f0a8d52622328e29bd3bdbe0402f680f425480e37e29ee42ceee907368710af"
     },
+    {
+      "path": "scripts/gds/upgrade-outcome.js",
+      "mode": "0000644",
+      "sha256": "a4f05b5e1042cf3d8c7096ef413b47fd039a02b78f2e4dbefb5bd002973784cb"
+    },
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "cde9fb1f13e660981e6b6431edd399b4fbcd457cf2ff3ca6a01e92937fdbc746"
+      "sha256": "399c2225543fc0d37505bca9cd96e33cf5598aa1f364a458d5b5efb3a588ddb3"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -11122,7 +11132,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "e8f28de6e2a1dbb5dead24503e6da1e013dd36a4a27c0dea9382480fdfdbb7e6"
+      "sha256": "4002317dabfa7084c1b541e2a6a605197ce8c1e45df90f81bfa2ef186b0d6776"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12067,7 +12077,7 @@
     {
       "path": "tests/core_upgrade_door.mjs",
       "mode": "0000644",
-      "sha256": "0bbd0f6bcecfb8c88e69256470610f40eb64ec555a67502b3172d69a220fc12b"
+      "sha256": "24f41ed750fc24003e31cd1e551256162119016ab299a94dda5e4c4fe030ff69"
     },
     {
       "path": "tests/core_upgrade_owner_door.mjs",
@@ -12077,7 +12087,7 @@
     {
       "path": "tests/core_upgrade_runner.mjs",
       "mode": "0000644",
-      "sha256": "f55d142db2f3207eb1b1dc7e06c978cb22a282ff0d16792808d212948993640a"
+      "sha256": "525e38bbafc2dd1419f3e41131dd89c6adc4f063f8585b193e2be72801bede5a"
     },
     {
       "path": "tests/cosmos_token_contrast.mjs",
@@ -14692,7 +14702,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "ad4c6e5d4dd342e8c2b183c6decd7a38c976b207b30e211042bed0a42f3f5f17"
+      "sha256": "6b4405a5a4e0263f321a49e04d25cad87a042d5d9a296ba65ff3d14a1941deb0"
     },
     {
       "path": "tests/provision_account_identity.mjs",
@@ -16094,6 +16104,11 @@
       "mode": "0000644",
       "sha256": "d3f5b941b89ede78ebb3cd7af43467363e5d6c6d35c7ad26a2977683ecf869e7"
     },
+    {
+      "path": "tests/upgrade_outcome.mjs",
+      "mode": "0000644",
+      "sha256": "cec960e84573efe77003beb324c0679900f321249148418e7a04daf7a7a40215"
+    },
     {
       "path": "tests/upgrade_persist_pin.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2715,5 +2715,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.27 with no explicit bump. run 36772266063. (task 1002620)
   1.20.29 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.28 with no explicit bump. run 36775277990. (task 1002620)
+  1.20.30 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.29 with no explicit bump. run 36777226204. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/core-upgrade.js

@@ -361,6 +361,11 @@ function previewFromSnapshot(inst, snap, openIntent, lastMove) {
       // `git status` (the dirty-tree one lists every file). Never set on a DONE move:
       // a done row's last_error is the note below, and a move that worked is not an error.
       error: lastMove.state !== 'done' && lastMove.last_error ? String(lastMove.last_error).slice(0, 600) : null,
+      // WHAT KIND of failure it was (task 1004446, migration provisioning_030): the class the
+      // page and the self-heal steps key on, and its fixed reason code. null on a move that
+      // worked, and on one resolved before the columns existed.
+      failure: lastMove.state !== 'done' && lastMove.failure_class
+        ? { class: lastMove.failure_class, reason: lastMove.failure_reason || null } : null,
       // It LANDED, but GitHub did not get the new pin (task 1004065) — parseRepoNote.
       warning: lastMove.state === 'done' ? parseRepoNote(lastMove.last_error) : null,
     } : null,

package/modules/provisioning/migrations/provisioning_030_intent_failure_class.sql

@@ -0,0 +1,28 @@
+-- provisioning_030_intent_failure_class.sql — WHAT KIND of failure stopped an intent
+-- (task 1004446, goal 1000090 deploy self-heal).
+--
+-- WHY. A failed core move was one sentence in last_error, and every non-zero exit read
+-- "failed and was rolled back" — a refusal that changed nothing, a real rollback, and a
+-- rollback that itself failed were indistinguishable to the runner and to the page. These
+-- two columns carry scripts/gds/upgrade-outcome.js's classification beside the sentence:
+--
+--   failure_class   transient | known_wedge | needs_decision | unknown — what the runner
+--                   may do about it (retry later, fix it itself, ask the owner, ask a person)
+--   failure_reason  a fixed reason code (dirty_tree, outside_channel, rollback_failed, …) —
+--                   vocabulary only, never free text, so it is safe to index and to show
+--
+-- NULL on both means "not a classified failure": a done intent, a pending one, or a row
+-- written before this migration. Written by the drain loop (scripts/gds/provision.js).
+--
+-- Additive and namespaced (ADR 0083): no down-migration, idempotent — safe to re-run.
+
+BEGIN;
+
+ALTER TABLE provisioning_intents ADD COLUMN IF NOT EXISTS failure_class text;
+ALTER TABLE provisioning_intents ADD COLUMN IF NOT EXISTS failure_reason text;
+
+ALTER TABLE provisioning_intents DROP CONSTRAINT IF EXISTS provisioning_intents_failure_class_check;
+ALTER TABLE provisioning_intents ADD CONSTRAINT provisioning_intents_failure_class_check
+  CHECK (failure_class IS NULL OR failure_class IN ('transient', 'known_wedge', 'needs_decision', 'unknown'));
+
+COMMIT;

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.29",
+  "version": "1.20.30",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.29",
+      "version": "1.20.30",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.29",
+  "version": "1.20.30",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -8246,5 +8246,11 @@
       "id": "1004445",
       "text": "Each project now has its own update rule. A project can be allowed to take bigger step-up updates (like 1.19 to 1.20) instead of being stuck on small fixes only, and its owner can change the rule."
     }
+  ],
+  "1.20.30": [
+    {
+      "id": "1004446",
+      "text": "When a software update fails, the system now records what kind of failure it was — a temporary glitch, a known snag, a rule only the owner can change, or something unknown — and tells the truth about it instead of always sayin"
+    }
   ]
 }

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
@@ -150,6 +151,12 @@ 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
@@ -189,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
@@ -198,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
@@ -209,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 -----------------------------------------
@@ -227,7 +234,7 @@ async function coreUpgradeInstance(inst, deps, intent) {
   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.
@@ -265,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) --------------------------------
@@ -287,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) ----

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.29'; // 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

@@ -964,5 +964,14 @@ await t('the route is gated like the move: the owner door OR core.pin.move', ()
   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

@@ -1449,5 +1449,71 @@ await t('the snapshot OFFERS what the project\'s rule admits — the button and
   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 () => {

package/tests/upgrade_outcome.mjs

@@ -0,0 +1,129 @@
+// tests/upgrade_outcome.mjs — every failed core move gets a class and honest wording
+// (task 1004446, goal 1000090 deploy self-heal).
+//
+// WHAT IS AT RISK. The deploy page said "failed and was rolled back" for every exit of
+// `bongos upgrade`, including refusals that changed nothing and rollbacks that themselves
+// failed. The rest of the self-heal chain (retry later, fix it, escalate) keys on the class
+// this file assigns, so a mislabel there is a retry of something that must not be retried,
+// or an automatic "fix" for something that needed a person.
+//
+// Run:  node tests/upgrade_outcome.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import {
+  outcomeLine, parseOutcomeLine, upgradeReason, upgradeStage, classifyFailure, runnerReason,
+  describeUpgradeFailure, FAILURE_CLASSES, REASON_CLASS, STAGES, OUTCOME_TAG,
+} from '../scripts/gds/upgrade-outcome.js';
+
+const require = createRequire(import.meta.url);
+const R = require('../scripts/gds/provision-core-upgrade.js');
+
+let passed = 0;
+let failed = 0;
+const t = async (name, fn) => {
+  try { await fn(); passed += 1; console.log(`  PASS  ${name}`); }
+  catch (e) { failed += 1; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+
+// Each row: an upgrade.js failure result as runUpgrade returns it → the stage, reason and
+// class it must get. These are the branches of runUpgrade's failure table (upgrade.js).
+const OK_RB = { restoreOk: true, reinstallOk: true, restartOk: true, healthOk: true };
+const TABLE = [
+  ['downgrade refusal', { ok: false, downgrade: true, error: 'refusing to DOWNGRADE: --to 1.19.1 is older' }, 'refused', 'downgrade', 'needs_decision'],
+  ['already on the target', { ok: false, error: 'already on 1.20.1 (pass --force to re-run the steps anyway)' }, 'refused', 'already_on', 'unknown'],
+  ['dirty working tree', { ok: false, error: 'working tree not clean — commit/stash first, or pass --force.\n M package.json' }, 'refused', 'dirty_tree', 'known_wedge'],
+  ['module pre-check', { ok: false, error: 'module pre-check failed: game incompatible with core 1.20.1' }, 'refused', 'module_incompatible', 'needs_decision'],
+  ['database unresolvable', { ok: false, error: 'cannot determine which database to migrate.\n    Set PGDATABASE' }, 'refused', 'db_unresolvable', 'unknown'],
+  ['database identity', { ok: false, error: 'database "cb" is not reachable as the current user: role "root" does not exist' }, 'refused', 'db_identity', 'unknown'],
+  ['artist gate hold', { ok: false, artistGate: true, error: 'a visual review is holding this deploy' }, 'refused', 'artist_gate', 'needs_decision'],
+  ['health url missing', { ok: false, error: 'post-restart health check is mandatory for a bump that restarts the service' }, 'refused', 'health_url_missing', 'unknown'],
+  ['npm install failed, rolled back', { ok: false, error: 'npm install failed (exit 1)', rolledBack: true, rollback: OK_RB }, 'rolled_back', 'npm_install', 'transient'],
+  ['disk full, rolled back', { ok: false, error: 'npm install failed (ENOSPC: no space left on device)', rolledBack: true, rollback: OK_RB }, 'rolled_back', 'disk_full', 'known_wedge'],
+  ['integrity pin mismatch', { ok: false, error: 'integrity pin MISMATCH (side-car) — installed core does not match its pin: x', rolledBack: true, rollback: OK_RB }, 'rolled_back', 'integrity_pin', 'unknown'],
+  ['migrate failed', { ok: false, error: 'migrate failed (exit 3)', rolledBack: true, rollback: OK_RB }, 'rolled_back', 'migrate', 'unknown'],
+  ['restart failed', { ok: false, error: 'restart failed (exit 1) — the instance is still running the previous core', rolledBack: true, rollback: OK_RB }, 'rolled_back', 'restart', 'unknown'],
+  ['health failed', { ok: false, error: 'health check failed after restart — rolled back to 1.19.1081', rolledBack: true, rollback: OK_RB }, 'rolled_back', 'health', 'unknown'],
+  ['served version unchanged', { ok: false, error: 'served core version did not change (still 1.19.1081, expected 1.20.1) — rolled back', rolledBack: true, rollback: OK_RB }, 'rolled_back', 'health', 'unknown'],
+  ['ROLLBACK FAILED (health still bad)', { ok: false, error: 'health check failed after restart — rolled back', rolledBack: true, rollback: { ...OK_RB, healthOk: false } }, 'rollback_failed', 'rollback_failed', 'unknown'],
+  ['ROLLBACK FAILED (reinstall)', { ok: false, error: 'migrate failed (exit 3)', rolledBack: true, rollback: { ...OK_RB, reinstallOk: false } }, 'rollback_failed', 'rollback_failed', 'unknown'],
+];
+
+console.log('\nevery branch of the upgrade failure table:');
+
+for (const [name, res, stage, reason, cls] of TABLE) {
+  await t(`${name} → ${stage} / ${reason} / ${cls}`, () => {
+    const o = parseOutcomeLine(outcomeLine(res));
+    assert.deepEqual(o, { stage, reason });
+    assert.equal(classifyFailure(o.reason).class, cls);
+  });
+}
+
+console.log('\nthe vocabulary:');
+
+await t('every reason maps to one of the four classes', () => {
+  for (const [r, c] of Object.entries(REASON_CLASS)) assert.ok(FAILURE_CLASSES.includes(c), `${r} → ${c}`);
+});
+
+await t('an unlisted reason is unknown — the safe direction', () => {
+  assert.deepEqual(classifyFailure('something_new'), { class: 'unknown', reason: 'unknown' });
+  assert.deepEqual(classifyFailure(undefined), { class: 'unknown', reason: 'unknown' });
+  assert.deepEqual(classifyFailure('__proto__'), { class: 'unknown', reason: 'unknown' });
+});
+
+await t('the migration CHECK carries exactly the four classes', async () => {
+  const { readFileSync } = await import('node:fs');
+  const sql = readFileSync(new URL('../modules/provisioning/migrations/provisioning_030_intent_failure_class.sql', import.meta.url), 'utf8');
+  for (const c of FAILURE_CLASSES) assert.match(sql, new RegExp(`'${c}'`));
+});
+
+await t('a stage is only what upgrade.js reports: no rollback flag means nothing moved', () => {
+  assert.equal(upgradeStage({ ok: false, error: 'x' }), 'refused');
+  assert.equal(upgradeStage({ ok: false, rolledBack: true, rollback: OK_RB }), 'rolled_back');
+  assert.equal(upgradeStage({ ok: false, rolledBack: true, rollback: { restartOk: false } }), 'rollback_failed');
+  assert.equal(upgradeReason(null), 'unknown');
+});
+
+await t('parseOutcomeLine takes the LAST line, and refuses anything off-vocabulary', () => {
+  const two = `${OUTCOME_TAG} {"stage":"refused","reason":"dirty_tree"}\nnoise\n${OUTCOME_TAG} {"stage":"rolled_back","reason":"migrate"}\n`;
+  assert.deepEqual(parseOutcomeLine(two), { stage: 'rolled_back', reason: 'migrate' });
+  assert.equal(parseOutcomeLine('no tag here'), null);
+  assert.equal(parseOutcomeLine(`${OUTCOME_TAG} {"stage":"exploded","reason":"x"}`), null);
+  assert.equal(parseOutcomeLine(`${OUTCOME_TAG} {"stage":"refused","reason":"<script>"}`), null);
+  assert.equal(parseOutcomeLine(`${OUTCOME_TAG} not json`), null);
+  assert.deepEqual([...STAGES], ['refused', 'rolled_back', 'rollback_failed']);
+});
+
+await t('the runner\'s own refusals get their reason from targetFault\'s sentences', () => {
+  assert.equal(runnerReason(R.targetFault('1.20.1', [], '1.19.1', 'patch', () => true)), 'registry_unreadable');
+  assert.equal(runnerReason(R.targetFault('1.20.1', ['1.19.1'], '1.19.1', 'patch', () => true)), 'not_published');
+  assert.equal(runnerReason(R.targetFault('1.20.1', ['1.20.1'], null, 'patch', () => true)), 'installed_unreadable');
+  assert.equal(runnerReason(R.targetFault('1.20.1', ['1.20.1'], '1.19.1', 'patch', () => false)), 'outside_channel');
+});
+
+console.log('\nthe wording says what happened, and no more:');
+
+await t('a refusal never says "rolled back"', () => {
+  const s = describeUpgradeFailure('1.20.1', { stage: 'refused', reason: 'dirty_tree' }, 'working tree not clean');
+  assert.doesNotMatch(s, /rolled back/);
+  assert.match(s, /refused before anything changed/);
+});
+
+await t('a real rollback says so', () => {
+  assert.match(describeUpgradeFailure('1.20.1', { stage: 'rolled_back', reason: 'migrate' }, 'migrate failed'), /failed and was rolled back/);
+});
+
+await t('a failed rollback says the project may be down and needs a person', () => {
+  const s = describeUpgradeFailure('1.20.1', { stage: 'rollback_failed', reason: 'rollback_failed' }, '');
+  assert.match(s, /rollback did not finish/);
+  assert.match(s, /needs a person/);
+});
+
+await t('no outcome line claims nothing about a rollback', () => {
+  const s = describeUpgradeFailure('1.20.1', null, 'sudo: unknown user bongos-test4');
+  assert.doesNotMatch(s, /rolled back/);
+  assert.match(s, /did not report how far it got/);
+});
+
+console.log(`\nupgrade_outcome: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);