@bongos/core 1.20.29 → 1.20.31

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.31",
+  "core_contract": "1.20.31",
+  "source_commit": "7d9880eac50e580874638a8cca10da6606c18228",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T20:49:43.614Z",
+  "built_at": "2026-09-30T21:24:24.438Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 562,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2660,
+    "functional_verbatim": 2666,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3248,
-  "tree_sha256": "91a5ebee3fc044967031c6f7dbb8e2a86b98fe305e68353f39c023c5ab042df9",
+  "file_count": 3254,
+  "tree_sha256": "88a5431f2eb9f9248c57014423f4881035e2d1b9a6cee88740a6800ab933ba38",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "7fab447c04933dbbe8ee8f154f854f15eb834163ae656799e5ff3c8f3756fdfc"
+      "sha256": "fd78a2ab7d52f77fbd7181a64af68b8cf4c45c25693bf7dbf31e1b9bba69ada7"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7282,7 +7282,7 @@
     {
       "path": "modules/provisioning/core-upgrade.js",
       "mode": "0000644",
-      "sha256": "8adf8842f6058224aeac88f54202cf4e7ed26f0021c44cf9bf1f94098b12ce07"
+      "sha256": "5467ab673dfad5969dec0029188d0be18ea82732a26f99bca720de6680e1d618"
     },
     {
       "path": "modules/provisioning/cost-ledger.js",
@@ -7459,6 +7459,16 @@
       "mode": "0000644",
       "sha256": "b667ec5165e611bd6f0d86b09465c5d9e632de853becce139bac49f5a88e5c1e"
     },
+    {
+      "path": "modules/provisioning/migrations/provisioning_030_intent_failure_class.sql",
+      "mode": "0000644",
+      "sha256": "7287181b4b42d3e391cd97e19ffa5fbc76026e81ad6f54648eb12a69dfea55a1"
+    },
+    {
+      "path": "modules/provisioning/migrations/provisioning_031_intent_not_before.sql",
+      "mode": "0000644",
+      "sha256": "a93d8946cbe4631b2af64b2e3638dca188981032a08f5d29d63e4d0adb22d235"
+    },
     {
       "path": "modules/provisioning/module.json",
       "mode": "0000644",
@@ -7507,7 +7517,7 @@
     {
       "path": "modules/provisioning/provisioning.js",
       "mode": "0000644",
-      "sha256": "f2dd673e30cf17abbfbadd3c0142616a1c40b3b680c865b57db8330933816405"
+      "sha256": "fb4f09b621654eebe595dcbca305773ea11ed063506a6e4116391e43566a540d"
     },
     {
       "path": "modules/provisioning/public-refusal.js",
@@ -8977,12 +8987,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "eb1cd0418a763ae11ad580a788df78980c6f19e4953d543e2111f4543d53a8ac"
+      "sha256": "892ad66ccaa864ee07860cd8578f134a72f8cc48625f728f186eaa0f994ac8ad"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "3aefd305535d6f2fc5f8a09ca30b7a6ae323e7f120008618e01d1c772198a363"
+      "sha256": "fdebee1582c5673a44b97471f05814ab6bc8e850958ca3131e4a356f3a663d90"
     },
     {
       "path": "public-docs/index.html",
@@ -9002,7 +9012,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "84ae8d8349b19fc436952c1455536f608f5804eca0a4b934d0b66555f72baef0"
+      "sha256": "4398d89d420cf704f3030db8752e1f9e67321e43e49b0765e23329c26160385e"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9734,6 +9744,11 @@
       "mode": "0000644",
       "sha256": "7b2402543c3b1eadbafc14907e6dc6689b434ac65fb9c709115dd81a92eb13eb"
     },
+    {
+      "path": "scripts/gds/intent-retry.js",
+      "mode": "0000644",
+      "sha256": "056622ecd8327527f4fb98b37ce8af90778d42c816455431ed3dd2f76800a75b"
+    },
     {
       "path": "scripts/gds/key-card.js",
       "mode": "0000644",
@@ -9962,7 +9977,7 @@
     {
       "path": "scripts/gds/provision-core-upgrade.js",
       "mode": "0000644",
-      "sha256": "3adfb1d93ac59f1a057bcfc55fbeb1ac1cfcb6b8148c4ce6551de9bf743c878b"
+      "sha256": "58599968201f98723a531c19f77985c0b26b9afa6d6448ae4803074497a6f2ad"
     },
     {
       "path": "scripts/gds/provision-disconnect.js",
@@ -10017,7 +10032,7 @@
     {
       "path": "scripts/gds/provision.js",
       "mode": "0000644",
-      "sha256": "8f03f6c0e043ba7d80e6c4543cc0d6abc8b2ccb8d4a7e40e814a6a14d6859440"
+      "sha256": "4da6314b41905bcffbc51abe127911512743ad14f8130b4c6a25c23600a3eb7f"
     },
     {
       "path": "scripts/gds/publish-credential-check.js",
@@ -10629,10 +10644,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 +11142,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "e8f28de6e2a1dbb5dead24503e6da1e013dd36a4a27c0dea9382480fdfdbb7e6"
+      "sha256": "8acd38044812dee3022427fad27e12cc7f9d81a90c1a0d921e860135a30f9e43"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12067,7 +12087,7 @@
     {
       "path": "tests/core_upgrade_door.mjs",
       "mode": "0000644",
-      "sha256": "0bbd0f6bcecfb8c88e69256470610f40eb64ec555a67502b3172d69a220fc12b"
+      "sha256": "8c8b03b8a3bb83b0c733726f3aa1256b6af5ac61c76e6af465fe2bc4f792ea6b"
     },
     {
       "path": "tests/core_upgrade_owner_door.mjs",
@@ -12077,7 +12097,7 @@
     {
       "path": "tests/core_upgrade_runner.mjs",
       "mode": "0000644",
-      "sha256": "f55d142db2f3207eb1b1dc7e06c978cb22a282ff0d16792808d212948993640a"
+      "sha256": "525e38bbafc2dd1419f3e41131dd89c6adc4f063f8585b193e2be72801bede5a"
     },
     {
       "path": "tests/cosmos_token_contrast.mjs",
@@ -13734,6 +13754,11 @@
       "mode": "0000644",
       "sha256": "9e69603c05fae6c39e2db7336d6569327f17365ff46ef05b1074943dc34a49e7"
     },
+    {
+      "path": "tests/intent_retry.mjs",
+      "mode": "0000644",
+      "sha256": "750745cf866dcf1012f2677881738aa64ae2b8ceaed078ab688612a8b0d2208c"
+    },
     {
       "path": "tests/interaction_posture.mjs",
       "mode": "0000644",
@@ -14692,7 +14717,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "ad4c6e5d4dd342e8c2b183c6decd7a38c976b207b30e211042bed0a42f3f5f17"
+      "sha256": "46b2235ee186ba304c18f5cf3002a9e5311f7bda11fa230bbada8a7a43bec3cd"
     },
     {
       "path": "tests/provision_account_identity.mjs",
@@ -16094,6 +16119,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,9 @@ 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)
+  1.20.31 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.30 with no explicit bump. run 36779142919. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/core-upgrade.js

@@ -128,6 +128,16 @@ function coreUpgradeFault(inst, to, live = null) {
 async function enqueueCoreUpgrade(provisioning, db, instanceId, to, requestedBy, action = 'core-upgrade') {
   const { intent, created } = await provisioning.enqueueIntent(db, instanceId, action, requestedBy, to);
   if (created) return { intent, created: true };
+  // THE SAME MOVE, WAITING OUT A RETRY (task 1004447). A transient failure re-pends the
+  // intent with a not_before up to six hours away, and it keeps the single open slot all
+  // that time — so without this, the owner pressing Move again was told "a run is pending,
+  // try again later" about the very move they were asking for. Same action, same target,
+  // still pending: bring its next attempt forward instead. Anything else stays a conflict.
+  if (intent && intent.state === 'pending' && intent.action === action && String(intent.target_version || '') === String(to)
+    && intent.not_before && new Date(intent.not_before).getTime() > Date.now()) {
+    await db.query("UPDATE provisioning_intents SET not_before = NULL, updated_at = now() WHERE id = $1 AND state = 'pending'", [intent.id]);
+    return { intent: { ...intent, not_before: null }, created: false, retryNow: true };
+  }
   return { intent, created: false, conflict: 'open_intent' };
 }
 
@@ -336,7 +346,9 @@ function previewFromSnapshot(inst, snap, openIntent, lastMove) {
     // and a stale pass is worse than no answer because it reads as a guarantee.
     preflight: preflightForOffer(pf, served, recommended),
     preflight_at: pf && recommended && pf.target === recommended ? (snap.preflight_at || null) : null,
-    open_intent: openIntent ? { action: openIntent.action, state: openIntent.state, target_version: openIntent.target_version || null } : null,
+    // not_before: a failed move waiting out its retry backoff (task 1004447) — the page can
+    // say "trying again at …" instead of an unexplained "pending" for up to six hours.
+    open_intent: openIntent ? { action: openIntent.action, state: openIntent.state, target_version: openIntent.target_version || null, not_before: openIntent.not_before || null, last_error: openIntent.not_before && openIntent.last_error ? String(openIntent.last_error).slice(0, 600) : null } : null,
     // THE LAST MOVE, WHATEVER BECAME OF IT (task 1004145).
     //
     // `open_intent` is `state IN ('pending','running')` — by the index's own definition.
@@ -361,6 +373,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/modules/provisioning/migrations/provisioning_031_intent_not_before.sql

@@ -0,0 +1,19 @@
+-- provisioning_031_intent_not_before.sql — a failed intent waits before its next attempt
+-- (task 1004447, goal 1000090 deploy self-heal).
+--
+-- WHY. A failed intent was re-pended with no delay, and the drain loop claims the oldest
+-- pending row — so one runner tick ran the same failing move up to MAX_INTENT_ATTEMPTS
+-- times back to back, restarting the service each time a pin had moved, and then gave up.
+-- A registry blip or a release still publishing needs minutes, not milliseconds.
+--
+-- not_before: the earliest time the runner may claim this row again. NULL = now (every row
+-- written before this column, and every fresh request). claimNextIntent skips a row whose
+-- not_before is still in the future; scripts/gds/provision.js sets it on each re-pend.
+--
+-- Additive and namespaced (ADR 0083): no down-migration, idempotent — safe to re-run.
+
+BEGIN;
+
+ALTER TABLE provisioning_intents ADD COLUMN IF NOT EXISTS not_before timestamptz;
+
+COMMIT;

package/modules/provisioning/provisioning.js

@@ -1254,7 +1254,7 @@ async function claimNextIntent(db) {
         SET state = 'running', attempts = attempts + 1, updated_at = now()
       WHERE id = (
         SELECT id FROM provisioning_intents
-         WHERE state = 'pending'
+         WHERE state = 'pending' AND (not_before IS NULL OR not_before <= now()) -- a re-pended failure waits out its backoff (task 1004447)
          ORDER BY created_at
          FOR UPDATE SKIP LOCKED
          LIMIT 1

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.29",
+  "version": "1.20.31",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.29",
+      "version": "1.20.31",
       "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.31",
   "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,17 @@
       "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"
+    }
+  ],
+  "1.20.31": [
+    {
+      "id": "1004447",
+      "text": "A software update that fails for a temporary reason now waits and tries again later — after 15 minutes, then an hour, then six hours — instead of hammering the same failing step three times in a row. Failures that retrying can"
+    }
   ]
 }

package/scripts/gds/intent-retry.js

@@ -0,0 +1,52 @@
+'use strict';
+//
+// scripts/gds/intent-retry.js — when a failed provisioning intent is tried again, and when it
+// is retired instead (task 1004447, goal 1000090 deploy self-heal).
+//
+// WHY. The drain loop re-pended a failure with no delay and claims the oldest pending row, so
+// one tick ran the same failing move up to MAX_INTENT_ATTEMPTS times back to back — seconds
+// apart, restarting the service after every pin move — and then gave up. That is the wrong
+// answer for each kind of failure upgrade-outcome.js now names:
+//   transient       — the registry blipped, the release is still publishing: WAIT, then retry
+//                     (about 15 minutes, 1 hour, 6 hours), which is what a person would do.
+//   known_wedge, needs_decision, unknown — trying the same thing again cannot change the
+//                     answer, so the intent is RETIRED at once and the failure left standing
+//                     for the next step (a fix, the owner, a person) to act on.
+// A failure with no class (every action other than a core move) keeps its old attempt budget,
+// but each retry now waits DEFAULT_RETRY_DELAY_MS — at least the next tick, never the same one.
+//
+// PURE: no I/O. The drain loop (scripts/gds/provision.js cmdRunIntents) asks and obeys.
+
+const MINUTE = 60 * 1000;
+const TRANSIENT_BACKOFF_MS = Object.freeze([15 * MINUTE, 60 * MINUTE, 6 * 60 * MINUTE]);
+const DEFAULT_RETRY_DELAY_MS = MINUTE;
+
+/**
+ * What to do with an intent whose run just failed. PURE.
+ * @param {object} p
+ * @param {number} p.attempts     the attempt that just ran (claimNextIntent increments first)
+ * @param {object} [p.failure]    `{ class, reason }` from the result, when classified
+ * @param {boolean} [p.terminal]  the leg said it must not be retried unattended
+ * @param {number} p.maxAttempts  the runner's budget for unclassified failures
+ * @returns {{ action: 'retire' } | { action: 'retry', delayMs: number }}
+ */
+function retryDecision({ attempts, failure, terminal, maxAttempts }) {
+  if (terminal) return { action: 'retire' };
+  if (failure && failure.class) {
+    if (failure.class !== 'transient') return { action: 'retire' };
+    const i = Math.max(0, (attempts || 1) - 1);
+    return i < TRANSIENT_BACKOFF_MS.length ? { action: 'retry', delayMs: TRANSIENT_BACKOFF_MS[i] } : { action: 'retire' };
+  }
+  return (attempts || 0) >= maxAttempts ? { action: 'retire' } : { action: 'retry', delayMs: DEFAULT_RETRY_DELAY_MS };
+}
+
+/**
+ * The attempt ceiling checked BEFORE an intent runs. A row waiting out a transient backoff
+ * has one attempt per backoff step plus the first, so the pre-run guard must not retire it
+ * on the default budget before its last scheduled try. PURE.
+ */
+function maxAttemptsFor(intent, maxAttempts) {
+  return intent && intent.failure_class === 'transient' ? Math.max(maxAttempts, TRANSIENT_BACKOFF_MS.length + 1) : maxAttempts;
+}
+
+module.exports = { TRANSIENT_BACKOFF_MS, DEFAULT_RETRY_DELAY_MS, retryDecision, maxAttemptsFor };

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

@@ -46,6 +46,7 @@ const path = require('node:path');
 const cp = require('node:child_process');
 const crypto = require('node:crypto');
 
+const retry = require('./intent-retry.js'); // when a failed intent is tried again (task 1004447)
 const { CONFIG, MANIFEST_UA, softFailResult, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, MAX_INTENT_ATTEMPTS, REPO_ROOT, coreVersionSafe, hasFlag, loadDeps, oauthSecret, provisionerBotEmail } = require('./provision-config.js');
 const { accountPreflight, appUser, alreadyScaffolded, buildCorePinRefreshCommit, coreCheckoutHasGit, dbCreateCmd, dbName, dbRoleCmd, dbRoleCmdShown, dbRoleGrantsCmd, ensureInstanceUserCmd, generateDbPassword, grantInstanceRepoReadCmd, instanceDbRole, instanceStateDir, instanceUser, deployKeyPath, deployKeyTitle, ensurePrivateRepoAccess, installedCorePackDir, installedCoreTarball, instanceInitSpec, instanceRepoRemote, migrateCmd, onboardMode, ownerLoginOf, parseTargetRef, planCorePinRefresh, refreshStandaloneCorePin, resolveOwnerGithubToken, resolveVendorableCoreTarball, safeVersionLabel, scaffoldStandaloneRepo, seedFirstVersionCmd, standaloneInstallCmd, standaloneMigrateCmd, standalonePullCmd, standaloneRegenDocsCmd, standaloneRoot } = require('./provision-repo.js');
 const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, renamedEnvCarry, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
@@ -1171,8 +1172,8 @@ async function cmdRunIntents(deps) {
     const intent = await provisioning.claimNextIntent(db);
     if (!intent) break;
     ran++;
-    if (intent.attempts > MAX_INTENT_ATTEMPTS) {
-      await provisioning.resolveIntent(db, intent.id, 'error', `exceeded ${MAX_INTENT_ATTEMPTS} attempts`);
+    if (intent.attempts > retry.maxAttemptsFor(intent, MAX_INTENT_ATTEMPTS)) { // a transient core move gets one try per backoff step (task 1004447)
+      await provisioning.resolveIntent(db, intent.id, 'error', `exceeded ${retry.maxAttemptsFor(intent, MAX_INTENT_ATTEMPTS)} attempts`);
       errors++; log(`  ✖ intent #${intent.id} retired (too many attempts)`); continue;
     }
     try {
@@ -1192,7 +1193,11 @@ async function cmdRunIntents(deps) {
       else if (intent.action === 'repo-private' || intent.action === 'render-standup') result = intent.action === 'repo-private' ? await require('./provision-repo-private.js').repoPrivateInstance(inst, deps) : await require('./provision-render.js').renderStandupInstance(inst, deps, intent); // wire the deploy key, THEN flip (task 1004193) · spend the borrowed Render key once (task 1004183); required here — this file is at the size ratchet
       else result = { ok: false, error: `unknown_action '${intent.action}' — runner core ${coreVersionSafe() || '?'} does not know it (runner too old?); refusing to guess` };
       if (result && result.ok === false) {
-        if (intent.attempts >= MAX_INTENT_ATTEMPTS || result.terminal) { // terminal: a leg that must not be retried unattended (the Render leg's key is already gone — task 1004183)
+        // WAIT OR RETIRE (task 1004447, intent-retry.js): a transient failure waits ~15m/1h/6h; a
+        // classified non-transient one is retired at once (retrying cannot change its answer);
+        // an unclassified one keeps its budget but never re-runs in the same tick.
+        const next = retry.retryDecision({ attempts: intent.attempts, failure: result.failure, terminal: result.terminal, maxAttempts: MAX_INTENT_ATTEMPTS });
+        if (next.action === 'retire') { // terminal: a leg that must not be retried unattended (the Render leg's key is already gone — task 1004183)
           await provisioning.resolveIntent(db, intent.id, 'error', result.error || 'op failed');
           // A retired intent stops silently otherwise (F19): record the reason
           // on the instance WITHOUT changing its lifecycle status — passing the
@@ -1200,8 +1205,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']);
+          await db.query(`UPDATE provisioning_intents SET state='pending', last_error=$2, not_before = now() + ($3 * interval '1 millisecond'), updated_at=now() WHERE id=$1`, [intent.id, result.error || 'op failed', next.delayMs]);
+          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 +1300,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.31'; // 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

@@ -431,7 +431,7 @@ await t('schema_pending passes through as a count, and UNKNOWN stays null rather
 await t('an open intent is surfaced with its target, so the page can say what is already running', () => {
   const p = CU.previewFromSnapshot(previewInst, { served_version: '1.19.758', available: [], recommended: null },
     { action: 'core-upgrade', state: 'running', target_version: '1.19.762' });
-  assert.deepEqual(p.open_intent, { action: 'core-upgrade', state: 'running', target_version: '1.19.762' });
+  assert.deepEqual(p.open_intent, { action: 'core-upgrade', state: 'running', target_version: '1.19.762', not_before: null, last_error: null });
 });
 
 console.log('\nthe deploy page is gated on the same atom as its routes:');
@@ -964,5 +964,48 @@ 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('\na move waiting out its retry (task 1004447):');
+
+const waiting = (over = {}) => ({ id: 5, action: 'core-upgrade', state: 'pending', target_version: '1.20.1', not_before: new Date(Date.now() + 3600e3).toISOString(), ...over });
+const enqueueAgainst = async (open, to = '1.20.1') => {
+  const writes = [];
+  const provisioning = { enqueueIntent: async () => ({ intent: open, created: false }) };
+  const db = { query: async (sql, params) => { writes.push({ sql, params }); return { rows: [] }; } };
+  return { r: await CU.enqueueCoreUpgrade(provisioning, db, 7, to, 'api:archon:42'), writes };
+};
+
+await t('pressing Move for the SAME waiting move brings its retry forward instead of refusing', async () => {
+  const { r, writes } = await enqueueAgainst(waiting());
+  assert.equal(r.retryNow, true);
+  assert.ok(!r.conflict);
+  assert.match(writes[0].sql, /SET not_before = NULL/);
+  assert.deepEqual(writes[0].params, [5]);
+});
+
+await t('a DIFFERENT target, a running move, or one not waiting is still a conflict', async () => {
+  for (const open of [waiting({ target_version: '1.20.2' }), waiting({ state: 'running' }), waiting({ not_before: null }), waiting({ action: 'restart' })]) {
+    const { r, writes } = await enqueueAgainst(open);
+    assert.equal(r.conflict, 'open_intent');
+    assert.equal(writes.length, 0);
+  }
+});
+
+await t('the preview says when a waiting move will try again, and why it is waiting', () => {
+  const p = CU.previewFromSnapshot(ACTIVE, null, waiting({ last_error: 'core 1.20.1 is not published yet' }), null);
+  assert.ok(p.open_intent.not_before);
+  assert.match(p.open_intent.last_error, /not published yet/);
+  assert.equal(CU.previewFromSnapshot(ACTIVE, null, waiting({ not_before: null, last_error: 'x' }), null).open_intent.last_error, null,
+    'an ordinary pending intent shows no error');
+});
+
 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/intent_retry.mjs

@@ -0,0 +1,57 @@
+// tests/intent_retry.mjs — a failed intent waits, or is retired, by what kind of failure it
+// was (task 1004447, goal 1000090 deploy self-heal).
+//
+// WHAT IS AT RISK. One runner tick used to run the same failing core move up to three times
+// back to back, restarting the service each time, then give up. These cases pin the policy
+// that replaced it; tests/provision.mjs drives the drain loop with it.
+//
+// Run:  node tests/intent_retry.mjs
+
+import { strict as assert } from 'node:assert';
+import { retryDecision, maxAttemptsFor, TRANSIENT_BACKOFF_MS, DEFAULT_RETRY_DELAY_MS } from '../scripts/gds/intent-retry.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}`); }
+};
+const MIN = 60 * 1000;
+const transient = { class: 'transient', reason: 'not_published' };
+
+await t('a transient failure waits about 15 minutes, then 1 hour, then 6 hours', () => {
+  assert.deepEqual([...TRANSIENT_BACKOFF_MS], [15 * MIN, 60 * MIN, 360 * MIN]);
+  for (const [attempts, ms] of [[1, 15 * MIN], [2, 60 * MIN], [3, 360 * MIN]]) {
+    assert.deepEqual(retryDecision({ attempts, failure: transient, maxAttempts: 3 }), { action: 'retry', delayMs: ms });
+  }
+});
+
+await t('and is retired after its last scheduled try', () => {
+  assert.deepEqual(retryDecision({ attempts: 4, failure: transient, maxAttempts: 3 }), { action: 'retire' });
+});
+
+await t('every NON-transient class is retired at once — retrying cannot change the answer', () => {
+  for (const c of ['known_wedge', 'needs_decision', 'unknown']) {
+    assert.deepEqual(retryDecision({ attempts: 1, failure: { class: c, reason: 'x' }, maxAttempts: 3 }), { action: 'retire' }, c);
+  }
+});
+
+await t('terminal always retires, even a transient class', () => {
+  assert.deepEqual(retryDecision({ attempts: 1, failure: transient, terminal: true, maxAttempts: 3 }), { action: 'retire' });
+});
+
+await t('an UNCLASSIFIED failure keeps its budget, but never retries in the same tick', () => {
+  assert.deepEqual(retryDecision({ attempts: 1, maxAttempts: 3 }), { action: 'retry', delayMs: DEFAULT_RETRY_DELAY_MS });
+  assert.ok(DEFAULT_RETRY_DELAY_MS >= MIN, 'at least a minute: the runner ticks about every two');
+  assert.deepEqual(retryDecision({ attempts: 3, maxAttempts: 3 }), { action: 'retire' });
+});
+
+await t('the pre-run guard gives a transient row room for its last scheduled try', () => {
+  assert.equal(maxAttemptsFor({ failure_class: 'transient' }, 3), 4);
+  assert.equal(maxAttemptsFor({ failure_class: 'unknown' }, 3), 3);
+  assert.equal(maxAttemptsFor({}, 3), 3);
+  assert.equal(maxAttemptsFor({ failure_class: 'transient' }, 9), 9, 'never lowers a configured budget');
+});
+
+console.log(`\nintent_retry: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/tests/provision.mjs

@@ -2564,6 +2564,65 @@ 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), and
+// waits or retires by that kind (task 1004447). The queue here is STATEFUL — a fake
+// claimNextIntent that honours not_before the way the real query does — so "one tick runs a
+// failing move at most once" is measured, not assumed.
+const queueRun = async ({ attempts = 0, transient = false } = {}) => {
+  const row = { id: 11, instance_id: 18, action: 'core-upgrade', target_version: '1.20.1', attempts, state: 'pending', not_before: null, failure_class: attempts && transient ? 'transient' : null }; // a re-tried row carries the class its last attempt wrote
+  let runs = 0; const resolved = []; const classWrites = []; const repends = [];
+  const deps = {
+    apply: true, log: () => {},
+    db: { query: async (sql, params) => {
+      if (/SET failure_class/.test(sql)) { classWrites.push(params); row.failure_class = params[1]; }
+      if (/SET state='pending'/.test(sql)) { repends.push(params); row.state = 'pending'; row.not_before = new Date(Date.now() + params[2]); }
+      return { rows: [] };
+    } },
+    provisioning: {
+      claimNextIntent: async () => {
+        if (row.state !== 'pending' || (row.not_before && row.not_before > new Date())) return null;
+        row.state = 'running'; row.attempts += 1; runs += 1; return { ...row };
+      },
+      // 'dedicated' is a shape the runner cannot move (needs_decision); the control plane with
+      // an unreadable registry is the transient case. Neither needs an exec.
+      getInstanceById: async () => (transient ? { ...activeStandalone, hosting_shape: 'control-plane' } : { ...activeStandalone, hosting_shape: 'dedicated' }),
+      resolveIntent: async (_db, id, state) => { resolved.push({ id, state }); row.state = state; },
+      setInstanceStatus: async () => {}, recordEvent: async () => {},
+      claimNextOAuthManifest: async () => null, resolveOAuthManifest: async () => {},
+    },
+    exec: () => ({ ok: true }), writeFile: () => ({ ok: true }),
+    readInstalledCoreVersion: () => '1.19.1081', selfInstanceRoot: () => '/srv/cb',
+    updateChannel: { DEFAULT_CHANNEL: 'patch', normalizeChannel: (c) => c || 'patch', channelAllows: () => true, listAvailableVersions: () => ({ ok: false, versions: [] }) },
+    checkDnsTokenScope: async () => ({ reachable: true, zone: 'z' }), checkCaddyWiring: () => null,
+  };
+  await P.cmdRunIntents(deps);
+  return { runs, resolved, classWrites, repends, row };
+};
+
+await ta('a needs-decision core move is RETIRED at once with its class — retrying cannot change it', async () => {
+  const { runs, resolved, classWrites } = await queueRun();
+  assert.equal(runs, 1);
+  assert.equal(resolved[0].state, 'error');
+  assert.deepEqual(classWrites, [[11, 'needs_decision', 'shape_not_automated']]);
+});
+
+await ta('a TRANSIENT core move runs ONCE per tick and waits ~15 minutes before its next try', async () => {
+  const { runs, resolved, repends, classWrites } = await queueRun({ transient: true });
+  assert.equal(runs, 1, 'the same failing move is not re-run inside one tick');
+  assert.equal(resolved.length, 0, 'not retired — it waits');
+  assert.equal(repends.length, 1);
+  assert.equal(repends[0][2], 15 * 60 * 1000, 'not_before = now + 15 minutes');
+  assert.deepEqual(classWrites, [[11, 'transient', 'registry_unreadable']]);
+});
+
+await ta('a transient move on its LAST scheduled try (the 6-hour one) is retired after it', async () => {
+  const { runs, resolved } = await queueRun({ transient: true, attempts: 3 });
+  // attempt 4 RUNS (the pre-run guard allows it for a transient row) and is then retired.
+  assert.equal(runs, 1, 'the 6-hour try actually ran — not retired unrun by the pre-run guard');
+  assert.equal(resolved.length, 1);
+  assert.equal(resolved[0].state, 'error');
+});
+
 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);