@ouro.bot/cli 0.1.0-alpha.81 → 0.1.0-alpha.811

package/dist/senses/sanctuary-health-runner.js

@@ -0,0 +1,101 @@
+"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.runSanctuaryHealthHabit = runSanctuaryHealthHabit;
+const path = __importStar(require("node:path"));
+const router_1 = require("../heart/external-events/router");
+const identity_1 = require("../heart/identity");
+const machine_identity_1 = require("../heart/machine-identity");
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const runtime_1 = require("../nerves/runtime");
+const sanctuary_health_1 = require("./sanctuary-health");
+const sanctuary_runtime_1 = require("./sanctuary-runtime");
+function evidenceInputs(agentName, result) {
+    const revision = result.observationRevision;
+    const current = result.incidents.map((incident) => ({
+        agent: agentName,
+        source: "sanctuary-health",
+        eventType: "health.observed",
+        eventId: incident.id,
+        observationRevision: incident.observationRevision ?? revision,
+        transition: incident.transition ?? result.transition ?? "changed",
+        summary: incident.summary,
+        evidence: [incident.summary],
+        priority: "high",
+    }));
+    const recovered = (result.recovered ?? []).map((incident) => ({
+        agent: agentName,
+        source: "sanctuary-health",
+        eventType: "health.observed",
+        eventId: incident.id,
+        observationRevision: incident.observationRevision ?? revision,
+        transition: "recovered",
+        summary: `recovered: ${incident.summary}`,
+        evidence: [`recovered: ${incident.summary}`],
+        priority: "high",
+    }));
+    return [...current, ...recovered];
+}
+async function runSanctuaryHealthHabit(agentName, options = {}) {
+    if (!options.createSweep && !(0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(agentName).ok) {
+        const machine = (0, machine_identity_1.loadOrCreateMachineIdentity)();
+        await (0, runtime_credentials_1.refreshMachineRuntimeCredentialConfig)(agentName, machine.machineId, { preserveCachedOnFailure: true });
+    }
+    const sweep = options.createSweep?.(agentName) ?? (0, sanctuary_health_1.createSanctuaryHealthSweep)({
+        toolContext: (0, sanctuary_runtime_1.createSanctuaryToolContext)(agentName),
+        statePath: path.join((0, identity_1.getAgentRoot)(agentName), "state", "health", "sanctuary-health.json"),
+    });
+    const result = await sweep();
+    const inputs = evidenceInputs(agentName, result);
+    if (inputs.length === 0) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.sanctuary_health_habit",
+            message: "Sanctuary health evidence submitted",
+            meta: { agentName, incidentCount: 0, submitted: 0, wakesRequested: 0 },
+        });
+        return { ok: true, message: "health evidence submitted", data: { incidentCount: 0, submitted: 0, wakesRequested: 0 } };
+    }
+    const submit = options.submitEvidence ?? ((input) => (0, router_1.recordExternalEvent)(input));
+    const receipts = await Promise.all(inputs.map((input) => submit(input)));
+    const wakesRequested = receipts.some((receipt) => receipt.shouldWake) ? 1 : 0;
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.sanctuary_health_habit",
+        message: "Sanctuary health evidence submitted",
+        meta: { agentName, incidentCount: result.incidents.length, submitted: inputs.length, wakesRequested },
+    });
+    return { ok: true, message: "health evidence submitted", data: { incidentCount: result.incidents.length, submitted: inputs.length, wakesRequested } };
+}

package/dist/senses/sanctuary-health.js

@@ -0,0 +1,408 @@
+"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_PUBLIC_ENDPOINTS = void 0;
+exports.withSanctuaryHealthStateLease = withSanctuaryHealthStateLease;
+exports.readSanctuaryHealthState = readSanctuaryHealthState;
+exports.probeSanctuaryEndpoint = probeSanctuaryEndpoint;
+exports.createSanctuaryHealthSweep = createSanctuaryHealthSweep;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+const sanctuary_acceptance_marker_1 = require("../heart/daemon/sanctuary-acceptance-marker");
+exports.SANCTUARY_PUBLIC_ENDPOINTS = [
+    "https://media.mendelow.cloud/",
+    "https://books.mendelow.cloud/",
+    "https://requests.mendelow.cloud/",
+    "https://readarr.mendelow.cloud/",
+];
+const REQUIRED_CONTAINERS = new Set(["calibre", "calibre-web", "Cloudflare-DDNS"]);
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const MAX_HEALTH_STATE_BYTES = 4 * 1024 * 1024;
+const MAX_HEALTH_TEXT_BYTES = 50_000;
+const MAX_HEALTH_INCIDENT_BYTES = 4_096;
+function boundedIncidentText(value) {
+    if (Buffer.byteLength(value) <= MAX_HEALTH_INCIDENT_BYTES)
+        return value;
+    let output = "";
+    for (const character of value) {
+        if (Buffer.byteLength(output) + Buffer.byteLength(character) > MAX_HEALTH_INCIDENT_BYTES - 3)
+            break;
+        output += character;
+    }
+    return `${output}…`;
+}
+function canonicalIsoTimestamp(value) {
+    if (typeof value !== "string" || value.length > 30)
+        return false;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+const healthLockTails = new Map();
+const healthLeaseBrand = Symbol("sanctuary-health-state-lease");
+const activeHealthLeases = new Set();
+function healthLeaseOwner(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Sanctuary health lease ownership is invalid");
+    const owner = value;
+    if (JSON.stringify(Object.keys(owner).sort()) !== JSON.stringify(["nonce", "pid", "schemaVersion"])
+        || owner.schemaVersion !== 1 || !Number.isSafeInteger(owner.pid) || Number(owner.pid) < 1
+        || typeof owner.nonce !== "string" || !/^[0-9a-f]{64}$/u.test(owner.nonce)) {
+        throw new Error("Sanctuary health lease ownership is invalid");
+    }
+    return owner;
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function removeHealthLeaseDirectory(leasePath) {
+    const entries = fs.readdirSync(leasePath, { withFileTypes: true });
+    if (entries.some((entry) => !entry.isFile() || entry.name !== "owner.json"))
+        throw new Error("Sanctuary health lease contains unexpected entries");
+    if (entries.length === 1)
+        fs.unlinkSync(path.join(leasePath, "owner.json"));
+    fs.rmdirSync(leasePath);
+}
+async function acquireHealthFileLease(statePath, timeoutMs) {
+    const leasePath = `${statePath}.lease`;
+    const ownerPath = path.join(leasePath, "owner.json");
+    const deadline = Date.now() + timeoutMs;
+    const nonce = (0, node_crypto_1.createHash)("sha256").update((0, node_crypto_1.randomUUID)()).digest("hex");
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    for (;;) {
+        try {
+            fs.mkdirSync(leasePath, { recursive: false, mode: 0o700 });
+            fs.writeFileSync(ownerPath, `${JSON.stringify({ schemaVersion: 1, pid: process.pid, nonce })}\n`, { flag: "wx", mode: 0o600 });
+            return { statePath, nonce, [healthLeaseBrand]: true };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                try {
+                    if (fs.existsSync(leasePath) && !fs.existsSync(ownerPath))
+                        fs.rmdirSync(leasePath);
+                }
+                catch { /* preserve the original failure */ }
+                throw error;
+            }
+            let owner;
+            try {
+                owner = healthLeaseOwner(JSON.parse(fs.readFileSync(ownerPath, "utf8")));
+            }
+            catch (ownerError) {
+                if (ownerError.code === "ENOENT" && Date.now() < deadline) {
+                    await new Promise((resolve) => setTimeout(resolve, 10));
+                    continue;
+                }
+                if (ownerError instanceof Error && ownerError.message.includes("ownership is invalid"))
+                    throw ownerError;
+                throw new Error("Sanctuary health lease ownership is invalid", { cause: ownerError });
+            }
+            if (!processIsAlive(owner.pid)) {
+                removeHealthLeaseDirectory(leasePath);
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error("Sanctuary health state lease timed out");
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+    }
+}
+function releaseHealthFileLease(lease) {
+    const leasePath = `${lease.statePath}.lease`;
+    const owner = healthLeaseOwner(JSON.parse(fs.readFileSync(path.join(leasePath, "owner.json"), "utf8")));
+    if (owner.nonce !== lease.nonce || owner.pid !== process.pid)
+        throw new Error("Sanctuary health lease ownership changed");
+    removeHealthLeaseDirectory(leasePath);
+}
+async function withSanctuaryHealthStateLease(statePath, operation, options = {}) {
+    const previous = healthLockTails.get(statePath) ?? Promise.resolve();
+    let releaseProcess;
+    const current = new Promise((resolve) => { releaseProcess = resolve; });
+    healthLockTails.set(statePath, current);
+    await previous;
+    let lease;
+    try {
+        lease = await acquireHealthFileLease(statePath, options.timeoutMs ?? 30_000);
+        activeHealthLeases.add(lease);
+        return await operation(lease);
+    }
+    finally {
+        if (lease) {
+            activeHealthLeases.delete(lease);
+            releaseHealthFileLease(lease);
+        }
+        releaseProcess();
+        if (healthLockTails.get(statePath) === current)
+            healthLockTails.delete(statePath);
+    }
+}
+async function withHealthLock(statePath, operation, lease) {
+    if (lease) {
+        if (lease.statePath !== statePath || !activeHealthLeases.has(lease) || lease[healthLeaseBrand] !== true) {
+            throw new Error("Sanctuary health state lease is invalid");
+        }
+        return await operation();
+    }
+    return withSanctuaryHealthStateLease(statePath, async () => operation());
+}
+function load(filePath) {
+    try {
+        if (fs.statSync(filePath).size > MAX_HEALTH_STATE_BYTES)
+            throw new Error("health state exceeds its bound");
+        const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        const validDelivery = (delivery) => Boolean(delivery && typeof delivery === "object"
+            && typeof delivery.id === "string" && delivery.id.length > 0 && delivery.id.length <= 128
+            && typeof delivery.message === "string" && Buffer.byteLength(delivery.message) <= MAX_HEALTH_TEXT_BYTES
+            && ["pending", "attempting"].includes(delivery.status)
+            && canonicalIsoTimestamp(delivery.createdAt)
+            && (delivery.kind === undefined || ["transition", "digest", "transition_and_digest", "legacy_unknown"].includes(delivery.kind))
+            && (delivery.summarizedMessage === undefined || (typeof delivery.summarizedMessage === "string" && Buffer.byteLength(delivery.summarizedMessage) <= MAX_HEALTH_TEXT_BYTES)));
+        if (!value.incidents || typeof value.incidents !== "object" || Array.isArray(value.incidents))
+            throw new Error("invalid incidents");
+        if (value.lastDigestDay !== null && typeof value.lastDigestDay !== "string")
+            throw new Error("invalid digest day");
+        if (typeof value.updatedAt !== "string")
+            throw new Error("invalid update time");
+        if (value.outbox !== undefined && value.outbox !== null && !validDelivery(value.outbox))
+            throw new Error("invalid health outbox");
+        if (value.indeterminateDeliveries !== undefined && (!Array.isArray(value.indeterminateDeliveries) || !value.indeterminateDeliveries.every(validDelivery)))
+            throw new Error("invalid indeterminate deliveries");
+        if (value.deliveredReceipts !== undefined && (!Array.isArray(value.deliveredReceipts) || value.deliveredReceipts.length > 100 || !value.deliveredReceipts.every((receipt) => (receipt && typeof receipt.deliveryId === "string" && receipt.deliveryId.length > 0 && receipt.deliveryId.length <= 128 && canonicalIsoTimestamp(receipt.deliveredAt)
+            && (receipt.kind === undefined || ["transition", "digest", "transition_and_digest", "legacy_unknown"].includes(receipt.kind))
+            && Array.isArray(receipt.messageIds) && receipt.messageIds.length > 0 && receipt.messageIds.length <= 100
+            && receipt.messageIds.every((id) => Number.isSafeInteger(id) && id > 0)))))
+            throw new Error("invalid delivered receipts");
+        if (value.sweepReceipts !== undefined && (!Array.isArray(value.sweepReceipts) || value.sweepReceipts.length > 500 || !value.sweepReceipts.every((receipt) => (receipt && typeof receipt.sweepId === "string" && UUID_V4.test(receipt.sweepId)
+            && canonicalIsoTimestamp(receipt.startedAt)
+            && canonicalIsoTimestamp(receipt.completedAt)
+            && /^[0-9a-f]{64}$/u.test(receipt.incidentDigest) && Number.isSafeInteger(receipt.opened) && receipt.opened >= 0
+            && Number.isSafeInteger(receipt.recovered) && receipt.recovered >= 0 && typeof receipt.digestDue === "boolean"
+            && (receipt.deliveryId === undefined || (typeof receipt.deliveryId === "string" && receipt.deliveryId.length > 0 && receipt.deliveryId.length <= 128))
+            && (receipt.scenarioHandleDigest === undefined || /^[0-9a-f]{64}$/u.test(receipt.scenarioHandleDigest))))))
+            throw new Error("invalid sweep receipts");
+        return {
+            incidents: value.incidents,
+            lastDigestDay: value.lastDigestDay,
+            updatedAt: value.updatedAt,
+            outbox: value.outbox ? { ...value.outbox, kind: value.outbox.kind ?? "legacy_unknown" } : null,
+            indeterminateDeliveries: (value.indeterminateDeliveries ?? []).map((delivery) => ({ ...delivery, kind: delivery.kind ?? "legacy_unknown" })),
+            deliveredReceipts: (value.deliveredReceipts ?? []).map((receipt) => ({ ...receipt, kind: receipt.kind ?? "legacy_unknown" })),
+            sweepReceipts: value.sweepReceipts ?? [],
+        };
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+            return { incidents: {}, lastDigestDay: null, updatedAt: new Date(0).toISOString(), outbox: null, indeterminateDeliveries: [], deliveredReceipts: [], sweepReceipts: [] };
+        throw new Error("Sanctuary health state is corrupt", { cause: error });
+    }
+}
+/** Read-only projection for status/orientation surfaces; mutation remains lease-owned by the sweep. */
+function readSanctuaryHealthState(filePath) {
+    return load(filePath);
+}
+function save(filePath, state) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const temporary = `${filePath}.tmp-${process.pid}-${(0, node_crypto_1.randomUUID)()}`;
+    fs.writeFileSync(temporary, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+    const temporaryHandle = fs.openSync(temporary, "r");
+    try {
+        fs.fsyncSync(temporaryHandle);
+    }
+    finally {
+        fs.closeSync(temporaryHandle);
+    }
+    fs.renameSync(temporary, filePath);
+    const directoryHandle = fs.openSync(path.dirname(filePath), "r");
+    try {
+        fs.fsyncSync(directoryHandle);
+    }
+    finally {
+        fs.closeSync(directoryHandle);
+    }
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+async function probeSanctuaryEndpoint(url, fetchImpl = fetch) {
+    const configured = new URL(url);
+    if (configured.protocol !== "https:" || configured.username || configured.password)
+        return { url, ok: false, status: 0 };
+    let current = configured;
+    try {
+        for (let redirects = 0;; redirects += 1) {
+            const response = await fetchImpl(current.href, { signal: AbortSignal.timeout(10_000), redirect: "manual" });
+            const redirect = response.status >= 300 && response.status < 400;
+            if (!redirect) {
+                await response.body?.cancel().catch(() => undefined);
+                return { url, ok: response.status >= 200 && response.status < 400, status: response.status };
+            }
+            const location = response.headers.get("location");
+            await response.body?.cancel().catch(() => undefined);
+            if (!location || redirects === 5)
+                return { url, ok: false, status: 0 };
+            const target = new URL(location, current);
+            if (target.protocol !== "https:" || target.origin !== configured.origin || target.username || target.password) {
+                return { url, ok: false, status: 0 };
+            }
+            current = target;
+        }
+    }
+    catch {
+        return { url, ok: false, status: 0 };
+    }
+}
+function createSanctuaryHealthSweep(options) {
+    const fetchImpl = options.fetch ?? fetch;
+    const now = options.now ?? (() => new Date());
+    const acceptanceEventMeta = options.acceptanceEventMeta ?? (() => (0, sanctuary_acceptance_marker_1.sanctuaryAcceptanceEventMeta)("sanctuary"));
+    const runSweep = async () => {
+        const sweepId = (0, node_crypto_1.randomUUID)();
+        const startedAt = now().toISOString();
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.sanctuary_health_start", message: "Sanctuary deterministic health sweep started", meta: { statePath: options.statePath, ...acceptanceEventMeta() } });
+        const pendingState = load(options.statePath);
+        if (pendingState.outbox) {
+            pendingState.outbox = null;
+            pendingState.indeterminateDeliveries = [];
+            pendingState.updatedAt = now().toISOString();
+            save(options.statePath, pendingState);
+        }
+        const runtime = options.toolContext.sanctuary;
+        if (!runtime)
+            throw new Error("Sanctuary health runtime is unavailable");
+        const [containersResult, storageResult, disksResult, notificationsResult, endpoints] = await Promise.all([
+            runtime.listContainers(), runtime.getStorage(), runtime.getDisks(), runtime.getNotifications(),
+            Promise.all(exports.SANCTUARY_PUBLIC_ENDPOINTS.map((url) => probeSanctuaryEndpoint(url, fetchImpl))),
+        ]);
+        const incidents = new Map();
+        const add = (id, rawSummary) => {
+            const summary = boundedIncidentText(rawSummary);
+            incidents.set(id, {
+                id,
+                summary,
+                observationRevision: (0, node_crypto_1.createHash)("sha256").update(`${id}\0${summary}`).digest("hex"),
+            });
+        };
+        const containers = record(containersResult)?.ok ? record(record(containersResult)?.data)?.containers : null;
+        if (!Array.isArray(containers))
+            add("containers:unavailable", "container status is unavailable");
+        else
+            for (const container of containers) {
+                if ((container.autostart === true || REQUIRED_CONTAINERS.has(container.name)) && container.state !== "running")
+                    add(`container:${container.id}:availability`, `${container.name} is ${container.state}`);
+                if (container.state === "unknown" || container.degraded === true)
+                    add(`container:${container.id}:health`, `${container.name} status is degraded`);
+            }
+        const storage = record(storageResult)?.ok ? record(record(storageResult)?.data) : null;
+        const array = record(storage?.array);
+        if (!array || array.degraded || typeof array.usedPercent !== "number")
+            add("storage:array:capacity", "array capacity is unavailable");
+        else if (array.usedPercent >= 90)
+            add("storage:array:capacity", `array usage is ${array.usedPercent}%`);
+        for (const share of Array.isArray(storage?.shares) ? storage.shares : [])
+            if (share.degraded || typeof share.usedPercent !== "number")
+                add(`storage:share:${share.name}:capacity`, `${share.name} capacity is unavailable`);
+            else if (share.usedPercent >= 90)
+                add(`storage:share:${share.name}:capacity`, `${share.name} usage is ${share.usedPercent}%`);
+        const disks = record(disksResult)?.ok ? record(record(disksResult)?.data) : null;
+        if (!disks)
+            add("disks:unavailable", "disk health is unavailable");
+        else {
+            for (const disk of Array.isArray(disks.disks) ? disks.disks : []) {
+                if (disk.smart !== "passed")
+                    add(`disk:${disk.id}:smart`, `${disk.name} SMART is ${disk.smart}`);
+                if (typeof disk.temperatureC !== "number")
+                    add(`disk:${disk.id}:temperature`, `${disk.name} temperature is unavailable`);
+                else if (disk.temperatureC >= 50)
+                    add(`disk:${disk.id}:temperature`, `${disk.name} is ${disk.temperatureC}°C`);
+            }
+            const parity = record(disks.parity);
+            if (!parity || parity.result !== "success" || typeof parity.ageHours !== "number" || parity.ageHours >= 45 * 24)
+                add("parity:stale-or-failed", "parity check is unsuccessful, unknown, or older than 45 days");
+        }
+        const notifications = record(notificationsResult)?.ok ? record(record(notificationsResult)?.data)?.unacknowledged : null;
+        if (!Array.isArray(notifications))
+            add("notifications:unavailable", "notification status is unavailable");
+        else
+            for (const item of notifications)
+                add(`notification:${item.id}`, `unacknowledged notification: ${item.title || item.id}`);
+        for (const endpoint of endpoints)
+            if (!endpoint.ok)
+                add(`endpoint:${endpoint.url}`, `${endpoint.url} returned ${endpoint.status || "no response"}`);
+        const previous = load(options.statePath);
+        const current = Object.fromEntries([...incidents.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([id, incident]) => {
+            const prior = previous.incidents[id];
+            const transition = !prior ? "opened" : prior.observationRevision === incident.observationRevision ? "unchanged" : "changed";
+            return [id, { ...incident, transition }];
+        }));
+        const opened = Object.values(current).filter((incident) => !previous.incidents[incident.id]);
+        const changed = Object.values(current).filter((incident) => incident.transition === "changed");
+        const recovered = Object.values(previous.incidents).filter((incident) => !current[incident.id]);
+        const acceptanceMeta = acceptanceEventMeta();
+        const completedAt = now().toISOString();
+        const incidentDigest = (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(current)).digest("hex");
+        const sweepReceipt = {
+            sweepId,
+            startedAt,
+            completedAt,
+            incidentDigest,
+            opened: opened.length,
+            recovered: recovered.length,
+            digestDue: false,
+            ...(acceptanceMeta.scenarioHandleDigest ? { scenarioHandleDigest: acceptanceMeta.scenarioHandleDigest } : {}),
+        };
+        const next = {
+            incidents: current,
+            lastDigestDay: null,
+            updatedAt: now().toISOString(),
+            outbox: null,
+            indeterminateDeliveries: [],
+            deliveredReceipts: previous.deliveredReceipts,
+            sweepReceipts: [...previous.sweepReceipts, sweepReceipt].slice(-500),
+        };
+        save(options.statePath, next);
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.sanctuary_health_end", message: "Sanctuary deterministic health sweep completed", meta: { incidentCount: incidents.size, opened: opened.length, recovered: recovered.length, digestDue: false, ...acceptanceEventMeta() } });
+        const transition = changed.length > 0 || (opened.length > 0 && recovered.length > 0) ? "changed" : opened.length > 0 ? "opened" : recovered.length > 0 ? "recovered" : "unchanged";
+        return { message: null, incidents: Object.values(current), recovered, observationRevision: incidentDigest, transition };
+    };
+    const sweep = (() => withHealthLock(options.statePath, runSweep, options.lease));
+    return sweep;
+}

package/dist/senses/sanctuary-install-state-contract.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanctuaryInstallStateRequiredToolCalls = sanctuaryInstallStateRequiredToolCalls;
+const runtime_1 = require("../nerves/runtime");
+const TOOL_NAME = "sanctuary_get_install_state";
+const REQUEST = /\b(?:use|run|call)\s+sanctuary_get_install_state\b/iu;
+const NEGATED_REQUEST = /\b(?:do not|don't|dont|never|must not|should not|cannot|can't)\s+(?:(?:under|any|all|circumstances|whatsoever|ever|please|really|actually|immediately)\s+)*(?:use|run|call)\s+sanctuary_get_install_state\b|\bnot\s+to\s+(?:use|run|call)\s+sanctuary_get_install_state\b|\b(?:do not|don't|dont)\s+(?:(?:want|need|ask)\b(?:(?![.!?;,:]).){0,64}|(?:(?:under|any|all|circumstances|whatsoever|ever|please|really|actually|immediately)\s+)*(?:attempt|try|plan|intend)\s+(?:to\s+)?)(?:use|run|call)\s+sanctuary_get_install_state\b/giu;
+const HISTORICAL_QUESTION = /\b(?:did|have|has)\s+(?:you\s+)?(?:use|run|call)\s+sanctuary_get_install_state\b[^.!?;:]*/giu;
+const MISMATCH_CODES = new Set([
+    "managed_file_missing",
+    "managed_file_content",
+    "managed_file_mode",
+    "bundle_meta_missing",
+    "bundle_meta_field",
+    "bundle_meta_mode",
+]);
+const REPAIR_ACTIONS = new Set([
+    "restart_from_verified_release",
+    "run_verified_update_recovery",
+    "roll_back_or_install_verified_release",
+]);
+function parseInstallState(result) {
+    try {
+        const parsed = JSON.parse(result);
+        const data = parsed.ok === true && parsed.data && typeof parsed.data === "object" && !Array.isArray(parsed.data)
+            ? parsed.data
+            : undefined;
+        const repair = data?.repair && typeof data.repair === "object" && !Array.isArray(data.repair)
+            ? data.repair
+            : undefined;
+        if (!data
+            || typeof data.runtimePackageVersion !== "string" || data.runtimePackageVersion.length === 0
+            || typeof data.packagedBundleVersion !== "string" || data.packagedBundleVersion.length === 0
+            || !(typeof data.liveBundleVersion === "string" && data.liveBundleVersion.length > 0 || data.liveBundleVersion === null)
+            || !["exact", "mismatch"].includes(String(data.parity))
+            || !Array.isArray(data.mismatchCodes)
+            || !data.mismatchCodes.every((code) => typeof code === "string" && MISMATCH_CODES.has(code))
+            || !["absent", "rollback", "committing"].includes(String(data.journalState))
+            || typeof data.ready !== "boolean"
+            || !(repair?.actor === "none" && repair.action === "none"
+                || repair?.actor === "human-required" && typeof repair.action === "string" && REPAIR_ACTIONS.has(repair.action)))
+            return undefined;
+        return {
+            runtimePackageVersion: data.runtimePackageVersion,
+            packagedBundleVersion: data.packagedBundleVersion,
+            liveBundleVersion: data.liveBundleVersion,
+            parity: data.parity,
+            journalState: data.journalState,
+            ready: data.ready,
+            repairAction: repair.action,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function exactAnswerPattern(current) {
+    const value = (raw) => raw.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const assignment = String.raw `\s*(?:(?:is)\s+|[:=]\s*)?`;
+    const separator = String.raw `\s*[,;]\s*`;
+    return new RegExp(String.raw `runtime(?: package)?(?: version)?${assignment}${value(current.runtimePackageVersion)}${separator}`
+        + String.raw `packaged(?: bundle)?(?: version)?${assignment}${value(current.packagedBundleVersion)}${separator}`
+        + String.raw `live(?: bundle)?(?: version)?${assignment}${value(current.liveBundleVersion ?? "null")}${separator}`
+        + String.raw `parity${assignment}${value(current.parity)}${separator}`
+        + String.raw `journal(?: state)?${assignment}${value(current.journalState)}${separator}`
+        + String.raw `ready(?: state)?${assignment}${value(String(current.ready))}${separator}`
+        + String.raw `repair(?: action)?${assignment}${value(current.repairAction)}(?=$|[\s,;.!?])`, "iu");
+}
+const RESIDUAL_INSTALL_STATE_CLAIM = /(?:^|[.!?;,]\s*)(?:(?:and|but|however|yet)\s+)*(?:(?:the\s+)?(?:runtime(?: package)?(?: version)?|packaged(?: bundle)?(?: version)?|live(?: bundle)?(?: version)?)\s*(?:(?:is)\s+|[:=]\s*)?(?=v?\d|unknown\b|null\b|missing\b|corrupt\b)|(?:the\s+)?installed package(?: version)?\b|(?:the\s+)?parity\s*(?:(?:is)\s+|[:=]\s*)?(?=(?:not\s+)?(?:exact|mismatch)\b)|(?:the\s+)?journal(?: state)?\s*(?:(?:is)\s+|[:=]\s*)?(?=(?:not\s+)?(?:absent|rollback|committing)\b)|(?:the\s+)?ready(?: state)?\s*(?:(?:is)\s+|[:=]\s*)?(?=(?:not\s+)?(?:true|false|ready)\b)|(?:the\s+)?repair(?: action)?\s*(?:(?:is)\s+|[:=]\s*)?(?=none\b|restart_from_verified_release\b|run_verified_update_recovery\b|roll_back_or_install_verified_release\b|required\b|needed\b)|(?:the\s+)?(?:install(?:ation)?|sanctuary|bundle|service|system|it)\s+(?:is(?:\s+not)?|isn't)\s+ready\b)/iu;
+function sanctuaryInstallStateRequiredToolCalls(request, advertisedToolNames) {
+    const normalizedRequest = request.normalize("NFKC").replace(/[‘’]/gu, "'");
+    const negationRequest = normalizedRequest.replace(/,/gu, " ");
+    const affirmativeRequest = negationRequest
+        .replace(NEGATED_REQUEST, " ")
+        .replace(HISTORICAL_QUESTION, " ");
+    if (!advertisedToolNames.includes(TOOL_NAME)
+        || !REQUEST.test(affirmativeRequest))
+        return undefined;
+    let current;
+    const retryMessage = "Call sanctuary_get_install_state with empty arguments, then answer only from that fresh result.";
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.sanctuary_install_state_required",
+        message: "explicit Sanctuary install-state request requires a fresh verified read",
+        meta: { requiredToolName: TOOL_NAME },
+    });
+    return {
+        names: [TOOL_NAME],
+        retryMessage,
+        requireSuccessfulResults: true,
+        validateRequiredToolResult: (name, result, args) => {
+            if (name !== TOOL_NAME || Object.keys(args).length !== 0)
+                return false;
+            current = parseInstallState(result);
+            return current !== undefined;
+        },
+        validateTerminalAnswer: (answer) => {
+            if (!current) {
+                return "Answer from the fresh install-state result and include its runtime package version, packaged bundle version, live bundle version, parity, journal state, ready state, and repair action.";
+            }
+            const normalizedAnswer = answer.normalize("NFKC").replace(/[‘’]/gu, "'").replace(/\*\*|`/gu, "");
+            const exactMatches = [...normalizedAnswer.matchAll(new RegExp(exactAnswerPattern(current).source, "giu"))];
+            if (exactMatches.length === 0) {
+                const currentValues = [
+                    current.runtimePackageVersion,
+                    current.packagedBundleVersion,
+                    current.liveBundleVersion ?? "null",
+                    current.parity,
+                    current.journalState,
+                    String(current.ready),
+                    current.repairAction,
+                ];
+                return currentValues.every((value) => normalizedAnswer.includes(value))
+                    ? "State each fresh install-state value exactly once in one compact answer."
+                    : "Answer from the fresh install-state result and include its runtime package version, packaged bundle version, live bundle version, parity, journal state, ready state, and repair action.";
+            }
+            if (exactMatches.length !== 1)
+                return "State each fresh install-state value exactly once in one compact answer.";
+            const match = exactMatches[0];
+            const residual = normalizedAnswer.replace(match[0], " ").trim();
+            if (RESIDUAL_INSTALL_STATE_CLAIM.test(residual))
+                return "State each fresh install-state value exactly once in one compact answer.";
+            return undefined;
+        },
+    };
+}