@ouro.bot/cli 0.1.0-alpha.742 → 0.1.0-alpha.744

package/dist/senses/telegram.js

@@ -33,12 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 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;
@@ -46,7 +48,10 @@ 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");
@@ -58,12 +63,37 @@ 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_sab_1 = require("./sanctuary-sab");
 const shared_turn_1 = require("./shared-turn");
 const telegram_client_1 = require("./telegram-client");
 const sanctuary_runtime_1 = require("./sanctuary-runtime");
 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 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 SANCTUARY_SAB_CONFIG_PATH = "/run/sanctuary/sabnzbd.ini";
+function createSabQueueProtectiveStateVerifier(options = {}) {
+    let client = null;
+    return async (action) => {
+        client ??= (0, sanctuary_sab_1.createSanctuarySabClient)({ iniPath: options.iniPath ?? SANCTUARY_SAB_CONFIG_PATH, 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;
@@ -343,6 +373,12 @@ function canonicalTelegramId(value, label) {
         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) {
@@ -626,17 +662,23 @@ function parseTelegramSenseCredentials(value) {
 }
 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, botToken, authorizedUserId, authorizedChatId);
+    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_1.runWithSanctuaryToolReceiptCollection;
     const useSanctuaryRuntime = options.agentName === "sanctuary" && !options.runTurn;
@@ -781,12 +823,59 @@ function createTelegramSenseApp(options) {
         }
         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_1.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,
@@ -795,6 +884,7 @@ function createTelegramSenseApp(options) {
             subject,
             identityKey,
             toolContext: toolContext ?? {},
+            effects: approvalEffects,
             effectBarrier: acceptanceAuditBarrier,
             dependencies: {
                 acceptanceMarker: () => {
@@ -818,7 +908,6 @@ function createTelegramSenseApp(options) {
     catch (error) {
         releaseAcceptanceAudit(error);
     }
-    const healthSweep = options.healthSweep;
     const migrateIdentity = options.migrateIdentity ?? (async () => {
         const legacySubjects = new Set([
             ...readTelegramSubjectIndex(agentRoot, subject),
@@ -848,6 +937,7 @@ function createTelegramSenseApp(options) {
     let approvalReconciliationActive = false;
     const approvalReconciliationsInFlight = new Set();
     let nextApprovalReconcileDeadline;
+    let reconcileSystemFailsafes;
     let stopPromise;
     let runPromise;
     const clearApprovalReconcileTimer = () => {
@@ -877,46 +967,244 @@ function createTelegramSenseApp(options) {
                 approvalReconciliationsInFlight.delete(reconciliation);
             });
             approvalReconciliationsInFlight.add(reconciliation);
+            const failsafe = runWithAcceptanceAuditOwner(reconcileSystemFailsafes)
+                .finally(() => { approvalReconciliationsInFlight.delete(failsafe); });
+            approvalReconciliationsInFlight.add(failsafe);
         }, delay);
     };
-    const runHealthSweep = async () => {
-        if (!healthSweep)
-            return;
+    const deliverButlerEffect = async (text, idempotencyKey, signal, onMessageDelivered) => {
+        return executeAuthorizedEffect({
+            idempotencyKey,
+            target: configuredOwnerTarget(),
+            authorClass: "butler",
+            effect: { kind: "text", text },
+            ...(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" };
         try {
-            acceptanceAuditBarrier();
-            const result = await healthSweep();
-            if (result.message) {
-                acceptanceAuditBarrier();
-                if (result.deliveryId)
-                    await healthSweep.markDeliveryAttempting?.(result.deliveryId);
-                const messageIds = await deliver(result.message);
-                acceptanceAuditBarrier();
-                if (result.deliveryId)
-                    await healthSweep.markDelivered?.(result.deliveryId, messageIds);
-                (0, runtime_1.emitNervesEvent)({
-                    component: "senses",
-                    event: "senses.sanctuary_health_delivered",
-                    message: "Sanctuary health notification was delivered",
-                    meta: { agentName: options.agentName, deliveryCount: messageIds.length, ...(0, sanctuary_acceptance_marker_1.sanctuaryAcceptanceEventMeta)(options.agentName) },
-                });
-            }
+            const obligation = (0, obligations_1.findPendingObligationForRequest)(agentRoot, { requestId: request.requestId, owedTo: { friendId: request.friendId, channel: "telegram", key: request.key } });
+            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: request.key, 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", request.key, agentRoot), [artifact]);
+            return { status: "delivered_now", detail: "sent to the exact request-bound Telegram chat" };
         }
         catch (error) {
-            acceptanceAuditBarrier();
-            (0, runtime_1.emitNervesEvent)({
-                level: "error",
-                component: "senses",
-                event: "senses.sanctuary_health_error",
-                message: "Sanctuary deterministic health sweep failed",
-                meta: { agentName: options.agentName, subject, error: transportError(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 deliver = async (text, signal, onMessageDelivered) => {
-        acceptanceAuditBarrier();
-        return (0, telegram_client_1.sendTelegramText)(api, authorizedChatId, text, signal, onMessageDelivered);
+    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 }) => ({
+            ...runAgentOptions,
+            toolContext: { ...runAgentOptions.toolContext, relationshipAuthorization: await resolveLiveRelationshipAuthorization() },
+        });
+    };
+    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.",
+                },
+            }
+            : undefined;
+        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 ?? {}) },
+            prepareRunAgentOptions: prepareRelationshipRunAgentOptions({ friendId: input.friendId, requestId: input.requestId,
+                sessionEventId: input.eventId, userId: input.userId, chatId: input.chatId, sessionKey: input.sessionKey }),
+            deliverySink: { onDelivery: (delivery) => deliver(delivery.text, delivery.kind === "settle") },
+        });
+        if (effects.length === 0 && result.response.trim())
+            await deliver(result.response, true);
+        const causalEventIds = Object.fromEntries(effects.flatMap((artifact, index) => {
+            const eventId = result.causalSessionEventIds?.[index] ?? (effects.length === 1 ? 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 onMessageBody = async (message) => {
+        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";
@@ -950,23 +1238,51 @@ function createTelegramSenseApp(options) {
         const turnMetricsObserver = { providerInvocationCount: 0, toolInvocationCount: 0 };
         const toolReceiptObserver = { toolResultDigests: [], toolGroundings: [] };
         const normalizedRequest = message.text.normalize("NFKC").trim().toLocaleLowerCase("en-US");
-        const groundingIntentTool = /^(?:what['’]?s up|status)\??$/u.test(normalizedRequest) ? "unraid_get_system"
-            : /^how much (?:space|storage) is left\??$/u.test(normalizedRequest) ? "unraid_get_storage"
-                : null;
+        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, relations: ingressRelations },
+                })
+                : null;
             const collected = await collectToolReceipts(() => runTurn({
                 agentName: options.agentName,
                 channel: "telegram",
-                sessionKey: `telegram:${subject}`,
-                friendId: `telegram-user:${subject}`,
+                sessionKey: currentSessionKey,
+                friendId: currentFriendId,
                 identity: {
                     provider: "telegram-user",
-                    externalId: subject,
-                    displayName: `Telegram user ${subject}`,
+                    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,
                 deliverySink: {
                     onDelivery: async (delivery) => {
@@ -974,15 +1290,26 @@ function createTelegramSenseApp(options) {
                             bufferedGroundedDeliveries.push(delivery.kind);
                         }
                         else {
-                            await deliver(delivery.text, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); });
+                            turnEffects.push(await deliverButlerEffect(delivery.text, `turn:${subject}:${message.updateId}:delivery:${deliveryOrdinal++}`, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); }));
                             deliveryCount += 1;
                         }
                     },
                 },
                 ...(toolContext ? { toolContext } : {}),
+                ...(options.resolveRelationshipAuthorization ? {
+                    prepareRunAgentOptions: prepareRelationshipRunAgentOptions({
+                        friendId: currentFriendId,
+                        requestId: inboundReference,
+                        sessionEventId: ingressReceipt.eventId,
+                        userId: message.userId,
+                        chatId: message.chatId,
+                        sessionKey: currentSessionKey,
+                    }),
+                } : {}),
                 ...(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) {
@@ -991,11 +1318,24 @@ function createTelegramSenseApp(options) {
                     || (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);
-                await deliver(canonical, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); });
+                turnEffects.push(await deliverButlerEffect(canonical, `turn:${subject}:${message.updateId}:delivery:${deliveryOrdinal++}`, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); }));
                 deliveryCount = 1;
             }
             else if (deliveryCount === 0 && result.response.trim()) {
-                await deliver(result.response, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); });
+                const artifact = await deliverButlerEffect(result.response, `turn:${subject}:${message.updateId}:delivery:${deliveryOrdinal++}`, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); });
+                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",
@@ -1026,7 +1366,8 @@ function createTelegramSenseApp(options) {
             });
             const fallback = "I couldn't complete that turn. The failure was recorded; please try again.";
             if (deliveredMessageIds.length === 0)
-                await deliver(fallback, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); });
+                turnEffects.push(await deliverButlerEffect(fallback, `turn:${subject}:${message.updateId}:fallback`, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); }));
+            await recordAcceptedEffects(currentSessionPath, turnEffects, { text: message.text, reference: inboundReference });
         }
         finally {
             if (acceptanceMarker) {
@@ -1068,9 +1409,54 @@ function createTelegramSenseApp(options) {
             }
         }
     };
-    const onMessage = (message) => runWithAcceptanceAuditOwner(() => onMessageBody(message));
+    const onMessage = (message) => runWithAcceptanceAuditOwner(async () => {
+        const ownerDecision = admissionController?.parseOwnerDecision({
+            text: message.text,
+            ...(message.replyToMessageId ? { replyToMessageId: Number(message.replyToMessageId) } : {}),
+        });
+        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;
+        }
+        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 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: message.text, reference } });
+        await dispatchResolvedRelationshipTurn({ friendId: approved.friendId, sessionKey, requestId: reference, eventId: receipt.eventId,
+            reference, text: message.text, userId: message.userId, chatId: message.chatId });
+    } : undefined;
     const onUpdate = async (update) => {
-        if (!update.callback_query || !approvalTransport)
+        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);
     };
@@ -1080,6 +1466,7 @@ function createTelegramSenseApp(options) {
             api,
             expectedUserId: authorizedUserId,
             expectedChatId: authorizedChatId,
+            ...(onUnknownMessage ? { botId: botId, onUnknownMessage } : {}),
             offsetStore,
             inboxStore,
             onMessage,
@@ -1122,6 +1509,16 @@ function createTelegramSenseApp(options) {
                 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 {
@@ -1137,7 +1534,6 @@ function createTelegramSenseApp(options) {
                         meta: { agentName: options.agentName, subject, error: transportError(error) },
                     });
                 }
-                await runWithAcceptanceAuditOwner(runHealthSweep);
                 (0, runtime_1.emitNervesEvent)({
                     component: "senses",
                     event: "senses.telegram_poll_start",
@@ -1174,7 +1570,26 @@ function createTelegramSenseApp(options) {
             return runPromise;
         },
         async sendProactive(text, signal) {
-            await runWithAcceptanceAuditOwner(() => deliver(requiredText(text, "proactive message"), 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)
@@ -1195,6 +1610,9 @@ function createTelegramSenseApp(options) {
                 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",
@@ -1220,8 +1638,252 @@ function loadTelegramSenseCredentials(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 updated = { ...current, trustLevel: input.defaults.trustLevel, admissionState: input.defaults.admissionState,
+                initiativePolicy: input.defaults.initiativePolicy, capabilityProfileId: input.defaults.capabilityProfileId, updatedAt: new Date().toISOString() };
+            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 app = createTelegramSenseApp({ agentName, credentials: loadTelegramSenseCredentials(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",
@@ -1230,3 +1892,21 @@ async function startTelegramSenseApp(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();
+    }
+}