@ouro.bot/cli 0.1.0-alpha.834 → 0.1.0-alpha.835

package/changelog.json

@@ -1,6 +1,14 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.835",
+      "changes": [
+        "Sanctuary: in-place upgrade of an installed root authority (D-043). The authority keeps its epoch, token, issuer and Telegram cursor; only the reviewed package, its pins and the resident image change. The new package's lifecycle runs stop, switch, resident, migrate and start from a journal, backs up every root record it rewrites, and rolls back exactly on any failure. An interrupted upgrade rolls back on the next authority boot. No token rotation.",
+        "Upgrade orchestrator: new upgrade phase stages the package beside the live one, pauses host supervision behind a self-expiring maintenance flag, runs the lifecycle upgrade with automatic rollback, pins the DockerMan template, and resumes supervision. --rehearse <step> stops after a step and rolls back, proving the rollback on the real host. The host keeper now also restarts a resident left stopped.",
+        "Sanctuary root lifecycle failures are recorded with their real cause in a root-only log (the authority directory), and stderr names that file (D-034). A stale copy of the live token left in incoming-token is removed after an upgrade (D-044)."
+      ]
+    },
     {
       "version": "0.1.0-alpha.834",
       "changes": [

package/deploy/unraid/sanctuary-butler-upgrade.mjs

@@ -19,11 +19,17 @@
 //              automatic rollback on ANY failure so the Butler is never left
 //              down. Requires a freshly rotated token at incoming-token.
 //   verify     health + preservation (Jellyfin, steward policy) + readback.
+//   upgrade    in-place upgrade of an INSTALLED authority (D-043): same epoch,
+//              token and cursor; new package, pins and resident image. The new
+//              package's own lifecycle does the work and rolls back exactly on
+//              any failure. `--rehearse <step>` stops after that step and rolls
+//              back, proving the rollback on real hardware. No token rotation.
 //
-// Run `preflight` and `prepare` freely. `install` is the only destructive phase
-// and refuses without a rotated incoming-token.
+// Run `preflight` and `prepare` freely. `install` is the first-install phase and
+// refuses without a rotated incoming-token. Run `upgrade` detached so an SSH drop
+// cannot interrupt it:  setsid nohup node <this> upgrade <version> > /var/log/ouro-upgrade.log 2>&1 &
 //
-// Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify> <version>
+// Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify|upgrade> <version> [--rehearse <step>]
 
 import { execFileSync } from "node:child_process"
 import { createHash } from "node:crypto"
@@ -47,6 +53,13 @@ const REQUIRED_PROGRAMS = [
   "deploy/unraid/sanctuary-authority-service.sh",
 ]
 const MIN_FREE_GB = 2
+const INCOMING_MANIFEST = `${ROOT}/incoming-package-manifest.json`
+const INCOMING_REQUEST = `${ROOT}/incoming-request.json`
+const UPGRADE_JOURNAL = `${ROOT}/upgrade.json`
+// Host supervision skips its work while this flag is fresh (< 30 min), so a crashed
+// upgrade can never leave self-heal off for longer than that.
+const MAINTENANCE = "/run/ouro-authority-maintenance"
+const UPGRADE_STEPS = ["stop", "switch", "resident", "migrate", "start"]
 
 const sh = (file, args, opts = {}) => execFileSync(file, args, { encoding: "utf8", maxBuffer: 64 << 20, ...opts })
 const docker = (args, opts = {}) => sh("/usr/bin/docker", args, opts)
@@ -109,8 +122,11 @@ function preflight(version) {
   } catch { bad(`the ${CONTAINER} container is absent`) }
   if (id && runningImage && id === runningImage) bad("target and running image are identical — nothing to upgrade")
 
+  const installed = existsSync(`${ROOT}/active.json`)
+  if (installed) console.log("  note: an authority is installed, so this is an in-place upgrade (run `upgrade`, no token rotation)")
+
   say("no stale authority runtime state")
-  {
+  if (!installed) {
     const stale = ["/sys/fs/cgroup/ouro-authority", "/var/lib/ouro-authority", "/run/ouro-authority", `${ROOT}/epochs`].filter((d) => existsSync(d))
     if (stale.length && !existsSync(`${ROOT}/active.json`)) console.log(`  note: stale dirs present, install will clear them: ${stale.join(", ")}`)
     else if (!stale.length) ok("no stale authority runtime dirs")
@@ -119,7 +135,8 @@ function preflight(version) {
 
   say("no upgrade already in flight")
   existsSync(JOURNAL) ? bad(`a template transaction journal is pending at ${JOURNAL}; resolve it first`) : ok("no pending template transaction")
-  existsSync(`${ROOT}/active.json`) ? bad("an authority is already installed (active.json present)") : ok("no prior authority installed")
+  if (installed) existsSync(UPGRADE_JOURNAL) ? console.log("  note: an in-place upgrade is pending; `upgrade` resumes it") : ok("no pending in-place upgrade")
+  if (installed && existsSync(`${ROOT}/incoming-token`)) console.log("  note: a stale incoming-token copy is present; the upgrade removes it (D-044)")
 
   say("host primitives (root-owned, not group/world-writable)")
   for (const f of PRIMITIVES) {
@@ -140,7 +157,8 @@ function preflight(version) {
   } catch { bad("could not inspect the image contents") }
 
   say("D-018: the fenced vault read the install depends on")
-  if (id) {
+  if (installed) ok("not needed: the installed gateway already holds the token in root custody")
+  else if (id) {
     // Run the read fenced exactly as THIS version's install will fence it, so
     // the rehearsal is faithful: an unfixed image is tested without the fix and
     // correctly fails here rather than during a real install.
@@ -169,7 +187,7 @@ function preflight(version) {
   catch { bad("jellyfin container not inspectable") }
 
   console.log("")
-  if (RED === 0) console.log("PREFLIGHT GREEN — the upgrade can proceed. Next: prepare, rotate the token, install.")
+  if (RED === 0) console.log(installed ? "PREFLIGHT GREEN — run `upgrade` (detached)." : "PREFLIGHT GREEN — the upgrade can proceed. Next: prepare, rotate the token, install.")
   else console.log(`PREFLIGHT RED — ${RED} blocker(s) above. Nothing was changed; fix these before rotating the token.`)
   process.exit(RED === 0 ? 0 : 1)
 }
@@ -215,7 +233,41 @@ function prepare(version) {
   say(`prepare inputs for ${version}`)
   const id = imageId(version)
   if (!id) fail(`image ${image(version)} is not present; pull it first`)
+  if (existsSync(`${ROOT}/active.json`)) fail("an authority is installed; use `upgrade` (in place, no token rotation) instead of prepare/install")
   const epochId = `${version.replace(/[^A-Za-z0-9_-]/g, "-")}-${new Date().toISOString().slice(0, 10).replace(/-/g, "")}`
+  const manifestBytes = stageIncomingPackage(version)
+  writePrivate(`${ROOT}/package-manifest.json`, manifestBytes)
+  const creds = JSON.parse(readFileSync(`/mnt/user/appdata/ouro-butler/runtime/container-credentials.json`, "utf8")).credentials[0].runtimeConfig
+  const request = {
+    schemaVersion: 1, epochId,
+    botId: String(creds.telegramBotToken).split(":")[0],
+    ownerUserId: String(creds.telegramAuthorizedUserId), ownerChatId: String(creds.telegramAuthorizedChatId),
+    ...packagePins(manifestBytes),
+  }
+  if (request.ownerUserId !== request.ownerChatId) fail("owner user and chat must match")
+  writePrivate(`${ROOT}/request.json`, Buffer.from(JSON.stringify(request)))
+  ok(`epoch ${epochId}, package ${request.packageDigest.slice(7, 19)}…`)
+
+  say("verify the prepared package against the installer's own rules")
+  verifyPackage(`${ROOT}/incoming-package`, `${ROOT}/package-manifest.json`, `${ROOT}/request.json`)
+  ok("package verifies")
+
+  console.log("\nPREPARE done. Next: rotate the bot token into ${ROOT}/incoming-token, then install.".replace("${ROOT}", ROOT))
+}
+
+// The package digest plus the host primitive pins every request carries.
+function packagePins(manifestBytes) {
+  const d = (f) => digest(readFileSync(f))
+  return {
+    packageDigest: digest(manifestBytes),
+    nodeDigest: d("/usr/local/bin/node"), prlimitDigest: d("/usr/bin/prlimit"),
+    setsidDigest: d("/usr/bin/setsid"), shellDigest: d(sh("/bin/readlink", ["-f", "/bin/sh"]).trim()),
+  }
+}
+
+// Extract the exact package from the image into incoming-package, normalised to the
+// installer's rules, and return its manifest bytes. The running Butler is untouched.
+function stageIncomingPackage(version) {
   const incoming = `${ROOT}/incoming-package`
 
   say("extract the exact package from the image")
@@ -252,27 +304,8 @@ function prepare(version) {
     }
   }
   walk("")
-  const manifestBytes = Buffer.from(JSON.stringify({ schemaVersion: 1, files }))
-  writePrivate(`${ROOT}/package-manifest.json`, manifestBytes)
-  const creds = JSON.parse(readFileSync(`/mnt/user/appdata/ouro-butler/runtime/container-credentials.json`, "utf8")).credentials[0].runtimeConfig
-  const d = (f) => digest(readFileSync(f))
-  const request = {
-    schemaVersion: 1, epochId,
-    botId: String(creds.telegramBotToken).split(":")[0],
-    ownerUserId: String(creds.telegramAuthorizedUserId), ownerChatId: String(creds.telegramAuthorizedChatId),
-    packageDigest: digest(manifestBytes),
-    nodeDigest: d("/usr/local/bin/node"), prlimitDigest: d("/usr/bin/prlimit"),
-    setsidDigest: d("/usr/bin/setsid"), shellDigest: d(sh("/bin/readlink", ["-f", "/bin/sh"]).trim()),
-  }
-  if (request.ownerUserId !== request.ownerChatId) fail("owner user and chat must match")
-  writePrivate(`${ROOT}/request.json`, Buffer.from(JSON.stringify(request)))
-  ok(`epoch ${epochId}, ${Object.keys(files).length} files pinned, package ${request.packageDigest.slice(7, 19)}…`)
-
-  say("verify the prepared package against the installer's own rules")
-  verifyPackage(incoming, `${ROOT}/package-manifest.json`, `${ROOT}/request.json`)
-  ok("package verifies")
-
-  console.log("\nPREPARE done. Next: rotate the bot token into ${ROOT}/incoming-token, then install.".replace("${ROOT}", ROOT))
+  ok(`${Object.keys(files).length} files pinned`)
+  return Buffer.from(JSON.stringify({ schemaVersion: 1, files }))
 }
 
 function writePrivate(path, bytes) { writeFileSync(path, bytes, { mode: 0o600 }); sh("/bin/chown", ["0:0", path]); chmodSync(path, 0o600) }
@@ -440,18 +473,23 @@ start_gw() {
   /bin/sh /boot/config/custom/ouro-authority/start.sh --boot >> "$LOG" 2>&1 \
     || echo "$(date) keeper: authority boot failed; will retry" >> "$LOG"
 }
+# An in-place upgrade pauses us with a flag; a stale flag (> 30 min) is ignored.
+maintenance() { [ -n "$(find /run/ouro-authority-maintenance -mmin -30 2>/dev/null)" ]; }
 pause_reaper; ensure_cg; ensure_sock
 last_res=0
 while true; do
+  if maintenance; then sleep 15; continue; fi
   pause_reaper
   ensure_cg
   ensure_sock
   [ -n "$(gw_pid)" ] || { start_gw; sleep 8; }
   rd=$(jq -rc .status "$R"/epochs/*/readiness.json 2>/dev/null)
   st=$(docker inspect ouro-butler --format '{{.State.Health.Status}}' 2>/dev/null)
+  ss=$(docker inspect ouro-butler --format '{{.State.Status}}' 2>/dev/null)
   now=$(date +%s)
-  if [ "$rd" = ready ] && [ "$st" = unhealthy ] && [ $((now - last_res)) -gt 90 ]; then
-    echo "$(date) keeper: reconnecting unhealthy resident" >> "$LOG"
+  # Unhealthy, or left stopped (an interrupted upgrade or restart): the gateway is ready, so bring it back.
+  if [ "$rd" = ready ] && { [ "$st" = unhealthy ] || [ "$ss" = exited ] || [ "$ss" = created ]; } && [ $((now - last_res)) -gt 90 ]; then
+    echo "$(date) keeper: reconnecting resident ($ss/$st)" >> "$LOG"
     docker restart ouro-butler >/dev/null 2>&1
     last_res=$now
   fi
@@ -468,6 +506,8 @@ const GATEWAY_WATCHDOG_SH = String.raw`#!/bin/sh
 set -u
 # The stop hook sets this during shutdown; never resurrect the supervisor then.
 [ -e /run/ouro-authority-shutdown ] && exit 0
+# An in-place upgrade pauses supervision; a stale flag (> 30 min) is ignored.
+[ -n "$(find /run/ouro-authority-maintenance -mmin -30 2>/dev/null)" ] && exit 0
 SUP=/boot/config/custom/ouro-authority/gateway-supervisor.sh
 LOG=/var/log/ouro-gateway.log
 if [ ! -f "$SUP" ]; then
@@ -737,6 +777,83 @@ function buildFinalProof(version, out) {
   writeFileSync(out, JSON.stringify(proof), { mode: 0o600 })
 }
 
+// ---- upgrade (in place, installed authority) --------------------------------
+
+function pauseSupervision() {
+  writeFileSync(MAINTENANCE, `${new Date().toISOString()} ${process.pid}\n`)
+  sh("/bin/sh", ["-c", "for p in $(pgrep -f '^/bin/sh /boot/config/custom/ouro-authority/[g]ateway-supervisor' || true); do kill $p; done"])
+  ok("host supervision paused (its flag expires on its own after 30 min)")
+}
+function resumeSupervision() {
+  rmSync(MAINTENANCE, { force: true })
+  installGatewaySupervisor()
+}
+
+// Keep Unraid's DockerMan template (what the UI's Apply/Update uses) on the live image.
+function pinTemplate(version) {
+  if (!existsSync(TEMPLATE)) { console.log("  note: no DockerMan template to update"); return }
+  const text = readFileSync(TEMPLATE, "utf8")
+  const next = text.replace(/<Repository>ghcr\.io\/ourostack\/ouroboros-butler:[^<]+<\/Repository>/u, `<Repository>${image(version)}</Repository>`)
+  if (!next.includes(`<Repository>${image(version)}</Repository>`)) { console.log("  WARN: DockerMan template Repository not recognised; left unchanged"); return }
+  if (next !== text) { writeFileSync(`${TEMPLATE}.prev`, text); writeFileSync(TEMPLATE, next) }
+  ok(`DockerMan template pins ${image(version)}`)
+}
+
+function lifecycleFailure(e) {
+  const detail = [e.stderr, e.stdout].map((x) => (x ? String(x).trim() : "")).filter(Boolean).join(" | ")
+  let last = ""
+  try { last = readFileSync(`${ROOT}/lifecycle-failure.log`, "utf8").trim().split("\n").filter((l) => /^\d{4}-/.test(l)).at(-1) ?? "" } catch { /* none */ }
+  return `${detail || e.message}${last ? `\n   last root failure: ${last}` : ""}`
+}
+
+function upgrade(version, rehearse) {
+  say(`in-place upgrade to ${version}${rehearse ? ` — REHEARSAL: stop after "${rehearse}", then roll back` : ""}`)
+  if (rehearse && !UPGRADE_STEPS.includes(rehearse)) fail(`--rehearse takes one of: ${UPGRADE_STEPS.join(", ")}`)
+  if (!existsSync(`${ROOT}/active.json`) || !existsSync(`${ROOT}/activation.json`)) fail("no installed authority; use prepare + install")
+  if (existsSync(JOURNAL)) fail("a template transaction is pending; resolve it first")
+  let id = imageId(version)
+  if (!id) { docker(["pull", image(version)]); id = imageId(version) }
+  if (!id) fail(`image ${image(version)} could not be pulled`)
+  ok(`image ${id.slice(0, 19)}…`)
+  if (existsSync(UPGRADE_JOURNAL)) console.log("  note: resuming the pending in-place upgrade with its staged package")
+  else {
+    const current = JSON.parse(readFileSync(`${ROOT}/request.json`, "utf8"))
+    const manifestBytes = stageIncomingPackage(version)
+    const pkgVersion = JSON.parse(readFileSync(`${ROOT}/incoming-package/deploy/unraid/sanctuary.ouro/bundle-meta.json`, "utf8")).runtimeVersion
+    if (pkgVersion !== version) fail(`staged package is ${pkgVersion}, not ${version}`)
+    writePrivate(INCOMING_MANIFEST, manifestBytes)
+    const request = { schemaVersion: 1, epochId: current.epochId, botId: current.botId, ownerUserId: current.ownerUserId, ownerChatId: current.ownerChatId, ...packagePins(manifestBytes) }
+    writePrivate(INCOMING_REQUEST, Buffer.from(JSON.stringify(request)))
+    verifyPackage(`${ROOT}/incoming-package`, INCOMING_MANIFEST, INCOMING_REQUEST)
+    ok("new package staged beside the live one and verified")
+  }
+  const lifecycle = `${ROOT}/incoming-package/dist/heart/daemon/sanctuary-authority-root-lifecycle.js`
+  const jellyfinBefore = docker(["inspect", "jellyfin", "--format", "{{.Id}}|{{.Image}}|{{.RestartCount}}|{{.State.StartedAt}}"]).trim()
+  const policyBefore = existsSync(POLICY) ? sha12(POLICY) : fail("steward policy missing")
+  pauseSupervision()
+  let failure = null
+  try {
+    say("lifecycle upgrade (stop → switch → resident → migrate → start)")
+    ok(sh("/usr/local/bin/node", [lifecycle, "upgrade", id, image(version), ...(rehearse ? ["--fail-after", rehearse] : [])], { stdio: ["ignore", "pipe", "pipe"] }).trim())
+  } catch (e) { failure = e }
+  if (failure) {
+    console.log(`\n!! ${rehearse ? "rehearsal stopped as planned" : "upgrade failed"}: ${lifecycleFailure(failure)}\n!! rolling back to the predecessor`)
+    try { ok(`rollback: ${sh("/usr/local/bin/node", [lifecycle, "upgrade-rollback"], { stdio: ["ignore", "pipe", "pipe"] }).trim()}`) }
+    catch (e) {
+      resumeSupervision()
+      fail(`ROLLBACK FAILED: ${lifecycleFailure(e)}\nThe journal is kept; the next authority boot (or \`upgrade-rollback\`) retries it.`)
+    }
+  } else pinTemplate(version)
+  resumeSupervision()
+  say("preservation")
+  docker(["inspect", "jellyfin", "--format", "{{.Id}}|{{.Image}}|{{.RestartCount}}|{{.State.StartedAt}}"]).trim() === jellyfinBefore ? ok("jellyfin unchanged") : fail("JELLYFIN CHANGED")
+  sha12(POLICY) === policyBefore ? ok("steward policy unchanged") : fail("STEWARD POLICY CHANGED")
+  const live = docker(["inspect", CONTAINER, "--format", "{{.Config.Image}} {{.State.Status}}/{{.State.Health.Status}}"]).trim()
+  ok(`butler: ${live}`)
+  if (failure && !rehearse) fail("upgrade rolled back; the Butler is on its prior version (see above)")
+  console.log(rehearse ? "\nREHEARSAL done — the rollback restored the predecessor." : `\nUPGRADE done — ${version} live. Run verify.`)
+}
+
 // ---- verify ---------------------------------------------------------------
 
 function verify() {
@@ -755,9 +872,9 @@ function fail(m) { console.error(`\nREFUSING: ${m}`); process.exit(1) }
 
 // ---- entry ----------------------------------------------------------------
 
-const [phase, version] = process.argv.slice(2)
-if (!phase || !["preflight", "prepare", "install", "verify"].includes(phase)) {
-  console.error("Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify> <version>")
+const [phase, version, flag, rehearse] = process.argv.slice(2)
+if (!phase || !["preflight", "prepare", "install", "verify", "upgrade"].includes(phase) || (flag !== undefined && !(phase === "upgrade" && flag === "--rehearse" && rehearse))) {
+  console.error("Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify|upgrade> <version> [--rehearse <step>]")
   process.exit(2)
 }
 if (phase !== "verify" && !/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(version || "")) {
@@ -770,3 +887,4 @@ if (phase === "preflight") preflight(version)
 else if (phase === "prepare") prepare(version)
 else if (phase === "install") install(version)
 else if (phase === "verify") verify()
+else if (phase === "upgrade") upgrade(version, rehearse)

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.834",
+  "runtimeVersion": "0.1.0-alpha.835",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.834</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.835</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/daemon/sanctuary-authority-epoch.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readSanctuaryAuthorityEpoch = readSanctuaryAuthorityEpoch;
 exports.prepareSanctuaryAuthorityEpoch = prepareSanctuaryAuthorityEpoch;
 exports.releaseSanctuaryAuthorityToken = releaseSanctuaryAuthorityToken;
+exports.rebindSanctuaryAuthorityEpochPackage = rebindSanctuaryAuthorityEpochPackage;
 exports.retireSanctuaryAuthorityEpoch = retireSanctuaryAuthorityEpoch;
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
@@ -238,6 +239,30 @@ function releaseSanctuaryAuthorityToken(root, options) {
         fs.unlinkSync(epoch.tokenPath);
     syncRoot(root);
 }
+/**
+ * Move a live epoch to a new reviewed package without replacing its token, issuer
+ * or cursor. An in-place upgrade (and its rollback) rebinds the package the epoch
+ * trusts; the gateway still refuses any config whose package differs from the epoch's.
+ */
+function rebindSanctuaryAuthorityEpochPackage(root, options) {
+    if (!DIGEST.test(options.from) || !DIGEST.test(options.to))
+        throw new Error("Sanctuary authority package rebind is invalid");
+    const epochPath = path.join(root, "epoch.json");
+    return (0, session_transaction_1.withImmediateSessionTurnLease)(epochPath, (lease) => {
+        const transaction = (0, session_transaction_1.readSessionTransaction)(epochPath, lease);
+        const epoch = readSanctuaryAuthorityEpoch(root, options);
+        if (epoch.state !== "prepared")
+            throw new Error("Sanctuary authority epoch is retired");
+        if (epoch.packageDigest === options.to)
+            return epoch;
+        if (epoch.packageDigest !== options.from)
+            throw new Error("Sanctuary authority epoch package changed");
+        const rebound = { ...epoch, packageDigest: options.to };
+        (0, session_transaction_1.writeSessionTransaction)(epochPath, rebound, { lease, expectedRevision: transaction.revision });
+        (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_authority_epoch_package_rebound", message: "Sanctuary authority epoch rebound to a reviewed package", meta: { epochId: epoch.epochId, from: options.from, to: options.to } });
+        return rebound;
+    });
+}
 function retireSanctuaryAuthorityEpoch(root, options) {
     if (options.quiescent !== true)
         throw new Error("Sanctuary authority execution state is not quiescent");

package/dist/heart/daemon/sanctuary-authority-root-lifecycle.js

@@ -32,8 +32,10 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SanctuaryAuthorityRootLifecycle = void 0;
+exports.SanctuaryAuthorityRootLifecycle = exports.SANCTUARY_UPGRADE_STEPS = void 0;
+exports.recordSanctuaryRootLifecycleFailure = recordSanctuaryRootLifecycleFailure;
 exports.runSanctuaryAuthorityRootCli = runSanctuaryAuthorityRootCli;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
@@ -57,7 +59,32 @@ const CGROUP = "/sys/fs/cgroup/ouro-authority";
 const BOOT = "/boot/config/custom/ouro-authority/start.sh";
 const BOOT_LINE = `/bin/sh ${BOOT} --boot & # ouro-authority`;
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const TEMPLATE_JOURNAL = "/boot/config/custom/ouro-butler/docker-man-template-transaction.json";
+// In-place upgrade of an installed authority: same epoch (token, issuer, cursor,
+// gateway state), new reviewed package and resident image. Every root record it
+// rewrites is backed up first so an interrupted or failed upgrade rolls back exactly.
+const UPGRADE = `${ROOT}/upgrade.json`;
+const PREVIOUS = `${ROOT}/upgrade-previous`;
+const NEXT_PACKAGE = `${ROOT}/package-next`;
+const INCOMING_REQUEST = `${ROOT}/incoming-request.json`;
+const INCOMING_MANIFEST = `${ROOT}/incoming-package-manifest.json`;
+const EVENTS = "/boot/config/custom/ouro-events/spool";
+const ICON = "https://raw.githubusercontent.com/ourostack/ouroboros/main/assets/ouroboros.png";
+const IMAGE_REFERENCE = /^ghcr\.io\/ourostack\/ouroboros-butler:[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/u;
+exports.SANCTUARY_UPGRADE_STEPS = ["stop", "switch", "resident", "migrate", "start"];
+const ROOT_RECORDS = [["request.json", 1024 * 1024], ["package-manifest.json", 8 * 1024 * 1024], ["active.json", 1024 * 1024], ["activation.json", 1024 * 1024]];
+const EPOCH_RECORDS = ["migration.json", "stage.json", "configured.json"];
 const digest = (value) => `sha256:${(0, node_crypto_1.createHash)("sha256").update(value).digest("hex")}`;
+function validateRequest(value) {
+    const request = value;
+    if (!request || typeof request !== "object" || Object.keys(request).sort().join(",") !== "botId,epochId,nodeDigest,ownerChatId,ownerUserId,packageDigest,prlimitDigest,schemaVersion,setsidDigest,shellDigest"
+        || request.schemaVersion !== 1 || !/^[A-Za-z0-9_-]{1,128}$/u.test(request.epochId)
+        || ![request.botId, request.ownerUserId, request.ownerChatId].every((id) => typeof id === "string" && /^[1-9][0-9]*$/u.test(id))
+        || request.ownerUserId !== request.ownerChatId
+        || ![request.packageDigest, request.nodeDigest, request.prlimitDigest, request.setsidDigest, request.shellDigest].every((pin) => typeof pin === "string" && DIGEST.test(pin)))
+        throw new Error("Sanctuary root lifecycle request is invalid");
+    return request;
+}
 // The prefix is a filesystem-fixture seam; the production CLI never accepts it.
 class SanctuaryAuthorityRootLifecycle {
     #request;
@@ -66,7 +93,9 @@ class SanctuaryAuthorityRootLifecycle {
     #uid;
     #gid;
     #socketGid;
+    #options;
     constructor(transaction, options = {}) {
+        this.#options = options;
         this.#prefix = options.prefix ?? "";
         this.#uid = options.expectedUid ?? 0;
         this.#gid = options.expectedGid ?? 0;
@@ -77,15 +106,8 @@ class SanctuaryAuthorityRootLifecycle {
             throw new Error("Sanctuary root lifecycle image identity is invalid");
         this.#transaction = { targetImageId: transaction.targetImageId, rollbackImageId: transaction.rollbackImageId };
         this.#directory(ROOT);
-        const request = JSON.parse(this.#private(`${ROOT}/request.json`));
-        if (!request || Object.keys(request).sort().join(",") !== "botId,epochId,nodeDigest,ownerChatId,ownerUserId,packageDigest,prlimitDigest,schemaVersion,setsidDigest,shellDigest"
-            || request.schemaVersion !== 1 || !/^[A-Za-z0-9_-]{1,128}$/u.test(request.epochId)
-            || ![request.botId, request.ownerUserId, request.ownerChatId].every((id) => typeof id === "string" && /^[1-9][0-9]*$/u.test(id))
-            || request.ownerUserId !== request.ownerChatId
-            || ![request.packageDigest, request.nodeDigest, request.prlimitDigest, request.setsidDigest, request.shellDigest].every((pin) => typeof pin === "string" && DIGEST.test(pin)))
-            throw new Error("Sanctuary root lifecycle request is invalid");
-        this.#request = request;
-        (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_root_lifecycle_loaded", message: "Sanctuary root lifecycle identity loaded", meta: { epochId: request.epochId, targetImageId: transaction.targetImageId } });
+        this.#request = validateRequest(JSON.parse(this.#private(`${ROOT}/request.json`)));
+        (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_root_lifecycle_loaded", message: "Sanctuary root lifecycle identity loaded", meta: { epochId: this.#request.epochId, targetImageId: transaction.targetImageId } });
     }
     plan() {
         const { epochId, botId, ownerUserId, ownerChatId, packageDigest } = this.#request;
@@ -94,6 +116,10 @@ class SanctuaryAuthorityRootLifecycle {
     async boot() {
         if (!fs.existsSync(this.#p(`${ROOT}/activation.json`)))
             return false;
+        // An upgrade that never finished (process killed, host rebooted) is rolled back
+        // here, so the Butler comes back on its known-good version without a human.
+        if (fs.existsSync(this.#p(UPGRADE)))
+            return this.rollbackUpgrade();
         this.#record(`${ROOT}/activation.json`, { ...this.#transaction, state: "active", epochId: this.#request.epochId });
         if (fs.existsSync(this.#p("/boot/config/custom/ouro-butler/docker-man-template-transaction.json")))
             throw new Error("Sanctuary pending installation requires recovery, not boot");
@@ -234,20 +260,20 @@ class SanctuaryAuthorityRootLifecycle {
         if (!stat.isDirectory() || stat.uid !== this.#uid || stat.gid !== gid || (stat.mode & 0o7777) !== mode || fs.realpathSync(directory) !== directory)
             throw new Error("Sanctuary root lifecycle directory is unsafe");
     }
-    #verifyPackage(packageRoot = `${ROOT}/package`, hostExecution = true) {
+    #verifyPackage(packageRoot = `${ROOT}/package`, hostExecution = true, manifestPath = `${ROOT}/package-manifest.json`, request = this.#request) {
         (0, sanctuary_authority_installation_1.verifySanctuaryAuthorityInstallation)({
-            packageRoot: this.#p(packageRoot), manifestPath: this.#p(`${ROOT}/package-manifest.json`), manifestDigest: this.#request.packageDigest,
+            packageRoot: this.#p(packageRoot), manifestPath: this.#p(manifestPath), manifestDigest: request.packageDigest,
             stateRoot: this.#p(this.#epochRoot()), stagingRoot: this.#p(STAGING), socketRoot: this.#p(SOCKET), cgroupRoot: this.#p(CGROUP),
             expectedUid: this.#uid, expectedGid: this.#gid, socketGroupId: this.#socketGid, mountInfo: fs.readFileSync(this.#p("/proc/self/mountinfo"), "utf8"),
         });
-        const manifest = JSON.parse(this.#private(`${ROOT}/package-manifest.json`, 0o600, 8 * 1024 * 1024));
+        const manifest = JSON.parse(this.#private(manifestPath, 0o600, 8 * 1024 * 1024));
         for (const program of ["dist/heart/daemon/sanctuary-telegram-authority-entry.js", "dist/heart/daemon/sanctuary-authority-root-lifecycle.js", "dist/heart/daemon/sanctuary-host-supervisor-entry.js", "deploy/unraid/sanctuary-host-launcher.sh", "deploy/unraid/sanctuary-authority-service.sh"]) {
             if (!Object.hasOwn(manifest.files, program))
                 throw new Error("Sanctuary authority package program is absent");
         }
         for (const [file, expected] of [
-            ["/usr/local/bin/node", this.#request.nodeDigest], ["/bin/sh", this.#request.shellDigest],
-            ...(hostExecution ? [["/usr/bin/prlimit", this.#request.prlimitDigest], ["/usr/bin/setsid", this.#request.setsidDigest]] : []),
+            ["/usr/local/bin/node", request.nodeDigest], ["/bin/sh", request.shellDigest],
+            ...(hostExecution ? [["/usr/bin/prlimit", request.prlimitDigest], ["/usr/bin/setsid", request.setsidDigest]] : []),
         ]) {
             this.#verifyPrimitive(file, expected);
         }
@@ -626,6 +652,215 @@ class SanctuaryAuthorityRootLifecycle {
             throw new Error("Sanctuary rollback readback failed");
         this.#write(`${this.#epochRoot()}/rollback.json`, JSON.stringify({ epochId: this.#request.epochId, state: "retired" }));
     }
+    /**
+     * Upgrade the installed authority in place to a reviewed package and resident image.
+     * The epoch (token, issuer, cursor, gateway state) is kept; only the package, its
+     * pins and the resident image change. Resumable from its journal; any failure is
+     * left for `rollbackUpgrade` (or the next boot) to undo exactly.
+     */
+    async upgrade(input) {
+        if (!DIGEST.test(input.targetImageId) || !IMAGE_REFERENCE.test(input.imageReference)
+            || (input.failAfter !== undefined && !exports.SANCTUARY_UPGRADE_STEPS.includes(input.failAfter)))
+            throw new Error("Sanctuary upgrade request is invalid");
+        if (fs.existsSync(this.#p(TEMPLATE_JOURNAL)))
+            throw new Error("Finish the pending installation before upgrading");
+        let journal = fs.existsSync(this.#p(UPGRADE)) ? this.#upgradeJournal() : this.#beginUpgrade(input);
+        if (journal.to.imageId !== input.targetImageId || journal.to.imageReference !== input.imageReference)
+            throw new Error("A different Sanctuary upgrade is pending; roll it back first");
+        const target = () => new _a({ targetImageId: journal.to.imageId, rollbackImageId: journal.from.imageId }, this.#options);
+        const steps = {
+            stop: () => this.#halt(),
+            switch: async () => { await this.#halt(); this.#switchPackage(journal); },
+            resident: () => this.#recreateResident(journal.to.imageReference, journal.to.imageId),
+            migrate: () => target().#bundle(["--operation", "migrate", "--rollback-image-id", journal.from.imageId, "--target-image-id", journal.to.imageId]),
+            start: () => target().#startUpgraded(),
+        };
+        for (const step of exports.SANCTUARY_UPGRADE_STEPS) {
+            if (!journal.completed.includes(step)) {
+                await steps[step]();
+                journal = { ...journal, completed: [...journal.completed, step] };
+                this.#write(UPGRADE, JSON.stringify(journal));
+                (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_upgrade_step", message: "Sanctuary upgrade step completed", meta: { step, to: journal.to.imageReference } });
+            }
+            if (input.failAfter === step)
+                throw new Error(`Sanctuary upgrade rehearsal stopped after ${step}`);
+        }
+        target().#bundle(["--operation", "commit"]);
+        // A copy of the live token must not linger as if it were a fresh rotation (D-044).
+        this.#remove(`${ROOT}/incoming-token`);
+        this.#remove(UPGRADE);
+        this.#removeTree(PREVIOUS);
+        (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_upgraded", message: "Sanctuary authority upgraded in place", meta: { from: journal.from.imageReference, to: journal.to.imageReference } });
+    }
+    /** Undo a pending in-place upgrade exactly, back to the recorded predecessor. */
+    async rollbackUpgrade() {
+        if (!fs.existsSync(this.#p(UPGRADE)))
+            return false;
+        let journal = this.#upgradeJournal();
+        await this.#halt();
+        if (journal.completed.includes("switch")) {
+            // A migration interrupted before the journal recorded it may or may not be
+            // pending; only a recorded migration must roll back. Once the bundle is back,
+            // record that so a retried rollback does not demand it again.
+            try {
+                this.#bundle(["--operation", "finalize-rollback"]);
+            }
+            catch (error) {
+                if (journal.completed.includes("migrate"))
+                    throw error;
+            }
+            journal = { ...journal, completed: journal.completed.filter((step) => step !== "migrate") };
+            this.#write(UPGRADE, JSON.stringify(journal));
+        }
+        if (fs.existsSync(this.#p(`${PREVIOUS}/package`))) {
+            this.#removeTree(`${ROOT}/package`);
+            fs.renameSync(this.#p(`${PREVIOUS}/package`), this.#p(`${ROOT}/package`));
+        }
+        this.#removeTree(NEXT_PACKAGE);
+        for (const [name, max] of ROOT_RECORDS)
+            this.#write(`${ROOT}/${name}`, this.#private(`${PREVIOUS}/${name}`, 0o600, max));
+        (0, sanctuary_authority_epoch_1.rebindSanctuaryAuthorityEpochPackage)(this.#p(this.#epochRoot()), { expectedUid: this.#uid, expectedGid: this.#gid, from: journal.to.packageDigest, to: journal.from.packageDigest });
+        for (const name of EPOCH_RECORDS)
+            this.#write(`${this.#epochRoot()}/${name}`, this.#private(`${PREVIOUS}/epoch/${name}`));
+        const predecessor = new _a({ targetImageId: journal.from.imageId, rollbackImageId: journal.from.rollbackImageId }, this.#options);
+        predecessor.#publishBoot();
+        if (this.#containers().find((container) => container.Name === "/ouro-butler")?.Image !== journal.from.imageId) {
+            predecessor.#recreateResident(journal.from.imageReference, journal.from.imageId);
+        }
+        await predecessor.#startUpgraded();
+        this.#remove(UPGRADE);
+        this.#removeTree(PREVIOUS);
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "daemon", event: "daemon.sanctuary_upgrade_rolled_back", message: "Sanctuary upgrade rolled back to its predecessor", meta: { from: journal.to.imageReference, to: journal.from.imageReference } });
+        return true;
+    }
+    #upgradeJournal() {
+        const journal = JSON.parse(this.#private(UPGRADE));
+        const sides = [journal?.from, journal?.to];
+        if (!journal || journal.schemaVersion !== 1 || journal.epochId !== this.#request.epochId || !Array.isArray(journal.completed)
+            || !journal.completed.every((step) => exports.SANCTUARY_UPGRADE_STEPS.includes(step))
+            || !sides.every((side) => side && DIGEST.test(side.imageId) && DIGEST.test(side.packageDigest) && IMAGE_REFERENCE.test(side.imageReference))
+            || !DIGEST.test(journal.from.rollbackImageId))
+            throw new Error("Sanctuary upgrade journal is invalid");
+        return journal;
+    }
+    #beginUpgrade(input) {
+        this.#record(`${ROOT}/activation.json`, { ...this.#transaction, state: "active", epochId: this.#request.epochId });
+        const current = this.#target();
+        if (input.targetImageId === this.#transaction.targetImageId)
+            throw new Error("Sanctuary already runs the requested image");
+        if (this.#docker(["image", "inspect", "--format", "{{.Id}}", input.imageReference]).trim() !== input.targetImageId)
+            throw new Error("Sanctuary upgrade image identity does not match its reference");
+        const request = validateRequest(JSON.parse(this.#private(INCOMING_REQUEST)));
+        if (["epochId", "botId", "ownerUserId", "ownerChatId"].some((key) => request[key] !== this.#request[key]))
+            throw new Error("Sanctuary upgrade would change the authority identity");
+        if (request.packageDigest === this.#request.packageDigest)
+            throw new Error("Sanctuary upgrade package is already installed");
+        this.#verifyPackage(`${ROOT}/incoming-package`, true, INCOMING_MANIFEST, request);
+        this.#removeTree(PREVIOUS);
+        this.#directory(PREVIOUS);
+        this.#directory(`${PREVIOUS}/epoch`);
+        for (const [name, max] of ROOT_RECORDS)
+            this.#write(`${PREVIOUS}/${name}`, this.#private(`${ROOT}/${name}`, 0o600, max));
+        for (const name of EPOCH_RECORDS)
+            this.#write(`${PREVIOUS}/epoch/${name}`, this.#private(`${this.#epochRoot()}/${name}`));
+        const journal = {
+            schemaVersion: 1, epochId: this.#request.epochId, completed: [],
+            from: { imageId: this.#transaction.targetImageId, imageReference: current.Config.Image, packageDigest: this.#request.packageDigest, rollbackImageId: this.#transaction.rollbackImageId },
+            to: { imageId: input.targetImageId, imageReference: input.imageReference, packageDigest: request.packageDigest },
+        };
+        if (!IMAGE_REFERENCE.test(journal.from.imageReference))
+            throw new Error("Sanctuary current resident image reference is not a reviewed release");
+        this.#write(UPGRADE, JSON.stringify(journal));
+        return journal;
+    }
+    /** Stop the resident, then the gateway, without retiring anything. */
+    async #halt() {
+        this.#assertNoForeignPoller();
+        for (const container of this.#containers())
+            if (container.State.Running)
+                this.#docker(["stop", "--time", "30", container.Name.slice(1)]);
+        if (this.#containers().some((container) => container.State.Running))
+            throw new Error("Sanctuary resident did not stop");
+        const pid = this.#pid();
+        if (pid !== null) {
+            process.kill(pid, "SIGTERM");
+            await this.#wait(() => this.#pid() === null);
+        }
+        this.#remove(`${this.#epochRoot()}/readiness.json`);
+    }
+    #switchPackage(journal) {
+        const manifestText = this.#private(INCOMING_MANIFEST, 0o600, 8 * 1024 * 1024);
+        if (!fs.existsSync(this.#p(`${PREVIOUS}/package`))) {
+            this.#populate(NEXT_PACKAGE, `${ROOT}/incoming-package`, JSON.parse(manifestText));
+            fs.renameSync(this.#p(`${ROOT}/package`), this.#p(`${PREVIOUS}/package`));
+        }
+        if (!fs.existsSync(this.#p(`${ROOT}/package`)))
+            fs.renameSync(this.#p(NEXT_PACKAGE), this.#p(`${ROOT}/package`));
+        this.#write(`${ROOT}/package-manifest.json`, manifestText);
+        this.#write(`${ROOT}/request.json`, this.#private(INCOMING_REQUEST));
+        (0, sanctuary_authority_epoch_1.rebindSanctuaryAuthorityEpochPackage)(this.#p(this.#epochRoot()), { expectedUid: this.#uid, expectedGid: this.#gid, from: journal.from.packageDigest, to: journal.to.packageDigest });
+        const target = new _a({ targetImageId: journal.to.imageId, rollbackImageId: journal.from.imageId }, this.#options);
+        target.#rebindRecords();
+    }
+    /** Copy a reviewed package into a fresh private tree, pin by pin. */
+    #populate(destinationRoot, sourceRoot, manifest) {
+        this.#removeTree(destinationRoot);
+        this.#directory(destinationRoot);
+        for (const [relative, pin] of Object.entries(manifest.files)) {
+            const destination = `${destinationRoot}/${relative}`;
+            this.#directory(path.dirname(destination));
+            fs.copyFileSync(this.#p(`${sourceRoot}/${relative}`), this.#p(destination), fs.constants.COPYFILE_EXCL);
+            fs.chmodSync(this.#p(destination), pin.mode);
+            if (digest(fs.readFileSync(this.#p(destination))) !== pin.digest)
+                throw new Error("Sanctuary upgrade package conflicts with its pin");
+        }
+    }
+    /** Point every epoch record at this lifecycle's (new) package and image, keeping the cursor. */
+    #rebindRecords() {
+        const migration = JSON.parse(this.#private(`${this.#epochRoot()}/migration.json`));
+        if (!Number.isSafeInteger(migration.predecessorCursor) || migration.predecessorCursor < 0)
+            throw new Error("Sanctuary root migration cursor is invalid");
+        this.#write(`${this.#epochRoot()}/migration.json`, JSON.stringify({ ...this.plan(), ...this.#transaction, predecessorCursor: migration.predecessorCursor }));
+        this.#write(`${this.#epochRoot()}/stage.json`, JSON.stringify({ packageDigest: this.#request.packageDigest }));
+        this.#write(`${this.#epochRoot()}/configured.json`, JSON.stringify({ epochId: this.#request.epochId, targetImageId: this.#transaction.targetImageId }));
+        this.#verifyPackage();
+        this.#publishBoot();
+        this.#write(`${ROOT}/active.json`, JSON.stringify(this.#configuration()));
+        this.#write(`${ROOT}/activation.json`, JSON.stringify({ ...this.#transaction, state: "active", epochId: this.#request.epochId }));
+    }
+    /** Point the boot service script at the installed package. On Unraid the host keeper
+     * (not a direct go line) invokes it, so the go file is left as the operator has it. */
+    #publishBoot() {
+        this.#write(BOOT, fs.readFileSync(this.#p(`${ROOT}/package/deploy/unraid/sanctuary-authority-service.sh`), "utf8"));
+    }
+    #recreateResident(reference, imageId) {
+        if (this.#containers().some((container) => container.Name === "/ouro-butler"))
+            this.#docker(["rm", "-f", "ouro-butler"]);
+        this.#docker(["create", "--name", "ouro-butler", "--network", "host", "--restart", "unless-stopped", "--user", "10001:10001",
+            "-l", "net.unraid.docker.managed=dockerman", "-l", `net.unraid.docker.icon=${ICON}`, "-l", "org.opencontainers.image.source=https://github.com/ourostack/ouroboros",
+            "-v", `${RUNTIME}:/home/ouro/.ouro-cli:rw`, "-v", `${BUNDLE}:/home/ouro/AgentBundles/sanctuary.ouro:rw`,
+            "-v", `${EVENTS}:/run/ouro-events:ro`, "-v", `${SOCKET}:${SOCKET}:ro`, reference]);
+        const resident = this.#containers().find((container) => container.Name === "/ouro-butler");
+        if (resident?.Image !== imageId || resident.State.Running)
+            throw new Error("Sanctuary resident recreation readback failed");
+    }
+    /** Run the installed package's bundle migration CLI, then return the bundle to the resident. */
+    #bundle(operation) {
+        (0, node_child_process_1.execFileSync)(this.#p("/usr/local/bin/node"), [this.#p(`${ROOT}/package/deploy/unraid/migrate-sanctuary-bundle.mjs`),
+            "--package-root", this.#p(`${ROOT}/package/deploy/unraid/sanctuary.ouro`), "--agent-root", this.#p(BUNDLE), ...operation], {
+            encoding: "utf8", timeout: 300_000, stdio: ["ignore", "pipe", "pipe"], env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }, cwd: "/",
+        });
+        (0, node_child_process_1.execFileSync)("/bin/chown", ["-R", "10001:10001", this.#p(BUNDLE)], { stdio: "ignore" });
+    }
+    /** Start the gateway, then the resident, and prove both. */
+    async #startUpgraded() {
+        await this.#startGateway();
+        this.#docker(["start", "ouro-butler"]);
+        await this.#wait(async () => this.#target().State.Running && this.#target().State.Health?.Status === "healthy" && await this.#ready(), 300_000);
+    }
+    #removeTree(absolute) {
+        fs.rmSync(this.#p(absolute), { recursive: true, force: true });
+    }
     #remove(absolute) {
         if (!fs.existsSync(this.#p(absolute)))
             return;
@@ -772,6 +1007,21 @@ class SanctuaryAuthorityRootLifecycle {
     }
 }
 exports.SanctuaryAuthorityRootLifecycle = SanctuaryAuthorityRootLifecycle;
+_a = SanctuaryAuthorityRootLifecycle;
+/**
+ * Keep the real failure where only root can read it (D-034). Stderr stays generic
+ * because a parse error can quote private bytes; the authority root is as private
+ * as the token it already holds.
+ */
+function recordSanctuaryRootLifecycleFailure(error, file = `${ROOT}/lifecycle-failure.log`) {
+    try {
+        fs.appendFileSync(file, `${new Date().toISOString()} ${error instanceof Error ? error.stack : String(error)}\n`, { mode: 0o600 });
+        return ` Details (root-only): ${file}`;
+    }
+    catch {
+        return "";
+    }
+}
 async function runSanctuaryAuthorityRootCli(argv, write = (text) => process.stdout.write(text)) {
     if (process.getuid() !== 0 || process.getgid() !== 0)
         throw new Error("Sanctuary root lifecycle requires root");
@@ -792,12 +1042,15 @@ async function runSanctuaryAuthorityRootCli(argv, write = (text) => process.stdo
         return;
     }
     const repin = argv.length === 3 && argv[0] === "repin-execution";
-    if (!repin && (argv.length !== 1 || argv[0] !== "boot"))
-        throw new Error("Usage: sanctuary-authority-root-lifecycle <boot|repin-execution <prlimit-sha256> <setsid-sha256>|vault snapshot|vault presence|vault remove|vault restore>");
-    await (0, session_transaction_1.withSessionTurnLease)("/boot/config/custom/ouro-butler/docker-man-template-transaction.json", async () => {
+    const upgrade = argv[0] === "upgrade" && (argv.length === 3 || (argv.length === 5 && argv[3] === "--fail-after"));
+    const rollback = argv.length === 1 && argv[0] === "upgrade-rollback";
+    if (!repin && !upgrade && !rollback && (argv.length !== 1 || argv[0] !== "boot"))
+        throw new Error("Usage: sanctuary-authority-root-lifecycle <boot|repin-execution <prlimit-sha256> <setsid-sha256>|upgrade <target-image-id> <image-reference> [--fail-after <step>]|upgrade-rollback|vault snapshot|vault presence|vault remove|vault restore>");
+    // Boot never waits: the host keeper retries it. An operator upgrade waits out a boot in flight.
+    await (0, session_transaction_1.withSessionTurnLease)(TEMPLATE_JOURNAL, async () => {
         const activationPath = `${ROOT}/activation.json`;
         if (!fs.existsSync(activationPath)) {
-            if (repin)
+            if (repin || upgrade || rollback)
                 throw new Error("Sanctuary authority is not active");
             return;
         }
@@ -807,13 +1060,20 @@ async function runSanctuaryAuthorityRootCli(argv, write = (text) => process.stdo
             lifecycle.repinExecution(argv[1], argv[2]);
             write('{"repinned":true,"gatewayRestartRequired":true}\n');
         }
+        else if (upgrade) {
+            await lifecycle.upgrade({ targetImageId: argv[1], imageReference: argv[2], ...(argv[4] ? { failAfter: argv[4] } : {}) });
+            write(`${JSON.stringify({ upgraded: argv[2] })}\n`);
+        }
+        else if (rollback) {
+            write(`${JSON.stringify({ rolledBack: await lifecycle.rollbackUpgrade() })}\n`);
+        }
         else
             await lifecycle.boot();
-    }, { timeoutMs: 0, confinementRoot: "/boot/config/custom/ouro-butler" });
+    }, { timeoutMs: upgrade || rollback ? 600_000 : 0, confinementRoot: "/boot/config/custom/ouro-butler" });
 }
 if (process.argv[1] && fs.existsSync(process.argv[1]) && fs.realpathSync(process.argv[1]) === __filename) {
-    void runSanctuaryAuthorityRootCli(process.argv.slice(2)).catch(() => {
-        process.stderr.write("Sanctuary root lifecycle failed; inspect the root transaction and repair its failed boundary.\n");
+    void runSanctuaryAuthorityRootCli(process.argv.slice(2)).catch((error) => {
+        process.stderr.write(`Sanctuary root lifecycle failed; inspect the root transaction and repair its failed boundary.${recordSanctuaryRootLifecycleFailure(error)}\n`);
         process.exitCode = 1;
     });
 }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.834",
+  "version": "0.1.0-alpha.835",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.834",
+      "version": "0.1.0-alpha.835",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.834",
+  "version": "0.1.0-alpha.835",
   "engines": {
     "node": ">=22"
   },