sneakoscope 7.3.0 → 7.6.0

package/dist/core/commands/telegram-command.js

@@ -1,8 +1,14 @@
 import path from 'node:path';
 import { isHelpRequest } from '../../cli/help.js';
-import { globalSksRoot, projectRoot, readJson, readStdin } from '../fsx.js';
+import { globalSksRoot, nowIso, projectRoot, readJson, readStdin, writeTextAtomic } from '../fsx.js';
 import { RemoteCodexSessionBindingStore, loadRemoteMachineRegistry, loadRemoteSessionIndex, remoteCodexSessionBindingsPath, remoteMachineRegistryPath, remoteSessionIndexPath, validateRemoteMachineRegistry, validateRemoteSessionIndex } from '../remote/index.js';
-import { loadTelegramConfig, resolveTelegramBotToken, TelegramActionBroker, TelegramAuditLedger, TelegramBotApiClient, TelegramHubRouter, TelegramHubRuntime, TelegramIdempotencyLedger, TelegramOwnerLock, TelegramMessageProjector, TelegramPollingHub, TelegramTopicRegistry, installAndStartTelegramHubService, restartTelegramHubService, setupTelegramLocalCoding, stopTelegramHubService, telegramHubPaths, telegramHubServiceStatus, telegramTokenFingerprint, validateTelegramConfig, validateTelegramPrivatePairing } from '../telegram/index.js';
+import { loadTelegramConfig, probeTelegramBotReadiness, resolveTelegramBotToken, TelegramActionBroker, TelegramAuditLedger, TelegramBotApiClient, TelegramBotApiError, TelegramHubRouter, TelegramHubRuntime, TelegramIdempotencyLedger, TelegramIngressSpool, TelegramOwnerLock, TelegramMessageProjector, TelegramPollingHub, TelegramTopicRegistry, telegramCenterLiveSnapshot, telegramCenterSnapshot, installAndStartTelegramHubService, restartTelegramHubService, setupTelegramLocalCoding, stopTelegramHubService, telegramHubPaths, telegramHubServiceStatus, telegramRuntimeIdentityFingerprint, telegramTokenFingerprint, validateTelegramConfig, validateTelegramPrivatePairing } from '../telegram/index.js';
+export const TELEGRAM_STATUS_NATIVE_DEADLINE_MS = 12_000;
+export const TELEGRAM_STATUS_TOKEN_LOOKUP_TIMEOUT_MS = 3_000;
+export const TELEGRAM_STATUS_BOT_REQUEST_TIMEOUT_MS = 1_500;
+export const TELEGRAM_STATUS_BOT_MAX_RETRIES = 0;
+export const TELEGRAM_STATUS_LIVE_PROBE_BUDGET_MS = TELEGRAM_STATUS_TOKEN_LOOKUP_TIMEOUT_MS
+    + TELEGRAM_STATUS_BOT_REQUEST_TIMEOUT_MS * 2;
 export async function telegramCommand(args = []) {
     if (isHelpRequest(args)) {
         printTelegramUsage();
@@ -17,6 +23,23 @@ export async function telegramCommand(args = []) {
         if (action === 'status') {
             return print(await telegramStatus(args, root, paths, configPath), json);
         }
+        if (action === 'center-snapshot') {
+            const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
+            const sortDirection = telegramCenterSortDirection(readOption(args, '--sort-direction'));
+            return print(await telegramCenterSnapshot({
+                projectRoot: controllingRoot,
+                sessionId: readOption(args, '--session-id'),
+                cursor: readOption(args, '--cursor'),
+                sortDirection
+            }), json);
+        }
+        if (action === 'center-live') {
+            const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
+            return print(await telegramCenterLiveSnapshot({
+                projectRoot: controllingRoot,
+                sessionId: readOption(args, '--session-id')
+            }), json);
+        }
         if (action === 'setup') {
             if (!args.includes('--bot-token-stdin'))
                 return fail('bot_token_stdin_required', ['setup --bot-token-stdin --project-root <path>'], json);
@@ -36,19 +59,83 @@ export async function telegramCommand(args = []) {
             const validation = validateTelegramConfig(await readJson(configPath, null));
             return print({ schema: 'sks.telegram-config-validation.v1', ...validation, config: validation.config ? redactConfig(validation.config) : null }, json);
         }
+        if (action === 'dead-letters') {
+            const request = telegramDeadLetterCommandRequest(args);
+            const config = await loadTelegramConfig(configPath);
+            const token = await resolveTelegramBotToken(config.bot_token_ref);
+            const tokenFingerprint = telegramTokenFingerprint(token);
+            const ingress = new TelegramIngressSpool(paths.ingress, {
+                identityFingerprint: telegramRuntimeIdentityFingerprint(config, tokenFingerprint),
+                legacyTokenFingerprint: tokenFingerprint
+            });
+            if (request.action === 'list' || request.action === 'inspect') {
+                const deadLetters = await ingress.deadLetters(request.updateId ?? undefined);
+                if (request.action === 'inspect' && deadLetters.length === 0) {
+                    throw new Error('telegram_ingress_dead_letter_not_found');
+                }
+                return print({
+                    schema: 'sks.telegram-ingress-dead-letter-list.v1',
+                    ok: true,
+                    unhealthy: deadLetters.length > 0,
+                    dead_letters: deadLetters,
+                    next_action: deadLetters.length > 0
+                        ? 'Stop the Hub, then explicitly requeue only requeue_safe entries or acknowledge entries whose effect may be ambiguous.'
+                        : 'No dead-lettered Telegram ingress remains.'
+                }, json);
+            }
+            const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
+            const service = await telegramHubServiceStatus({
+                projectRoot: controllingRoot,
+                globalRoot: root
+            });
+            if (service.running)
+                throw new Error('telegram_hub_must_be_stopped_before_dead_letter_recovery');
+            if (!request.confirmed)
+                throw new Error('telegram_dead_letter_recovery_confirmation_required');
+            if (request.action === 'requeue') {
+                const requeued = await ingress.requeueDeadLetter(request.updateId);
+                const counts = await ingress.counts();
+                await updateTelegramIngressHealth(paths.receive_health, counts);
+                return print({
+                    schema: 'sks.telegram-ingress-recovery.v1',
+                    ok: true,
+                    disposition: 'requeued',
+                    update_id: requeued.update_id,
+                    replayed: false,
+                    pending_ingress: counts.pending,
+                    dead_letter_ingress: counts.dead_letters,
+                    next_action: 'Restart the Telegram Hub to process the explicitly requeued request.'
+                }, json);
+            }
+            const acknowledged = await ingress.acknowledgeDeadLetters(request.updateId === null ? undefined : [request.updateId]);
+            const counts = await ingress.counts();
+            await updateTelegramIngressHealth(paths.receive_health, counts);
+            return print({
+                schema: 'sks.telegram-ingress-recovery.v1',
+                ok: true,
+                disposition: 'acknowledged',
+                acknowledged_dead_letters: acknowledged,
+                acknowledged_update_id: request.updateId,
+                replayed: false,
+                resend_required: acknowledged > 0,
+                next_action: acknowledged > 0
+                    ? 'Restart the Telegram Hub, then resend each failed request from the paired private chat.'
+                    : 'No dead-lettered Telegram ingress remained.'
+            }, json);
+        }
         if (action === 'hub') {
             const hubAction = args[1] && !String(args[1]).startsWith('-') ? String(args[1]) : 'run';
             const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
             if (hubAction === 'start') {
                 await assertHubSetupReady(controllingRoot, root, configPath);
-                return print(await installAndStartTelegramHubService({ projectRoot: controllingRoot, globalRoot: root }), json);
+                return print(markTelegramHubMutationResult(await installAndStartTelegramHubService({ projectRoot: controllingRoot, globalRoot: root })), json);
             }
             if (hubAction === 'stop') {
-                return print(await stopTelegramHubService({ projectRoot: controllingRoot, globalRoot: root }), json);
+                return print(markTelegramHubMutationResult(await stopTelegramHubService({ projectRoot: controllingRoot, globalRoot: root })), json);
             }
             if (hubAction === 'restart') {
                 await assertHubSetupReady(controllingRoot, root, configPath);
-                return print(await restartTelegramHubService({ projectRoot: controllingRoot, globalRoot: root }), json);
+                return print(markTelegramHubMutationResult(await restartTelegramHubService({ projectRoot: controllingRoot, globalRoot: root })), json);
             }
             if (hubAction === 'status') {
                 return print(await telegramHubServiceStatus({ projectRoot: controllingRoot, globalRoot: root }), json);
@@ -59,7 +146,7 @@ export async function telegramCommand(args = []) {
         }
     }
     catch (err) {
-        process.exitCode = 1;
+        process.exitCode = action === 'hub' && args.includes('--service-managed') ? 0 : 1;
         return print({
             schema: 'sks.telegram-command-error.v1',
             ok: false,
@@ -68,8 +155,13 @@ export async function telegramCommand(args = []) {
     }
     return fail('unknown_action', [
         'status',
+        'center-snapshot [--session-id <id>] [--cursor <opaque>] [--sort-direction asc|desc] --project-root <path>',
+        'center-live [--session-id <id>] --project-root <path>',
         'setup --bot-token-stdin --project-root <path>',
         'validate-config',
+        'dead-letters list|inspect --project-root <path>',
+        'dead-letters requeue --update-id <id> --yes --project-root <path>',
+        'dead-letters acknowledge [--update-id <id>] --yes --project-root <path>',
         'hub run|start|stop|restart|status'
     ], json);
 }
@@ -79,6 +171,7 @@ async function telegramStatus(args, root, paths, configPath) {
     const owner = await readJson(paths.owner, null);
     const topics = await new TelegramTopicRegistry(paths.topics).list();
     const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
+    const servicePromise = telegramHubServiceStatus({ projectRoot: controllingRoot, globalRoot: root });
     const machineRegistryRaw = await readJson(readOption(args, '--machines') ?? remoteMachineRegistryPath(root), null);
     const machineValidation = validateRemoteMachineRegistry(machineRegistryRaw);
     const sessionIndexRaw = await readJson(readOption(args, '--session-index') ?? remoteSessionIndexPath(controllingRoot), null);
@@ -90,29 +183,63 @@ async function telegramStatus(args, root, paths, configPath) {
     const registered = bindings.filter((binding) => targets.some((target) => (binding.machine_id === target.machine_id
         && binding.project_id === target.project_id
         && path.resolve(binding.project_root) === path.resolve(target.project_root))));
-    const service = await telegramHubServiceStatus({ projectRoot: controllingRoot, globalRoot: root });
     let tokenConfigured = false;
-    if (validation.config) {
-        tokenConfigured = await resolveTelegramBotToken(validation.config.bot_token_ref).then(() => true).catch(() => false);
+    let liveProbe = telegramLiveProbeStatus(null);
+    const probeConfig = validation.config;
+    if (probeConfig) {
+        const token = await resolveTelegramBotToken(probeConfig.bot_token_ref, {
+            timeoutMs: TELEGRAM_STATUS_TOKEN_LOOKUP_TIMEOUT_MS
+        }).catch(() => null);
+        tokenConfigured = token !== null;
+        if (token) {
+            try {
+                liveProbe = telegramLiveProbeStatus(await probeTelegramBotReadiness(new TelegramBotApiClient(token, {
+                    timeoutMs: TELEGRAM_STATUS_BOT_REQUEST_TIMEOUT_MS,
+                    maxRetries: TELEGRAM_STATUS_BOT_MAX_RETRIES
+                })));
+            }
+            catch (error) {
+                liveProbe = telegramLiveProbeStatus(null, error);
+            }
+        }
     }
+    const service = await servicePromise;
     const pairing = telegramPairingReadiness(rawConfig);
     const blockers = [
-        ...validation.issues.map((issue) => `config:${issue}`),
+        ...validation.issues.map((issue) => (issue === 'telegram_identity_migration_required'
+            ? issue
+            : `config:${issue}`)),
         ...machineValidation.issues.map((issue) => `machine:${issue}`),
         ...sessionValidation.issues.map((issue) => `target:${issue}`),
         ...(tokenConfigured ? [] : ['telegram_token_not_available']),
+        ...(liveProbe.blocker ? [liveProbe.blocker] : []),
         ...(pairing.blocker ? [pairing.blocker] : []),
         ...(registered.length ? [] : ['no_registered_codex_session']),
-        ...(service.running ? [] : ['telegram_hub_not_running'])
+        ...(service.running
+            ? service.dead_letter_ingress > 0
+                ? ['telegram_ingress_dead_letter_present']
+                : service.receive_ready ? [] : ['telegram_receive_not_ready']
+            : ['telegram_hub_not_running'])
     ];
     return {
         schema: 'sks.telegram-status.v1',
         ok: blockers.length === 0,
         configured: rawConfig !== null,
         token_configured: tokenConfigured,
+        bot_verified: liveProbe.bot_verified,
+        bot: liveProbe.bot,
+        webhook_configured: liveProbe.webhook_configured,
+        pending_update_count: liveProbe.pending_update_count,
+        long_poll_ready: liveProbe.long_poll_ready,
+        telegram_probe_error: liveProbe.telegram_probe_error,
         pairing_valid: pairing.pairing_valid,
         pairing_issues: pairing.pairing_issues,
         hub_running: service.running,
+        hub_ready: service.receive_ready,
+        receive_state: service.receive_state,
+        last_successful_poll_at: service.last_successful_poll_at,
+        pending_ingress: service.pending_ingress,
+        dead_letter_ingress: service.dead_letter_ingress,
         service,
         config_issues: validation.issues,
         owner: owner ? {
@@ -135,7 +262,8 @@ async function telegramStatus(args, root, paths, configPath) {
             updated_at: binding.updated_at
         })),
         remote_config_issues: [...machineValidation.issues, ...sessionValidation.issues],
-        blockers
+        blockers,
+        next_actions: telegramNextActions(blockers)
     };
 }
 function printTelegramUsage() {
@@ -143,49 +271,94 @@ function printTelegramUsage() {
 
 Usage:
   sks telegram status [--project-root <path>] [--json]
+  sks telegram center-snapshot --project-root <path> [--session-id <id>]
+                               [--cursor <opaque>] [--sort-direction asc|desc] [--json]
+  sks telegram center-live --project-root <path> [--session-id <id>] [--json]
   sks telegram setup --bot-token-stdin --project-root <path> [--paired-chat-id <id>]
                      [--paired-user-id <id>] [--new-session] [--json]
   sks telegram validate-config [--config <path>] [--json]
+  sks telegram dead-letters list --project-root <path> [--json]
+  sks telegram dead-letters inspect --update-id <id> --project-root <path> [--json]
+  sks telegram dead-letters requeue --update-id <id> --yes --project-root <path> [--json]
+  sks telegram dead-letters acknowledge [--update-id <id>] --yes --project-root <path> [--json]
   sks telegram hub start|stop|restart|status [--project-root <path>] [--json]
   sks telegram hub run [--project-root <path>] [--json]
 
 Pairing (do these first):
-  1. Create a private bot with @BotFather in Telegram and copy its token.
+  1. Open @BotFather, send /newbot, choose a name and a unique username ending in "bot",
+     then copy the HTTP API token BotFather returns.
   2. Send /start to that bot from the Telegram account you want to pair.
   3. printf '%s' "<token>" | sks telegram setup --bot-token-stdin --project-root "$PWD" --json
      The token is read from stdin only and stored in the macOS Keychain.
   4. sks telegram hub start --project-root "$PWD" --json
 
+If status reports telegram_webhook_conflict, remove the webhook in the service
+that configured it, then retry. SKS does not delete external webhook state implicitly.
+If setup or the hub reports telegram_409_conflict, stop the other poller using
+this bot token before retrying.
+Stop the SKS Telegram hub before rerunning setup or rotating its BotFather token.
+If status reports telegram_ingress_dead_letter_present, inspect the bounded list,
+stop the Hub, then explicitly requeue only entries marked requeue_safe or acknowledge
+an ambiguous entry and resend it from the paired private chat. Requeue never executes
+until the Hub is separately restarted, and ambiguous effects are never replayed.
+
 The same flow is available in SKS Center → Remote & Telegram.
+Center uses center-snapshot for stored conversation pages and center-live for the
+bounded local event journal. Center checks the journal files every 2.5 seconds and
+runs center-live only after a change; it never starts Codex App Server for that path.
+The default page is Latest. Use Older, Newer, and Latest in Center, or pass a
+returned cursor with its paired sort direction, to browse every stored turn
+without resuming the Codex thread.
+Reasoning text, raw tool output, and credentials are excluded from that projection.
 See docs/telegram-and-center.md for the full guide and troubleshooting.
 `);
 }
 export function telegramPairingReadiness(value) {
     const pairing = validateTelegramPrivatePairing(value);
+    const multipleIds = hasMultipleTelegramPairingIds(value);
     return {
         pairing_valid: pairing.ok,
         pairing_issues: pairing.issues,
         blocker: pairing.ok
             ? null
-            : pairing.missing
-                ? 'telegram_pairing_missing'
-                : `telegram_pairing_invalid:${pairing.issues.join(',')}`
+            : multipleIds
+                ? 'telegram_pairing_multiple_ids_requires_setup'
+                : pairing.missing
+                    ? 'telegram_pairing_missing'
+                    : `telegram_pairing_invalid:${pairing.issues.join(',')}`
+    };
+}
+export function telegramLiveProbeStatus(readiness, error = null) {
+    const probeError = error === null ? null : telegramProbeFailure(error);
+    const webhookConfigured = readiness?.webhook_configured === true;
+    return {
+        bot_verified: readiness !== null,
+        bot: readiness?.bot ?? null,
+        webhook_configured: webhookConfigured,
+        pending_update_count: readiness?.pending_update_count ?? 0,
+        long_poll_ready: readiness !== null && !webhookConfigured,
+        telegram_probe_error: probeError,
+        blocker: probeError ?? (webhookConfigured ? 'telegram_webhook_conflict' : null)
     };
 }
 async function runHub(args, root, paths, configPath, json) {
+    const serviceManaged = args.includes('--service-managed');
+    const centerSupervisorPid = telegramCenterSupervisorPid(args);
     const config = await loadTelegramConfig(configPath);
     const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
     const machineRegistry = await loadRemoteMachineRegistry(readOption(args, '--machines') ?? remoteMachineRegistryPath(root));
     const sessionIndex = await loadRemoteSessionIndex(readOption(args, '--session-index') ?? remoteSessionIndexPath(controllingRoot), machineRegistry);
     const token = await resolveTelegramBotToken(config.bot_token_ref);
     const fingerprint = telegramTokenFingerprint(token);
+    const identityFingerprint = telegramRuntimeIdentityFingerprint(config, fingerprint);
     const owner = new TelegramOwnerLock({
         lockPath: paths.owner,
         tokenFingerprint: fingerprint,
+        reclaimDeadImmediately: centerSupervisorPid !== null,
         ...(config.owner_stale_ms === undefined ? {} : { staleMs: config.owner_stale_ms })
     });
     await owner.acquire();
-    const topics = new TelegramTopicRegistry(paths.topics);
+    const topics = new TelegramTopicRegistry(paths.topics, { identityFingerprint });
     const actions = new TelegramActionBroker(paths.actions);
     const audit = new TelegramAuditLedger(paths.audit, fingerprint);
     const router = new TelegramHubRouter({
@@ -196,6 +369,10 @@ async function runHub(args, root, paths, configPath, json) {
         audit
     });
     const api = new TelegramBotApiClient(token, { timeoutMs: (config.long_poll_timeout_sec ?? 25) * 1000 + 5_000 });
+    const ingress = new TelegramIngressSpool(paths.ingress, {
+        identityFingerprint,
+        legacyTokenFingerprint: fingerprint
+    });
     const runtime = new TelegramHubRuntime({
         config,
         router,
@@ -213,37 +390,102 @@ async function runHub(args, root, paths, configPath, json) {
         }),
         machineRegistry,
         sessionIndex,
-        projectionStatePath: paths.projection
+        projectionStatePath: paths.projection,
+        ingress
+    });
+    const polling = new TelegramPollingHub(api, runtime, owner, config.long_poll_timeout_sec ?? 25, {
+        ingress,
+        healthPath: paths.receive_health
     });
-    const polling = new TelegramPollingHub(api, runtime, owner, config.long_poll_timeout_sec ?? 25);
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    const supervisorMonitor = centerSupervisorPid === null
+        ? null
+        : setInterval(() => {
+            if (!telegramCenterSupervisorAlive(centerSupervisorPid))
+                controller.abort();
+        }, 250);
+    supervisorMonitor?.unref();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
     try {
         await polling.ensureLongPollingAllowed();
-        const sync = await runtime.initialize();
-        if (args.includes('--once')) {
-            const result = await polling.pollOnce();
-            return print({ schema: 'sks.telegram-hub-run.v1', ...result, sync }, json);
+        const receive = await polling.establishReadiness(controller.signal);
+        if (receive.stopped_reason === 'aborted') {
+            return print({
+                schema: 'sks.telegram-hub-run.v1',
+                ok: true,
+                processed: 0,
+                stopped_reason: 'aborted',
+                receive,
+                sync: null
+            }, json);
         }
-        const controller = new AbortController();
-        const stop = () => controller.abort();
-        process.once('SIGINT', stop);
-        process.once('SIGTERM', stop);
-        try {
-            const result = await polling.run(controller.signal);
-            return print({ schema: 'sks.telegram-hub-run.v1', ...result, sync }, json);
+        if (!receive.ok) {
+            return print(markTelegramHubMutationResult({
+                schema: 'sks.telegram-hub-run.v1',
+                ok: false,
+                processed: 0,
+                stopped_reason: receive.stopped_reason ?? 'receive_not_ready',
+                receive,
+                sync: null
+            }, { setExitCode: !serviceManaged }), json);
         }
-        finally {
-            process.off('SIGINT', stop);
-            process.off('SIGTERM', stop);
+        const sync = await runtime.initialize();
+        if (controller.signal.aborted) {
+            return print({
+                schema: 'sks.telegram-hub-run.v1',
+                ok: true,
+                processed: receive.received,
+                stopped_reason: 'aborted',
+                receive,
+                sync
+            }, json);
         }
+        await polling.drainPending();
+        if (args.includes('--once')) {
+            await polling.waitForIdle();
+            return print({
+                schema: 'sks.telegram-hub-run.v1',
+                ok: true,
+                processed: receive.received,
+                stopped_reason: null,
+                receive,
+                sync
+            }, json);
+        }
+        const result = await polling.run(controller.signal);
+        return print(markTelegramHubMutationResult({
+            schema: 'sks.telegram-hub-run.v1',
+            ...result,
+            receive,
+            sync
+        }, { setExitCode: !serviceManaged }), json);
     }
     finally {
+        if (supervisorMonitor)
+            clearInterval(supervisorMonitor);
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
         await runtime.close();
         await owner.release();
     }
 }
 async function assertHubSetupReady(controllingRoot, globalRoot, configPath) {
     const config = await loadTelegramConfig(configPath);
-    await resolveTelegramBotToken(config.bot_token_ref);
+    const token = await resolveTelegramBotToken(config.bot_token_ref);
+    let readiness;
+    try {
+        readiness = await probeTelegramBotReadiness(new TelegramBotApiClient(token, {
+            timeoutMs: 8_000,
+            maxRetries: 1
+        }));
+    }
+    catch (error) {
+        throw new Error(telegramProbeFailure(error));
+    }
+    if (readiness.webhook_configured)
+        throw new Error('telegram_webhook_conflict');
     const registry = await loadRemoteMachineRegistry(remoteMachineRegistryPath(globalRoot));
     const index = await loadRemoteSessionIndex(remoteSessionIndexPath(controllingRoot), registry);
     const bindings = await new RemoteCodexSessionBindingStore(remoteCodexSessionBindingsPath(controllingRoot)).list();
@@ -253,10 +495,82 @@ async function assertHubSetupReady(controllingRoot, globalRoot, configPath) {
         throw new Error('no_registered_codex_session');
     }
 }
+export function markTelegramHubMutationResult(result, options = {}) {
+    if (result.ok !== true && options.setExitCode !== false)
+        process.exitCode = 1;
+    return result;
+}
+export function telegramCenterSupervisorPid(args, actualParentPid = process.ppid) {
+    const supervisedCount = args.filter((value) => value === '--center-supervised').length;
+    const pidOptionCount = args.filter((value) => value === '--center-supervisor-pid').length;
+    if (supervisedCount === 0 && pidOptionCount === 0)
+        return null;
+    if (supervisedCount !== 1
+        || pidOptionCount !== 1
+        || args.includes('--service-managed')) {
+        throw new Error('telegram_center_supervisor_invalid');
+    }
+    const rawPid = readOption(args, '--center-supervisor-pid');
+    if (!rawPid || !/^[1-9]\d*$/.test(rawPid))
+        throw new Error('telegram_center_supervisor_invalid');
+    const pid = Number(rawPid);
+    if (!Number.isSafeInteger(pid) || pid !== actualParentPid) {
+        throw new Error('telegram_center_supervisor_invalid');
+    }
+    return pid;
+}
+export function telegramCenterSupervisorAlive(pid, probe = (candidate) => process.kill(candidate, 0)) {
+    try {
+        probe(pid);
+        return true;
+    }
+    catch (error) {
+        return error?.code !== 'ESRCH';
+    }
+}
 function readOption(args, name) {
     const index = args.indexOf(name);
     return index >= 0 && args[index + 1] ? String(args[index + 1]) : null;
 }
+export function telegramDeadLetterCommandRequest(args) {
+    const rawAction = args[1] && !String(args[1]).startsWith('-')
+        ? String(args[1])
+        : 'list';
+    const action = rawAction === 'status' ? 'list' : rawAction;
+    if (!['list', 'inspect', 'requeue', 'acknowledge'].includes(action)) {
+        throw new Error('unknown_dead_letter_action');
+    }
+    const updateId = readTelegramUpdateId(args);
+    if ((action === 'inspect' || action === 'requeue') && updateId === null) {
+        throw new Error('telegram_dead_letter_update_id_required');
+    }
+    return {
+        action: action,
+        updateId,
+        confirmed: args.includes('--yes')
+    };
+}
+function readTelegramUpdateId(args) {
+    const optionIndexes = args.flatMap((value, index) => value === '--update-id' ? [index] : []);
+    if (optionIndexes.length === 0)
+        return null;
+    if (optionIndexes.length !== 1)
+        throw new Error('telegram_dead_letter_update_id_invalid');
+    const raw = args[optionIndexes[0] + 1];
+    if (!raw || !/^\d+$/.test(raw))
+        throw new Error('telegram_dead_letter_update_id_invalid');
+    const updateId = Number(raw);
+    if (!Number.isSafeInteger(updateId))
+        throw new Error('telegram_dead_letter_update_id_invalid');
+    return updateId;
+}
+function telegramCenterSortDirection(value) {
+    if (value === null)
+        return null;
+    if (value === 'asc' || value === 'desc')
+        return value;
+    throw new Error('telegram_center_sort_direction_invalid');
+}
 function redactConfig(config) {
     const record = config;
     return {
@@ -266,6 +580,17 @@ function redactConfig(config) {
             : null
     };
 }
+async function updateTelegramIngressHealth(healthPath, counts) {
+    const receiveHealth = await readJson(healthPath, null);
+    if (receiveHealth?.schema !== 'sks.telegram-receive-health.v1')
+        return;
+    await writeTextAtomic(healthPath, `${JSON.stringify({
+        ...receiveHealth,
+        updated_at: nowIso(),
+        pending_ingress: counts.pending,
+        dead_letter_ingress: counts.dead_letters
+    }, null, 2)}\n`, { mode: 0o600 });
+}
 function print(value, json) {
     if (json)
         console.log(JSON.stringify(value, null, 2));
@@ -284,3 +609,46 @@ function publicError(err) {
         .replace(/(?:\/Users|\/home)\/[^\s]+/g, '[path-redacted]')
         .slice(0, 500);
 }
+function telegramProbeFailure(error) {
+    return error instanceof TelegramBotApiError && (error.errorCode === 401 || error.errorCode === 404)
+        ? 'telegram_bot_auth_failed'
+        : 'telegram_bot_probe_failed';
+}
+export function telegramNextActions(blockers) {
+    const actions = [];
+    if (blockers.includes('telegram_identity_migration_required')) {
+        actions.push('Stop the Hub, then reconnect this project once so SKS writes the v2 bot/pairing identity contract.');
+    }
+    if (blockers.includes('telegram_token_not_available') || blockers.includes('telegram_bot_auth_failed')) {
+        actions.push('Create or regenerate the bot token in @BotFather, then rerun setup with --bot-token-stdin.');
+    }
+    if (blockers.includes('telegram_webhook_conflict')) {
+        actions.push('Remove the existing webhook in the service that configured it, then rerun telegram status.');
+    }
+    if (blockers.includes('telegram_bot_probe_failed')) {
+        actions.push('Check network access to api.telegram.org, then rerun telegram status.');
+    }
+    if (blockers.includes('telegram_ingress_dead_letter_present')) {
+        actions.push('Inspect dead letters, stop the Hub, then explicitly requeue only safe entries or acknowledge an ambiguous entry before resending it.');
+    }
+    if (blockers.includes('telegram_pairing_missing') || blockers.some((blocker) => blocker.startsWith('telegram_pairing_invalid:'))) {
+        actions.push('Send /start to the bot in a private chat, then rerun telegram setup.');
+    }
+    if (blockers.includes('telegram_pairing_multiple_ids_requires_setup')) {
+        actions.push('Stop the hub, then rerun telegram setup to replace the ambiguous multi-ID config with one verified private chat and user.');
+    }
+    if (blockers.includes('no_registered_codex_session')) {
+        actions.push('Rerun telegram setup for this project root.');
+    }
+    if (blockers.includes('telegram_hub_not_running')) {
+        actions.push('Run sks telegram hub start --project-root \"$PWD\" --json after other blockers are cleared.');
+    }
+    return actions;
+}
+function hasMultipleTelegramPairingIds(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return (Array.isArray(record.paired_chat_ids) && record.paired_chat_ids.length > 1)
+        || (Array.isArray(record.paired_user_ids) && record.paired_user_ids.length > 1);
+}

package/dist/core/commands/triwiki-command.js

@@ -5,11 +5,21 @@ import { computeTriWikiAffectedGraph } from '../triwiki/triwiki-affected-graph.j
 import { buildTriWikiGateImpactMap } from '../triwiki/triwiki-gate-impact-map.js';
 import { DEFAULT_TRIWIKI_MODULE_CARDS } from '../triwiki/triwiki-module-card.js';
 import { summarizeTriWikiProofBank } from '../triwiki/triwiki-proof-bank.js';
+import { isTriWikiGraphSubcommand, triwikiGraphCommand } from './triwiki-graph-command.js';
 export async function triwikiCommand(args = []) {
     const root = await projectRoot();
     const sub = args[0] && !args[0].startsWith('-') ? args[0] : 'index';
     const json = flag(args, '--json');
     let result;
+    if (isTriWikiGraphSubcommand(sub)) {
+        const answer = await triwikiGraphCommand(root, sub, args.slice(1));
+        process.exitCode = answer.ok ? 0 : 2;
+        if (json)
+            return printJson(answer.result);
+        for (const line of answer.lines)
+            console.log(line);
+        return answer.result;
+    }
     if (sub === 'index') {
         result = {
             schema: 'sks.triwiki-index.v1',
@@ -26,7 +36,7 @@ export async function triwikiCommand(args = []) {
         result = summarizeTriWikiProofBank(root);
     }
     else {
-        console.error('Usage: sks triwiki index|affected|proof-bank [--json]');
+        console.error('Usage: sks triwiki index|affected|proof-bank|graph-status|graph-lint|graph-query [--json]');
         process.exitCode = 1;
         return null;
     }