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

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/dist/repertoire/tools.js

@@ -74,6 +74,8 @@ exports.SANCTUARY_MCP_PROVIDED_TOOLS = new Set([
     "media_search", "media_request", "media_request_status",
     "media_diagnose_and_fix", "media_chain_health", "media_play_or_resolve",
 ]);
+/** Channels a Sanctuary turn can arrive on from the host itself, not from a remote party. */
+const SANCTUARY_LOCAL_CHANNELS = new Set(["inner", "cli", "mcp"]);
 exports.SANCTUARY_OWNER_ADDITIONS = new Set([
     "shell", "shell_status", "shell_tail", "read_file", "write_file", "edit_file", "glob", "grep",
     "web_search", "search_facts", "consult_diary", "consult_notes", "get_friend_note",
@@ -125,10 +127,20 @@ function applyPreference(tool, pref) {
 function selectToolsForChannel(capabilities, toolPreferences, _context, providerCapabilities, mcpManager, _chatModel, context) {
     const relationship = context?.relationshipAuthorization;
     const profileId = relationship?.profileId;
-    const sanctuary = (context?.agentName === "sanctuary" && (relationship !== undefined || capabilities?.channel === "telegram"))
+    // Every Sanctuary turn that reaches the agent from outside the host (Telegram, A2A,
+    // any future remote sense) is relationship-scoped: without a known capability
+    // profile it gets no tools at all. Only the Butler's own local channels (its inner
+    // loop and the host-local CLI/MCP) keep the unscoped tool set.
+    const channel = capabilities?.channel;
+    const remote = channel !== undefined && !SANCTUARY_LOCAL_CHANNELS.has(channel);
+    const sanctuary = (context?.agentName === "sanctuary" && (relationship !== undefined || remote))
         || profileId?.startsWith("sanctuary-") === true;
     const owner = profileId === "sanctuary-owner";
-    const knownSanctuaryProfile = relationship !== undefined && (owner || profileId === "sanctuary-household" || profileId === "sanctuary-event");
+    // A trusted peer agent acting for the owner gets the owner's chat tool menu. Host
+    // execution and approval-gated routine actions stay Telegram-owner-only: the host
+    // tool is only ever added on the Telegram channel, and the peer profile omits them.
+    const ownerLike = owner || profileId === "sanctuary-agent-peer";
+    const knownSanctuaryProfile = relationship !== undefined && (ownerLike || profileId === "sanctuary-household" || profileId === "sanctuary-event");
     const mcp = mcpManager ? (0, mcp_tools_1.mcpToolsAsDefinitions)(mcpManager) : [];
     const native = [...tools_base_1.baseToolDefinitions, ...additionalDefinitions];
     assertUniqueToolSchemas([
@@ -140,8 +152,8 @@ function selectToolsForChannel(capabilities, toolPreferences, _context, provider
         ordinary = knownSanctuaryProfile
             ? [
                 ...tools_base_1.baseToolDefinitions.filter((definition) => SANCTUARY_RELATIONSHIP_BASE_TOOLS.has(definition.tool.function.name)
-                    || (owner && exports.SANCTUARY_OWNER_ADDITIONS.has(definition.tool.function.name))),
-                ...tools_unraid_1.unraidToolDefinitions, tools_steward_policy_1.stewardPolicyToolDefinition, ...(owner ? mcp : []),
+                    || (ownerLike && exports.SANCTUARY_OWNER_ADDITIONS.has(definition.tool.function.name))),
+                ...tools_unraid_1.unraidToolDefinitions, tools_steward_policy_1.stewardPolicyToolDefinition, ...(ownerLike ? mcp : []),
             ]
             : [];
     }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.833",
+  "version": "0.1.0-alpha.835",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.833",
+      "version": "0.1.0-alpha.835",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",
@@ -18,7 +18,7 @@
         "@microsoft/teams.common": "2.0.11",
         "@microsoft/teams.dev": "2.0.11",
         "@microsoft/teams.graph": "2.0.11",
-        "@ouro.bot/friends": "0.1.0-alpha.10",
+        "@ouro.bot/friends": "0.1.0-alpha.12",
         "@types/react": "^17.0.91",
         "@types/ws": "^8.18.1",
         "ajv": "^8.20.0",
@@ -1357,9 +1357,9 @@
       }
     },
     "node_modules/@ouro.bot/friends": {
-      "version": "0.1.0-alpha.10",
-      "resolved": "https://registry.npmjs.org/@ouro.bot/friends/-/friends-0.1.0-alpha.10.tgz",
-      "integrity": "sha512-HxKCXDv74pWnVPcyEYyWn4L1Okg4otanHo3o80J1yofN2ycb56Nreimj+IPSTf7d3lthIsoSbksgIpDyE11OGw==",
+      "version": "0.1.0-alpha.12",
+      "resolved": "https://registry.npmjs.org/@ouro.bot/friends/-/friends-0.1.0-alpha.12.tgz",
+      "integrity": "sha512-pzV2PQvi1eUkcog3iDDHIvwSBDwpsB8/ykrJpoZQ/wB84qQa0xGKJSDnTt45r8H4j/68Cc5LU6vcjlwI5GG47g==",
       "license": "Apache-2.0",
       "dependencies": {
         "libsodium-wrappers": "0.8.4"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.833",
+  "version": "0.1.0-alpha.835",
   "engines": {
     "node": ">=22"
   },
@@ -65,7 +65,7 @@
     "@microsoft/teams.common": "2.0.11",
     "@microsoft/teams.dev": "2.0.11",
     "@microsoft/teams.graph": "2.0.11",
-    "@ouro.bot/friends": "0.1.0-alpha.10",
+    "@ouro.bot/friends": "0.1.0-alpha.12",
     "@types/react": "^17.0.91",
     "@types/ws": "^8.18.1",
     "ajv": "^8.20.0",