sneakoscope 7.3.0 → 7.6.0

package/dist/core/telegram/config.js

@@ -1,40 +1,71 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
-import { runProcess, sha256 } from '../fsx.js';
+import { runProcess, sha256, which } from '../fsx.js';
 import { isRecord } from '../json/records.js';
+const KEYCHAIN_READER_SWIFT = `import Foundation
+import Security
+let a=CommandLine.arguments[1],s=CommandLine.arguments[2]
+let q:[String:Any]=[kSecClass as String:kSecClassGenericPassword,kSecAttrAccount as String:a,kSecAttrService as String:s,kSecReturnData as String:true,kSecMatchLimit as String:kSecMatchLimitOne]
+var item:CFTypeRef?
+let r=SecItemCopyMatching(q as CFDictionary,&item)
+if r==errSecItemNotFound{exit(44)}
+guard r==errSecSuccess,let d=item as? Data,let v=String(data:d,encoding:.utf8) else{FileHandle.standardError.write(Data("keychain_status=\\(r)\\n".utf8));exit(1)}
+print(v)`;
 export function validateTelegramConfig(value) {
-    const issues = [];
+    const issues = telegramBaseConfigIssues(value);
     if (!isRecord(value))
         return { ok: false, issues: ['config_not_object'], config: null };
-    if (value.schema !== 'sks.telegram-config.v1')
-        issues.push('schema');
-    if ('bot_token' in value || 'token' in value)
-        issues.push('raw_bot_token_forbidden');
-    const secret = value.bot_token_ref;
-    if (!isRecord(secret) || !['keychain', 'external_file'].includes(String(secret.type || ''))) {
-        issues.push('bot_token_ref');
+    if (value.schema !== 'sks.telegram-config.v2') {
+        issues.push(value.schema === 'sks.telegram-config.v1'
+            ? 'telegram_identity_migration_required'
+            : 'telegram_config_schema_unsupported');
+        return { ok: false, issues, config: null };
     }
-    else if (secret.type === 'keychain') {
-        if (!nonEmpty(secret.service) || !nonEmpty(secret.account))
-            issues.push('keychain_reference_incomplete');
+    if (!isPositiveTelegramId(value.bot_user_id))
+        issues.push('bot_user_id');
+    if (!telegramFingerprint(value.bot_token_fingerprint))
+        issues.push('bot_token_fingerprint');
+    const pairedChatId = Array.isArray(value.paired_chat_ids) ? value.paired_chat_ids[0] : undefined;
+    const pairedUserId = Array.isArray(value.paired_user_ids) ? value.paired_user_ids[0] : undefined;
+    if (!isPositiveTelegramId(value.paired_chat_id) || value.paired_chat_id !== pairedChatId) {
+        issues.push('paired_chat_id');
     }
-    else if (secret.type === 'external_file') {
-        if (!nonEmpty(secret.path) || !path.isAbsolute(String(secret.path)))
-            issues.push('external_secret_path_must_be_absolute');
+    if (!isPositiveTelegramId(value.paired_user_id) || value.paired_user_id !== pairedUserId) {
+        issues.push('paired_user_id');
+    }
+    if (!Number.isSafeInteger(value.config_generation) || Number(value.config_generation) < 1) {
+        issues.push('config_generation');
+    }
+    if (!telegramFingerprint(value.identity_fingerprint)) {
+        issues.push('identity_fingerprint');
+    }
+    else if (issues.length === 0
+        && value.identity_fingerprint !== telegramIdentityFingerprint({
+            botUserId: String(value.bot_user_id),
+            botTokenFingerprint: String(value.bot_token_fingerprint),
+            pairedChatId: String(value.paired_chat_id),
+            pairedUserId: String(value.paired_user_id),
+            configGeneration: Number(value.config_generation)
+        })) {
+        issues.push('identity_fingerprint_mismatch');
     }
-    issues.push(...validateTelegramPrivatePairing(value).issues);
-    if (typeof value.long_poll_timeout_sec === 'number' && (value.long_poll_timeout_sec < 1 || value.long_poll_timeout_sec > 50))
-        issues.push('long_poll_timeout_sec');
-    if (typeof value.owner_stale_ms === 'number' && value.owner_stale_ms < 5_000)
-        issues.push('owner_stale_ms');
-    if ('mini_app' in value)
-        issues.push('mini_app_excluded_from_6_3_package');
     return {
         ok: issues.length === 0,
         issues,
         config: issues.length === 0 ? value : null
     };
 }
+export function readTelegramPreviousConfig(value) {
+    if (!isRecord(value))
+        return null;
+    if (value.schema === 'sks.telegram-config.v2') {
+        return validateTelegramConfig(value).config;
+    }
+    if (value.schema !== 'sks.telegram-config.v1')
+        return null;
+    const issues = telegramBaseConfigIssues(value);
+    return issues.length === 0 ? value : null;
+}
 export async function loadTelegramConfig(file) {
     const parsed = JSON.parse(await fsp.readFile(file, 'utf8'));
     const validation = validateTelegramConfig(parsed);
@@ -46,15 +77,10 @@ export async function resolveTelegramBotToken(ref, options = {}) {
     if (ref.type === 'keychain') {
         if (!ref.service || !ref.account)
             throw new Error('telegram_keychain_reference_incomplete');
-        if (process.platform !== 'darwin')
-            throw new Error('telegram_keychain_requires_macos');
-        const run = options.run ?? runProcess;
-        const result = await run('/usr/bin/security', [
-            'find-generic-password', '-w', '-s', ref.service, '-a', ref.account
-        ], { timeoutMs: 5_000, maxOutputBytes: 8 * 1024 });
-        if (result.code !== 0 || result.timedOut)
+        const token = await readTelegramKeychainToken(ref.service, ref.account, options);
+        if (token === null)
             throw new Error('telegram_keychain_lookup_failed');
-        return validateTelegramBotToken(result.stdout.trim());
+        return token;
     }
     if (!ref.path || !path.isAbsolute(ref.path))
         throw new Error('telegram_external_secret_path_invalid');
@@ -67,9 +93,76 @@ export async function resolveTelegramBotToken(ref, options = {}) {
         throw new Error('telegram_external_secret_permissions_must_be_0600');
     return validateTelegramBotToken((await fsp.readFile(ref.path, 'utf8')).trim());
 }
+export async function readTelegramKeychainToken(service, account, options = {}) {
+    if (!service.trim() || !account.trim())
+        throw new Error('telegram_keychain_reference_incomplete');
+    if (process.platform !== 'darwin')
+        throw new Error('telegram_keychain_requires_macos');
+    const run = options.run ?? runProcess;
+    const swift = options.swiftBin
+        ?? await which('swift').catch(() => null)
+        ?? '/usr/bin/swift';
+    const timeoutMs = Math.max(500, Math.min(30_000, options.timeoutMs ?? 5_000));
+    const result = await run(swift, ['-e', KEYCHAIN_READER_SWIFT, account, service], {
+        timeoutMs,
+        maxOutputBytes: 8 * 1024
+    });
+    if (result.code === 44 && !result.timedOut)
+        return null;
+    if (result.code !== 0 || result.timedOut)
+        throw new Error('telegram_keychain_lookup_failed');
+    return validateTelegramBotToken(result.stdout.trim());
+}
 export function telegramTokenFingerprint(token) {
     return `sha256:${sha256(token)}`;
 }
+export function telegramIdentityFingerprint(input) {
+    return `sha256:${sha256(JSON.stringify([
+        'sks.telegram-identity.v1',
+        input.botUserId,
+        input.botTokenFingerprint,
+        input.pairedChatId,
+        input.pairedUserId,
+        input.configGeneration
+    ]))}`;
+}
+export function telegramRuntimeIdentityFingerprint(config, botTokenFingerprint) {
+    if (config.bot_token_fingerprint !== botTokenFingerprint) {
+        throw new Error('telegram_config_token_identity_mismatch:run_setup_to_rotate_token');
+    }
+    return config.identity_fingerprint;
+}
+export function telegramConfigPairing(config) {
+    return {
+        chatId: config.paired_chat_id,
+        userId: config.paired_user_id
+    };
+}
+export function buildTelegramConfigV2(input) {
+    const identityFingerprint = telegramIdentityFingerprint({
+        botUserId: input.botUserId,
+        botTokenFingerprint: input.botTokenFingerprint,
+        pairedChatId: input.pairedChatId,
+        pairedUserId: input.pairedUserId,
+        configGeneration: input.configGeneration
+    });
+    return {
+        schema: 'sks.telegram-config.v2',
+        bot_token_ref: input.botTokenRef,
+        paired_chat_ids: [input.pairedChatId],
+        paired_user_ids: [input.pairedUserId],
+        bot_user_id: input.botUserId,
+        bot_token_fingerprint: input.botTokenFingerprint,
+        paired_chat_id: input.pairedChatId,
+        paired_user_id: input.pairedUserId,
+        config_generation: input.configGeneration,
+        identity_fingerprint: identityFingerprint,
+        ...(input.longPollTimeoutSec === undefined ? {} : { long_poll_timeout_sec: input.longPollTimeoutSec }),
+        ...(input.ownerStaleMs === undefined ? {} : { owner_stale_ms: input.ownerStaleMs }),
+        ...(input.protectContent === undefined ? {} : { protect_content: input.protectContent }),
+        ...(input.silentNotifications === undefined ? {} : { silent_notifications: input.silentNotifications })
+    };
+}
 export function validateTelegramBotToken(token) {
     if (!/^\d{5,}:[A-Za-z0-9_-]{20,}$/.test(token))
         throw new Error('telegram_bot_token_format_invalid');
@@ -98,7 +191,41 @@ function nonEmpty(value) {
     return typeof value === 'string' && value.trim().length > 0;
 }
 function positiveStringIdArray(value) {
-    return Array.isArray(value) && value.length > 0 && value.every(isPositiveTelegramId);
+    return Array.isArray(value) && value.length === 1 && value.every(isPositiveTelegramId);
+}
+function telegramFingerprint(value) {
+    return typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+}
+function telegramBaseConfigIssues(value) {
+    if (!isRecord(value))
+        return ['config_not_object'];
+    const issues = [];
+    if ('bot_token' in value || 'token' in value)
+        issues.push('raw_bot_token_forbidden');
+    const secret = value.bot_token_ref;
+    if (!isRecord(secret) || !['keychain', 'external_file'].includes(String(secret.type || ''))) {
+        issues.push('bot_token_ref');
+    }
+    else if (secret.type === 'keychain') {
+        if (!nonEmpty(secret.service) || !nonEmpty(secret.account))
+            issues.push('keychain_reference_incomplete');
+    }
+    else if (secret.type === 'external_file') {
+        if (!nonEmpty(secret.path) || !path.isAbsolute(String(secret.path))) {
+            issues.push('external_secret_path_must_be_absolute');
+        }
+    }
+    issues.push(...validateTelegramPrivatePairing(value).issues);
+    if (typeof value.long_poll_timeout_sec === 'number'
+        && (value.long_poll_timeout_sec < 1 || value.long_poll_timeout_sec > 50)) {
+        issues.push('long_poll_timeout_sec');
+    }
+    if (typeof value.owner_stale_ms === 'number' && value.owner_stale_ms < 5_000) {
+        issues.push('owner_stale_ms');
+    }
+    if ('mini_app' in value)
+        issues.push('mini_app_not_supported');
+    return issues;
 }
 function pairingFieldMissing(value, field) {
     return !(field in value) || (Array.isArray(value[field]) && value[field].length === 0);

package/dist/core/telegram/hub.js

@@ -1,7 +1,8 @@
 import crypto from 'node:crypto';
 import path from 'node:path';
-import { globalSksRoot, nowIso } from '../fsx.js';
+import { globalSksRoot, nowIso, sha256, writeTextAtomic } from '../fsx.js';
 import { TelegramBotApiClient, TelegramBotApiError } from './bot-api.js';
+import { TelegramIngressSpool } from './ingress-spool.js';
 import { TelegramActionBroker, TelegramAuditLedger, TelegramIdempotencyLedger, TelegramTopicRegistry } from './ledgers.js';
 import { TelegramOwnerLock } from './owner-lock.js';
 const COMMAND_POLICY = {
@@ -19,6 +20,7 @@ const COMMAND_POLICY = {
     '/open': { kind: 'read', risk: 'R0' }
 };
 const UI_POLICY = {
+    status: { command: '/status', kind: 'read', risk: 'R0' },
     open: { command: '/open', kind: 'read', risk: 'R0' },
     diff: { command: '/diff', kind: 'read', risk: 'R0' },
     proof: { command: '/proof', kind: 'read', risk: 'R0' },
@@ -37,23 +39,29 @@ export class TelegramHubRouter {
         this.commandRevision = options.commandRevision ?? 1;
         this.now = options.now ?? Date.now;
     }
-    async handleUpdate(update) {
+    async handleUpdate(update, options = {}) {
         const actor = actorFromUpdate(update);
         if (!actor || !this.isPaired(actor.chatId, actor.userId, actor.chatType)) {
             await this.audit(update, actor?.chatId ?? 'unknown', actor?.topicId ?? null, null, 'unpaired', 'rejected', 'not_paired');
             return result(false, 'not_paired');
         }
-        if (!await this.options.idempotency.claim(update.update_id)) {
+        if (!options.skipIdempotency && !await this.options.idempotency.claim(update.update_id)) {
             await this.audit(update, actor.chatId, actor.topicId, null, 'duplicate', 'rejected', 'duplicate_update_id');
             return result(false, 'duplicate_update_id');
         }
         const callback = update.callback_query;
         if (callback?.data?.startsWith('cb:')) {
+            const inspected = await this.options.actions.inspect(callback.data);
+            const currentRoute = inspected.action
+                ? await this.options.topics.findBySession(inspected.action.machine_id, inspected.action.project_id, inspected.action.session_id)
+                : null;
             const resolution = await this.options.actions.resolve({
                 callback_data: callback.data,
                 chat_id: actor.chatId,
                 message_thread_id: actor.topicId ?? 0,
+                route_generation: currentRoute?.generation ?? null,
                 revision: this.commandRevision,
+                update_id: update.update_id,
                 now: this.now()
             });
             await this.audit(update, actor.chatId, actor.topicId, callback.data.slice(3), 'callback', resolution.ok ? 'accepted' : 'rejected', resolution.status);
@@ -83,7 +91,7 @@ export class TelegramHubRouter {
             const prompt = policy.kind === 'input'
                 ? inputText(text, command, Boolean(staticUiAction))
                 : command || staticUiAction?.command || '';
-            const action = makeAction(route, policy.kind, policy.risk, prompt, this.commandRevision, this.now());
+            const action = makeAction(route, policy.kind, policy.risk, prompt, this.commandRevision, this.now(), update.update_id);
             if (action.risk === 'R2') {
                 const created = await this.options.actions.create(action, { chat_id: route.chat_id, message_thread_id: route.message_thread_id });
                 await this.audit(update, actor.chatId, actor.topicId, created.callback_data.slice(3), command, 'accepted', 'approval_required');
@@ -98,7 +106,7 @@ export class TelegramHubRouter {
         if (!text)
             return this.reject(update, actor, 'empty', 'unsupported_update');
         const forceReply = message?.reply_to_message?.message_id;
-        const action = makeAction(route, 'input', 'R1', text, this.commandRevision, this.now());
+        const action = makeAction(route, 'input', 'R1', text, this.commandRevision, this.now(), update.update_id);
         const authorization = authorizeTelegramAction(action.risk, { exactTopic: true, explicitUserMessage: true });
         if (!authorization.ok)
             return this.reject(update, actor, 'input', authorization.reason);
@@ -127,7 +135,9 @@ export class TelegramHubRouter {
             command_kind: commandKind,
             decision,
             policy_reason: policyReason,
-            effect_receipt: null
+            effect_receipt: null,
+            telegram_delivery: 'not_attempted',
+            telegram_delivery_receipt: null
         });
     }
 }
@@ -151,46 +161,269 @@ export class TelegramPollingHub {
     processor;
     ownerLock;
     longPollTimeoutSeconds;
+    options;
     offset = 0;
-    constructor(client, processor, ownerLock, longPollTimeoutSeconds = 25) {
+    offsetInitialized = false;
+    generation = crypto.randomUUID();
+    startedAt;
+    activeUpdateIds = new Set();
+    laneTails = new Map();
+    inFlight = new Set();
+    maxConflictRetries;
+    conflictBackoffMs;
+    maxPollRetries;
+    pollBackoffMs;
+    startupRequestTimeoutMs;
+    sleep;
+    now;
+    pid;
+    consecutiveConflicts = 0;
+    readyEstablished = false;
+    lastSuccessfulPollAt = null;
+    constructor(client, processor, ownerLock, longPollTimeoutSeconds = 25, options = {}) {
         this.client = client;
         this.processor = processor;
         this.ownerLock = ownerLock;
         this.longPollTimeoutSeconds = longPollTimeoutSeconds;
+        this.options = options;
+        this.maxConflictRetries = Math.max(0, options.maxConflictRetries ?? 3);
+        this.conflictBackoffMs = options.conflictBackoffMs?.length
+            ? options.conflictBackoffMs
+            : [1_000, 2_000, 5_000];
+        this.maxPollRetries = Math.max(0, options.maxPollRetries ?? 5);
+        this.pollBackoffMs = options.pollBackoffMs?.length
+            ? options.pollBackoffMs
+            : [1_000, 2_000, 5_000, 10_000, 30_000];
+        this.startupRequestTimeoutMs = Math.max(1_000, options.startupRequestTimeoutMs ?? 8_000);
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.now = options.now ?? Date.now;
+        this.pid = options.pid ?? process.pid;
+        this.startedAt = new Date(this.now()).toISOString();
     }
     async ensureLongPollingAllowed() {
         const info = await this.client.call('getWebhookInfo', {});
-        if (info?.url)
-            throw new Error('telegram_webhook_conflict');
+        if (typeof info?.url === 'string' && info.url.trim()) {
+            throw new Error('telegram_webhook_conflict:remove_webhook_before_long_polling');
+        }
     }
-    async pollOnce() {
+    async establishReadiness(signal) {
+        await this.ensureOffset();
+        await this.writeHealth('starting', null);
+        const result = await this.receiveBatch(0, false, this.startupRequestTimeoutMs, signal);
+        this.readyEstablished = result.ok && result.stopped_reason === null;
+        return { ok: result.ok, received: result.processed, stopped_reason: result.stopped_reason };
+    }
+    async pollOnce(options = {}) {
+        await this.ensureOffset();
+        const result = await this.receiveBatch(this.longPollTimeoutSeconds, true, undefined, options.signal);
+        if (!result.ok || result.stopped_reason === 'aborted')
+            return result;
+        if (options.awaitProcessing !== false) {
+            await this.waitForIdle();
+            await this.processor.tick?.();
+        }
+        else if (this.inFlight.size === 0) {
+            await this.processor.tick?.();
+        }
+        await this.ownerLock.heartbeat();
+        return result;
+    }
+    async run(signal) {
         try {
-            const updates = await this.client.getUpdates({ offset: this.offset, timeout: this.longPollTimeoutSeconds });
-            for (const update of updates) {
-                await this.processor.processUpdate(update);
-                this.offset = Math.max(this.offset, update.update_id + 1);
+            if (!this.readyEstablished) {
+                await this.ensureLongPollingAllowed();
+                const readiness = await this.establishReadiness(signal);
+                if (readiness.stopped_reason === 'aborted') {
+                    return { ok: true, stopped_reason: 'aborted' };
+                }
+                if (!readiness.ok) {
+                    return { ok: false, stopped_reason: readiness.stopped_reason ?? 'receive_not_ready' };
+                }
             }
+            await this.drainPending();
+            while (!signal.aborted) {
+                const result = await this.pollOnce({ awaitProcessing: false, signal });
+                if (result.stopped_reason === 'aborted')
+                    return { ok: true, stopped_reason: 'aborted' };
+                if (!result.ok)
+                    return { ok: false, stopped_reason: result.stopped_reason ?? 'poll_failed' };
+            }
+            return { ok: true, stopped_reason: 'aborted' };
+        }
+        finally {
+            await this.waitForIdle();
             await this.processor.tick?.();
-            await this.ownerLock.heartbeat();
-            return { ok: true, processed: updates.length, stopped_reason: null };
         }
-        catch (error) {
-            if (error instanceof TelegramBotApiError && error.errorCode === 409) {
-                await this.ownerLock.release();
-                return { ok: false, processed: 0, stopped_reason: 'telegram_409_conflict' };
+    }
+    async drainPending() {
+        const ingress = this.options.ingress;
+        if (!ingress)
+            return 0;
+        const entries = await ingress.pending();
+        let scheduled = 0;
+        for (const entry of entries) {
+            if (this.activeUpdateIds.has(entry.update_id))
+                continue;
+            let routed = entry.routed;
+            try {
+                if (!routed && this.processor.prepareUpdate) {
+                    routed = await this.processor.prepareUpdate(entry.update, { durablyAdmitted: true });
+                    await ingress.markRouted(entry.update_id, routed);
+                }
+            }
+            catch (error) {
+                await ingress.markFailed(entry.update_id, error);
+                continue;
             }
-            throw error;
+            this.scheduleEntry(entry.update, routed);
+            scheduled += 1;
         }
+        await this.writeHealth('ready', null);
+        return scheduled;
     }
-    async run(signal) {
-        await this.ensureLongPollingAllowed();
-        while (!signal.aborted) {
-            const result = await this.pollOnce();
-            if (!result.ok)
-                return { ok: false, stopped_reason: result.stopped_reason ?? 'poll_failed' };
+    async waitForIdle() {
+        while (this.inFlight.size > 0) {
+            await Promise.allSettled([...this.inFlight]);
         }
-        await this.ownerLock.release();
-        return { ok: true, stopped_reason: 'aborted' };
+    }
+    async receiveBatch(timeout, dispatch, requestTimeoutMs, signal) {
+        let conflictAttempt = 0;
+        let pollAttempt = 0;
+        while (true) {
+            if (signal?.aborted)
+                return { ok: true, processed: 0, stopped_reason: 'aborted' };
+            try {
+                const updates = await this.client.getUpdates({ offset: this.offset, timeout }, {
+                    ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+                    ...(signal === undefined ? {} : { signal })
+                });
+                for (const update of updates) {
+                    if (this.options.ingress) {
+                        await this.options.ingress.admit(update);
+                    }
+                    else if (dispatch) {
+                        await this.processor.processUpdate(update);
+                    }
+                    this.offset = Math.max(this.offset, update.update_id + 1);
+                }
+                this.consecutiveConflicts = 0;
+                this.lastSuccessfulPollAt = new Date(this.now()).toISOString();
+                await this.writeHealth('ready', null);
+                if (dispatch && this.options.ingress)
+                    await this.drainPending();
+                return { ok: true, processed: updates.length, stopped_reason: null };
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return { ok: true, processed: 0, stopped_reason: 'aborted' };
+                if (!(error instanceof TelegramBotApiError) || error.errorCode !== 409) {
+                    this.consecutiveConflicts = 0;
+                    await this.ownerLock.heartbeat().catch(() => undefined);
+                    if (pollAttempt >= this.maxPollRetries) {
+                        await this.writeHealth('terminal', 'telegram_poll_failed');
+                        return { ok: false, processed: 0, stopped_reason: 'telegram_poll_failed' };
+                    }
+                    await this.writeHealth('degraded', 'telegram_poll_retrying');
+                    const delay = this.pollBackoffMs[Math.min(pollAttempt, this.pollBackoffMs.length - 1)] ?? 30_000;
+                    pollAttempt += 1;
+                    await this.sleepWithSignal(Math.max(0, delay), signal);
+                    continue;
+                }
+                this.consecutiveConflicts += 1;
+                await this.ownerLock.heartbeat().catch(() => undefined);
+                if (conflictAttempt >= this.maxConflictRetries) {
+                    await this.writeHealth('terminal', 'telegram_409_conflict');
+                    return { ok: false, processed: 0, stopped_reason: 'telegram_409_conflict' };
+                }
+                await this.writeHealth('degraded', 'telegram_409_conflict_retrying');
+                const delay = this.conflictBackoffMs[Math.min(conflictAttempt, this.conflictBackoffMs.length - 1)] ?? 5_000;
+                conflictAttempt += 1;
+                await this.sleepWithSignal(Math.max(0, delay), signal);
+            }
+        }
+    }
+    async sleepWithSignal(ms, signal) {
+        if (!signal) {
+            await this.sleep(ms);
+            return;
+        }
+        if (signal.aborted)
+            return;
+        let onAbort = null;
+        const aborted = new Promise((resolve) => {
+            onAbort = () => resolve();
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+        try {
+            await Promise.race([this.sleep(ms), aborted]);
+        }
+        finally {
+            if (onAbort)
+                signal.removeEventListener('abort', onAbort);
+        }
+    }
+    scheduleEntry(update, routed) {
+        const ingress = this.options.ingress;
+        if (!ingress)
+            return;
+        const updateId = update.update_id;
+        const lane = updateLane(update);
+        this.activeUpdateIds.add(updateId);
+        const previous = this.laneTails.get(lane) ?? Promise.resolve();
+        let task;
+        task = previous
+            .catch(() => undefined)
+            .then(async () => {
+            if (routed && this.processor.executePreparedUpdate) {
+                await this.processor.executePreparedUpdate(update, routed);
+            }
+            else {
+                await this.processor.processUpdate(update);
+            }
+            await ingress.markCompleted(updateId);
+        })
+            .catch(async (error) => {
+            await ingress.markFailed(updateId, error);
+        })
+            .finally(() => {
+            this.activeUpdateIds.delete(updateId);
+            this.inFlight.delete(task);
+            if (this.laneTails.get(lane) === task)
+                this.laneTails.delete(lane);
+        });
+        this.laneTails.set(lane, task);
+        this.inFlight.add(task);
+    }
+    async ensureOffset() {
+        if (this.offsetInitialized)
+            return;
+        this.offset = this.options.ingress ? await this.options.ingress.nextOffset() : 0;
+        this.offsetInitialized = true;
+    }
+    async writeHealth(state, terminalReason) {
+        if (!this.options.healthPath)
+            return;
+        const counts = this.options.ingress
+            ? await this.options.ingress.counts()
+            : { pending: this.activeUpdateIds.size, dead_letters: 0 };
+        const at = new Date(this.now()).toISOString();
+        const effectiveState = state === 'ready' && counts.dead_letters > 0
+            ? 'degraded'
+            : state;
+        const health = {
+            schema: 'sks.telegram-receive-health.v1',
+            generation: this.generation,
+            pid: this.pid,
+            state: effectiveState,
+            started_at: this.startedAt,
+            updated_at: at,
+            last_successful_poll_at: this.lastSuccessfulPollAt,
+            consecutive_conflicts: this.consecutiveConflicts,
+            pending_ingress: counts.pending,
+            dead_letter_ingress: counts.dead_letters,
+            terminal_reason: effectiveState === 'terminal' ? terminalReason : null
+        };
+        await writeTextAtomic(this.options.healthPath, `${JSON.stringify(health, null, 2)}\n`, { mode: 0o600 });
     }
 }
 export function telegramHubPaths(root = globalSksRoot()) {
@@ -202,7 +435,9 @@ export function telegramHubPaths(root = globalSksRoot()) {
         topics: path.join(base, 'topic-registry.json'),
         actions: path.join(base, 'actions.json'),
         audit: path.join(base, 'audit.jsonl'),
-        projection: path.join(base, 'projection-state.json')
+        projection: path.join(base, 'projection-state.json'),
+        ingress: path.join(base, 'ingress-spool.json'),
+        receive_health: path.join(base, 'receive-health.json')
     };
 }
 function actorFromUpdate(update) {
@@ -214,17 +449,28 @@ function actorFromUpdate(update) {
         chatId: String(message.chat.id),
         userId: String(from.id),
         chatType: message.chat.type,
-        topicId: Number.isInteger(message.message_thread_id) ? message.message_thread_id ?? null : null,
+        topicId: message.is_topic_message === true && Number.isInteger(message.message_thread_id)
+            ? message.message_thread_id ?? null
+            : null,
         message: update.message ?? null
     };
 }
-function makeAction(route, kind, risk, prompt, revision, now) {
+function makeAction(route, kind, risk, prompt, revision, now, updateId) {
     return {
         schema: 'sks.remote-action.v1',
-        action_id: crypto.randomUUID(),
+        action_id: `tg-${sha256([
+            updateId,
+            route.machine_id,
+            route.project_id,
+            route.session_id,
+            route.generation,
+            kind,
+            revision
+        ].join(':')).slice(0, 40)}`,
         machine_id: route.machine_id,
         project_id: route.project_id,
         session_id: route.session_id,
+        route_generation: route.generation,
         kind,
         risk,
         prompt: prompt.slice(0, kind === 'input' ? 16 * 1024 : 120),
@@ -245,3 +491,12 @@ function inputText(text, command, staticAction) {
 function result(ok, status) {
     return { schema: 'sks.telegram-route-result.v1', ok, status, action: null, session_picker: false };
 }
+function updateLane(update) {
+    const message = update.message ?? update.callback_query?.message;
+    if (!message)
+        return `update:${update.update_id}`;
+    const topic = message.is_topic_message === true && Number.isInteger(message.message_thread_id)
+        ? message.message_thread_id
+        : 0;
+    return `${String(message.chat.id)}:${topic}`;
+}

package/dist/core/telegram/index.js

@@ -3,8 +3,10 @@ export * from './config.js';
 export * from './owner-lock.js';
 export * from './ledgers.js';
 export * from './bot-api.js';
+export * from './ingress-spool.js';
 export * from './messages.js';
 export * from './hub.js';
 export * from './runtime.js';
 export * from './setup.js';
 export * from './service.js';
+export * from './center-snapshot.js';