sneakoscope 7.3.0 → 7.6.0

package/dist/core/telegram/service.js

@@ -1,7 +1,8 @@
 import fsp from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { ensureDir, exists, globalSksRoot, runProcess, writeTextAtomic } from '../fsx.js';
+import { codexAppServerExecutablePath } from '../codex-control/codex-app-server-runtime-env.js';
+import { ensureDir, exists, globalSksRoot, readJson, runProcess, writeTextAtomic } from '../fsx.js';
 export const TELEGRAM_HUB_LAUNCH_LABEL = 'com.sneakoscope.telegram-hub';
 export function telegramHubServicePaths(globalRoot = globalSksRoot(), home = process.env.HOME || os.homedir()) {
     const root = path.resolve(globalRoot);
@@ -10,10 +11,17 @@ export function telegramHubServicePaths(globalRoot = globalSksRoot(), home = pro
         global_root: root,
         launch_agent_path: path.join(path.resolve(home), 'Library', 'LaunchAgents', `${TELEGRAM_HUB_LAUNCH_LABEL}.plist`),
         stdout_log_path: path.join(logs, 'hub.out.log'),
-        stderr_log_path: path.join(logs, 'hub.err.log')
+        stderr_log_path: path.join(logs, 'hub.err.log'),
+        receive_health_path: path.join(root, 'telegram', 'receive-health.json')
     };
 }
 export function telegramHubLaunchAgentSource(input) {
+    const home = path.dirname(path.dirname(path.dirname(input.paths.launch_agent_path)));
+    const executablePath = codexAppServerExecutablePath({
+        nodeBin: input.nodeBin,
+        home,
+        inheritedPath: ''
+    });
     const args = [
         '/usr/bin/caffeinate',
         '-i',
@@ -24,6 +32,7 @@ export function telegramHubLaunchAgentSource(input) {
         'run',
         '--project-root',
         path.resolve(input.projectRoot),
+        '--service-managed',
         '--json'
     ];
     return `<?xml version="1.0" encoding="UTF-8"?>
@@ -35,6 +44,7 @@ export function telegramHubLaunchAgentSource(input) {
 <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
 <key>ProcessType</key><string>Background</string>
 <key>ThrottleInterval</key><integer>5</integer>
+<key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(executablePath)}</string></dict>
 <key>StandardOutPath</key><string>${xml(input.paths.stdout_log_path)}</string>
 <key>StandardErrorPath</key><string>${xml(input.paths.stderr_log_path)}</string>
 </dict></plist>
@@ -116,23 +126,91 @@ export async function telegramHubServiceStatus(options) {
         timedOut: false
     }));
     const text = `${result.stdout || ''}\n${result.stderr || ''}`;
-    const state = text.match(/^[ \t]*state = ([^\n]+)/m)?.[1]?.trim() ?? null;
+    const launchState = text.match(/^[ \t]*state = ([^\n]+)/m)?.[1]?.trim() ?? null;
     const pidText = text.match(/^[ \t]*pid = (\d+)/m)?.[1] ?? null;
-    const pid = pidText ? Number(pidText) : null;
+    const launchPid = pidText ? Number(pidText) : null;
     const loaded = result.code === 0;
-    const running = loaded && state === 'running' && Boolean(pid);
+    const launchRunning = loaded && launchState === 'running' && Boolean(launchPid);
+    const receiveHealth = await readJson(paths.receive_health_path, null);
+    const currentReceiveHealth = receiveHealth?.schema === 'sks.telegram-receive-health.v1'
+        ? receiveHealth
+        : null;
+    const owner = await readJson(path.join(paths.global_root, 'telegram', 'owner.lock'), null);
+    const now = Date.now();
+    const isPidAlive = options.isPidAlive ?? localPidAlive;
+    const directOwnerFresh = Boolean(owner?.schema === 'sks.telegram-owner.v1'
+        && owner.host === os.hostname()
+        && Number.isInteger(owner.pid)
+        && owner.pid > 0
+        && Number.isFinite(Date.parse(owner.heartbeat_at))
+        && now - Date.parse(owner.heartbeat_at) <= 90_000
+        && isPidAlive(owner.pid));
+    const directIdentity = directOwnerFresh && owner
+        ? await (options.inspectDirectHub ?? inspectCenterSupervisedDirectHub)(owner.pid, options.projectRoot)
+            .catch(() => null)
+        : null;
+    const directRunning = Boolean(directOwnerFresh
+        && directIdentity
+        && directIdentity.parent_pid === directIdentity.supervisor_pid
+        && isPidAlive(directIdentity.supervisor_pid));
+    const launchHealthMatches = Boolean(launchRunning
+        && currentReceiveHealth
+        && currentReceiveHealth.pid === launchPid);
+    const mode = launchHealthMatches
+        ? 'launch_agent'
+        : directRunning
+            ? 'direct'
+            : launchRunning
+                ? 'launch_agent'
+                : null;
+    const running = launchRunning || directRunning;
+    const pid = mode === 'direct' ? owner?.pid ?? null : launchPid;
+    const state = mode === 'direct' ? 'direct' : launchState;
+    const matchingReceiveHealth = Boolean(running
+        && currentReceiveHealth
+        && currentReceiveHealth.pid === pid);
+    const receiveReady = Boolean(matchingReceiveHealth
+        && currentReceiveHealth?.state === 'ready'
+        && currentReceiveHealth.last_successful_poll_at
+        && Date.now() - Date.parse(currentReceiveHealth.last_successful_poll_at) <= 90_000
+        && currentReceiveHealth.dead_letter_ingress === 0);
     return {
         schema: 'sks.telegram-hub-service.v1',
-        ok: running,
+        ok: receiveReady,
         supported: true,
         installed,
         loaded,
         running,
+        mode,
         state,
         pid,
+        receive_ready: receiveReady,
+        receive_state: receiveHealth?.schema === 'sks.telegram-receive-health.v1'
+            ? receiveHealth.state
+            : null,
+        receive_generation: receiveHealth?.schema === 'sks.telegram-receive-health.v1'
+            ? receiveHealth.generation
+            : null,
+        last_successful_poll_at: receiveHealth?.schema === 'sks.telegram-receive-health.v1'
+            ? receiveHealth.last_successful_poll_at
+            : null,
+        pending_ingress: receiveHealth?.schema === 'sks.telegram-receive-health.v1'
+            ? receiveHealth.pending_ingress
+            : 0,
+        dead_letter_ingress: receiveHealth?.schema === 'sks.telegram-receive-health.v1'
+            ? receiveHealth.dead_letter_ingress
+            : 0,
         service,
         launch_agent_path: paths.launch_agent_path,
-        error: running ? null : loaded ? 'telegram_hub_not_running' : boundedError(result.stderr || result.stdout || 'telegram_hub_not_loaded')
+        error: receiveReady
+            ? null
+            : running
+                ? matchingReceiveHealth && Number(currentReceiveHealth?.dead_letter_ingress) > 0
+                    ? 'telegram_ingress_dead_letter_present'
+                    : 'telegram_receive_not_ready'
+                : loaded
+                    ? 'telegram_hub_not_running'
+                    : boundedError(result.stderr || result.stdout || 'telegram_hub_not_loaded')
     };
 }
 export async function removeTelegramHubService(options) {
@@ -150,8 +228,15 @@ function unsupportedStatus(paths, error, uid) {
         installed: false,
         loaded: false,
         running: false,
+        mode: null,
         state: null,
         pid: null,
+        receive_ready: false,
+        receive_state: null,
+        receive_generation: null,
+        last_successful_poll_at: null,
+        pending_ingress: 0,
+        dead_letter_ingress: 0,
         service: `${launchDomain(uid)}/${TELEGRAM_HUB_LAUNCH_LABEL}`,
         launch_agent_path: paths.launch_agent_path,
         error
@@ -159,7 +244,7 @@ function unsupportedStatus(paths, error, uid) {
 }
 async function waitForTelegramHubService(options) {
     let status = await telegramHubServiceStatus(options);
-    for (let attempt = 0; attempt < 25 && !status.running; attempt += 1) {
+    for (let attempt = 0; attempt < 80 && !status.ok; attempt += 1) {
         await new Promise((resolve) => setTimeout(resolve, 100));
         status = await telegramHubServiceStatus(options);
     }
@@ -171,6 +256,50 @@ function launchDomain(uid = typeof process.getuid === 'function' ? process.getui
 function boundedError(value) {
     return String(value || '').replace(/(?:\/Users|\/home)\/[^\s]+/g, '[path-redacted]').slice(0, 500);
 }
+function localPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function inspectCenterSupervisedDirectHub(pid, projectRoot) {
+    const result = await runProcess('/bin/ps', [
+        '-p',
+        String(pid),
+        '-o',
+        'ppid=',
+        '-o',
+        'command='
+    ], {
+        timeoutMs: 1_000,
+        maxOutputBytes: 16 * 1024
+    });
+    if (result.code !== 0 || result.timedOut)
+        return null;
+    const match = result.stdout.trim().match(/^(\d+)\s+([\s\S]+)$/);
+    if (!match)
+        return null;
+    const parentText = match[1];
+    const command = match[2];
+    if (!parentText || !command)
+        return null;
+    const parentPid = Number(parentText);
+    const supervisorMatch = command.match(/(?:^|\s)--center-supervisor-pid\s+([1-9]\d*)(?:\s|$)/);
+    if (!Number.isSafeInteger(parentPid)
+        || !supervisorMatch
+        || !/(?:^|\s)telegram\s+hub\s+run(?:\s|$)/.test(command)
+        || !/(?:^|\s)--center-supervised(?:\s|$)/.test(command)
+        || !command.includes(`--project-root ${path.resolve(projectRoot)}`)) {
+        return null;
+    }
+    const supervisorPid = Number(supervisorMatch[1]);
+    if (!Number.isSafeInteger(supervisorPid))
+        return null;
+    return { parent_pid: parentPid, supervisor_pid: supervisorPid };
+}
 function xml(value) {
     return value
         .replace(/&/g, '&amp;')

package/dist/core/telegram/setup.js

@@ -1,10 +1,15 @@
+import fsp from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { ensureDir, globalSksRoot, nowIso, readJson, runProcess, sha256, which, writeJsonAtomic } from '../fsx.js';
+import { errorCodeOf } from '../errors/message.js';
+import { ensureDir, globalSksRoot, nowIso, readJson, runProcess, sha256, which, writeBinaryAtomic, writeJsonAtomic, writeTextAtomic } from '../fsx.js';
 import { REMOTE_MACHINE_REGISTRY_SCHEMA, REMOTE_SESSION_INDEX_SCHEMA, RemoteCodexSessionBindingStore, remoteCodexSessionBindingsPath, remoteMachineRegistryPath, remoteSessionIndexPath, validateAllowedRoot, validateRemoteMachineRegistry, validateRemoteSessionIndex } from '../remote/index.js';
-import { TelegramBotApiClient } from './bot-api.js';
-import { isPositiveTelegramId, validateTelegramBotToken } from './config.js';
+import { probeTelegramBotReadiness, TelegramBotApiClient, TelegramBotApiError } from './bot-api.js';
+import { buildTelegramConfigV2, isPositiveTelegramId, readTelegramKeychainToken, readTelegramPreviousConfig, telegramTokenFingerprint, validateTelegramBotToken } from './config.js';
 import { telegramHubPaths } from './hub.js';
+import { TelegramIngressSpool } from './ingress-spool.js';
+import { TelegramTopicRegistry } from './ledgers.js';
+import { TelegramOwnerConflictError, TelegramOwnerLock } from './owner-lock.js';
 const KEYCHAIN_SERVICE = 'com.sneakoscope.telegram.bot';
 const KEYCHAIN_WRITER_SWIFT = `import Foundation
 import Security
@@ -15,6 +20,12 @@ let v:[String:Any]=[kSecValueData as String:Data(k.utf8)]
 var r=SecItemUpdate(q as CFDictionary,v as CFDictionary)
 if r==errSecItemNotFound{var n=q;n[kSecValueData as String]=Data(k.utf8);r=SecItemAdd(n as CFDictionary,nil)}
 if r != errSecSuccess{FileHandle.standardError.write(Data("keychain_status=\\(r)\\n".utf8));exit(1)}`;
+const KEYCHAIN_DELETE_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]
+let r=SecItemDelete(q as CFDictionary)
+if r != errSecSuccess && r != errSecItemNotFound{FileHandle.standardError.write(Data("keychain_status=\\(r)\\n".utf8));exit(1)}`;
 export async function setupTelegramLocalCoding(input) {
     const token = validateTelegramBotToken(input.token.trim());
     const explicitPair = normalizeExplicitPair(input.pairedChatId, input.pairedUserId);
@@ -23,93 +34,228 @@ export async function setupTelegramLocalCoding(input) {
     if (rootIssue)
         throw new Error(`telegram_project_root_invalid:${rootIssue}`);
     const globalRoot = path.resolve(input.globalRoot ?? globalSksRoot());
+    const setupOwner = new TelegramOwnerLock({
+        lockPath: telegramHubPaths(globalRoot).owner,
+        tokenFingerprint: telegramTokenFingerprint(token)
+    });
+    try {
+        await setupOwner.acquire();
+    }
+    catch (error) {
+        if (error instanceof TelegramOwnerConflictError) {
+            throw new Error('telegram_hub_must_be_stopped_before_setup');
+        }
+        throw error;
+    }
+    try {
+        return await setupTelegramLocalCodingLocked(input, token, explicitPair, projectRoot, globalRoot);
+    }
+    finally {
+        await setupOwner.release();
+    }
+}
+async function setupTelegramLocalCodingLocked(input, token, explicitPair, projectRoot, globalRoot) {
     const api = input.api ?? new TelegramBotApiClient(token, { timeoutMs: 12_000, maxRetries: 0 });
-    const bot = await api.call('getMe', {});
-    const pairing = explicitPair ?? await detectPrivateStart(api);
+    const readiness = await probeTelegramBotReadiness(api).catch(throwTelegramSetupApiError);
+    if (readiness.webhook_configured) {
+        throw new Error('telegram_webhook_conflict:remove_webhook_before_long_polling');
+    }
+    const detectedPair = explicitPair === null
+        ? await detectPrivateStart(api, readiness.bot.username, false).catch(throwTelegramSetupApiError)
+        : null;
+    const pairing = explicitPair ?? detectedPair;
     const account = input.account?.trim() || process.env.USER || os.userInfo().username || 'sks';
-    await (input.keychainWriter ?? writeTelegramKeychain)(token, KEYCHAIN_SERVICE, account);
     const hostname = input.hostname ?? os.hostname();
     const machineId = `local-${sha256(hostname).slice(0, 12)}`;
     const projectId = `project-${sha256(projectRoot).slice(0, 12)}`;
     const sessionId = `telegram-${sha256(`${machineId}:${projectId}`).slice(0, 12)}`;
-    const bindingStore = new RemoteCodexSessionBindingStore(remoteCodexSessionBindingsPath(projectRoot));
+    const bindingPath = remoteCodexSessionBindingsPath(projectRoot);
+    const machinePath = remoteMachineRegistryPath(globalRoot);
+    const indexPath = remoteSessionIndexPath(projectRoot);
+    const hubPaths = telegramHubPaths(globalRoot);
+    const configPath = hubPaths.config;
+    const stateSnapshots = await Promise.all([
+        snapshotSetupFile(bindingPath),
+        snapshotSetupFile(machinePath),
+        snapshotSetupFile(indexPath),
+        snapshotSetupFile(hubPaths.topics),
+        snapshotSetupFile(hubPaths.projection),
+        snapshotSetupFile(hubPaths.idempotency),
+        snapshotSetupFile(hubPaths.ingress),
+        snapshotSetupFile(hubPaths.receive_health),
+        snapshotSetupFile(configPath)
+    ]);
+    const keychainWriter = input.keychainWriter ?? writeTelegramKeychain;
+    const keychainReader = input.keychainReader
+        ?? (input.keychainWriter ? async () => null : readTelegramKeychain);
+    const keychainDeleter = input.keychainDeleter
+        ?? (input.keychainWriter
+            ? async () => { throw new Error('telegram_keychain_rollback_unavailable'); }
+            : deleteTelegramKeychain);
+    const previousToken = await keychainReader(KEYCHAIN_SERVICE, account);
+    const previousConfig = await readPreviousTelegramConfig(configPath);
+    const tokenFingerprint = telegramTokenFingerprint(token);
+    const samePersistedIdentity = previousConfig?.schema === 'sks.telegram-config.v2'
+        && previousConfig.bot_user_id === readiness.bot.id
+        && previousConfig.bot_token_fingerprint === tokenFingerprint
+        && previousConfig.paired_chat_id === pairing.chatId
+        && previousConfig.paired_user_id === pairing.userId
+        && input.resetSession !== true;
+    const configGeneration = previousConfig?.schema === 'sks.telegram-config.v2'
+        ? samePersistedIdentity
+            ? previousConfig.config_generation
+            : previousConfig.config_generation + 1
+        : 1;
+    const config = buildTelegramConfigV2({
+        botTokenRef: { type: 'keychain', service: KEYCHAIN_SERVICE, account },
+        botUserId: readiness.bot.id,
+        botTokenFingerprint: tokenFingerprint,
+        pairedChatId: pairing.chatId,
+        pairedUserId: pairing.userId,
+        configGeneration,
+        longPollTimeoutSec: 25,
+        ownerStaleMs: 60_000,
+        protectContent: true,
+        silentNotifications: false
+    });
+    const identityChanged = previousConfig?.schema !== 'sks.telegram-config.v2'
+        || previousConfig.identity_fingerprint !== config.identity_fingerprint
+        || input.resetSession === true;
+    const ingress = new TelegramIngressSpool(hubPaths.ingress, {
+        identityFingerprint: config.identity_fingerprint,
+        ...(previousToken
+            ? { legacyTokenFingerprint: telegramTokenFingerprint(previousToken) }
+            : {})
+    });
+    if (identityChanged)
+        await ingress.assertIdentityRotationSafe();
+    const bindingStore = new RemoteCodexSessionBindingStore(bindingPath);
     const existingBinding = await bindingStore.find(sessionId);
-    const binding = existingBinding && input.resetSession !== true
-        ? existingBinding
-        : await bindingStore.upsert({
-            session_id: sessionId,
+    let credentialWriteAttempted = false;
+    try {
+        credentialWriteAttempted = true;
+        await keychainWriter(token, KEYCHAIN_SERVICE, account);
+        if (input.keychainWriter === undefined) {
+            await verifyTelegramKeychainReadback(token, KEYCHAIN_SERVICE, account, keychainReader);
+        }
+        const binding = existingBinding && input.resetSession !== true
+            ? existingBinding
+            : await bindingStore.upsert({
+                session_id: sessionId,
+                machine_id: machineId,
+                project_id: projectId,
+                project_root: projectRoot,
+                codex_thread_id: null,
+                last_turn_id: null,
+                last_turn_status: null
+            });
+        const registry = await upsertLocalMachine(machinePath, {
+            id: machineId,
+            display_name: `This Mac (${hostname})`.slice(0, 120),
+            transport: 'local',
+            allowed_roots: [projectRoot],
+            enabled: true
+        });
+        await upsertLocalTarget(indexPath, registry, {
             machine_id: machineId,
             project_id: projectId,
-            project_root: projectRoot,
-            codex_thread_id: null,
-            last_turn_id: null,
-            last_turn_status: null
+            project_root: projectRoot
         });
-    const machinePath = remoteMachineRegistryPath(globalRoot);
-    const registry = await upsertLocalMachine(machinePath, {
-        id: machineId,
-        display_name: `This Mac (${hostname})`.slice(0, 120),
-        transport: 'local',
-        allowed_roots: [projectRoot],
-        enabled: true
-    });
-    const indexPath = remoteSessionIndexPath(projectRoot);
-    await upsertLocalTarget(indexPath, registry, {
-        machine_id: machineId,
-        project_id: projectId,
-        project_root: projectRoot
-    });
-    const config = {
-        schema: 'sks.telegram-config.v1',
-        bot_token_ref: { type: 'keychain', service: KEYCHAIN_SERVICE, account },
-        paired_chat_ids: [pairing.chatId],
-        paired_user_ids: [pairing.userId],
-        long_poll_timeout_sec: 25,
-        owner_stale_ms: 60_000,
-        protect_content: true,
-        silent_notifications: false
-    };
-    const configPath = telegramHubPaths(globalRoot).config;
-    await writeJsonAtomic(configPath, config);
-    return {
-        schema: 'sks.telegram-setup.v1',
-        ok: true,
-        bot: {
-            id: bot?.id === undefined ? null : String(bot.id),
-            username: bot?.username ? String(bot.username) : null
-        },
-        pairing: {
-            chat_id: pairing.chatId,
-            user_id: pairing.userId,
-            detected: explicitPair === null
-        },
-        machine_id: machineId,
-        project_id: projectId,
-        project_root: projectRoot,
-        session_id: sessionId,
-        codex_thread_id: binding.codex_thread_id,
-        codex_thread_state: binding.codex_thread_id ? 'ready' : 'pending_first_turn',
-        token_storage: 'macos-keychain',
-        config_path: configPath,
-        machine_registry_path: machinePath,
-        session_index_path: indexPath
-    };
+        if (identityChanged) {
+            await new TelegramTopicRegistry(hubPaths.topics, {
+                identityFingerprint: config.identity_fingerprint
+            }).invalidateAll();
+            await ingress.resetForIdentity();
+            await writeJsonAtomic(hubPaths.projection, {
+                schema: 'sks.telegram-projection-state.v1',
+                sessions: {}
+            });
+            await writeTextAtomic(hubPaths.idempotency, '', { mode: 0o600 });
+            await fsp.unlink(hubPaths.receive_health).catch((error) => {
+                if (errorCodeOf(error) !== 'ENOENT')
+                    throw error;
+            });
+        }
+        await writeJsonAtomic(configPath, config);
+        if (detectedPair) {
+            await acknowledgePrivateStart(api, detectedPair.updateId).catch(throwTelegramSetupApiError);
+        }
+        return {
+            schema: 'sks.telegram-setup.v1',
+            ok: true,
+            bot: readiness.bot,
+            pairing: {
+                chat_id: pairing.chatId,
+                user_id: pairing.userId,
+                detected: explicitPair === null
+            },
+            machine_id: machineId,
+            project_id: projectId,
+            project_root: projectRoot,
+            session_id: sessionId,
+            codex_thread_id: binding.codex_thread_id,
+            codex_thread_state: binding.codex_thread_id ? 'ready' : 'pending_first_turn',
+            token_storage: 'macos-keychain',
+            config_path: configPath,
+            machine_registry_path: machinePath,
+            session_index_path: indexPath
+        };
+    }
+    catch (error) {
+        const rollbackErrors = [];
+        for (const snapshot of [...stateSnapshots].reverse()) {
+            await restoreSetupFile(snapshot).catch((rollbackError) => {
+                rollbackErrors.push(publicSetupError(rollbackError));
+            });
+        }
+        if (credentialWriteAttempted) {
+            const restoreCredential = previousToken === null
+                ? keychainDeleter(KEYCHAIN_SERVICE, account)
+                : keychainWriter(previousToken, KEYCHAIN_SERVICE, account);
+            await restoreCredential.catch((rollbackError) => {
+                rollbackErrors.push(publicSetupError(rollbackError));
+            });
+        }
+        if (rollbackErrors.length > 0) {
+            throw new Error(`telegram_setup_rollback_failed:${publicSetupError(error)}:${rollbackErrors.join(',')}`);
+        }
+        throw error;
+    }
 }
-export async function detectPrivateStart(api) {
+async function readPreviousTelegramConfig(file) {
+    const raw = await readJson(file, null);
+    if (raw === null)
+        return null;
+    const config = readTelegramPreviousConfig(raw);
+    if (!config)
+        throw new Error('telegram_config_invalid:unsupported_or_malformed');
+    return config;
+}
+export async function detectPrivateStart(api, botUsername = null, consume = true) {
     const updates = await api.getUpdates({ timeout: 0, allowed_updates: ['message'] });
-    const match = [...updates].reverse().find(isPrivateStart);
+    const candidates = updates.filter((update) => isPrivateStart(update, botUsername));
+    const identities = new Set(candidates.map((update) => (`${String(update.message.chat.id)}:${String(update.message.from.id)}`)));
+    if (identities.size > 1) {
+        throw new Error('telegram_pairing_ambiguous:retry_with_explicit_private_chat_and_user_ids');
+    }
+    const match = candidates.at(-1);
     if (!match?.message?.from) {
         throw new Error('telegram_pairing_start_not_found:send_/start_to_the_bot_then_retry');
     }
+    if (consume)
+        await acknowledgePrivateStart(api, match.update_id);
+    return {
+        chatId: String(match.message.chat.id),
+        userId: String(match.message.from.id),
+        updateId: match.update_id
+    };
+}
+async function acknowledgePrivateStart(api, updateId) {
     await api.getUpdates({
-        offset: match.update_id + 1,
+        offset: updateId + 1,
         timeout: 0,
         allowed_updates: ['message']
     });
-    return {
-        chatId: String(match.message.chat.id),
-        userId: String(match.message.from.id)
-    };
 }
 export async function writeTelegramKeychain(token, service, account) {
     if (process.platform !== 'darwin')
@@ -123,6 +269,65 @@ export async function writeTelegramKeychain(token, service, account) {
     if (result.code !== 0 || result.timedOut)
         throw new Error('telegram_keychain_store_failed');
 }
+export async function readTelegramKeychain(service, account) {
+    return readTelegramKeychainToken(service, account, { timeoutMs: 5_000 })
+        .catch((error) => {
+        if (error instanceof Error && error.message === 'telegram_keychain_requires_macos')
+            throw error;
+        throw new Error('telegram_keychain_snapshot_failed');
+    });
+}
+export async function verifyTelegramKeychainReadback(expectedToken, service, account, reader = readTelegramKeychain) {
+    const storedToken = await reader(service, account).catch(() => null);
+    if (storedToken !== expectedToken)
+        throw new Error('telegram_keychain_readback_failed');
+}
+export async function deleteTelegramKeychain(service, account) {
+    if (process.platform !== 'darwin')
+        throw new Error('telegram_keychain_requires_macos');
+    const swift = await which('swift').catch(() => null) || '/usr/bin/swift';
+    const result = await runProcess(swift, ['-e', KEYCHAIN_DELETE_SWIFT, account, service], {
+        timeoutMs: 30_000,
+        maxOutputBytes: 8 * 1024
+    });
+    if (result.code !== 0 || result.timedOut)
+        throw new Error('telegram_keychain_delete_failed');
+}
+async function snapshotSetupFile(file) {
+    const stat = await fsp.lstat(file).catch((error) => {
+        if (errorCodeOf(error) === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (stat === null)
+        return { file, contents: null, mode: null };
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error('telegram_setup_state_snapshot_invalid');
+    return {
+        file,
+        contents: await fsp.readFile(file),
+        mode: stat.mode & 0o777
+    };
+}
+async function restoreSetupFile(snapshot) {
+    if (snapshot.contents === null) {
+        await fsp.unlink(snapshot.file).catch((error) => {
+            if (errorCodeOf(error) !== 'ENOENT')
+                throw error;
+        });
+        return;
+    }
+    await writeBinaryAtomic(snapshot.file, snapshot.contents, {
+        ...(snapshot.mode === null ? {} : { mode: snapshot.mode })
+    });
+}
+function publicSetupError(error) {
+    return (error instanceof Error ? error.message : String(error))
+        .replace(/\b\d{5,}:[A-Za-z0-9_-]{20,}\b/g, '[redacted]')
+        .replace(/(?:\/Users|\/home)\/[^\s]+/g, '[path-redacted]')
+        .replace(/[:,]+/g, '_')
+        .slice(0, 160);
+}
 async function upsertLocalMachine(file, machine) {
     await ensureDir(path.dirname(file));
     const raw = await readJson(file, null);
@@ -206,11 +411,24 @@ function normalizeExplicitPair(chatId, userId) {
     }
     return { chatId: chat, userId: user };
 }
-function isPrivateStart(update) {
+function isPrivateStart(update, botUsername) {
     const message = update.message;
     if (!message || message.chat.type !== 'private' || !message.from)
         return false;
-    return /^\/start(?:@\w+)?(?:\s|$)/i.test(String(message.text || '').trim());
+    const command = /^\/start(?:@([A-Za-z0-9_]+))?(?:\s|$)/i.exec(String(message.text || '').trim());
+    if (!command)
+        return false;
+    const addressedBot = command[1];
+    return !addressedBot || (botUsername !== null && addressedBot.toLowerCase() === botUsername.toLowerCase());
+}
+function throwTelegramSetupApiError(error) {
+    if (error instanceof TelegramBotApiError && (error.errorCode === 401 || error.errorCode === 404)) {
+        throw new Error('telegram_bot_auth_failed');
+    }
+    if (error instanceof TelegramBotApiError && error.errorCode === 409) {
+        throw new Error('telegram_409_conflict:stop_other_poller_and_retry');
+    }
+    throw error;
 }
 export function telegramSetupKeychainReference(account = process.env.USER || os.userInfo().username || 'sks') {
     return { type: 'keychain', service: KEYCHAIN_SERVICE, account };

package/dist/core/text/strings.js

@@ -1,3 +1,6 @@
+export function uniqueValues(values) {
+    return [...new Set(values)];
+}
 export function uniqueStrings(values) {
     return [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))];
 }