@moxxy/plugin-telegram 0.27.0

package/src/index.ts

@@ -0,0 +1,347 @@
+import { defineChannel, defineTool, definePlugin, z, type LifecycleHooks, type Plugin } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { Api, GrammyError } from 'grammy';
+import { markdownToTelegramHtml } from './format.js';
+import { stripHtml } from './channel/html.js';
+import { TelegramChannel } from './channel.js';
+import { TELEGRAM_AUTHORIZED_CHAT_KEY, TELEGRAM_TOKEN_KEY, parseChatId } from './keys.js';
+import { runTelegramWizard } from './setup-wizard.js';
+import { runPairFlow } from './pair-flow.js';
+
+export {
+  TelegramChannel,
+  type TelegramChannelOptions,
+  type TelegramStartOpts,
+} from './channel.js';
+export { TelegramPermissionResolver, type PendingPermission } from './permission.js';
+export { TelegramApprovalResolver, type PendingApproval } from './approval.js';
+export {
+  createPairingState,
+  beginHostIssuedPairing,
+  handleStart,
+  submitChatCode,
+  isAuthorized,
+  clearPairing,
+  type PairingPhase,
+  type PairingState,
+  type PairingDecision,
+} from './pairing.js';
+export type { PairingConfirmResult } from './channel.js';
+export { TurnRenderer, splitForTelegram } from './render.js';
+export { markdownToTelegramHtml } from './format.js';
+
+export interface BuildTelegramPluginOptions {
+  readonly vault: VaultStore;
+}
+
+export { TELEGRAM_TOKEN_KEY, TELEGRAM_AUTHORIZED_CHAT_KEY, TELEGRAM_TOKEN_RE } from './keys.js';
+
+// Backwards-compat aliases for the existing call sites in this file.
+const TOKEN_KEY = TELEGRAM_TOKEN_KEY;
+const AUTHORIZED_CHAT_KEY = TELEGRAM_AUTHORIZED_CHAT_KEY;
+
+export function buildTelegramPlugin(opts: BuildTelegramPluginOptions): Plugin {
+  // Host-injected vault (available immediately).
+  return makeTelegramPlugin(() => opts.vault);
+}
+
+/**
+ * Discovery-loadable default export: resolves the vault from the inter-plugin
+ * service registry in `onInit` (the vault plugin publishes `'vault'`). Requires
+ * `@moxxy/plugin-vault` to load first (declared in `package.json`
+ * `moxxy.requirements`). The channel + tools read the vault via `getVault()`,
+ * so resolution is deferred to call time — after `onInit` has wired it.
+ */
+export const telegramPlugin: Plugin = (() => {
+  let resolved: VaultStore | null = null;
+  const getVault = (): VaultStore => {
+    if (!resolved) {
+      throw new Error(
+        '@moxxy/plugin-telegram: the "vault" service is unavailable — @moxxy/plugin-vault must load first',
+      );
+    }
+    return resolved;
+  };
+  const hooks: LifecycleHooks = {
+    onInit: (ctx) => {
+      resolved = ctx.services.require<VaultStore>('vault');
+    },
+  };
+  return makeTelegramPlugin(getVault, hooks);
+})();
+
+function makeTelegramPlugin(getVault: () => VaultStore, hooks?: LifecycleHooks): Plugin {
+  return definePlugin({
+    name: '@moxxy/plugin-telegram',
+    version: '0.0.0',
+    ...(hooks ? { hooks } : {}),
+    channels: [
+      defineChannel({
+        name: 'telegram',
+        description: 'Telegram bot channel via grammy. QR deep-link chat pairing.',
+        // Like Slack, run on a dedicated, isolated runner (separate socket +
+        // sticky session) so the bot keeps its own persistent history apart from
+        // the user's desktop/TUI work. Telegram long-polls (no tunnel needed).
+        dedicatedRunner: true,
+        sessionSource: 'telegram',
+        // Self-described config so a control surface (TUI `/channels`, `moxxy
+        // channels start`) can configure + run Telegram without a hardcoded table.
+        config: {
+          fields: [
+            {
+              name: 'token',
+              label: 'Bot token',
+              vaultKey: TELEGRAM_TOKEN_KEY,
+              required: true,
+              secret: true,
+              placeholder: '123456:ABC-DEF…',
+              help: 'Create a bot with @BotFather and paste its token',
+            },
+          ],
+          hasRequestUrl: false,
+          runHint:
+            'Scan the QR (or open the link) and tap START in Telegram to pair your chat — no code to type.',
+          connect: {
+            kind: 'qr',
+            title: 'Connect your Telegram',
+            hint: 'Scan the QR with your phone (or tap Open in Telegram), then press START — your chat pairs automatically.',
+            openable: true,
+            openLabel: 'Open in Telegram',
+          },
+        },
+        create: (deps) =>
+          new TelegramChannel({
+            vault: getVault(),
+            token: (deps.options?.['token'] as string | undefined) ?? undefined,
+            logger: deps.logger as never,
+          }),
+        isAvailable: async () => {
+          const envToken = process.env.MOXXY_TELEGRAM_TOKEN;
+          if (envToken) return { ok: true };
+          try {
+            const stored = await getVault().has(TOKEN_KEY);
+            if (stored) return { ok: true };
+            return {
+              ok: false,
+              reason:
+                "No bot token. Set MOXXY_TELEGRAM_TOKEN, or store one in the vault as '" +
+                TOKEN_KEY +
+                "' via the `telegram-setup` skill.",
+            };
+          } catch {
+            return {
+              ok: false,
+              reason:
+                'Set MOXXY_TELEGRAM_TOKEN to skip the vault, or unlock the vault first.',
+            };
+          }
+        },
+        interactiveCommand: 'setup',
+        subcommands: {
+          setup: {
+            description:
+              'Interactive setup: store a bot token, pair a chat, then start the bot. Shown by default for `moxxy telegram` on a TTY.',
+            run: async (ctx) => {
+              // The wizard drives token entry + pairing through clack
+              // prompts, so it needs an interactive terminal. In a
+              // headless invocation we just start the bot directly.
+              if (process.stdin.isTTY !== true) {
+                return ctx.startChannel();
+              }
+              return runTelegramWizard(ctx);
+            },
+          },
+          pair: {
+            description:
+              'Open a pairing window and print a QR. Scan it (or open the link) and tap START in Telegram to pair your chat — the same mechanism the desktop uses.',
+            run: async (ctx) => {
+              // Pairing renders a QR for the user to scan, so it needs an
+              // interactive terminal. In a headless invocation we bail with a
+              // clear message instead of starting a bot nobody can pair. (The
+              // desktop Channels panel pairs the same way without a TTY — it
+              // renders the QR in the GUI.)
+              if (process.stdin.isTTY !== true) {
+                process.stderr.write(
+                  'Pairing needs a TTY to show the QR. Run `moxxy channels telegram pair` on a workstation, or pair from the desktop Channels panel.\n',
+                );
+                return 1;
+              }
+              return runPairFlow(ctx);
+            },
+          },
+          unpair: {
+            description: 'Forget the currently authorized Telegram chat.',
+            run: async (ctx) => {
+              const vault = ctx.deps.vault as VaultStore | undefined;
+              if (!vault) {
+                process.stderr.write('vault unavailable\n');
+                return 1;
+              }
+              const removed = await vault.delete(AUTHORIZED_CHAT_KEY);
+              process.stdout.write(removed ? 'unpaired\n' : 'no pairing was active\n');
+              return 0;
+            },
+          },
+          status: {
+            description: 'Report whether a Telegram token + an authorized chat are configured.',
+            run: async (ctx) => {
+              const vault = ctx.deps.vault as VaultStore | undefined;
+              if (!vault) {
+                process.stderr.write('vault unavailable\n');
+                return 1;
+              }
+              const hasToken = await vault.has(TOKEN_KEY);
+              const authorized = await vault.get(AUTHORIZED_CHAT_KEY);
+              process.stdout.write(
+                JSON.stringify(
+                  {
+                    tokenConfigured: hasToken,
+                    authorizedChatId: parseChatId(authorized),
+                  },
+                  null,
+                  2,
+                ) + '\n',
+              );
+              return 0;
+            },
+          },
+        },
+      }),
+    ],
+    tools: [
+      defineTool({
+        name: 'telegram_set_token',
+        description:
+          'Store a Telegram bot token (from @BotFather) in the vault under telegram_bot_token. Validates the token shape but does not test connectivity.',
+        inputSchema: z.object({
+          token: z.string().regex(/^\d+:[A-Za-z0-9_-]{20,}$/, 'token must look like 1234567890:ABC...'),
+        }),
+        permission: { action: 'prompt' },
+        // Vault writes land in ~/.moxxy/vault.json (key material in
+        // ~/.moxxy/vault.key) — hence the vault.* glob.
+        isolation: {
+          capabilities: {
+            fs: { read: ['~/.moxxy/vault.*'], write: ['~/.moxxy/vault.*'] },
+            net: { mode: 'none' },
+            timeMs: 10_000,
+          },
+        },
+        handler: async ({ token }) => {
+          await getVault().set(TOKEN_KEY, token, ['telegram']);
+          return `stored Telegram token (${token.split(':')[0]}:…) in vault`;
+        },
+      }),
+      defineTool({
+        name: 'telegram_status',
+        description: 'Report whether a Telegram token + an authorized chat are configured.',
+        inputSchema: z.object({}),
+        isolation: {
+          capabilities: {
+            fs: { read: ['~/.moxxy/vault.*'] },
+            net: { mode: 'none' },
+            timeMs: 10_000,
+          },
+        },
+        handler: async () => {
+          const hasToken = await getVault().has(TOKEN_KEY);
+          const authorized = await getVault().get(AUTHORIZED_CHAT_KEY);
+          return {
+            tokenConfigured: hasToken,
+            authorizedChatId: parseChatId(authorized),
+          };
+        },
+      }),
+      defineTool({
+        name: 'telegram_send_message',
+        description:
+          'Push a one-off message to the currently authorized Telegram chat. Use this from a ' +
+          'scheduled prompt to deliver results without an interactive channel running. By ' +
+          'default the text is rendered with the same rich Markdown→Telegram formatting as ' +
+          'interactive replies (bold, code, `> [!type]` callouts, `||spoilers||`, etc.); pass ' +
+          'an explicit `parseMode` to send the raw text under that parse mode instead. Requires ' +
+          'a stored bot token + a paired chat (run `moxxy channels telegram pair` once).',
+        inputSchema: z.object({
+          text: z.string().min(1).max(4096),
+          /** Optional override; defaults to the vault-paired chat id. */
+          chatId: z.number().int().optional(),
+          /**
+           * Force a specific Telegram parse mode and send `text` verbatim under
+           * it. Omit to get the default Markdown→HTML rendering (recommended).
+           */
+          parseMode: z.enum(['MarkdownV2', 'Markdown', 'HTML']).optional(),
+        }),
+        permission: { action: 'prompt' },
+        isolation: {
+          capabilities: {
+            fs: { read: ['~/.moxxy/vault.*'] },
+            net: { mode: 'allowlist', hosts: ['api.telegram.org'] },
+            env: ['MOXXY_TELEGRAM_TOKEN'],
+            timeMs: 60_000,
+          },
+        },
+        handler: async ({ text, chatId, parseMode }) => {
+          const token = process.env.MOXXY_TELEGRAM_TOKEN ?? (await getVault().get(TOKEN_KEY));
+          if (!token) {
+            throw new Error(
+              'no Telegram bot token configured (set MOXXY_TELEGRAM_TOKEN or run `moxxy init` to store one)',
+            );
+          }
+          const targetChat =
+            chatId ?? parseChatId(await getVault().get(AUTHORIZED_CHAT_KEY));
+          if (!targetChat) {
+            throw new Error(
+              'no authorized chat — run `moxxy channels telegram pair` first or pass `chatId` explicitly',
+            );
+          }
+          // Use grammy's lightweight `Api` client directly rather than a full
+          // `Bot` (which builds a polling-capable instance + lazily resolves
+          // bot info). This is a one-off send — no long-polling — so the Bot
+          // wrapper was pure overhead per invocation.
+          const api = new Api(token);
+          if (parseMode) {
+            // Explicit mode → caller owns the markup; send text verbatim.
+            await api.sendMessage(targetChat, text, { parse_mode: parseMode });
+          } else {
+            // Default → render Markdown to Telegram HTML for the same rich look
+            // as interactive replies, falling back to plain text if the model's
+            // text produced an entity Telegram can't parse (rare).
+            const html = markdownToTelegramHtml(text);
+            try {
+              await api.sendMessage(targetChat, html, {
+                parse_mode: 'HTML',
+                link_preview_options: { is_disabled: true },
+              });
+            } catch (err) {
+              if (err instanceof GrammyError && /can't parse entities|Bad Request: can't parse/i.test(err.description ?? '')) {
+                await api.sendMessage(targetChat, stripHtml(html));
+              } else {
+                throw err;
+              }
+            }
+          }
+          return { delivered: true, chatId: targetChat, length: text.length };
+        },
+      }),
+      defineTool({
+        name: 'telegram_unpair',
+        description: 'Forget the currently authorized Telegram chat. The next /start will start a fresh pairing.',
+        inputSchema: z.object({}),
+        permission: { action: 'prompt' },
+        isolation: {
+          capabilities: {
+            fs: { read: ['~/.moxxy/vault.*'], write: ['~/.moxxy/vault.*'] },
+            net: { mode: 'none' },
+            timeMs: 10_000,
+          },
+        },
+        handler: async () => {
+          const removed = await getVault().delete(AUTHORIZED_CHAT_KEY);
+          return removed ? 'unpaired' : 'no pairing was active';
+        },
+      }),
+    ],
+  });
+}
+
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default telegramPlugin;

package/src/keys.ts

@@ -0,0 +1,52 @@
+/**
+ * Vault keys + token validation shared by the channel, its subcommands, and the
+ * interactive setup wizard. Kept in their own module so the wizard / pair-flow
+ * helpers can import them without pulling in the plugin's full index.
+ */
+
+/** Vault key the plugin uses for the Bot API token. */
+export const TELEGRAM_TOKEN_KEY = 'telegram_bot_token';
+/** Vault key the plugin uses for the paired chat id. */
+export const TELEGRAM_AUTHORIZED_CHAT_KEY = 'telegram_authorized_chat_id';
+/**
+ * Vault key for the voice-replies preference. Single-paired-chat model, so a
+ * simple present-flag (`'1'` = on, absent = off) keyed like the other telegram
+ * keys, toggled from the paired chat via `/voice`.
+ */
+export const TELEGRAM_VOICE_REPLIES_KEY = 'telegram_voice_replies';
+/** Regex validating a Telegram bot token (`<digits>:<22+ url-safe>`). */
+export const TELEGRAM_TOKEN_RE = /^\d+:[A-Za-z0-9_-]{20,}$/;
+
+/** The narrow vault slice the voice-replies flag helpers use. */
+interface VoiceFlagVault {
+  get(name: string): Promise<string | null>;
+  set(name: string, value: string): Promise<void>;
+  delete(name: string): Promise<boolean>;
+}
+
+/** Read the persisted voice-replies preference (`'1'` → on). */
+export async function loadVoiceReplies(vault: Pick<VoiceFlagVault, 'get'>): Promise<boolean> {
+  return (await vault.get(TELEGRAM_VOICE_REPLIES_KEY)) === '1';
+}
+
+/** Persist the voice-replies preference: store `'1'` when on, remove it when off. */
+export async function saveVoiceReplies(
+  vault: Pick<VoiceFlagVault, 'set' | 'delete'>,
+  on: boolean,
+): Promise<void> {
+  if (on) await vault.set(TELEGRAM_VOICE_REPLIES_KEY, '1');
+  else await vault.delete(TELEGRAM_VOICE_REPLIES_KEY);
+}
+
+/**
+ * Parse a stored chat-id (the vault keeps it as a string). Returns `null` for a
+ * missing OR corrupt value rather than letting `Number(x)` yield `NaN` — a
+ * silent NaN serializes to `null` in status output (masking the corruption) and
+ * would otherwise be passed to `api.sendMessage(NaN, …)` as a real target,
+ * producing an opaque Telegram 400 instead of a clear "not paired" signal.
+ */
+export function parseChatId(raw: string | null | undefined): number | null {
+  if (raw == null || raw === '') return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}

package/src/pair-flow.ts

@@ -0,0 +1,131 @@
+import { log, outro, spinner } from '@clack/prompts';
+import QRCode from 'qrcode';
+import { exitAfterPairRequested, type ChannelSubcommandContext } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { TelegramChannel } from './channel.js';
+
+// Tiny zero-dep ANSI dim helper, so this flow stays inside the plugin.
+const ANSI = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s: string): string => (ANSI ? `\x1b[2m${s}\x1b[22m` : s);
+
+/**
+ * Drive the host-issued QR pairing flow end-to-end in a terminal — the SAME
+ * mechanism the desktop Channels panel uses, just rendered inline here.
+ *
+ * Steps:
+ *   1. Build a TelegramChannel from the subcommand ctx and wire the session's
+ *      permission resolver.
+ *   2. Subscribe to "paired" BEFORE starting the bot so a fast scan can't race us.
+ *   3. Start the bot in pairing mode — it mints a code and publishes a
+ *      `t.me/<bot>?start=<code>` deep link as `channel.requestUrl`.
+ *   4. Render that deep link as a scannable QR (+ the plain link).
+ *   5. The user scans / opens the link and taps START (or sends the 6 digits);
+ *      the bot authorizes that chat and `onPaired` fires.
+ *   6. Hand off SIGINT to keep the bot running until the user Ctrl-Cs.
+ */
+export async function runPairFlow(ctx: ChannelSubcommandContext): Promise<number> {
+  const session = ctx.session;
+  const channel = new TelegramChannel({
+    vault: ctx.deps.vault as VaultStore,
+    token: (ctx.deps.options?.['token'] as string | undefined) ?? undefined,
+    logger: ctx.deps.logger as never,
+  });
+  session.setPermissionResolver(channel.permissionResolver);
+
+  // Subscribe BEFORE start so the first scan can't fire before us.
+  let pairedResolve: ((chatId: number) => void) | null = null;
+  const paired = new Promise<number>((resolve) => {
+    pairedResolve = resolve;
+  });
+  const unsubscribe = channel.onPaired((chatId) => {
+    pairedResolve?.(chatId);
+    pairedResolve = null;
+  });
+
+  outro(dim('opening pairing window...'));
+
+  // `pair: true` opens the host-issued QR window and resolves the bot's deep link.
+  const handle = await channel.start({ session, pair: true });
+
+  // From here on we own the bot lifecycle. Any failure path needs to
+  // call stopBot() before returning.
+  const stopBot = async (): Promise<void> => {
+    unsubscribe();
+    try {
+      await handle.stop('wizard');
+    } catch {
+      /* ignore */
+    }
+  };
+
+  // Already paired (no window was opened): there's nothing to scan. Tell the
+  // user how to re-pair rather than hanging on a pairing that can't happen.
+  if (channel.connected) {
+    log.info(
+      'This bot is already paired. Run `moxxy channels telegram unpair` first to pair a different chat.',
+    );
+    await stopBot();
+    return 0;
+  }
+
+  const url = channel.requestUrl;
+  if (!url) {
+    log.error('Could not resolve the bot link — check the token is valid and the network is reachable.');
+    await stopBot();
+    return 1;
+  }
+
+  await printPairQr(url);
+  log.info('Scan the QR with your phone (or open the link and tap START) — your chat pairs automatically.');
+
+  // Graceful Ctrl-C while waiting (or once running): stop the bot and exit.
+  let stopping = false;
+  const shutdown = async (): Promise<void> => {
+    if (stopping) return;
+    stopping = true;
+    await stopBot();
+    await session.close('SIGINT').catch(() => undefined);
+    process.exit(0);
+  };
+  const onSignal = (): void => void shutdown();
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+
+  const spin = spinner();
+  spin.start('Waiting for you to pair in Telegram...');
+  const chatId = await paired;
+  spin.stop(`Paired ✓ — chat ${chatId} is authorized.`);
+
+  if (exitAfterPairRequested(ctx)) {
+    // Orchestrated pairing (`moxxy onboard`): hand control back — the caller
+    // starts the bot under its own service afterwards. Our SIGINT handlers
+    // would `process.exit` the orchestrator, so drop them first.
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+    await stopBot();
+    return 0;
+  }
+
+  log.info('Bot is running. Press Ctrl+C to stop.');
+  try {
+    // Only reached if the bot stops on its own (a signal path exits via
+    // shutdown()); remove our handlers so they don't outlive this flow.
+    await handle.running;
+    return 0;
+  } finally {
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  }
+}
+
+/** Render the pairing deep link as a scannable terminal QR + the plain link. */
+async function printPairQr(url: string): Promise<void> {
+  let qr = '';
+  try {
+    qr = await QRCode.toString(url, { type: 'terminal', small: true });
+  } catch {
+    qr = '';
+  }
+  // CLI surface — intentional stdout.
+  console.log(['', qr, `  link: ${url}`, ''].join('\n'));
+}

package/src/pairing.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beginHostIssuedPairing,
+  createPairingState,
+  handleStart,
+  isAuthorized,
+  submitChatCode,
+} from './pairing.js';
+
+describe('pairing protocol (host-issued QR code)', () => {
+  it('starts in idle phase', () => {
+    const s = createPairingState();
+    expect(s.phase).toBe('idle');
+    expect(s.authorizedChatId).toBeNull();
+  });
+
+  it('starts in paired phase when an authorized chat is restored', () => {
+    const s = createPairingState({ authorizedChatId: 42 });
+    expect(s.phase).toBe('paired');
+    expect(isAuthorized(s, 42)).toBe(true);
+    expect(isAuthorized(s, 99)).toBe(false);
+  });
+
+  it('beginHostIssuedPairing mints a 6-digit code up front and opens the window', () => {
+    const { state, code } = beginHostIssuedPairing(createPairingState());
+    expect(state.phase).toBe('awaiting-host-code');
+    expect(code).toMatch(/^\d{6}$/);
+    expect(state.code).toBe(code);
+    // No TTL by default — the window lives as long as the channel runs unpaired.
+    expect(state.expiresAt).toBeNull();
+  });
+
+  it('submitChatCode pairs the presenting chat on the correct code', () => {
+    const { state, code } = beginHostIssuedPairing(createPairingState());
+    const r = submitChatCode(state, 1, code);
+    expect(r.action.kind).toBe('paired');
+    expect(r.state.phase).toBe('paired');
+    expect(r.state.authorizedChatId).toBe(1);
+    expect(isAuthorized(r.state, 1)).toBe(true);
+  });
+
+  it('submitChatCode accepts the code with surrounding whitespace', () => {
+    const { state, code } = beginHostIssuedPairing(createPairingState());
+    const r = submitChatCode(state, 7, `  ${code} `);
+    expect(r.action.kind).toBe('paired');
+    expect(r.state.authorizedChatId).toBe(7);
+  });
+
+  it('submitChatCode reports a mismatch on a wrong code', () => {
+    const { state, code } = beginHostIssuedPairing(createPairingState());
+    const wrong = code === '000000' ? '111111' : '000000';
+    const r = submitChatCode(state, 1, wrong);
+    expect(r.action.kind).toBe('mismatch');
+    if (r.action.kind !== 'mismatch') return;
+    expect(r.action.message).toMatch(/didn't match/);
+  });
+
+  it('submitChatCode treats non-digit input as a mismatch', () => {
+    const { state } = beginHostIssuedPairing(createPairingState());
+    const r = submitChatCode(state, 1, 'hello!');
+    expect(r.action.kind).toBe('mismatch');
+  });
+
+  it('submitChatCode reports not-pending when no window is open', () => {
+    const r = submitChatCode(createPairingState(), 1, '123456');
+    expect(r.action.kind).toBe('not-pending');
+  });
+
+  it('submitChatCode acknowledges the already-paired chat (idempotent)', () => {
+    const r = submitChatCode(createPairingState({ authorizedChatId: 5 }), 5, '123456');
+    expect(r.action.kind).toBe('still-paired');
+  });
+
+  it('submitChatCode rejects a different chat once one is paired', () => {
+    const r = submitChatCode(createPairingState({ authorizedChatId: 5 }), 6, '123456');
+    expect(r.action.kind).toBe('reject');
+  });
+
+  it('expires after the (optional) TTL window', () => {
+    const t0 = 1_000_000;
+    const { state, code } = beginHostIssuedPairing(createPairingState(), undefined, t0, 1000);
+    const r = submitChatCode(state, 1, code, t0 + 2000);
+    expect(r.action.kind).toBe('expired');
+    expect(r.state.phase).toBe('expired');
+  });
+});
+
+describe('handleStart (bare /start, no code payload)', () => {
+  it('rejects with a "start pairing" nudge when no window is open', () => {
+    const r = handleStart(createPairingState(), 1);
+    expect(r.action.kind).toBe('reject');
+    if (r.action.kind !== 'reject') return;
+    expect(r.action.message).toMatch(/No pairing window/);
+  });
+
+  it('nudges to use the QR / send the code while a host window is open', () => {
+    const { state } = beginHostIssuedPairing(createPairingState());
+    const r = handleStart(state, 1);
+    expect(r.action.kind).toBe('reject');
+    if (r.action.kind !== 'reject') return;
+    expect(r.action.message).toMatch(/QR|code/i);
+  });
+
+  it('acknowledges the already-paired chat', () => {
+    const r = handleStart(createPairingState({ authorizedChatId: 7 }), 7);
+    expect(r.action.kind).toBe('still-paired');
+  });
+
+  it('rejects a different chat when one is paired', () => {
+    const r = handleStart(createPairingState({ authorizedChatId: 7 }), 999);
+    expect(r.action.kind).toBe('reject');
+  });
+});