@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.920

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

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanctuaryInstallStateRequiredToolCalls = sanctuaryInstallStateRequiredToolCalls;
+exports.sanctuaryVersionQuestionRequiredToolCalls = sanctuaryVersionQuestionRequiredToolCalls;
+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;
+        },
+    };
+}
+const VERSION_QUESTION = /\b(?:what|which)(?:'s|\s+is)?\s+(?:your\s+|the\s+)?(?:current\s+|live\s+|installed\s+|running\s+)?version\b|\bversion\s+(?:are|r)\s+(?:you|u)\b|\bwhat\s+(?:are\s+you|you're)\s+(?:on|running)\b|\bare\s+you\s+(?:on|running)\s+(?:the\s+)?(?:latest|newest|new|current)\b/iu;
+const VERSION_CLAIM = /\bv?\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?\b/gu;
+/**
+ * A natural question about the Butler's own version must be answered from a fresh
+ * install-state read. After an upgrade the Butler once answered "Just checked the live
+ * state: 0.1.0-alpha.841" from earlier conversation while it was running 845, with no
+ * tool call at all. Unlike the explicit install-state contract, the wording stays free:
+ * only the version it states is checked against the read.
+ */
+function sanctuaryVersionQuestionRequiredToolCalls(request, advertisedToolNames) {
+    const normalizedRequest = request.normalize("NFKC").replace(/[‘’]/gu, "'");
+    if (!advertisedToolNames.includes(TOOL_NAME) || REQUEST.test(normalizedRequest) || !VERSION_QUESTION.test(normalizedRequest))
+        return undefined;
+    let current;
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.sanctuary_version_question_required",
+        message: "a question about the running version requires a fresh install-state read",
+        meta: { requiredToolName: TOOL_NAME },
+    });
+    return {
+        names: [TOOL_NAME],
+        retryMessage: "Call sanctuary_get_install_state with empty arguments now, then state the version from that fresh result, not from earlier conversation.",
+        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 "Call sanctuary_get_install_state and state the version from that fresh result.";
+            const known = new Set([current.runtimePackageVersion, current.packagedBundleVersion, ...(current.liveBundleVersion ? [current.liveBundleVersion] : [])].map((version) => version.replace(/^v/u, "")));
+            const claimed = [...answer.normalize("NFKC").matchAll(VERSION_CLAIM)].map((match) => match[0].replace(/^v/u, ""));
+            if (claimed.length === 0)
+                return `State the running version from the fresh result: ${current.runtimePackageVersion}.`;
+            const stale = claimed.filter((version) => !known.has(version));
+            return stale.length === 0 ? undefined : `The fresh install-state result says ${current.runtimePackageVersion}; do not state ${stale.join(", ")} as the current version.`;
+        },
+    };
+}

package/dist/senses/sanctuary-interactive-control.js

@@ -0,0 +1,410 @@
+"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.proveSanctuaryAttemptedRecoveryWithoutRetry = proveSanctuaryAttemptedRecoveryWithoutRetry;
+exports.executeSanctuaryInteractiveEngine = executeSanctuaryInteractiveEngine;
+exports.createSanctuaryInteractiveControl = createSanctuaryInteractiveControl;
+exports.sanctuaryInteractiveControlReady = sanctuaryInteractiveControlReady;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_net_1 = require("node:net");
+const path = __importStar(require("node:path"));
+const approval_store_1 = require("../heart/approval-store");
+const tool_approval_1 = require("../heart/tool-approval");
+const runtime_1 = require("../nerves/runtime");
+const telegram_client_1 = require("./telegram-client");
+const SHA256 = /^[0-9a-f]{64}$/u;
+const MAX_CONTROL_REQUEST = 16 * 1024;
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function exactKeys(value, keys, label) {
+    if (JSON.stringify(Object.keys(value).sort()) !== JSON.stringify([...keys].sort()))
+        throw new Error(`${label} shape is invalid`);
+}
+function sha256(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value, "utf8").digest("hex");
+}
+function exactApproval(projections) {
+    const matches = projections.filter(({ approval }) => approval.toolName === "unraid_restart_container" && approval.arguments.container === "calibre-web");
+    if (matches.length !== 1)
+        throw new Error("interactive production approval is absent or ambiguous");
+    return matches[0];
+}
+function exactPending(records, approvalId) {
+    const validCallback = (value) => typeof value === "string" && Buffer.byteLength(value) >= 1 && Buffer.byteLength(value) <= 64;
+    const matches = records.filter((record) => record.approvalId === approvalId && record.deliveryState === "bound" && record.messageId !== null
+        && validCallback(record.approveCallbackData) && validCallback(record.denyCallbackData));
+    if (matches.length !== 1)
+        throw new Error("interactive production pending approval is absent or ambiguous");
+    return matches[0];
+}
+function exactTerminalTombstone(records, approvalId) {
+    const validCallback = (value) => typeof value === "string" && Buffer.byteLength(value) >= 1 && Buffer.byteLength(value) <= 64;
+    const matches = records.filter((record) => record.approvalId === approvalId && record.deliveryState === "terminal_tombstone" && record.messageId !== null
+        && validCallback(record.approveCallbackData) && validCallback(record.denyCallbackData)
+        && record.expiryObservation?.schemaVersion === "telegram-approval-expiry-observation-v1"
+        && record.expiryObservation.deadlineAt === record.expiresAt && Number.isSafeInteger(record.expiryObservation.observedAt)
+        && record.expiryObservation.observedAt >= record.expiresAt && typeof record.expiryObservation.evidenceMac === "string" && SHA256.test(record.expiryObservation.evidenceMac)
+        && Number.isSafeInteger(record.terminalizedAt) && Number(record.terminalizedAt) >= record.expiryObservation.observedAt);
+    if (matches.length !== 1)
+        throw new Error("interactive production terminal tombstone is absent or ambiguous");
+    return matches[0];
+}
+function pendingDigest(record) {
+    return sha256(JSON.stringify({ approvalId: record.approvalId, messageId: record.messageId, deliveryState: record.deliveryState, approveCallbackData: record.approveCallbackData, denyCallbackData: record.denyCallbackData, expiresAt: record.expiresAt }));
+}
+function proveSanctuaryAttemptedRecoveryWithoutRetry(agentRoot, scenarioHandleDigest, approval) {
+    if (!SHA256.test(scenarioHandleDigest))
+        throw new Error("attempted recovery scenario is invalid");
+    const databaseRoot = path.join(agentRoot, "state", "acceptance", "attempted-recovery-probes");
+    (0, node_fs_1.mkdirSync)(databaseRoot, { recursive: true, mode: 0o700 });
+    const databasePath = path.join(databaseRoot, `${scenarioHandleDigest}.sqlite`);
+    if ((0, node_fs_1.existsSync)(databasePath))
+        throw new Error("attempted recovery proof requires inspect-before-retry");
+    const instant = new Date("2026-08-21T00:00:00.000Z");
+    const first = (0, approval_store_1.openApprovalStore)({ databasePath, now: () => instant });
+    const ownerId = "acceptance-attempted-recovery";
+    const toolCallId = `acceptance-${approval.toolCallId}`;
+    const frozenAssistantMessage = structuredClone(approval.frozenAssistantMessage);
+    const toolCalls = frozenAssistantMessage.tool_calls;
+    if (!Array.isArray(toolCalls) || toolCalls.length !== 1 || !toolCalls[0] || typeof toolCalls[0] !== "object" || Array.isArray(toolCalls[0])) {
+        first.close();
+        throw new Error("attempted recovery frozen tool call is invalid");
+    }
+    toolCalls[0].id = toolCallId;
+    const prepared = first.prepare({
+        toolCallId, toolName: approval.toolName, arguments: approval.arguments,
+        schemaDigest: approval.schemaDigest, toolDigest: approval.toolDigest, policyDigest: approval.policyDigest, policyId: approval.policyId,
+        sessionKey: "acceptance:attempted-recovery", sessionPath: path.join(databaseRoot, `${scenarioHandleDigest}.session.json`),
+        baseSessionRevision: approval.baseSessionRevision, checkpointDigest: approval.checkpointDigest,
+        requesterId: "acceptance-probe", transport: "telegram", transportUserId: "acceptance-probe", transportChatId: "acceptance-probe",
+        expiresAt: "2099-01-01T00:00:00.000Z", frozenAssistantMessage,
+    });
+    first.activate({ approvalId: prepared.record.approvalId, checkpointDigest: prepared.record.checkpointDigest, suspendedSessionRevision: approval.suspendedSessionRevision });
+    first.bindPrompt({ approvalId: prepared.record.approvalId, transport: "telegram", transportChatId: "acceptance-probe", transportMessageId: "acceptance-message" });
+    const claimed = first.decide({
+        approvalId: prepared.record.approvalId, decisionToken: prepared.decisionToken, decision: "approve", requesterId: "acceptance-probe",
+        transport: "telegram", transportUserId: "acceptance-probe", transportChatId: "acceptance-probe", transportMessageId: "acceptance-message",
+        sessionKey: "acceptance:attempted-recovery", ownerId,
+    });
+    const attempted = first.markAttempted({ approvalId: claimed.approvalId, ownerId, epoch: claimed.epoch });
+    first.close();
+    const attemptedRecordDigest = sha256(JSON.stringify(attempted));
+    const reopened = (0, approval_store_1.openApprovalStore)({ databasePath, now: () => instant });
+    const durableAttempted = reopened.read(attempted.approvalId);
+    if (!durableAttempted || durableAttempted.state !== "attempted") {
+        reopened.close();
+        throw new Error("attempted recovery record was not durable across reopen");
+    }
+    const recovered = (0, tool_approval_1.recoverAttemptedApproval)({ approvalStore: reopened, approvalId: durableAttempted.approvalId });
+    let retryCount = 0;
+    try {
+        (0, tool_approval_1.recoverAttemptedApproval)({ approvalStore: reopened, approvalId: durableAttempted.approvalId });
+        retryCount += 1;
+    }
+    catch { /* expected */ }
+    reopened.close();
+    return { observed: recovered.state === "attempted_indeterminate", retryCount, reopened: true, attemptedRecordDigest, recoveredRecordDigest: sha256(JSON.stringify(recovered)) };
+}
+async function executeSanctuaryInteractiveEngine(raw, deps) {
+    const payload = object(raw, "interactive runtime payload");
+    exactKeys(payload, ["operation", "label", "scenarioHandleDigest"], "interactive runtime payload");
+    const operation = payload.operation;
+    const label = payload.label;
+    const scenarioHandleDigest = payload.scenarioHandleDigest;
+    if (typeof scenarioHandleDigest !== "string" || !SHA256.test(scenarioHandleDigest)
+        || !["unit-16k-timeout-stale", "unit-16l-duplicate-callback", "unit-16m-restart-continuation"].includes(label)
+        || !["drive_timeout_stale", "drive_duplicate_callbacks", "prepare_restart_continuation", "reconcile_restart_continuation"].includes(String(operation))
+        || (operation === "drive_timeout_stale") !== (label === "unit-16k-timeout-stale")
+        || (operation === "drive_duplicate_callbacks") !== (label === "unit-16l-duplicate-callback"))
+        throw new Error("interactive runtime operation binding is invalid");
+    const before = exactApproval(deps.readApprovals(scenarioHandleDigest));
+    if (!before.approval.suspendedSessionRevision)
+        throw new Error("interactive production approval checkpoint is unavailable");
+    if (operation === "drive_timeout_stale") {
+        if (before.approval.state === "proposed") {
+            exactPending(deps.readPending(), before.approval.approvalId);
+            return { state: "waiting" };
+        }
+        if (before.approval.state !== "expired" || before.approval.epoch !== 0)
+            throw new Error("timeout stale approval is not expired without a claim");
+        const captured = exactTerminalTombstone(deps.readPending(), before.approval.approvalId);
+        const session = await deps.createSession();
+        try {
+            const queryId = (0, node_crypto_1.randomBytes)(18).toString("base64url");
+            const result = await session.handle({ callbackData: captured.approveCallbackData, queryId, messageId: captured.messageId });
+            const after = exactApproval(deps.readApprovals(scenarioHandleDigest));
+            const promptTerminal = !session.pendingApprovalIds().includes(before.approval.approvalId);
+            if (!result.handled || result.accepted || result.reason !== "stale_callback" || after.approval.state !== "expired" || after.approval.epoch !== 0 || !promptTerminal) {
+                throw new Error("timeout stale callback proof failed");
+            }
+            return {
+                schemaVersion: "sanctuary-timeout-stale-driver-receipt-v1", phase: "complete", label, scenarioHandleDigest,
+                approvalIdDigest: sha256(before.approval.approvalId), checkpointDigest: before.approval.checkpointDigest,
+                suspendedSessionRevisionDigest: sha256(before.approval.suspendedSessionRevision), approvalEpochBefore: before.approval.epoch,
+                callbackAttempts: 1, distinctQueryCount: 1, callbackDataDigest: sha256(captured.approveCallbackData),
+                settledCount: 1, claimCount: 0, mutationCount: 0, staleAcknowledged: true, promptTerminal,
+            };
+        }
+        finally {
+            session.close();
+        }
+    }
+    if (before.approval.state !== "proposed")
+        throw new Error("interactive production approval is not currently proposed");
+    const pending = exactPending(deps.readPending(), before.approval.approvalId);
+    const common = { approvalIdDigest: sha256(before.approval.approvalId), checkpointDigest: before.approval.checkpointDigest, suspendedSessionRevisionDigest: sha256(before.approval.suspendedSessionRevision), approvalEpochBefore: before.approval.epoch };
+    if (operation === "prepare_restart_continuation") {
+        const recovery = deps.proveIndeterminateRecovery(before.approval, scenarioHandleDigest);
+        if (!recovery.observed || recovery.retryCount !== 0 || !recovery.reopened
+            || !SHA256.test(recovery.attemptedRecordDigest) || !SHA256.test(recovery.recoveredRecordDigest)
+            || recovery.attemptedRecordDigest === recovery.recoveredRecordDigest)
+            throw new Error("isolated attempted recovery proof failed");
+        return {
+            schemaVersion: "sanctuary-interactive-driver-receipt-v2", phase: "prepared", label, scenarioHandleDigest, ...common,
+            pendingDigestBefore: pendingDigest(pending), indeterminateRecoveryObserved: true,
+            attemptedRecoveryReopened: true, attemptedRecordDigest: recovery.attemptedRecordDigest, recoveredRecordDigest: recovery.recoveredRecordDigest,
+        };
+    }
+    const session = await deps.createSession();
+    try {
+        if (operation === "drive_duplicate_callbacks") {
+            const queryIds = [(0, node_crypto_1.randomBytes)(18).toString("base64url"), (0, node_crypto_1.randomBytes)(18).toString("base64url")];
+            let arrivals = 0;
+            let release;
+            const barrier = new Promise((resolve) => { release = resolve; });
+            const invoke = async (queryId) => { arrivals += 1; if (arrivals === 2)
+                release(); await barrier; return session.handle({ callbackData: pending.approveCallbackData, queryId, messageId: pending.messageId }); };
+            const results = await Promise.all(queryIds.map(invoke));
+            const after = exactApproval(deps.readApprovals(scenarioHandleDigest));
+            const stale = await session.handle({ callbackData: pending.approveCallbackData, queryId: (0, node_crypto_1.randomBytes)(18).toString("base64url"), messageId: pending.messageId });
+            return { schemaVersion: "sanctuary-interactive-driver-receipt-v2", phase: "complete", label, scenarioHandleDigest, ...common, callbackAttempts: 2, distinctQueryCount: new Set(queryIds).size, callbackDataDigest: sha256(pending.approveCallbackData), barrierObserved: arrivals === 2, settledCount: results.filter(({ handled }) => handled).length, claimCount: after.approval.epoch === before.approval.epoch + 1 ? 1 : 0, mutationCount: after.approval.state === "succeeded" ? 1 : 0, staleReplayAttempts: 1, staleReplaySettled: stale.handled, staleReplayMutationCount: 0, promptTerminal: !session.pendingApprovalIds().includes(before.approval.approvalId), writeCredentialObserved: deps.writeCredentialObserved() };
+        }
+        const result = await session.handle({ callbackData: pending.approveCallbackData, queryId: (0, node_crypto_1.randomBytes)(18).toString("base64url"), messageId: pending.messageId });
+        const after = exactApproval(deps.readApprovals(scenarioHandleDigest));
+        if (!after.continuation || after.approval.state !== "succeeded")
+            throw new Error("restart continuation did not complete");
+        return { approvalEpochAfterRestart: before.approval.epoch, continuationEpochAfter: after.continuation.continuationEpoch, pendingDigestAfter: pendingDigest(pending), pendingRestored: true, callbackAttempts: 1, mutationCount: result.accepted ? 1 : 0, indeterminateRetryCount: 0 };
+    }
+    finally {
+        session.close();
+    }
+}
+function createSanctuaryInteractiveControl(options) {
+    const socketPath = path.join(options.agentRoot, "state", "acceptance", "telegram-control.sock");
+    const runRequest = options.runRequest ?? (async (operation) => operation());
+    let server;
+    let endpoint;
+    let startPromise;
+    let stopPromise;
+    let updateId = 2_100_000_000;
+    const readEndpoint = () => (0, node_fs_1.lstatSync)(socketPath, { bigint: true, throwIfNoEntry: false });
+    // Socket mtime, unlike ctime, survives permission-only changes.
+    const matches = (observed, current) => current !== undefined && current.isSocket() && current.dev === observed.dev && current.ino === observed.ino
+        && current.birthtimeNs === observed.birthtimeNs && current.mtimeNs === observed.mtimeNs;
+    const stopListener = async () => {
+        const active = server;
+        if (!active)
+            return;
+        if (active.listening) {
+            const current = readEndpoint();
+            // Native Server.close() also unlinks its pathname, so ownership must precede it.
+            if (current && (!endpoint || !matches(endpoint, current)))
+                throw new Error("Sanctuary interactive control socket ownership was replaced");
+            await new Promise((resolve, reject) => active.close((error) => error ? reject(error) : resolve()));
+        }
+        server = undefined;
+        endpoint = undefined;
+    };
+    return {
+        socketPath,
+        start() {
+            if (startPromise)
+                return startPromise;
+            const previousStop = stopPromise;
+            stopPromise = undefined;
+            const starting = (async () => {
+                if (previousStop)
+                    await previousStop;
+                if (server) {
+                    if (endpoint && matches(endpoint, readEndpoint()))
+                        return;
+                    await stopListener();
+                }
+                (0, node_fs_1.mkdirSync)(path.dirname(socketPath), { recursive: true, mode: 0o700 });
+                const previous = readEndpoint();
+                if (previous) {
+                    if (!previous.isSocket())
+                        throw new Error("Sanctuary interactive control endpoint is not a socket");
+                    await new Promise((resolve, reject) => {
+                        const socket = (0, node_net_1.createConnection)(socketPath);
+                        const finish = (error) => { socket.destroy(); if (error)
+                            reject(error);
+                        else
+                            resolve(); };
+                        socket.setTimeout(1_000, () => finish(new Error("Sanctuary interactive control ownership probe timed out")));
+                        socket.once("connect", () => finish(new Error("Sanctuary interactive control endpoint has another live listener")));
+                        socket.once("error", (error) => finish(error.code === "ECONNREFUSED" ? undefined : error));
+                    });
+                    const current = readEndpoint();
+                    if (!matches(previous, current) || current.ctimeNs !== previous.ctimeNs)
+                        throw new Error("Sanctuary interactive control endpoint was replaced during the ownership probe");
+                    (0, node_fs_1.unlinkSync)(socketPath);
+                }
+                server = (0, node_net_1.createServer)({ allowHalfOpen: true }, (connection) => {
+                    let raw = "";
+                    connection.setEncoding("utf8");
+                    connection.on("error", () => undefined);
+                    connection.on("data", (chunk) => { raw += chunk; if (Buffer.byteLength(raw) > MAX_CONTROL_REQUEST)
+                        connection.destroy(); });
+                    connection.on("end", () => {
+                        void runRequest(async () => {
+                            try {
+                                (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.sanctuary_interactive_control_request", message: "Sanctuary interactive control request received", meta: { bytes: Buffer.byteLength(raw) } });
+                                const parsed = object(JSON.parse(raw), "interactive control request");
+                                if (parsed.operation === "interactive_runtime_ready") {
+                                    exactKeys(parsed, ["operation", "label", "scenarioHandleDigest"], "interactive readiness request");
+                                    if (parsed.label !== "unit-16m-restart-continuation" || typeof parsed.scenarioHandleDigest !== "string" || !SHA256.test(parsed.scenarioHandleDigest))
+                                        throw new Error("interactive readiness binding is invalid");
+                                    connection.end(`${JSON.stringify({ ok: true, result: { ready: true } })}\n`);
+                                    return;
+                                }
+                                const result = await executeSanctuaryInteractiveEngine(parsed, {
+                                    agentRoot: options.agentRoot,
+                                    readApprovals: (digest) => (0, approval_store_1.readApprovalsByScenarioHandleDigest)(path.join(options.agentRoot, "state", "approvals", "approvals.sqlite"), digest),
+                                    readPending: () => new telegram_client_1.FileTelegramPendingApprovalStore(path.join(options.agentRoot, "state", "approvals", "telegram-pending.json")).load(),
+                                    createSession: async () => ({
+                                        handle: ({ callbackData, queryId, messageId }) => runRequest(() => options.transport.handleUpdate({
+                                            update_id: updateId++,
+                                            callback_query: {
+                                                id: queryId,
+                                                from: { id: Number(options.authorizedUserId) },
+                                                data: callbackData,
+                                                message: {
+                                                    message_id: Number(messageId),
+                                                    chat: { id: Number(options.authorizedChatId) },
+                                                },
+                                            },
+                                        })),
+                                        pendingApprovalIds: () => options.transport.listPendingDeliveries().map(({ approvalId }) => approvalId),
+                                        close: () => undefined,
+                                    }),
+                                    proveIndeterminateRecovery: (approval, digest) => proveSanctuaryAttemptedRecoveryWithoutRetry(options.agentRoot, digest, approval),
+                                    writeCredentialObserved: () => /credential|api[_-]?key|token|secret/iu.test(raw),
+                                });
+                                connection.end(`${JSON.stringify({ ok: true, result })}\n`);
+                            }
+                            catch {
+                                connection.end(`${JSON.stringify({ ok: false, error: "interactive runtime operation failed" })}\n`);
+                            }
+                        }).catch(() => { if (!connection.destroyed)
+                            connection.end(`${JSON.stringify({ ok: false, error: "interactive runtime operation failed" })}\n`); });
+                    });
+                });
+                const active = server;
+                try {
+                    await new Promise((resolve, reject) => {
+                        const onError = (error) => { active.off("listening", onListening); reject(error); };
+                        const onListening = () => {
+                            active.off("error", onError);
+                            try {
+                                if (!endpoint || !matches(endpoint, readEndpoint()))
+                                    throw new Error("Sanctuary interactive control socket ownership was replaced during startup");
+                                resolve();
+                            }
+                            catch (error) {
+                                reject(error);
+                            }
+                        };
+                        active.once("error", onError);
+                        active.once("listening", onListening);
+                        try {
+                            active.listen(socketPath);
+                            if (active.listening) {
+                                endpoint = readEndpoint();
+                                if (!endpoint?.isSocket())
+                                    throw new Error("Sanctuary interactive control startup ownership is unproven");
+                                (0, node_fs_1.chmodSync)(socketPath, 0o600);
+                                endpoint = readEndpoint();
+                            }
+                        }
+                        catch (error) {
+                            active.off("error", onError);
+                            onError(error);
+                        }
+                    });
+                }
+                catch (error) {
+                    try {
+                        await stopListener();
+                    }
+                    catch (cleanupError) {
+                        throw new AggregateError([error, cleanupError], "Sanctuary interactive control startup and ownership cleanup failed");
+                    }
+                    throw error;
+                }
+            })().finally(() => { if (startPromise === starting)
+                startPromise = undefined; });
+            startPromise = starting;
+            return starting;
+        },
+        stop() {
+            if (stopPromise)
+                return stopPromise;
+            const starting = startPromise;
+            startPromise = undefined;
+            const stopping = (async () => {
+                if (starting)
+                    await starting;
+                await stopListener();
+            })().finally(() => { if (stopPromise === stopping)
+                stopPromise = undefined; });
+            stopPromise = stopping;
+            return stopping;
+        },
+    };
+}
+async function sanctuaryInteractiveControlReady(socketPath, timeoutMs = 1_000) {
+    return new Promise((resolve) => {
+        const socket = (0, node_net_1.createConnection)(socketPath);
+        const finish = (ready) => { socket.destroy(); resolve(ready); };
+        socket.setTimeout(timeoutMs, () => finish(false));
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+    });
+}