talon-agent 3.34.0 → 3.35.0

package/src/frontend/telegram/auth-panel.ts

@@ -0,0 +1,205 @@
+/**
+ * /auth panel — sign the daemon's Claude and Codex CLIs back in from
+ * Telegram, admin only.
+ *
+ * The panel lists each provider's login state with a sign-in button. A
+ * tap starts the core login flow and rewrites the same message into the
+ * instructions the CLI printed: an "Open sign-in page" URL button plus,
+ * for Codex, the one-time device code, or, for Claude, a request to reply
+ * with the code the browser shows. The message is edited again when the
+ * CLI finishes, so the whole exchange lives in one bubble.
+ */
+
+import type { Context } from "grammy";
+import type { InlineKeyboardButton } from "grammy/types";
+import {
+  activeLoginFlow,
+  startLogin,
+  type LoginBinaries,
+  type LoginFlow,
+  type LoginPrompt,
+} from "../../core/auth/login-flow.js";
+import {
+  AUTH_PROVIDERS,
+  describeProviderStatus,
+  PROVIDER_LABELS,
+  readAllProviderStatus,
+  type AuthProvider,
+  type ProviderAuthStatus,
+} from "../../core/auth/status.js";
+import { logWarn } from "../../util/log.js";
+import { escapeHtml } from "./formatting.js";
+
+type AuthKeyboard = InlineKeyboardButton[][];
+
+export interface AuthPanel {
+  text: string;
+  keyboard: AuthKeyboard;
+}
+
+export function isAuthProvider(value: string): value is AuthProvider {
+  return (AUTH_PROVIDERS as readonly string[]).includes(value);
+}
+
+function statusIcon(s: ProviderAuthStatus): string {
+  if (!s.loggedIn || s.expired) return "🔴";
+  if (
+    s.loginExpiresAt !== undefined &&
+    s.loginExpiresAt - Date.now() < 7 * 86_400_000
+  )
+    return "🟡";
+  return "🟢";
+}
+
+/** The resting panel: one status line + one sign-in button per provider. */
+export function renderAuthPanel(statuses: ProviderAuthStatus[]): AuthPanel {
+  const lines = ["<b>🔑 Backend logins</b>", ""];
+  const keyboard: AuthKeyboard = [];
+  for (const s of statuses) {
+    const label = PROVIDER_LABELS[s.provider];
+    lines.push(
+      `${statusIcon(s)} <b>${label}</b> — ${escapeHtml(describeProviderStatus(s))}`,
+    );
+    const pending = activeLoginFlow(s.provider);
+    keyboard.push([
+      pending
+        ? {
+            text: `⏳ ${label} sign-in in progress…`,
+            callback_data: `auth:resume:${s.provider}`,
+          }
+        : {
+            text: `${s.loggedIn && !s.expired ? "🔄 Re-sign in to" : "🔑 Sign in to"} ${label}`,
+            callback_data: `auth:login:${s.provider}`,
+          },
+    ]);
+  }
+  keyboard.push([{ text: "↻ Refresh", callback_data: "auth:refresh" }]);
+  return { text: lines.join("\n"), keyboard };
+}
+
+/** The in-progress panel: the CLI's instructions, an open-link button, cancel. */
+export function renderLoginPrompt(
+  provider: AuthProvider,
+  prompt: LoginPrompt,
+): AuthPanel {
+  const label = PROVIDER_LABELS[provider];
+  const lines = [
+    `<b>🔑 Sign in to ${label}</b>`,
+    "",
+    "1. Open the sign-in page (button below) and log in.",
+  ];
+  if (prompt.code) {
+    lines.push(
+      `2. Enter this one-time code: <code>${escapeHtml(prompt.code)}</code>`,
+    );
+  }
+  if (prompt.needsCode) {
+    lines.push(
+      `${prompt.code ? 3 : 2}. Copy the code the page shows and <b>reply to this message</b> with it.`,
+    );
+  }
+  lines.push("", "<i>This link expires in 15 minutes.</i>");
+  return {
+    text: lines.join("\n"),
+    keyboard: [
+      [{ text: "🌐 Open sign-in page", url: prompt.url }],
+      [{ text: "✖ Cancel", callback_data: `auth:cancel:${provider}` }],
+    ],
+  };
+}
+
+export async function currentAuthPanel(): Promise<AuthPanel> {
+  return renderAuthPanel(await readAllProviderStatus());
+}
+
+/** Messages awaiting a pasted code, keyed by chat → prompt message id. */
+const awaitingCode = new Map<
+  string,
+  { provider: AuthProvider; messageId: number }
+>();
+
+export function pendingCodePrompt(
+  chatId: string,
+): { provider: AuthProvider; messageId: number } | undefined {
+  return awaitingCode.get(chatId);
+}
+
+async function editPanel(
+  ctx: Context,
+  chatId: number,
+  messageId: number,
+  panel: AuthPanel,
+): Promise<void> {
+  try {
+    await ctx.api.editMessageText(chatId, messageId, panel.text, {
+      parse_mode: "HTML",
+      reply_markup: { inline_keyboard: panel.keyboard },
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (!/message is not modified/i.test(msg))
+      logWarn("bot", `auth panel edit failed: ${msg}`);
+  }
+}
+
+/**
+ * Start (or attach to) a login for `provider` and drive the panel message
+ * through prompt → outcome. Returns once the prompt is on screen; the
+ * outcome edit happens when the CLI exits.
+ */
+export async function driveLogin(
+  ctx: Context,
+  chatId: number,
+  messageId: number,
+  provider: AuthProvider,
+  bins: LoginBinaries,
+): Promise<void> {
+  const flow: LoginFlow =
+    activeLoginFlow(provider) ?? startLogin(provider, bins);
+  let prompt: LoginPrompt;
+  try {
+    prompt = await flow.prompt;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    const panel = await currentAuthPanel();
+    await editPanel(ctx, chatId, messageId, {
+      text: `${panel.text}\n\n❌ Couldn't start ${PROVIDER_LABELS[provider]} sign-in: ${escapeHtml(detail)}`,
+      keyboard: panel.keyboard,
+    });
+    return;
+  }
+  if (prompt.needsCode)
+    awaitingCode.set(String(chatId), { provider, messageId });
+  await editPanel(ctx, chatId, messageId, renderLoginPrompt(provider, prompt));
+
+  void flow.done.then(async (outcome) => {
+    if (awaitingCode.get(String(chatId))?.messageId === messageId)
+      awaitingCode.delete(String(chatId));
+    const panel = await currentAuthPanel();
+    const label = PROVIDER_LABELS[provider];
+    const note = outcome.ok
+      ? `✅ ${label} signed in.`
+      : outcome.reason === "cancelled"
+        ? `✖ ${label} sign-in cancelled.`
+        : outcome.reason === "timeout"
+          ? `⌛ ${label} sign-in link expired. Tap the button to try again.`
+          : `❌ ${label} sign-in failed: ${escapeHtml(outcome.detail ?? "unknown error")}`;
+    await editPanel(ctx, chatId, messageId, {
+      text: `${panel.text}\n\n${note}`,
+      keyboard: panel.keyboard,
+    });
+  });
+}
+
+/** Feed a pasted code to the pending flow for this chat. True when consumed. */
+export function submitPendingCode(chatId: string, text: string): boolean {
+  const pending = awaitingCode.get(chatId);
+  if (!pending) return false;
+  const flow = activeLoginFlow(pending.provider);
+  if (!flow) {
+    awaitingCode.delete(chatId);
+    return false;
+  }
+  flow.submitCode(text);
+  return true;
+}

package/src/frontend/telegram/callbacks/auth.ts

@@ -0,0 +1,70 @@
+/**
+ * `auth:*` callbacks — the /auth panel's buttons.
+ *
+ *   auth:login:<provider>   start a sign-in and show its instructions
+ *   auth:resume:<provider>  re-show the instructions of a running sign-in
+ *   auth:cancel:<provider>  abort a running sign-in
+ *   auth:refresh            re-read credential files and redraw
+ */
+
+import type { Context } from "grammy";
+import { activeLoginFlow } from "../../../core/auth/login-flow.js";
+import { currentAuthPanel, driveLogin, isAuthProvider } from "../auth-panel.js";
+import { loginBinariesFrom } from "../commands/auth.js";
+import { isAuthorizedAdmin } from "../commands/state.js";
+import { answerCallbackQuerySafe, type CallbackDeps } from "./shared.js";
+
+export async function handleAuthCallback(
+  ctx: Context,
+  data: string,
+  { config }: CallbackDeps,
+): Promise<void> {
+  if (!isAuthorizedAdmin(ctx)) {
+    await answerCallbackQuerySafe(ctx, { text: "Not authorized." });
+    return;
+  }
+  const chatId = ctx.chat?.id;
+  const messageId = ctx.callbackQuery?.message?.message_id;
+  if (chatId === undefined || messageId === undefined) {
+    await answerCallbackQuerySafe(ctx);
+    return;
+  }
+  const [, action, provider = ""] = data.split(":");
+
+  if (action === "refresh") {
+    await answerCallbackQuerySafe(ctx);
+    const panel = await currentAuthPanel();
+    await ctx.api
+      .editMessageText(chatId, messageId, panel.text, {
+        parse_mode: "HTML",
+        reply_markup: { inline_keyboard: panel.keyboard },
+      })
+      .catch(() => {});
+    return;
+  }
+
+  if (!isAuthProvider(provider)) {
+    await answerCallbackQuerySafe(ctx, { text: "Unknown provider" });
+    return;
+  }
+
+  if (action === "cancel") {
+    activeLoginFlow(provider)?.cancel();
+    await answerCallbackQuerySafe(ctx, { text: "Cancelled" });
+    return;
+  }
+
+  if (action === "login" || action === "resume") {
+    await answerCallbackQuerySafe(ctx, { text: "Starting sign-in…" });
+    await driveLogin(
+      ctx,
+      chatId,
+      messageId,
+      provider,
+      loginBinariesFrom(config),
+    );
+    return;
+  }
+
+  await answerCallbackQuerySafe(ctx, { text: "Invalid callback data" });
+}

package/src/frontend/telegram/callbacks/index.ts

@@ -9,6 +9,8 @@
  *   - `effort`   — `effort:*`
  *   - `metrics`  — `metrics:*` (today ↔ all-time panel grain)
  *   - `model`    — `model:*` (menu / backend / browse controller)
+ *   - `auth`     — `auth:*` (backend sign-in panel, admin only)
+ *   - `whatsapp` — `whatsapp:*` (WhatsApp link panel, admin only)
  *
  * `registerCallbacks` installs one `callback_query:data` listener that
  * dispatches on the data prefix, preserving the original order and the
@@ -25,6 +27,8 @@ import { handlePulseCallback } from "./pulse.js";
 import { handleEffortCallback } from "./effort.js";
 import { handleMetricsCallback } from "./metrics.js";
 import { handleModelCallback } from "./model.js";
+import { handleAuthCallback } from "./auth.js";
+import { handleWhatsAppCallback } from "./whatsapp.js";
 
 export { answerCallbackQuerySafe } from "./shared.js";
 
@@ -70,6 +74,18 @@ export function registerCallbacks(
       return;
     }
 
+    // Handle /auth (backend CLI sign-in) callbacks.
+    if (data.startsWith("auth:")) {
+      await handleAuthCallback(ctx, data, deps);
+      return;
+    }
+
+    // Handle /whatsapp (link status / pairing) callbacks.
+    if (data.startsWith("whatsapp:")) {
+      await handleWhatsAppCallback(ctx, data);
+      return;
+    }
+
     // Forward other callbacks to the AI backend
     handleCallbackQuery(ctx, bot, config);
   });

package/src/frontend/telegram/callbacks/whatsapp.ts

@@ -0,0 +1,50 @@
+/**
+ * `whatsapp:*` callbacks — the /whatsapp panel's buttons.
+ *
+ *   whatsapp:pair     run one bounded pairing attempt
+ *   whatsapp:refresh  re-read link state and redraw the panel
+ */
+
+import type { Context } from "grammy";
+import {
+  runWhatsAppPairing,
+  whatsAppPanel,
+} from "../commands/whatsapp-pairing.js";
+import { isAuthorizedAdmin } from "../commands/state.js";
+import { answerCallbackQuerySafe } from "./shared.js";
+
+export async function handleWhatsAppCallback(
+  ctx: Context,
+  data: string,
+): Promise<void> {
+  if (!isAuthorizedAdmin(ctx)) {
+    await answerCallbackQuerySafe(ctx, { text: "Not authorized." });
+    return;
+  }
+  const [, action] = data.split(":");
+
+  if (action === "refresh") {
+    await answerCallbackQuerySafe(ctx);
+    const panel = whatsAppPanel();
+    const chatId = ctx.chat?.id;
+    const messageId = ctx.callbackQuery?.message?.message_id;
+    if (chatId === undefined || messageId === undefined) return;
+    await ctx.api
+      .editMessageText(chatId, messageId, panel.text, {
+        parse_mode: "HTML",
+        ...(panel.keyboard.length
+          ? { reply_markup: { inline_keyboard: panel.keyboard } }
+          : {}),
+      })
+      .catch(() => {});
+    return;
+  }
+
+  if (action === "pair") {
+    await answerCallbackQuerySafe(ctx, { text: "Starting pairing…" });
+    await runWhatsAppPairing(ctx);
+    return;
+  }
+
+  await answerCallbackQuerySafe(ctx, { text: "Invalid callback data" });
+}

package/src/frontend/telegram/commands/auth.ts

@@ -0,0 +1,58 @@
+/**
+ * /auth — backend login panel (admin only). Also captures the code an
+ * admin replies with during a Claude sign-in, before the message reaches
+ * the agent.
+ */
+
+import type { Bot } from "grammy";
+import type { LoginBinaries } from "../../../core/auth/login-flow.js";
+import {
+  currentAuthPanel,
+  pendingCodePrompt,
+  submitPendingCode,
+} from "../auth-panel.js";
+import { isAuthorizedAdmin, type RegisterDeps } from "./state.js";
+
+export function loginBinariesFrom(
+  config: RegisterDeps["config"],
+): LoginBinaries {
+  return {
+    claude: config.claudeBinary,
+    codex: process.env.TALON_CODEX_BINARY || config.codexBinary,
+  };
+}
+
+export function registerAuthCommand(bot: Bot): void {
+  bot.command("auth", async (ctx) => {
+    if (!isAuthorizedAdmin(ctx)) {
+      await ctx.reply("Not authorized.");
+      return;
+    }
+    const panel = await currentAuthPanel();
+    await ctx.reply(panel.text, {
+      parse_mode: "HTML",
+      reply_markup: { inline_keyboard: panel.keyboard },
+    });
+  });
+
+  // A reply to the sign-in prompt carries the pasted code. Only admins,
+  // only while a flow is waiting, only as a reply to that exact message —
+  // anything else falls through to the normal pipeline untouched.
+  bot.on("message:text", async (ctx, next) => {
+    const chatId = String(ctx.chat.id);
+    const pending = pendingCodePrompt(chatId);
+    if (
+      !pending ||
+      !isAuthorizedAdmin(ctx) ||
+      ctx.message.reply_to_message?.message_id !== pending.messageId
+    ) {
+      await next();
+      return;
+    }
+    if (submitPendingCode(chatId, ctx.message.text)) {
+      await ctx.reply("Got it — finishing sign-in…");
+      return;
+    }
+    await next();
+  });
+}

package/src/frontend/telegram/commands/definitions.ts

@@ -33,6 +33,10 @@ export const TELEGRAM_COMMANDS: ReadonlyArray<{
   { command: "reset", description: "Clear session and start fresh" },
   { command: "restart", description: "Restart the bot (admin)" },
   { command: "whatsapp", description: "WhatsApp link status / pair (admin)" },
+  {
+    command: "auth",
+    description: "Backend logins — sign in to Claude/Codex (admin)",
+  },
   { command: "usage", description: "Plan limits across every backend" },
   { command: "metrics", description: "Aggregate performance metrics" },
   {

package/src/frontend/telegram/commands/index.ts

@@ -10,9 +10,9 @@
  *   - `admin`       — /admin /metrics /doctor /dream /soul /restart /update
  *                     + the unknown-command suggester
  *
- * `registerCommands` wires every group onto the bot, preserving the original
- * registration order (info → session → settings → admin, with the
- * unknown-command catch-all registered last).
+ * `registerCommands` wires every group onto the bot in an order that ends
+ * with `admin`, because admin owns the unknown-command catch-all and that
+ * must be the last handler to see a bare /command.
  */
 
 import type { Bot } from "grammy";
@@ -23,6 +23,7 @@ import { registerSessionCommands } from "./session.js";
 import { registerSettingsCommands } from "./settings.js";
 import { registerAdminCommands } from "./admin.js";
 import { registerWhatsAppPairingCommand } from "./whatsapp-pairing.js";
+import { registerAuthCommand } from "./auth.js";
 
 export { telegramCommandMenu } from "./definitions.js";
 export { setAdminUserId } from "./state.js";
@@ -36,6 +37,11 @@ export function registerCommands(
   registerInfoCommands(bot);
   registerSessionCommands(bot, deps);
   registerSettingsCommands(bot, deps);
-  registerAdminCommands(bot, deps);
   registerWhatsAppPairingCommand(bot);
+  registerAuthCommand(bot);
+  // admin LAST: it owns the unknown-command catch-all, which must only
+  // be reached after every real command has had its chance to match.
+  // Registering anything after it makes that command look unknown
+  // ("Unknown command /whatsapp — did you mean /whatsapp?").
+  registerAdminCommands(bot, deps);
 }

package/src/frontend/telegram/commands/whatsapp-pairing.ts

@@ -1,19 +1,125 @@
 /**
  * /whatsapp — drive WhatsApp device pairing from Telegram.
  *
- * `/whatsapp` reports link state; `/whatsapp pair` runs ONE bounded
- * pairing attempt via the core pairing broker and replies with the QR as
- * a photo (plus the phone-number code when the account has one
- * configured). The human runs it when they are holding the phone —
- * pairing is never automatic, because automatic retries are how the
- * account got rate-limited into "couldn't connect device".
+ * Bare `/whatsapp` draws a status panel with a button per sub-command;
+ * `/whatsapp pair` runs ONE bounded pairing attempt via the core pairing
+ * broker and replies with the QR as a photo (plus the phone-number code
+ * when the account has one configured). The human runs it when they are
+ * holding the phone — pairing is never automatic, because automatic
+ * retries are how the account got rate-limited into "couldn't connect
+ * device".
  */
 
-import { InputFile, type Bot } from "grammy";
+import { InputFile, type Bot, type Context } from "grammy";
 import { getPairingProvider } from "../../../core/pairing-broker.js";
 import { log } from "../../../util/log.js";
 import { isAuthorizedAdmin } from "./state.js";
 
+const WHATSAPP_NOT_ENABLED =
+  'WhatsApp isn\'t enabled on this daemon — add "whatsapp" to the ' +
+  "frontend list and configure the whatsapp block, then restart.";
+
+export type WhatsAppPanel = {
+  text: string;
+  keyboard: Array<Array<{ text: string; callback_data: string }>>;
+};
+
+/**
+ * The bare-`/whatsapp` panel: link state plus one button per
+ * sub-command, so the commands are discoverable instead of folklore.
+ */
+export function whatsAppPanel(): WhatsAppPanel {
+  const provider = getPairingProvider();
+  if (!provider) {
+    return { text: WHATSAPP_NOT_ENABLED, keyboard: [] };
+  }
+  const linked = provider.isLinked();
+  const text = linked
+    ? "<b>WhatsApp</b>\n✅ Linked and connected.\n\n" +
+      "Re-link only if the phone has unlinked this device."
+    : "<b>WhatsApp</b>\n📴 Not linked.\n\n" +
+      "Tap <b>Pair device</b> when you're holding the phone — I'll reply " +
+      "with a QR to scan (WhatsApp → ⋮ → Linked devices → Link a device).";
+  return {
+    text,
+    keyboard: [
+      [
+        {
+          text: linked ? "🔗 Re-pair" : "🔗 Pair device",
+          callback_data: "whatsapp:pair",
+        },
+        { text: "🔄 Refresh", callback_data: "whatsapp:refresh" },
+      ],
+    ],
+  };
+}
+
+/**
+ * One bounded pairing attempt, shared by `/whatsapp pair` and the panel
+ * button so both paths behave identically.
+ */
+export async function runWhatsAppPairing(ctx: Context): Promise<void> {
+  const provider = getPairingProvider();
+  if (!provider) {
+    await ctx.reply(WHATSAPP_NOT_ENABLED);
+    return;
+  }
+
+  if (provider.isLinked()) {
+    await ctx.reply(
+      "WhatsApp is already linked. Unlink it on the phone first if you " +
+        "want to re-pair.",
+    );
+    return;
+  }
+
+  let attempt;
+  try {
+    attempt = await provider.begin();
+  } catch (err) {
+    await ctx.reply(
+      `Couldn't start pairing: ${err instanceof Error ? err.message : err}`,
+    );
+    return;
+  }
+
+  if (attempt.qrPng) {
+    const codeLine = attempt.code
+      ? `\nOr enter code: ${attempt.code} (Link with phone number instead)`
+      : "";
+    await ctx.replyWithPhoto(new InputFile(attempt.qrPng, "whatsapp-qr.png"), {
+      caption:
+        "Scan within ~2 minutes:\n" +
+        "WhatsApp → ⋮ → Linked devices → Link a device" +
+        codeLine,
+    });
+  } else {
+    await ctx.reply(
+      "No QR came back — WhatsApp may still be rate-limiting. Try later.",
+    );
+  }
+
+  const outcome = await attempt.result;
+  if (outcome.ok) {
+    log("bot", `WhatsApp paired via /whatsapp pair (${outcome.identity})`);
+    await ctx.reply(
+      `✅ Linked as ${outcome.identity}. WhatsApp is connecting now.`,
+    );
+  } else if (outcome.reason === "expired") {
+    await ctx.reply(
+      "⌛ That window expired without a successful scan. Run " +
+        "/whatsapp pair again when you're ready — if the phone says " +
+        '"couldn\'t connect device", WhatsApp is still rate-limiting; ' +
+        "wait an hour and try once more.",
+    );
+  } else if (outcome.reason !== "cancelled") {
+    await ctx.reply(
+      `❌ Pairing failed${outcome.detail ? `: ${outcome.detail}` : ""}. ` +
+        "Run /whatsapp pair to try again.",
+    );
+  }
+}
+
 export function registerWhatsAppPairingCommand(bot: Bot): void {
   bot.command("whatsapp", async (ctx) => {
     if (!isAuthorizedAdmin(ctx)) {
@@ -21,82 +127,18 @@ export function registerWhatsAppPairingCommand(bot: Bot): void {
       return;
     }
 
-    const provider = getPairingProvider();
-    if (!provider) {
-      await ctx.reply(
-        'WhatsApp isn\'t enabled on this daemon — add "whatsapp" to the ' +
-          "frontend list and configure the whatsapp block, then restart.",
-      );
-      return;
-    }
-
     const arg = (ctx.match ?? "").trim().toLowerCase();
     if (arg !== "pair") {
-      await ctx.reply(
-        provider.isLinked()
-          ? "✅ WhatsApp is linked and connected.\nSend /whatsapp pair to re-link."
-          : "📴 WhatsApp is not linked.\nSend /whatsapp pair when you're " +
-              "holding the phone — I'll reply with a QR to scan " +
-              "(WhatsApp → Linked devices → Link a device).",
-      );
+      const panel = whatsAppPanel();
+      await ctx.reply(panel.text, {
+        parse_mode: "HTML",
+        ...(panel.keyboard.length
+          ? { reply_markup: { inline_keyboard: panel.keyboard } }
+          : {}),
+      });
       return;
     }
 
-    if (provider.isLinked()) {
-      await ctx.reply(
-        "WhatsApp is already linked. Unlink it on the phone first if you " +
-          "want to re-pair.",
-      );
-      return;
-    }
-
-    let attempt;
-    try {
-      attempt = await provider.begin();
-    } catch (err) {
-      await ctx.reply(
-        `Couldn't start pairing: ${err instanceof Error ? err.message : err}`,
-      );
-      return;
-    }
-
-    if (attempt.qrPng) {
-      const codeLine = attempt.code
-        ? `\nOr enter code: ${attempt.code} (Link with phone number instead)`
-        : "";
-      await ctx.replyWithPhoto(
-        new InputFile(attempt.qrPng, "whatsapp-qr.png"),
-        {
-          caption:
-            "Scan within ~2 minutes:\n" +
-            "WhatsApp → ⋮ → Linked devices → Link a device" +
-            codeLine,
-        },
-      );
-    } else {
-      await ctx.reply(
-        "No QR came back — WhatsApp may still be rate-limiting. Try later.",
-      );
-    }
-
-    const outcome = await attempt.result;
-    if (outcome.ok) {
-      log("bot", `WhatsApp paired via /whatsapp pair (${outcome.identity})`);
-      await ctx.reply(
-        `✅ Linked as ${outcome.identity}. WhatsApp is connecting now.`,
-      );
-    } else if (outcome.reason === "expired") {
-      await ctx.reply(
-        "⌛ That window expired without a successful scan. Run " +
-          "/whatsapp pair again when you're ready — if the phone says " +
-          '"couldn\'t connect device", WhatsApp is still rate-limiting; ' +
-          "wait an hour and try once more.",
-      );
-    } else if (outcome.reason !== "cancelled") {
-      await ctx.reply(
-        `❌ Pairing failed${outcome.detail ? `: ${outcome.detail}` : ""}. ` +
-          "Run /whatsapp pair to try again.",
-      );
-    }
+    await runWhatsAppPairing(ctx);
   });
 }