@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.831

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

@@ -0,0 +1,819 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SanctuaryAuthorityRootLifecycle = void 0;
+exports.runSanctuaryAuthorityRootCli = runSanctuaryAuthorityRootCli;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const telegram_client_1 = require("../../senses/telegram-client");
+const sanctuary_authority_installation_1 = require("./sanctuary-authority-installation");
+const sanctuary_authority_epoch_1 = require("./sanctuary-authority-epoch");
+const sanctuary_telegram_authority_gateway_1 = require("./sanctuary-telegram-authority-gateway");
+const sanctuary_authority_resident_1 = require("../../senses/sanctuary-authority-resident");
+const sanctuary_authority_vault_migration_1 = require("./sanctuary-authority-vault-migration");
+const session_transaction_1 = require("../../mind/session-transaction");
+const runtime_1 = require("../../nerves/runtime");
+const ROOT = "/mnt/user/appdata/ouro-authority";
+const BUNDLE = "/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro";
+const RUNTIME = "/mnt/user/appdata/ouro-butler/runtime/.ouro-cli";
+const OFFSET = `${BUNDLE}/state/senses/telegram/offset.json`;
+const SOCKET = "/run/ouro-authority";
+const STAGING = "/var/lib/ouro-authority/staging";
+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 digest = (value) => `sha256:${(0, node_crypto_1.createHash)("sha256").update(value).digest("hex")}`;
+// The prefix is a filesystem-fixture seam; the production CLI never accepts it.
+class SanctuaryAuthorityRootLifecycle {
+    #request;
+    #transaction;
+    #prefix;
+    #uid;
+    #gid;
+    #socketGid;
+    constructor(transaction, options = {}) {
+        this.#prefix = options.prefix ?? "";
+        this.#uid = options.expectedUid ?? 0;
+        this.#gid = options.expectedGid ?? 0;
+        this.#socketGid = options.socketGroupId ?? 10001;
+        if (process.getuid() !== this.#uid || process.getgid() !== this.#gid)
+            throw new Error("Sanctuary root lifecycle requires root");
+        if (!DIGEST.test(transaction.targetImageId) || !DIGEST.test(transaction.rollbackImageId) || transaction.targetImageId === transaction.rollbackImageId)
+            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 } });
+    }
+    plan() {
+        const { epochId, botId, ownerUserId, ownerChatId, packageDigest } = this.#request;
+        return { schemaVersion: 1, epochId, botId, ownerUserId, ownerChatId, packageDigest, publicKeyDigest: null, predecessorContract: "canonical-pre-gateway", targetContract: "canonical-gateway" };
+    }
+    async boot() {
+        if (!fs.existsSync(this.#p(`${ROOT}/activation.json`)))
+            return false;
+        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");
+        this.#assertNoForeignPoller();
+        this.#target();
+        if (this.#containers().some((container) => container.Name !== "/ouro-butler" && container.State.Running))
+            throw new Error("Sanctuary rollback resident is running");
+        this.#runtimeDirectories();
+        this.#verifyPackage(undefined, false);
+        // Boot may already have a tokenless resident under Docker's restart policy.
+        // Only handoff requires us to start it strictly after gateway readiness.
+        await this.#startGateway(true);
+        return true;
+    }
+    repinExecution(prlimitDigest, setsidDigest) {
+        if (![prlimitDigest, setsidDigest].every(pin => DIGEST.test(pin)))
+            throw new Error("Reviewed execution digests are required");
+        if (fs.existsSync(this.#p("/boot/config/custom/ouro-butler/docker-man-template-transaction.json")))
+            throw new Error("Finish the pending installation before re-pinning");
+        this.#record(`${ROOT}/activation.json`, { ...this.#transaction, state: "active", epochId: this.#request.epochId });
+        this.#verifyPackage(undefined, false);
+        if (this.#pid() !== null)
+            throw new Error("Stop the verified gateway process before re-pinning");
+        for (const name of ["executions", "supervisors"]) {
+            const directory = `${this.#epochRoot()}/${name}`;
+            if (fs.existsSync(this.#p(directory))) {
+                this.#directory(directory);
+                if (fs.readdirSync(this.#p(directory)).length !== 0)
+                    throw new Error("Resolve pending execution state before re-pinning");
+            }
+        }
+        if (fs.readdirSync(this.#p(CGROUP)).some(name => fs.lstatSync(this.#p(`${CGROUP}/${name}`)).isDirectory()))
+            throw new Error("Resolve pending cgroups before re-pinning");
+        this.#verifyPrimitive("/usr/bin/prlimit", prlimitDigest);
+        this.#verifyPrimitive("/usr/bin/setsid", setsidDigest);
+        const currentRequest = JSON.parse(this.#private(`${ROOT}/request.json`));
+        if (JSON.stringify(currentRequest) !== JSON.stringify(this.#request))
+            throw new Error("Sanctuary re-pin request changed");
+        const configuration = { ...this.#configuration(), hostPrlimitDigest: prlimitDigest, hostSetsidDigest: setsidDigest };
+        const current = JSON.parse(this.#private(`${ROOT}/active.json`));
+        if (JSON.stringify({ ...current, hostPrlimitDigest: prlimitDigest, hostSetsidDigest: setsidDigest }) !== JSON.stringify(configuration))
+            throw new Error("Sanctuary re-pin configuration changed");
+        const request = { ...this.#request, prlimitDigest, setsidDigest };
+        // Request-first interruption leaves the old runtime pins fail-closed; repeating the command completes publication.
+        this.#write(`${ROOT}/request.json`, JSON.stringify(request));
+        this.#write(`${ROOT}/active.json`, JSON.stringify(configuration));
+        this.#request.prlimitDigest = prlimitDigest;
+        this.#request.setsidDigest = setsidDigest;
+        (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_execution_pins_refreshed", message: "Reviewed Sanctuary execution pins refreshed; gateway restart required", meta: { prlimitDigest, setsidDigest } });
+    }
+    effect(step) {
+        const effects = {
+            "freeze-resident": { read: () => this.#frozen(), apply: () => this.#freeze() },
+            "stage-authority": { read: () => this.#staged(), apply: () => this.#stage() },
+            "verify-token-rotation": { read: () => this.#rotated(), apply: () => this.#rotate() },
+            "transfer-cursor": { read: () => this.#transferred(), apply: () => this.#transfer() },
+            "remove-resident-token": { read: () => this.#tokensAbsent(), apply: () => { this.#requireStopped(); this.#vault("remove"); } },
+            "start-gateway": { read: () => this.#ready(), apply: () => this.#startGateway() },
+            "configure-resident": { read: () => this.#configured(), apply: () => this.#configure() },
+            "start-resident": { read: () => this.#target().State.Running, apply: () => this.#startResident() },
+            "verify-install": { read: () => this.#active(), apply: () => this.#activate() },
+            "rollback:freeze-resident": { read: () => this.#frozen() && !fs.existsSync(this.#p(`${ROOT}/activation.json`)), apply: () => { this.#remove(`${ROOT}/activation.json`); this.#freeze(); } },
+            "rollback:retire-registrations": { read: () => this.#retiredProcess(), apply: () => this.#retireProcess() },
+            "rollback:reconcile-executions": { read: () => this.#retiredProcess(), apply: () => this.#retireProcess() },
+            "rollback:stop-gateway": { read: () => this.#retiredProcess() && this.#pid() === null, apply: () => this.#stopGateway() },
+            "rollback:end-epoch": { read: () => this.#epoch().state === "retired", apply: () => this.#endEpoch() },
+            "rollback:restore-token-cursor": { read: () => this.#restoredToken(), apply: () => this.#restoreToken() },
+            "rollback:restore-resident": { read: () => this.#rollback().State.Running, apply: () => this.#restoreResident() },
+            "rollback:verify-rollback": { read: () => this.#rollbackVerified(), apply: () => this.#verifyRollback() },
+        };
+        const effect = effects[step];
+        if (!effect)
+            throw new Error("Sanctuary root lifecycle effect is invalid");
+        const beforeDigest = digest(`${this.#request.epochId}:${step}:before`);
+        const afterDigest = digest(`${this.#request.epochId}:${step}:after`);
+        return {
+            beforeDigest, afterDigest,
+            readback: async () => await effect.read() ? afterDigest : beforeDigest,
+            apply: async () => { await effect.apply(); },
+        };
+    }
+    #frozen() {
+        this.#assertNoForeignPoller();
+        if (!this.#containers().every((container) => !container.State.Running) || !fs.existsSync(this.#p(`${this.#epochRoot()}/migration.json`)))
+            return false;
+        this.#migration();
+        return true;
+    }
+    #freeze() {
+        this.#assertNoForeignPoller();
+        for (const container of this.#containers()) {
+            if (![this.#transaction.targetImageId, this.#transaction.rollbackImageId].includes(container.Image))
+                throw new Error("Sanctuary resident image changed");
+            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");
+        if (fs.existsSync(this.#p(`${this.#epochRoot()}/migration.json`))) {
+            this.#migration();
+            return;
+        }
+        if (fs.existsSync(this.#p(`${ROOT}/active.json`))) {
+            const previous = JSON.parse(this.#private(`${ROOT}/active.json`));
+            const epoch = (0, sanctuary_authority_epoch_1.readSanctuaryAuthorityEpoch)(previous.epochRoot, { expectedUid: this.#uid, expectedGid: this.#gid });
+            if (epoch.state !== "retired" || !fs.existsSync(path.join(previous.epochRoot, "handoff.json"))
+                || fs.existsSync(this.#p(`${ROOT}/activation.json`)))
+                throw new Error("Sanctuary previous epoch handoff is incomplete");
+        }
+        // A missing cursor is not a fresh install: it is lost handoff evidence.
+        fs.lstatSync(this.#p(OFFSET));
+        const predecessorCursor = new telegram_client_1.FileTelegramOffsetStore(this.#p(OFFSET)).load();
+        const snapshot = this.#vault("snapshot");
+        if (["botId", "ownerUserId", "ownerChatId"].some((key) => snapshot[key] !== this.#request[key]))
+            throw new Error("Sanctuary predecessor identity changed");
+        this.#write(`${ROOT}/epochs/${this.#request.epochId}/previous-token`, snapshot.token);
+        this.#write(`${this.#epochRoot()}/migration.json`, JSON.stringify({ ...this.plan(), ...this.#transaction, predecessorCursor }));
+    }
+    #epochRoot() { return `${ROOT}/epochs/${this.#request.epochId}`; }
+    #migration() {
+        const value = JSON.parse(this.#private(`${this.#epochRoot()}/migration.json`));
+        for (const [key, expected] of Object.entries({ ...this.plan(), ...this.#transaction })) {
+            if (value[key] !== expected)
+                throw new Error("Sanctuary root migration identity changed");
+        }
+        if (!Number.isSafeInteger(value.predecessorCursor) || value.predecessorCursor < 0)
+            throw new Error("Sanctuary root migration cursor is invalid");
+        return value;
+    }
+    #directory(absolute, mode = 0o700, gid = this.#gid) {
+        const directory = this.#p(absolute);
+        if (!fs.existsSync(directory)) {
+            fs.mkdirSync(directory, { recursive: true, mode });
+            fs.chownSync(directory, this.#uid, gid);
+            fs.chmodSync(directory, mode);
+        }
+        const stat = fs.lstatSync(directory);
+        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) {
+        (0, sanctuary_authority_installation_1.verifySanctuaryAuthorityInstallation)({
+            packageRoot: this.#p(packageRoot), manifestPath: this.#p(`${ROOT}/package-manifest.json`), manifestDigest: this.#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));
+        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]] : []),
+        ]) {
+            this.#verifyPrimitive(file, expected);
+        }
+    }
+    #verifyPrimitive(file, expected) {
+        const actual = this.#p(file);
+        const stat = fs.statSync(actual);
+        if (!stat.isFile() || stat.uid !== this.#uid || stat.gid !== this.#gid || (stat.mode & 0o022) !== 0 || (stat.mode & 0o111) === 0 || digest(fs.readFileSync(actual)) !== expected)
+            throw new Error("Sanctuary host primitive pin changed");
+    }
+    #staged(hostExecution = true) {
+        if (!fs.existsSync(this.#p(`${this.#epochRoot()}/stage.json`)))
+            return false;
+        this.#record(`${this.#epochRoot()}/stage.json`, { packageDigest: this.#request.packageDigest });
+        this.#verifyPackage(undefined, hostExecution);
+        if (this.#bootScript().text.split("\n").filter((line) => line === BOOT_LINE).length !== 1
+            || digest(this.#private(BOOT)) !== digest(fs.readFileSync(this.#p(`${ROOT}/package/deploy/unraid/sanctuary-authority-service.sh`))))
+            throw new Error("Sanctuary installed boot lifecycle changed");
+        return true;
+    }
+    #runtimeDirectories() {
+        for (const directory of [this.#epochRoot(), STAGING, CGROUP])
+            this.#directory(directory);
+        this.#directory(SOCKET, 0o750, this.#socketGid);
+        // Add only the required controllers; never replace another owner's controls.
+        for (const root of ["/sys/fs/cgroup", CGROUP]) {
+            const control = this.#p(`${root}/cgroup.subtree_control`);
+            if (fs.existsSync(control)) {
+                const enabled = fs.readFileSync(control, "utf8").trim().split(/\s+/u);
+                const missing = ["cpu", "memory", "pids"].filter((name) => !enabled.includes(name));
+                if (missing.length)
+                    fs.writeFileSync(control, missing.map((name) => `+${name}`).join(" "));
+            }
+        }
+    }
+    #stage(hostExecution = true) {
+        this.#migration();
+        this.#runtimeDirectories();
+        this.#verifyPackage(`${ROOT}/incoming-package`, hostExecution);
+        const manifest = JSON.parse(this.#private(`${ROOT}/package-manifest.json`, 0o600, 8 * 1024 * 1024));
+        this.#directory(`${ROOT}/package`);
+        for (const [relative, pin] of Object.entries(manifest.files)) {
+            const destination = `${ROOT}/package/${relative}`;
+            this.#directory(path.dirname(destination));
+            if (fs.existsSync(this.#p(destination))) {
+                const stat = fs.lstatSync(this.#p(destination));
+                if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.uid !== this.#uid || stat.gid !== this.#gid || (stat.mode & 0o7777) !== pin.mode || fs.realpathSync(this.#p(destination)) !== this.#p(destination))
+                    throw new Error("Sanctuary installed package destination is unsafe");
+                if (digest(fs.readFileSync(this.#p(destination))) !== pin.digest)
+                    throw new Error("Sanctuary installed package conflicts with its pin");
+            }
+            else {
+                fs.copyFileSync(this.#p(`${ROOT}/incoming-package/${relative}`), this.#p(destination), fs.constants.COPYFILE_EXCL);
+            }
+            fs.chmodSync(this.#p(destination), pin.mode);
+        }
+        this.#verifyPackage(undefined, hostExecution);
+        const { text: boot, mode: bootMode } = this.#bootScript();
+        if (boot.split("\n").some((line) => line.includes("ouro-authority") && line !== BOOT_LINE))
+            throw new Error("Sanctuary boot ownership is ambiguous");
+        this.#write(BOOT, fs.readFileSync(this.#p(`${ROOT}/package/deploy/unraid/sanctuary-authority-service.sh`), "utf8"));
+        if (!boot.split("\n").includes(BOOT_LINE))
+            this.#write("/boot/config/go", `${boot}${boot.endsWith("\n") ? "" : "\n"}${BOOT_LINE}\n`, bootMode);
+        this.#write(`${this.#epochRoot()}/stage.json`, JSON.stringify({ packageDigest: this.#request.packageDigest }));
+    }
+    #epoch() {
+        const epoch = (0, sanctuary_authority_epoch_1.readSanctuaryAuthorityEpoch)(this.#p(this.#epochRoot()), { expectedUid: this.#uid, expectedGid: this.#gid });
+        if (epoch.epochId !== this.#request.epochId || epoch.botId !== this.#request.botId || epoch.ownerUserId !== this.#request.ownerUserId
+            || epoch.ownerChatId !== this.#request.ownerChatId || epoch.packageDigest !== this.#request.packageDigest
+            || epoch.predecessorCursor !== this.#migration().predecessorCursor)
+            throw new Error("Sanctuary root epoch identity changed");
+        return epoch;
+    }
+    #rotated() {
+        if (!fs.existsSync(this.#p(`${this.#epochRoot()}/epoch.json`)))
+            return false;
+        if (this.#epoch().state !== "prepared")
+            throw new Error("Sanctuary root epoch is retired");
+        return true;
+    }
+    async #rotate(hostExecution = true) {
+        if (!this.#frozen() || !this.#staged(hostExecution))
+            throw new Error("Sanctuary root installation must be frozen and staged");
+        const token = this.#private(`${ROOT}/incoming-token`).trim();
+        this.#write(`${this.#epochRoot()}/current-token`, token);
+        await (0, sanctuary_authority_epoch_1.prepareSanctuaryAuthorityEpoch)({
+            root: this.#p(this.#epochRoot()), epochId: this.#request.epochId, tokenPath: this.#p(`${this.#epochRoot()}/current-token`),
+            previousTokenPath: this.#p(`${this.#epochRoot()}/previous-token`), botId: this.#request.botId,
+            ownerUserId: this.#request.ownerUserId, ownerChatId: this.#request.ownerChatId,
+            predecessorCursor: this.#migration().predecessorCursor, packageDigest: this.#request.packageDigest,
+        }, {
+            expectedUid: this.#uid, expectedGid: this.#gid, now: () => new Date().toISOString(),
+            probe: async (value) => {
+                const response = await fetch(`https://api.telegram.org/bot${value}/getMe`, { signal: AbortSignal.timeout(15_000) });
+                const body = await response.json();
+                return { status: response.status, botId: body.ok === true && Number.isSafeInteger(body.result?.id) ? String(body.result.id) : null };
+            },
+        });
+    }
+    #gateway() {
+        const epoch = this.#epoch();
+        return new sanctuary_telegram_authority_gateway_1.FileSanctuaryTelegramAuthorityGateway(this.#p(`${this.#epochRoot()}/agent`), {
+            targetHost: "sanctuary", botId: epoch.botId, ownerUserId: epoch.ownerUserId, ownerChatId: epoch.ownerChatId,
+            keyId: epoch.epochId, publicKeyDigest: epoch.publicKeyDigest, privateKey: (0, node_crypto_1.createPrivateKey)(this.#private(`${this.#epochRoot()}/issuer.pem`)),
+        });
+    }
+    #transferred() {
+        if (!fs.existsSync(this.#p(`${ROOT}/active.json`)))
+            return false;
+        if (!fs.existsSync((0, sanctuary_telegram_authority_gateway_1.sanctuaryTelegramAuthorityStatePath)(this.#p(`${this.#epochRoot()}/agent`))))
+            return false;
+        if (JSON.stringify(JSON.parse(this.#private(`${ROOT}/active.json`))) !== JSON.stringify(this.#configuration()))
+            throw new Error("Sanctuary root configuration changed during handoff");
+        if (this.#gateway().cursor() !== this.#migration().predecessorCursor)
+            throw new Error("Sanctuary root handoff cursor changed");
+        return true;
+    }
+    #transfer() {
+        if (!this.#frozen() || !this.#rotated())
+            throw new Error("Sanctuary root epoch is not ready for cursor handoff");
+        this.#gateway().initializeCursor(this.#epoch().predecessorCursor);
+        this.#write(`${ROOT}/active.json`, JSON.stringify(this.#configuration()));
+    }
+    #configuration() {
+        const epoch = this.#epoch();
+        const program = `${ROOT}/package/dist/heart/daemon/sanctuary-host-supervisor-entry.js`;
+        const launcher = `${ROOT}/package/deploy/unraid/sanctuary-host-launcher.sh`;
+        const config = {
+            schemaVersion: 1, targetHost: "sanctuary", botId: epoch.botId, ownerUserId: epoch.ownerUserId, ownerChatId: epoch.ownerChatId,
+            keyId: epoch.epochId, publicKeyDigest: epoch.publicKeyDigest, socketGroupId: this.#socketGid,
+            agentRoot: this.#p(`${this.#epochRoot()}/agent`), epochRoot: this.#p(this.#epochRoot()),
+            tokenPath: epoch.tokenPath, privateKeyPath: this.#p(`${this.#epochRoot()}/issuer.pem`),
+            socketPath: this.#p(`${SOCKET}/authority.sock`), readinessPath: this.#p(`${this.#epochRoot()}/readiness.json`), lockPath: this.#p(`${this.#epochRoot()}/authority.lock`),
+            hostStagingRoot: this.#p(STAGING), hostExecutionStateRoot: this.#p(`${this.#epochRoot()}/executions`), hostSupervisorStateRoot: this.#p(`${this.#epochRoot()}/supervisors`),
+            hostCgroupRoot: this.#p(CGROUP), hostSupervisorProgramPath: this.#p(program), hostSupervisorProgramDigest: digest(fs.readFileSync(this.#p(program))),
+            hostLauncherPath: this.#p(launcher), hostLauncherDigest: digest(fs.readFileSync(this.#p(launcher))),
+            hostPrlimitPath: this.#p("/usr/bin/prlimit"), hostPrlimitDigest: this.#request.prlimitDigest,
+            hostSetsidPath: this.#p("/usr/bin/setsid"), hostSetsidDigest: this.#request.setsidDigest, hostShellPath: this.#p("/bin/sh"), hostShellDigest: this.#request.shellDigest,
+            packageRoot: this.#p(`${ROOT}/package`), packageManifestPath: this.#p(`${ROOT}/package-manifest.json`), packageManifestDigest: this.#request.packageDigest,
+        };
+        return config;
+    }
+    #requireStopped() {
+        this.#assertNoForeignPoller();
+        if (this.#containers().some((container) => container.State.Running))
+            throw new Error("Sanctuary resident must be stopped");
+    }
+    #tokensAbsent() {
+        const presence = this.#vault("presence");
+        if (!presence || Object.keys(presence).join(",") !== "tokenPresent" || typeof presence.tokenPresent !== "boolean")
+            throw new Error("Sanctuary vault presence readback is invalid");
+        return !presence.tokenPresent;
+    }
+    #pid() {
+        const lock = `${this.#epochRoot()}/authority.lock`;
+        if (!fs.existsSync(this.#p(lock)))
+            return null;
+        const pid = Number(this.#private(lock));
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            throw new Error("Sanctuary gateway process lock is invalid");
+        if (!fs.existsSync(this.#p(`/proc/${pid}`)))
+            return null;
+        const status = fs.readFileSync(this.#p(`/proc/${pid}/status`), "utf8");
+        const command = fs.readFileSync(this.#p(`/proc/${pid}/cmdline`), "utf8");
+        const expected = [this.#p("/usr/local/bin/node"), this.#p(`${ROOT}/package/dist/heart/daemon/sanctuary-telegram-authority-entry.js`), "--config", this.#p(`${ROOT}/active.json`), ""].join("\0");
+        if (!status.split("\n").includes(`Uid:\t${this.#uid}\t${this.#uid}\t${this.#uid}\t${this.#uid}`) || command !== expected)
+            throw new Error("Sanctuary gateway process identity changed");
+        return pid;
+    }
+    async #ready() {
+        if (!fs.existsSync(this.#p(`${this.#epochRoot()}/readiness.json`)))
+            return false;
+        if (this.#pid() === null)
+            throw new Error("Sanctuary gateway readiness has no live process");
+        const epoch = this.#epoch();
+        const readiness = JSON.parse(this.#private(`${this.#epochRoot()}/readiness.json`));
+        if (readiness.status !== "ready" || readiness.botId !== epoch.botId || readiness.publicKeyDigest !== epoch.publicKeyDigest)
+            throw new Error("Sanctuary gateway readiness identity changed");
+        const authority = (0, sanctuary_authority_resident_1.openSanctuaryResidentAuthority)({}, {}, { configPath: this.#p(`${SOCKET}/resident.json`), expectedUid: this.#uid, expectedGid: this.#socketGid });
+        try {
+            const snapshot = await authority.cursorSnapshot();
+            if (snapshot.keyId !== epoch.epochId || snapshot.botId !== epoch.botId || snapshot.publicKeyDigest !== epoch.publicKeyDigest || snapshot.cursor < epoch.predecessorCursor)
+                throw new Error("Sanctuary gateway signed readiness changed");
+            return true;
+        }
+        finally {
+            authority.authorityTransport.api.stop();
+        }
+    }
+    async #wait(check, timeoutMs = 120_000) {
+        const until = Date.now() + timeoutMs;
+        while (!await check()) {
+            if (Date.now() >= until)
+                throw new Error("Sanctuary root lifecycle readback timed out");
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    }
+    async #startGateway(boot = false) {
+        if (!boot)
+            this.#requireStopped();
+        this.#verifyPackage(undefined, !boot);
+        if (!this.#tokensAbsent() || !this.#rotated())
+            throw new Error("Sanctuary root token custody is not exclusive");
+        if (this.#pid() === null) {
+            this.#remove(`${this.#epochRoot()}/readiness.json`);
+            const child = (0, node_child_process_1.spawn)(this.#p("/usr/local/bin/node"), [this.#p(`${ROOT}/package/dist/heart/daemon/sanctuary-telegram-authority-entry.js`), "--config", this.#p(`${ROOT}/active.json`)], {
+                cwd: "/", env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }, detached: true, stdio: "ignore",
+            });
+            child.unref();
+            let failed = false;
+            child.once("error", () => { failed = true; });
+            await this.#wait(async () => {
+                if (failed)
+                    throw new Error("Sanctuary gateway launch failed");
+                return this.#ready();
+            });
+        }
+        else
+            await this.#wait(() => this.#ready());
+    }
+    #target() {
+        const target = this.#containers().find((container) => container.Name === "/ouro-butler");
+        if (!target || target.Image !== this.#transaction.targetImageId || target.Config.User !== "10001:10001"
+            || target.Config.Env.some((entry) => /telegram.*token|bot.*token/iu.test(entry))
+            || target.Mounts.filter((mount) => mount.Source === SOCKET && mount.Destination === SOCKET && mount.RW === false).length !== 1
+            || target.Mounts.some((mount) => mount.Source === "/var/run/docker.sock" || mount.Source.startsWith(ROOT)))
+            throw new Error("Sanctuary target resident is not tokenless and gateway-mounted");
+        return target;
+    }
+    #configured() {
+        if (!fs.existsSync(this.#p(`${this.#epochRoot()}/configured.json`)))
+            return false;
+        this.#record(`${this.#epochRoot()}/configured.json`, { epochId: this.#request.epochId, targetImageId: this.#transaction.targetImageId });
+        this.#target();
+        return this.#tokensAbsent() && this.#directAutostartDisabled();
+    }
+    async #configure() {
+        this.#requireStopped();
+        this.#target();
+        if (!this.#tokensAbsent() || !this.#directAutostartDisabled() || !await this.#ready())
+            throw new Error("Sanctuary gateway must be ready and direct autostart disabled before configuring the resident");
+        this.#write(`${this.#epochRoot()}/configured.json`, JSON.stringify({ epochId: this.#request.epochId, targetImageId: this.#transaction.targetImageId }));
+    }
+    async #startResident() {
+        this.#assertNoForeignPoller();
+        if (!this.#configured() || !await this.#ready())
+            throw new Error("Sanctuary gateway must be ready before resident startup");
+        if (this.#containers().some((container) => container.Name !== "/ouro-butler" && container.State.Running))
+            throw new Error("Sanctuary rollback resident is running");
+        if (!this.#target().State.Running)
+            this.#docker(["start", "ouro-butler"]);
+        await this.#wait(() => this.#target().State.Running && this.#target().State.Health?.Status === "healthy");
+    }
+    async #active() {
+        if (!fs.existsSync(this.#p(`${ROOT}/activation.json`)))
+            return false;
+        this.#record(`${ROOT}/activation.json`, { ...this.#transaction, state: "active", epochId: this.#request.epochId });
+        return this.#configured() && this.#target().State.Running && this.#target().State.Health?.Status === "healthy" && await this.#ready();
+    }
+    async #activate() {
+        if (!this.#configured() || !this.#target().State.Running || this.#target().State.Health?.Status !== "healthy" || !await this.#ready())
+            throw new Error("Sanctuary activation readback failed");
+        this.#write(`${ROOT}/activation.json`, JSON.stringify({ ...this.#transaction, state: "active", epochId: this.#request.epochId }));
+    }
+    #retiredProcess() {
+        const retirement = `${this.#epochRoot()}/retirement.json`;
+        if (!fs.existsSync(this.#p(retirement)))
+            return false;
+        const proof = JSON.parse(this.#private(retirement));
+        const epoch = this.#epoch();
+        if (proof.schemaVersion !== 1 || proof.keyId !== epoch.epochId || proof.publicKeyDigest !== epoch.publicKeyDigest || proof.quiescent !== true
+            || !Number.isSafeInteger(proof.cursor) || proof.cursor < epoch.predecessorCursor
+            || fs.readdirSync(this.#p(CGROUP)).some((entry) => fs.lstatSync(this.#p(`${CGROUP}/${entry}`)).isDirectory()))
+            throw new Error("Sanctuary gateway retirement cleanup is unproven");
+        return true;
+    }
+    async #retireProcess() {
+        this.#requireStopped();
+        if (this.#retiredProcess())
+            return;
+        // An interrupted installation may never have published an epoch/config.
+        // Complete only the root prerequisites needed to retire it; never start
+        // ingress or a resident while recovering this rollback intent.
+        if (!fs.existsSync(this.#p(`${this.#epochRoot()}/epoch.json`))) {
+            if (!this.#staged(false))
+                this.#stage(false);
+            await this.#rotate(false);
+        }
+        if (!fs.existsSync(this.#p(`${ROOT}/active.json`)) || JSON.parse(this.#private(`${ROOT}/active.json`)).keyId !== this.#request.epochId)
+            this.#transfer();
+        this.#verifyPackage(undefined, false);
+        const pid = this.#pid();
+        if (pid !== null) {
+            process.kill(pid, "SIGUSR2");
+            await this.#wait(() => this.#retiredProcess(), 1_020_000);
+        }
+        else {
+            (0, node_child_process_1.execFileSync)(this.#p("/usr/local/bin/node"), [this.#p(`${ROOT}/package/dist/heart/daemon/sanctuary-telegram-authority-entry.js`), "--config", this.#p(`${ROOT}/active.json`), "--retire-only"], {
+                encoding: "utf8", timeout: 1_020_000, stdio: ["ignore", "pipe", "pipe"], env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }, cwd: "/",
+            });
+            if (!this.#retiredProcess())
+                throw new Error("Sanctuary gateway retirement readback failed");
+        }
+    }
+    async #stopGateway() {
+        if (!this.#retiredProcess())
+            throw new Error("Sanctuary gateway must retire before stopping");
+        const pid = this.#pid();
+        if (pid !== null) {
+            process.kill(pid, "SIGTERM");
+            await this.#wait(() => this.#pid() === null);
+        }
+        this.#remove(`${this.#epochRoot()}/readiness.json`);
+    }
+    #endEpoch() {
+        if (!this.#retiredProcess() || this.#pid() !== null)
+            throw new Error("Sanctuary gateway must retire and stop before ending its epoch");
+        const proof = JSON.parse(this.#private(`${this.#epochRoot()}/retirement.json`));
+        (0, sanctuary_authority_epoch_1.retireSanctuaryAuthorityEpoch)(this.#p(this.#epochRoot()), { expectedUid: this.#uid, expectedGid: this.#gid, quiescent: true, cursor: proof.cursor });
+    }
+    #restoredToken() {
+        if (this.#epoch().state !== "retired" || !fs.existsSync(this.#p(`${this.#epochRoot()}/restored.json`))
+            || !fs.existsSync(this.#p(`${this.#epochRoot()}/handoff.json`)) || fs.existsSync(this.#p(`${this.#epochRoot()}/current-token`)) || fs.existsSync(this.#p(`${ROOT}/incoming-token`)))
+            return false;
+        this.#record(`${this.#epochRoot()}/restored.json`, { tokenDigest: this.#epoch().tokenDigest, cursor: this.#epoch().terminalCursor });
+        const token = this.#vault("snapshot");
+        return digest(token.token) === this.#epoch().tokenDigest && new telegram_client_1.FileTelegramOffsetStore(this.#p(OFFSET)).load() >= this.#epoch().terminalCursor;
+    }
+    #restoreToken() {
+        this.#requireStopped();
+        const epoch = this.#epoch();
+        if (epoch.state !== "retired" || this.#pid() !== null || !this.#retiredProcess())
+            throw new Error("Sanctuary epoch must retire before token handoff");
+        if (this.#restoredToken())
+            return;
+        const token = fs.existsSync(this.#p(`${this.#epochRoot()}/current-token`))
+            ? this.#private(`${this.#epochRoot()}/current-token`).trim() : this.#vault("snapshot").token;
+        if (digest(token) !== epoch.tokenDigest)
+            throw new Error("Sanctuary current token handoff identity changed");
+        this.#vault("restore", { token, botId: epoch.botId, ownerUserId: epoch.ownerUserId, ownerChatId: epoch.ownerChatId });
+        new telegram_client_1.FileTelegramOffsetStore(this.#p(OFFSET)).save(epoch.terminalCursor);
+        // Restore the original resident ownership; root must not strand a root-owned cursor.
+        fs.chownSync(this.#p(OFFSET), this.#uid === 0 ? 10001 : this.#uid, this.#uid === 0 ? 10001 : this.#gid);
+        this.#write(`${this.#epochRoot()}/restored.json`, JSON.stringify({ tokenDigest: epoch.tokenDigest, cursor: epoch.terminalCursor }));
+        const restored = this.#vault("snapshot");
+        if (digest(restored.token) !== epoch.tokenDigest || new telegram_client_1.FileTelegramOffsetStore(this.#p(OFFSET)).load() !== epoch.terminalCursor)
+            throw new Error("Sanctuary token and cursor handoff readback failed");
+        (0, sanctuary_authority_epoch_1.releaseSanctuaryAuthorityToken)(this.#p(this.#epochRoot()), { expectedUid: this.#uid, expectedGid: this.#gid, tokenDigest: epoch.tokenDigest, cursor: epoch.terminalCursor });
+        if (fs.existsSync(this.#p(`${ROOT}/incoming-token`))) {
+            if (digest(this.#private(`${ROOT}/incoming-token`).trim()) !== epoch.tokenDigest)
+                throw new Error("Sanctuary incoming token changed during handoff");
+            this.#remove(`${ROOT}/incoming-token`);
+        }
+    }
+    #rollback() {
+        const resident = this.#containers().find((container) => container.Name === "/ouro-butler");
+        if (!resident || resident.Image !== this.#transaction.rollbackImageId || resident.Config.User !== "10001:10001"
+            || resident.Mounts.some((mount) => mount.Source === SOCKET || mount.Destination === SOCKET))
+            throw new Error("Sanctuary rollback image or socket mount has not been restored");
+        return resident;
+    }
+    async #restoreResident() {
+        this.#assertNoForeignPoller();
+        if (!this.#restoredToken() || this.#pid() !== null)
+            throw new Error("Sanctuary rollback token handoff is incomplete");
+        const resident = this.#rollback();
+        if (!resident.State.Running)
+            this.#docker(["start", "ouro-butler"]);
+        await this.#wait(() => this.#rollback().State.Health?.Status === "healthy" && this.#rollback().State.Running);
+    }
+    #rollbackVerified() {
+        return fs.existsSync(this.#p(`${this.#epochRoot()}/rollback.json`)) && this.#restoredToken() && this.#pid() === null && this.#rollback().State.Running && this.#rollback().State.Health?.Status === "healthy";
+    }
+    #verifyRollback() {
+        if (!this.#restoredToken() || this.#pid() !== null || !this.#rollback().State.Running || this.#rollback().State.Health?.Status !== "healthy")
+            throw new Error("Sanctuary rollback readback failed");
+        this.#write(`${this.#epochRoot()}/rollback.json`, JSON.stringify({ epochId: this.#request.epochId, state: "retired" }));
+    }
+    #remove(absolute) {
+        if (!fs.existsSync(this.#p(absolute)))
+            return;
+        this.#private(absolute);
+        fs.unlinkSync(this.#p(absolute));
+        const directory = fs.openSync(path.dirname(this.#p(absolute)), fs.constants.O_RDONLY);
+        try {
+            fs.fsyncSync(directory);
+        }
+        finally {
+            fs.closeSync(directory);
+        }
+    }
+    #directAutostartDisabled() {
+        const file = this.#p("/var/lib/docker/unraid-autostart");
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== this.#uid || stat.gid !== this.#gid || (stat.mode & 0o7777) !== 0o644)
+            throw new Error("Sanctuary DockerMan autostart state is unsafe");
+        return !fs.readFileSync(file, "utf8").split("\n").some((line) => /^ouro-butler(?:-rollback|-staging|-legacy-evidence)?(?:\s|$)/u.test(line));
+    }
+    #p(absolute) { return `${this.#prefix}${absolute}`; }
+    #bootScript() {
+        const mode = fs.lstatSync(this.#p("/boot/config/go")).mode & 0o7777;
+        if (![0o600, 0o644, 0o700, 0o755].includes(mode))
+            throw new Error("Sanctuary boot script metadata is unsafe");
+        return { text: this.#private("/boot/config/go", mode), mode };
+    }
+    #record(absolute, expected) {
+        const value = JSON.parse(this.#private(absolute));
+        if (!value || Object.keys(value).sort().join(",") !== Object.keys(expected).sort().join(",")
+            || Object.entries(expected).some(([key, entry]) => value[key] !== entry))
+            throw new Error("Sanctuary root lifecycle record identity changed");
+    }
+    #private(absolute, mode = 0o600, maxBytes = 1024 * 1024) {
+        const file = this.#p(absolute);
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const stat = fs.fstatSync(fd);
+            if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== this.#uid || stat.gid !== this.#gid || (stat.mode & 0o7777) !== mode
+                || fs.realpathSync(file) !== file || stat.size < 1 || stat.size > maxBytes)
+                throw new Error("Sanctuary root lifecycle private file is unsafe");
+            return fs.readFileSync(fd, "utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    #write(absolute, value, mode = 0o600) {
+        const file = this.#p(absolute);
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const parent = fs.lstatSync(path.dirname(file));
+        if (parent.uid !== this.#uid || parent.gid !== this.#gid
+            || !(absolute === "/boot/config/go" ? [0o700, 0o755] : [0o700]).includes(parent.mode & 0o7777)
+            || fs.realpathSync(path.dirname(file)) !== path.dirname(file))
+            throw new Error("Sanctuary root lifecycle parent is unsafe");
+        // This temporary belongs exclusively to the fenced root transaction.
+        const temporary = `${file}.tmp`;
+        const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW, 0o600);
+        let owned = false;
+        try {
+            try {
+                const stat = fs.fstatSync(fd);
+                if (stat.nlink !== 1 || !stat.isFile() || stat.uid !== this.#uid || stat.gid !== this.#gid || ![0o600, mode].includes(stat.mode & 0o7777))
+                    throw new Error("Sanctuary root lifecycle temporary is unsafe");
+                owned = true;
+                fs.ftruncateSync(fd, 0);
+                fs.writeFileSync(fd, value);
+                fs.fchmodSync(fd, mode);
+                fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            fs.renameSync(temporary, file);
+        }
+        catch (error) {
+            if (owned)
+                fs.unlinkSync(temporary);
+            throw error;
+        }
+        const directory = fs.openSync(path.dirname(file), fs.constants.O_RDONLY);
+        try {
+            fs.fsyncSync(directory);
+        }
+        finally {
+            fs.closeSync(directory);
+        }
+    }
+    #docker(args, input) {
+        return (0, node_child_process_1.execFileSync)("/usr/bin/docker", args, { encoding: "utf8", input, maxBuffer: 1024 * 1024, timeout: 120_000, stdio: ["pipe", "pipe", "pipe"] });
+    }
+    #containers() {
+        const names = this.#docker(["ps", "-a", "--format", "{{json .}}"]).trim().split("\n").filter(Boolean).map((line) => String(JSON.parse(line).Names));
+        return names.filter((name) => ["ouro-butler", "ouro-butler-rollback"].includes(name)).flatMap((name) => JSON.parse(this.#docker(["inspect", name])));
+    }
+    #assertNoForeignPoller() {
+        const names = this.#docker(["ps", "--format", "{{json .}}"]).trim().split("\n").filter(Boolean).map((line) => String(JSON.parse(line).Names));
+        for (const name of names) {
+            if (["ouro-butler", "ouro-butler-rollback"].includes(name))
+                continue;
+            const containers = JSON.parse(this.#docker(["inspect", name]));
+            if (containers.some((container) => container.Mounts.some((mount) => mount.Source === BUNDLE || mount.Source === RUNTIME)))
+                throw new Error("Sanctuary has an unowned possible direct poller");
+        }
+    }
+    #vault(operation, input) {
+        // The fenced container runs root with every capability dropped, but the
+        // resident credential store is owned by the resident uid (10001), so a bare
+        // cap-dropped root cannot even read it (EACCES on agent.json → surfaces as
+        // "vault owner unavailable"). CAP_DAC_OVERRIDE is restored — the single
+        // capability needed to reach the resident's files, nothing broader.
+        //
+        // bitwarden cannot unlock (or sync) a store it cannot write to, so the store
+        // dir must be writable inside the fence. The two verbs split by intent:
+        //   • snapshot / presence are READS: the read-only store is copied into a
+        //     throwaway tmpfs, so the fence never mutates resident state.
+        //   • remove / restore are WRITES whose whole purpose is to change the vault
+        //     (remove-resident-token, rollback restore-token-cursor). They bind the
+        //     real ${RUNTIME}/bitwarden writable (rw over the read-only .ouro-cli),
+        //     so the edit — and bitwarden's own sync-on-unlock — persists. Copying to
+        //     tmpfs here would silently discard the write and fail the step's readback.
+        // `operation` is one of the four fixed literals validated by the CLI.
+        const cli = "/opt/ouro/dist/heart/daemon/sanctuary-authority-root-lifecycle.js";
+        const persists = operation === "remove" || operation === "restore";
+        const bitwarden = persists
+            ? ["--mount", `type=bind,src=${RUNTIME}/bitwarden,dst=/home/ouro/.ouro-cli/bitwarden`]
+            : [
+                "--mount", `type=bind,src=${RUNTIME}/bitwarden,dst=/home/ouro/.bw-src,readonly`,
+                "--tmpfs", "/home/ouro/.ouro-cli/bitwarden:rw,nosuid,nodev,noexec,mode=0700",
+            ];
+        const prepare = persists ? "" : "cp -r /home/ouro/.bw-src/. /home/ouro/.ouro-cli/bitwarden/ && ";
+        return JSON.parse(this.#docker([
+            "run", "--rm", "-i", "--pull=never", "--network", "host", "--user", "0:0", "--read-only",
+            "--cap-drop=ALL", "--cap-add=DAC_OVERRIDE", "--security-opt=no-new-privileges", "--entrypoint", "/bin/sh",
+            "--mount", `type=bind,src=${RUNTIME},dst=/home/ouro/.ouro-cli,readonly`,
+            ...bitwarden,
+            "--mount", `type=bind,src=${BUNDLE},dst=/home/ouro/AgentBundles/sanctuary.ouro,readonly`,
+            "--tmpfs", "/home/ouro/.config:rw,nosuid,nodev,noexec,mode=0700",
+            "--tmpfs", "/tmp:rw,nosuid,nodev,noexec,mode=0700",
+            "--env", `OURO_AUTHORITY_REMOVE_INTERLOCK=${this.#request.epochId}`,
+            this.#transaction.targetImageId, "-c",
+            `${prepare}exec /usr/local/bin/node ${cli} vault ${operation}`,
+        ], input === undefined ? undefined : JSON.stringify(input)));
+    }
+}
+exports.SanctuaryAuthorityRootLifecycle = SanctuaryAuthorityRootLifecycle;
+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");
+    if (argv.length === 2 && argv[0] === "vault") {
+        // `remove` is the one vault verb that can strand the household. It is safe
+        // only inside the install transaction, which has already proven the same
+        // token into root custody at `verify-token-rotation`. Run bare against a
+        // host with no installed root authority it leaves the Butler with no route
+        // to Telegram at all, which is how Sanctuary lost its front door on
+        // 2026-09-21. This is a safety interlock against invoking it outside its
+        // transaction, not a privilege boundary: root can always set the variable,
+        // but it can no longer do this by reaching for a documented verb.
+        if (argv[1] === "remove" && !process.env.OURO_AUTHORITY_REMOVE_INTERLOCK) {
+            throw new Error("Sanctuary vault removal runs only inside the authority install transaction; use docker-man-template-transaction.mjs authority-install");
+        }
+        const input = argv[1] === "restore" ? JSON.parse(fs.readFileSync(0, "utf8")) : undefined;
+        write(`${JSON.stringify(await (0, sanctuary_authority_vault_migration_1.migrateSanctuaryAuthorityVault)(argv[1], input))}\n`);
+        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 activationPath = `${ROOT}/activation.json`;
+        if (!fs.existsSync(activationPath)) {
+            if (repin)
+                throw new Error("Sanctuary authority is not active");
+            return;
+        }
+        const activation = JSON.parse(fs.readFileSync(activationPath, "utf8"));
+        const lifecycle = new SanctuaryAuthorityRootLifecycle(activation);
+        if (repin) {
+            lifecycle.repinExecution(argv[1], argv[2]);
+            write('{"repinned":true,"gatewayRestartRequired":true}\n');
+        }
+        else
+            await lifecycle.boot();
+    }, { timeoutMs: 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");
+        process.exitCode = 1;
+    });
+}