cli.js

#!/usr/bin/env node
import fs from 'fs';
import os from 'os';
import path from 'path';
import { spawn, spawnSync } from 'child_process';
import { setTimeout as delay } from 'timers/promises';
import { fileURLToPath, pathToFileURL } from 'url';
import readline from 'readline';
import { AsyncLocalStorage } from 'node:async_hooks';
import { format as formatOutput } from 'node:util';
import { Command, Option } from 'commander';

import {
  acquireOwnerLock,
  acquireStoreLock as acquireStoreLockBase,
  acquireReadLock as acquireReadLockBase,
  isPidAlive,
  parseStoreLock,
  readStoreLock,
} from './store-lock.js';
import {
  addAccount,
  bindAccountIdentity,
  listAccounts,
  normalizePhoneNumber,
  resolveAccountContext,
} from './core/accounts.js';
import { loadConfig, normalizeConfig, saveConfig, validateConfig } from './core/config.js';
import {
  createMessageSyncService as createMessageSyncServiceBase,
  createServices as createServicesBase,
  createTelegramClient as createTelegramClientBase,
} from './core/services.js';
import { ArchiveReader } from './core/archive-reader.js';
import { runOwnerOperation } from './core/owner-operations.js';
import { createOwnerOperations } from './core/owner-operations.js';
import { callOwner, startOwnerIpc } from './core/owner-ipc.js';
import { startShutdownWatchdog } from './core/shutdown.js';
import { getTelegramRequestSignal } from './core/request-context.js';
import {
  buildSendErrorPayload,
  buildSendSuccessPayload,
  classifySendError,
  executeSendWithRetries,
  formatSendErrorMessage,
  parseRetryBackoff,
  SendCommandError,
} from './core/send-utils.js';
import { parseLaunchdList, resolveServiceIdentity } from './core/service-identity.js';
import { resolveStoreDir as resolveStoreDirBase } from './core/store.js';
import { formatErrorMessage, parseRequiredWaitSeconds, withSendRetry } from './core/retry.js';
import { startWebAppHandoff } from './core/webapp-handoff.js';

const CLI_PATH = fileURLToPath(import.meta.url);
const SERVICE_STATE_FILE = 'service-state.json';
const AUTH_SYNC_HINT = 'Run `tgcli sync --once` or `tgcli sync --follow` when you need archive data.';
const DEFAULT_SEND_PHOTO_RETRIES = 2;
const CONFIG_SPECS = [
  { key: 'apiId', path: ['apiId'], type: 'number' },
  { key: 'apiHash', path: ['apiHash'], type: 'string', secret: true },
  { key: 'phoneNumber', path: ['phoneNumber'], type: 'string' },
  { key: 'proxy', path: ['proxy'], type: 'string', secret: true },
  { key: 'mcp.enabled', path: ['mcp', 'enabled'], type: 'boolean' },
  { key: 'mcp.host', path: ['mcp', 'host'], type: 'string' },
  { key: 'mcp.port', path: ['mcp', 'port'], type: 'number' },
];
const SEND_PARSE_MODES = ['markdown', 'html', 'none'];
const ownerExecution = new AsyncLocalStorage();

function resolveStoreDir() {
  return ownerExecution.getStore()?.storeDir ?? resolveStoreDirBase();
}

function ownerServiceProxy(service, closeMethod) {
  return new Proxy(service, {
    get(target, property) {
      if (property === closeMethod) return async () => {};
      const value = Reflect.get(target, property, target);
      return typeof value === 'function' ? value.bind(target) : value;
    },
  });
}

function assertOwnerStore(context, storeDir) {
  if (!storeDir || fs.realpathSync(storeDir) !== fs.realpathSync(context.storeDir)) {
    throw new Error('Owner CLI handler attempted to access a different account store');
  }
}

function createServices(options) {
  const context = ownerExecution.getStore();
  if (!context) return createServicesBase(options);
  assertOwnerStore(context, options?.storeDir);
  return {
    ...context.services,
    telegramClient: context.telegramClient,
    messageSyncService: context.messageSyncService,
  };
}

function createTelegramClient(options) {
  const context = ownerExecution.getStore();
  if (context) assertOwnerStore(context, options?.storeDir);
  return context
    ? { telegramClient: context.telegramClient }
    : createTelegramClientBase(options);
}

function createMessageSyncService(telegramClient, options) {
  const context = ownerExecution.getStore();
  if (context) assertOwnerStore(context, options?.storeDir);
  return context
    ? { messageSyncService: context.messageSyncService }
    : createMessageSyncServiceBase(telegramClient, options);
}

function acquireStoreLock(storeDir) {
  return ownerExecution.getStore() ? () => {} : acquireStoreLockBase(storeDir);
}

function acquireReadLock(storeDir) {
  return ownerExecution.getStore() ? () => {} : acquireReadLockBase(storeDir);
}

const CLI_PROGRAM = buildProgram();

function buildProgram() {
  const program = new Command();
  program
    .name('tgcli')
    .description('Telegram CLI + MCP server')
    .usage('[options] <command>')
    .option('--account <id|alias|phone>', 'Telegram account profile')
    .option('--json', 'Machine-readable output')
    .option('--timeout <duration>', 'Wall-clock timeout (e.g. 30s, 5m)')
    .version(readVersion(), '--version', 'Print version and exit')
    .showHelpAfterError(true);

  const auth = program.command('auth').description('Authentication and session setup');
  auth
    .option('--follow', 'Continue syncing after login')
    .option('--force-sms', 'Force SMS code delivery instead of in-app')
    .option('--qr', 'Use QR-code login flow instead of confirmation code')
    .action(withGlobalOptions((globalFlags, options) =>
      runAuthLogin(globalFlags, options),
    ));
  auth
    .command('status')
    .description('Show auth status')
    .action(withGlobalOptions((globalFlags) => runAuthStatus(globalFlags)));
  auth
    .command('logout')
    .description('Log out of Telegram')
    .action(withGlobalOptions((globalFlags) => runAuthLogout(globalFlags)));

  const config = program.command('config').description('View and edit config');
  config
    .command('list')
    .description('List config values')
    .action(withGlobalOptions((globalFlags) => runConfigList(globalFlags)));
  config
    .command('get')
    .description('Get a config value')
    .argument('<key>', 'Config key')
    .action(withGlobalOptions((globalFlags, key) => runConfigGet(globalFlags, key)));
  config
    .command('set')
    .description('Set a config value')
    .argument('<key>', 'Config key')
    .argument('<value>', 'Config value')
    .action(withGlobalOptions((globalFlags, key, value) => runConfigSet(globalFlags, key, value)));
  config
    .command('unset')
    .description('Unset a config value')
    .argument('<key>', 'Config key')
    .action(withGlobalOptions((globalFlags, key) => runConfigUnset(globalFlags, key)));

  const accounts = program.command('accounts').description('Manage isolated Telegram account profiles');
  accounts
    .command('list')
    .description('List account profiles')
    .action(withGlobalOptions((globalFlags) => runAccountsList(globalFlags)));
  accounts
    .command('add')
    .description('Add an isolated account profile')
    .argument('<id>', 'Stable account profile id')
    .requiredOption('--phone <number>', 'Telegram phone number with country code')
    .option('--alias <name>', 'Additional account selector', collectList)
    .action(withGlobalOptions((globalFlags, id, options) => runAccountsAdd(globalFlags, id, options)));

  const sync = program.command('sync').description('Archive backfill and realtime sync');
  sync
    .option('--once', 'Run once and exit')
    .option('--follow', 'Keep syncing realtime updates')
    .option('--idle-exit <duration>', 'Exit after idle period')
    .action(withGlobalOptions((globalFlags, options) => runSync(globalFlags, options)));
  sync
    .command('status')
    .description('Show sync status')
    .action(withGlobalOptions((globalFlags) => runSyncStatus(globalFlags)));
  const syncJobs = sync.command('jobs').description('Manage sync jobs');
  syncJobs
    .command('list')
    .description('List sync jobs')
    .option('--status <status>', 'Filter by status (pending|in_progress|idle|error)')
    .option('--limit <n>', 'Limit results')
    .option('--channel <id|username>', 'Filter by channel')
    .action(withGlobalOptions((globalFlags, options) => runSyncJobsList(globalFlags, options)));
  syncJobs
    .command('add')
    .description('Add a sync job')
    .option('--chat <id|username>', 'Channel identifier')
    .option('--depth <n>', 'Maximum messages to backfill')
    .option('--min-date <iso>', 'Earliest date to backfill')
    .action(withGlobalOptions((globalFlags, options) => runSyncJobsAdd(globalFlags, options)));
  syncJobs
    .command('retry')
    .description('Retry failed jobs')
    .option('--job-id <n>', 'Retry by job id')
    .option('--channel <id|username>', 'Retry by channel')
    .option('--all-errors', 'Retry all error jobs')
    .action(withGlobalOptions((globalFlags, options) => runSyncJobsRetry(globalFlags, options)));
  syncJobs
    .command('cancel')
    .description('Cancel jobs')
    .option('--job-id <n>', 'Cancel by job id')
    .option('--channel <id|username>', 'Cancel by channel')
    .action(withGlobalOptions((globalFlags, options) => runSyncJobsCancel(globalFlags, options)));

  program
    .command('server')
    .description('Run background sync service (MCP optional)')
    .action(withGlobalOptions((globalFlags) => runServer(globalFlags)));

  program.command('owner').description('Inspect the active store owner')
    .command('request').description('Show the outcome of an owner request')
    .argument('<requestId>', 'Request ID shown after an uncertain result')
    .action(withGlobalOptions((globalFlags, requestId) => runOwnerRequestStatus(globalFlags, requestId)));

  const service = program.command('service').description('Manage background service');
  service
    .command('install')
    .description('Install service definition')
    .action(withGlobalOptions((globalFlags) => runServiceInstall(globalFlags)));
  service
    .command('start')
    .description('Start service')
    .action(withGlobalOptions((globalFlags) => runServiceStart(globalFlags)));
  service
    .command('stop')
    .description('Stop service')
    .action(withGlobalOptions((globalFlags) => runServiceStop(globalFlags)));
  service
    .command('status')
    .description('Show service status')
    .action(withGlobalOptions((globalFlags) => runServiceStatus(globalFlags)));
  service
    .command('logs')
    .description('Show service logs')
    .action(withGlobalOptions((globalFlags) => runServiceLogs(globalFlags)));

  program
    .command('doctor')
    .description('Diagnostics and sanity checks')
    .option('--connect', 'Connect to Telegram for live checks')
    .action(withGlobalOptions((globalFlags, options) => runDoctor(globalFlags, options)));

  const channels = program.command('channels').description('Channel discovery and settings');
  channels
    .command('list')
    .description('List channels')
    .option('--query <text>', 'Search by title or username')
    .option('--limit <n>', 'Limit results')
    .action(withGlobalOptions((globalFlags, options) => runChannelsList(globalFlags, options)));
  channels
    .command('show')
    .description('Show channel info')
    .option('--chat <id|username>', 'Channel identifier')
    .action(withGlobalOptions((globalFlags, options) => runChannelsShow(globalFlags, options)));
  channels
    .command('sync')
    .description('Enable or disable sync')
    .option('--chat <id|username>', 'Channel identifier')
    .option('--enable', 'Enable sync')
    .option('--disable', 'Disable sync')
    .action(withGlobalOptions((globalFlags, options) => runChannelsSync(globalFlags, options)));

  const messages = program.command('messages').description('List and search messages');
  messages
    .command('list')
    .description('List messages')
    .option('--chat <id|username>', 'Channel identifier', collectList)
    .option('--topic <id>', 'Forum topic id')
    .option('--source <source>', 'archive|live|both')
    .option('--after <iso>', 'Filter messages after date')
    .option('--before <iso>', 'Filter messages before date')
    .option('--limit <n>', 'Limit results')
    .action(withGlobalOptions((globalFlags, options) => runMessagesList(globalFlags, options)));
  messages
    .command('search')
    .description('Search messages')
    .argument('[query...]')
    .option('--query <text>', 'Search query')
    .option('--chat <id|username>', 'Channel identifier', collectList)
    .option('--topic <id>', 'Forum topic id')
    .option('--source <source>', 'archive|live|both')
    .option('--after <iso>', 'Filter messages after date')
    .option('--before <iso>', 'Filter messages before date')
    .option('--limit <n>', 'Limit results')
    .option('--regex <pattern>', 'Regex pattern')
    .option('--tag <tag>', 'Filter by tag', collectList)
    .option('--tags <tags>', 'Comma-separated tags')
    .option('--case-sensitive', 'Disable case-insensitive search')
    .action(withGlobalOptions((globalFlags, queryParts, options) =>
      runMessagesSearch(globalFlags, queryParts, options),
    ));
  messages
    .command('show')
    .description('Show a message')
    .option('--chat <id|username>', 'Channel identifier')
    .option('--id <msgId>', 'Message id')
    .option('--source <source>', 'archive|live|both')
    .action(withGlobalOptions((globalFlags, options) => runMessagesShow(globalFlags, options)));
  messages
    .command('edit-caption')
    .description('Edit the caption of an existing photo message')
    .requiredOption('--chat <id|username>', 'Chat containing the photo')
    .requiredOption('--id <msgId>', 'Photo message id')
    .requiredOption('--caption-file <path>', 'UTF-8 file with the new caption')
    .requiredOption('--expected-text-file <path>', 'UTF-8 file with the current caption; edit is refused if it differs')
    .option('--parse-mode <mode>', 'markdown|html|none', 'none')
    .action(withGlobalOptions((globalFlags, options) => runMessagesEditCaption(globalFlags, options)));
  messages
    .command('context')
    .description('Show message context')
    .option('--chat <id|username>', 'Channel identifier')
    .option('--id <msgId>', 'Message id')
    .option('--source <source>', 'archive|live|both')
    .option('--before <n>', 'Messages before')
    .option('--after <n>', 'Messages after')
    .action(withGlobalOptions((globalFlags, options) => runMessagesContext(globalFlags, options)));
  const messageButtons = messages.command('buttons').description('Inspect and click inline message buttons');
  messageButtons
    .command('list')
    .description('List inline buttons on a live message')
    .requiredOption('--chat <id|username>', 'Channel identifier')
    .requiredOption('--id <msgId>', 'Message id')
    .action(withGlobalOptions((globalFlags, options) => runMessageButtonsList(globalFlags, options)));
  messageButtons
    .command('click')
    .description('Click one callback button using 1-based row and column')
    .requiredOption('--chat <id|username>', 'Channel identifier')
    .requiredOption('--id <msgId>', 'Message id')
    .requiredOption('--row <n>', '1-based button row')
    .requiredOption('--column <n>', '1-based button column')
    .action(withGlobalOptions((globalFlags, options) => runMessageButtonClick(globalFlags, options)));

  const send = program.command('send').description('Send text, photos, or files');
  send
    .command('text')
    .description('Send a text message')
    .option('--to <id|username>', 'Recipient id or username')
    .addOption(new Option('--chat <id|username>', 'Alias for --to').hideHelp())
    .option('--message <text>', 'Message text')
    .addOption(new Option('--text <text>', 'Alias for --message').hideHelp())
    .option('--parse-mode <mode>', 'Parse mode: markdown|html|none')
    .option('--topic <id>', 'Forum topic id')
    .option('--reply-to <id>', 'Reply to message id')
    .option('--no-preview', 'Disable link preview')
    .option('--silent', 'Send without notification sound')
    .option('--no-forwards', 'Protect message from forwarding')
    .option('--schedule <iso>', 'Schedule message (ISO 8601 datetime)')
    .option('--retries <n>', 'Max retries on failure', '0')
    .action(withGlobalOptions((globalFlags, options) => runSendText(globalFlags, options)));
  send
    .command('photo')
    .description('Send a photo with preview')
    .option('--to <id|username>', 'Recipient id or username')
    .addOption(new Option('--chat <id|username>', 'Alias for --to').hideHelp())
    .option('--photo <path>', 'Photo path')
    .option('--caption <text>', 'Optional caption')
    .option('--parse-mode <mode>', 'Parse mode for caption: markdown|html|none')
    .option('--topic <id>', 'Forum topic id')
    .option('--reply-to <id>', 'Reply to message id')
    .option('--silent', 'Send without notification sound')
    .option('--no-forwards', 'Protect message from forwarding')
    .option('--caption-above', 'Show caption above media')
    .option('--spoiler', 'Blur media until tapped')
    .option('--schedule <iso>', 'Schedule message (ISO 8601 datetime)')
    .option('--retries <n>', 'Retry count for transient send failures')
    .option('--retry-backoff <value>', 'Retry backoff in ms or strategy: constant|linear|exponential')
    .action(withGlobalOptions((globalFlags, options) => runSendPhoto(globalFlags, options)));
  send
    .command('file')
    .description('Send a file')
    .option('--to <id|username>', 'Recipient id or username')
    .addOption(new Option('--chat <id|username>', 'Alias for --to').hideHelp())
    .option('--file <path>', 'File path')
    .option('--caption <text>', 'Optional caption')
    .option('--parse-mode <mode>', 'Parse mode for caption: markdown|html|none')
    .option('--filename <name>', 'Override filename')
    .option('--topic <id>', 'Forum topic id')
    .option('--reply-to <id>', 'Reply to message id')
    .option('--silent', 'Send without notification sound')
    .option('--no-forwards', 'Protect message from forwarding')
    .option('--caption-above', 'Show caption above media')
    .option('--spoiler', 'Blur media until tapped')
    .option('--schedule <iso>', 'Schedule message (ISO 8601 datetime)')
    .option('--force-document', 'Send as uncompressed document')
    .option('--retries <n>', 'Max retries on failure', '0')
    .action(withGlobalOptions((globalFlags, options) => runSendFile(globalFlags, options)));

  const media = program.command('media').description('Download media');
  media
    .command('download')
    .description('Download message media')
    .option('--chat <id|username>', 'Channel identifier')
    .option('--id <msgId>', 'Message id')
    .option('--output <path>', 'Output file path')
    .action(withGlobalOptions((globalFlags, options) => runMediaDownload(globalFlags, options)));

  const topics = program.command('topics').description('Forum topics');
  topics
    .command('list')
    .description('List topics')
    .option('--chat <id|username>', 'Channel identifier')
    .option('--limit <n>', 'Limit results')
    .action(withGlobalOptions((globalFlags, options) => runTopicsList(globalFlags, options)));
  topics
    .command('search')
    .description('Search topics')
    .option('--chat <id|username>', 'Channel identifier')
    .option('--query <text>', 'Search query')
    .option('--limit <n>', 'Limit results')
    .action(withGlobalOptions((globalFlags, options) => runTopicsSearch(globalFlags, options)));

  const webapp = program.command('webapp').description('Open an authenticated Telegram Mini App');
  webapp
    .command('serve')
    .description('Serve a one-time local redirect to a bot main Mini App without printing its signed URL')
    .requiredOption('--bot <username>', 'Bot username, for example @BotFather')
    .action(withGlobalOptions((globalFlags, options) => runWebappServe(globalFlags, options)));

  const tags = program.command('tags').description('Channel tags');
  tags
    .command('set')
    .description('Set channel tags')
    .option('--chat <id|username>', 'Channel identifier')
    .option('--tags <tags>', 'Comma-separated tags')
    .option('--tag <tag>', 'Tag', collectList)
    .option('--source <source>', 'Tag source')
    .action(withGlobalOptions((globalFlags, options) => runTagsSet(globalFlags, options)));
  tags
    .command('list')
    .description('List channel tags')
    .option('--chat <id|username>', 'Channel identifier')
    .option('--source <source>', 'Tag source')
    .action(withGlobalOptions((globalFlags, options) => runTagsList(globalFlags, options)));
  tags
    .command('search')
    .description('Search channels by tag')
    .option('--tag <tag>', 'Tag to search')
    .option('--source <source>', 'Tag source')
    .option('--limit <n>', 'Limit results')
    .action(withGlobalOptions((globalFlags, options) => runTagsSearch(globalFlags, options)));
  tags
    .command('auto')
    .description('Auto-tag channels')
    .option('--chat <id|username>', 'Channel identifier', collectList)
    .option('--limit <n>', 'Limit channels')
    .option('--source <source>', 'Tag source')
    .option('--no-refresh-metadata', 'Skip metadata refresh')
    .action(withGlobalOptions((globalFlags, options) => runTagsAuto(globalFlags, options)));

  const metadata = program.command('metadata').description('Channel metadata cache');
  metadata
    .command('get')
    .description('Show cached metadata')
    .option('--chat <id|username>', 'Channel identifier')
    .action(withGlobalOptions((globalFlags, options) => runMetadataGet(globalFlags, options)));
  metadata
    .command('refresh')
    .description('Refresh cached metadata')
    .option('--chat <id|username>', 'Channel identifier', collectList)
    .option('--limit <n>', 'Limit channels')
    .option('--force', 'Force refresh')
    .option('--only-missing', 'Only refresh missing metadata')
    .action(withGlobalOptions((globalFlags, options) => runMetadataRefresh(globalFlags, options)));

  const contacts = program.command('contacts').description('Contacts and people');
  contacts
    .command('search')
    .description('Search contacts')
    .argument('<query...>')
    .option('--limit <n>', 'Limit results')
    .action(withGlobalOptions((globalFlags, queryParts, options) =>
      runContactsSearch(globalFlags, queryParts, options),
    ));
  contacts
    .command('show')
    .description('Show contact profile')
    .option('--user <id>', 'User id')
    .action(withGlobalOptions((globalFlags, options) => runContactsShow(globalFlags, options)));
  const contactAlias = contacts.command('alias').description('Manage contact aliases');
  contactAlias
    .command('set')
    .description('Set contact alias')
    .option('--user <id>', 'User id')
    .option('--alias <name>', 'Alias')
    .action(withGlobalOptions((globalFlags, options) => runContactsAliasSet(globalFlags, options)));
  contactAlias
    .command('rm')
    .description('Remove contact alias')
    .option('--user <id>', 'User id')
    .action(withGlobalOptions((globalFlags, options) => runContactsAliasRm(globalFlags, options)));
  const contactTags = contacts.command('tags').description('Manage contact tags');
  contactTags
    .command('add')
    .description('Add contact tags')
    .option('--user <id>', 'User id')
    .option('--tag <tag>', 'Tag', collectList)
    .action(withGlobalOptions((globalFlags, options) => runContactsTagsAdd(globalFlags, options)));
  contactTags
    .command('rm')
    .description('Remove contact tags')
    .option('--user <id>', 'User id')
    .option('--tag <tag>', 'Tag', collectList)
    .action(withGlobalOptions((globalFlags, options) => runContactsTagsRm(globalFlags, options)));
  const contactNotes = contacts.command('notes').description('Manage contact notes');
  contactNotes
    .command('set')
    .description('Set contact notes')
    .option('--user <id>', 'User id')
    .option('--notes <text>', 'Notes')
    .action(withGlobalOptions((globalFlags, options) => runContactsNotesSet(globalFlags, options)));

  const groups = program.command('groups').description('Group management');
  groups
    .command('list')
    .description('List groups')
    .option('--query <text>', 'Search by title')
    .option('--limit <n>', 'Limit results')
    .action(withGlobalOptions((globalFlags, options) => runGroupsList(globalFlags, options)));
  groups
    .command('info')
    .description('Show group info')
    .option('--chat <id|username>', 'Group identifier')
    .action(withGlobalOptions((globalFlags, options) => runGroupsInfo(globalFlags, options)));
  const groupRequests = groups.command('requests').description('Manage join requests');
  groupRequests
    .command('list')
    .description('List pending join requests')
    .option('--chat <id|username>', 'Group identifier')
    .option('--limit <n>', 'Limit results')
    .option('--query <text>', 'Search pending requests by user')
    .option('--link <url>', 'Filter by invite link')
    .action(withGlobalOptions((globalFlags, options) => runGroupJoinRequestsList(globalFlags, options)));
  groupRequests
    .command('approve')
    .description('Approve a pending join request')
    .option('--chat <id|username>', 'Group identifier')
    .option('--user <id|username>', 'User identifier')
    .action(withGlobalOptions((globalFlags, options) => runGroupJoinRequestApprove(globalFlags, options)));
  groupRequests
    .command('decline')
    .description('Decline a pending join request')
    .option('--chat <id|username>', 'Group identifier')
    .option('--user <id|username>', 'User identifier')
    .action(withGlobalOptions((globalFlags, options) => runGroupJoinRequestDecline(globalFlags, options)));
  groups
    .command('rename')
    .description('Rename group')
    .option('--chat <id|username>', 'Group identifier')
    .option('--name <text>', 'New name')
    .action(withGlobalOptions((globalFlags, options) => runGroupsRename(globalFlags, options)));
  const groupMembers = groups.command('members').description('Manage group members');
  groupMembers
    .command('add')
    .description('Add members')
    .option('--chat <id|username>', 'Group identifier')
    .option('--user <id>', 'User id', collectList)
    .action(withGlobalOptions((globalFlags, options) => runGroupMembersAdd(globalFlags, options)));
  groupMembers
    .command('remove')
    .description('Remove members')
    .option('--chat <id|username>', 'Group identifier')
    .option('--user <id>', 'User id', collectList)
    .action(withGlobalOptions((globalFlags, options) => runGroupMembersRemove(globalFlags, options)));
  const groupInvite = groups.command('invite').description('Manage invite links');
  groupInvite
    .command('get')
    .description('Get invite link')
    .option('--chat <id|username>', 'Group identifier')
    .action(withGlobalOptions((globalFlags, options) => runGroupInviteLinkGet(globalFlags, options)));
  groupInvite
    .command('edit')
    .description('Edit an existing invite link')
    .option('--chat <id|username>', 'Group identifier')
    .option('--link <url>', 'Existing invite link')
    .option('--request-needed <true|false>', 'Require admin approval before joining')
    .action(withGlobalOptions((globalFlags, options) => runGroupInviteLinkEdit(globalFlags, options)));
  groupInvite
    .command('revoke')
    .description('Revoke invite link')
    .option('--chat <id|username>', 'Group identifier')
    .action(withGlobalOptions((globalFlags, options) => runGroupInviteLinkRevoke(globalFlags, options)));
  groups
    .command('join')
    .description('Join via invite code')
    .option('--code <invite-code>', 'Invite code')
    .action(withGlobalOptions((globalFlags, options) => runGroupsJoin(globalFlags, options)));
  groups
    .command('leave')
    .description('Leave group')
    .option('--chat <id|username>', 'Group identifier')
    .action(withGlobalOptions((globalFlags, options) => runGroupsLeave(globalFlags, options)));

  // --- Folders ---
  const folders = program.command('folders').description('Chat folder management');
  folders
    .command('list')
    .description('List all folders')
    .action(withGlobalOptions((globalFlags) => runFoldersList(globalFlags)));
  folders
    .command('show')
    .description('Show folder details')
    .argument('<folder>', 'Folder ID or title')
    .option('--resolve', 'Resolve peer IDs to names (slower, requires API calls)')
    .action(withGlobalOptions((globalFlags, folder, opts) => runFoldersShow(globalFlags, folder, opts)));
  folders
    .command('create')
    .description('Create a new folder')
    .requiredOption('--title <name>', 'Folder name (max 12 chars)')
    .option('--emoji <emoji>', 'Emoji icon')
    .option('--include-contacts', 'Include contacts')
    .option('--include-non-contacts', 'Include non-contacts')
    .option('--include-groups', 'Include groups')
    .option('--include-channels', 'Include channels')
    .option('--include-bots', 'Include bots')
    .option('--exclude-muted', 'Exclude muted')
    .option('--exclude-read', 'Exclude read')
    .option('--exclude-archived', 'Exclude archived')
    .option('--chat <id>', 'Chat to include (repeatable)', collectOption, [])
    .option('--exclude-chat <id>', 'Chat to exclude (repeatable)', collectOption, [])
    .option('--pin-chat <id>', 'Pin chat in folder (repeatable)', collectOption, [])
    .action(withGlobalOptions((globalFlags, options) => runFoldersCreate(globalFlags, options)));
  folders
    .command('edit')
    .description('Edit an existing folder')
    .argument('<folder>', 'Folder ID or title')
    .option('--title <name>', 'Folder name (max 12 chars)')
    .option('--emoji <emoji>', 'Emoji icon')
    .option('--include-contacts', 'Include contacts')
    .option('--no-include-contacts', 'Do not include contacts')
    .option('--include-non-contacts', 'Include non-contacts')
    .option('--no-include-non-contacts', 'Do not include non-contacts')
    .option('--include-groups', 'Include groups')
    .option('--no-include-groups', 'Do not include groups')
    .option('--include-channels', 'Include channels')
    .option('--no-include-channels', 'Do not include channels')
    .option('--include-bots', 'Include bots')
    .option('--no-include-bots', 'Do not include bots')
    .option('--exclude-muted', 'Exclude muted')
    .option('--no-exclude-muted', 'Do not exclude muted')
    .option('--exclude-read', 'Exclude read')
    .option('--no-exclude-read', 'Do not exclude read')
    .option('--exclude-archived', 'Exclude archived')
    .option('--no-exclude-archived', 'Do not exclude archived')
    .option('--chat <id>', 'Chat to include (repeatable)', collectOption, [])
    .option('--exclude-chat <id>', 'Chat to exclude (repeatable)', collectOption, [])
    .option('--pin-chat <id>', 'Pin chat in folder (repeatable)', collectOption, [])
    .action(withGlobalOptions((globalFlags, folder, options) => runFoldersEdit(globalFlags, folder, options)));
  folders
    .command('delete')
    .description('Delete a folder')
    .argument('<folder>', 'Folder ID or title')
    .action(withGlobalOptions((globalFlags, folder) => runFoldersDelete(globalFlags, folder)));
  folders
    .command('reorder')
    .description('Reorder folders')
    .requiredOption('--ids <id1,id2,...>', 'Comma-separated folder IDs in desired order')
    .action(withGlobalOptions((globalFlags, options) => runFoldersReorder(globalFlags, options)));
  const foldersChats = folders.command('chats').description('Manage chats in a folder');
  foldersChats
    .command('add')
    .description('Add chat to folder')
    .argument('<folder>', 'Folder ID or title')
    .requiredOption('--chat <chatId>', 'Chat identifier')
    .action(withGlobalOptions((globalFlags, folder, options) => runFoldersChatsAdd(globalFlags, folder, options)));
  foldersChats
    .command('remove')
    .description('Remove chat from folder')
    .argument('<folder>', 'Folder ID or title')
    .requiredOption('--chat <chatId>', 'Chat identifier')
    .action(withGlobalOptions((globalFlags, folder, options) => runFoldersChatsRemove(globalFlags, folder, options)));
  folders
    .command('join')
    .description('Join shared folder via invite link')
    .argument('<link>', 'Shared folder invite link')
    .action(withGlobalOptions((globalFlags, link) => runFoldersJoin(globalFlags, link)));

  disableHelpCommand(program);
  program.addHelpText('after', '\nUse "tgcli [command] --help" for more information about a command.');
  program.action(() => {
    program.help();
  });
  return program;
}

function disableHelpCommand(command) {
  command.addHelpCommand(false);
  for (const subcommand of command.commands) {
    disableHelpCommand(subcommand);
  }
}

function getGlobalFlags(command) {
  const options = command.optsWithGlobals();
  const timeoutMs = options.timeout ? parseDuration(options.timeout) : null;
  const baseStoreDir = resolveStoreDir();
  const accountContext = resolveAccountContext({
    baseStoreDir,
    selector: options.account || process.env.TGCLI_ACCOUNT || 'default',
  });
  process.env.TGCLI_STORE = accountContext.storeDir;
  return {
    account: accountContext,
    baseStoreDir,
    json: Boolean(options.json),
    timeout: options.timeout ?? null,
    timeoutMs,
  };
}

function commandPath(command) {
  const parts = [];
  for (let current = command; current?.parent; current = current.parent) {
    parts.unshift(current.name());
  }
  return parts.join(' ');
}

function normalizeOwnerArgs(name, args) {
  const normalized = structuredClone(args);
  const options = normalized.at(-1);
  if (options && typeof options === 'object') {
    const inputField = name === 'send photo' ? 'photo' : name === 'send file' ? 'file' : null;
    if (inputField && options[inputField]) options[inputField] = path.resolve(options[inputField]);
    if (name === 'media download' && options.output) options.output = path.resolve(options.output);
    if (name === 'messages edit-caption') {
      for (const field of ['captionFile', 'expectedTextFile']) {
        if (options[field]) options[field] = path.resolve(options[field]);
      }
    }
  }
  return normalized;
}

function readCachedOwnerResult(name, options, storeDir) {
  const methods = {
    'channels show': ['chat', 'getChannel'],
    'metadata get': ['chat', 'getChannelMetadata'],
    'contacts show': ['user', 'getContact'],
  };
  const match = methods[name];
  if (!match || !options?.[match[0]]) return null;
  let reader;
  try {
    reader = new ArchiveReader(storeDir);
    return reader[match[1]](options[match[0]]);
  } catch (error) {
    if (error.name === 'ArchiveUnavailableError' && error.cause?.code === 'SQLITE_CANTOPEN') return null;
    throw error;
  } finally {
    reader?.close();
  }
}

function withGlobalOptions(handler) {
  return async (...args) => {
    let globalFlags;
    try {
      const command = args[args.length - 1];
      globalFlags = getGlobalFlags(command);
      const name = commandPath(command);
      const actionArgs = args.slice(0, -1);
      if (name === 'send text' || name === 'send file') {
        validateSendParseMode(name, actionArgs.at(-1) ?? {});
      }
      if (name === 'auth' || name === 'auth logout') {
        const current = parseStoreLock(readStoreLock(resolveStoreDir()).info);
        if (current?.pid && isPidAlive(current.pid)) {
          if (name === 'auth') {
            const options = actionArgs.at(-1) ?? {};
            if (options.forceSms || options.qr) {
              throw new Error('An active owner is already authenticated; stop it before changing login method.');
            }
            const auth = await runOwnerOperation({ storeDir: resolveStoreDir(),
              operation: 'auth.current', timeoutMs: globalFlags.timeoutMs ?? 30000 });
            if (!auth.authenticated) throw new Error('Store owner has no authenticated Telegram session.');
            if (globalFlags.json) writeJson({ authenticated: true, archiveReady: true, running: true });
            else console.log(`Authenticated${auth.username ? ` as @${auth.username}` : ''}; sync is running.`);
          } else {
            const result = await runOwnerOperation({ storeDir: resolveStoreDir(),
              operation: 'auth.logout', timeoutMs: globalFlags.timeoutMs ?? 30000 });
            if (globalFlags.json) writeJson(result);
            else console.log('Logged out.');
          }
          return;
        }
      }
      const archiveMessages = ['messages list', 'messages search', 'messages show', 'messages context'].includes(name) &&
        resolveSource(actionArgs.at(-1)?.source) === 'archive';
      const archiveTags = name === 'tags list' || name === 'tags search';
      const configWrite = name === 'config set' || name === 'config unset';
      const unconfiguredAuthStatus = name === 'auth status' &&
        getStoreConfig(resolveStoreDir()).missing.length > 0;
      if (ownerCliHandlers[name] && !archiveMessages && !archiveTags && !unconfiguredAuthStatus) {
        const cached = readCachedOwnerResult(name, actionArgs.at(-1), resolveStoreDir());
        if (cached) {
          if (globalFlags.json) writeJson(cached);
          else console.log(JSON.stringify(cached, null, 2));
          return;
        }
        let result;
        try {
          result = await runOwnerOperation({
            storeDir: resolveStoreDir(),
            operation: 'cli.execute',
            args: { commandPath: name, args: normalizeOwnerArgs(name, actionArgs),
              flags: { json: globalFlags.json, timeoutMs: globalFlags.timeoutMs } },
            timeoutMs: globalFlags.timeoutMs,
            localHandler: configWrite ? () => handler(globalFlags, ...args) : undefined,
          });
        } catch (error) {
          if (['channels show', 'metadata get', 'contacts show'].includes(name) &&
              error.code === 'OWNER_UNAVAILABLE') {
            const unavailable = new Error('Not in archive; store owner is unavailable for live lookup.');
            unavailable.code = 'OWNER_UNAVAILABLE';
            throw unavailable;
          }
          throw error;
        }
        if (result == null) return;
        if (result.stderr) process.stderr.write(result.stderr);
        if (result.stdout) process.stdout.write(result.stdout);
        return;
      }
      if (classifyCliRoute(name) === null) {
        throw new Error(`CLI command has no store route: ${name}`);
      }
      await handler(globalFlags, ...args);
    } catch (error) {
      writeError(error, globalFlags?.json ?? process.argv.includes('--json'));
      process.exitCode = 1;
    }
  };
}

async function runAccountsList(globalFlags) {
  const accounts = listAccounts(globalFlags.baseStoreDir);
  if (globalFlags.json) {
    writeJson(accounts);
    return;
  }
  if (accounts.length === 0) {
    console.log('No additional account profiles configured.');
    return;
  }
  for (const account of accounts) {
    const aliases = account.aliases.length > 0 ? ` (${account.aliases.join(', ')})` : '';
    console.log(`${account.id}: ${account.phoneNumber}${aliases}`);
  }
}

async function runAccountsAdd(globalFlags, id, options = {}) {
  const requestedPhone = normalizePhoneNumber(options.phone);
  const { config: defaultConfig, rawConfig: defaultRawConfig } = loadConfig(globalFlags.baseStoreDir);
  const accountConfig = normalizeConfig(defaultRawConfig ?? {}, { includeEnv: false });
  if (defaultConfig?.phoneNumber
      && normalizePhoneNumber(defaultConfig.phoneNumber) === requestedPhone) {
    throw new Error(`Phone ${requestedPhone} already belongs to the default account.`);
  }
  const account = addAccount(globalFlags.baseStoreDir, {
    id,
    phoneNumber: requestedPhone,
    aliases: options.alias ?? [],
  });
  accountConfig.phoneNumber = account.phoneNumber;
  saveConfig(account.storeDir, accountConfig);
  if (globalFlags.json) {
    writeJson(account);
    return;
  }
  console.log(`Added account ${account.id} (${account.phoneNumber}). Run \`tgcli --account ${account.id} auth\`.`);
}

function writeJson(payload) {
  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
}

function writeError(error, asJson) {
  if (error instanceof SendCommandError) {
    if (asJson) {
      process.stderr.write(`${JSON.stringify(buildSendErrorPayload(error.details), null, 2)}\n`);
    } else {
      process.stderr.write(`${formatSendErrorMessage(error.details)}\n`);
    }
    return;
  }

  const message = error?.message ?? String(error);
  if (asJson) {
    const payload = { ok: false, error: message };
    if (error?.code) payload.code = error.code;
    if (error?.requestId) payload.requestId = error.requestId;
    if (error?.retryLog?.length > 0) {
      payload.attempts = error.attempts;
      payload.retry_log = error.retryLog;
    }
    process.stderr.write(`${JSON.stringify(payload)}\n`);
  } else {
    process.stderr.write(`${message}\n`);
  }
}


function collectOption(value, previous) {
  return previous.concat([value]);
}

function parseDuration(value) {
  if (typeof value !== 'string' || !value.trim()) {
    return null;
  }
  const raw = value.trim();
  const match = raw.match(/^(\d+)(ms|s|m|h)?$/i);
  if (!match) {
    throw new Error(`Invalid duration: ${value}`);
  }
  const amount = Number(match[1]);
  const unit = (match[2] || 's').toLowerCase();
  if (unit === 'ms') return amount;
  if (unit === 's') return amount * 1000;
  if (unit === 'm') return amount * 60 * 1000;
  if (unit === 'h') return amount * 60 * 60 * 1000;
  return amount * 1000;
}

function resolveConfigSpec(key) {
  if (typeof key !== 'string' || !key.trim()) {
    throw new Error('Config key is required.');
  }
  const normalized = key.trim().toLowerCase();
  const spec = CONFIG_SPECS.find((entry) => entry.key.toLowerCase() === normalized);
  if (!spec) {
    const allowed = CONFIG_SPECS.map((entry) => entry.key).join(', ');
    throw new Error(`Unknown config key "${key}". Supported keys: ${allowed}.`);
  }
  return spec;
}

function normalizeOutputValue(value) {
  if (value === undefined || value === null) {
    return null;
  }
  if (typeof value === 'string' && !value.trim()) {
    return null;
  }
  return value;
}

function maskSecret(value) {
  if (value === null || value === undefined) {
    return null;
  }
  const str = String(value);
  if (str.length <= 4) {
    return '****';
  }
  return `${'*'.repeat(str.length - 4)}${str.slice(-4)}`;
}

function formatConfigValue(value) {
  if (value === null || value === undefined) {
    return 'unset';
  }
  if (typeof value === 'boolean') {
    return value ? 'true' : 'false';
  }
  return String(value);
}

function getValueAtPath(target, pathParts) {
  let current = target;
  for (const part of pathParts) {
    if (!current || typeof current !== 'object' || !(part in current)) {
      return undefined;
    }
    current = current[part];
  }
  return current;
}

function setValueAtPath(target, pathParts, value) {
  let current = target;
  for (let index = 0; index < pathParts.length - 1; index += 1) {
    const part = pathParts[index];
    if (!current[part] || typeof current[part] !== 'object') {
      current[part] = {};
    }
    current = current[part];
  }
  current[pathParts[pathParts.length - 1]] = value;
}

function deleteValueAtPath(target, pathParts) {
  let current = target;
  for (let index = 0; index < pathParts.length - 1; index += 1) {
    const part = pathParts[index];
    if (!current || typeof current !== 'object') {
      return;
    }
    current = current[part];
  }
  if (current && typeof current === 'object') {
    delete current[pathParts[pathParts.length - 1]];
  }
}

function parseBooleanValue(value) {
  if (typeof value === 'boolean') {
    return value;
  }
  if (typeof value === 'number') {
    return value !== 0;
  }
  if (typeof value === 'string') {
    const normalized = value.trim().toLowerCase();
    if (['true', '1', 'yes', 'y', 'on'].includes(normalized)) {
      return true;
    }
    if (['false', '0', 'no', 'n', 'off'].includes(normalized)) {
      return false;
    }
  }
  throw new Error('Value must be boolean (true/false).');
}

function parseNumberValue(value, label) {
  const parsed = Number(value);
  if (!Number.isFinite(parsed) || parsed <= 0) {
    throw new Error(`${label} must be a positive number.`);
  }
  return parsed;
}

function parseStringValue(value, label) {
  if (value === undefined || value === null) {
    throw new Error(`${label} is required.`);
  }
  const trimmed = String(value).trim();
  if (!trimmed) {
    throw new Error(`${label} must not be empty.`);
  }
  return trimmed;
}

function parseConfigValue(spec, rawValue) {
  if (spec.type === 'boolean') {
    return parseBooleanValue(rawValue);
  }
  if (spec.type === 'number') {
    return parseNumberValue(rawValue, spec.key);
  }
  return parseStringValue(rawValue, spec.key);
}

function runCommand(command, args, options = {}) {
  const result = spawnSync(command, args, {
    encoding: 'utf8',
    ...options,
  });
  return {
    status: result.status ?? 1,
    stdout: result.stdout ?? '',
    stderr: result.stderr ?? '',
    error: result.error ?? null,
  };
}

function getServiceStatePath(storeDir) {
  return path.join(storeDir, SERVICE_STATE_FILE);
}

function readServiceState(storeDir) {
  try {
    const raw = fs.readFileSync(getServiceStatePath(storeDir), 'utf8');
    return JSON.parse(raw);
  } catch (error) {
    return null;
  }
}

function getLaunchdPaths(identity = resolveServiceIdentity()) {
  const baseDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
  return {
    plistPath: path.join(baseDir, `${identity.launchdLabel}.plist`),
    logPath: path.join(os.homedir(), 'Library', 'Logs', `${identity.logBasename}.log`),
    errorLogPath: path.join(os.homedir(), 'Library', 'Logs', `${identity.logBasename}.error.log`),
  };
}

function getSystemdPath(identity = resolveServiceIdentity()) {
  return path.join(os.homedir(), '.config', 'systemd', 'user', `${identity.systemdServiceName}.service`);
}

function xmlEscape(value) {
  return String(value)
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&apos;');
}

function buildLaunchdPlist({ label, nodePath, cliPath, envVars, logPath, errorLogPath }) {
  const envEntries = Object.entries(envVars || {})
    .map(([key, value]) => `    <key>${xmlEscape(key)}</key>\n    <string>${xmlEscape(value)}</string>`)
    .join('\n');
  const envBlock = envEntries
    ? `  <key>EnvironmentVariables</key>\n  <dict>\n${envEntries}\n  </dict>\n`
    : '';

  return [
    '<?xml version="1.0" encoding="UTF-8"?>',
    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
    '<plist version="1.0">',
    '<dict>',
    `  <key>Label</key>`,
    `  <string>${xmlEscape(label)}</string>`,
    '  <key>ProgramArguments</key>',
    '  <array>',
    `    <string>${xmlEscape(nodePath)}</string>`,
    `    <string>${xmlEscape(cliPath)}</string>`,
    '    <string>server</string>',
    '  </array>',
    envBlock.trimEnd(),
    '  <key>RunAtLoad</key>',
    '  <true/>',
    '  <key>KeepAlive</key>',
    '  <true/>',
    `  <key>StandardOutPath</key>`,
    `  <string>${xmlEscape(logPath)}</string>`,
    `  <key>StandardErrorPath</key>`,
    `  <string>${xmlEscape(errorLogPath)}</string>`,
    '</dict>',
    '</plist>',
    '',
  ]
    .filter((line) => line !== '')
    .join('\n');
}

function buildSystemdService({ nodePath, cliPath, envVars }) {
  const envLines = Object.entries(envVars || {}).map(
    ([key, value]) => `Environment=${key}=${JSON.stringify(String(value))}`,
  );
  return [
    '[Unit]',
    'Description=tgcli background service',
    'After=network-online.target',
    '',
    '[Service]',
    `ExecStart=${nodePath} ${cliPath} server`,
    'Restart=on-failure',
    ...envLines,
    '',
    '[Install]',
    'WantedBy=default.target',
    '',
  ].join('\n');
}

function parseBrewServicesList(output) {
  const lines = output.split('\n').slice(1);
  for (const line of lines) {
    if (!line.trim()) continue;
    const [name, status] = line.trim().split(/\s+/);
    if (name === 'tgcli') {
      return { status };
    }
  }
  return null;
}

function detectBrewService() {
  const brewCheck = runCommand('brew', ['--version']);
  if (brewCheck.status !== 0) {
    return { available: false };
  }
  const list = runCommand('brew', ['list', '--formula', 'tgcli']);
  if (list.status !== 0) {
    return { available: true, installed: false };
  }
  const prefixResult = runCommand('brew', ['--prefix', 'tgcli']);
  const brewPrefix = prefixResult.status === 0 ? prefixResult.stdout.trim() : null;
  const cliPath = fs.realpathSync(CLI_PATH);
  const brewCliMatch = brewPrefix ? cliPath.startsWith(path.join(brewPrefix, 'libexec')) : false;

  const servicesResult = runCommand('brew', ['services', 'list']);
  const serviceEntry = servicesResult.status === 0 ? parseBrewServicesList(servicesResult.stdout) : null;
  const serviceAvailable = Boolean(serviceEntry);

  return {
    available: true,
    installed: true,
    brewPrefix,
    brewCliMatch,
    serviceAvailable,
    serviceStatus: serviceEntry?.status ?? null,
  };
}

function resolveServiceManager(accountId = 'default') {
  const brewInfo = detectBrewService();
  if (accountId === 'default' && brewInfo.available && brewInfo.installed && brewInfo.serviceAvailable) {
    return { manager: 'brew', brewInfo };
  }
  if (process.platform === 'darwin') {
    return { manager: 'launchd', brewInfo };
  }
  if (process.platform === 'linux') {
    const systemctlCheck = runCommand('systemctl', ['--user', '--version']);
    if (systemctlCheck.status !== 0) {
      return { manager: 'unsupported', brewInfo };
    }
    return { manager: 'systemd', brewInfo };
  }
  return { manager: 'unsupported', brewInfo };
}

function runWithTimeout(task, timeoutMs, onTimeout) {
  // Owner IPC has its own deadline. Let an accepted operation finish before its
  // shared services can be closed or a transient owner claim can be released.
  if (ownerExecution.getStore()) {
    return task();
  }
  if (!timeoutMs) {
    return task();
  }
  let timeoutId;
  const timeoutPromise = new Promise((_, reject) => {
    timeoutId = setTimeout(async () => {
      try {
        if (onTimeout) {
          await onTimeout();
        }
      } finally {
        reject(new Error('Timeout'));
      }
    }, timeoutMs);
  });
  return Promise.race([task(), timeoutPromise]).finally(() => {
    if (timeoutId) {
      clearTimeout(timeoutId);
    }
  });
}

async function claimStoreOwner(storeDir, options, timeoutMs) {
  const deadline = Date.now() + (timeoutMs ?? 30000);
  while (Date.now() < deadline) {
    try {
      return acquireOwnerLock(storeDir, options);
    } catch (error) {
      if (!error.message.includes('locked') && !error.message.includes('readers') &&
          !error.message.includes('recovery')) throw error;
      await delay(100);
    }
  }
  throw new Error('Timed out waiting for the store owner');
}

async function refreshDialogsWithRetry(messageSyncService, options = {}) {
  const maxWaitSeconds = options.maxWaitSeconds ?? 30;
  try {
    return await messageSyncService.refreshChannelsFromDialogs();
  } catch (error) {
    const waitSeconds = parseRequiredWaitSeconds(error);
    if (!waitSeconds || waitSeconds > maxWaitSeconds) {
      throw error;
    }
    process.stderr.write(`Rate limited while seeding dialogs. Waiting ${waitSeconds}s and retrying once...\n`);
    await delay(waitSeconds * 1000);
    return await messageSyncService.refreshChannelsFromDialogs();
  }
}

function normalizeSendCommandError(error, { method, retries, attempt = 1 } = {}) {
  if (error instanceof SendCommandError) {
    return error;
  }
  if (error instanceof TypeError || error instanceof ReferenceError || error instanceof SyntaxError || error instanceof RangeError) {
    return error;
  }
  return new SendCommandError(classifySendError(error, { method, retries, attempt }));
}

function logSendRetry(details, globalFlags) {
  if (globalFlags.json) {
    process.stderr.write(`${JSON.stringify({ event: 'retry', type: details.type, method: details.method, message: details.message, attempt: details.attempt, retries: details.retries })}\n`);
    return;
  }
  const totalAttempts = (details.retries ?? 0) + 1;
  const codeSuffix = details.code !== undefined && details.code !== null && details.code !== ''
    ? ` (${details.code})`
    : '';
  process.stderr.write(
    `${details.method} transient ${details.type} error on attempt ${details.attempt}/${totalAttempts}${codeSuffix}; retrying...\n`,
  );
}

function readVersion() {
  try {
    const pkgPath = new URL('./package.json', import.meta.url);
    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
    return pkg.version || '0.0.0';
  } catch (error) {
    return '0.0.0';
  }
}

function promptInput(question) {
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });
  return new Promise(resolve => {
    rl.question(question, answer => {
      rl.close();
      resolve(answer.trim());
    });
  });
}

function getStoreConfig(storeDir) {
  const { config } = loadConfig(storeDir);
  const normalized = normalizeConfig(config ?? {});
  const missing = validateConfig(normalized);
  return { config: normalized, missing };
}

async function ensureStoreConfig(storeDir) {
  const { config, missing } = getStoreConfig(storeDir);
  if (missing.length === 0) {
    return config;
  }

  const updated = { ...config };
  if (!updated.apiId) {
    updated.apiId = await promptInput('Telegram API ID: ');
  }
  if (!updated.apiHash) {
    updated.apiHash = await promptInput('Telegram API hash: ');
  }
  if (!updated.phoneNumber) {
    updated.phoneNumber = await promptInput('Telegram phone number (+...): ');
  }

  const normalized = normalizeConfig(updated);
  const remaining = validateConfig(normalized);
  if (remaining.length > 0) {
    throw new Error('Missing tgcli configuration. Run "tgcli auth" to set credentials.');
  }
  saveConfig(storeDir, normalized);
  return normalized;
}

function parseScheduleDate(value) {
  if (value === undefined || value === null || value === '') {
    return undefined;
  }
  const date = new Date(value);
  if (isNaN(date.getTime())) {
    throw new Error('--schedule must be a valid ISO 8601 datetime');
  }
  const now = Date.now();
  if (date.getTime() < now) {
    throw new Error('--schedule must be in the future');
  }
  const maxFuture = now + 365 * 24 * 60 * 60 * 1000;
  if (date.getTime() > maxFuture) {
    throw new Error('--schedule must be within 365 days from now');
  }
  return Math.floor(date.getTime() / 1000);
}

function resolveSendAliases(options) {
  if (!options.to && options.chat) options.to = options.chat;
  if (!options.message && options.text) options.message = options.text;
}

function parsePositiveInt(value, label) {
  if (value === undefined || value === null || value === '') {
    return null;
  }
  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    throw new Error(`${label} must be a positive integer`);
  }
  return parsed;
}

function parseNonNegativeInt(value, label) {
  if (value === undefined || value === null || value === '') {
    return null;
  }
  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed < 0) {
    throw new Error(`${label} must be a non-negative integer`);
  }
  return parsed;
}

function collectList(value, previous) {
  const list = previous ?? [];
  list.push(value);
  return list;
}

function parseListValues(value) {
  const raw = Array.isArray(value) ? value : (value ? [value] : []);
  return raw
    .flatMap((entry) => String(entry).split(','))
    .map((entry) => entry.trim())
    .filter(Boolean);
}

function parseSendParseMode(value) {
  if (value === undefined || value === null || value === '') {
    return null;
  }
  const normalized = String(value).trim().toLowerCase();
  if (!SEND_PARSE_MODES.includes(normalized)) {
    throw new Error(`--parse-mode must be one of: ${SEND_PARSE_MODES.join(', ')}`);
  }
  return normalized;
}

function validateSendParseMode(commandName, options) {
  const parseMode = parseSendParseMode(options.parseMode);
  if (commandName === 'send file' && parseMode &&
      !(typeof options.caption === 'string' && options.caption.trim())) {
    throw new Error('--parse-mode requires --caption for send file');
  }
  return parseMode;
}

function resolveSource(source) {
  const resolved = source ? String(source).toLowerCase() : 'archive';
  if (!['archive', 'live', 'both'].includes(resolved)) {
    throw new Error(`Invalid source: ${source}`);
  }
  return resolved;
}

function openMessageCommandServices(storeDir, source) {
  if (source === 'archive') {
    const messageSyncService = new ArchiveReader(storeDir);
    return {
      telegramClient: null,
      messageSyncService,
      close: async () => messageSyncService.close(),
    };
  }

  const release = acquireReadLock(storeDir);
  try {
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    return {
      telegramClient,
      messageSyncService,
      close: async () => {
        try {
          await messageSyncService.shutdown();
        } finally {
          try {
            await telegramClient.destroy();
          } finally {
            release();
          }
        }
      },
    };
  } catch (error) {
    release();
    throw error;
  }
}

function parseDateMs(value, label) {
  if (!value) {
    return null;
  }
  const ts = Date.parse(value);
  if (Number.isNaN(ts)) {
    throw new Error(`Invalid ${label}: ${value}`);
  }
  return ts;
}

function filterLiveMessagesByDate(messages, fromDate, toDate) {
  const fromMs = parseDateMs(fromDate, 'after');
  const toMs = parseDateMs(toDate, 'before');
  if (!fromMs && !toMs) {
    return messages;
  }
  return messages.filter((message) => {
    const ts = typeof message.date === 'number' ? message.date * 1000 : null;
    if (!ts) {
      return false;
    }
    if (fromMs && ts < fromMs) {
      return false;
    }
    if (toMs && ts > toMs) {
      return false;
    }
    return true;
  });
}

function formatLiveMessage(message, context) {
  const dateIso = message.date ? new Date(message.date * 1000).toISOString() : null;
  return {
    channelId: context.channelId ?? message.peer_id ?? null,
    peerTitle: context.peerTitle ?? null,
    username: context.username ?? null,
    messageId: message.id,
    date: dateIso,
    fromId: message.from_id ?? null,
    fromUsername: message.from_username ?? null,
    fromDisplayName: message.from_display_name ?? null,
    fromPeerType: message.from_peer_type ?? null,
    fromIsBot: typeof message.from_is_bot === 'boolean' ? message.from_is_bot : null,
    text: message.text ?? message.message ?? '',
    urls: message.urls ?? null,
    media: message.media ?? null,
    topicId: message.topic_id ?? null,
    inlineButtons: message.inline_buttons ?? null,
  };
}

function getMessageSenderLabel(message) {
  return message.fromDisplayName || message.fromUsername || message.fromId || null;
}

function groupMessagesByChannel(messages) {
  const groups = new Map();
  for (const message of messages) {
    const channelId = message.channelId ?? 'unknown';
    const key = String(channelId);
    let group = groups.get(key);
    if (!group) {
      group = {
        channelId: key,
        peerTitle: message.peerTitle ?? null,
        username: message.username ?? null,
        messages: [],
      };
      groups.set(key, group);
    } else {
      if (!group.peerTitle && message.peerTitle) {
        group.peerTitle = message.peerTitle;
      }
      if (!group.username && message.username) {
        group.username = message.username;
      }
    }
    group.messages.push(message);
  }
  return Array.from(groups.values());
}

function formatPeerHeaderLabel(group) {
  const title = typeof group.peerTitle === 'string' ? group.peerTitle.trim() : '';
  let username = typeof group.username === 'string' ? group.username.trim() : '';
  if (username.startsWith('@')) {
    username = username.slice(1);
  }
  const handle = username ? `@${username}` : '';
  if (title) {
    if (handle && !title.includes(handle)) {
      return `"${title}" (${handle})`;
    }
    return `"${title}"`;
  }
  if (handle) {
    return `${handle}`;
  }
  return group.channelId || 'unknown';
}

function messageDateMs(message) {
  const ts = Date.parse(message.date ?? '');
  return Number.isNaN(ts) ? 0 : ts;
}

function mergeMessageSets(sets, limit) {
  const map = new Map();
  for (const list of sets) {
    for (const message of list) {
      const channelId = message.channelId ?? '';
      const messageId = message.messageId ?? message.id;
      const key = `${String(channelId)}:${String(messageId)}`;
      if (!map.has(key) || message.source === 'live') {
        map.set(key, message);
      }
    }
  }
  const merged = Array.from(map.values());
  merged.sort((a, b) => messageDateMs(b) - messageDateMs(a));
  return limit && limit > 0 ? merged.slice(0, limit) : merged;
}

function normalizeInviteCode(value) {
  if (typeof value !== 'string' || !value.trim()) {
    return null;
  }
  const trimmed = value.trim();
  if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
    return trimmed;
  }
  if (trimmed.startsWith('t.me/')) {
    return `https://${trimmed}`;
  }
  if (trimmed.startsWith('+')) {
    return `https://t.me/${trimmed}`;
  }
  if (trimmed.startsWith('@')) {
    return trimmed;
  }
  return `https://t.me/joinchat/${trimmed}`;
}

async function withShutdown(handler) {
  let stopping = false;
  const stop = async () => {
    if (stopping) return;
    stopping = true;
    try {
      await handler();
    } finally {
      process.exit(0);
    }
  };
  process.on('SIGINT', () => void stop());
  process.on('SIGTERM', () => void stop());
}

async function waitForIdle(service, idleExitMs) {
  let idleStart = null;
  while (true) {
    const stats = service.getQueueStats();
    const active = stats.pending + stats.in_progress;
    if (!stats.processing && active === 0) {
      if (!idleStart) {
        idleStart = Date.now();
      }
      if (Date.now() - idleStart >= idleExitMs) {
        return;
      }
    } else {
      idleStart = null;
    }
    await delay(500);
  }
}

async function runAuthStatus(globalFlags) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const { config, missing } = getStoreConfig(storeDir);
    if (missing.length > 0) {
      if (globalFlags.json) {
        writeJson({ authenticated: false, configured: false });
      } else {
        console.log('Not authenticated. Run `tgcli auth`.');
      }
      return;
    }
    const { telegramClient } = createTelegramClient({ storeDir, config, disableUpdates: true });
    let messageSyncService = null;
    let search = { enabled: null };
    let archiveError = null;
    try {
      try {
        ({ messageSyncService } = createMessageSyncService(telegramClient, { storeDir }));
        search = messageSyncService.getSearchStatus();
      } catch (error) {
        archiveError = formatErrorMessage(error);
      }
      const me = await telegramClient.getCurrentUser();
      const authenticated = Boolean(me);
      const username = me?.username ? `@${me.username}` : null;
      const payload = {
        authenticated,
        configured: true,
        phoneNumber: config.phoneNumber || null,
        username: me?.username ?? null,
        ftsEnabled: archiveError ? null : search.enabled,
        archiveReady: !archiveError,
        archiveError,
      };
      if (globalFlags.json) {
        writeJson(payload);
      } else {
        if (!authenticated) {
          console.log('Not authenticated. Run `tgcli auth`.');
        } else if (username && config.phoneNumber) {
          console.log(`Authenticated as ${config.phoneNumber} (${username}).`);
        } else if (username) {
          console.log(`Authenticated as ${username}.`);
        } else {
          console.log(config.phoneNumber ? `Authenticated as ${config.phoneNumber}.` : 'Authenticated.');
        }
        if (archiveError) {
          console.log(`Archive unavailable: ${archiveError}`);
        }
      }
    } finally {
      if (messageSyncService) {
        await messageSyncService.shutdown();
      }
      await telegramClient.destroy();
    }
  }, timeoutMs);
}

async function runAuthLogout(globalFlags) {
  const timeoutMs = globalFlags.timeoutMs;
  let release = null;
  let telegramClient = null;
  const cleanup = async () => {
    let cleanupError;
    if (telegramClient) {
      const currentClient = telegramClient;
      telegramClient = null;
      try { await currentClient.destroy(); } catch (error) { cleanupError = error; }
    }
    if (release) {
      const currentRelease = release;
      release = null;
      try { currentRelease(); } catch (error) { cleanupError ??= error; }
    }
    if (cleanupError) throw cleanupError;
  };
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const { missing } = getStoreConfig(storeDir);
    if (missing.length > 0) {
      if (globalFlags.json) {
        writeJson({ loggedOut: false, configured: false });
      } else {
        console.log('Not authenticated.');
      }
      return;
    }
    const config = await ensureStoreConfig(storeDir);
    release = (await claimStoreOwner(storeDir, { kind: 'transient', state: 'transient' }, timeoutMs)).release;
    try {
      ({ telegramClient } = createTelegramClient({ storeDir, config, disableUpdates: true }));
      const loginSuccess = await telegramClient.login();
      if (!loginSuccess) {
        throw new Error('Failed to login to Telegram.');
      }
      await telegramClient.client.logout();
      if (globalFlags.json) {
        writeJson({ loggedOut: true });
      } else {
        console.log('Logged out.');
      }
    } finally {
      await cleanup();
    }
  }, timeoutMs);
}

async function runAuthLogin(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  let ownerLock = null;
  let stopOwnerIpc = null;
  let telegramClient = null;
  let messageSyncService = null;
  let handedOff = false;
  const cleanup = async () => {
    const stopWatchdog = startShutdownWatchdog();
    let cleanupError;
    if (stopOwnerIpc) {
      const stop = stopOwnerIpc;
      stopOwnerIpc = null;
      try { await stop(); } catch (error) { cleanupError = error; }
    }
    if (messageSyncService) {
      const currentService = messageSyncService;
      messageSyncService = null;
      try { await currentService.shutdown(); } catch (error) { cleanupError ??= error; }
    }
    if (telegramClient) {
      const currentClient = telegramClient;
      telegramClient = null;
      try { await currentClient.destroy(); } catch (error) { cleanupError ??= error; }
    }
    if (ownerLock) {
      const currentOwner = ownerLock;
      ownerLock = null;
      try { currentOwner.release(); } catch (error) { cleanupError ??= error; }
    }
    stopWatchdog();
    if (cleanupError) throw cleanupError;
  };
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const config = await ensureStoreConfig(storeDir);
    ownerLock = await claimStoreOwner(storeDir, {
      kind: options.follow ? 'auth' : 'transient',
      state: options.follow ? 'starting' : 'transient',
    }, timeoutMs);
    try {
      ({ telegramClient } = createTelegramClient({
        storeDir,
        config,
        forceSms: options.forceSms,
        useQr: options.qr,
        disableUpdates: !options.follow,
      }));
      const loginSuccess = await telegramClient.login();
      if (!loginSuccess) {
        throw new Error('Failed to login to Telegram.');
      }
      if (globalFlags.account?.id && globalFlags.account.id !== 'default') {
        const me = await telegramClient.getCurrentUser();
        if (!me) {
          throw new Error(`Cannot bind account ${globalFlags.account.id}: Telegram identity is unavailable.`);
        }
        bindAccountIdentity(storeDir, me);
      }
      if (options.follow) {
        let archiveError = null;
        try {
          ({ messageSyncService } = createMessageSyncService(telegramClient, { storeDir }));
          await refreshDialogsWithRetry(messageSyncService);
        } catch (error) {
          archiveError = formatErrorMessage(error);
          throw new Error(`Authenticated, but archive sync could not start: ${archiveError}`);
        }
        await telegramClient.startUpdates();
        messageSyncService.startRealtimeSync();
        messageSyncService.resumePendingJobs();
        stopOwnerIpc = await startOwnerIpc({ storeDir, ownerLock,
          operations: createOwnerOperations({ storeDir, telegramClient, messageSyncService,
            onAuthLogout: () => cleanup().finally(() => process.exit(0)) }) });
        await withShutdown(async () => {
          await cleanup();
        });
        handedOff = true;
        return;
      }

      if (globalFlags.json) {
        writeJson({
          authenticated: true,
          dialogs: null,
          archiveReady: false,
          archiveError: null,
        });
      } else {
        console.log(`Authenticated. ${AUTH_SYNC_HINT}`);
      }
    } finally {
      if (!handedOff) {
        await cleanup();
      }
    }
  }, timeoutMs);
}

async function runConfigList(globalFlags) {
  const storeDir = resolveStoreDir();
  const { config } = loadConfig(storeDir);
  const normalized = normalizeConfig(config ?? {});
  const payload = {};
  for (const spec of CONFIG_SPECS) {
    let value = normalizeOutputValue(getValueAtPath(normalized, spec.path));
    if (spec.secret) {
      value = maskSecret(value);
    }
    payload[spec.key] = value;
  }
  if (globalFlags.json) {
    writeJson(payload);
    return;
  }
  for (const [key, value] of Object.entries(payload)) {
    console.log(`${key}: ${formatConfigValue(value)}`);
  }
}

async function runConfigGet(globalFlags, key) {
  const storeDir = resolveStoreDir();
  const spec = resolveConfigSpec(key);
  const { config } = loadConfig(storeDir);
  const normalized = normalizeConfig(config ?? {});
  const value = normalizeOutputValue(getValueAtPath(normalized, spec.path));
  if (globalFlags.json) {
    writeJson({ key: spec.key, value });
    return;
  }
  console.log(`${spec.key}: ${formatConfigValue(value)}`);
}

async function runConfigSet(globalFlags, key, value) {
  const storeDir = resolveStoreDir();
  const spec = resolveConfigSpec(key);
  const parsedValue = parseConfigValue(spec, value);
  const { rawConfig } = loadConfig(storeDir);
  const next = normalizeConfig(rawConfig ?? {}, { includeEnv: false });
  setValueAtPath(next, spec.path, parsedValue);
  const { config: saved } = saveConfig(storeDir, next);
  const storedValue = normalizeOutputValue(getValueAtPath(saved, spec.path));
  const restartRequired = Boolean(ownerExecution.getStore());
  if (globalFlags.json) {
    writeJson({ ok: true, key: spec.key, value: storedValue, restartRequired });
    return;
  }
  console.log(`Updated ${spec.key}: ${formatConfigValue(storedValue)}`);
  if (restartRequired) console.log('Restart the running service to apply this setting.');
}

async function runConfigUnset(globalFlags, key) {
  const storeDir = resolveStoreDir();
  const spec = resolveConfigSpec(key);
  const { rawConfig } = loadConfig(storeDir);
  if (!rawConfig) {
    if (globalFlags.json) {
      writeJson({ ok: true, key: spec.key, value: null });
    } else {
      console.log(`${spec.key} already unset.`);
    }
    return;
  }
  const next = normalizeConfig(rawConfig, { includeEnv: false });
  deleteValueAtPath(next, spec.path);
  const { config: saved } = saveConfig(storeDir, next);
  const storedValue = normalizeOutputValue(getValueAtPath(saved, spec.path));
  const restartRequired = Boolean(ownerExecution.getStore());
  if (globalFlags.json) {
    writeJson({ ok: true, key: spec.key, value: storedValue, restartRequired });
    return;
  }
  console.log(`Cleared ${spec.key}.`);
  if (restartRequired) console.log('Restart the running service to apply this setting.');
}

async function runSync(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const idleExitMs = parseDuration(options.idleExit || '30s');
    const follow = options.follow || !options.once;
    const ownershipDeadline = Date.now() + (timeoutMs ?? 30000);
    let ownerLock;
    while (!ownerLock && Date.now() < ownershipDeadline) {
      const current = parseStoreLock(readStoreLock(storeDir).info);
      if (current?.pid && isPidAlive(current.pid) && current.state === 'ready' && current.socketPath &&
          !(follow && current.kind === 'sync-once')) {
        if (follow) {
          await runOwnerOperation({ storeDir, operation: 'sync.status', timeoutMs: Math.max(1, ownershipDeadline - Date.now()) });
          if (!globalFlags.json) console.log(`Sync is already running in process ${current.pid}.`);
          else writeJson({ running: true, ownerPid: current.pid });
        } else {
          const result = await runOwnerOperation({ storeDir, operation: 'sync.once',
            args: { idleExitMs }, timeoutMs });
          if (globalFlags.json) writeJson({ ok: true, mode: 'once', queue: result.queue });
          else console.log('Sync complete.');
        }
        return;
      }
      try {
        ownerLock = acquireOwnerLock(storeDir, { kind: follow ? 'sync' : 'sync-once', state: 'starting' });
      } catch (error) {
        if (!error.message.includes('locked') && !error.message.includes('readers') &&
            !error.message.includes('recovery')) throw error;
        await delay(100);
      }
    }
    if (!ownerLock) throw new Error('Timed out waiting for the store owner');
    let services;
    let stopOwnerIpc;
    let handedOff = false;
    const cleanup = async () => {
      const stopWatchdog = startShutdownWatchdog();
      let cleanupError;
      if (stopOwnerIpc) {
        try { await stopOwnerIpc(); } catch (error) { cleanupError = error; }
      }
      if (services) {
        try { await services.messageSyncService.shutdown(); } catch (error) { cleanupError ??= error; }
        try { await services.telegramClient.destroy(); } catch (error) { cleanupError ??= error; }
      }
      try { ownerLock.release(); } catch (error) { cleanupError ??= error; }
      stopWatchdog();
      if (cleanupError) throw cleanupError;
    };
    try {
      services = createServices({ storeDir });
      const { telegramClient, messageSyncService } = services;
      if (!(await telegramClient.isAuthorized().catch((err) => { process.stderr.write(`Auth check failed: ${err.message}\n`); return false; }))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }

      await messageSyncService.refreshChannelsFromDialogs();
      messageSyncService.resumePendingJobs();

      if (follow) {
        await telegramClient.startUpdates();
        messageSyncService.startRealtimeSync();
      }
      stopOwnerIpc = await startOwnerIpc({ storeDir, ownerLock,
        operations: createOwnerOperations({ ...services,
          onAuthLogout: () => cleanup().finally(() => process.exit(0)) }) });
      if (follow) {
        if (!globalFlags.json) console.log('Sync running. Press Ctrl+C to stop.');
        await withShutdown(cleanup);
        handedOff = true;
        return;
      }

      await waitForIdle(messageSyncService, idleExitMs);
      const stats = messageSyncService.getQueueStats();
      if (globalFlags.json) {
        writeJson({ ok: true, mode: 'once', queue: stats });
      } else {
        console.log('Sync complete.');
      }
    } finally {
      if (!handedOff) await cleanup();
    }
  }, timeoutMs);
}

async function runServer(globalFlags) {
  const timeoutMs = globalFlags.timeoutMs;
  let child = null;

  const runChild = () => new Promise((resolve, reject) => {
    const serverPath = fileURLToPath(new URL('./mcp-server.js', import.meta.url));
    const handleSignal = (signal) => {
      if (child && !child.killed) {
        child.kill(signal);
      }
    };
    const cleanup = () => {
      process.off('SIGINT', handleSignal);
      process.off('SIGTERM', handleSignal);
    };

    process.on('SIGINT', handleSignal);
    process.on('SIGTERM', handleSignal);

    child = spawn(process.execPath, [serverPath], {
      stdio: 'inherit',
      env: process.env,
    });

    child.on('error', (error) => {
      cleanup();
      reject(error);
    });

    child.on('exit', (code, signal) => {
      cleanup();
      if (code === 0 || signal === 'SIGINT' || signal === 'SIGTERM') {
        resolve();
        return;
      }
      reject(new Error(`Server exited with code ${code ?? 'null'}${signal ? ` (${signal})` : ''}`));
    });
  });

  const { missing } = getStoreConfig(resolveStoreDir());
  if (missing.length > 0) {
    throw new Error('Not authenticated. Run "tgcli auth" to configure credentials.');
  }

  return runWithTimeout(runChild, timeoutMs, () => {
    if (child && !child.killed) {
      child.kill('SIGTERM');
    }
  });
}

async function runOwnerRequestStatus(globalFlags, requestId) {
  const result = await callOwner({ storeDir: resolveStoreDir(), operation: 'owner.requestStatus',
    args: { requestId }, timeoutMs: globalFlags.timeoutMs ?? 30000 });
  if (globalFlags.json) writeJson(result);
  else console.log(`${result.requestId}: ${result.status}${result.code ? ` (${result.code})` : ''}`);
}

async function runServiceInstall(globalFlags) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const identity = resolveServiceIdentity(globalFlags.account?.id);
    const { manager, brewInfo } = resolveServiceManager(identity.accountId);
    const envVars = {
      TGCLI_SERVICE_MANAGER: manager,
    };
    if (process.env.TGCLI_STORE) {
      envVars.TGCLI_STORE = process.env.TGCLI_STORE;
    }

    if (manager === 'brew') {
      const note = brewInfo?.brewCliMatch
        ? 'Brew service available. Use `tgcli service start`.'
        : 'Brew service available, but current tgcli is not from brew.';
      if (globalFlags.json) {
        writeJson({ manager, installed: true, note });
      } else {
        console.log(note);
      }
      return;
    }

    if (manager === 'unsupported') {
      throw new Error('Service install is supported only on macOS and Linux.');
    }

    if (manager === 'launchd') {
      const { plistPath, logPath, errorLogPath } = getLaunchdPaths(identity);
      fs.mkdirSync(path.dirname(plistPath), { recursive: true });
      fs.mkdirSync(path.dirname(logPath), { recursive: true });
      for (const filePath of [logPath, errorLogPath]) {
        const fd = fs.openSync(filePath, 'a', 0o600);
        try {
          fs.fchmodSync(fd, 0o600);
        } finally {
          fs.closeSync(fd);
        }
      }
      const content = buildLaunchdPlist({
        label: identity.launchdLabel,
        nodePath: process.execPath,
        cliPath: CLI_PATH,
        envVars,
        logPath,
        errorLogPath,
      });
      fs.writeFileSync(plistPath, content, 'utf8');
      if (globalFlags.json) {
        writeJson({ manager, installed: true, path: plistPath });
      } else {
        console.log(`Service installed at ${plistPath}. Run \`tgcli service start\` to launch.`);
      }
      return;
    }

    if (manager === 'systemd') {
      const servicePath = getSystemdPath(identity);
      fs.mkdirSync(path.dirname(servicePath), { recursive: true });
      const content = buildSystemdService({
        nodePath: process.execPath,
        cliPath: CLI_PATH,
        envVars,
      });
      fs.writeFileSync(servicePath, content, 'utf8');
      runCommand('systemctl', ['--user', 'daemon-reload']);
      if (globalFlags.json) {
        writeJson({ manager, installed: true, path: servicePath });
      } else {
        console.log(`Service installed at ${servicePath}. Run \`tgcli service start\` to launch.`);
      }
      return;
    }
  }, timeoutMs);
}

async function runServiceStart(globalFlags) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const identity = resolveServiceIdentity(globalFlags.account?.id);
    const { manager, brewInfo } = resolveServiceManager(identity.accountId);

    if (manager === 'brew') {
      const result = runCommand('brew', ['services', 'start', 'tgcli'], { stdio: 'inherit' });
      if (result.status !== 0) {
        throw new Error(result.stderr || 'Failed to start brew service.');
      }
      if (globalFlags.json) {
        writeJson({ manager, started: true });
      }
      if (!brewInfo?.brewCliMatch && !globalFlags.json) {
        console.log('Warning: brew-managed service may not match this tgcli binary.');
      }
      return;
    }

    if (manager === 'unsupported') {
      throw new Error('Service start is supported only on macOS and Linux.');
    }

    if (manager === 'launchd') {
      const { plistPath } = getLaunchdPaths(identity);
      if (!fs.existsSync(plistPath)) {
        throw new Error(`Service not installed. Run \`tgcli service install\` first.`);
      }
      const domain = `gui/${process.getuid()}`;
      const result = runCommand('launchctl', ['bootstrap', domain, plistPath]);
      if (result.status !== 0) {
        throw new Error(result.stderr || 'Failed to start launchd service.');
      }
      if (globalFlags.json) {
        writeJson({ manager, started: true });
      } else {
        console.log('Service started.');
      }
      return;
    }

    if (manager === 'systemd') {
      const servicePath = getSystemdPath(identity);
      if (!fs.existsSync(servicePath)) {
        throw new Error(`Service not installed. Run \`tgcli service install\` first.`);
      }
      const result = runCommand('systemctl', ['--user', 'enable', '--now', identity.systemdServiceName]);
      if (result.status !== 0) {
        throw new Error(result.stderr || 'Failed to start systemd service.');
      }
      if (globalFlags.json) {
        writeJson({ manager, started: true });
      } else {
        console.log('Service started.');
      }
    }
  }, timeoutMs);
}

async function runServiceStop(globalFlags) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const identity = resolveServiceIdentity(globalFlags.account?.id);
    const { manager } = resolveServiceManager(identity.accountId);

    if (manager === 'brew') {
      const result = runCommand('brew', ['services', 'stop', 'tgcli'], { stdio: 'inherit' });
      if (result.status !== 0) {
        throw new Error(result.stderr || 'Failed to stop brew service.');
      }
      if (globalFlags.json) {
        writeJson({ manager, stopped: true });
      }
      return;
    }

    if (manager === 'unsupported') {
      throw new Error('Service stop is supported only on macOS and Linux.');
    }

    if (manager === 'launchd') {
      const { plistPath } = getLaunchdPaths(identity);
      if (!fs.existsSync(plistPath)) {
        throw new Error(`Service not installed. Run \`tgcli service install\` first.`);
      }
      const domain = `gui/${process.getuid()}`;
      const result = runCommand('launchctl', ['bootout', domain, plistPath]);
      if (result.status !== 0 && result.stderr.trim()) {
        throw new Error(result.stderr || 'Failed to stop launchd service.');
      }
      if (globalFlags.json) {
        writeJson({ manager, stopped: true });
      } else {
        console.log('Service stopped.');
      }
      return;
    }

    if (manager === 'systemd') {
      const result = runCommand('systemctl', ['--user', 'stop', identity.systemdServiceName]);
      if (result.status !== 0) {
        throw new Error(result.stderr || 'Failed to stop systemd service.');
      }
      if (globalFlags.json) {
        writeJson({ manager, stopped: true });
      } else {
        console.log('Service stopped.');
      }
    }
  }, timeoutMs);
}

async function runServiceStatus(globalFlags) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const identity = resolveServiceIdentity(globalFlags.account?.id);
    const { manager, brewInfo } = resolveServiceManager(identity.accountId);
    const storeDir = resolveStoreDir();
    const serviceState = readServiceState(storeDir);
    const cliVersion = readVersion();

    let installed = false;
    let running = false;
    let pid = null;
    let statusLabel = null;

    if (manager === 'brew') {
      installed = Boolean(brewInfo?.installed && brewInfo.serviceAvailable);
      if (brewInfo?.serviceStatus) {
        statusLabel = brewInfo.serviceStatus;
        running = brewInfo.serviceStatus === 'started';
      }
    } else if (manager === 'launchd') {
      const { plistPath } = getLaunchdPaths(identity);
      installed = fs.existsSync(plistPath);
      const list = runCommand('launchctl', ['list']);
      if (list.status === 0) {
        const launchdStatus = parseLaunchdList(list.stdout, identity.launchdLabel);
        if (launchdStatus) {
          pid = launchdStatus.pid;
          running = launchdStatus.running;
          statusLabel = launchdStatus.status;
        }
      }
    } else if (manager === 'systemd') {
      const servicePath = getSystemdPath(identity);
      installed = fs.existsSync(servicePath);
      const active = runCommand('systemctl', ['--user', 'is-active', identity.systemdServiceName]);
      running = active.status === 0 && active.stdout.trim() === 'active';
      statusLabel = active.stdout.trim();
    } else {
      statusLabel = 'unsupported';
    }

    const serviceVersion = serviceState?.version ?? null;
    const versionMismatch = serviceVersion && cliVersion && serviceVersion !== cliVersion;
    const resolvedPid = running ? (pid ?? serviceState?.pid ?? null) : null;
    const output = {
      manager,
      installed,
      running,
      status: statusLabel,
      pid: resolvedPid,
      serviceVersion,
      cliVersion,
      storeDir,
      mcpEnabled: serviceState?.mcpEnabled ?? null,
    };

    if (globalFlags.json) {
      writeJson({
        ...output,
        versionMismatch,
        brewCliMatch: brewInfo?.brewCliMatch ?? null,
      });
      return;
    }

    console.log(`Manager: ${manager}`);
    console.log(`Installed: ${installed ? 'yes' : 'no'}`);
    console.log(`Running: ${running ? 'yes' : 'no'}`);
    if (statusLabel) {
      console.log(`Status: ${statusLabel}`);
    }
    if (output.pid) {
      console.log(`PID: ${output.pid}`);
    }
    if (serviceVersion) {
      console.log(`Service version: ${serviceVersion}`);
    }
    console.log(`CLI version: ${cliVersion}`);
    console.log(`Store: ${storeDir}`);
    if (serviceState && serviceState.mcpEnabled !== null && serviceState.mcpEnabled !== undefined) {
      console.log(`MCP enabled: ${serviceState.mcpEnabled ? 'yes' : 'no'}`);
    }
    if (versionMismatch) {
      console.log('Warning: service version differs from CLI. Run `tgcli doctor`.');
    }
    if (manager === 'brew' && brewInfo && brewInfo.brewCliMatch === false) {
      console.log('Warning: brew-managed service may not match this tgcli binary.');
    }
  }, timeoutMs);
}

async function runServiceLogs(globalFlags) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const identity = resolveServiceIdentity(globalFlags.account?.id);
    const { manager } = resolveServiceManager(identity.accountId);

    if (manager === 'brew') {
      const info = runCommand('brew', ['services', 'info', 'tgcli']);
      if (info.status !== 0) {
        throw new Error(info.stderr || 'Failed to read brew service info.');
      }
      const match = info.stdout.match(/Log:\s+(.+)/i);
      const logPath = match ? match[1].trim() : null;
      if (globalFlags.json) {
        writeJson({ manager, logPath });
        return;
      }
      if (logPath && fs.existsSync(logPath)) {
        runCommand('tail', ['-n', '200', logPath], { stdio: 'inherit' });
      } else {
        process.stdout.write(info.stdout);
      }
      return;
    }

    if (manager === 'launchd') {
      const { logPath, errorLogPath } = getLaunchdPaths(identity);
      if (globalFlags.json) {
        writeJson({ manager, logPath, errorLogPath });
        return;
      }
      if (fs.existsSync(logPath)) {
        runCommand('tail', ['-n', '200', logPath], { stdio: 'inherit' });
      } else if (fs.existsSync(errorLogPath)) {
        runCommand('tail', ['-n', '200', errorLogPath], { stdio: 'inherit' });
      } else {
        console.log('No log file found.');
      }
      return;
    }

    if (manager === 'systemd') {
      if (globalFlags.json) {
        writeJson({ manager, journal: true });
        return;
      }
      runCommand('journalctl', ['--user', '-u', identity.systemdServiceName, '-n', '200', '--no-pager'], {
        stdio: 'inherit',
      });
      return;
    }

    throw new Error('Service logs are supported only on macOS and Linux.');
  }, timeoutMs);
}

async function runSyncStatus(globalFlags) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const owner = readStoreLock(storeDir);
    const ownerInfo = parseStoreLock(owner.info);
    const ownerAlive = ownerInfo?.pid && isPidAlive(ownerInfo.pid);
    let queue;
    let dialogRefreshDeferred = ownerAlive ? null : false;
    if (ownerAlive && ownerInfo.state === 'ready') {
      try {
        const result = await runOwnerOperation({ storeDir, operation: 'sync.status',
          timeoutMs: timeoutMs ?? 30000 });
        queue = result.queue;
        dialogRefreshDeferred = result.dialogRefreshDeferred ?? null;
      } catch (error) {
        if (!['OWNER_UNAVAILABLE', 'OWNER_STARTING', 'UNKNOWN_RESULT', 'ECONNREFUSED', 'ENOENT'].includes(error.code)) throw error;
      }
    }
    if (!queue) {
      let reader;
      try {
        reader = new ArchiveReader(storeDir);
        queue = reader.getQueueStats();
      } catch (error) {
        if (error.name !== 'ArchiveUnavailableError' || error.cause?.code !== 'SQLITE_CANTOPEN') throw error;
        queue = { pending: 0, in_progress: 0, idle: 0, error: 0, processing: false };
      } finally {
        reader?.close();
      }
      if (ownerAlive) queue.processing = null;
    }
    if (globalFlags.json) {
      writeJson({ queue, dialogRefreshDeferred });
    } else {
      console.log(`QUEUE: pending=${queue.pending} in_progress=${queue.in_progress} idle=${queue.idle} error=${queue.error}`);
      console.log(`PROCESSING: ${queue.processing ?? 'unknown'}`);
      if (dialogRefreshDeferred !== false) {
        console.log(`DIALOG REFRESH: ${dialogRefreshDeferred ? 'deferred by Telegram rate limit' : 'unknown'}`);
      }
    }
  }, timeoutMs);
}

async function runSyncJobsList(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const status = options.status ? String(options.status) : null;
    if (status && !['pending', 'in_progress', 'idle', 'error'].includes(status)) {
      throw new Error(`Unknown status: ${status}`);
    }
    const limit = parsePositiveInt(options.limit, '--limit') ?? 100;
    const reader = new ArchiveReader(storeDir);
    try {
      const jobs = reader.listJobs({
        status,
        channelId: options.channel ?? null,
        limit,
      });
      if (globalFlags.json) {
        writeJson(jobs);
      } else {
        for (const job of jobs) {
          const label = job.peer_title || job.channel_id;
          console.log(`#${job.id} ${label} [${job.status}] ${job.message_count}/${job.target_message_count}`);
        }
      }
    } finally {
      reader.close();
    }
  }, timeoutMs);
}

async function runSyncJobsAdd(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const storeDir = resolveStoreDir();
    const depth = parsePositiveInt(options.depth, '--depth');
    const job = await runOwnerOperation({ storeDir, operation: 'sync.jobs.add',
      args: { chat: options.chat, depth, minDate: options.minDate ?? null }, timeoutMs: timeoutMs ?? 30000 });
    if (globalFlags.json) writeJson(job);
    else console.log(`Job scheduled for ${job.channel_id} (#${job.id}).`);
  }, timeoutMs);
}

async function runSyncJobsRetry(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const jobId = parsePositiveInt(options.jobId, '--job-id');
    const channelId = options.channel ?? null;
    const allErrors = Boolean(options.allErrors);
    if (!jobId && !channelId && !allErrors) {
      throw new Error('--job-id, --channel, or --all-errors is required');
    }
    if (allErrors && (jobId || channelId)) {
      throw new Error('Use --all-errors without --job-id/--channel');
    }
    const storeDir = resolveStoreDir();
    const result = await runOwnerOperation({ storeDir, operation: 'sync.jobs.retry',
      args: { jobId, channelId, allErrors }, timeoutMs: timeoutMs ?? 30000 });
    if (globalFlags.json) writeJson(result);
    else console.log(`Re-queued ${result.updated} job(s).`);
  }, timeoutMs);
}

async function runSyncJobsCancel(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const jobId = parsePositiveInt(options.jobId, '--job-id');
    const channelId = options.channel ?? null;
    if (!jobId && !channelId) {
      throw new Error('--job-id or --channel is required');
    }
    if (jobId && channelId) {
      throw new Error('Use --job-id or --channel, not both');
    }
    const storeDir = resolveStoreDir();
    const result = await runOwnerOperation({ storeDir, operation: 'sync.jobs.cancel',
      args: { jobId, channelId }, timeoutMs: timeoutMs ?? 30000 });
    if (globalFlags.json) writeJson(result);
    else console.log(`Canceled ${result.canceled} job(s).`);
  }, timeoutMs);
}

async function runDoctor(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const lock = readStoreLock(storeDir);
    const owner = parseStoreLock(lock.info);
    const ownerAlive = owner?.pid && isPidAlive(owner.pid);
    let details;
    if (options.connect || ownerAlive && owner.state === 'ready' && owner.socketPath) {
      try {
        details = await runOwnerOperation({ storeDir, operation: 'doctor.status',
          args: { connect: Boolean(options.connect) }, timeoutMs: timeoutMs ?? 30000 });
      } catch (error) {
        if (options.connect || !['OWNER_UNAVAILABLE', 'OWNER_STARTING', 'UNKNOWN_RESULT'].includes(error.code)) throw error;
      }
    }
    if (!details) {
      let reader;
      let search = { enabled: null, version: null };
      let queue = { pending: 0, in_progress: 0, idle: 0, error: 0, processing: ownerAlive ? null : false };
      try {
        reader = new ArchiveReader(storeDir);
        search = reader.getSearchStatus();
        queue = reader.getQueueStats();
        if (ownerAlive) queue.processing = null;
      } catch (error) {
        if (error.name !== 'ArchiveUnavailableError' || error.cause?.code !== 'SQLITE_CANTOPEN') throw error;
      } finally {
        reader?.close();
      }
      details = { authenticated: null, connected: null, search, queue };
    }

    const payload = {
      storeDir,
      lockHeld: lock.exists,
      lockInfo: lock.info,
      authenticated: details.authenticated,
      connected: details.connected,
      ftsEnabled: details.search.enabled,
      ftsVersion: details.search.version,
      queue: details.queue,
    };

    if (globalFlags.json) {
      writeJson(payload);
      return;
    }

    console.log(`STORE: ${payload.storeDir}`);
    console.log(`LOCKED: ${payload.lockHeld}${payload.lockInfo ? ` (${payload.lockInfo})` : ''}`);
    console.log(`AUTHENTICATED: ${payload.authenticated ?? 'unknown'}`);
    console.log(`CONNECTED: ${payload.connected ?? 'unknown'}`);
    console.log(`FTS: ${payload.ftsEnabled}${payload.ftsVersion ? ` (v${payload.ftsVersion})` : ''}`);
    console.log(`QUEUE: pending=${payload.queue.pending} in_progress=${payload.queue.in_progress} idle=${payload.queue.idle} error=${payload.queue.error}`);
  }, timeoutMs);
}

async function runChannelsList(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const limit = parsePositiveInt(options.limit, '--limit') ?? 50;
    const dialogs = await runOwnerOperation({ storeDir, operation: 'channels.list',
      args: { query: options.query ?? null, limit }, timeoutMs: timeoutMs ?? 30000 });
    if (globalFlags.json) {
      writeJson(dialogs);
    } else {
      for (const dialog of dialogs) {
        const label = dialog.title || dialog.username || dialog.id;
        console.log(`${label} (${dialog.id})`);
      }
    }
  }, timeoutMs);
}

async function runChannelsShow(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      let channel = messageSyncService.getChannel(options.chat);
      if (!channel) {
        if (!(await telegramClient.isAuthorized().catch(() => false))) {
          throw new Error('Not authenticated. Run `node cli.js auth` first.');
        }
        const meta = await telegramClient.getPeerMetadata(options.chat);
        channel = {
          channelId: String(options.chat),
          peerTitle: meta?.peerTitle ?? null,
          peerType: meta?.peerType ?? null,
          chatType: meta?.chatType ?? null,
          isForum: meta?.isForum ?? null,
          username: meta?.username ?? null,
          syncEnabled: null,
          lastMessageId: null,
          lastMessageDate: null,
          oldestMessageId: null,
          oldestMessageDate: null,
          about: meta?.about ?? null,
          metadataUpdatedAt: null,
          createdAt: null,
          updatedAt: null,
          source: 'live',
        };
      }

      if (globalFlags.json) {
        writeJson(channel);
      } else {
        console.log(JSON.stringify(channel, null, 2));
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runChannelsSync(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    if (options.enable && options.disable) {
      throw new Error('Use either --enable or --disable');
    }
    if (!options.enable && !options.disable) {
      throw new Error('--enable or --disable is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      const result = messageSyncService.setChannelSync(options.chat, Boolean(options.enable));
      let job = null;
      let jobQueued = false;
      if (options.enable) {
        const existing = messageSyncService.listJobs({ channelId: options.chat, limit: 1 });
        if (existing.length > 0) {
          job = existing[0];
        } else {
          job = messageSyncService.addJob(options.chat);
          jobQueued = true;
        }
      }
      if (globalFlags.json) {
        writeJson({
          channelId: result.channel_id,
          syncEnabled: Boolean(result.sync_enabled),
          jobId: job?.id ?? null,
          jobStatus: job?.status ?? null,
          jobQueued,
        });
      } else {
        if (result.sync_enabled) {
          const jobMessage = job
            ? jobQueued
              ? ` Backfill job queued (#${job.id}).`
              : ` Backfill job exists (#${job.id}, ${job.status}).`
            : '';
          console.log(
            `Sync enabled for ${result.channel_id}.${jobMessage} ` +
              'Run `tgcli sync --once` (or `tgcli sync --follow`/`tgcli server`) to process.',
          );
        } else {
          console.log(`Sync disabled for ${result.channel_id}`);
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

function createLiveMetadataResolver(messageSyncService, telegramClient) {
  return async (channelId, fallback = {}) => {
    const meta = messageSyncService.getChannelMetadata(channelId);
    let peerTitle = meta?.peerTitle ?? fallback.peerTitle ?? null;
    let username = meta?.username ?? fallback.username ?? null;
    if (!peerTitle || !username) {
      const live = await telegramClient.getPeerMetadata(channelId);
      peerTitle = peerTitle ?? live?.peerTitle ?? null;
      username = username ?? live?.username ?? null;
    }
    return { peerTitle, username };
  };
}

async function runMessagesList(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const resolvedSource = resolveSource(options.source);
    const { telegramClient, messageSyncService, close } = openMessageCommandServices(storeDir, resolvedSource);
    const resolveLiveMetadata = createLiveMetadataResolver(messageSyncService, telegramClient);
    try {
      const channelIds = parseListValues(options.chat);
      const topicId = parsePositiveInt(options.topic, '--topic');
      const finalLimit = parsePositiveInt(options.limit, '--limit') ?? 50;
      let archivedResults = [];
      let liveResults = [];
      let authChecked = false;

      const ensureAuthorized = async () => {
        if (authChecked) {
          return;
        }
        if (!(await telegramClient.isAuthorized().catch(() => false))) {
          throw new Error('Not authenticated. Run `node cli.js auth` first.');
        }
        authChecked = true;
      };

      const fetchLiveMessages = async (liveChannelIds) => {
        await ensureAuthorized();
        const results = [];
        for (const id of liveChannelIds) {
          let peerTitle = null;
          let username = null;
          let liveMessages = [];

          if (topicId) {
            const response = await telegramClient.getTopicMessages(id, topicId, finalLimit);
            liveMessages = response.messages;
          } else {
            const response = await telegramClient.getMessagesByChannelId(id, finalLimit);
            liveMessages = response.messages;
            peerTitle = response.peerTitle ?? null;
          }

          const meta = await resolveLiveMetadata(id, { peerTitle, username });
          peerTitle = meta.peerTitle;
          username = meta.username;

          const filtered = filterLiveMessagesByDate(liveMessages, options.after, options.before);
          const formatted = filtered.map((message) => ({
            ...formatLiveMessage(message, { channelId: String(id), peerTitle, username }),
            source: 'live',
          }));
          results.push(...formatted);
        }
        return results;
      };

      if (resolvedSource === 'archive' || resolvedSource === 'both') {
        const archived = messageSyncService.listArchivedMessages({
          channelIds: channelIds.length ? channelIds : null,
          topicId,
          fromDate: options.after,
          toDate: options.before,
          limit: finalLimit,
        });
        archivedResults = archived.map((message) => ({ ...message, source: 'archive' }));
      }

      if (resolvedSource === 'live' || resolvedSource === 'both') {
        if (!channelIds.length) {
          throw new Error('--chat is required for live source.');
        }
        liveResults = await fetchLiveMessages(channelIds);
      }

      let messages = [];
      let outputSource = resolvedSource;
      if (resolvedSource === 'both') {
        messages = mergeMessageSets([archivedResults, liveResults], finalLimit);
      } else if (resolvedSource === 'live') {
        messages = liveResults;
        outputSource = 'live';
      } else {
        messages = archivedResults;
      }

      if (globalFlags.json) {
        writeJson({ source: outputSource, returned: messages.length, messages });
      } else {
        const groups = groupMessagesByChannel(messages);
        for (const group of groups) {
          const label = formatPeerHeaderLabel(group);
          const count = group.messages.length;
          console.log(`Showing ${count} message${count === 1 ? '' : 's'} for ${label}:`);
          for (const message of group.messages) {
            const sender = getMessageSenderLabel(message) || 'unknown';
            const text = (message.text || '').replace(/\s+/g, ' ').trim();
            const prefix = outputSource === 'both' ? `[${message.source}] ` : '';
            console.log(`${prefix}${message.date ?? ''} ${sender} #${message.messageId}: ${text}`);
          }
          if (groups.length > 1) {
            console.log('');
          }
        }
      }
    } finally {
      await close();
    }
  }, timeoutMs);
}

async function runMessagesSearch(globalFlags, queryParts, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const resolvedSource = resolveSource(options.source);
    const { telegramClient, messageSyncService, close } = openMessageCommandServices(storeDir, resolvedSource);
    const resolveLiveMetadata = createLiveMetadataResolver(messageSyncService, telegramClient);
    try {
      const query = options.query || (queryParts || []).join(' ').trim();
      const channelIds = parseListValues(options.chat);
      const tagList = [
        ...parseListValues(options.tag),
        ...parseListValues(options.tags),
      ];
      const topicId = parsePositiveInt(options.topic, '--topic');
      const finalLimit = parsePositiveInt(options.limit, '--limit') ?? 100;
      const caseInsensitive = !options.caseSensitive;

      if (!query && !options.regex && tagList.length === 0) {
        throw new Error('Provide query, regex, or tag for messages search.');
      }

      let archivedResults = [];
      let liveResults = [];
      let authChecked = false;

      const ensureAuthorized = async () => {
        if (authChecked) {
          return;
        }
        if (!(await telegramClient.isAuthorized().catch(() => false))) {
          throw new Error('Not authenticated. Run `node cli.js auth` first.');
        }
        authChecked = true;
      };

      const buildLiveChannelIds = () => {
        let liveChannelIds = channelIds;
        if (!liveChannelIds.length && tagList.length) {
          const tagged = new Map();
          for (const tag of tagList) {
            const channels = messageSyncService.listTaggedChannels(tag, { limit: 200 });
            for (const channel of channels) {
              tagged.set(channel.channelId, channel);
            }
          }
          liveChannelIds = Array.from(tagged.keys());
        }
        return liveChannelIds;
      };

      const fetchLiveResults = async (liveChannelIds) => {
        await ensureAuthorized();
        let liveRegex = null;
        if (options.regex) {
          try {
            liveRegex = new RegExp(options.regex, caseInsensitive ? 'i' : '');
          } catch (error) {
            throw new Error(`Invalid regex: ${error.message}`);
          }
        }

        const results = [];
        for (const id of liveChannelIds) {
          let peerTitle = null;
          let username = null;
          let liveMessages = [];

          if (query) {
            const response = await telegramClient.searchChannelMessages(id, {
              query,
              limit: finalLimit,
              topicId,
            });
            liveMessages = response.messages;
            peerTitle = response.peerTitle ?? null;
          } else if (topicId) {
            const response = await telegramClient.getTopicMessages(id, topicId, finalLimit);
            liveMessages = response.messages;
          } else {
            const response = await telegramClient.getMessagesByChannelId(id, finalLimit);
            liveMessages = response.messages;
            peerTitle = response.peerTitle ?? null;
          }

          const meta = await resolveLiveMetadata(id, { peerTitle, username });
          peerTitle = meta.peerTitle;
          username = meta.username;

          let filtered = filterLiveMessagesByDate(liveMessages, options.after, options.before);
          if (liveRegex) {
            filtered = filtered.filter((message) =>
              liveRegex.test(message.text ?? message.message ?? ''),
            );
          }

          const formatted = filtered.map((message) => ({
            ...formatLiveMessage(message, { channelId: String(id), peerTitle, username }),
            source: 'live',
          }));
          results.push(...formatted);
        }
        return results;
      };

      if (resolvedSource === 'archive' || resolvedSource === 'both') {
        const archived = messageSyncService.searchArchiveMessages({
          query,
          regex: options.regex,
          tags: tagList.length ? tagList : null,
          channelIds: channelIds.length ? channelIds : null,
          topicId,
          fromDate: options.after,
          toDate: options.before,
          limit: finalLimit,
          caseInsensitive,
        });
        archivedResults = archived.map((message) => ({ ...message, source: 'archive' }));
      }

      if (resolvedSource === 'live' || resolvedSource === 'both') {
        const liveChannelIds = buildLiveChannelIds();
        if (!liveChannelIds.length) {
          throw new Error('--chat is required for live search.');
        }
        liveResults = await fetchLiveResults(liveChannelIds);
      }

      let messages = [];
      let outputSource = resolvedSource;
      if (resolvedSource === 'both') {
        messages = mergeMessageSets([archivedResults, liveResults], finalLimit);
      } else if (resolvedSource === 'live') {
        messages = liveResults;
        outputSource = 'live';
      } else {
        messages = archivedResults;
      }

      if (globalFlags.json) {
        writeJson({ source: outputSource, returned: messages.length, messages });
      } else {
        const groups = groupMessagesByChannel(messages);
        for (const group of groups) {
          const label = formatPeerHeaderLabel(group);
          const count = group.messages.length;
          console.log(`Showing ${count} message${count === 1 ? '' : 's'} for ${label}:`);
          for (const message of group.messages) {
            const sender = getMessageSenderLabel(message) || 'unknown';
            const text = (message.text || '').replace(/\s+/g, ' ').trim();
            const prefix = outputSource === 'both' ? `[${message.source}] ` : '';
            console.log(`${prefix}${message.date ?? ''} ${sender} #${message.messageId}: ${text}`);
          }
          if (groups.length > 1) {
            console.log('');
          }
        }
      }
    } finally {
      await close();
    }
  }, timeoutMs);
}

async function runMessagesShow(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    if (!options.id) {
      throw new Error('--id is required');
    }
    const storeDir = resolveStoreDir();
    const resolvedSource = resolveSource(options.source);
    const { telegramClient, messageSyncService, close } = openMessageCommandServices(storeDir, resolvedSource);
    const resolveLiveMetadata = createLiveMetadataResolver(messageSyncService, telegramClient);
    try {
      const messageId = parsePositiveInt(options.id, '--id');
      let message = null;
      let resolvedFrom = null;

      if (resolvedSource === 'live' || resolvedSource === 'both') {
        if (!(await telegramClient.isAuthorized().catch(() => false))) {
          throw new Error('Not authenticated. Run `node cli.js auth` first.');
        }
        const live = await telegramClient.getMessageById(options.chat, messageId);
        if (live) {
          const meta = await resolveLiveMetadata(options.chat);
          message = {
            ...formatLiveMessage(live, { channelId: String(options.chat), ...meta }),
            source: 'live',
          };
          resolvedFrom = 'live';
        }
      }

      if (!message && (resolvedSource === 'archive' || resolvedSource === 'both')) {
        const archived = messageSyncService.getArchivedMessage({
          channelId: options.chat,
          messageId,
        });
        if (archived) {
          message = { ...archived, source: 'archive' };
          resolvedFrom = 'archive';
        }
      }

      if (!message) {
        throw new Error('Message not found.');
      }

      const payload = { source: resolvedFrom ?? resolvedSource, message };
      if (globalFlags.json) {
        writeJson(payload);
      } else {
        console.log(JSON.stringify(payload, null, 2));
      }
    } finally {
      await close();
    }
  }, timeoutMs);
}

async function runMessagesEditCaption(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const messageId = parsePositiveInt(options.id, '--id');
    const parseMode = parseSendParseMode(options.parseMode);
    const caption = fs.readFileSync(options.captionFile, 'utf8');
    const expectedText = fs.readFileSync(options.expectedTextFile, 'utf8');
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const result = await telegramClient.editPhotoCaption(options.chat, messageId, caption, {
        parseMode,
        expectedText,
      });
      if (globalFlags.json) {
        writeJson({ ok: true, chat_id: options.chat, message_id: result.messageId,
          media_type: result.media?.type, urls: result.urls });
      } else {
        console.log(`Photo caption edited (${result.messageId}).`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runMessagesContext(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    if (!options.id) {
      throw new Error('--id is required');
    }
    const storeDir = resolveStoreDir();
    const resolvedSource = resolveSource(options.source);
    const { telegramClient, messageSyncService, close } = openMessageCommandServices(storeDir, resolvedSource);
    const resolveLiveMetadata = createLiveMetadataResolver(messageSyncService, telegramClient);
    try {
      const messageId = parsePositiveInt(options.id, '--id');
      const safeBefore = parseNonNegativeInt(options.before, '--before') ?? 20;
      const safeAfter = parseNonNegativeInt(options.after, '--after') ?? 20;
      let context = null;
      let resolvedFrom = null;

      if (resolvedSource === 'live' || resolvedSource === 'both') {
        if (!(await telegramClient.isAuthorized().catch(() => false))) {
          throw new Error('Not authenticated. Run `node cli.js auth` first.');
        }
        const liveContext = await telegramClient.getMessageContext(options.chat, messageId, {
          before: safeBefore,
          after: safeAfter,
        });
        if (liveContext.target) {
          const meta = await resolveLiveMetadata(options.chat);
          context = {
            target: {
              ...formatLiveMessage(liveContext.target, { channelId: String(options.chat), ...meta }),
              source: 'live',
            },
            before: liveContext.before.map((message) => ({
              ...formatLiveMessage(message, { channelId: String(options.chat), ...meta }),
              source: 'live',
            })),
            after: liveContext.after.map((message) => ({
              ...formatLiveMessage(message, { channelId: String(options.chat), ...meta }),
              source: 'live',
            })),
          };
          resolvedFrom = 'live';
        }
      }

      if (!context && (resolvedSource === 'archive' || resolvedSource === 'both')) {
        const archiveContext = messageSyncService.getArchivedMessageContext({
          channelId: options.chat,
          messageId,
          before: safeBefore,
          after: safeAfter,
        });
        if (archiveContext.target) {
          context = {
            target: { ...archiveContext.target, source: 'archive' },
            before: archiveContext.before.map((message) => ({ ...message, source: 'archive' })),
            after: archiveContext.after.map((message) => ({ ...message, source: 'archive' })),
          };
          resolvedFrom = 'archive';
        }
      }

      if (!context) {
        throw new Error('Message not found.');
      }

      const payload = { source: resolvedFrom ?? resolvedSource, ...context };
      if (globalFlags.json) {
        writeJson(payload);
      } else {
        console.log(JSON.stringify(payload, null, 2));
      }
    } finally {
      await close();
    }
  }, timeoutMs);
}

async function runMessageButtonsList(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const messageId = parsePositiveInt(options.id, '--id');
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const message = await telegramClient.getMessageById(options.chat, messageId);
      if (!message) {
        throw new Error('Message not found.');
      }
      const payload = {
        channelId: String(options.chat),
        messageId,
        buttons: message.inline_buttons ?? [],
      };
      if (globalFlags.json) {
        writeJson(payload);
      } else if (payload.buttons.length === 0) {
        console.log('No inline buttons found.');
      } else {
        for (const button of payload.buttons) {
          console.log(`[${button.row},${button.column}] ${button.text} (${button.type})`);
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runMessageButtonClick(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const messageId = parsePositiveInt(options.id, '--id');
    const row = parsePositiveInt(options.row, '--row');
    const column = parsePositiveInt(options.column, '--column');
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const result = await telegramClient.clickInlineButton(options.chat, messageId, {
        row,
        column,
      });
      const payload = { channelId: String(options.chat), ...result };
      if (globalFlags.json) {
        writeJson(payload);
      } else {
        console.log(`Clicked [${row},${column}] ${result.button.text}.`);
        if (result.answer.message) {
          console.log(result.answer.message);
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runSendText(globalFlags, options = {}) {
  resolveSendAliases(options);
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.to) {
      throw new Error('--to is required');
    }
    if (!options.message) {
      throw new Error('--message is required');
    }
    const parseMode = validateSendParseMode('send text', options);
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const topicId = parsePositiveInt(options.topic, '--topic');
      const replyToMessageId = parsePositiveInt(options.replyTo, '--reply-to');
      const scheduleDate = parseScheduleDate(options.schedule);
      const retries = Math.max(0, parseInt(options.retries, 10) || 0);
      const { result, retryLog, attempts } = await withSendRetry(
        () => telegramClient.sendTextMessage(options.to, options.message, {
          topicId,
          replyToMessageId,
          parseMode,
          noPreview: options.noPreview,
          silent: options.silent || false,
          noforwards: options.forwards === false,
          scheduleDate,
        }),
        { retries, json: globalFlags.json }
      );
      const payload = { channelId: options.to, ...result };
      if (retryLog.length > 0) {
        payload.attempts = attempts;
        payload.retry_log = retryLog;
      }

      if (globalFlags.json) {
        writeJson(payload);
      } else {
        console.log(`Message sent (${result.messageId}).`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runSendPhoto(globalFlags, options = {}) {
  resolveSendAliases(options);
  const timeoutMs = globalFlags.timeoutMs;
  const method = 'sendPhoto';
  let retries = DEFAULT_SEND_PHOTO_RETRIES;

  try {
    return await runWithTimeout(async () => {
      if (!options.to) {
        throw new Error('--to is required');
      }
      if (!options.photo) {
        throw new Error('--photo is required');
      }

      const parseMode = parseSendParseMode(options.parseMode);
      if (parseMode && !(typeof options.caption === 'string' && options.caption.trim())) {
        throw new Error('--parse-mode requires --caption for send photo');
      }

      retries = parseNonNegativeInt(options.retries, '--retries') ?? DEFAULT_SEND_PHOTO_RETRIES;
      const retryBackoff = parseRetryBackoff(options.retryBackoff);
      const storeDir = resolveStoreDir();
      const release = acquireStoreLock(storeDir);
      const { telegramClient, messageSyncService } = createServices({ storeDir });
      try {
        if (!(await telegramClient.isAuthorized().catch((err) => { process.stderr.write(`Auth check failed: ${err.message}\n`); return false; }))) {
          throw new Error('Not authenticated. Run `node cli.js auth` first.');
        }
        const topicId = parsePositiveInt(options.topic, '--topic');
        const replyToMessageId = parsePositiveInt(options.replyTo, '--reply-to');
        const scheduleDate = parseScheduleDate(options.schedule);
        const sendOptions = {
          caption: options.caption,
          topicId,
          replyToMessageId,
          parseMode,
          silent: options.silent || false,
          noforwards: options.forwards === false,
          captionAbove: options.captionAbove || false,
          spoiler: options.spoiler || false,
          scheduleDate,
        };
        const prepared = await telegramClient.preparePhotoMessage(options.to, options.photo, sendOptions);
        const { result, attempts } = await executeSendWithRetries(
          () => telegramClient.sendPreparedPhotoMessage(prepared),
          {
            method,
            retries,
            retryBackoff,
            timeoutMs,
            sleep: (ms) => delay(ms, undefined, { signal: getTelegramRequestSignal() }),
            onRetry: (details) => logSendRetry(details, globalFlags),
          },
        );

        if (globalFlags.json) {
          writeJson(buildSendPhotoSuccessPayload({ method, inputChatId: options.to, result, attempts }));
        } else {
          console.log(`Photo sent (${result.messageId}).`);
        }
      } finally {
        await messageSyncService.shutdown();
        await telegramClient.destroy();
        release();
      }
    }, timeoutMs);
  } catch (error) {
    throw normalizeSendCommandError(error, { method, retries });
  }
}

function buildSendPhotoSuccessPayload({ method, inputChatId, result, attempts }) {
  return buildSendSuccessPayload({
    method,
    chatId: result?.chatId ?? inputChatId,
    messageId: result?.messageId,
    media: result?.media ?? { type: 'photo' },
    attempts,
    warning: result?.warning,
  });
}

async function runSendFile(globalFlags, options = {}) {
  resolveSendAliases(options);
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.to) {
      throw new Error('--to is required');
    }
    if (!options.file) {
      throw new Error('--file is required');
    }
    const parseMode = validateSendParseMode('send file', options);
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const topicId = parsePositiveInt(options.topic, '--topic');
      const replyToMessageId = parsePositiveInt(options.replyTo, '--reply-to');
      const scheduleDate = parseScheduleDate(options.schedule);
      const retries = Math.max(0, parseInt(options.retries, 10) || 0);
      const { result, retryLog, attempts } = await withSendRetry(
        () => telegramClient.sendFileMessage(options.to, options.file, {
          caption: options.caption,
          filename: options.filename,
          topicId,
          replyToMessageId,
          parseMode,
          silent: options.silent || false,
          noforwards: options.forwards === false,
          captionAbove: options.captionAbove || false,
          spoiler: options.spoiler || false,
          scheduleDate,
          forceDocument: options.forceDocument || false,
        }),
        { retries, json: globalFlags.json }
      );
      const payload = { channelId: options.to, ...result };
      if (retryLog.length > 0) {
        payload.attempts = attempts;
        payload.retry_log = retryLog;
      }

      if (globalFlags.json) {
        writeJson(payload);
      } else {
        console.log(`File sent (${result.messageId}).`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runMediaDownload(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    if (!options.id) {
      throw new Error('--id is required');
    }
    const messageId = parsePositiveInt(options.id, '--id');

    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const result = await telegramClient.downloadMessageMedia(options.chat, messageId, {
        outputPath: options.output,
      });

      if (globalFlags.json) {
        writeJson(result);
      } else {
        console.log(`Downloaded to ${result.path} (${result.bytes} bytes).`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runWebappServe(globalFlags, options = {}) {
  const bot = String(options.bot ?? '').trim();
  if (!/^@[A-Za-z0-9_]{5,32}$/.test(bot)) {
    throw new Error('--bot must be a Telegram bot username starting with @.');
  }
  const { url } = await runOwnerOperation({
    storeDir: resolveStoreDir(),
    operation: 'webapp.main',
    args: { bot },
    timeoutMs: globalFlags.timeoutMs ?? 30000,
  });
  const handoff = await startWebAppHandoff(url);
  if (globalFlags.json) {
    writeJson({ url: handoff.url, expiresInSeconds: 90, bot });
  } else {
    console.log(`Open ${handoff.url} in an isolated browser within 90 seconds.`);
    console.log('The signed Telegram URL is passed to the browser once and is not printed.');
  }
  await handoff.wait();
}

async function runTopicsList(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const limit = parsePositiveInt(options.limit, '--limit') ?? 100;
      const topics = await telegramClient.listForumTopics(options.chat, { limit });
      messageSyncService.upsertTopics(options.chat, topics);

      if (globalFlags.json) {
        writeJson({ total: topics.total ?? topics.length, topics });
      } else {
        for (const topic of topics) {
          console.log(`#${topic.id} ${topic.title ?? ''}`.trim());
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runTopicsSearch(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    if (!options.query) {
      throw new Error('--query is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const limit = parsePositiveInt(options.limit, '--limit') ?? 100;
      const topics = await telegramClient.listForumTopics(options.chat, {
        query: options.query,
        limit,
      });
      messageSyncService.upsertTopics(options.chat, topics);

      if (globalFlags.json) {
        writeJson({ total: topics.total ?? topics.length, topics });
      } else {
        for (const topic of topics) {
          console.log(`#${topic.id} ${topic.title ?? ''}`.trim());
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runTagsSet(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const hasTagFlag = options.tags !== undefined || options.tag !== undefined;
    const tagValues = [
      ...parseListValues(options.tags),
      ...parseListValues(options.tag),
    ];
    if (!hasTagFlag) {
      throw new Error('--tags or --tag is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      const finalTags = messageSyncService.setChannelTags(options.chat, tagValues, {
        source: options.source,
      });
      if (globalFlags.json) {
        writeJson({ channelId: options.chat, tags: finalTags });
      } else {
        console.log(`Tags set for ${options.chat}: ${finalTags.join(', ')}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runTagsList(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const storeDir = resolveStoreDir();
    const reader = new ArchiveReader(storeDir);
    try {
      const tags = reader.listChannelTags(options.chat, { source: options.source });
      if (globalFlags.json) {
        writeJson(tags);
      } else {
        console.log(tags.map((tag) => tag.tag).join(', '));
      }
    } finally {
      reader.close();
    }
  }, timeoutMs);
}

async function runTagsSearch(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.tag) {
      throw new Error('--tag is required');
    }
    const storeDir = resolveStoreDir();
    const reader = new ArchiveReader(storeDir);
    try {
      const limit = parsePositiveInt(options.limit, '--limit') ?? 100;
      const channels = reader.listTaggedChannels(options.tag, {
        source: options.source,
        limit,
      });
      if (globalFlags.json) {
        writeJson(channels);
      } else {
        for (const channel of channels) {
          const label = channel.peerTitle || channel.username || channel.channelId;
          console.log(`${label} (${channel.channelId})`);
        }
      }
    } finally {
      reader.close();
    }
  }, timeoutMs);
}

async function runTagsAuto(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const channelIds = parseListValues(options.chat);
      const limit = parsePositiveInt(options.limit, '--limit') ?? 50;
      const results = await messageSyncService.autoTagChannels({
        channelIds: channelIds.length ? channelIds : null,
        limit,
        source: options.source,
        refreshMetadata: options.refreshMetadata !== false,
      });
      if (globalFlags.json) {
        writeJson(results);
      } else {
        for (const entry of results) {
          console.log(`${entry.channelId}: ${entry.tags.map((tag) => tag.tag).join(', ')}`);
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runMetadataGet(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      let metadata = messageSyncService.getChannelMetadata(options.chat);
      if (!metadata) {
        if (!(await telegramClient.isAuthorized().catch(() => false))) {
          throw new Error('Not authenticated. Run `node cli.js auth` first.');
        }
        const live = await telegramClient.getPeerMetadata(options.chat);
        metadata = {
          channelId: String(options.chat),
          peerTitle: live?.peerTitle ?? null,
          peerType: live?.peerType ?? null,
          chatType: live?.chatType ?? null,
          isForum: live?.isForum ?? null,
          username: live?.username ?? null,
          about: live?.about ?? null,
          metadataUpdatedAt: null,
          source: 'live',
        };
      }
      if (globalFlags.json) {
        writeJson(metadata);
      } else {
        console.log(JSON.stringify(metadata, null, 2));
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runMetadataRefresh(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const channelIds = parseListValues(options.chat);
      const limit = parsePositiveInt(options.limit, '--limit') ?? 20;
      const results = await messageSyncService.refreshChannelMetadata({
        channelIds: channelIds.length ? channelIds : null,
        limit,
        force: Boolean(options.force),
        onlyMissing: Boolean(options.onlyMissing),
      });
      if (globalFlags.json) {
        writeJson(results);
      } else {
        console.log(JSON.stringify(results, null, 2));
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runContactsSearch(globalFlags, queryParts, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const query = (queryParts || []).join(' ').trim();
    if (!query) {
      throw new Error('search requires a query');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      await messageSyncService.refreshContacts();
      const contacts = messageSyncService.searchContacts(query, {
        limit: parsePositiveInt(options.limit, '--limit') ?? 50,
      });

      if (globalFlags.json) {
        writeJson(contacts);
      } else {
        for (const contact of contacts) {
          const label = contact.alias || contact.displayName || contact.username || contact.userId;
          console.log(`${label} (${contact.userId})`);
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runContactsShow(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.user) {
      throw new Error('--user is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      let contact = messageSyncService.getContact(options.user);
      if (!contact) {
        if (!(await telegramClient.isAuthorized().catch(() => false))) {
          throw new Error('Not authenticated. Run `node cli.js auth` first.');
        }
        await messageSyncService.refreshContacts();
        contact = messageSyncService.getContact(options.user);
      }
      if (!contact) {
        throw new Error('Contact not found.');
      }

      if (globalFlags.json) {
        writeJson(contact);
      } else {
        console.log(JSON.stringify(contact, null, 2));
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runContactsAliasSet(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.user) {
      throw new Error('--user is required');
    }
    if (!options.alias) {
      throw new Error('--alias is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      const alias = messageSyncService.setContactAlias(options.user, options.alias);
      if (globalFlags.json) {
        writeJson({ userId: options.user, alias });
      } else {
        console.log(`Alias set for ${options.user}: ${alias}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runContactsAliasRm(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.user) {
      throw new Error('--user is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      messageSyncService.removeContactAlias(options.user);
      if (globalFlags.json) {
        writeJson({ userId: options.user, removed: true });
      } else {
        console.log(`Alias removed for ${options.user}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runContactsTagsAdd(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.user) {
      throw new Error('--user is required');
    }
    const tags = parseListValues(options.tag);
    if (!tags.length) {
      throw new Error('--tag is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      const updated = messageSyncService.addContactTags(options.user, tags);
      if (globalFlags.json) {
        writeJson({ userId: options.user, tags: updated });
      } else {
        console.log(`Tags updated for ${options.user}: ${updated.join(', ')}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runContactsTagsRm(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.user) {
      throw new Error('--user is required');
    }
    const tags = parseListValues(options.tag);
    if (!tags.length) {
      throw new Error('--tag is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      const updated = messageSyncService.removeContactTags(options.user, tags);
      if (globalFlags.json) {
        writeJson({ userId: options.user, tags: updated });
      } else {
        console.log(`Tags updated for ${options.user}: ${updated.join(', ')}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runContactsNotesSet(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.user) {
      throw new Error('--user is required');
    }
    if (options.notes === undefined) {
      throw new Error('--notes is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      const notes = messageSyncService.setContactNotes(options.user, options.notes);
      if (globalFlags.json) {
        writeJson({ userId: options.user, notes });
      } else {
        console.log(`Notes updated for ${options.user}.`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupsList(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const groups = await telegramClient.listGroups({
        query: options.query,
        limit: parsePositiveInt(options.limit, '--limit') ?? 100,
      });

      if (globalFlags.json) {
        writeJson(groups);
      } else {
        for (const group of groups) {
          console.log(`${group.title} (${group.id})`);
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupsInfo(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const info = await telegramClient.getGroupInfo(options.chat);
      if (globalFlags.json) {
        writeJson(info);
      } else {
        console.log(JSON.stringify(info, null, 2));
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupJoinRequestsList(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const result = await telegramClient.listGroupJoinRequests(options.chat, {
        limit: parsePositiveInt(options.limit, '--limit') ?? 100,
        query: options.query,
        link: options.link,
      });
      const payload = { channelId: options.chat, ...result };

      if (globalFlags.json) {
        writeJson(payload);
      } else if (!result.requests.length) {
        console.log('No pending join requests.');
      } else {
        for (const request of result.requests) {
          const username = request.username ? ` @${request.username}` : '';
          const bio = request.bio ? ` — ${request.bio}` : '';
          console.log(`${request.displayName ?? 'Unknown'}${username} (${request.userId}) ${request.requestedAt}${bio}`);
        }
        console.log(`Showing ${result.returned} of ${result.total} pending request(s).`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupJoinRequestResolution(globalFlags, options = {}, action) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    if (!options.user) {
      throw new Error('--user is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      await telegramClient.resolveGroupJoinRequest(options.chat, options.user, action);
      const payload = {
        channelId: options.chat,
        userId: options.user,
        action,
        ok: true,
      };
      if (globalFlags.json) {
        writeJson(payload);
      } else {
        console.log(`Join request ${action === 'approve' ? 'approved' : 'declined'} for ${options.user}.`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupJoinRequestApprove(globalFlags, options = {}) {
  return runGroupJoinRequestResolution(globalFlags, options, 'approve');
}

async function runGroupJoinRequestDecline(globalFlags, options = {}) {
  return runGroupJoinRequestResolution(globalFlags, options, 'decline');
}

async function runGroupsRename(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    if (!options.name) {
      throw new Error('--name is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      await telegramClient.renameGroup(options.chat, options.name);
      if (globalFlags.json) {
        writeJson({ channelId: options.chat, name: options.name });
      } else {
        console.log(`Group renamed: ${options.name}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupMembersAdd(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const users = parseListValues(options.user);
    if (!users.length) {
      throw new Error('--user is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const failed = await telegramClient.addGroupMembers(options.chat, users);
      if (globalFlags.json) {
        writeJson({ channelId: options.chat, failed });
      } else if (failed.length) {
        console.log(`Some members failed: ${JSON.stringify(failed, null, 2)}`);
      } else {
        console.log('Members added.');
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupMembersRemove(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const users = parseListValues(options.user);
    if (!users.length) {
      throw new Error('--user is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const result = await telegramClient.removeGroupMembers(options.chat, users);
      if (globalFlags.json) {
        writeJson({ channelId: options.chat, ...result });
      } else {
        console.log(`Removed: ${result.removed.join(', ')}`);
        if (result.failed.length) {
          console.log(`Failed: ${JSON.stringify(result.failed, null, 2)}`);
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupInviteLinkGet(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const link = await telegramClient.getGroupInviteLink(options.chat);
      if (globalFlags.json) {
        writeJson({
          link: link.link,
          requestNeeded: Boolean(link.approvalNeeded),
          isPrimary: Boolean(link.isPrimary),
        });
      } else {
        console.log(link.link);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupInviteLinkEdit(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    if (!options.link) {
      throw new Error('--link is required');
    }
    if (options.requestNeeded === undefined) {
      throw new Error('--request-needed is required');
    }
    const requestNeeded = parseBooleanValue(options.requestNeeded);
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const invite = await telegramClient.editGroupInviteLink(options.chat, options.link, {
        requestNeeded,
      });
      const payload = {
        channelId: options.chat,
        link: invite.link,
        requestNeeded: Boolean(invite.approvalNeeded),
        isPrimary: Boolean(invite.isPrimary),
      };
      if (globalFlags.json) {
        writeJson(payload);
      } else {
        console.log(`${invite.link} (request needed: ${payload.requestNeeded})`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupInviteLinkRevoke(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const existing = await telegramClient.getGroupInviteLink(options.chat);
      const link = await telegramClient.revokeGroupInviteLink(options.chat, existing);
      if (globalFlags.json) {
        writeJson({ link: link.link });
      } else {
        console.log(link.link);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupsJoin(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.code) {
      throw new Error('--code is required');
    }
    const invite = normalizeInviteCode(options.code);
    if (!invite) {
      throw new Error('Invalid invite code.');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      const chat = await telegramClient.joinGroup(invite);
      if (globalFlags.json) {
        writeJson({
          id: chat.id?.toString?.() ?? null,
          title: chat.displayName || chat.title || 'Unknown',
          username: chat.username ?? null,
        });
      } else {
        console.log(`Joined: ${chat.displayName || chat.title || 'Unknown'}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runGroupsLeave(globalFlags, options = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) {
      throw new Error('--chat is required');
    }
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });

    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `node cli.js auth` first.');
      }
      await telegramClient.leaveGroup(options.chat);
      if (globalFlags.json) {
        writeJson({ channelId: options.chat, left: true });
      } else {
        console.log(`Left ${options.chat}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runFoldersList(globalFlags) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const folders = await telegramClient.getFolders();
      if (globalFlags.json) {
        writeJson(folders);
      } else {
        for (const f of folders) {
          console.log(`${f.title} (id=${f.id}, type=${f.type})`);
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runFoldersShow(globalFlags, folder, opts = {}) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const release = acquireReadLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const info = await telegramClient.showFolder(folder, { resolve: opts.resolve });
      if (globalFlags.json) {
        writeJson(info);
      } else {
        console.log(`${info.title} (id=${info.id}, type=${info.type})`);
        if (info.emoji) console.log(`  emoji: ${info.emoji}`);
        const flags = ['contacts', 'nonContacts', 'groups', 'broadcasts', 'bots'].filter((f) => info[f]);
        if (flags.length) console.log(`  includes: ${flags.join(', ')}`);
        const excludes = ['excludeMuted', 'excludeRead', 'excludeArchived'].filter((f) => info[f]);
        if (excludes.length) console.log(`  excludes: ${excludes.join(', ')}`);

        if (opts.resolve) {
          // Group peers by type and show with names
          const printResolvedPeers = (peers, label) => {
            if (!peers?.length) return;
            if (label) console.log(`  ${label}:`);
            const indent = label ? '    ' : '  ';
            const grouped = {};
            for (const p of peers) {
              const group = p.type + 's';
              if (!grouped[group]) grouped[group] = [];
              const displayName = p.name ?? p.title ?? '(unresolved)';
              grouped[group].push(`${displayName} (${p.id})`);
            }
            for (const [group, items] of Object.entries(grouped)) {
              console.log(`${indent}${group}:`);
              for (const item of items) console.log(`${indent}  - ${item}`);
            }
          };
          printResolvedPeers(info.includePeers);
          printResolvedPeers(info.excludePeers, 'excluded');
          printResolvedPeers(info.pinnedPeers, 'pinned');
        } else {
          // Show typed ID list
          const printPeers = (peers, label) => {
            if (!peers?.length) {
              console.log(`  ${label}: (none)`);
              return;
            }
            console.log(`  ${label}:`);
            for (const p of peers) console.log(`    - ${p.type}:${p.id}`);
          };
          printPeers(info.includePeers, 'includePeers');
          printPeers(info.excludePeers, 'excludePeers');
          printPeers(info.pinnedPeers, 'pinnedPeers');
        }
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runFoldersCreate(globalFlags, options) {
  if (!options.title || options.title.length > 12) throw new Error('Folder title must be 1-12 characters');
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const result = await telegramClient.createFolder({
        title: options.title,
        emoji: options.emoji,
        contacts: options.includeContacts,
        nonContacts: options.includeNonContacts,
        groups: options.includeGroups,
        broadcasts: options.includeChannels,
        bots: options.includeBots,
        excludeMuted: options.excludeMuted,
        excludeRead: options.excludeRead,
        excludeArchived: options.excludeArchived,
        includePeers: options.chat?.length ? options.chat : undefined,
        excludePeers: options.excludeChat?.length ? options.excludeChat : undefined,
        pinnedPeers: options.pinChat?.length ? options.pinChat : undefined,
      });
      if (globalFlags.json) {
        writeJson(result);
      } else {
        console.log(`Created folder: ${result.title} (id=${result.id})`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runFoldersEdit(globalFlags, folder, options) {
  if (options.title !== undefined && (options.title.length === 0 || options.title.length > 12)) throw new Error('Folder title must be 1-12 characters');
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const modification = {};
      if (options.title !== undefined) modification.title = options.title;
      if (options.emoji !== undefined) modification.emoji = options.emoji;
      if (options.includeContacts !== undefined) modification.contacts = options.includeContacts;
      if (options.includeNonContacts !== undefined) modification.nonContacts = options.includeNonContacts;
      if (options.includeGroups !== undefined) modification.groups = options.includeGroups;
      if (options.includeChannels !== undefined) modification.broadcasts = options.includeChannels;
      if (options.includeBots !== undefined) modification.bots = options.includeBots;
      if (options.excludeMuted !== undefined) modification.excludeMuted = options.excludeMuted;
      if (options.excludeRead !== undefined) modification.excludeRead = options.excludeRead;
      if (options.excludeArchived !== undefined) modification.excludeArchived = options.excludeArchived;
      if (options.chat?.length) modification.includePeers = options.chat;
      if (options.excludeChat?.length) modification.excludePeers = options.excludeChat;
      if (options.pinChat?.length) modification.pinnedPeers = options.pinChat;
      const result = await telegramClient.editFolder(folder, modification);
      if (globalFlags.json) {
        writeJson(result);
      } else {
        console.log(`Updated folder: ${result.title} (id=${result.id})`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runFoldersDelete(globalFlags, folder) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const result = await telegramClient.deleteFolder(folder);
      if (globalFlags.json) {
        writeJson(result);
      } else {
        console.log(`Deleted folder id=${result.id}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runFoldersReorder(globalFlags, options) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const ids = options.ids.split(',').map((s) => s.trim()).filter((s) => s !== '').map(Number);
      const result = await telegramClient.setFoldersOrder(ids);
      if (globalFlags.json) {
        writeJson(result);
      } else {
        console.log('Folders reordered');
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runFoldersChatsAdd(globalFlags, folder, options) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) throw new Error('--chat is required');
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const result = await telegramClient.addChatToFolder(folder, options.chat);
      if (globalFlags.json) {
        writeJson(result);
      } else {
        console.log(`Chat added to folder id=${result.folderId}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runFoldersChatsRemove(globalFlags, folder, options) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    if (!options.chat) throw new Error('--chat is required');
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const result = await telegramClient.removeChatFromFolder(folder, options.chat);
      if (globalFlags.json) {
        writeJson(result);
      } else {
        console.log(`Chat removed from folder id=${result.folderId}`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

async function runFoldersJoin(globalFlags, link) {
  const timeoutMs = globalFlags.timeoutMs;
  return runWithTimeout(async () => {
    const storeDir = resolveStoreDir();
    const release = acquireStoreLock(storeDir);
    const { telegramClient, messageSyncService } = createServices({ storeDir });
    try {
      if (!(await telegramClient.isAuthorized().catch(() => false))) {
        throw new Error('Not authenticated. Run `tgcli auth` first.');
      }
      const result = await telegramClient.joinChatlist(link);
      if (globalFlags.json) {
        writeJson(result);
      } else {
        console.log(`Joined folder: ${result.title} (id=${result.id})`);
      }
    } finally {
      await messageSyncService.shutdown();
      await telegramClient.destroy();
      release();
    }
  }, timeoutMs);
}

const ownerCliHandlers = {
  'auth status': runAuthStatus,
  'config set': runConfigSet,
  'config unset': runConfigUnset,
  'channels show': runChannelsShow,
  'channels sync': runChannelsSync,
  'messages list': runMessagesList,
  'messages search': runMessagesSearch,
  'messages show': runMessagesShow,
  'messages edit-caption': runMessagesEditCaption,
  'messages context': runMessagesContext,
  'messages buttons list': runMessageButtonsList,
  'messages buttons click': runMessageButtonClick,
  'send text': runSendText,
  'send photo': runSendPhoto,
  'send file': runSendFile,
  'media download': runMediaDownload,
  'topics list': runTopicsList,
  'topics search': runTopicsSearch,
  'tags set': runTagsSet,
  'tags list': runTagsList,
  'tags search': runTagsSearch,
  'tags auto': runTagsAuto,
  'metadata get': runMetadataGet,
  'metadata refresh': runMetadataRefresh,
  'contacts search': runContactsSearch,
  'contacts show': runContactsShow,
  'contacts alias set': runContactsAliasSet,
  'contacts alias rm': runContactsAliasRm,
  'contacts tags add': runContactsTagsAdd,
  'contacts tags rm': runContactsTagsRm,
  'contacts notes set': runContactsNotesSet,
  'groups list': runGroupsList,
  'groups info': runGroupsInfo,
  'groups requests list': runGroupJoinRequestsList,
  'groups requests approve': runGroupJoinRequestApprove,
  'groups requests decline': runGroupJoinRequestDecline,
  'groups rename': runGroupsRename,
  'groups members add': runGroupMembersAdd,
  'groups members remove': runGroupMembersRemove,
  'groups invite get': runGroupInviteLinkGet,
  'groups invite edit': runGroupInviteLinkEdit,
  'groups invite revoke': runGroupInviteLinkRevoke,
  'groups join': runGroupsJoin,
  'groups leave': runGroupsLeave,
  'folders list': runFoldersList,
  'folders show': runFoldersShow,
  'folders create': runFoldersCreate,
  'folders edit': runFoldersEdit,
  'folders delete': runFoldersDelete,
  'folders reorder': runFoldersReorder,
  'folders chats add': runFoldersChatsAdd,
  'folders chats remove': runFoldersChatsRemove,
  'folders join': runFoldersJoin,
};

const localCliCommands = new Set([
  'auth',
  'auth logout',
  'accounts list',
  'accounts add',
  'config list',
  'config get',
  'sync',
  'sync status',
  'sync jobs list',
  'sync jobs add',
  'sync jobs retry',
  'sync jobs cancel',
  'server',
  'owner request',
  'service install',
  'service start',
  'service stop',
  'service status',
  'service logs',
  'doctor',
  'channels list',
  'webapp serve',
]);

export function classifyCliRoute(name) {
  if (ownerCliHandlers[name]) return 'owner';
  if (localCliCommands.has(name)) return 'local';
  return null;
}

let ownerOutputCaptureInstalled = false;
function installOwnerOutputCapture() {
  if (ownerOutputCaptureInstalled) return;
  ownerOutputCaptureInstalled = true;
  const originalLog = console.log.bind(console);
  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
  const originalStderrWrite = process.stderr.write.bind(process.stderr);
  console.log = (...values) => {
    const context = ownerExecution.getStore();
    if (context?.active) context.stdout.push(`${formatOutput(...values)}\n`);
    else originalLog(...values);
  };
  const captureWrite = (original, field) => (chunk, encoding, callback) => {
    const context = ownerExecution.getStore();
    if (!context?.active) return original(chunk, encoding, callback);
    context[field].push(Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk));
    const done = typeof encoding === 'function' ? encoding : callback;
    if (typeof done === 'function') done();
    return true;
  };
  process.stdout.write = captureWrite(originalStdoutWrite, 'stdout');
  process.stderr.write = captureWrite(originalStderrWrite, 'stderr');
}

export async function executeOwnerCliCommand({ commandPath, args, flags }, services, storeDir) {
  const handler = ownerCliHandlers[commandPath];
  if (!handler || !Array.isArray(args)) throw new Error('Owner CLI command is not allowed');
  installOwnerOutputCapture();
  const context = {
    storeDir,
    services,
    telegramClient: ownerServiceProxy(services.telegramClient, 'destroy'),
    messageSyncService: ownerServiceProxy(services.messageSyncService, 'shutdown'),
    stdout: [],
    stderr: [],
    active: true,
  };
  try {
    await ownerExecution.run(context, () => handler({
      json: Boolean(flags?.json),
      timeoutMs: flags?.timeoutMs ?? null,
    }, ...args));
    return { stdout: context.stdout.join(''), stderr: context.stderr.join('') };
  } finally {
    context.active = false;
  }
}

async function main() {
  await CLI_PROGRAM.parseAsync(process.argv);
}

function isCliEntrypoint(argvPath = process.argv[1]) {
  if (!argvPath) {
    return false;
  }
  try {
    return pathToFileURL(fs.realpathSync(argvPath)).href === import.meta.url;
  } catch (error) {
    process.stderr.write(`isCliEntrypoint: realpathSync failed for ${argvPath}: ${error.message}\n`);
    return pathToFileURL(path.resolve(argvPath)).href === import.meta.url;
  }
}

function resolveEntrypointPath(filePath) {
  if (!filePath) {
    return null;
  }
  try {
    return fs.realpathSync(filePath);
  } catch (error) {
    if (error?.code !== 'ENOENT') {
      console.error(`[resolveEntrypointPath] realpathSync failed for ${filePath}: ${error?.message}`);
    }
    return path.resolve(filePath);
  }
}

function shouldRunMain(entryPath = process.argv[1]) {
  const resolvedEntryPath = resolveEntrypointPath(entryPath);
  return resolvedEntryPath !== null && resolvedEntryPath === CLI_PATH;
}

export {
  buildProgram,
  buildSendPhotoSuccessPayload,
  isCliEntrypoint,
  logSendRetry,
  main,
  normalizeSendCommandError,
  parseNonNegativeInt,
  runAuthLogin,
  runGroupJoinRequestApprove,
  runGroupJoinRequestDecline,
  runGroupJoinRequestsList,
  runGroupInviteLinkEdit,
  runGroupInviteLinkGet,
  runMessageButtonClick,
  runMessageButtonsList,
  shouldRunMain,
  writeError,
};

if (isCliEntrypoint()) {
  await main();
}