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

package/dist/senses/telegram.js

@@ -0,0 +1,2045 @@
+"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.createSabQueueProtectiveStateVerifier = createSabQueueProtectiveStateVerifier;
+exports.telegramAcceptanceAuditOwnerDigest = telegramAcceptanceAuditOwnerDigest;
+exports.sanctuaryTelegramTurnReceiptDigest = sanctuaryTelegramTurnReceiptDigest;
+exports.sanctuaryTelegramTurnReceiptMac = sanctuaryTelegramTurnReceiptMac;
+exports.sanctuaryTelegramAuditLifecycleMac = sanctuaryTelegramAuditLifecycleMac;
+exports.sanctuaryTelegramUnauthorizedDropMac = sanctuaryTelegramUnauthorizedDropMac;
+exports.sanctuaryTelegramApprovalEvidenceMac = sanctuaryTelegramApprovalEvidenceMac;
+exports.telegramBotIdFromToken = telegramBotIdFromToken;
+exports.readOrCreateTelegramIdentityKey = readOrCreateTelegramIdentityKey;
+exports.opaqueTelegramSubject = opaqueTelegramSubject;
+exports.migrateTelegramFriendIdentity = migrateTelegramFriendIdentity;
+exports.migrateTelegramSessionIdentity = migrateTelegramSessionIdentity;
+exports.parseTelegramSenseCredentials = parseTelegramSenseCredentials;
+exports.createTelegramSenseApp = createTelegramSenseApp;
+exports.loadTelegramSenseCredentials = loadTelegramSenseCredentials;
+exports.createProductionTelegramRelationshipComposition = createProductionTelegramRelationshipComposition;
+exports.startTelegramSenseApp = startTelegramSenseApp;
+exports.sendTelegramExternalEventDecision = sendTelegramExternalEventDecision;
+exports.sendTelegramAwaitFollowUp = sendTelegramAwaitFollowUp;
+const node_crypto_1 = require("node:crypto");
+const node_async_hooks_1 = require("node:async_hooks");
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const friends_1 = require("@ouro.bot/friends");
+const identity_1 = require("../heart/identity");
+const sanctuary_acceptance_marker_1 = require("../heart/daemon/sanctuary-acceptance-marker");
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const runtime_1 = require("../nerves/runtime");
+const nerves_1 = require("../nerves");
+const sanctuary_interactive_control_1 = require("./sanctuary-interactive-control");
+const sanctuary_runtime_1 = require("./sanctuary-runtime");
+const sanctuary_sab_1 = require("./sanctuary-sab");
+const sanctuary_download_credit_presentation_1 = require("./sanctuary-download-credit-presentation");
+const shared_turn_1 = require("./shared-turn");
+const config_1 = require("../heart/config");
+const telegram_client_1 = require("./telegram-client");
+const sanctuary_runtime_2 = require("./sanctuary-runtime");
+const sanctuary_full_visibility_contract_1 = require("./sanctuary-full-visibility-contract");
+const sanctuary_install_state_contract_1 = require("./sanctuary-install-state-contract");
+const sanctuary_media_catalog_contract_1 = require("./sanctuary-media-catalog-contract");
+const sanctuary_storage_optimization_contract_1 = require("./sanctuary-storage-optimization-contract");
+const sanctuary_grounding_1 = require("./sanctuary-grounding");
+const telegram_approval_runtime_1 = require("./telegram-approval-runtime");
+const telegram_audit_ledger_1 = require("./telegram-audit-ledger");
+const session_events_1 = require("../heart/session-events");
+const router_1 = require("../heart/external-events/router");
+const session_transaction_1 = require("../mind/session-transaction");
+const approval_files_1 = require("../heart/approval-files");
+const approval_store_1 = require("../heart/approval-store");
+const tools_awaiting_1 = require("../repertoire/tools-awaiting");
+const obligations_1 = require("../arc/obligations");
+const orientation_frame_1 = require("../heart/orientation-frame");
+const render_1 = require("../heart/attachments/render");
+const telegram_attachments_1 = require("./telegram-attachments");
+const pending_1 = require("../mind/pending");
+const relationship_authorization_1 = require("../repertoire/relationship-authorization");
+const telegram_admission_1 = require("./telegram-admission");
+const telegram_effect_adapter_1 = require("./telegram-effect-adapter");
+const EMPTY_SHARED_TURN_DIAGNOSTIC = "(agent responded but response was empty)";
+function hasUserVisibleTurnResponse(response) {
+    const text = response.trim();
+    return text.length > 0 && text !== EMPTY_SHARED_TURN_DIAGNOSTIC;
+}
+function responseFallbackAfterDeliveries(result, successfulDeliveryCount) {
+    const failedTerminal = result.responseDeliveryFailure?.text ?? (result.responseCausalSessionEventId ? result.deliveryFailures.at(-1)?.text : undefined);
+    const response = failedTerminal ?? (successfulDeliveryCount === 0 && result.deliveryFailures.length === 0 ? result.response : "");
+    return hasUserVisibleTurnResponse(response) ? response : null;
+}
+function createFullVisibilityProgress() {
+    const progress = {};
+    return { progress, emptyResponseFallback: () => progress.fallback?.() };
+}
+function createSabQueueProtectiveStateVerifier(options = {}) {
+    let client = null;
+    return async (action) => {
+        client ??= (0, sanctuary_sab_1.createSanctuarySabClient)({ loadApiKey: options.loadApiKey ?? (() => (0, sanctuary_runtime_1.loadSanctuarySabApiKey)("sanctuary")), fetch: options.fetch, now: options.now });
+        const snapshot = await client.readQueue();
+        const paused = snapshot.paused;
+        const digest = (0, node_crypto_1.createHash)("sha256").update(`sabnzbd.queue.paused=${String(paused)}`).digest("hex");
+        const verified = action.action === "sabnzbd.pause" && paused && action.verification.verified && action.verification.digest === digest;
+        return { verified, reference: `sabnzbd.queue.paused:${digest}:${snapshot.observedAt}` };
+    };
+}
+const APPROVAL_EXPIRY_RECONCILE_INTERVAL_MS = 1_000;
+const TELEGRAM_SUBJECT_DOMAIN = "ouroboros.telegram.subject.v1";
+const TELEGRAM_IDENTITY_KEY = /^[A-Za-z0-9_-]{43}$/u;
+const TELEGRAM_SUBJECT = /^tg_[A-Za-z0-9_-]{43}$/u;
+const TELEGRAM_SUBJECT_INDEX = "identity-subjects.json";
+const TELEGRAM_ACCEPTANCE_AUDIT_EVENTS = new Set([
+    "approval.acceptance_continuation_transition",
+    "approval.acceptance_transition",
+    "senses.sanctuary_health_delivered",
+    "senses.sanctuary_read_receipt",
+    "senses.telegram_approved_restart_end",
+    "senses.telegram_approved_restart_error",
+    "senses.telegram_approved_restart_start",
+    "senses.telegram_approval_continuation_delivered",
+    "senses.telegram_approval_prompt_bound",
+    "senses.telegram_turn_end",
+    "senses.telegram_turn_error",
+    "senses.telegram_turn_start",
+    "telegram.approval_prompt_terminalized",
+    "telegram.approval_expiry_observed",
+    "telegram.approval_stale_callback_settled",
+    "telegram.callback_recovery_settled",
+    "telegram.callback_settled",
+    "telegram.update_dropped",
+]);
+const telegramAcceptanceAuditOwner = new node_async_hooks_1.AsyncLocalStorage();
+const telegramAcceptanceAuditScenario = new node_async_hooks_1.AsyncLocalStorage();
+const telegramAcceptanceAuditExplicitCommit = new node_async_hooks_1.AsyncLocalStorage();
+const telegramAcceptanceAudits = new Map();
+const TELEGRAM_TURN_RECEIPT_DOMAINS = {
+    "sanctuary-telegram-turn-receipt-v3": "ouroboros.telegram.turn-receipt.v3",
+    "sanctuary-telegram-turn-receipt-v4": "ouroboros.telegram.turn-receipt.v4",
+};
+const TELEGRAM_TURN_LEDGER_MAX_BYTES = 4 * 1024 * 1024;
+const TELEGRAM_TURN_LEDGER_MAX_ROWS = 500;
+const TELEGRAM_TURN_LEDGER_MAX_ROW_BYTES = 16 * 1024;
+const telegramTurnLedgerTails = new Map();
+function telegramAcceptanceAuditOwnerDigest(identityKey, agentName, root) {
+    return (0, node_crypto_1.createHmac)("sha256", identityKey)
+        .update(`ouroboros.telegram.acceptance-audit-owner.v1\0${agentName}\0${root}`, "utf8")
+        .digest("hex");
+}
+function acquireTelegramAcceptanceAudit(root, agentName, identityKey, privateValues, scenarioHandleDigest, releaseHook, maxBytes) {
+    const existing = telegramAcceptanceAudits.get(root);
+    if (existing) {
+        if (existing.identityKey !== identityKey)
+            throw new Error("Telegram acceptance audit identity changed while active");
+        if (existing.scenarioHandleDigest !== scenarioHandleDigest)
+            throw new Error("Telegram acceptance audit scenario changed while active");
+        existing.ledger.assertHealthy();
+        existing.references += 1;
+        return { ledger: existing.ledger, ownerDigest: existing.ownerDigest, scenarioHandleDigest: existing.scenarioHandleDigest, release: () => {
+                existing.references -= 1;
+                if (existing.references === 0) {
+                    try {
+                        existing.unregister();
+                    }
+                    finally {
+                        telegramAcceptanceAudits.delete(root);
+                    }
+                    releaseHook?.();
+                }
+            } };
+    }
+    const ledger = (0, telegram_audit_ledger_1.createTelegramAuditLedger)({ root, identityKey, privateValues, _maxBytes: maxBytes });
+    const ownerDigest = telegramAcceptanceAuditOwnerDigest(identityKey, agentName, root);
+    let record;
+    const unregister = (0, nerves_1.registerGlobalLogSink)((event) => {
+        if (!TELEGRAM_ACCEPTANCE_AUDIT_EVENTS.has(event.event))
+            return;
+        if (telegramAcceptanceAuditExplicitCommit.getStore())
+            return;
+        const explicitOwner = event.meta.acceptanceAuditOwnerDigest;
+        const contextualOwner = telegramAcceptanceAuditOwner.getStore();
+        if (explicitOwner !== ownerDigest && contextualOwner !== ownerDigest)
+            return;
+        const scenario = event.meta.scenarioHandleDigest;
+        if (typeof scenario !== "string" || !/^[0-9a-f]{64}$/u.test(scenario) || record.scenarioHandleDigest !== scenario) {
+            ledger.poison(new Error("Telegram acceptance audit scenario ownership drift"));
+        }
+        ledger.append(event);
+    });
+    record = { agentName, identityKey, ledger, ownerDigest, references: 1, scenarioHandleDigest, unregister };
+    telegramAcceptanceAudits.set(root, record);
+    return { ledger, ownerDigest, scenarioHandleDigest, release: () => {
+            record.references -= 1;
+            if (record.references === 0) {
+                try {
+                    record.unregister();
+                }
+                finally {
+                    telegramAcceptanceAudits.delete(root);
+                }
+                releaseHook?.();
+            }
+        } };
+}
+function sanctuaryTelegramTurnReceiptDigest(identityKey, schemaVersion, purpose, value) {
+    return (0, node_crypto_1.createHmac)("sha256", identityKey).update(`${TELEGRAM_TURN_RECEIPT_DOMAINS[schemaVersion]}\0${purpose}\0${value}`, "utf8").digest("hex");
+}
+function canonicalReceiptJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalReceiptJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).filter((key) => record[key] !== undefined).sort().map((key) => `${JSON.stringify(key)}:${canonicalReceiptJson(record[key])}`).join(",")}}`;
+    }
+    const rendered = JSON.stringify(value);
+    if (rendered === undefined)
+        throw new Error("Telegram receipt contains an unsupported value");
+    return rendered;
+}
+function sanctuaryTelegramTurnReceiptMac(identityKey, value) {
+    const unsigned = Object.fromEntries(Object.entries(value).filter(([key]) => key !== "receiptMac"));
+    return sanctuaryTelegramTurnReceiptDigest(identityKey, "sanctuary-telegram-turn-receipt-v4", "receipt", canonicalReceiptJson(unsigned));
+}
+function sanctuaryTelegramAuditLifecycleMac(identityKey, schemaVersion, event, meta) {
+    const unsigned = Object.fromEntries(Object.entries(meta).filter(([key]) => key !== "lifecycleMac"));
+    return sanctuaryTelegramTurnReceiptDigest(identityKey, schemaVersion, "audit-lifecycle", canonicalReceiptJson({ event, meta: unsigned }));
+}
+function sanctuaryTelegramUnauthorizedDropMac(identityKey, schemaVersion, value) {
+    return sanctuaryTelegramTurnReceiptDigest(identityKey, schemaVersion, "unauthorized-drop", canonicalReceiptJson(value));
+}
+function sanctuaryTelegramApprovalEvidenceMac(identityKey, event, meta) {
+    const unsigned = Object.fromEntries(Object.entries(meta).filter(([key]) => key !== "evidenceMac"));
+    return sanctuaryTelegramTurnReceiptDigest(identityKey, "sanctuary-telegram-turn-receipt-v3", "approval-evidence", canonicalReceiptJson({ event, meta: unsigned }));
+}
+function sameTelegramLedgerMetadata(left, right) {
+    return left.dev === right.dev
+        && left.ino === right.ino
+        && left.mode === right.mode
+        && left.nlink === right.nlink
+        && left.uid === right.uid
+        && left.gid === right.gid
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs;
+}
+function readStableBoundedTelegramLedger(filePath, afterPreReadStat) {
+    let handle;
+    try {
+        handle = (0, node_fs_1.openSync)(filePath, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        const before = (0, node_fs_1.fstatSync)(handle, { bigint: true });
+        if (!before.isFile())
+            throw new Error("Telegram turn receipt ledger must be a regular file");
+        if (before.size > BigInt(TELEGRAM_TURN_LEDGER_MAX_BYTES))
+            throw new Error("Telegram turn receipt ledger exceeds its bound");
+        afterPreReadStat?.(filePath);
+        const expectedBytes = Number(before.size);
+        const content = Buffer.allocUnsafe(expectedBytes);
+        let offset = 0;
+        while (offset < expectedBytes) {
+            const bytesRead = (0, node_fs_1.readSync)(handle, content, offset, expectedBytes - offset, offset);
+            if (bytesRead === 0)
+                throw new Error("Telegram turn receipt ledger changed during read");
+            offset += bytesRead;
+        }
+        const overflow = Buffer.allocUnsafe(1);
+        const overflowBytes = (0, node_fs_1.readSync)(handle, overflow, 0, 1, expectedBytes);
+        const after = (0, node_fs_1.fstatSync)(handle, { bigint: true });
+        const pathAfter = (0, node_fs_1.lstatSync)(filePath, { bigint: true });
+        if (overflowBytes !== 0 || !sameTelegramLedgerMetadata(before, after)
+            || !pathAfter.isFile() || pathAfter.dev !== before.dev || pathAfter.ino !== before.ino) {
+            throw new Error("Telegram turn receipt ledger changed during read");
+        }
+        return content.toString("utf8");
+    }
+    finally {
+        (0, node_fs_1.closeSync)(handle);
+    }
+}
+function validateSanctuaryTurnReceipt(value) {
+    const grounded = value.schemaVersion === "sanctuary-telegram-turn-receipt-v4";
+    const exactKeys = ["completedAt", "deliveries", "deliveryCount", "errorCategory", "providerInvocationCount", "responseDigest", "scenarioHandleDigest", "schemaVersion", "sequenceDigest", "status", "toolInvocationCount", "toolResultDigests", "updateDigest", ...(grounded ? ["receiptMac", "toolGroundings"] : [])].sort();
+    const deliveries = value.deliveries;
+    if (JSON.stringify(Object.keys(value).sort()) !== JSON.stringify(exactKeys)
+        || (!grounded && value.schemaVersion !== "sanctuary-telegram-turn-receipt-v3")
+        || typeof value.scenarioHandleDigest !== "string" || !/^[0-9a-f]{64}$/u.test(value.scenarioHandleDigest)
+        || (value.status !== "success" && value.status !== "error")
+        || (value.status === "success"
+            ? value.errorCategory !== null
+            : typeof value.errorCategory !== "string" || value.errorCategory.length < 1 || value.errorCategory.length > 128)
+        || ![value.updateDigest, value.sequenceDigest, value.responseDigest].every((digest) => typeof digest === "string" && /^[0-9a-f]{64}$/u.test(digest))
+        || !Array.isArray(value.toolResultDigests) || value.toolResultDigests.length > 100 || !value.toolResultDigests.every((digest) => typeof digest === "string" && /^[0-9a-f]{64}$/u.test(digest))
+        || !Array.isArray(deliveries) || deliveries.length > 100 || !deliveries.every((delivery) => {
+        if (!delivery || typeof delivery !== "object" || Array.isArray(delivery))
+            return false;
+        const record = delivery;
+        return JSON.stringify(Object.keys(record).sort()) === JSON.stringify(grounded ? ["chunkDigest", "messageIdDigest", "redactedText", "utf16Units"] : ["chunkDigest", "messageIdDigest"])
+            && typeof record.chunkDigest === "string" && /^[0-9a-f]{64}$/u.test(record.chunkDigest)
+            && typeof record.messageIdDigest === "string" && /^[0-9a-f]{64}$/u.test(record.messageIdDigest)
+            && (!grounded || (typeof record.redactedText === "string" && record.redactedText.length === record.utf16Units && record.utf16Units <= 1_200));
+    })
+        || (grounded && (!Array.isArray(value.toolGroundings) || value.toolGroundings.length !== 1 || !value.toolGroundings.every((raw) => {
+            if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                return false;
+            const record = raw;
+            if (JSON.stringify(Object.keys(record).sort()) !== JSON.stringify(["facts", "groundingDigest", "observedAt", "resultDigest", "sourceIdentityDigest", "toolName"]) || (record.toolName !== "unraid_get_system" && record.toolName !== "unraid_get_storage")
+                || typeof record.resultDigest !== "string" || !/^[0-9a-f]{64}$/u.test(record.resultDigest) || typeof record.groundingDigest !== "string" || !/^[0-9a-f]{64}$/u.test(record.groundingDigest)
+                || typeof record.sourceIdentityDigest !== "string" || !/^[0-9a-f]{64}$/u.test(record.sourceIdentityDigest) || typeof record.observedAt !== "string" || !Number.isFinite(Date.parse(record.observedAt)) || new Date(Date.parse(record.observedAt)).toISOString() !== record.observedAt
+                || !record.facts || typeof record.facts !== "object" || Array.isArray(record.facts))
+                return false;
+            return (0, sanctuary_grounding_1.sanctuaryGroundingDigest)(record.facts) === record.groundingDigest && value.toolResultDigests.includes(record.resultDigest);
+        })))
+        || (grounded && (typeof value.receiptMac !== "string" || !/^[0-9a-f]{64}$/u.test(value.receiptMac)))
+        || ![value.providerInvocationCount, value.toolInvocationCount].every((count) => Number.isSafeInteger(count) && Number(count) >= 0 && Number(count) <= 1_000)
+        || !Number.isSafeInteger(value.deliveryCount) || value.deliveryCount !== deliveries.length
+        || typeof value.completedAt !== "string" || value.completedAt.length > 30 || !Number.isFinite(Date.parse(value.completedAt)) || new Date(Date.parse(value.completedAt)).toISOString() !== value.completedAt)
+        throw new Error("Telegram turn receipt ledger row is invalid");
+}
+async function appendSanctuaryTurnReceipt(agentRoot, receipt, afterPreReadStat) {
+    const filePath = path.join(agentRoot, "state", "acceptance", "telegram-turns.ndjson");
+    const previous = telegramTurnLedgerTails.get(filePath) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(() => {
+        (0, node_fs_1.mkdirSync)(path.dirname(filePath), { recursive: true, mode: 0o700 });
+        let existing = [];
+        const raw = readStableBoundedTelegramLedger(filePath, afterPreReadStat);
+        if (raw !== null) {
+            existing = raw.split("\n").filter(Boolean);
+            if (existing.length > TELEGRAM_TURN_LEDGER_MAX_ROWS || existing.some((line) => Buffer.byteLength(line) > TELEGRAM_TURN_LEDGER_MAX_ROW_BYTES))
+                throw new Error("Telegram turn receipt ledger is invalid");
+            for (const line of existing) {
+                validateSanctuaryTurnReceipt(JSON.parse(line));
+            }
+        }
+        validateSanctuaryTurnReceipt(receipt);
+        const serialized = JSON.stringify(receipt);
+        if (Buffer.byteLength(serialized) > TELEGRAM_TURN_LEDGER_MAX_ROW_BYTES)
+            throw new Error("Telegram turn receipt exceeds its bound");
+        const lines = [...existing, serialized].slice(-TELEGRAM_TURN_LEDGER_MAX_ROWS);
+        let aggregateBytes = lines.reduce((total, line) => total + Buffer.byteLength(line) + 1, 0);
+        while (aggregateBytes > TELEGRAM_TURN_LEDGER_MAX_BYTES && lines.length > 1) {
+            aggregateBytes -= Buffer.byteLength(lines.shift()) + 1;
+        }
+        const temporary = `${filePath}.tmp-${process.pid}-${(0, node_crypto_1.randomUUID)()}`;
+        (0, node_fs_1.writeFileSync)(temporary, `${lines.join("\n")}\n`, { mode: 0o600, flag: "wx" });
+        const handle = (0, node_fs_1.openSync)(temporary, "r");
+        try {
+            (0, node_fs_1.fsyncSync)(handle);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(handle);
+        }
+        (0, node_fs_1.renameSync)(temporary, filePath);
+        const directory = (0, node_fs_1.openSync)(path.dirname(filePath), "r");
+        try {
+            (0, node_fs_1.fsyncSync)(directory);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(directory);
+        }
+    });
+    telegramTurnLedgerTails.set(filePath, current);
+    try {
+        await current;
+    }
+    finally {
+        if (telegramTurnLedgerTails.get(filePath) === current)
+            telegramTurnLedgerTails.delete(filePath);
+    }
+}
+function requiredText(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`Telegram ${label} is missing`);
+    return value.trim();
+}
+function canonicalTelegramId(value, label) {
+    const text = requiredText(value, label);
+    if (!/^[1-9][0-9]*$/u.test(text))
+        throw new Error(`Telegram ${label} must be a canonical positive decimal string`);
+    return text;
+}
+function telegramBotIdFromToken(token) {
+    const match = /^([1-9][0-9]*):/u.exec(token.trim());
+    if (!match)
+        throw new Error("Telegram bot token does not expose a canonical numeric bot id");
+    return match[1];
+}
+function canonicalTelegramIdentityKey(value) {
+    const key = value.trim();
+    if (!TELEGRAM_IDENTITY_KEY.test(key) || Buffer.from(key, "base64url").length !== 32) {
+        throw new Error("Telegram opaque identity key is invalid");
+    }
+    return key;
+}
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : undefined;
+}
+function openSecureTelegramDirectory(directory, afterOpen) {
+    try {
+        const existing = (0, node_fs_1.lstatSync)(directory);
+        if (existing.isSymbolicLink())
+            throw new Error("Telegram state directory must not be a symbolic link");
+        if (!existing.isDirectory())
+            throw new Error("Telegram state directory is not a directory");
+    }
+    catch (error) {
+        if (errorCode(error) !== "ENOENT")
+            throw error;
+        (0, node_fs_1.mkdirSync)(directory, { recursive: true, mode: 0o700 });
+    }
+    const handle = (0, node_fs_1.openSync)(directory, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_DIRECTORY | node_fs_1.constants.O_NOFOLLOW);
+    try {
+        (0, node_fs_1.fchmodSync)(handle, 0o700);
+        afterOpen?.(handle);
+        const metadata = (0, node_fs_1.fstatSync)(handle);
+        if (!metadata.isDirectory() || (metadata.mode & 0o777) !== 0o700) {
+            throw new Error("Telegram state directory permissions are invalid");
+        }
+        return handle;
+    }
+    catch (error) {
+        (0, node_fs_1.closeSync)(handle);
+        throw error;
+    }
+}
+function readOrCreateTelegramIdentityKey(agentRoot, hooks = {}) {
+    const directory = path.join(agentRoot, "state", "senses", "telegram");
+    const keyPath = path.join(directory, "identity.key");
+    const directoryHandle = openSecureTelegramDirectory(directory, hooks.afterOpenDirectory);
+    const readKey = () => {
+        const handle = (0, node_fs_1.openSync)(keyPath, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NOFOLLOW);
+        try {
+            const metadata = (0, node_fs_1.fstatSync)(handle);
+            if (!metadata.isFile() || (metadata.mode & 0o777) !== 0o600)
+                throw new Error("Telegram opaque identity key permissions are invalid");
+            return canonicalTelegramIdentityKey((0, node_fs_1.readFileSync)(handle, "utf8"));
+        }
+        finally {
+            (0, node_fs_1.closeSync)(handle);
+        }
+    };
+    try {
+        try {
+            return readKey();
+        }
+        catch (error) {
+            if (errorCode(error) !== "ENOENT")
+                throw error;
+        }
+        const key = (0, node_crypto_1.randomBytes)(32).toString("base64url");
+        hooks.beforeCreate?.(keyPath);
+        const temporaryPath = path.join(directory, `.identity.key.${(0, node_crypto_1.randomBytes)(12).toString("base64url")}.tmp`);
+        let temporaryHandle;
+        try {
+            temporaryHandle = (0, node_fs_1.openSync)(temporaryPath, node_fs_1.constants.O_CREAT | node_fs_1.constants.O_EXCL | node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_NOFOLLOW, 0o600);
+            hooks.afterCreateTemporary?.(temporaryPath, keyPath);
+            (0, node_fs_1.writeFileSync)(temporaryHandle, `${key}\n`);
+            (0, node_fs_1.fsyncSync)(temporaryHandle);
+            (0, node_fs_1.closeSync)(temporaryHandle);
+            temporaryHandle = undefined;
+            hooks.beforePublish?.(temporaryPath, keyPath);
+            try {
+                (0, node_fs_1.linkSync)(temporaryPath, keyPath);
+            }
+            catch (error) {
+                if (errorCode(error) !== "EEXIST")
+                    throw error;
+                return readKey();
+            }
+            (0, node_fs_1.fsyncSync)(directoryHandle);
+            return key;
+        }
+        finally {
+            if (temporaryHandle !== undefined)
+                (0, node_fs_1.closeSync)(temporaryHandle);
+            if ((0, node_fs_1.existsSync)(temporaryPath))
+                (0, node_fs_1.unlinkSync)(temporaryPath);
+            (0, node_fs_1.fsyncSync)(directoryHandle);
+        }
+    }
+    finally {
+        (0, node_fs_1.closeSync)(directoryHandle);
+    }
+}
+function opaqueTelegramSubject(identityKey, botToken, authorizedUserId, authorizedChatId) {
+    const payload = [
+        TELEGRAM_SUBJECT_DOMAIN,
+        `bot:${botToken.length}:${botToken}`,
+        `user:${authorizedUserId.length}:${authorizedUserId}`,
+        `chat:${authorizedChatId.length}:${authorizedChatId}`,
+    ].join("\0");
+    return `tg_${(0, node_crypto_1.createHmac)("sha256", identityKey).update(payload, "utf8").digest("base64url")}`;
+}
+function readTelegramSubjectIndex(agentRoot, subject) {
+    const indexPath = path.join(agentRoot, "state", "senses", "telegram", TELEGRAM_SUBJECT_INDEX);
+    let text;
+    let handle;
+    try {
+        handle = (0, node_fs_1.openSync)(indexPath, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NOFOLLOW);
+        const metadata = (0, node_fs_1.fstatSync)(handle);
+        if (!metadata.isFile() || (metadata.mode & 0o777) !== 0o600)
+            throw new Error("Telegram identity subject index permissions are invalid");
+        text = (0, node_fs_1.readFileSync)(handle, "utf8");
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return [];
+        throw error;
+    }
+    finally {
+        if (handle !== undefined)
+            (0, node_fs_1.closeSync)(handle);
+    }
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("Telegram identity subject index is invalid");
+    const record = parsed;
+    if (record.version !== 1 || typeof record.subject !== "string" || !TELEGRAM_SUBJECT.test(record.subject) || !Array.isArray(record.legacySubjects)
+        || Object.keys(record).sort().join(",") !== "legacySubjects,subject,version") {
+        throw new Error("Telegram identity subject index is invalid");
+    }
+    const legacySubjects = record.legacySubjects;
+    if (!legacySubjects.every((candidate) => typeof candidate === "string" && TELEGRAM_SUBJECT.test(candidate))) {
+        throw new Error("Telegram identity subject index is invalid");
+    }
+    return record.subject === subject ? [] : [record.subject];
+}
+function discoverTelegramFilesystemSubjects(agentRoot) {
+    const subjects = new Set();
+    const addFriendDirectorySubjects = (root) => {
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)(root, { withFileTypes: true });
+        }
+        catch (error) {
+            if (errorCode(error) === "ENOENT")
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !entry.name.startsWith("telegram-user:"))
+                continue;
+            const candidate = entry.name.slice("telegram-user:".length);
+            if (TELEGRAM_SUBJECT.test(candidate))
+                subjects.add(candidate);
+        }
+    };
+    addFriendDirectorySubjects(path.join(agentRoot, "state", "sessions"));
+    addFriendDirectorySubjects(path.join(agentRoot, "state", "pending"));
+    addFriendDirectorySubjects(path.join(agentRoot, "state", "pending-returns"));
+    const friendsRoot = path.join(agentRoot, "friends");
+    let friendFiles;
+    try {
+        friendFiles = (0, node_fs_1.readdirSync)(friendsRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return [...subjects];
+        throw error;
+    }
+    for (const entry of friendFiles) {
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const friend = JSON.parse((0, node_fs_1.readFileSync)(path.join(friendsRoot, entry.name), "utf8"));
+        if (!friend || typeof friend !== "object" || !Array.isArray(friend.externalIds)) {
+            throw new Error("Telegram Friend identity record is invalid");
+        }
+        for (const external of friend.externalIds) {
+            if (!external || typeof external !== "object")
+                throw new Error("Telegram Friend external identity is invalid");
+            const identity = external;
+            if (identity.provider === "telegram-user" && typeof identity.externalId === "string" && TELEGRAM_SUBJECT.test(identity.externalId)) {
+                subjects.add(identity.externalId);
+            }
+        }
+    }
+    return [...subjects];
+}
+function writeTelegramSubjectIndex(agentRoot, subject, legacySubjects, hooks = {}) {
+    const directory = path.join(agentRoot, "state", "senses", "telegram");
+    const indexPath = path.join(directory, TELEGRAM_SUBJECT_INDEX);
+    const directoryHandle = openSecureTelegramDirectory(directory);
+    const temporaryPath = path.join(directory, `.identity-subjects.${(0, node_crypto_1.randomBytes)(12).toString("base64url")}.tmp`);
+    let temporaryHandle;
+    try {
+        temporaryHandle = (0, node_fs_1.openSync)(temporaryPath, node_fs_1.constants.O_CREAT | node_fs_1.constants.O_EXCL | node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_NOFOLLOW, 0o600);
+        hooks.afterCreateTemporary?.(temporaryPath);
+        const contents = `${JSON.stringify({ version: 1, subject, legacySubjects: [...legacySubjects] }, null, 2)}\n`;
+        (0, node_fs_1.writeFileSync)(temporaryHandle, contents);
+        (0, node_fs_1.fsyncSync)(temporaryHandle);
+        (0, node_fs_1.closeSync)(temporaryHandle);
+        temporaryHandle = undefined;
+        (0, node_fs_1.renameSync)(temporaryPath, indexPath);
+        (0, node_fs_1.fsyncSync)(directoryHandle);
+    }
+    finally {
+        if (temporaryHandle !== undefined)
+            (0, node_fs_1.closeSync)(temporaryHandle);
+        if ((0, node_fs_1.existsSync)(temporaryPath))
+            (0, node_fs_1.unlinkSync)(temporaryPath);
+        (0, node_fs_1.closeSync)(directoryHandle);
+    }
+}
+async function migrateTelegramFriendIdentity(agentRoot, legacyUserId, subject) {
+    const store = new friends_1.FileFriendStore(path.join(agentRoot, "friends"));
+    const legacy = await store.findByExternalId("telegram-user", legacyUserId);
+    if (!legacy)
+        return;
+    const current = await store.findByExternalId("telegram-user", subject);
+    if (current && current.id !== legacy.id)
+        throw new Error("Telegram friend identity migration is ambiguous");
+    legacy.externalIds = legacy.externalIds.map((external) => external.provider === "telegram-user" && external.externalId === legacyUserId
+        ? { ...external, externalId: subject }
+        : external);
+    if (legacy.name === `Telegram user ${legacyUserId}`)
+        legacy.name = `Telegram user ${subject}`;
+    legacy.updatedAt = new Date().toISOString();
+    await store.put(legacy.id, legacy);
+}
+function migrateTelegramSessionIdentity(agentRoot, legacyUserId, legacyChatId, subject) {
+    const legacyFriendId = `telegram-user:${legacyUserId}`;
+    const opaqueFriendId = `telegram-user:${subject}`;
+    const migrateDirectory = (root) => {
+        const legacy = path.join(root, legacyFriendId);
+        const opaque = path.join(root, opaqueFriendId);
+        if (!(0, node_fs_1.existsSync)(legacy))
+            return (0, node_fs_1.existsSync)(opaque) ? opaque : null;
+        if ((0, node_fs_1.existsSync)(opaque))
+            throw new Error("Telegram session identity migration is ambiguous");
+        (0, node_fs_1.mkdirSync)(root, { recursive: true });
+        (0, node_fs_1.renameSync)(legacy, opaque);
+        return opaque;
+    };
+    const sessions = migrateDirectory(path.join(agentRoot, "state", "sessions"));
+    if (sessions) {
+        const legacySession = path.join(sessions, "telegram", `telegram_${legacyChatId}.json`);
+        const opaqueSession = path.join(sessions, "telegram", `telegram_${subject}.json`);
+        if ((0, node_fs_1.existsSync)(legacySession)) {
+            if ((0, node_fs_1.existsSync)(opaqueSession))
+                throw new Error("Telegram session file migration is ambiguous");
+            (0, node_fs_1.renameSync)(legacySession, opaqueSession);
+        }
+    }
+    const pending = migrateDirectory(path.join(agentRoot, "state", "pending"));
+    if (pending) {
+        const legacyPending = path.join(pending, "telegram", `telegram:${legacyChatId}`);
+        const opaquePending = path.join(pending, "telegram", `telegram:${subject}`);
+        if ((0, node_fs_1.existsSync)(legacyPending)) {
+            if ((0, node_fs_1.existsSync)(opaquePending))
+                throw new Error("Telegram pending identity migration is ambiguous");
+            (0, node_fs_1.renameSync)(legacyPending, opaquePending);
+        }
+    }
+    migrateDirectory(path.join(agentRoot, "state", "pending-returns"));
+}
+function redactTelegramPrivateValues(error, privateValues) {
+    let message = error instanceof Error ? error.message : String(error);
+    for (const privateValue of privateValues)
+        message = message.split(privateValue).join("[redacted]");
+    return message;
+}
+function parseTelegramSenseCredentials(value) {
+    return {
+        botToken: requiredText(value.telegramBotToken, "bot token"),
+        authorizedUserId: canonicalTelegramId(value.telegramAuthorizedUserId, "authorized user id"),
+        authorizedChatId: canonicalTelegramId(value.telegramAuthorizedChatId, "authorized chat id"),
+    };
+}
+function createTelegramSenseApp(options) {
+    const botToken = requiredText(options.credentials.botToken, "bot token");
+    const botId = options.credentials.botId !== undefined
+        ? canonicalTelegramId(options.credentials.botId, "bot id")
+        : options.admission ? telegramBotIdFromToken(botToken) : null;
+    const authorizedUserId = canonicalTelegramId(options.credentials.authorizedUserId, "authorized user id");
+    const authorizedChatId = canonicalTelegramId(options.credentials.authorizedChatId, "authorized chat id");
+    const agentRoot = options._agentRoot ?? (0, identity_1.getAgentRoot)(options.agentName);
+    const identityKey = options.identityKey === undefined
+        ? readOrCreateTelegramIdentityKey(agentRoot)
+        : canonicalTelegramIdentityKey(options.identityKey);
+    const subject = opaqueTelegramSubject(identityKey, botId ?? botToken, authorizedUserId, authorizedChatId);
+    const transportError = (error) => redactTelegramPrivateValues(error, [botToken, authorizedUserId, authorizedChatId]);
+    const api = options.api ?? (0, telegram_client_1.createTelegramBotApi)({ token: botToken });
+    const offsetStore = options.offsetStore ?? new telegram_client_1.FileTelegramOffsetStore(path.join(agentRoot, "state", "senses", "telegram", "offset.json"));
+    const inboxStore = options.inboxStore ?? new telegram_client_1.FileTelegramUpdateInboxStore(path.join(agentRoot, "state", "senses", "telegram", "inbox.json"));
+    const admissionStore = options.admission
+        ? new telegram_admission_1.FileTelegramAdmissionStore(path.join(agentRoot, "state", "senses", "telegram", "admissions"))
+        : undefined;
+    const runTurn = options.runTurn ?? options._runTurn ?? shared_turn_1.runSenseTurn;
+    const collectToolReceipts = options._runWithToolReceiptCollection ?? sanctuary_runtime_2.runWithSanctuaryToolReceiptCollection;
+    const useSanctuaryRuntime = options.agentName === "sanctuary" && !options.runTurn;
+    const readScenarioHandleDigest = () => (options.acceptanceMarker
+        ? options.acceptanceMarker()
+        : (0, sanctuary_acceptance_marker_1.readSanctuaryAcceptanceMarker)(options.agentName))?.scenarioHandleDigest;
+    let acceptanceAuditLease;
+    const retireAcceptanceAudit = () => {
+        const lease = acceptanceAuditLease;
+        if (!lease)
+            return;
+        const errors = [];
+        try {
+            lease.ledger.assertHealthy();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            lease.release();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        finally {
+            acceptanceAuditLease = undefined;
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, "Telegram acceptance audit retirement failed");
+    };
+    const ensureAcceptanceAudit = () => {
+        if (!useSanctuaryRuntime)
+            return undefined;
+        const scenarioHandleDigest = readScenarioHandleDigest();
+        const effectScenarioHandleDigest = telegramAcceptanceAuditScenario.getStore();
+        if (effectScenarioHandleDigest !== undefined && (scenarioHandleDigest ?? null) !== effectScenarioHandleDigest) {
+            const error = new Error("Telegram acceptance audit scenario ownership drift");
+            acceptanceAuditLease?.ledger.poison(error);
+            throw error;
+        }
+        if (scenarioHandleDigest === undefined) {
+            if (acceptanceAuditLease) {
+                retireAcceptanceAudit();
+            }
+            return undefined;
+        }
+        if (!/^[0-9a-f]{64}$/u.test(scenarioHandleDigest))
+            throw new Error("Telegram acceptance audit scenario handle is invalid");
+        if (!acceptanceAuditLease) {
+            acceptanceAuditLease = acquireTelegramAcceptanceAudit(options.acceptanceReceiptRoot ?? agentRoot, options.agentName, identityKey, [botToken, authorizedUserId, authorizedChatId], scenarioHandleDigest, options._acceptanceAuditReleaseHook, options._acceptanceAuditMaxBytes);
+        }
+        else if (scenarioHandleDigest !== acceptanceAuditLease.scenarioHandleDigest) {
+            retireAcceptanceAudit();
+            acceptanceAuditLease = acquireTelegramAcceptanceAudit(options.acceptanceReceiptRoot ?? agentRoot, options.agentName, identityKey, [botToken, authorizedUserId, authorizedChatId], scenarioHandleDigest, options._acceptanceAuditReleaseHook, options._acceptanceAuditMaxBytes);
+        }
+        return acceptanceAuditLease;
+    };
+    ensureAcceptanceAudit();
+    const acceptanceAuditBarrier = () => {
+        const lease = ensureAcceptanceAudit();
+        if (!lease)
+            return;
+        lease.ledger.assertHealthy();
+        lease.ledger.assertCapacity(8);
+    };
+    const runWithAcceptanceAuditOwner = async (operation) => {
+        const scenarioHandleDigest = readScenarioHandleDigest() ?? null;
+        return telegramAcceptanceAuditScenario.run(scenarioHandleDigest, async () => {
+            acceptanceAuditBarrier();
+            const ownerDigest = acceptanceAuditLease?.ownerDigest ?? "";
+            return telegramAcceptanceAuditOwner.run(ownerDigest, async () => {
+                try {
+                    const result = await operation();
+                    acceptanceAuditBarrier();
+                    return result;
+                }
+                catch (error) {
+                    try {
+                        acceptanceAuditBarrier();
+                    }
+                    catch (auditError) {
+                        if (error === auditError)
+                            throw auditError;
+                        throw new AggregateError([error, auditError], "Telegram effect and acceptance audit verification failed");
+                    }
+                    throw error;
+                }
+            });
+        });
+    };
+    const emitDurableSettlementEvidence = async (event, meta) => {
+        if (event === "telegram.callback_settled") {
+            await (0, runtime_1.emitNervesEventDurable)({
+                component: "senses",
+                event: "telegram.callback_settled",
+                message: "Telegram approval acceptance evidence durably recorded",
+                meta,
+            });
+        }
+        else if (event === "telegram.callback_recovery_settled") {
+            await (0, runtime_1.emitNervesEventDurable)({
+                component: "senses",
+                event: "telegram.callback_recovery_settled",
+                message: "Telegram approval acceptance evidence durably recorded",
+                meta,
+            });
+        }
+        else {
+            throw new Error("Telegram durable acceptance settlement event is unsupported");
+        }
+    };
+    const commitAcceptanceEvidence = useSanctuaryRuntime ? async (event, meta) => {
+        acceptanceAuditBarrier();
+        const lease = acceptanceAuditLease;
+        if (!lease) {
+            await emitDurableSettlementEvidence(event, meta);
+            return;
+        }
+        await telegramAcceptanceAuditExplicitCommit.run(true, async () => {
+            await emitDurableSettlementEvidence(event, meta);
+        });
+        acceptanceAuditBarrier();
+        lease.ledger.append({
+            ts: new Date().toISOString(),
+            level: "info",
+            event,
+            trace_id: (0, node_crypto_1.randomUUID)(),
+            component: "senses",
+            message: "Telegram approval acceptance evidence durably recorded",
+            meta,
+        });
+        lease.ledger.assertHealthy();
+    } : undefined;
+    const releaseAcceptanceAudit = (primaryError) => {
+        try {
+            acceptanceAuditLease?.release();
+        }
+        catch (releaseError) {
+            throw new AggregateError([primaryError, releaseError], "Telegram sense construction and audit release failed");
+        }
+        throw primaryError;
+    };
+    let effectJournal;
+    const getEffectJournal = () => {
+        effectJournal ??= new telegram_effect_adapter_1.FileTelegramEffectJournal(path.join(agentRoot, "state", "telegram", "effects"));
+        return effectJournal;
+    };
+    const configuredOwnerFriendId = options.admission?.ownerFriendId ?? `telegram-user:${subject}`;
+    const configuredOwnerSessionKey = `telegram:${subject}`;
+    const defaultEffectAuthorization = async (input) => {
+        const target = input.target;
+        if (target.kind === "admission_gate") {
+            const pending = admissionStore.read(target.admissionId);
+            const authorization = (0, relationship_authorization_1.authorizeRelationshipAccess)({
+                profiles: [],
+                pendingAdmission: { admissionId: pending.id, botId: pending.botId, userId: pending.userId, chatId: pending.chatId, expiresAt: new Date(pending.expiresAt).toISOString() },
+                request: { kind: "admission_gate", admissionId: target.admissionId, botId: target.botId, userId: target.userId, chatId: target.chatId, effect: "fixed_ack", idempotencyKey: input.idempotencyKey, expiresAt: new Date(pending.expiresAt).toISOString() },
+            });
+            const admissionAuthorization = authorization;
+            return { allowed: true, receiptId: admissionAuthorization.receiptId, expiresAt: admissionAuthorization.expiresAt, transport: { chatId: target.chatId } };
+        }
+        if (input.authorClass === "system_failsafe" && (input.effect.kind !== "text" || input.effect.text !== telegram_effect_adapter_1.FIXED_USENET_SYSTEM_FAILSAFE || !input.idempotencyKey.startsWith("system-failsafe:"))) {
+            return { allowed: false, reason: "system failsafe shape is not fixed" };
+        }
+        if (options.authorizeRelationshipEffect) {
+            if (target.friendId === configuredOwnerFriendId && target.sessionKey !== configuredOwnerSessionKey)
+                return { allowed: false, reason: "owner relationship session binding changed" };
+            return options.authorizeRelationshipEffect(input);
+        }
+        if (target.friendId !== `telegram-user:${subject}` || target.sessionKey !== `telegram:${subject}`) {
+            return { allowed: false, reason: "effect target is not the configured owner relationship" };
+        }
+        return { allowed: true, receiptId: `configured-owner:${subject}`, expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(), transport: { chatId: authorizedChatId } };
+    };
+    const authorizeEffect = options.authorizeEffect ?? defaultEffectAuthorization;
+    let recordAcceptedEffects;
+    const configuredOwnerTarget = () => ({ kind: "approved_relationship", friendId: configuredOwnerFriendId, sessionKey: configuredOwnerSessionKey });
+    const executeAuthorizedEffect = (0, telegram_effect_adapter_1.createTelegramAuthorizedEffectExecutor)({
+        store: getEffectJournal,
+        api,
+        authorize: authorizeEffect,
+        barrier: acceptanceAuditBarrier,
+    });
+    const recordConfiguredOwnerEffect = async (artifact, causalEventId) => {
+        await recordAcceptedEffects((0, shared_turn_1.getSenseSessionPath)(options.agentName, configuredOwnerFriendId, "telegram", configuredOwnerSessionKey, agentRoot), [artifact], undefined, causalEventId ? { [artifact.id]: causalEventId } : undefined);
+    };
+    const approvalEffects = (0, telegram_effect_adapter_1.createTelegramApprovalEffectPort)({ target: configuredOwnerTarget(), chatId: authorizedChatId, execute: executeAuthorizedEffect, record: recordConfiguredOwnerEffect });
+    let toolContext;
+    let approvalRuntime;
+    let approvalTransport;
+    let interactiveControl;
+    try {
+        toolContext = useSanctuaryRuntime ? (options._toolContext ?? (0, sanctuary_runtime_2.createSanctuaryToolContext)(options.agentName)) : undefined;
+        if (toolContext && options.telegramContactManager)
+            toolContext.telegramContactManager = options.telegramContactManager;
+        approvalRuntime = options.approvalRuntime ?? (useSanctuaryRuntime ? (options._createApprovalRuntime ?? telegram_approval_runtime_1.createTelegramApprovalRuntime)({
+            agentName: options.agentName,
+            api,
+            authorizedUserId,
+            authorizedChatId,
+            subject,
+            identityKey,
+            toolContext: toolContext ?? {},
+            effects: approvalEffects,
+            effectBarrier: acceptanceAuditBarrier,
+            dependencies: {
+                acceptanceMarker: () => {
+                    const scenarioHandleDigest = readScenarioHandleDigest();
+                    return scenarioHandleDigest ? { scenarioHandleDigest } : null;
+                },
+                commitAcceptanceEvidence,
+            },
+        }) : undefined);
+        approvalTransport = options.approvalTransport ?? approvalRuntime?.transport;
+        interactiveControl = useSanctuaryRuntime && approvalTransport
+            ? (options._createInteractiveControl ?? sanctuary_interactive_control_1.createSanctuaryInteractiveControl)({
+                agentRoot,
+                transport: approvalTransport,
+                authorizedUserId,
+                authorizedChatId,
+                runRequest: runWithAcceptanceAuditOwner,
+            })
+            : undefined;
+    }
+    catch (error) {
+        releaseAcceptanceAudit(error);
+    }
+    const migrateIdentity = options.migrateIdentity ?? (async () => {
+        const legacySubjects = new Set([
+            ...readTelegramSubjectIndex(agentRoot, subject),
+            ...discoverTelegramFilesystemSubjects(agentRoot),
+            ...(approvalRuntime?.legacySubjects?.() ?? []),
+        ]);
+        legacySubjects.delete(subject);
+        if (legacySubjects.size > 1)
+            throw new Error("Telegram legacy identity subject migration is ambiguous");
+        const migrationSubjects = [...legacySubjects];
+        for (const legacySubject of migrationSubjects) {
+            acceptanceAuditBarrier();
+            migrateTelegramSessionIdentity(agentRoot, legacySubject, legacySubject, subject);
+            acceptanceAuditBarrier();
+            if (!options.admission)
+                await migrateTelegramFriendIdentity(agentRoot, legacySubject, subject);
+        }
+        acceptanceAuditBarrier();
+        migrateTelegramSessionIdentity(agentRoot, authorizedUserId, authorizedChatId, subject);
+        acceptanceAuditBarrier();
+        if (!options.admission)
+            await migrateTelegramFriendIdentity(agentRoot, authorizedUserId, subject);
+        acceptanceAuditBarrier();
+        approvalRuntime?.migrateIdentity?.(migrationSubjects);
+        acceptanceAuditBarrier();
+        writeTelegramSubjectIndex(agentRoot, subject, migrationSubjects, options.subjectIndexHooks);
+    });
+    let approvalReconcileTimer;
+    let approvalReconciliationActive = false;
+    const approvalReconciliationsInFlight = new Set();
+    let nextApprovalReconcileDeadline;
+    let reconcileSystemFailsafes;
+    let stopPromise;
+    let runPromise;
+    const clearApprovalReconcileTimer = () => {
+        if (approvalReconcileTimer)
+            clearTimeout(approvalReconcileTimer);
+        approvalReconcileTimer = undefined;
+    };
+    const scheduleApprovalReconcile = () => {
+        if (!approvalTransport || !approvalReconciliationActive)
+            return;
+        const scheduledAt = nextApprovalReconcileDeadline ?? (Date.now() + APPROVAL_EXPIRY_RECONCILE_INTERVAL_MS);
+        nextApprovalReconcileDeadline = scheduledAt + APPROVAL_EXPIRY_RECONCILE_INTERVAL_MS;
+        const delay = Math.max(0, scheduledAt - Date.now());
+        approvalReconcileTimer = setTimeout(() => {
+            approvalReconcileTimer = undefined;
+            scheduleApprovalReconcile();
+            const reconciliation = runWithAcceptanceAuditOwner(() => approvalTransport.reconcileExpired()).catch((error) => {
+                acceptanceAuditBarrier();
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "senses",
+                    event: "senses.telegram_approval_reconcile_error",
+                    message: "Telegram approval expiry reconciliation failed",
+                    meta: { agentName: options.agentName, subject, error: transportError(error) },
+                });
+            }).finally(() => {
+                approvalReconciliationsInFlight.delete(reconciliation);
+            });
+            approvalReconciliationsInFlight.add(reconciliation);
+            const failsafe = runWithAcceptanceAuditOwner(reconcileSystemFailsafes)
+                .finally(() => { approvalReconciliationsInFlight.delete(failsafe); });
+            approvalReconciliationsInFlight.add(failsafe);
+        }, delay);
+    };
+    const deliverButlerEffect = async (text, idempotencyKey, signal, onMessageDelivered, exactDownloadCreditQuestion = false) => {
+        const presentedText = (0, sanctuary_download_credit_presentation_1.presentSanctuaryDownloadCreditReply)(options.agentName, exactDownloadCreditQuestion, text);
+        return executeAuthorizedEffect({
+            idempotencyKey,
+            target: configuredOwnerTarget(),
+            authorClass: "butler",
+            effect: { kind: "text", text: presentedText },
+            ...(signal ? { signal } : {}),
+            ...(onMessageDelivered ? { onMessageDelivered } : {}),
+        });
+    };
+    recordAcceptedEffects = async (sessionPath, artifacts, bootstrapInbound, causalEventIds) => {
+        await (0, telegram_effect_adapter_1.recordTelegramEffectsInSession)({ store: getEffectJournal(), sessionPath, artifacts, ...(bootstrapInbound ? { inbound: bootstrapInbound } : {}), ...(causalEventIds ? { causalEventIds } : {}) });
+        for (const artifact of artifacts) {
+            if (artifact.target.kind !== "approved_relationship" || !artifact.target.requestId || artifact.effect.kind !== "text")
+                continue;
+            const recorded = getEffectJournal().read(artifact.id);
+            if (!recorded.parts.every((part) => part.state === "session_recorded"))
+                continue;
+            if (!artifact.obligationReturnId)
+                continue;
+            const obligation = (0, obligations_1.readObligation)(agentRoot, artifact.obligationReturnId);
+            if (obligation?.returnReadyAt && obligation.requestId === artifact.target.requestId
+                && obligation.owedTo?.friendId === artifact.target.friendId && obligation.owedTo.channel === "telegram"
+                && obligation.owedTo.key === artifact.target.sessionKey)
+                (0, obligations_1.fulfillObligation)(agentRoot, obligation.id);
+        }
+    };
+    const deliverAwaitFollowUp = async (request) => {
+        if (!request.requestId)
+            return { status: "blocked", detail: "Telegram follow-up is missing its request binding" };
+        const sessionKey = (0, config_1.canonicalizeTelegramSessionKey)(request.key);
+        try {
+            const obligation = (0, obligations_1.findPendingObligationForRequest)(agentRoot, { requestId: request.requestId, owedTo: { friendId: request.friendId, channel: "telegram", key: sessionKey } });
+            if (obligation && !obligation.returnReadyAt)
+                (0, obligations_1.markObligationReturnReady)(agentRoot, obligation.id, request.deliveryId ?? `telegram-return:${request.requestId}`);
+            const expiry = request.deliveryId?.endsWith(":expired") === true;
+            const artifact = await executeAuthorizedEffect({
+                idempotencyKey: `await-${expiry ? "expiry-" : ""}follow-up:${request.requestId}:${(0, node_crypto_1.createHash)("sha256").update(request.deliveryId ?? request.content).digest("hex")}`,
+                target: { kind: "approved_relationship", friendId: request.friendId, sessionKey, requestId: request.requestId },
+                authorClass: "butler",
+                effect: { kind: "text", text: request.content },
+                ...(obligation ? { obligationReturnId: obligation.id } : {}),
+            });
+            await recordAcceptedEffects((0, shared_turn_1.getSenseSessionPath)(options.agentName, request.friendId, "telegram", sessionKey, agentRoot), [artifact]);
+            return { status: "delivered_now", detail: "sent to the exact request-bound Telegram chat" };
+        }
+        catch (error) {
+            return { status: "blocked", detail: error instanceof Error ? error.message : String(error) };
+        }
+    };
+    (0, tools_awaiting_1.setAwaitToolDeps)({
+        buildDeliveryDeps: () => ({
+            agentName: options.agentName,
+            queuePending: (message) => (0, pending_1.queuePendingMessage)((0, pending_1.getPrivateRuntimePendingDir)(options.agentName), message),
+            deliverers: {
+                telegram: deliverAwaitFollowUp,
+            },
+        }),
+    });
+    reconcileSystemFailsafes = async () => {
+        if (!options.privilegedFailsafe)
+            return;
+        const target = configuredOwnerTarget();
+        try {
+            await (0, telegram_effect_adapter_1.sweepTelegramSystemFailsafes)({
+                eventRoot: options.privilegedFailsafe.eventRoot,
+                target,
+                verifyProtectiveState: options.privilegedFailsafe.verifyProtectiveState,
+                execute: executeAuthorizedEffect,
+                recordArtifact: async (artifact) => {
+                    await recordAcceptedEffects((0, shared_turn_1.getSenseSessionPath)(options.agentName, target.friendId, "telegram", target.sessionKey, agentRoot), [artifact]);
+                },
+            });
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.telegram_system_failsafe_error", message: "Telegram system failsafe reconciliation failed", meta: { agentName: options.agentName, subject, error: transportError(error) } });
+        }
+    };
+    const prepareRelationshipRunAgentOptions = (input) => {
+        if (!options.resolveRelationshipAuthorization)
+            throw new Error("Telegram relationship authorization resolver is unavailable");
+        const relationshipCoordinates = { ...input, botId: botId };
+        const resolveLiveRelationshipAuthorization = async () => {
+            const authorization = await options.resolveRelationshipAuthorization(relationshipCoordinates);
+            if (authorization.subject.friendId !== input.friendId || authorization.subject.admissionState !== "active")
+                throw new Error("Telegram relationship admission is not active");
+            return {
+                requestId: input.requestId,
+                profileId: authorization.profileId,
+                authorizedContextScopes: authorization.authorizedContextScopes,
+                advertisedToolNames: authorization.advertisedToolNames,
+                actor: authorization.actor,
+                authorizeTool: async (name, args) => (await options.resolveRelationshipAuthorization(relationshipCoordinates)).authorizeTool(name, args),
+            };
+        };
+        return async ({ runAgentOptions, activeCares = [], careEvidenceNow = Date.now() }) => {
+            const relationshipAuthorization = await resolveLiveRelationshipAuthorization();
+            const isSanctuaryOwner = options.agentName === "sanctuary" && relationshipAuthorization.profileId === "sanctuary-owner";
+            const isSanctuaryHouseholdConversation = options.agentName === "sanctuary"
+                && (relationshipAuthorization.profileId === "sanctuary-owner" || relationshipAuthorization.profileId === "sanctuary-household");
+            const storageOptimization = isSanctuaryOwner
+                ? (0, sanctuary_storage_optimization_contract_1.sanctuaryStorageOptimizationRequiredToolCalls)(input.userMessage, relationshipAuthorization.advertisedToolNames)
+                : undefined;
+            const staleDockerCare = isSanctuaryOwner
+                ? (0, sanctuary_full_visibility_contract_1.sanctuaryStaleDockerCareRequiredToolCalls)(activeCares, careEvidenceNow, relationshipAuthorization.advertisedToolNames)
+                : undefined;
+            const fullVisibility = isSanctuaryOwner
+                ? (0, sanctuary_full_visibility_contract_1.sanctuaryFullVisibilityRequiredToolCalls)(input.userMessage, relationshipAuthorization.advertisedToolNames, () => staleDockerCare?.currentRiskClaims() ?? [])
+                : undefined;
+            const mediaCatalog = isSanctuaryHouseholdConversation
+                ? (0, sanctuary_media_catalog_contract_1.sanctuaryMediaCatalogRequiredToolCalls)(input.userMessage, relationshipAuthorization.advertisedToolNames)
+                : undefined;
+            const installState = isSanctuaryOwner
+                ? (0, sanctuary_install_state_contract_1.sanctuaryInstallStateRequiredToolCalls)(input.userMessage, relationshipAuthorization.advertisedToolNames)
+                : undefined;
+            if (input.fullVisibilityProgress && fullVisibility)
+                input.fullVisibilityProgress.fallback = fullVisibility.emptyResponseFallback;
+            const contracts = [storageOptimization, fullVisibility, staleDockerCare, mediaCatalog, installState].filter(Boolean);
+            const ownedNames = contracts.map((contract) => new Set(contract.names));
+            const requiredToolCalls = contracts.length === 0 ? undefined : {
+                names: [...new Set(contracts.flatMap((contract) => [...contract.names]))],
+                get retryMessage() { return contracts.map((contract) => contract.retryMessage).join(" "); },
+                requireSuccessfulResults: true,
+                validateRequiredToolResult: (name, result, args) => contracts.every((contract, index) => {
+                    if (!ownedNames[index].has(name))
+                        return true;
+                    return contract.validateRequiredToolResult?.(name, result, args) ?? true;
+                }),
+                validateToolCallBeforeDispatch: (name, args) => contracts.map((contract) => contract.validateToolCallBeforeDispatch?.(name, args)).find((rejection) => rejection !== undefined),
+                requiredToolCallsAfterResult: (name, args, result) => {
+                    const added = new Set();
+                    contracts.forEach((contract, index) => {
+                        if (!ownedNames[index].has(name) || !contract.requiredToolCallsAfterResult)
+                            return;
+                        for (const requiredName of contract.requiredToolCallsAfterResult(name, args, result)) {
+                            ownedNames[index].add(requiredName);
+                            added.add(requiredName);
+                        }
+                    });
+                    return [...added];
+                },
+                validateTerminalAnswer: (answer) => contracts.map((contract) => contract.validateTerminalAnswer?.(answer)).find((rejection) => rejection !== undefined),
+            };
+            return {
+                ...runAgentOptions,
+                ...(requiredToolCalls ? { requiredToolCalls } : {}),
+                toolContext: { ...runAgentOptions.toolContext, relationshipAuthorization },
+            };
+        };
+    };
+    const dispatchResolvedRelationshipTurn = async (input) => {
+        const sessionPath = (0, shared_turn_1.getSenseSessionPath)(options.agentName, input.friendId, "telegram", input.sessionKey, agentRoot);
+        const effects = [];
+        let ordinal = 0;
+        const deliver = async (text, terminalReturn = false) => {
+            const obligation = terminalReturn ? (0, obligations_1.findPendingObligationForRequest)(agentRoot, {
+                requestId: input.requestId,
+                owedTo: { friendId: input.friendId, channel: "telegram", key: input.sessionKey },
+            }) : undefined;
+            effects.push(await executeAuthorizedEffect({
+                idempotencyKey: `relationship-turn:${input.requestId}:delivery:${ordinal++}`,
+                target: { kind: "approved_relationship", friendId: input.friendId, sessionKey: input.sessionKey, requestId: input.requestId },
+                authorClass: "butler",
+                effect: { kind: "text", text },
+                ...(obligation?.returnReadyAt ? { obligationReturnId: obligation.id } : {}),
+            }));
+        };
+        const orientationFrame = input.orientation?.kind === "newly_admitted"
+            ? {
+                ...(0, orientation_frame_1.buildOrientationFrame)({ channel: "telegram", messages: [{ role: "user", content: input.text }] }),
+                source: {
+                    kind: "telegram_newly_admitted",
+                    authority: "presentation_only",
+                    routingHint: [
+                        "This is this person’s first admitted turn. Welcome them warmly and briefly explain what the household Butler can help with before answering their request.",
+                        input.orientation.relationship ? `The owner identified this person as their ${input.orientation.relationship}.` : null,
+                        input.orientation.attachmentsNeedResend ? "Their original message included attachments that were not downloaded; ask them to resend those attachments now." : null,
+                    ].filter(Boolean).join(" "),
+                },
+            }
+            : undefined;
+        const fullVisibility = createFullVisibilityProgress();
+        const result = await runTurn({
+            agentName: options.agentName,
+            channel: "telegram",
+            sessionKey: input.sessionKey,
+            friendId: input.friendId,
+            identity: { provider: "telegram-user", externalId: input.userId, displayName: "Household member", tenantId: botId },
+            userMessage: input.text,
+            ingressRelations: { replyToEventId: null, threadRootEventId: null, references: [input.reference] },
+            precommittedIngress: { eventId: input.eventId, reference: input.reference },
+            ...(orientationFrame ? { orientationFrame } : {}),
+            toolContext: { ...(toolContext ?? {}), attachmentIds: input.attachmentIds ?? [] },
+            prepareRunAgentOptions: prepareRelationshipRunAgentOptions({ friendId: input.friendId, requestId: input.requestId,
+                sessionEventId: input.eventId, userId: input.userId, chatId: input.chatId, sessionKey: input.sessionKey, userMessage: input.text, fullVisibilityProgress: fullVisibility.progress }),
+            emptyResponseFallback: fullVisibility.emptyResponseFallback,
+            deliverySink: { onDelivery: (delivery) => deliver(delivery.text, delivery.kind === "settle") },
+        });
+        let responseFallbackArtifactId;
+        const responseFallback = responseFallbackAfterDeliveries(result, effects.length);
+        if (responseFallback) {
+            await deliver(responseFallback, true);
+            responseFallbackArtifactId = effects.at(-1)?.id;
+        }
+        const causalEventIds = Object.fromEntries(effects.flatMap((artifact, index) => {
+            const eventId = result.causalSessionEventIds?.[index]
+                ?? (artifact.id === responseFallbackArtifactId ? result.responseCausalSessionEventId : undefined);
+            return eventId ? [[artifact.id, eventId]] : [];
+        }));
+        await recordAcceptedEffects(sessionPath, effects, undefined, causalEventIds);
+    };
+    const admissionController = options.admission && admissionStore ? (0, telegram_admission_1.createTelegramAdmissionController)({
+        store: admissionStore,
+        owner: { friendId: configuredOwnerFriendId, sessionKey: configuredOwnerSessionKey },
+        sendEffect: async (request) => {
+            const artifact = await executeAuthorizedEffect(request);
+            if (artifact.target.kind === "approved_relationship") {
+                await recordAcceptedEffects((0, shared_turn_1.getSenseSessionPath)(options.agentName, artifact.target.friendId, "telegram", artifact.target.sessionKey, agentRoot), [artifact]);
+            }
+            return artifact.id;
+        },
+        resolveOwnerCard: (messageId) => {
+            const resolved = (0, telegram_effect_adapter_1.resolveTelegramControlArtifact)(getEffectJournal(), { messageId, friendId: configuredOwnerFriendId, sessionKey: configuredOwnerSessionKey });
+            return resolved?.requestId
+                ? { artifactId: resolved.artifactId, admissionId: resolved.requestId }
+                : null;
+        },
+        resolveOwnerCardMessageId: (artifactId) => {
+            const artifact = getEffectJournal().read(artifactId);
+            if (artifact.authorClass !== "control" || artifact.target.kind !== "approved_relationship"
+                || artifact.target.friendId !== configuredOwnerFriendId || artifact.target.sessionKey !== configuredOwnerSessionKey)
+                return null;
+            return artifact.parts.find((part) => part.state === "session_recorded" && part.messageId)?.messageId ?? null;
+        },
+        claimFriend: options.admission.claimFriend,
+        revokeFriend: options.admission.revokeFriend,
+        commitApprovedIngress: async (input) => {
+            const sessionKey = `telegram:${input.botId}:${input.userId}`;
+            const reference = `telegram-admission:${input.admissionId}`;
+            const sessionPath = (0, shared_turn_1.getSenseSessionPath)(options.agentName, input.friendId, "telegram", sessionKey, agentRoot);
+            const receipt = await (0, telegram_effect_adapter_1.recordTelegramEffectsInSession)({ store: getEffectJournal(), sessionPath, artifacts: [], inbound: { text: input.text, reference } });
+            return { admissionId: input.admissionId, friendId: input.friendId, sessionKey, eventId: receipt.eventId, reference };
+        },
+        enqueueApprovedWork: async (input) => {
+            if (!inboxStore.captureAdmittedWork)
+                throw new Error("Telegram admitted work inbox is unavailable");
+            inboxStore.captureAdmittedWork(input);
+        },
+        dispatchApprovedWork: async (input) => {
+            if (!inboxStore.admittedWorkState || !inboxStore.claimAdmittedWork || !inboxStore.completeAdmittedWork)
+                return "indeterminate";
+            const state = inboxStore.admittedWorkState(input.admissionId);
+            if (state === "settled")
+                return "settled";
+            if (state !== "pending" || !inboxStore.claimAdmittedWork(input.admissionId))
+                return "indeterminate";
+            try {
+                const sessionPath = (0, shared_turn_1.getSenseSessionPath)(options.agentName, input.friendId, "telegram", input.sessionKey, agentRoot);
+                const envelope = (0, session_events_1.loadSessionEnvelopeFile)(sessionPath);
+                const event = envelope?.events.find((candidate) => candidate.id === input.eventId
+                    && candidate.role === "user" && candidate.relations.references.includes(input.reference));
+                if (!event || typeof event.content !== "string")
+                    throw new Error("Telegram admitted work ingress is unavailable");
+                const record = admissionStore.read(input.admissionId);
+                await dispatchResolvedRelationshipTurn({ friendId: input.friendId, sessionKey: input.sessionKey, requestId: input.admissionId,
+                    eventId: input.eventId, reference: input.reference, text: event.content, userId: record.userId, chatId: record.chatId, orientation: input.orientation });
+                inboxStore.completeAdmittedWork(input.admissionId);
+                return "settled";
+            }
+            catch {
+                return "indeterminate";
+            }
+        },
+        withDecisionLease: (admissionId, work) => (0, session_transaction_1.withSessionTurnLease)(path.join(agentRoot, "state", "senses", "telegram", "admission-decisions", admissionId), async () => work()),
+        ...(options.admission.createDisplayCode ? { createDisplayCode: options.admission.createDisplayCode } : {}),
+    }) : undefined;
+    const recoverEffectOutbox = async () => {
+        if (!effectJournal && !(0, node_fs_1.existsSync)(path.join(agentRoot, "state", "telegram", "effects")))
+            return;
+        await (0, telegram_effect_adapter_1.recoverTelegramEffectOutbox)({
+            store: getEffectJournal(),
+            execute: executeAuthorizedEffect,
+            matches: (artifact) => artifact.target.kind === "approved_relationship",
+        });
+        const accepted = getEffectJournal().list().filter((artifact) => artifact.target.kind === "approved_relationship" && artifact.parts.some((part) => part.state === "accepted"));
+        for (const artifact of accepted) {
+            const target = artifact.target;
+            await recordAcceptedEffects((0, shared_turn_1.getSenseSessionPath)(options.agentName, target.friendId, "telegram", target.sessionKey, agentRoot), [artifact]);
+        }
+    };
+    const hydrateAuthorizedMessage = async (message) => {
+        if (!message.attachments?.length)
+            return { text: [message.text, ...(message.attachmentNotices ?? [])].filter(Boolean).join("\n"), attachmentIds: [] };
+        const ingested = await (0, telegram_attachments_1.ingestTelegramAttachments)({
+            agentName: options.agentName,
+            agentRoot,
+            botToken,
+            api,
+            ...(options.attachmentFetch ? { fetch: options.attachmentFetch } : {}),
+            attachments: message.attachments ?? [],
+        });
+        const attachmentIds = ingested.attachments.map((attachment) => attachment.id);
+        return {
+            text: [message.text, (0, render_1.renderAttachmentBlock)(ingested.attachments), ...(message.attachmentNotices ?? []), ...ingested.notices].filter(Boolean).join("\n"),
+            attachmentIds,
+        };
+    };
+    const onMessageBody = async (rawMessage) => {
+        const hydrated = await hydrateAuthorizedMessage(rawMessage);
+        const message = { ...rawMessage, text: hydrated.text };
+        const currentFriendId = configuredOwnerFriendId;
+        const currentSessionKey = configuredOwnerSessionKey;
+        const currentSessionPath = (0, shared_turn_1.getSenseSessionPath)(options.agentName, currentFriendId, "telegram", currentSessionKey, agentRoot);
+        const inboundReference = `telegram-inbound:${(0, node_crypto_1.createHmac)("sha256", identityKey).update(`${message.updateId}\0${message.messageId}`).digest("hex")}`;
+        const acceptanceMarker = options.acceptanceMarker ? options.acceptanceMarker() : (0, sanctuary_acceptance_marker_1.readSanctuaryAcceptanceMarker)(options.agentName);
+        const acceptanceMeta = (0, sanctuary_acceptance_marker_1.sanctuaryAcceptanceEventMeta)(options.agentName);
+        const groundedAcceptance = acceptanceMarker?.label === "unit-16d-whats-up" || acceptanceMarker?.label === "unit-16d-1-space";
+        const acceptanceSchema = groundedAcceptance ? "sanctuary-telegram-turn-receipt-v4" : "sanctuary-telegram-turn-receipt-v3";
+        const auditDigest = (purpose, value) => sanctuaryTelegramTurnReceiptDigest(identityKey, acceptanceSchema, purpose, value);
+        const lifecycleCoordinates = acceptanceMarker ? {
+            scenarioHandleDigest: acceptanceMarker.scenarioHandleDigest,
+            turnDigest: auditDigest("turn", `${message.updateId}\0${message.messageId}`),
+            updateDigest: auditDigest("update", `${message.updateId}\0${message.messageId}`),
+            subject,
+            identityDigest: auditDigest("identity", subject),
+            sessionDigest: auditDigest("session", `telegram:${subject}`),
+            argumentDigest: auditDigest("argument", message.text),
+        } : {};
+        const lifecycleStartedAt = Date.now();
+        const lifecycleMeta = (event, meta, lifecycleAt) => acceptanceMarker
+            ? { ...meta, lifecycleAt, lifecycleMac: sanctuaryTelegramAuditLifecycleMac(identityKey, acceptanceSchema, event, { ...meta, lifecycleAt }) }
+            : meta;
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.telegram_turn_start",
+            message: "Telegram authorized turn started",
+            meta: lifecycleMeta("senses.telegram_turn_start", { agentName: options.agentName, subject, ...acceptanceMeta, ...lifecycleCoordinates }, lifecycleStartedAt),
+        });
+        acceptanceAuditBarrier();
+        const deliveredMessageIds = [];
+        const deliveredChunks = [];
+        let receiptStatus = "success";
+        let errorCategory = null;
+        const turnMetricsObserver = { providerInvocationCount: 0, toolInvocationCount: 0 };
+        const toolReceiptObserver = { toolResultDigests: [], toolGroundings: [] };
+        const normalizedRequest = message.text.normalize("NFKC").trim().toLocaleLowerCase("en-US");
+        const exactDownloadCreditQuestion = normalizedRequest === "why aren't my shows downloading?";
+        const groundingIntentTool = groundedAcceptance
+            ? /^(?:what['’]?s up|status)\??$/u.test(normalizedRequest) ? "unraid_get_system"
+                : /^how much (?:space|storage) is left\??$/u.test(normalizedRequest) ? "unraid_get_storage"
+                    : null
+            : null;
+        const bufferedGroundedDeliveries = [];
+        const turnEffects = [];
+        let deliveryOrdinal = 0;
+        await recoverEffectOutbox();
+        let ingressRelations = { replyToEventId: null, threadRootEventId: null, references: [inboundReference] };
+        if (message.replyToMessageId && /^[1-9][0-9]*$/u.test(message.replyToMessageId)) {
+            const replyMessageId = Number(message.replyToMessageId);
+            const reply = (0, telegram_effect_adapter_1.resolveTelegramReply)(getEffectJournal(), { messageId: replyMessageId, friendId: currentFriendId, sessionKey: currentSessionKey });
+            const session = reply ? (0, session_events_1.loadSessionEnvelopeFile)(currentSessionPath) : null;
+            if (reply && session?.events.some((event) => event.id === reply.sessionEventId))
+                ingressRelations = {
+                    replyToEventId: reply.sessionEventId,
+                    threadRootEventId: null,
+                    references: [inboundReference, `telegram-artifact:${reply.artifactId}`, ...(reply.requestId ? [`request:${reply.requestId}`] : [])],
+                };
+        }
+        try {
+            acceptanceAuditBarrier();
+            const ingressReceipt = options.resolveRelationshipAuthorization
+                ? await (0, telegram_effect_adapter_1.recordTelegramEffectsInSession)({
+                    store: getEffectJournal(),
+                    sessionPath: currentSessionPath,
+                    artifacts: [],
+                    inbound: { text: message.text, reference: inboundReference, attachmentIds: hydrated.attachmentIds, relations: ingressRelations },
+                })
+                : null;
+            const fullVisibility = createFullVisibilityProgress();
+            const collected = await collectToolReceipts(() => runTurn({
+                agentName: options.agentName,
+                channel: "telegram",
+                sessionKey: currentSessionKey,
+                friendId: currentFriendId,
+                identity: {
+                    provider: "telegram-user",
+                    externalId: options.admission ? message.userId : subject,
+                    displayName: options.admission ? "Ari" : `Telegram user ${subject}`,
+                    ...(options.admission ? { tenantId: botId } : {}),
+                },
+                userMessage: message.text,
+                ingressRelations,
+                ...(ingressReceipt ? { precommittedIngress: ingressReceipt } : {}),
+                turnMetricsObserver,
+                emptyResponseFallback: fullVisibility.emptyResponseFallback,
+                deliverySink: {
+                    onDelivery: async (delivery) => {
+                        if (groundingIntentTool) {
+                            bufferedGroundedDeliveries.push(delivery.kind);
+                        }
+                        else {
+                            turnEffects.push(await deliverButlerEffect(delivery.text, `turn:${subject}:${message.updateId}:delivery:${deliveryOrdinal++}`, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); }, exactDownloadCreditQuestion));
+                        }
+                    },
+                },
+                ...(toolContext || options.resolveRelationshipAuthorization ? {
+                    toolContext: { ...(toolContext ?? {}), ...(options.resolveRelationshipAuthorization ? { attachmentIds: hydrated.attachmentIds } : {}) },
+                } : {}),
+                ...(options.resolveRelationshipAuthorization ? {
+                    prepareRunAgentOptions: prepareRelationshipRunAgentOptions({
+                        friendId: currentFriendId,
+                        requestId: inboundReference,
+                        sessionEventId: ingressReceipt.eventId,
+                        userId: message.userId,
+                        chatId: message.chatId,
+                        sessionKey: currentSessionKey,
+                        userMessage: message.text,
+                        fullVisibilityProgress: fullVisibility.progress,
+                    }),
+                } : {}),
+                ...(approvalRuntime ? { approvalCoordinatorFactory: approvalRuntime.coordinator } : {}),
+            }), toolReceiptObserver);
+            const result = collected.result;
+            let responseFallbackArtifactId;
+            turnMetricsObserver.providerInvocationCount = Math.max(turnMetricsObserver.providerInvocationCount, result.providerInvocationCount ?? 0);
+            turnMetricsObserver.toolInvocationCount = Math.max(turnMetricsObserver.toolInvocationCount, result.toolInvocationCount ?? 0);
+            if (groundingIntentTool) {
+                const grounding = toolReceiptObserver.toolGroundings?.length === 1 ? toolReceiptObserver.toolGroundings[0] : undefined;
+                if (!grounding || grounding.toolName !== groundingIntentTool || bufferedGroundedDeliveries.length > 1
+                    || (bufferedGroundedDeliveries.length === 1 && bufferedGroundedDeliveries[0] !== "settle"))
+                    throw new Error("Canonical Sanctuary query did not produce exactly one matching grounded settle");
+                const canonical = (0, sanctuary_grounding_1.renderSanctuaryGroundedResponse)(grounding.toolName, grounding.facts);
+                turnEffects.push(await deliverButlerEffect(canonical, `turn:${subject}:${message.updateId}:delivery:${deliveryOrdinal++}`, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); }));
+            }
+            else {
+                const responseFallback = responseFallbackAfterDeliveries(result, turnEffects.length);
+                if (responseFallback) {
+                    const artifact = await deliverButlerEffect(responseFallback, `turn:${subject}:${message.updateId}:delivery:${deliveryOrdinal++}`, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); }, exactDownloadCreditQuestion);
+                    turnEffects.push(artifact);
+                    responseFallbackArtifactId = artifact.id;
+                }
+            }
+            if (result.sessionPath) {
+                const causalEventIds = Object.fromEntries((groundingIntentTool ? [] : turnEffects).flatMap((artifact, index) => {
+                    const eventId = result.causalSessionEventIds?.[index];
+                    if (eventId)
+                        return [[artifact.id, eventId]];
+                    return artifact.id === responseFallbackArtifactId && result.responseCausalSessionEventId
+                        ? [[artifact.id, result.responseCausalSessionEventId]]
+                        : [];
+                }));
+                await recordAcceptedEffects(result.sessionPath, turnEffects, undefined, causalEventIds);
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.telegram_turn_end",
+                message: "Telegram authorized turn completed",
+                meta: lifecycleMeta("senses.telegram_turn_end", { agentName: options.agentName, subject, deliveryCount: turnEffects.length, ...acceptanceMeta, ...lifecycleCoordinates, ...(acceptanceMarker ? { outcome: "success", errorDigest: null } : {}) }, Math.max(Date.now(), lifecycleStartedAt + 1)),
+            });
+        }
+        catch (error) {
+            receiptStatus = "error";
+            errorCategory = (error instanceof Error && error.name.trim() ? error.name : "unknown").slice(0, 128);
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.telegram_turn_error",
+                message: "Telegram authorized turn failed",
+                meta: lifecycleMeta("senses.telegram_turn_error", {
+                    agentName: options.agentName,
+                    subject,
+                    ...acceptanceMeta,
+                    ...lifecycleCoordinates,
+                    ...(acceptanceMarker ? {
+                        outcome: "error",
+                        errorDigest: auditDigest("error", redactTelegramPrivateValues(error, [botToken, authorizedUserId, authorizedChatId, String(message.updateId), message.messageId])),
+                        deliveryCount: deliveredMessageIds.length,
+                    } : { error: redactTelegramPrivateValues(error, [botToken, authorizedUserId, authorizedChatId, String(message.updateId), message.messageId]) }),
+                }, Math.max(Date.now(), lifecycleStartedAt + 1)),
+            });
+            const fallback = "I couldn't complete that turn. The failure was recorded; please try again.";
+            if (deliveredMessageIds.length === 0)
+                turnEffects.push(await deliverButlerEffect(fallback, `turn:${subject}:${message.updateId}:fallback`, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); }, exactDownloadCreditQuestion));
+            await recordAcceptedEffects(currentSessionPath, turnEffects, { text: message.text, reference: inboundReference, attachmentIds: hydrated.attachmentIds });
+        }
+        finally {
+            if (acceptanceMarker) {
+                acceptanceAuditBarrier();
+                const grounded = groundedAcceptance;
+                const schemaVersion = grounded ? "sanctuary-telegram-turn-receipt-v4" : "sanctuary-telegram-turn-receipt-v3";
+                const hmac = (purpose, value) => sanctuaryTelegramTurnReceiptDigest(identityKey, schemaVersion, purpose, value);
+                const redact = (value) => [botToken, authorizedUserId, authorizedChatId, String(message.updateId), message.messageId]
+                    .reduce((text, privateValue) => privateValue.length >= 5 ? text.replaceAll(privateValue, "[REDACTED]") : text, value);
+                const deliveries = deliveredMessageIds.map((messageId, index) => {
+                    const chunk = deliveredChunks[index];
+                    const redactedText = redact(chunk);
+                    return { messageIdDigest: hmac("delivery", String(messageId)), chunkDigest: hmac("chunk", grounded ? redactedText : chunk), ...(grounded ? { redactedText, utf16Units: redactedText.length } : {}) };
+                });
+                try {
+                    const receipt = {
+                        schemaVersion,
+                        scenarioHandleDigest: acceptanceMarker.scenarioHandleDigest,
+                        status: receiptStatus,
+                        errorCategory,
+                        updateDigest: hmac("update", `${message.updateId}\0${message.messageId}`),
+                        sequenceDigest: hmac("sequence", String(message.updateId)),
+                        responseDigest: hmac("response", JSON.stringify(deliveries)),
+                        toolResultDigests: toolReceiptObserver.toolResultDigests,
+                        ...(grounded ? { toolGroundings: toolReceiptObserver.toolGroundings } : {}),
+                        providerInvocationCount: turnMetricsObserver.providerInvocationCount,
+                        toolInvocationCount: turnMetricsObserver.toolInvocationCount,
+                        deliveryCount: deliveries.length,
+                        deliveries,
+                        completedAt: new Date().toISOString(),
+                    };
+                    if (grounded)
+                        receipt.receiptMac = sanctuaryTelegramTurnReceiptMac(identityKey, receipt);
+                    await appendSanctuaryTurnReceipt(options.acceptanceReceiptRoot ?? agentRoot, receipt, options._afterAcceptanceLedgerPreReadStat);
+                }
+                catch (error) {
+                    (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.telegram_acceptance_receipt_error", message: "Telegram acceptance receipt persistence failed", meta: { agentName: options.agentName, scenarioHandleDigest: acceptanceMarker.scenarioHandleDigest, category: error instanceof Error ? error.name : "unknown" } });
+                }
+            }
+        }
+    };
+    const onMessage = (message) => runWithAcceptanceAuditOwner(async () => {
+        const ownerDecision = !message.attachments?.length && !message.attachmentNotices?.length ? admissionController?.parseOwnerDecision({
+            text: message.text,
+            ...(message.replyToMessageId ? { replyToMessageId: Number(message.replyToMessageId) } : {}),
+        }) : null;
+        if (ownerDecision) {
+            const actor = await options.admission?.resolveOwner({ botId: botId, userId: message.userId, chatId: message.chatId, sessionKey: configuredOwnerSessionKey });
+            if (!actor)
+                throw new Error("Telegram admission owner decision identity is invalid");
+            await admissionController.decide({ ...ownerDecision, actorFriendId: actor.friendId });
+            return;
+        }
+        if ((message.attachments?.length || message.attachmentNotices?.length) && options.admission) {
+            const actor = await options.admission.resolveOwner({ botId: botId, userId: message.userId, chatId: message.chatId, sessionKey: configuredOwnerSessionKey });
+            if (!actor || actor.friendId !== configuredOwnerFriendId)
+                throw new Error("Telegram attachment owner relationship is not active");
+        }
+        await onMessageBody(message);
+    });
+    const onUnknownMessage = admissionController && options.admission ? async (message) => {
+        const approved = await options.admission.resolveApprovedFriend(message);
+        if (!approved) {
+            await admissionController.handleUnknown(message);
+            return;
+        }
+        const hydrated = await hydrateAuthorizedMessage({
+            updateId: message.updateId,
+            messageId: String(message.messageId),
+            userId: message.userId,
+            chatId: message.chatId,
+            text: message.text,
+            attachments: message.attachments,
+            attachmentNotices: message.attachmentNotices,
+        });
+        const sessionKey = `telegram:${message.botId}:${message.userId}`;
+        const reference = `telegram-inbound:${(0, node_crypto_1.createHmac)("sha256", identityKey).update(`${message.botId}\0${message.userId}\0${message.updateId}\0${message.messageId}`).digest("hex")}`;
+        const sessionPath = (0, shared_turn_1.getSenseSessionPath)(options.agentName, approved.friendId, "telegram", sessionKey, agentRoot);
+        const receipt = await (0, telegram_effect_adapter_1.recordTelegramEffectsInSession)({ store: getEffectJournal(), sessionPath, artifacts: [], inbound: { text: hydrated.text, reference, attachmentIds: hydrated.attachmentIds } });
+        await dispatchResolvedRelationshipTurn({ friendId: approved.friendId, sessionKey, requestId: reference, eventId: receipt.eventId,
+            reference, text: hydrated.text, attachmentIds: hydrated.attachmentIds, userId: message.userId, chatId: message.chatId });
+    } : undefined;
+    const onUpdate = async (update) => {
+        const callback = update.callback_query;
+        if (callback?.data?.startsWith("admit:") && admissionController && callback.message) {
+            return runWithAcceptanceAuditOwner(async () => {
+                const actor = await options.admission?.resolveOwner({ botId: botId, userId: String(callback.from.id), chatId: String(callback.message.chat.id), sessionKey: configuredOwnerSessionKey });
+                if (!actor)
+                    throw new Error("Telegram admission owner callback identity is invalid");
+                const decision = admissionController.parseCallback(callback.data, callback.message.message_id);
+                await admissionController.decide({ ...decision, actorFriendId: actor.friendId });
+                const ownerTarget = configuredOwnerTarget();
+                const artifact = await executeAuthorizedEffect({
+                    idempotencyKey: `admission-callback:${callback.id}`,
+                    target: { ...ownerTarget, requestId: decision.admissionId },
+                    authorClass: "control",
+                    effect: { kind: "callback_ack", callbackQueryId: callback.id },
+                });
+                await recordAcceptedEffects((0, shared_turn_1.getSenseSessionPath)(options.agentName, ownerTarget.friendId, "telegram", ownerTarget.sessionKey, agentRoot), [artifact]);
+                return true;
+            });
+        }
+        if (!callback || !approvalTransport)
+            return false;
+        return runWithAcceptanceAuditOwner(async () => (await approvalTransport.handleUpdate(update)).handled);
+    };
+    let poll;
+    try {
+        poll = (options.createLongPoll ?? telegram_client_1.createTelegramLongPoll)({
+            api,
+            expectedUserId: authorizedUserId,
+            expectedChatId: authorizedChatId,
+            ...(onUnknownMessage ? { botId: botId, onUnknownMessage } : {}),
+            offsetStore,
+            inboxStore,
+            onMessage,
+            onUpdate,
+            acceptanceEventMeta: (update, distinctAccount) => {
+                const marker = options.acceptanceMarker ? options.acceptanceMarker() : (0, sanctuary_acceptance_marker_1.readSanctuaryAcceptanceMarker)(options.agentName);
+                if (!marker)
+                    return {};
+                const auditOwnerMeta = acceptanceAuditLease ? { acceptanceAuditOwnerDigest: acceptanceAuditLease.ownerDigest } : {};
+                const messageId = update?.message?.message_id ?? update?.callback_query?.message?.message_id;
+                const senderId = update?.message?.from?.id;
+                if (!update || messageId === undefined || senderId === undefined)
+                    return { scenarioHandleDigest: marker.scenarioHandleDigest, ...auditOwnerMeta };
+                const schemaVersion = marker.label === "unit-16d-whats-up" || marker.label === "unit-16d-1-space"
+                    ? "sanctuary-telegram-turn-receipt-v4" : "sanctuary-telegram-turn-receipt-v3";
+                const digest = (purpose, value) => sanctuaryTelegramTurnReceiptDigest(identityKey, schemaVersion, purpose, value);
+                const senderDistinct = String(senderId) !== authorizedUserId;
+                if (distinctAccount !== senderDistinct)
+                    throw new Error("Telegram dropped-update identity classification mismatch");
+                const binding = {
+                    scenarioHandleDigest: marker.scenarioHandleDigest,
+                    updateDigest: digest("update", `${update.update_id}\0${messageId}`),
+                    senderIdentityDigest: digest("sender-identity", String(senderId)),
+                    authorizedIdentityDigest: digest("sender-identity", authorizedUserId),
+                    senderDistinct,
+                    nextOffsetDigest: digest("next-update-id", String(update.update_id + 1)),
+                };
+                return { ...binding, ...auditOwnerMeta, dropMac: sanctuaryTelegramUnauthorizedDropMac(identityKey, schemaVersion, binding) };
+            },
+            onBeforeDispatch: acceptanceAuditBarrier,
+            onDispatchSettled: acceptanceAuditBarrier,
+        });
+    }
+    catch (error) {
+        releaseAcceptanceAudit(error);
+    }
+    return {
+        run(signal) {
+            if (runPromise)
+                return runPromise;
+            runPromise = (async () => {
+                await runWithAcceptanceAuditOwner(migrateIdentity);
+                inboxStore.quarantineStrandedAdmittedWork?.();
+                await runWithAcceptanceAuditOwner(async () => { await admissionController?.recover(); });
+                await runWithAcceptanceAuditOwner(recoverEffectOutbox);
+                await runWithAcceptanceAuditOwner(reconcileSystemFailsafes);
+                try {
+                    await runWithAcceptanceAuditOwner(async () => { await toolContext?.sanctuary?.recoverRoutineActions?.(); });
+                }
+                catch (error) {
+                    (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.sanctuary_routine_recovery_error", message: "Sanctuary routine action recovery requires inspection", meta: { agentName: options.agentName, subject, category: error instanceof Error ? error.name : "unknown" } });
+                }
+                await runWithAcceptanceAuditOwner(async () => { await approvalRuntime?.recover(); });
+                await runWithAcceptanceAuditOwner(async () => { await interactiveControl?.start(); });
+                try {
+                    await runWithAcceptanceAuditOwner(async () => { await approvalTransport?.reconcileExpired(); });
+                }
+                catch (error) {
+                    acceptanceAuditBarrier();
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "error",
+                        component: "senses",
+                        event: "senses.telegram_approval_reconcile_error",
+                        message: "Telegram approval expiry reconciliation failed",
+                        meta: { agentName: options.agentName, subject, error: transportError(error) },
+                    });
+                }
+                (0, runtime_1.emitNervesEvent)({
+                    component: "senses",
+                    event: "senses.telegram_poll_start",
+                    message: "Telegram long poll started",
+                    meta: { agentName: options.agentName, subject },
+                });
+                approvalReconciliationActive = true;
+                nextApprovalReconcileDeadline = undefined;
+                scheduleApprovalReconcile();
+                try {
+                    await poll.run(signal);
+                }
+                finally {
+                    approvalReconciliationActive = false;
+                    nextApprovalReconcileDeadline = undefined;
+                    clearApprovalReconcileTimer();
+                    await Promise.all([...approvalReconciliationsInFlight]);
+                    try {
+                        await runWithAcceptanceAuditOwner(async () => { await approvalTransport?.reconcileExpired(); });
+                    }
+                    catch (error) {
+                        acceptanceAuditBarrier();
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "error",
+                            component: "senses",
+                            event: "senses.telegram_approval_reconcile_error",
+                            message: "Telegram approval expiry reconciliation failed",
+                            meta: { agentName: options.agentName, subject, error: transportError(error) },
+                        });
+                    }
+                    await interactiveControl?.stop();
+                }
+            })();
+            return runPromise;
+        },
+        async sendProactive(text, signal) {
+            await runWithAcceptanceAuditOwner(async () => {
+                const effect = await deliverButlerEffect(requiredText(text, "proactive message"), `proactive:${(0, node_crypto_1.randomUUID)()}`, signal);
+                const sessionPath = (0, shared_turn_1.getSenseSessionPath)(options.agentName, configuredOwnerFriendId, "telegram", configuredOwnerSessionKey, agentRoot);
+                await recordAcceptedEffects(sessionPath, [effect]);
+            });
+        },
+        async sendExternalEventDecision(input) {
+            const source = requiredText(input.source, "external event source");
+            const eventId = requiredText(input.eventId, "external event id");
+            if (Buffer.byteLength(source) > 512 || Buffer.byteLength(eventId) > 512 || !Number.isSafeInteger(input.generation) || input.generation < 1)
+                throw new Error("Telegram external event identity is invalid");
+            await runWithAcceptanceAuditOwner(async () => {
+                const receiptIdentity = JSON.stringify([source, eventId, input.generation]);
+                const effect = await deliverButlerEffect(requiredText(input.text, "external event decision"), `external-event:${receiptIdentity}`, input.signal);
+                const sessionPath = (0, shared_turn_1.getSenseSessionPath)(options.agentName, configuredOwnerFriendId, "telegram", configuredOwnerSessionKey, agentRoot);
+                await recordAcceptedEffects(sessionPath, [effect]);
+            });
+        },
+        async sendAwaitFollowUp(request) {
+            return runWithAcceptanceAuditOwner(() => deliverAwaitFollowUp(request));
+        },
+        stop() {
+            if (stopPromise)
+                return stopPromise;
+            stopPromise = (async () => {
+                const errors = [];
+                const attempt = async (operation) => {
+                    try {
+                        await operation();
+                    }
+                    catch (error) {
+                        errors.push(error);
+                    }
+                };
+                await attempt(() => poll.stop());
+                await attempt(async () => { await runPromise?.catch(() => undefined); });
+                await attempt(async () => { await Promise.all([...approvalReconciliationsInFlight]); });
+                await attempt(async () => { await interactiveControl?.stop(); });
+                await attempt(() => api.stop());
+                await attempt(() => approvalRuntime?.close());
+                await attempt(() => effectJournal?.close());
+                await attempt(() => admissionStore?.close());
+                await attempt(() => (0, tools_awaiting_1.resetAwaitToolDeps)());
+                await attempt(() => runWithAcceptanceAuditOwner(() => {
+                    (0, runtime_1.emitNervesEvent)({
+                        component: "senses",
+                        event: "senses.telegram_poll_end",
+                        message: "Telegram long poll stopped",
+                        meta: { agentName: options.agentName, subject },
+                    });
+                }));
+                await attempt(retireAcceptanceAudit);
+                if (errors.length === 1)
+                    throw errors[0];
+                if (errors.length > 1)
+                    throw new AggregateError(errors, "Telegram sense cleanup failed");
+            })();
+            return stopPromise;
+        },
+    };
+}
+function loadTelegramSenseCredentials(agentName) {
+    const runtime = (0, runtime_credentials_1.readRuntimeCredentialConfig)(agentName);
+    if (!runtime.ok) {
+        throw new Error(`Telegram runtime config is ${runtime.reason}; actor: agent-runnable; run ouro connect telegram --agent ${agentName}`);
+    }
+    return parseTelegramSenseCredentials(runtime.config);
+}
+async function createProductionTelegramRelationshipComposition(agentName, credentials, agentRootOverride) {
+    const agentRoot = agentRootOverride ?? (0, identity_1.getAgentRoot)(agentName);
+    const botId = canonicalTelegramId(credentials.botId ?? telegramBotIdFromToken(credentials.botToken), "bot id");
+    const ownerUserId = canonicalTelegramId(credentials.authorizedUserId, "authorized user id");
+    const ownerChatId = canonicalTelegramId(credentials.authorizedChatId, "authorized chat id");
+    if (ownerUserId !== ownerChatId)
+        throw new Error("Telegram owner relationship requires a private user-bound chat");
+    const ownerSessionKey = `telegram:${opaqueTelegramSubject(readOrCreateTelegramIdentityKey(agentRoot), botId, ownerUserId, ownerChatId)}`;
+    const store = new friends_1.FileFriendStore(path.join(agentRoot, "friends"));
+    const sameBotTelegramBindings = (friend) => friend.externalIds.filter((external) => external.provider === "telegram-user" && external.tenantId === botId);
+    const exactTelegramIdentity = (friend, userId) => {
+        const bindings = sameBotTelegramBindings(friend);
+        return bindings.length === 1 && /^[1-9][0-9]*$/u.test(bindings[0].externalId) && bindings[0].externalId === userId;
+    };
+    const canonicalOwner = (friend) => Boolean(friend
+        && exactTelegramIdentity(friend, ownerUserId) && friend.admissionState === "active" && friend.trustLevel === "family"
+        && friend.initiativePolicy === "proactive" && friend.capabilityProfileId === "sanctuary-owner");
+    const canonicalHousehold = (friend, userId) => Boolean(friend
+        && exactTelegramIdentity(friend, userId) && friend.admissionState === "active" && friend.trustLevel === "friend"
+        && friend.initiativePolicy === "request_follow_up_only" && friend.capabilityProfileId === "sanctuary-household");
+    const owner = await store.findByExternalId("telegram-user", ownerUserId, botId);
+    if (!owner || !canonicalOwner(owner)) {
+        throw new Error("Telegram owner Friend must be active with the sanctuary-owner profile and exact bot identity");
+    }
+    const registry = (0, relationship_authorization_1.loadRelationshipCapabilityRegistry)(agentRoot);
+    if (!registry.profiles["sanctuary-owner"] || !registry.profiles["sanctuary-household"]) {
+        throw new Error("Telegram relationship capability registry is missing canonical profiles");
+    }
+    const assertLiveOwner = async (actorFriendId) => {
+        const current = await store.get(owner.id);
+        if (actorFriendId !== owner.id || !canonicalOwner(current))
+            throw new Error("Only the live Telegram owner may manage contacts");
+    };
+    const admissionsRoot = path.join(agentRoot, "state", "senses", "telegram", "admissions");
+    const invalidatePendingApprovals = (sessionPath) => {
+        const stateRoot = path.join(agentRoot, "state", "approvals");
+        const checkpoints = new approval_files_1.FileApprovalCheckpointStore(path.join(stateRoot, "checkpoints.json"));
+        const tokens = new approval_files_1.FileApprovalTokenStore(path.join(stateRoot, "tokens.json"));
+        const approvals = (0, approval_store_1.openApprovalStore)({ databasePath: path.join(stateRoot, "approvals.sqlite") });
+        try {
+            for (const checkpoint of checkpoints.list()) {
+                const approval = approvals.read(checkpoint.approvalId);
+                if (!approval || path.resolve(approval.sessionPath) !== path.resolve(sessionPath))
+                    continue;
+                const decisionToken = tokens.get(checkpoint.approvalId);
+                if (approval.state === "preparing")
+                    approvals.recoverPreparing({ approvalId: approval.approvalId, state: "abandoned_before_attempt", reason: "requesting relationship was revoked" });
+                else if (approval.state === "awaiting_prompt_binding")
+                    approvals.abandonPromptBinding({ approvalId: approval.approvalId, reason: "requesting relationship was revoked" });
+                else if (approval.state === "proposed" && decisionToken)
+                    approvals.decide({
+                        approvalId: approval.approvalId, decisionToken, decision: "deny", requesterId: approval.requesterId,
+                        transport: approval.transport, transportUserId: approval.transportUserId, transportChatId: approval.transportChatId,
+                        transportMessageId: approval.transportMessageId, sessionKey: approval.sessionKey, ownerId: `relationship-revocation-${(0, node_crypto_1.randomUUID)()}`,
+                    });
+                else if (approval.state === "proposed")
+                    throw new Error(`Cannot revoke relationship while approval ${approval.approvalId} is missing its decision token`);
+                else if (approval.state === "claimed" && approval.ownerId)
+                    approvals.abandonBeforeAttempt({ approvalId: approval.approvalId, ownerId: approval.ownerId, epoch: approval.epoch, reason: "requesting relationship was revoked" });
+                else if (approval.state === "claimed")
+                    throw new Error(`Cannot revoke relationship while approval ${approval.approvalId} is missing its claim owner`);
+                const terminal = approvals.read(checkpoint.approvalId);
+                if (terminal && terminal.state !== "attempted")
+                    checkpoints.remove(checkpoint.approvalId);
+                tokens.remove(checkpoint.approvalId);
+            }
+        }
+        finally {
+            approvals.close();
+        }
+    };
+    const telegramContactManager = {
+        list: async ({ actorFriendId }) => {
+            await assertLiveOwner(actorFriendId);
+            const contacts = (await store.listAll()).flatMap((friend) => {
+                if (friend.id === owner.id)
+                    return [];
+                const bindings = sameBotTelegramBindings(friend);
+                if (bindings.length !== 1 || !/^[1-9][0-9]*$/u.test(bindings[0].externalId))
+                    return [];
+                return [{ friendId: friend.id, name: friend.name, userId: bindings[0].externalId, admissionState: friend.admissionState ?? "unverified", initiativePolicy: friend.initiativePolicy ?? "none" }];
+            }).slice(0, 256);
+            const admissions = new telegram_admission_1.FileTelegramAdmissionStore(admissionsRoot);
+            try {
+                const blocked = admissions.list().filter((record) => record.status === "blocked" && record.botId === botId)
+                    .slice(0, 256).map((record) => ({ admissionId: record.id, userId: record.userId, displayCode: record.displayCode, status: "blocked", createdAt: new Date(record.createdAt).toISOString() }));
+                return { contacts, blocked };
+            }
+            finally {
+                admissions.close();
+            }
+        },
+        revoke: async ({ actorFriendId, friendId }) => {
+            await assertLiveOwner(actorFriendId);
+            if (friendId === owner.id)
+                throw new Error("The Telegram owner relationship cannot revoke itself");
+            const current = await store.get(friendId);
+            if (!current)
+                throw new Error("Telegram contact was not found");
+            const bindings = sameBotTelegramBindings(current);
+            if (bindings.length !== 1 || !/^[1-9][0-9]*$/u.test(bindings[0].externalId) || bindings[0].externalId === ownerUserId)
+                throw new Error("Telegram contact identity is not exact");
+            const sessionKey = `telegram:${botId}:${bindings[0].externalId}`;
+            const sessionPath = (0, shared_turn_1.getSenseSessionPath)(agentName, current.id, "telegram", sessionKey, agentRoot);
+            await (0, session_transaction_1.withSessionTurnLease)(sessionPath, async () => {
+                invalidatePendingApprovals(sessionPath);
+                const live = await store.get(current.id);
+                if (!live || !exactTelegramIdentity(live, bindings[0].externalId))
+                    throw new Error("Telegram contact identity changed");
+                const { capabilityProfileId: _removedProfile, ...withoutProfile } = live;
+                await store.put(live.id, { ...withoutProfile, admissionState: "revoked", initiativePolicy: "none", updatedAt: new Date().toISOString() });
+                (0, tools_awaiting_1.cancelRelationshipFollowUps)(agentRoot, agentName, { friendId: live.id, channel: "telegram", key: sessionKey });
+            });
+            return { revoked: true, friendId };
+        },
+        unblock: async ({ actorFriendId, admissionId }) => {
+            await assertLiveOwner(actorFriendId);
+            const admissions = new telegram_admission_1.FileTelegramAdmissionStore(admissionsRoot);
+            try {
+                const record = admissions.read(admissionId);
+                if (record.botId !== botId || record.userId !== record.chatId)
+                    throw new Error("Blocked Telegram contact identity changed");
+                admissions.releaseBlock(admissionId);
+            }
+            finally {
+                admissions.close();
+            }
+            return { unblocked: true, admissionId };
+        },
+    };
+    const resolveEvaluator = async (input) => {
+        const friend = await store.get(input.friendId);
+        const ownerBound = friend?.id === owner.id;
+        const coordinatesValid = ownerBound
+            ? input.botId === botId && input.userId === ownerUserId && input.chatId === ownerChatId && input.sessionKey === ownerSessionKey
+            : input.botId === botId && input.userId === input.chatId && input.sessionKey === `telegram:${botId}:${input.userId}`;
+        if (!friend || !coordinatesValid || (ownerBound ? !canonicalOwner(friend) : !canonicalHousehold(friend, input.userId))) {
+            throw new Error("Telegram relationship identity binding is not active");
+        }
+        return (0, relationship_authorization_1.createRelationshipAuthorizationEvaluator)({
+            friend,
+            registry: (0, relationship_authorization_1.loadRelationshipCapabilityRegistry)(agentRoot),
+            requestId: input.requestId,
+            requestPhase: "inbound",
+            sessionEventId: input.sessionEventId,
+        });
+    };
+    const admission = {
+        ownerFriendId: owner.id,
+        resolveOwner: async ({ botId: candidateBotId, userId, chatId, sessionKey }) => {
+            if (candidateBotId !== botId || userId !== ownerUserId || chatId !== ownerChatId || sessionKey !== ownerSessionKey)
+                return null;
+            const exact = await store.findByExternalId("telegram-user", userId, botId);
+            const current = await store.get(owner.id);
+            return exact?.id === owner.id && canonicalOwner(current)
+                ? { friendId: owner.id }
+                : null;
+        },
+        resolveApprovedFriend: async ({ botId: candidateBotId, userId, chatId }) => {
+            if (candidateBotId !== botId || userId !== chatId)
+                return null;
+            const friend = await store.findByExternalId("telegram-user", userId, botId);
+            return friend && canonicalHousehold(friend, userId) ? { friendId: friend.id } : null;
+        },
+        claimFriend: async (input) => {
+            if (input.botId !== botId || input.userId !== input.chatId)
+                return { kind: "collision", reason: "Telegram identity is not bound to this bot and private chat" };
+            const claimed = await store.claimExternalId({
+                externalId: { provider: "telegram-user", externalId: input.userId, tenantId: botId, linkedAt: new Date().toISOString() },
+                target: { kind: "create", record: { id: (0, node_crypto_1.randomUUID)(), name: "Household member" } },
+            });
+            const current = claimed.record;
+            const now = new Date().toISOString();
+            const connections = input.relationship
+                ? [{ name: owner.name, relationship: input.relationship }, ...(current.connections ?? []).filter((connection) => !(connection.name === owner.name && connection.relationship === input.relationship))]
+                : current.connections;
+            const updated = { ...current,
+                ...(connections ? { connections } : {}),
+                trustLevel: input.defaults.trustLevel, admissionState: input.defaults.admissionState,
+                initiativePolicy: input.defaults.initiativePolicy, capabilityProfileId: input.defaults.capabilityProfileId, updatedAt: now };
+            await store.put(current.id, updated);
+            return { kind: claimed.status === "created" ? "created" : "existing", friendId: current.id };
+        },
+        revokeFriend: async (input) => {
+            if (input.botId !== botId || input.userId !== input.chatId)
+                return { kind: "collision", reason: "Telegram revocation identity is invalid" };
+            const current = await store.findByExternalId("telegram-user", input.userId, botId);
+            if (!current || current.id !== input.friendId || !exactTelegramIdentity(current, input.userId))
+                return { kind: "collision", reason: "Telegram revocation identity changed" };
+            const { capabilityProfileId: _removedProfile, ...withoutProfile } = current;
+            await store.put(current.id, { ...withoutProfile, admissionState: "revoked", initiativePolicy: "none", updatedAt: new Date().toISOString() });
+            (0, tools_awaiting_1.cancelRelationshipFollowUps)(agentRoot, agentName, { friendId: current.id, channel: "telegram", key: `telegram:${botId}:${input.userId}` });
+            return { kind: "revoked" };
+        },
+    };
+    return {
+        telegramContactManager,
+        admission,
+        resolveRelationshipAuthorization: resolveEvaluator,
+        authorizeRelationshipEffect: async (input) => {
+            if (input.target.kind !== "approved_relationship")
+                return { allowed: false, reason: "relationship effect target is required" };
+            const friend = await store.get(input.target.friendId);
+            if (!friend)
+                return { allowed: false, reason: "relationship admission is not active" };
+            const bindings = sameBotTelegramBindings(friend);
+            if (bindings.length !== 1 || !/^[1-9][0-9]*$/u.test(bindings[0].externalId))
+                return { allowed: false, reason: "relationship Telegram identity binding is unavailable" };
+            const chatId = bindings[0].externalId;
+            if (friend.id === owner.id ? !canonicalOwner(friend) : !canonicalHousehold(friend, chatId))
+                return { allowed: false, reason: "relationship admission is not active or canonical" };
+            if (friend.id === owner.id) {
+                if (chatId !== ownerUserId || chatId !== ownerChatId || input.target.sessionKey !== ownerSessionKey)
+                    return { allowed: false, reason: "owner Telegram identity or session binding changed" };
+            }
+            else if (input.target.sessionKey !== `telegram:${botId}:${chatId}`)
+                return { allowed: false, reason: "relationship Telegram session binding changed" };
+            const inboundIdempotency = input.target.requestId
+                ? new RegExp(`^relationship-turn:${input.target.requestId.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}:delivery:[0-9]+$`, "u").test(input.idempotencyKey)
+                : false;
+            const durableFollowUp = friend.id !== owner.id && input.target.requestId
+                ? (0, tools_awaiting_1.hasActiveRelationshipFollowUp)(agentRoot, { friendId: friend.id, channel: "telegram", key: input.target.sessionKey, requestId: input.target.requestId, allowElapsed: input.idempotencyKey.startsWith("await-expiry-follow-up:") })
+                : false;
+            if (friend.id !== owner.id && input.target.requestId && !inboundIdempotency && !durableFollowUp)
+                return { allowed: false, reason: "relationship follow-up is not bound to an active request await" };
+            const evaluator = (0, relationship_authorization_1.createRelationshipAuthorizationEvaluator)({
+                friend,
+                registry: (0, relationship_authorization_1.loadRelationshipCapabilityRegistry)(agentRoot),
+                ...(input.target.requestId ? { requestId: input.target.requestId, requestPhase: inboundIdempotency ? "inbound" : "follow_up" } : {}),
+            });
+            const scope = input.target.friendId === owner.id
+                ? (input.target.requestId ? "telegram.owner_event" : "telegram.proactive")
+                : "telegram.request_return";
+            const authorization = evaluator.authorizeEffect(scope);
+            return authorization.allowed
+                ? { allowed: true, receiptId: authorization.receiptId, expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(), transport: { chatId } }
+                : authorization;
+        },
+    };
+}
+async function startTelegramSenseApp(agentName) {
+    const loaded = loadTelegramSenseCredentials(agentName);
+    const credentials = { ...loaded, botId: telegramBotIdFromToken(loaded.botToken) };
+    const app = createTelegramSenseApp({
+        agentName,
+        credentials,
+        ...(await createProductionTelegramRelationshipComposition(agentName, credentials)),
+        ...(agentName === "sanctuary" ? { privilegedFailsafe: {
+                eventRoot: (0, router_1.getExternalEventRoot)(),
+                verifyProtectiveState: createSabQueueProtectiveStateVerifier(),
+            } } : {}),
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.telegram_app_ready",
+        message: "Telegram sense app is ready",
+        meta: { agentName },
+    });
+    return app;
+}
+async function sendTelegramExternalEventDecision(agentName, input) {
+    const app = await startTelegramSenseApp(agentName);
+    try {
+        await app.sendExternalEventDecision(input);
+    }
+    finally {
+        await app.stop();
+    }
+}
+async function sendTelegramAwaitFollowUp(agentName, request) {
+    const app = await startTelegramSenseApp(agentName);
+    try {
+        return await app.sendAwaitFollowUp(request);
+    }
+    finally {
+        await app.stop();
+    }
+}