@ouro.bot/cli 0.1.0-alpha.99 → 0.1.0-alpha.991

package/dist/heart/daemon/sanctuary-bundle-migration.js

@@ -0,0 +1,974 @@
+"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.SANCTUARY_GIT_EXCLUDES = exports.SANCTUARY_BUNDLE_ROLLBACK_FILE = exports.SANCTUARY_STARTER_PSYCHE_FILES = exports.SANCTUARY_PACKAGE_MANAGED_FILES = void 0;
+exports.sanctuaryGitExcludeText = sanctuaryGitExcludeText;
+exports.bundleSyncEnabled = bundleSyncEnabled;
+exports.writeSanctuaryGitExclude = writeSanctuaryGitExclude;
+exports.inspectSanctuaryDirectoryFromBase = inspectSanctuaryDirectoryFromBase;
+exports.sanctuaryDirectoriesShareIdentity = sanctuaryDirectoriesShareIdentity;
+exports.inspectSanctuaryPackageManagedBundle = inspectSanctuaryPackageManagedBundle;
+exports.ensureSanctuaryPackageManagedBundle = ensureSanctuaryPackageManagedBundle;
+exports.seedSanctuaryPsycheIfAbsent = seedSanctuaryPsycheIfAbsent;
+exports.inspectSanctuaryPackageManagedBundleRollback = inspectSanctuaryPackageManagedBundleRollback;
+exports.rollbackSanctuaryPackageManagedBundle = rollbackSanctuaryPackageManagedBundle;
+exports.commitSanctuaryPackageManagedBundle = commitSanctuaryPackageManagedBundle;
+exports.migrateSanctuaryPackageManagedBundle = migrateSanctuaryPackageManagedBundle;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../../nerves/runtime");
+const house_names_1 = require("../../mind/house-names");
+exports.SANCTUARY_PACKAGE_MANAGED_FILES = [
+    "provider-readiness.json",
+    "tool-profiles.json",
+    "mcp/media-mcp.mjs",
+    "habits/sanctuary-health.md",
+    "awaiting/house-care-sweep.md",
+    "product/PRODUCT.md",
+];
+// The psyche belongs to the install: it is seeded from these files only when `psyche/` is absent, and no release touches it again.
+exports.SANCTUARY_STARTER_PSYCHE_FILES = ["psyche/ASPIRATIONS.md", "psyche/IDENTITY.md", "psyche/LORE.md", "psyche/SOUL.md", "psyche/TACIT.md"];
+const PSYCHE_SEED_STAGE_PREFIX = ".psyche-seed.";
+// mkdtemp appends six characters from [A-Za-z0-9]; any other name under the prefix belongs to the owner.
+const PSYCHE_SEED_STAGE_NAME = /^\.psyche-seed\.[A-Za-z0-9]{6}$/u;
+const STARTER_PSYCHE_NAMES = new Set(exports.SANCTUARY_STARTER_PSYCHE_FILES.map((relative) => path.basename(relative)));
+exports.SANCTUARY_BUNDLE_ROLLBACK_FILE = ".sanctuary-package-managed-rollback.json";
+const SANCTUARY_BUNDLE_COMMITTING_FILE = `${exports.SANCTUARY_BUNDLE_ROLLBACK_FILE}.committing`;
+/**
+ * What sync never commits from the Butler's bundle. The first block is the hourly host backup's own list, copied from
+ * bundle-backup/repo.git/info/exclude on 2026-11-06. Then any MCP credential file, the files each release installs, and
+ * the release's own bookkeeping, then the transient temp and lock files written inside the bundle. The cutover writes this list with `ouro sanctuary git-exclude --print`, and every boot
+ * writes it again.
+ */
+exports.SANCTUARY_GIT_EXCLUDES = [
+    "**/credentials.json",
+    "mcp/media-credentials.json",
+    "books/hey/.config/",
+    "**/*.key",
+    "**/*.pem",
+    "**/deploy_key*",
+    "**/id_rsa*",
+    "**/id_ed25519*",
+    "**/id_ecdsa*",
+    "**/.env",
+    "state/",
+    "inbox/",
+    "arc/flight-recorder/",
+    "arc/obligations/",
+    "arc/packets/",
+    "books/bin/",
+    "books/vendor/",
+    "books/work/",
+    "books/fonts/",
+    "mcp/*.pre-*",
+    "books/hey/",
+    "**/__pycache__/",
+    "mcp/*credentials*",
+    ...exports.SANCTUARY_PACKAGE_MANAGED_FILES,
+    "bundle-meta.json",
+    `${exports.SANCTUARY_BUNDLE_ROLLBACK_FILE}*`,
+    `${PSYCHE_SEED_STAGE_PREFIX}*`,
+    // The upgrade's release marker and its staged copy, planted in psyche/ for the length of a gated ship.
+    "psyche/.release-marker*",
+    // Transient files the runtime and the replay gate write inside the bundle: atomic-write temps and lock files.
+    "*.tmp",
+    "*.tmp-*",
+    "*.tmp.*",
+    "*.lock",
+    "*.lock.reclaim",
+    "*.turn.lock-*",
+    ".locks/",
+];
+/** The exclude file's content: one entry per line. */
+function sanctuaryGitExcludeText() {
+    return `${exports.SANCTUARY_GIT_EXCLUDES.join("\n")}\n`;
+}
+/** Whether the bundle's agent.json turns sync on. An unreadable agent.json reads as off. */
+function bundleSyncEnabled(agentRoot) {
+    try {
+        const sync = readObject(path.join(agentRoot, "agent.json")).sync;
+        return sync?.enabled === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write the bundle's `.git/info/exclude`. A bundle with sync on and no repository yet (a fresh install) gets
+ * `git init -b main` first; sync makes the first commit on the first turn. A bundle with sync off and no
+ * repository is left alone. A tracked .gitignore is the owner's and is never touched.
+ */
+function writeSanctuaryGitExclude(agentRoot) {
+    const gitDir = path.join(agentRoot, ".git");
+    let initialized = false;
+    if (!fs.existsSync(gitDir)) {
+        if (!bundleSyncEnabled(agentRoot))
+            return { initialized: false, written: false };
+        const run = (0, node_child_process_1.spawnSync)("git", ["init", "-q", "-b", "main"], { cwd: agentRoot, env: { ...process.env, LC_ALL: "C", LANG: "C" }, encoding: "utf8" });
+        if (run.status !== 0)
+            throw new Error(`git init failed: ${run.error ? run.error.message : run.stderr.trim()}`);
+        initialized = true;
+    }
+    const excludePath = path.join(gitDir, "info", "exclude");
+    const text = sanctuaryGitExcludeText();
+    let current = null;
+    try {
+        current = fs.readFileSync(excludePath, "utf8");
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    if (current === text)
+        return { initialized, written: false };
+    fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+    writeAtomic(excludePath, text, 0o644);
+    (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_git_exclude_written", message: "wrote the Sanctuary bundle's git exclude", meta: { initialized, entries: exports.SANCTUARY_GIT_EXCLUDES.length } });
+    return { initialized, written: true };
+}
+const BUNDLE_META_VERSION_FIELDS = ["runtimeVersion", "bundleSchemaVersion", "lastUpdated"];
+class SanctuaryInspectionFault extends Error {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.code = code;
+    }
+}
+const CANONICAL_EMPTY_PACKAGED_POLICY = { schemaVersion: 1, version: 0, desiredStates: {}, routineActionGrants: {}, updatedAt: null };
+function readObject(filePath) {
+    const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${path.basename(filePath)} must contain an object`);
+    return value;
+}
+function isMissing(error) {
+    return !!error && typeof error === "object" && "code" in error && error.code === "ENOENT";
+}
+function isFilesystemFailure(error) {
+    return !!error && typeof error === "object" && "code" in error && typeof error.code === "string";
+}
+function inspectSanctuaryDirectoryFromBase(baseRoot, segments) {
+    if (!path.isAbsolute(baseRoot))
+        return null;
+    let current = path.resolve(baseRoot);
+    let stat = null;
+    for (const candidate of [current, ...segments.map((segment) => { current = path.join(current, segment); return current; })]) {
+        try {
+            stat = fs.lstatSync(candidate);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return null;
+            throw error;
+        }
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            return null;
+    }
+    const realPath = fs.realpathSync(current);
+    if (realPath !== path.resolve(current))
+        return null;
+    return { realPath, device: stat.dev, inode: stat.ino };
+}
+function sanctuaryDirectoriesShareIdentity(left, right) {
+    return left.realPath === right.realPath || (left.device === right.device && left.inode === right.inode);
+}
+function inspectStandaloneSanctuaryDirectory(root) {
+    if (!path.isAbsolute(root))
+        return null;
+    const resolved = path.resolve(root);
+    return inspectSanctuaryDirectoryFromBase(path.dirname(resolved), [path.basename(resolved)]);
+}
+function isCanonicalEmptyPackagedPolicy(value) {
+    return JSON.stringify(Object.keys(value).sort()) === JSON.stringify(Object.keys(CANONICAL_EMPTY_PACKAGED_POLICY).sort())
+        && value.schemaVersion === 1
+        && value.version === 0
+        && value.updatedAt === null
+        && !!value.desiredStates
+        && typeof value.desiredStates === "object"
+        && !Array.isArray(value.desiredStates)
+        && Object.keys(value.desiredStates).length === 0
+        && !!value.routineActionGrants
+        && typeof value.routineActionGrants === "object"
+        && !Array.isArray(value.routineActionGrants)
+        && Object.keys(value.routineActionGrants).length === 0;
+}
+function validatePackagedPolicy(packageRoot) {
+    const relative = "state/policy/steward.json";
+    validateDestination(packageRoot, relative);
+    requirePlainFile(path.join(packageRoot, relative), "packaged steward policy");
+    const value = readObject(path.join(packageRoot, relative));
+    if (value.routineActionGrants && typeof value.routineActionGrants === "object" && !Array.isArray(value.routineActionGrants) && Object.keys(value.routineActionGrants).length > 0)
+        throw new Error("packaged steward policy must not carry routine action grants; authorize them through an authenticated owner session");
+    if (value.desiredStates && typeof value.desiredStates === "object" && !Array.isArray(value.desiredStates) && Object.keys(value.desiredStates).length > 0)
+        throw new Error("packaged steward policy must not carry desired state");
+    if (!isCanonicalEmptyPackagedPolicy(value))
+        throw new Error("packaged steward policy must be the canonical empty policy");
+}
+function requirePlainFile(filePath, label) {
+    let stat;
+    try {
+        stat = fs.lstatSync(filePath);
+    }
+    catch {
+        throw new Error(`${label} is missing`);
+    }
+    if (stat.isSymbolicLink())
+        throw new Error(`${label} must not be a symlink`);
+    if (!stat.isFile())
+        throw new Error(`${label} must be a regular file`);
+}
+function ensureSafeParent(agentRoot, relative) {
+    let current = agentRoot;
+    for (const segment of path.dirname(relative).split(path.sep).filter((value) => value !== ".")) {
+        current = path.join(current, segment);
+        if (!fs.existsSync(current))
+            fs.mkdirSync(current, { mode: 0o700 });
+    }
+}
+function validateDestination(agentRoot, relative) {
+    let current = agentRoot;
+    for (const segment of relative.split(path.sep)) {
+        current = path.join(current, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(current);
+        }
+        catch {
+            return;
+        }
+        if (stat.isSymbolicLink())
+            throw new Error(`package-managed destination must not be a symlink: ${relative}`);
+        if (current !== path.join(agentRoot, relative) && !stat.isDirectory())
+            throw new Error(`package-managed destination parent must be a directory: ${relative}`);
+        if (current === path.join(agentRoot, relative) && !stat.isFile())
+            throw new Error(`package-managed destination must be a regular file: ${relative}`);
+    }
+}
+function syncDirectory(directoryPath) {
+    const directory = fs.openSync(directoryPath, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        fs.fsyncSync(directory);
+    }
+    finally {
+        fs.closeSync(directory);
+    }
+}
+function syncNearestExistingDirectory(directoryPath, agentRoot) {
+    let current = directoryPath;
+    while (current !== agentRoot && !fs.existsSync(current))
+        current = path.dirname(current);
+    syncDirectory(current);
+}
+function writeAtomic(filePath, content, mode = 0o600) {
+    const stagingDirectory = fs.mkdtempSync(`${filePath}.package-migration.`);
+    const temporary = path.join(stagingDirectory, "value");
+    try {
+        const fd = fs.openSync(temporary, "wx", 0o600);
+        try {
+            fs.writeFileSync(fd, content);
+            fs.fchmodSync(fd, mode);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temporary, filePath);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+        fs.rmdirSync(stagingDirectory);
+    }
+    syncDirectory(path.dirname(filePath));
+}
+const SNAPSHOT_RELATIVES = [...exports.SANCTUARY_PACKAGE_MANAGED_FILES, "bundle-meta.json"];
+function packageManagedArtifactPaths(agentRoot) {
+    return SNAPSHOT_RELATIVES.map((relative) => path.join(agentRoot, relative));
+}
+function inspectInterruptedWrites(filePaths, restoredModes) {
+    const stages = [];
+    for (const filePath of [...filePaths].sort()) {
+        const parent = path.dirname(filePath);
+        const prefix = `${path.basename(filePath)}.package-migration.`;
+        let names;
+        try {
+            names = fs.readdirSync(parent).sort();
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            throw error;
+        }
+        for (const name of names) {
+            if (!name.startsWith(prefix))
+                continue;
+            const stagingDirectory = path.join(parent, name);
+            const parentStat = fs.lstatSync(parent);
+            const stagingStat = fs.lstatSync(stagingDirectory);
+            if (parentStat.isSymbolicLink() || !parentStat.isDirectory() || stagingStat.isSymbolicLink() || !stagingStat.isDirectory() || (stagingStat.mode & 0o777) !== 0o700 || stagingStat.uid !== parentStat.uid || stagingStat.gid !== parentStat.gid)
+                throw new Error(`interrupted package migration stage is invalid: ${name}`);
+            const entries = fs.readdirSync(stagingDirectory);
+            if (entries.some((entry) => entry !== "value"))
+                throw new Error(`interrupted package migration stage contains unexpected entries: ${name}`);
+            const temporary = entries.includes("value") ? path.join(stagingDirectory, "value") : null;
+            if (temporary) {
+                const temporaryStat = fs.lstatSync(temporary);
+                const temporaryMode = temporaryStat.mode & 0o777;
+                if (temporaryStat.isSymbolicLink() || !temporaryStat.isFile() || (temporaryMode !== 0o600 && temporaryMode !== restoredModes?.get(filePath)) || temporaryStat.uid !== stagingStat.uid || temporaryStat.gid !== stagingStat.gid)
+                    throw new Error(`interrupted package migration value is invalid: ${name}`);
+            }
+            stages.push({ stagingDirectory, temporary });
+        }
+    }
+    return stages;
+}
+function cleanupInterruptedWrites(filePaths, restoredModes) {
+    const stages = inspectInterruptedWrites(filePaths, restoredModes);
+    for (const stage of stages) {
+        if (stage.temporary)
+            fs.unlinkSync(stage.temporary);
+        fs.rmdirSync(stage.stagingDirectory);
+    }
+    for (const parent of [...new Set(stages.map((stage) => path.dirname(stage.stagingDirectory)))].sort()) {
+        syncDirectory(parent);
+    }
+}
+function snapshotDirectoryRelatives() {
+    const directories = new Set();
+    for (const relative of SNAPSHOT_RELATIVES) {
+        let directory = path.dirname(relative);
+        while (directory !== ".") {
+            directories.add(directory);
+            directory = path.dirname(directory);
+        }
+    }
+    return [...directories].sort((left, right) => left.length - right.length);
+}
+function captureMigrationSnapshot(agentRoot) {
+    const files = SNAPSHOT_RELATIVES.map((relative) => {
+        const filePath = path.join(agentRoot, relative);
+        if (!fs.existsSync(filePath))
+            return { path: filePath, content: null, mode: null };
+        const stat = fs.lstatSync(filePath);
+        return { path: filePath, content: fs.readFileSync(filePath), mode: stat.mode & 0o777 };
+    });
+    const directories = snapshotDirectoryRelatives().map((relative) => {
+        const directory = path.join(agentRoot, relative);
+        if (!fs.existsSync(directory))
+            return { path: directory, mode: null };
+        const stat = fs.lstatSync(directory);
+        return { path: directory, mode: stat.mode & 0o777 };
+    });
+    return { files, directories };
+}
+function rollbackPath(agentRoot) {
+    return path.join(agentRoot, exports.SANCTUARY_BUNDLE_ROLLBACK_FILE);
+}
+function durableSnapshot(agentRoot, snapshot, rollbackImageId, targetImageId) {
+    const payload = {
+        schemaVersion: 1,
+        rollbackImageId,
+        targetImageId,
+        files: snapshot.files.map((file) => ({ relative: path.relative(agentRoot, file.path), contentBase64: file.content?.toString("base64") ?? null, mode: file.mode })),
+        directories: snapshot.directories.map((directory) => ({ relative: path.relative(agentRoot, directory.path), mode: directory.mode })),
+    };
+    return { ...payload, snapshotDigest: (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(payload)).digest("hex") };
+}
+function readDurableRecord(agentRoot) {
+    const names = fs.readdirSync(agentRoot);
+    const stagePrefixes = [`${exports.SANCTUARY_BUNDLE_ROLLBACK_FILE}.package-migration.`, `${SANCTUARY_BUNDLE_COMMITTING_FILE}.package-migration.`];
+    if (names.some((name) => stagePrefixes.some((prefix) => name.startsWith(prefix))))
+        throw new Error("Sanctuary bundle journal staging residue requires verified recovery");
+    const candidates = [rollbackPath(agentRoot), path.join(agentRoot, SANCTUARY_BUNDLE_COMMITTING_FILE)].flatMap((filePath) => {
+        try {
+            return [{ filePath, stat: fs.lstatSync(filePath) }];
+        }
+        catch (error) {
+            if (isMissing(error))
+                return [];
+            throw error;
+        }
+    });
+    if (candidates.length === 0)
+        return null;
+    if (candidates.length !== 1)
+        throw new Error("Sanctuary bundle rollback record state is ambiguous");
+    const [{ filePath, stat }] = candidates;
+    if (stat.isSymbolicLink())
+        throw new Error("Sanctuary bundle rollback record must not be a symlink");
+    if (!stat.isFile() || (stat.mode & 0o777) !== 0o600)
+        throw new Error("Sanctuary bundle rollback record must be a mode-0600 regular file");
+    const serialized = fs.readFileSync(filePath, "utf8");
+    let value;
+    try {
+        value = JSON.parse(serialized);
+    }
+    catch {
+        throw new Error("Sanctuary bundle rollback record is invalid JSON");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Sanctuary bundle rollback record is invalid");
+    const record = value;
+    if (record.schemaVersion !== 1 || typeof record.rollbackImageId !== "string" || !/^sha256:[0-9a-f]{64}$/u.test(record.rollbackImageId) || typeof record.targetImageId !== "string" || !/^sha256:[0-9a-f]{64}$/u.test(record.targetImageId) || record.targetImageId === record.rollbackImageId || typeof record.snapshotDigest !== "string" || !/^[0-9a-f]{64}$/u.test(record.snapshotDigest) || !Array.isArray(record.files) || !Array.isArray(record.directories))
+        throw new Error("Sanctuary bundle rollback record is invalid");
+    const fileRelatives = record.files.map((file) => file?.relative);
+    const directoryRelatives = record.directories.map((directory) => directory?.relative);
+    const expectedDirectories = snapshotDirectoryRelatives();
+    if (JSON.stringify(fileRelatives) !== JSON.stringify(SNAPSHOT_RELATIVES) || JSON.stringify(directoryRelatives) !== JSON.stringify(expectedDirectories))
+        throw new Error("Sanctuary bundle rollback record paths are invalid");
+    for (const relative of SNAPSHOT_RELATIVES)
+        validateDestination(agentRoot, relative);
+    const validMode = (mode) => mode === null || (Number.isInteger(mode) && mode >= 0 && mode <= 0o777);
+    const files = record.files.map((file) => {
+        if (!file || typeof file.relative !== "string" || !validMode(file.mode) || (file.contentBase64 !== null && typeof file.contentBase64 !== "string") || (file.contentBase64 === null) !== (file.mode === null))
+            throw new Error("Sanctuary bundle rollback record file is invalid");
+        const content = file.contentBase64 === null ? null : Buffer.from(file.contentBase64, "base64");
+        if (file.contentBase64 !== null && (!content || content.toString("base64") !== file.contentBase64))
+            throw new Error("Sanctuary bundle rollback record content is invalid");
+        return { path: path.join(agentRoot, file.relative), content, mode: file.mode };
+    });
+    const directories = record.directories.map((directory) => {
+        if (!directory || typeof directory.relative !== "string" || !validMode(directory.mode))
+            throw new Error("Sanctuary bundle rollback record directory is invalid");
+        return { path: path.join(agentRoot, directory.relative), mode: directory.mode };
+    });
+    const payload = { schemaVersion: record.schemaVersion, rollbackImageId: record.rollbackImageId, targetImageId: record.targetImageId, files: record.files, directories: record.directories };
+    if ((0, node_crypto_1.createHash)("sha256").update(JSON.stringify(payload)).digest("hex") !== record.snapshotDigest)
+        throw new Error("Sanctuary bundle rollback record digest is invalid");
+    return { snapshot: { files, directories }, rollbackImageId: record.rollbackImageId, targetImageId: record.targetImageId, filePath, state: filePath === rollbackPath(agentRoot) ? "rollback" : "committing" };
+}
+function removeRollbackRecord(agentRoot, filePath) {
+    fs.unlinkSync(filePath);
+    syncDirectory(agentRoot);
+}
+function validateAgentRoot(agentRoot) {
+    if (!path.isAbsolute(agentRoot))
+        throw new Error("agent root must be an absolute path");
+    if (!inspectStandaloneSanctuaryDirectory(agentRoot))
+        throw new Error("agent root must be a canonical real directory");
+}
+function inspectionError(code) {
+    if (code === "invalid_package_root" || code === "invalid_package_source" || code === "packaged_policy_not_empty" || code === "package_version_mismatch") {
+        return { ok: false, error: { code, message: "verified release contents are invalid", degraded: true, repair: { actor: "human-required", action: "roll_back_or_install_verified_release" } } };
+    }
+    if (code === "invalid_live_root" || code === "invalid_live_bundle") {
+        return { ok: false, error: { code, message: "installed Sanctuary bundle is invalid", degraded: true, repair: { actor: "human-required", action: "roll_back_or_install_verified_release" } } };
+    }
+    if (code === "invalid_journal") {
+        return { ok: false, error: { code, message: "Sanctuary update recovery is required", degraded: true, repair: { actor: "human-required", action: "run_verified_update_recovery" } } };
+    }
+    return { ok: false, error: { code, message: "Sanctuary install state is unavailable", degraded: true, repair: { actor: "human-required", action: "run_verified_update_recovery" } } };
+}
+function validateInspectionRoot(root, code) {
+    const identity = inspectStandaloneSanctuaryDirectory(root);
+    if (!identity)
+        throw new SanctuaryInspectionFault(code);
+    return identity;
+}
+function inspectRelativeFile(root, relative, code) {
+    let current = root;
+    let result = null;
+    const segments = relative.split(path.sep);
+    for (let index = 0; index < segments.length; index += 1) {
+        current = path.join(current, segments[index]);
+        let stat;
+        try {
+            stat = fs.lstatSync(current);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return null;
+            throw error;
+        }
+        if (stat.isSymbolicLink())
+            throw new SanctuaryInspectionFault(code);
+        if (index < segments.length - 1 && !stat.isDirectory())
+            throw new SanctuaryInspectionFault(code);
+        if (index === segments.length - 1 && !stat.isFile())
+            throw new SanctuaryInspectionFault(code);
+        if (index === segments.length - 1)
+            result = stat;
+    }
+    return result;
+}
+function readInspectionObject(filePath, code) {
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new SanctuaryInspectionFault(code);
+        throw error;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new SanctuaryInspectionFault(code);
+    return value;
+}
+function inspectPackageSources(packageRoot, runtimePackageVersion) {
+    const managed = new Map();
+    for (const relative of exports.SANCTUARY_PACKAGE_MANAGED_FILES) {
+        if (!inspectRelativeFile(packageRoot, relative, "invalid_package_source"))
+            throw new SanctuaryInspectionFault("invalid_package_source");
+        managed.set(relative, fs.readFileSync(path.join(packageRoot, relative)));
+    }
+    if (!inspectRelativeFile(packageRoot, "bundle-meta.json", "invalid_package_source"))
+        throw new SanctuaryInspectionFault("invalid_package_source");
+    const metadata = readInspectionObject(path.join(packageRoot, "bundle-meta.json"), "invalid_package_source");
+    if (typeof metadata.runtimeVersion !== "string" || metadata.runtimeVersion.length === 0 || !Number.isInteger(metadata.bundleSchemaVersion) || typeof metadata.lastUpdated !== "string" || metadata.lastUpdated.length === 0)
+        throw new SanctuaryInspectionFault("invalid_package_source");
+    if (!inspectRelativeFile(packageRoot, "state/policy/steward.json", "invalid_package_source"))
+        throw new SanctuaryInspectionFault("invalid_package_source");
+    const policy = readInspectionObject(path.join(packageRoot, "state/policy/steward.json"), "invalid_package_source");
+    if (!isCanonicalEmptyPackagedPolicy(policy))
+        throw new SanctuaryInspectionFault("packaged_policy_not_empty");
+    if (runtimePackageVersion.length === 0 || metadata.runtimeVersion !== runtimePackageVersion)
+        throw new SanctuaryInspectionFault("package_version_mismatch");
+    return { managed, metadata, packagedBundleVersion: metadata.runtimeVersion };
+}
+function journalRepair(journalState, parity) {
+    if (parity === "exact" && journalState !== "committing")
+        return { actor: "none", action: "none" };
+    if (parity === "mismatch" && journalState === "absent")
+        return { actor: "human-required", action: "restart_from_verified_release" };
+    return { actor: "human-required", action: "run_verified_update_recovery" };
+}
+function inspectSanctuaryPackageManagedBundle(input) {
+    try {
+        const packageIdentity = validateInspectionRoot(input.packageRoot, "invalid_package_root");
+        const packaged = inspectPackageSources(input.packageRoot, input.runtimePackageVersion);
+        const agentIdentity = validateInspectionRoot(input.agentRoot, "invalid_live_root");
+        if (sanctuaryDirectoriesShareIdentity(packageIdentity, agentIdentity))
+            throw new SanctuaryInspectionFault("invalid_live_root");
+        let managedMissing = false;
+        let managedContent = false;
+        let managedMode = false;
+        for (const relative of exports.SANCTUARY_PACKAGE_MANAGED_FILES) {
+            const stat = inspectRelativeFile(input.agentRoot, relative, "invalid_live_bundle");
+            if (!stat) {
+                managedMissing = true;
+                continue;
+            }
+            if (!fs.readFileSync(path.join(input.agentRoot, relative)).equals(packaged.managed.get(relative)))
+                managedContent = true;
+            if ((stat.mode & 0o777) !== 0o600)
+                managedMode = true;
+        }
+        let liveBundleVersion = null;
+        let bundleMetaMissing = false;
+        let bundleMetaField = false;
+        let bundleMetaMode = false;
+        const liveMetaStat = inspectRelativeFile(input.agentRoot, "bundle-meta.json", "invalid_live_bundle");
+        if (!liveMetaStat) {
+            bundleMetaMissing = true;
+        }
+        else {
+            const liveMeta = readInspectionObject(path.join(input.agentRoot, "bundle-meta.json"), "invalid_live_bundle");
+            liveBundleVersion = typeof liveMeta.runtimeVersion === "string" ? liveMeta.runtimeVersion : null;
+            bundleMetaField = BUNDLE_META_VERSION_FIELDS.some((field) => liveMeta[field] !== packaged.metadata[field]);
+            bundleMetaMode = (liveMetaStat.mode & 0o777) !== 0o600;
+        }
+        let journalState = "absent";
+        try {
+            if (inspectInterruptedWrites(packageManagedArtifactPaths(input.agentRoot)).length > 0)
+                throw new Error("Sanctuary bundle staging residue requires verified recovery");
+            journalState = readDurableRecord(input.agentRoot)?.state ?? "absent";
+        }
+        catch (error) {
+            if (isFilesystemFailure(error))
+                throw error;
+            throw new SanctuaryInspectionFault("invalid_journal");
+        }
+        const mismatchCodes = [];
+        if (managedMissing)
+            mismatchCodes.push("managed_file_missing");
+        if (managedContent)
+            mismatchCodes.push("managed_file_content");
+        if (managedMode)
+            mismatchCodes.push("managed_file_mode");
+        if (bundleMetaMissing)
+            mismatchCodes.push("bundle_meta_missing");
+        if (bundleMetaField)
+            mismatchCodes.push("bundle_meta_field");
+        if (bundleMetaMode)
+            mismatchCodes.push("bundle_meta_mode");
+        const parity = mismatchCodes.length === 0 ? "exact" : "mismatch";
+        const ready = parity === "exact" && journalState !== "committing";
+        return {
+            ok: true,
+            data: {
+                runtimePackageVersion: input.runtimePackageVersion,
+                packagedBundleVersion: packaged.packagedBundleVersion,
+                liveBundleVersion,
+                parity,
+                mismatchCodes,
+                journalState,
+                ready,
+                repair: journalRepair(journalState, parity),
+            },
+        };
+    }
+    catch (error) {
+        return inspectionError(error instanceof SanctuaryInspectionFault ? error.code : "inspection_unavailable");
+    }
+}
+function ensureSanctuaryPackageManagedBundle(input, deps = {}) {
+    const seedFailure = seedLivePsyche(input, deps.seed ?? seedSanctuaryPsycheIfAbsent);
+    if (seedFailure)
+        return seedFailure;
+    const inspect = deps.inspect ?? inspectSanctuaryPackageManagedBundle;
+    const before = inspect(input);
+    if (!before.ok) {
+        if (before.error.code !== "invalid_journal")
+            return before;
+        try {
+            (deps.migrate ?? migrateSanctuaryPackageManagedBundle)({ packageRoot: input.packageRoot, agentRoot: input.agentRoot });
+        }
+        catch {
+            return before;
+        }
+    }
+    else if (before.data.ready) {
+        return before;
+    }
+    else if (before.data.parity === "mismatch" && before.data.journalState !== "absent") {
+        return before;
+    }
+    else if (before.data.parity === "exact" && before.data.journalState === "committing") {
+        (deps.commit ?? commitSanctuaryPackageManagedBundle)(input.agentRoot);
+    }
+    else {
+        (deps.migrate ?? migrateSanctuaryPackageManagedBundle)({ packageRoot: input.packageRoot, agentRoot: input.agentRoot });
+    }
+    const after = inspect(input);
+    if (!after.ok || !after.data.ready)
+        return after;
+    if (after.data.parity !== "exact" || after.data.journalState !== "absent")
+        throw new Error("Sanctuary package-managed bundle did not converge");
+    return after;
+}
+// A live root that is not a canonical directory is left for inspection to report as invalid_live_root.
+function seedLivePsyche(input, seed) {
+    try {
+        if (!inspectStandaloneSanctuaryDirectory(input.agentRoot))
+            return null;
+        const seeded = seed({ packageRoot: input.packageRoot, agentRoot: input.agentRoot });
+        return seeded.ok ? null : inspectionError(seeded.code);
+    }
+    catch (error) {
+        return inspectionError(error instanceof SanctuaryInspectionFault ? error.code : "inspection_unavailable");
+    }
+}
+function psycheState(agentRoot) {
+    let stat;
+    try {
+        stat = fs.lstatSync(path.join(agentRoot, "psyche"));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return "absent";
+        throw error;
+    }
+    return stat.isDirectory() ? "directory" : "invalid";
+}
+function sameInode(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+// Returns the entries of a stage this seeder could have left, or null when anything about it says otherwise.
+function interruptedPsycheSeedEntries(stage, root) {
+    const before = fs.lstatSync(stage);
+    const mode = before.mode & 0o777;
+    if (!before.isDirectory() || (mode !== 0o700 && mode !== 0o755) || before.uid !== root.uid || before.gid !== root.gid)
+        return null;
+    const handle = fs.openSync(stage, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    let entries = [];
+    try {
+        if (!sameInode(before, fs.fstatSync(handle)))
+            return null;
+        entries = fs.readdirSync(stage);
+        if (!sameInode(before, fs.lstatSync(stage)))
+            return null;
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+    for (const entry of entries) {
+        if (!STARTER_PSYCHE_NAMES.has(entry))
+            return null;
+        const stat = fs.lstatSync(path.join(stage, entry));
+        if (!stat.isFile() || (stat.mode & 0o777) !== 0o600 || stat.uid !== root.uid)
+            return null;
+    }
+    return entries;
+}
+// A seed interrupted before its rename leaves a mkdtemp-named stage holding only starter files that never became the psyche.
+// Anything that does not match that exact shape may be the owner's, so it is left alone.
+function cleanupInterruptedPsycheSeeds(agentRoot) {
+    const root = fs.lstatSync(agentRoot);
+    let removed = false;
+    for (const name of fs.readdirSync(agentRoot).filter((entry) => PSYCHE_SEED_STAGE_NAME.test(entry)).sort()) {
+        const stage = path.join(agentRoot, name);
+        const entries = interruptedPsycheSeedEntries(stage, root);
+        if (!entries)
+            continue;
+        for (const entry of entries)
+            fs.unlinkSync(path.join(stage, entry));
+        fs.rmdirSync(stage);
+        removed = true;
+    }
+    if (removed)
+        syncDirectory(agentRoot);
+}
+/** The names in the install's own house/house.json, read only as a plain, non-symlinked file; anything else gives none. */
+function seedHouseNames(agentRoot) {
+    const relative = path.join("house", "house.json");
+    let fd;
+    try {
+        if (!inspectRelativeFile(agentRoot, relative, "invalid_live_bundle"))
+            return {};
+        // Opened without following a link and re-checked on the descriptor, so a swap after the check reads nothing.
+        fd = fs.openSync(path.join(agentRoot, relative), fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        if (!fs.fstatSync(fd).isFile())
+            return {};
+        return (0, house_names_1.houseNameFields)(fs.readFileSync(fd, "utf8"));
+    }
+    catch {
+        return {};
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+function seedSanctuaryPsycheIfAbsent(input, deps = {}) {
+    validateAgentRoot(input.agentRoot);
+    cleanupInterruptedPsycheSeeds(input.agentRoot);
+    const state = psycheState(input.agentRoot);
+    if (state === "directory")
+        return { ok: true, seeded: false };
+    if (state === "invalid")
+        return { ok: false, code: "invalid_live_bundle" };
+    const names = seedHouseNames(input.agentRoot);
+    const named = Object.keys(names).length > 0;
+    const sources = exports.SANCTUARY_STARTER_PSYCHE_FILES.map((relative) => {
+        if (!inspectRelativeFile(input.packageRoot, relative, "invalid_package_source"))
+            throw new SanctuaryInspectionFault("invalid_package_source", `starter psyche source is missing: ${relative}`);
+        const raw = fs.readFileSync(path.join(input.packageRoot, relative));
+        // With no names to give, the seed is the packaged bytes exactly.
+        return { name: path.basename(relative), content: named ? Buffer.from((0, house_names_1.fillHouseNames)(raw.toString("utf8"), names), "utf8") : raw };
+    });
+    const writeFile = deps.writeFile ?? ((fd, content) => fs.writeFileSync(fd, content));
+    const stage = fs.mkdtempSync(path.join(input.agentRoot, PSYCHE_SEED_STAGE_PREFIX));
+    for (const source of sources) {
+        const fd = fs.openSync(path.join(stage, source.name), "wx", 0o600);
+        try {
+            writeFile(fd, source.content);
+            fs.fchmodSync(fd, 0o600);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    const directory = fs.openSync(stage, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        fs.fchmodSync(directory, 0o755);
+        fs.fsyncSync(directory);
+    }
+    finally {
+        fs.closeSync(directory);
+    }
+    if (psycheState(input.agentRoot) !== "absent")
+        throw new SanctuaryInspectionFault("invalid_live_bundle", "psyche appeared while the starter psyche was staged");
+    // POSIX rename can still replace an empty psyche directory created in this window, which loses no content; Node has no RENAME_NOREPLACE.
+    fs.renameSync(stage, path.join(input.agentRoot, "psyche"));
+    syncDirectory(input.agentRoot);
+    (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_psyche_seeded", message: "seeded the starter psyche into a bundle that had none", meta: { agentRoot: input.agentRoot, files: sources.length } });
+    return { ok: true, seeded: true };
+}
+function inspectSanctuaryPackageManagedBundleRollback(agentRoot) {
+    validateAgentRoot(agentRoot);
+    const record = readDurableRecord(agentRoot);
+    return record ? { rollbackImageId: record.rollbackImageId, targetImageId: record.targetImageId, state: record.state } : null;
+}
+function rollbackSanctuaryPackageManagedBundle(agentRoot, options = {}) {
+    validateAgentRoot(agentRoot);
+    const record = readDurableRecord(agentRoot);
+    if (!record)
+        return false;
+    if (record.state === "committing")
+        throw new Error("Sanctuary bundle commit is pending and cannot be rolled back");
+    restoreMigrationSnapshot(record.snapshot, agentRoot);
+    if (!options.retainRecord)
+        removeRollbackRecord(agentRoot, record.filePath);
+    return true;
+}
+function commitSanctuaryPackageManagedBundle(agentRoot) {
+    validateAgentRoot(agentRoot);
+    const record = readDurableRecord(agentRoot);
+    if (!record)
+        return false;
+    const committingPath = path.join(agentRoot, SANCTUARY_BUNDLE_COMMITTING_FILE);
+    if (record.filePath !== committingPath) {
+        fs.renameSync(record.filePath, committingPath);
+        syncDirectory(agentRoot);
+    }
+    removeRollbackRecord(agentRoot, committingPath);
+    return true;
+}
+function restoreMigrationSnapshot(snapshot, agentRoot) {
+    const restoredModes = new Map();
+    for (const file of snapshot.files)
+        if (file.mode !== null)
+            restoredModes.set(file.path, file.mode);
+    cleanupInterruptedWrites(snapshot.files.map((file) => file.path), restoredModes);
+    for (const file of snapshot.files) {
+        if (file.content === null) {
+            fs.rmSync(file.path, { force: true });
+            syncNearestExistingDirectory(path.dirname(file.path), agentRoot);
+        }
+        else {
+            writeAtomic(file.path, file.content, file.mode);
+        }
+    }
+    for (const directory of [...snapshot.directories].reverse()) {
+        if (directory.mode === null) {
+            if (!fs.existsSync(directory.path)) {
+                syncNearestExistingDirectory(path.dirname(directory.path), agentRoot);
+            }
+            else if (fs.readdirSync(directory.path).length === 0) {
+                fs.rmdirSync(directory.path);
+                syncNearestExistingDirectory(path.dirname(directory.path), agentRoot);
+            }
+        }
+        else {
+            const handle = fs.openSync(directory.path, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+            try {
+                fs.fchmodSync(handle, directory.mode);
+                fs.fsyncSync(handle);
+            }
+            finally {
+                fs.closeSync(handle);
+            }
+        }
+    }
+}
+function migrateSanctuaryPackageManagedBundle(input) {
+    (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_bundle_migration_start", message: "starting Sanctuary package-managed bundle migration", meta: { agentRoot: input.agentRoot } });
+    let snapshot = null;
+    try {
+        if (!path.isAbsolute(input.packageRoot) || !path.isAbsolute(input.agentRoot))
+            throw new Error("package and agent roots must be absolute paths");
+        const packageIdentity = inspectStandaloneSanctuaryDirectory(input.packageRoot);
+        const agentIdentity = inspectStandaloneSanctuaryDirectory(input.agentRoot);
+        if (!packageIdentity)
+            throw new Error("package root must be a canonical real directory");
+        if (!agentIdentity)
+            throw new Error("agent root must be a canonical real directory");
+        if (sanctuaryDirectoriesShareIdentity(packageIdentity, agentIdentity))
+            throw new Error("package and agent roots must be distinct real directories");
+        if (input.retainRollback && (!input.rollbackImageId || !/^sha256:[0-9a-f]{64}$/u.test(input.rollbackImageId) || !input.targetImageId || !/^sha256:[0-9a-f]{64}$/u.test(input.targetImageId) || input.targetImageId === input.rollbackImageId))
+            throw new Error("retained rollback requires distinct exact rollback and target image IDs");
+        const existingRollback = rollbackPath(input.agentRoot);
+        if (readDurableRecord(input.agentRoot))
+            throw new Error("Sanctuary bundle rollback is pending; rollback or commit it before another migration");
+        for (const relative of exports.SANCTUARY_PACKAGE_MANAGED_FILES) {
+            requirePlainFile(path.join(input.packageRoot, relative), `package-managed source ${relative}`);
+            validateDestination(input.agentRoot, relative);
+        }
+        requirePlainFile(path.join(input.packageRoot, "bundle-meta.json"), "packaged bundle-meta.json");
+        validateDestination(input.agentRoot, "bundle-meta.json");
+        const packagedMeta = readObject(path.join(input.packageRoot, "bundle-meta.json"));
+        for (const field of BUNDLE_META_VERSION_FIELDS)
+            if (!(field in packagedMeta))
+                throw new Error(`packaged bundle-meta.json is missing ${field}`);
+        validatePackagedPolicy(input.packageRoot);
+        cleanupInterruptedWrites(packageManagedArtifactPaths(input.agentRoot));
+        snapshot = captureMigrationSnapshot(input.agentRoot);
+        if (input.retainRollback) {
+            writeAtomic(existingRollback, `${JSON.stringify(durableSnapshot(input.agentRoot, snapshot, input.rollbackImageId, input.targetImageId))}\n`);
+        }
+        let managedFilesUpdated = 0;
+        for (const relative of exports.SANCTUARY_PACKAGE_MANAGED_FILES) {
+            const source = fs.readFileSync(path.join(input.packageRoot, relative), "utf8");
+            const destination = path.join(input.agentRoot, relative);
+            ensureSafeParent(input.agentRoot, relative);
+            if (fs.existsSync(destination) && fs.readFileSync(destination, "utf8") === source && (fs.statSync(destination).mode & 0o777) === 0o600)
+                continue;
+            writeAtomic(destination, source);
+            managedFilesUpdated += 1;
+        }
+        const metaPath = path.join(input.agentRoot, "bundle-meta.json");
+        const metaExists = fs.existsSync(metaPath);
+        const currentMeta = metaExists ? readObject(metaPath) : {};
+        const nextMeta = { ...currentMeta };
+        for (const field of BUNDLE_META_VERSION_FIELDS)
+            nextMeta[field] = packagedMeta[field];
+        if (!metaExists || BUNDLE_META_VERSION_FIELDS.some((field) => currentMeta[field] !== packagedMeta[field])) {
+            writeAtomic(metaPath, `${JSON.stringify(nextMeta, null, 2)}\n`);
+        }
+        else if ((fs.statSync(metaPath).mode & 0o777) !== 0o600) {
+            fs.chmodSync(metaPath, 0o600);
+            const meta = fs.openSync(metaPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+            try {
+                fs.fsyncSync(meta);
+            }
+            finally {
+                fs.closeSync(meta);
+            }
+        }
+        if (!seedSanctuaryPsycheIfAbsent({ packageRoot: input.packageRoot, agentRoot: input.agentRoot }).ok)
+            throw new Error("psyche must be a real directory, not a symlink or file");
+        const result = { managedFilesUpdated };
+        (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_bundle_migration_end", message: "completed Sanctuary package-managed bundle migration", meta: result });
+        return result;
+    }
+    catch (error) {
+        let failure = error;
+        if (snapshot) {
+            try {
+                restoreMigrationSnapshot(snapshot, input.agentRoot);
+                if (fs.existsSync(rollbackPath(input.agentRoot)))
+                    removeRollbackRecord(input.agentRoot, rollbackPath(input.agentRoot));
+            }
+            catch (restoreError) {
+                failure = new AggregateError([error, restoreError], "Sanctuary bundle migration and rollback both failed");
+            }
+        }
+        (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_bundle_migration_error", level: "error", message: "Sanctuary package-managed bundle migration failed", meta: { error: String(failure), agentRoot: input.agentRoot } });
+        throw failure;
+    }
+}