grok-telegram-bot 2.2.3 → 2.3.0

package/.env.example

@@ -132,9 +132,12 @@ QUIET_NOTIFICATIONS=true
 # LOG_DIR=
 # LOG_FILE=
 
-# ── Voice messages (speech-to-text) ──────────────────────────────────────────
-# Any OpenAI/Whisper-compatible transcription endpoint. xAI offers one too:
-# STT_API_URL=https://api.x.ai/v1
+# ── Voice messages (optional) ────────────────────────────────────────────────
+# Voice is ONLY available when STT is configured. Grok Build CLI over ACP does
+# not accept audio content blocks, so without STT the bot replies that voice
+# isn't configured. Use any OpenAI/Whisper-compatible transcription endpoint
+# (including xAI STT if your gateway exposes /audio/transcriptions):
+# STT_API_URL=https://api.openai.com/v1
 # STT_API_KEY=
 # STT_MODEL=whisper-1
-# STT_LANGUAGE=
+# STT_LANGUAGE=                # blank = auto-detect

package/CHANGELOG.md

@@ -9,6 +9,54 @@ The latest section is published verbatim as the GitHub Release notes by
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-07-17
+
+### Added
+
+- **⚡ Instant project switch.** Choosing a project no longer waits on ACP
+  `session/new`. The bot switches cwd immediately and creates the live session
+  lazily on the first message. Reuses an existing controlled runtime for the
+  same path when available.
+- **🖼 Image-output prompt rules.** When agent image return is enabled, prompts
+  include rules to keep generated files in the Grok session media folder
+  (`images/` / `assets/`) or project `images/`, and to report absolute paths.
+
+### Fixed
+
+- **🖼 Agent images as Telegram files.** Generated images are sent with
+  `sendDocument` (downloadable file) instead of compressed `sendPhoto`. Discovery
+  now scans Grok session `images/` **and** `assets/`, plus project `images/` and
+  tool/text paths (Imagine was writing under `images/` while the bot only scanned
+  `assets/`).
+- **⏱ Stale callback queries.** Callback answers are safe/idempotent; expired
+  Telegram query IDs no longer spam ERROR logs. Handlers answer before slow ACP
+  work (stop / model / agent / project open).
+- **🎙 Voice requires STT again.** Voice / audio / video notes only work when
+  `STT_API_URL` is set (optional `STT_API_KEY`). Without STT the bot replies that
+  voice isn't configured — the CLI cannot accept ACP audio blocks.
+- **🔄 Non-blocking session handoff.** Backgrounding a session no longer waits
+  on streamer finalize / `prepare()` mid-switch, so the bot stays responsive.
+
+## [2.2.4] - 2026-07-16
+
+### Fixed
+
+- **🚫 Rotate immediately on Grok access denial.** API `403 Forbidden` / `Access
+  denied` responses now bypass same-account retry backoff, mark the failed
+  login with `⚠️`, and rotate to the next eligible saved account. If the active
+  host login was not already saved (for example after an external sign-in or
+  token refresh), it is captured first so the warning is visible and persists.
+- **🔐 Isolated Grok Telegram identity.** The Grok bot now takes its Telegram
+  token from its own instance `.env` before considering an inherited process
+  environment value. This prevents a machine-wide token for a sibling bot from
+  making Grok poll as Codex/Kiro/OpenCode and causing Telegram conflicts.
+- **⚠️ Persistent account warnings.** Account access/quota failures are shown
+  in `/accounts`, excluded from later automatic rotations, and can be manually
+  re-enabled after the account is repaired.
+- **🛟 No false success for silent ACP turns.** A Grok ACP completion with no
+  text, thought, or tool update is now treated as a recoverable agent failure
+  instead of reporting `Done · no text output`.
+
 ## [2.2.3] - 2026-07-13
 
 ### Fixed
@@ -713,6 +761,9 @@ from a single chat and switch between them, on a redesigned, compact menu.
   diffs, MarkdownV2 rendering, scheduled tasks, multi-image prompts, and a
   cross-platform 24/7 background service.
 
+[2.3.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.3.0
+[2.2.4]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.2.4
+[2.2.3]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.2.3
 [2.2.2]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.2.2
 [2.2.1]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.2.1
 [2.2.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.2.0

package/README.md

@@ -275,16 +275,25 @@ caption. The bot downloads them and attaches them all to the prompt as image
 content blocks, so the agent can analyze them together. Images sent while Grok
 is busy are queued with your next turn.
 
-**Images come back too:** when the agent produces images during a turn (e.g.
-takes screenshots while testing an app), the bot detects the freshly-written
-files and sends them back to Telegram automatically (`SEND_AGENT_IMAGES`).
+**Images come back too:** when the agent produces images during a turn — Imagine
+`image_gen` / `image_edit` (written under
+`~/.grok/sessions/<cwd>/<session>/images/` and `…/assets/`), screenshots, or
+files under `<project>/images/` — the bot detects the freshly-written files and
+sends them back to Telegram as **downloadable documents** (`SEND_AGENT_IMAGES`,
+default on). Prompts also include image-output rules so the agent keeps gens in
+the session media folder and reports absolute paths.
 
 ## 🎙 Sending voice
 
-Send a voice note (or audio file) and the bot transcribes it and runs it as a
-prompt. Configure any OpenAI/Whisper-compatible endpoint via `STT_API_URL` in
-`.env`; leave `STT_LANGUAGE` blank for automatic detection (English, Russian,
-Romanian/Moldovan, and ~100 more).
+Send a voice note, audio file, or video note and the bot runs it as a prompt
+**only when STT is configured**.
+
+Set any OpenAI/Whisper-compatible endpoint via `STT_API_URL` (and `STT_API_KEY`
+if needed). The bot transcribes, shows the quote, and submits plain text.
+Without `STT_API_URL`, voice is rejected with a short “not configured” message
+— Grok Build CLI rejects ACP `audio` content blocks, so raw audio cannot be
+heard by the agent. Leave `STT_LANGUAGE` blank for automatic detection
+(English, Russian, Romanian/Moldovan, and ~100 more).
 
 ## 📎 Sending files
 
@@ -530,7 +539,8 @@ user. See [SECURITY.md](./SECURITY.md) for the full model.
 - [x] Multi-image prompts (albums)
 - [x] Combined, throttled output (anti-spam)
 - [x] 24/7 cross-platform background service
-- [x] Voice messages → speech-to-text → prompt (multi-language)
+- [x] Voice messages → STT (`STT_API_URL`) → text prompt (disabled without STT)
+- [x] Agent-generated images → Telegram document files (session `images/`/`assets/`)
 - [x] Context-usage % in the status panel
 - [x] Inline approvals — approve/deny risky tools from buttons (non trust-all mode)
 - [x] Session auto-approve + pinned permission prompts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-telegram-bot",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "description": "Control the official Grok Build CLI from Telegram over the Agent Client Protocol (ACP). Sign in with your xAI account, switch projects, resume sessions, stream responses with diffs, queue follow-ups, manage multiple sign-ins, and run 24/7 as a cross-platform background service.",
   "type": "module",
   "main": "src/index.ts",

package/src/app/accounts.ts

@@ -32,6 +32,11 @@ export interface StoredAccount {
   startUrl?: string;
   accountType?: string;
   region?: string;
+  /** Excluded from automatic rotation after an account-specific quota/billing failure. */
+  warning?: {
+    reason: string;
+    markedAt: string;
+  };
 }
 
 interface AccountsData {
@@ -171,6 +176,9 @@ export class AccountManager {
       email: (email && email.includes("@") ? email : undefined) || existing?.email,
       startUrl: (email && email.includes("@") ? email : undefined) || existing?.email || existing?.startUrl,
       savedAt: new Date().toISOString(),
+      // Automatic pre-rotation snapshots must not silently re-enable an
+      // account that was quarantined after a quota/billing failure.
+      warning: existing?.warning,
     };
     this.store.update((d) => {
       const idx = d.accounts.findIndex((a) => a.id === id);
@@ -227,6 +235,33 @@ export class AccountManager {
     return updated;
   }
 
+  /** Mark an account as unsuitable for future automatic rotations. */
+  markWarning(id: string, reason: string): StoredAccount | undefined {
+    let updated: StoredAccount | undefined;
+    this.store.update((d) => {
+      const account = d.accounts.find((a) => a.id === id);
+      if (account) {
+        account.warning = { reason, markedAt: new Date().toISOString() };
+        updated = account;
+      }
+    });
+    if (updated) log.warn(`marked account ${updated.label} with rotation warning: ${reason}`);
+    return updated;
+  }
+
+  /** Re-allow a manually restored account to participate in auto-rotation. */
+  clearWarning(id: string): StoredAccount | undefined {
+    let updated: StoredAccount | undefined;
+    this.store.update((d) => {
+      const account = d.accounts.find((a) => a.id === id);
+      if (account?.warning) {
+        delete account.warning;
+        updated = account;
+      }
+    });
+    return updated;
+  }
+
   async forget(id: string): Promise<boolean> {
     const existed = !!this.get(id);
     await rm(this.snapshotPath(id), { force: true }).catch(() => {});

package/src/app/stt.ts

@@ -1,9 +1,12 @@
 /**
  * Speech-to-text via any OpenAI/Whisper-compatible endpoint.
  *
+ * Required for Telegram voice / audio / video notes: Grok Build CLI over ACP
+ * does not accept audio content blocks, so without STT_API_URL the bot rejects
+ * voice with a "not configured" message instead of attaching unusable audio.
+ *
  * Language handling: when STT_LANGUAGE is unset, Whisper auto-detects the
- * spoken language (covers English, Russian, Romanian/Moldovan, and ~100 more),
- * so multilingual voice notes work out of the box.
+ * spoken language (covers English, Russian, Romanian/Moldovan, and ~100 more).
  */
 import { createLogger } from "../logger.js";
 

package/src/app/types.ts

@@ -37,10 +37,24 @@ export interface PromptImage {
   mimeType: string;
 }
 
-/** A unit of work submitted to the agent: text plus optional images. */
+/**
+ * A file the agent can open (ACP `resource_link`). Used for voice notes and
+ * other binaries when we cannot embed the media as a first-class content type
+ * (Grok CLI currently rejects ACP `audio` blocks).
+ */
+export interface PromptResourceLink {
+  uri: string;
+  name: string;
+  mimeType?: string;
+  size?: number;
+}
+
+/** A unit of work submitted to the agent: text plus optional images / links. */
 export interface PromptInput {
   text: string;
   images: PromptImage[];
+  /** Optional file references (voice notes, binaries). */
+  resourceLinks?: PromptResourceLink[];
   /** Telegram message id of the prompt, so the reply threads to it. */
   replyTo?: number;
   /**
@@ -52,5 +66,5 @@ export interface PromptInput {
 }
 
 export function textPrompt(text: string, replyTo?: number, quotedText?: string): PromptInput {
-  return { text, images: [], replyTo, quotedText };
+  return { text, images: [], resourceLinks: [], replyTo, quotedText };
 }

package/src/bot/account-rotator.ts

@@ -37,6 +37,8 @@ export interface AccountRotator {
   targets(): Promise<RotationTarget[]>;
   /** Make a saved account active (swap auth.json + re-bind). Throws on error. */
   activate(id: string): Promise<void>;
+  /** Quarantine an account after an account-specific failure. Undefined means active. */
+  markFailed(id: string | undefined, reason: string): Promise<void>;
 }
 
 export class AccountRotatorImpl implements AccountRotator {
@@ -52,7 +54,26 @@ export class AccountRotatorImpl implements AccountRotator {
   async targets(): Promise<RotationTarget[]> {
     const list = this.accounts.list();
     const activeId = this.accounts.activeAccountId();
-    return list.filter((a) => a.id !== activeId).map((a) => ({ id: a.id, label: a.label }));
+    return list
+      .filter((a) => a.id !== activeId && !a.warning)
+      .map((a) => ({ id: a.id, label: a.label }));
+  }
+
+  async markFailed(id: string | undefined, reason: string): Promise<void> {
+    let accountId = id ?? this.accounts.activeAccountId();
+    if (!accountId) {
+      // The host may have been signed in or had its token refreshed outside the
+      // bot, so no saved snapshot matches yet. Capture it before marking; this
+      // guarantees the actual failed login appears with a warning in /accounts
+      // and is excluded from the target list below.
+      try {
+        accountId = (await this.accounts.captureCurrent()).id;
+      } catch (error) {
+        log.warn("could not capture active account for rotation warning:", (error as Error).message);
+        return;
+      }
+    }
+    this.accounts.markWarning(accountId, reason);
   }
 
   /**

package/src/bot/bot.ts

@@ -20,6 +20,7 @@ import { TaskRunner } from "../tasks/runner.js";
 import { Scheduler } from "../tasks/scheduler.js";
 import { TaskStore } from "../tasks/store.js";
 import { createAuthMiddleware } from "./auth.js";
+import { isStaleCallbackError, safeCallbackMiddleware } from "./callback.js";
 import { COMMANDS } from "./commands.js";
 import { type BotDeps, MenuCache } from "./deps.js";
 import { registerControl } from "./handlers/control.js";
@@ -139,6 +140,9 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
   bot.on("message:pinned_message", (ctx) => void ctx.deleteMessage().catch(() => {}));
 
   bot.use(createAuthMiddleware(cfg));
+  // Answer callback queries safely: never throw on stale IDs, auto-answer if a
+  // handler forgets (prevents the loading spinner + unhandled 400 noise).
+  bot.use(safeCallbackMiddleware());
 
   // Keep history clean: after handling, delete the user's command (/…) and
   // persistent-bar button taps. Plain prompts and wizard input are kept.
@@ -188,6 +192,12 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
   registerMessages(bot, deps); // catch-all text prompt — keep last
 
   bot.catch((err) => {
+    // Stale callback answers are expected when the bot was busy past Telegram's
+    // ~timeout — middleware already swallows most of them; keep noise out of ERROR.
+    if (isStaleCallbackError(err.error)) {
+      log.debug("stale callback query:", err.error instanceof Error ? err.error.message : err.error);
+      return;
+    }
     log.error("unhandled bot error:", err.error instanceof Error ? err.error.message : err.error);
   });
 

package/src/bot/callback.ts

@@ -0,0 +1,74 @@
+/**
+ * Callback-query helpers — Telegram requires answerCallbackQuery within a few
+ * seconds of the tap. Stale/expired IDs throw 400; without a catch those become
+ * unhandled bot errors and the client spinner never clears.
+ */
+import { type Context, type MiddlewareFn, GrammyError } from "grammy";
+
+/** True when Telegram rejected the answer because the query expired or is invalid. */
+export function isStaleCallbackError(err: unknown): boolean {
+  if (!(err instanceof GrammyError)) return false;
+  if (err.error_code !== 400 && err.error_code !== 440) return false;
+  return /query is too old|query ID is invalid|response timeout expired/i.test(err.description);
+}
+
+type AnswerParams = Parameters<Context["answerCallbackQuery"]>[0];
+
+/**
+ * Idempotent, non-throwing answer for a single handler (when middleware is not
+ * in play). Safe to call after slow work — stale queries are swallowed.
+ */
+export async function safeAnswerCallbackQuery(ctx: Context, params?: AnswerParams): Promise<boolean> {
+  try {
+    await ctx.answerCallbackQuery(params);
+    return true;
+  } catch (err) {
+    if (isStaleCallbackError(err)) return false;
+    throw err;
+  }
+}
+
+/**
+ * Patch every callback update so:
+ *   1. answerCallbackQuery never throws on stale/expired query IDs,
+ *   2. double-answers are no-ops,
+ *   3. if a handler forgets to answer, we answer once in `finally` so the
+ *      client spinner always stops (best-effort; may already be too late).
+ */
+export function safeCallbackMiddleware(): MiddlewareFn<Context> {
+  return async (ctx, next) => {
+    if (!ctx.callbackQuery) {
+      await next();
+      return;
+    }
+
+    let answered = false;
+    const original = ctx.answerCallbackQuery.bind(ctx);
+
+    ctx.answerCallbackQuery = (async (params?: AnswerParams) => {
+      if (answered) return true;
+      answered = true;
+      try {
+        return await original(params);
+      } catch (err) {
+        if (isStaleCallbackError(err)) return true;
+        // Leave answered=true so a retry storm can't spam Telegram; surface
+        // unexpected errors to bot.catch for visibility.
+        throw err;
+      }
+    }) as Context["answerCallbackQuery"];
+
+    try {
+      await next();
+    } finally {
+      if (!answered) {
+        try {
+          await original();
+        } catch {
+          /* stale or network — spinner already gone */
+        }
+        answered = true;
+      }
+    }
+  };
+}

package/src/bot/chat-controller.ts

@@ -79,20 +79,69 @@ export class ChatController {
     }));
   }
 
-  /** Start a brand-new session and bring it to the foreground. */
+  /** Start a brand-new session and bring it to the foreground.
+   *  Always binds a live ACP session (`session/new`) — use {@link switchProject}
+   *  when you only need to change the working directory (instant). */
   async addNew(cwd: string, projectName?: string): Promise<SessionRuntime> {
     this.ensureRestored();
     const prevFg = this.fg;
     const rt = this.create({ cwd, projectName });
     this.runtimes.push(rt);
     this.fg = rt;
-    await this.background(prevFg);
+    // Fire-and-forget: finalizing the previous streamer must not block the new
+    // session bind (that was a major source of "bot freezes on switch").
+    void this.background(prevFg);
     await rt.startNewSession(cwd, projectName);
     this.markSeen(rt);
     this.persist();
     return rt;
   }
 
+  /**
+   * Switch the chat to a project directory **without** waiting on ACP.
+   * - Reuses an existing controlled runtime for the same path when possible.
+   * - Does **not** call `session/new` — the live session is created lazily on
+   *   the first prompt / prepare (via `ensureSession`).
+   * This keeps the project picker responsive even while another turn is running.
+   */
+  async switchProject(cwd: string, projectName?: string): Promise<SessionRuntime> {
+    this.ensureRestored();
+    const key = normPath(cwd);
+    const same = this.runtimes.filter((r) => normPath(r.cwd) === key);
+    // Prefer the current FG if it already points here, else the most recent match.
+    const existing = same.find((r) => r === this.fg) ?? same.at(-1);
+
+    if (existing) {
+      if (projectName) existing.projectName = projectName;
+      if (existing === this.fg) {
+        this.persist();
+        return existing;
+      }
+      if (existing.sessionId) {
+        // Fast path: switchTo no longer awaits ACP re-bind.
+        const sw = await this.switchTo(existing.sessionId);
+        return sw?.rt ?? existing;
+      }
+      void this.background(this.fg);
+      this.fg = existing;
+      await existing.setForeground(true);
+      this.persist();
+      return existing;
+    }
+
+    const prevFg = this.fg;
+    const rt = this.create({ cwd, projectName });
+    this.runtimes.push(rt);
+    this.fg = rt;
+    void this.background(prevFg);
+    // Drop other never-used project placeholders (no session yet) so rapid
+    // project browsing can't accumulate infinite idle runtimes/listeners.
+    this.pruneUnusedPlaceholders(rt);
+    // No startNewSession — sessionId stays undefined until the first message.
+    this.persist();
+    return rt;
+  }
+
   /**
    * Connect to a session with resume-or-fork semantics (used by /sessions),
    * adding it as a controlled session and bringing it to the foreground.
@@ -114,7 +163,7 @@ export class ChatController {
     const rt = this.create({ cwd, projectName, sessionId });
     this.runtimes.push(rt);
     this.fg = rt;
-    await this.background(prevFg);
+    void this.background(prevFg);
     const result = await rt.attach(sessionId, cwd, projectName, priorEntries);
     this.markSeen(rt);
     this.persist();
@@ -131,8 +180,8 @@ export class ChatController {
     const rt = this.create({ cwd, projectName, sessionId });
     this.runtimes.push(rt);
     this.fg = rt;
-    await this.background(prevFg);
-    await rt.prepare().catch(() => {});
+    void this.background(prevFg);
+    // Lazy re-bind on first prompt (rebindPending); don't block the resume UI.
     const path = this.store.jsonlPath(sessionId);
     const unread = readHistory(path, 12);
     this.lastRead.set(sessionId, jsonlSize(path));
@@ -148,10 +197,12 @@ export class ChatController {
     if (rt === this.fg) {
       return { rt, sessionId, projectName: rt.projectName, busy: rt.isBusy, unread: [], firstView: false, alreadyForeground: true };
     }
-    await this.background(this.fg);
+    void this.background(this.fg);
     this.fg = rt;
     await rt.setForeground(true);
-    await rt.prepare().catch(() => {});
+    // Do NOT await prepare()/loadSession here — re-bind is lazy on the next
+    // prompt (rebindPending). Awaiting ACP mid-switch freezes the bot when the
+    // agent is busy with another turn.
 
     const path = this.store.jsonlPath(sessionId);
     const seen = this.lastRead.get(sessionId);
@@ -222,8 +273,23 @@ export class ChatController {
       seen.add(cs.sessionId);
       this.runtimes.push(this.create({ cwd: cs.projectPath, projectName: cs.projectName, sessionId: cs.sessionId }));
     }
+    // Lazy project switches persist projectPath without a sessionId. If the
+    // saved project is not among controlled sessions, recreate an unbound FG
+    // so a restart lands on the project the user last chose.
+    if (s.projectPath) {
+      const key = normPath(s.projectPath);
+      const hasProject = this.runtimes.some((r) => normPath(r.cwd) === key);
+      if (!hasProject) {
+        this.runtimes.push(this.create({ cwd: s.projectPath, projectName: s.projectName }));
+      }
+    }
     if (this.runtimes.length > 0) {
-      const fg = this.runtimes.find((r) => r.sessionId === s.foregroundSessionId) ?? this.runtimes[0]!;
+      let fg = this.runtimes.find((r) => r.sessionId && r.sessionId === s.foregroundSessionId);
+      if (!fg && s.projectPath) {
+        const key = normPath(s.projectPath);
+        fg = this.runtimes.find((r) => normPath(r.cwd) === key);
+      }
+      fg = fg ?? this.runtimes[0]!;
       for (const r of this.runtimes) void r.setForeground(r === fg);
       this.fg = fg;
     }
@@ -284,6 +350,17 @@ export class ChatController {
     await rt.setForeground(false);
   }
 
+  /** Remove idle runtimes that never bound an ACP session (lazy project taps). */
+  private pruneUnusedPlaceholders(keep: SessionRuntime): void {
+    for (let i = this.runtimes.length - 1; i >= 0; i--) {
+      const r = this.runtimes[i]!;
+      if (r === keep || r === this.fg) continue;
+      if (r.sessionId || r.isBusy) continue;
+      r.dispose();
+      this.runtimes.splice(i, 1);
+    }
+  }
+
   private markSeen(rt: SessionRuntime): void {
     if (rt.sessionId) this.lastRead.set(rt.sessionId, jsonlSize(this.store.jsonlPath(rt.sessionId)));
   }
@@ -315,3 +392,8 @@ export class ChatController {
     });
   }
 }
+
+/** Path key for project matching (case / separators / trailing slash). */
+function normPath(p: string): string {
+  return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}

package/src/bot/handlers/accounts.ts

@@ -17,7 +17,7 @@ import type { BotDeps } from "../deps.js";
 const log = createLogger("accounts");
 
 function accountLine(a: StoredAccount, active: boolean): string {
-  const mark = active ? "\u2705 " : "\u{1F464} ";
+  const mark = a.warning ? "\u26A0\uFE0F " : active ? "\u2705 " : "\u{1F464} ";
   return `${mark}${a.label}`;
 }
 
@@ -51,15 +51,18 @@ async function view(deps: BotDeps, note?: string): Promise<{ text: string; keybo
   if (list.length === 0) {
     lines.push("No saved accounts yet.", "", "Save the current login below, or sign in via /reauth.");
   } else {
-    for (const a of list) lines.push(accountLine(a, a.id === active));
+    for (const a of list) {
+      lines.push(accountLine(a, a.id === active));
+      if (a.warning) lines.push("  \u2514 Skipped by auto-rotate after an account access or quota error.");
+    }
   }
   const rotate = deps.accounts.autoRotateEnabled();
   lines.push(
     "",
     `\u{1F501} Auto-rotate on errors: ${rotate ? "ON" : "OFF"}`,
     rotate
-      ? "  \u2514 On give-up / 402 balance exhausted: stop CLI, swap auth, restart, retry each account once."
-      : "  \u2514 Turns stay on the active account (402 balance exhausted stops immediately).",
+      ? "  \u2514 On account access/quota errors: stop CLI, swap auth, restart, retry each eligible account once. \u26A0\uFE0F accounts are skipped."
+      : "  \u2514 Turns stay on the active account (account access/quota errors stop immediately).",
   );
   if (note) lines.push("", note);
 
@@ -70,6 +73,7 @@ async function view(deps: BotDeps, note?: string): Promise<{ text: string; keybo
       .text("\u270F\uFE0F", `acct:rename:${a.id}`)
       .text("\u{1F5D1}", `acct:del:${a.id}`)
       .row();
+    if (a.warning) kb.text(`\u26A0\uFE0F Re-enable ${trim(a.label)}`, `acct:clearwarning:${a.id}`).row();
   }
   kb.text("\u{1F4BE} Save current login", "acct:save").text("\u270F\uFE0F Save as\u2026", "acct:saveas").row();
   kb.text("\u{1F4E5} Import existing", "acct:import").text("\u{1F511} Sign in\u2026", "acct:login").row();
@@ -161,6 +165,13 @@ export function registerAccounts(bot: Bot, deps: BotDeps): void {
     await promptName(ctx, "rename", ctx.match![1]!);
   });
 
+  bot.callbackQuery(/^acct:clearwarning:(.+)$/, async (ctx) => {
+    const id = ctx.match![1]!;
+    const account = deps.accounts.clearWarning(id);
+    await ctx.answerCallbackQuery({ text: account ? "Account re-enabled for auto-rotate" : "No warning to clear" });
+    await rerender(ctx, deps, account ? `\u2705 ${account.label} can be used by auto-rotate again.` : undefined);
+  });
+
   bot.callbackQuery("acct:close", async (ctx) => {
     await ctx.answerCallbackQuery();
     await deps.ephemeral.drop(ctx);

package/src/bot/handlers/menu.ts

@@ -56,8 +56,10 @@ export function registerMenu(bot: Bot, deps: BotDeps): void {
   bot.callbackQuery(/^agent:set:(\d+)$/, async (ctx) => {
     const mode = deps.acp.availableModes[Number(ctx.match![1])];
     if (!mode) return void ctx.answerCallbackQuery({ text: "Expired, tap Agent again." });
+    // Answer before ACP so a slow setMode never expires the callback query.
+    await ctx.answerCallbackQuery({ text: `\u{1F916} Agent: ${mode.name}` });
     await deps.registry.get(ctx.chat!.id).setAgentPref(mode.id);
-    await confirm(ctx, deps, `\u{1F916} Agent: ${mode.name}`);
+    await confirmUi(ctx, deps);
   });
 
   // ── Reasoning ──────────────────────────────────────────────────────────────
@@ -71,12 +73,17 @@ export function registerMenu(bot: Bot, deps: BotDeps): void {
   bot.callbackQuery(/^model:set:(\d+)$/, async (ctx) => {
     const entry = deps.acp.availableModels[Number(ctx.match![1])];
     if (!entry) return void ctx.answerCallbackQuery({ text: "Expired, tap Model again." });
+    await ctx.answerCallbackQuery({ text: `\u{1F9E9} Model: ${entry.name}` });
     const res = await deps.registry.get(ctx.chat!.id).setModelPref(entry.modelId);
-    await confirm(ctx, deps, res.ok ? `\u{1F9E9} Model: ${entry.name}` : `\u26A0\uFE0F Model set failed: ${res.error}`);
+    if (!res.ok) {
+      await ctx.reply(`\u26A0\uFE0F Model set failed: ${res.error}`).catch(() => {});
+    }
+    await confirmUi(ctx, deps);
   });
   bot.callbackQuery("model:clear", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "\u{1F9E9} Model: default" });
     await deps.registry.get(ctx.chat!.id).setModelPref("");
-    await confirm(ctx, deps, "\u{1F9E9} Model: default");
+    await confirmUi(ctx, deps);
   });
 }
 
@@ -143,15 +150,25 @@ async function dispatchMenu(ctx: Context, deps: BotDeps, action: string): Promis
       } catch (e) {
         return void ctx.reply(`\u274C ${(e as Error).message}`);
       }
-    case "stop":
-      return void ctx.answerCallbackQuery({ text: (await rt.cancel()) ? "Cancelling\u2026" : "Nothing is running" });
+    case "stop": {
+      // Answer first so a slow cancel never times out the callback query.
+      await ctx.answerCallbackQuery({ text: rt.isBusy ? "Cancelling\u2026" : "Nothing is running" });
+      if (rt.isBusy) await rt.cancel();
+      return;
+    }
     default:
       return void ctx.answerCallbackQuery();
   }
 }
 
 async function confirm(ctx: Context, deps: BotDeps, text: string): Promise<void> {
+  // Toast first (callback must be answered within ~seconds), then UI updates.
   await ctx.answerCallbackQuery({ text });
+  await confirmUi(ctx, deps);
+}
+
+/** Refresh status + reopen the main menu after a preference change. */
+async function confirmUi(ctx: Context, deps: BotDeps): Promise<void> {
   try {
     await ctx.deleteMessage();
   } catch {