grok-telegram-bot 2.2.1 → 2.2.3

package/CHANGELOG.md

@@ -9,6 +9,42 @@ The latest section is published verbatim as the GitHub Release notes by
 
 ## [Unreleased]
 
+## [2.2.3] - 2026-07-13
+
+### Fixed
+
+- **💳 Instant account rotate on 402 balance exhausted.** Grok Build
+  `Payment Required` / `usage balance exhausted` errors (usually wrapped as ACP
+  Internal error `[-32603]`) are no longer treated as transient. Same-account
+  backoff retries are skipped. With **auto-rotate ON**, the bot immediately:
+  stops the Grok CLI → swaps `~/.grok/auth.json` → restarts the CLI with
+  headless `cached_token` auth → opens a fresh session → retries the same
+  prompt. If that account fails, it switches to the next saved account (one
+  pass). If all accounts fail (or auto-rotate is OFF), the turn stops with a
+  clear error. Telegram shows
+  `Account switched to … because of: …` plus a CLI-restart notice.
+
+## [2.2.2] - 2026-07-12
+
+Patch release that hardens multi-account identity and documents the full **2.2.x**
+batch (headless rotation, session auto-approve, pinned permission prompts).
+
+### Fixed
+
+- **📧 Real account emails from `auth.json`.** Modern Grok access tokens often
+  omit the `email` claim; the bot now prefers `email` / `first_name` /
+  `last_name` written on the auth entry by `grok login`, then falls back to JWT
+  claims. `/accounts` and `/usage` show the host login correctly again.
+- **🪪 Active account = live token hash.** The marked `activeId` is no longer
+  trusted when the host login changed outside the menu (`grok login` / `/reauth`).
+  Saving never overwrites a different saved account; mismatch is shown in the
+  `/accounts` UI (“Host Grok login” vs saved).
+
+### Docs
+
+- README: headless account switch, device-code `/reauth`, auto-approve + pinned
+  permission prompts, `AUTO_APPROVE_PERMISSIONS`.
+
 ## [2.2.1] - 2026-07-12
 
 ### Fixed
@@ -677,6 +713,7 @@ 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.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
 [2.1.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.1.0

package/README.md

@@ -38,9 +38,10 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | 🧩 **MCP control** | `/mcp` lists MCP servers, **health-checks** them (which connected / failed and why), and **enables/disables** them — then restarts the agent to apply. |
 | 👥 **Subagent visibility** | When Grok delegates to subagents and waits on them, you see each one **start / work / finish** plus a live `🤖 N running` summary — and subagent permission prompts route to your chat. |
 | 📈 **Task progress bar** | The agent appends a `{progress: N%}` marker; the bot hides it and shows a **green 0–100% loading bar** on the live message, in the status panel, and on session cards (`SHOW_PROGRESS`). |
-| 🔐 **Sign in from chat** | `/reauth` signs you in without a terminal — **🔑 Sign in** runs `grok login` (any verification link/code streams to your chat), or **📥 Import** an existing on-host login; the agent restarts under the new identity. |
-| 👥 **Multiple accounts** | `/accounts` saves several Grok **sign-ins** (custom names) and switches between them in a tap — copies that login back over `~/.grok/auth.json` and restarts so sessions re-bind under the new account. |
-| 🔁 **Auto-rotate on give-up** | When a turn exhausts its retries, optionally cycle through your other saved accounts once and retry on each — the first that works wins (toggle in `/accounts`). |
+| 🔐 **Sign in from chat** | `/reauth` signs you in without a terminal — **🔑 Sign in** runs headless `grok login --device-auth` (link/code streams to your chat, no host browser), or **📥 Import** an existing on-host login; the agent restarts under the new identity. |
+| 👥 **Multiple accounts** | `/accounts` saves several Grok **sign-ins** (custom names) and switches between them in a tap — **stops the agent → replaces `~/.grok/auth.json` → restarts headlessly** (never opens a browser). |
+| 🔁 **Auto-rotate on give-up** | When a turn exhausts its retries (or hits **402 balance exhausted** with no same-account retry), optionally cycle through your other saved accounts once: stop CLI → swap `auth.json` → restart + re-auth → retry. First that works wins (toggle in `/accounts`). |
+| ✅ **Auto-approve tools** | By default, ACP permission prompts are auto-approved for the **session** (`AUTO_APPROVE_PERMISSIONS`). Turn both that and `GROK_TRUST_ALL_TOOLS` off for interactive Approve/Deny — those prompts are **pinned** until you act. |
 | 🪙 **Credits & usage** | The `✅ Done` line and `/usage` show credits used (when Grok reports them), turns this session, and account info. |
 | ⌨️ **Typing indicator** | Stays on for the whole turn, even through long tool chains. |
 | 📥 **Queued follow-ups** | Message while Grok is busy — it's queued and runs next. `/btw` runs it ASAP (now if idle, else right after the current task); `/flush` runs the queue now. |
@@ -62,9 +63,10 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | Attach to **live** PC sessions (watch / fork) | ✅ | ❌ |
 | **Kill a session by PID** (or all at once) | ✅ | ❌ |
 | **Live task-progress bars** (`{progress: N%}`) | ✅ | ❌ |
-| **Sign in from chat** (`/reauth`) | ✅ | ❌ |
-| **Multiple saved accounts** + one-tap switch (`/accounts`) | ✅ | ❌ |
+| **Sign in from chat** (`/reauth`, device-code) | ✅ | ❌ |
+| **Multiple saved accounts** + headless one-tap switch (`/accounts`) | ✅ | ❌ |
 | **Auto-rotate accounts** when a turn gives up | ✅ | ❌ |
+| **Session auto-approve** + **pinned** interactive permissions | ✅ | ❌ |
 | Multiple isolated sessions | ✅ | ❌ (single shared) |
 | Queued follow-ups while busy | ✅ | ❌ |
 | **Scheduled tasks** (cron-like) | ✅ | ❌ |
@@ -326,9 +328,10 @@ takes precedence and the value never decreases. Disable the fallback with
 Grok Build signs in with your **xAI account** (SuperGrok / X Premium+), not an
 API key. Run **`/reauth`** to sign in without touching a terminal:
 
-- **🔑 Sign in** — runs `grok login`; if a verification link/code appears it
-  streams into the chat so you can approve it on any device. The bot then
-  restarts the agent so your next turn runs on the new identity.
+- **🔑 Sign in** — runs `grok login --device-auth` (device code, **no browser on
+  the host**). The verification link/code streams into the chat so you can
+  approve it on any device. The bot then restarts the agent under the new
+  identity.
 - **📥 Import existing** — adopt a `grok login` already done on this machine
   (`~/.grok/auth.json`).
 
@@ -338,16 +341,24 @@ It's refused while a turn is running. You can also sign in up front by running
 ## 👥 Multiple accounts
 
 **`/accounts`** manages several Grok **sign-ins** side by side. Save the current
-login as a named account (auto-named from its email, or **Save as…** with a
-custom name), rename or delete saved ones, and **switch** in a tap — the bot
-copies that account's token back over `~/.grok/auth.json` and restarts the agent
-so your next turn runs under it (the current login is snapshotted first so it's
-never lost). Snapshots live only in git-ignored per-account files.
+login as a named account (auto-named from its email when available, or
+**Save as…** with a custom name), rename or delete saved ones, and **switch** in
+a tap. Switching is deliberately headless:
+
+1. Snapshot the current login (so it isn't lost),
+2. **Stop** the shared agent,
+3. **Replace** `~/.grok/auth.json` with the saved snapshot,
+4. **Start** the agent and authenticate with `cached_token` only — never a
+   browser method like `grok.com` (which would hang a service host).
+
+The menu shows the **host Grok login** vs which saved account it matches, so a
+manual `grok login` outside the bot doesn't leave a stale “active” label.
 
 **🔁 Auto-rotate on errors** (toggle here): when a turn exhausts its retries and
-can't recover, the bot cycles through your other saved logins **once**, retrying
-the prompt on each — the first that succeeds stays active; if they all fail it
-stops after one pass. Handy when an account gets throttled or runs out of quota.
+can't recover, the bot cycles through your other saved logins **once** with the
+same stop → auth.json → start path — the first that succeeds stays active; if
+they all fail it stops after one pass. Handy when an account gets throttled or
+runs out of quota.
 
 ---
 
@@ -390,7 +401,8 @@ Resuming an **idle** session loads it directly so you continue the exact thread.
 | `GROK_MODEL` | no | `grok-4.5` | Default model for new sessions. |
 | `GROK_TG_DIR` | no | `~/.grok/tg` | Folder holding this instance's `.env`, `logs/`, `data/`. Resolution: `--instance` → `GROK_TG_DIR` → a `.env` in the current folder → `~/.grok/tg`. So a `.env` created once is loaded from any startup path. |
 | `GROK_AGENT` | no | — | Custom sub-agent name (informational; Grok delegates via its own `task`/`delegate` tools). |
-| `GROK_TRUST_ALL_TOOLS` | no | `true` | Run tools without prompts. |
+| `GROK_TRUST_ALL_TOOLS` | no | `true` | Pass `--always-approve` so tools run without prompts. |
+| `AUTO_APPROVE_PERMISSIONS` | no | `true` | Auto-approve ACP `session/request_permission` (prefer “allow for this session”). Set `false` **and** `GROK_TRUST_ALL_TOOLS=false` for interactive Approve/Deny buttons (those prompts are **pinned** until you act or they time out). |
 | `PROJECT_ROOTS` | no | workspace parent + home | Roots for `/projects`. |
 | `STREAM_THROTTLE_MS` | no | `1500` | Live-edit interval while streaming. |
 | `MESSAGE_BATCH_MS` | no | `800` | Window to coalesce rapid text messages (e.g. a long message Telegram split at 4096 chars) into one prompt. `0` disables. |
@@ -486,13 +498,20 @@ the bot inherits whatever MCP servers Grok CLI is configured with.
 
 ## 🔐 Tool approvals
 
-Over ACP, Grok honors a permission mode. With `GROK_TRUST_ALL_TOOLS=true`
-(default) the bot passes `--always-approve`, so tools run without prompts. Set it
-to `false` to run in ACP **"ask"** mode: Grok sends `session/request_permission`
-before risky tools (file writes, shell commands) and the bot surfaces
-**Approve / Approve always / Deny** buttons in Telegram, sending your choice back
-(unanswered prompts eventually cancel). You can also intervene on any live turn
-with the tool stream + **⏹ Stop** (`/cancel`), which cancels that session's turn.
+Over ACP, Grok honors a permission mode. Defaults are built for unattended
+mobile use:
+
+| Setting | Default | Effect |
+|---|---|---|
+| `GROK_TRUST_ALL_TOOLS` | `true` | Passes `--always-approve` so tools run without prompts. |
+| `AUTO_APPROVE_PERMISSIONS` | `true` | If a permission request still arrives, auto-pick **allow for this session** / always-allow. |
+
+Set **both** to `false` for ACP **"ask"** mode: Grok sends
+`session/request_permission` before risky tools and the bot surfaces
+**Approve / Allow for session / Deny** buttons. Those prompts are **pinned** so
+they aren't buried by streaming output; the pin is removed when you choose,
+or when the request times out (status panel is re-pinned). You can always
+intervene on a live turn with the tool stream + **⏹ Stop** (`/cancel`).
 
 ## 🔐 Security
 
@@ -514,10 +533,11 @@ user. See [SECURITY.md](./SECURITY.md) for the full model.
 - [x] Voice messages → speech-to-text → prompt (multi-language)
 - [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
 - [x] Account & context usage (`/usage`)
-- [x] Multiple accounts with one-tap switch + auto-rotate on errors (`/accounts`)
-- [x] Organization / Import-from-Grok-IDE login + credits on the Done line
-- [x] Release automation — downloadable zip + CHANGELOG-driven notes on tag push
+- [x] Multiple accounts with headless one-tap switch + auto-rotate (`/accounts`)
+- [x] Device-code `/reauth` (no host browser) + real email labels from auth.json
+- [x] Rich per-kind tool-call detail (search / edit diffs / shell / MCP / …)
 - [x] README community sections — Contributors, Top Contributors, Stars, StarMapper
 - [ ] **Token & cost meter** — per-session token counts and an estimated spend tally
 - [ ] **Text-to-speech replies** — optionally speak answers back as voice notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-telegram-bot",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "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/scripts/_tmp-release.mjs

@@ -0,0 +1,16 @@
+import { execSync } from "node:child_process";
+
+function run(cmd) {
+  console.log(`$ ${cmd}`);
+  execSync(cmd, { stdio: "inherit" });
+}
+
+// Annotated release tag (triggers GitHub Release workflow on push).
+try {
+  run('git tag -a v2.2.3 -m "v2.2.3 — instant account rotate on 402 balance exhausted"');
+} catch {
+  console.log("tag v2.2.3 already exists locally — continuing");
+}
+run("git push origin v2.2.3");
+run("npm publish --access public");
+console.log("done");

package/src/app/accounts.ts

@@ -76,17 +76,44 @@ export class AccountManager {
   }
 
   /**
-   * Id of the currently active saved account. Prefers the last switch target
-   * (`activeId`), then falls back to matching the live auth.json token hash.
+   * Id of the saved account that matches the live auth.json (if any).
+   * Token hash is authoritative — never trust a stale `activeId` when the host
+   * login has changed (e.g. `grok login` / /reauth outside this menu).
    */
   activeAccountId(): string | undefined {
     const data = this.store.get();
+    const lid = loginId();
+    if (lid) {
+      const byToken = data.accounts.find((a) => a.loginId === lid);
+      if (byToken) return byToken.id;
+      // Live login differs from every saved account (and any stale activeId).
+      return undefined;
+    }
+    // No readable token (API-key-only / missing file) — last switch target only.
     if (data.activeId && data.accounts.some((a) => a.id === data.activeId)) {
       return data.activeId;
     }
+    return undefined;
+  }
+
+  /**
+   * Last switch/save target stored by the app, even when the host Grok login
+   * no longer matches that snapshot (used only for mismatch UI copy).
+   */
+  markedActiveId(): string | undefined {
+    const id = this.store.get().activeId;
+    if (!id) return undefined;
+    return this.store.get().accounts.some((a) => a.id === id) ? id : undefined;
+  }
+
+  /** Whether the host's live login matches the saved account marked active. */
+  liveMatchesActive(): boolean {
     const lid = loginId();
-    if (!lid) return undefined;
-    return data.accounts.find((a) => a.loginId === lid)?.id;
+    if (!lid) return false;
+    const marked = this.markedActiveId();
+    if (!marked) return this.activeAccountId() !== undefined;
+    const meta = this.get(marked);
+    return !!meta?.loginId && meta.loginId === lid;
   }
 
   get(id: string): StoredAccount | undefined {
@@ -117,19 +144,32 @@ export class AccountManager {
     }
     const label = customLabel?.trim() || loginLabel() || `account ${lid.slice(0, 6)}`;
     const email = loginLabel();
-    // Match by token hash first; fall back to the currently marked active slot
-    // when the user is re-saving after a silent token refresh.
-    const existing =
-      this.store.get().accounts.find((a) => a.loginId === lid) ??
-      (this.store.get().activeId ? this.get(this.store.get().activeId!) : undefined);
+    // Match by token hash first. Only reuse the marked active slot when it is
+    // the same login (token refresh) or the same email — never overwrite a
+    // different saved account when the host is signed in as someone else.
+    const accounts = this.store.get().accounts;
+    const byToken = accounts.find((a) => a.loginId === lid);
+    const active = this.store.get().activeId ? this.get(this.store.get().activeId!) : undefined;
+    const emailKey = email?.toLowerCase();
+    const byEmail =
+      emailKey && emailKey.includes("@")
+        ? accounts.find((a) => (a.email || a.label || "").toLowerCase() === emailKey)
+        : undefined;
+    const sameActiveRefresh =
+      active &&
+      (active.loginId === lid ||
+        (!!emailKey &&
+          emailKey.includes("@") &&
+          [active.email, active.label].some((v) => (v || "").toLowerCase() === emailKey)));
+    const existing = byToken ?? (sameActiveRefresh ? active : undefined) ?? byEmail;
     const id = existing?.id ?? makeId();
     await writeFile(this.snapshotPath(id), raw, "utf-8");
     const meta: StoredAccount = {
       id,
       label: customLabel?.trim() || existing?.label || label,
       loginId: lid,
-      email: email || existing?.email,
-      startUrl: email || existing?.email,
+      email: (email && email.includes("@") ? email : undefined) || existing?.email,
+      startUrl: (email && email.includes("@") ? email : undefined) || existing?.email || existing?.startUrl,
       savedAt: new Date().toISOString(),
     };
     this.store.update((d) => {

package/src/app/grok-credentials.ts

@@ -2,7 +2,7 @@
  * Grok Build login state. The official CLI signs in with your xAI account
  * (`grok login`, browser OIDC) and stores the token in `~/.grok/auth.json`:
  *
- *   { "<scope_url>": { "key": "<token>" }, ... }
+ *   { "<scope_url>": { "key": "<token>", "email"?: "...", ... }, ... }
  *
  * (An `XAI_API_KEY` env var is an alternative for non-browser hosts.) This
  * module reads that file so the bot can show who's signed in, detect a usable
@@ -36,7 +36,19 @@ export function authFileExists(): boolean {
   return existsSync(grokAuthPath());
 }
 
-type AuthFile = Record<string, { key?: string } | undefined>;
+/** One scope entry inside ~/.grok/auth.json (fields beyond `key` are optional). */
+export interface AuthEntry {
+  key?: string;
+  email?: string;
+  first_name?: string;
+  last_name?: string;
+  user_id?: string;
+  principal_id?: string;
+  auth_mode?: string;
+  [extra: string]: unknown;
+}
+
+export type AuthFile = Record<string, AuthEntry | undefined>;
 
 export function readAuth(): AuthFile {
   try {
@@ -46,12 +58,18 @@ export function readAuth(): AuthFile {
   }
 }
 
+/** Active scope entry (OIDC preferred, then legacy). */
+export function currentAuthEntry(auth: AuthFile = readAuth()): AuthEntry | undefined {
+  const oidc = auth[OIDC_SCOPE];
+  if (oidc?.key?.trim()) return oidc;
+  const legacy = auth[LEGACY_SCOPE];
+  if (legacy?.key?.trim()) return legacy;
+  return undefined;
+}
+
 /** The active sign-in token from auth.json (OIDC preferred, then legacy). */
 export function currentToken(auth: AuthFile = readAuth()): string | undefined {
-  const oidc = auth[OIDC_SCOPE]?.key?.trim();
-  if (oidc) return oidc;
-  const legacy = auth[LEGACY_SCOPE]?.key?.trim();
-  return legacy || undefined;
+  return currentAuthEntry(auth)?.key?.trim() || undefined;
 }
 
 /** Whether a usable login exists (a token in auth.json, or XAI_API_KEY). */
@@ -81,16 +99,33 @@ function decodeJwtPayload(jwt: string): Record<string, unknown> | undefined {
   }
 }
 
-/** Best-effort identity (email/name) decoded from the sign-in JWT. */
+/**
+ * Best-effort identity (email/name). Prefer fields Grok writes on the auth
+ * entry (`email`, `first_name`, …) — modern access tokens often omit email
+ * claims — then fall back to JWT claims when present.
+ */
 export function identityFromAuth(auth: AuthFile = readAuth()): LoginIdentity {
-  const tok = currentToken(auth);
-  if (!tok) return {};
-  const claims = decodeJwtPayload(tok);
-  if (!claims) return {};
-  const str = (k: string): string | undefined => (typeof claims[k] === "string" ? (claims[k] as string) : undefined);
-  const emailish = str("email") || str("preferred_username") || str("upn");
-  const email = emailish && emailish.includes("@") ? emailish : undefined;
-  return { email, name: str("name") || str("given_name") };
+  const entry = currentAuthEntry(auth);
+  if (!entry) return {};
+
+  const entryEmail = typeof entry.email === "string" && entry.email.includes("@") ? entry.email : undefined;
+  const entryName = [entry.first_name, entry.last_name]
+    .filter((p): p is string => typeof p === "string" && p.trim().length > 0)
+    .join(" ")
+    .trim() || undefined;
+
+  const tok = entry.key?.trim();
+  const claims = tok ? decodeJwtPayload(tok) : undefined;
+  const str = (k: string): string | undefined =>
+    claims && typeof claims[k] === "string" ? (claims[k] as string) : undefined;
+  const claimEmailish = str("email") || str("preferred_username") || str("upn");
+  const claimEmail = claimEmailish && claimEmailish.includes("@") ? claimEmailish : undefined;
+  const claimName = str("name") || str("given_name");
+
+  return {
+    email: entryEmail || claimEmail,
+    name: entryName || claimName,
+  };
 }
 
 /** A short human label for the active login (email, else a short token hash). */

package/src/bot/account-rotator.ts

@@ -1,6 +1,7 @@
 /**
- * Auto-rotate-on-give-up. When a turn exhausts its retries (and auto-fork can't
- * recover it), the runtime can cycle through the OTHER saved Grok accounts,
+ * Auto-rotate-on-give-up. When a turn exhausts its retries (or fails immediately
+ * with a permanent billing error like HTTP 402 balance exhausted) and auto-fork
+ * can't recover it, the runtime can cycle through the OTHER saved Grok accounts,
  * retrying the same prompt on each — useful when the active account is
  * throttled, out of quota, or its backend keeps returning "dispatch failure".
  *
@@ -12,8 +13,11 @@
  * a rotation restarts the shared agent and affects every chat — intended, since
  * the whole point is to move everyone onto a working login.
  *
- * CRITICAL: switch = stop agent → replace ~/.grok/auth.json → start agent with
- * headless `cached_token` auth. Never opens a browser / never runs `grok login`.
+ * CRITICAL: every activate() MUST fully restart the CLI so the new auth applies:
+ *   1. stop agent (`stopAndWait`) — process must exit so it cannot rewrite auth,
+ *   2. replace ~/.grok/auth.json with the saved snapshot,
+ *   3. start agent + `authenticate({ methodId: "cached_token" })` headlessly.
+ * Never opens a browser / never runs `grok login`.
  */
 import type { GrokClient } from "../grok/client.js";
 import type { AccountManager } from "../app/accounts.js";
@@ -52,10 +56,11 @@ export class AccountRotatorImpl implements AccountRotator {
   }
 
   /**
-   * Pure file-based account swap:
-   *   1. Stop the shared agent (so it cannot rewrite auth.json),
+   * Pure file-based account swap with a full CLI restart so the new token is
+   * loaded (agent is process-local with `--no-leader`):
+   *   1. Stop the shared agent and wait for exit (so it cannot rewrite auth.json),
    *   2. Copy the saved snapshot over ~/.grok/auth.json,
-   *   3. Start the agent and authenticate with `cached_token` (headless).
+   *   3. Start a fresh agent process and authenticate with `cached_token`.
    * Never launches a browser.
    */
   async activate(id: string): Promise<void> {
@@ -63,12 +68,15 @@ export class AccountRotatorImpl implements AccountRotator {
     await this.accounts.captureCurrent().catch((e) => {
       log.warn("pre-rotate capture failed (continuing):", (e as Error).message);
     });
-    log.info(`rotating: stopping agent before auth.json swap (${id})`);
+    log.info(`rotating: stopping Grok CLI before auth.json swap (${id})`);
     await this.acp.stopAndWait();
     try {
       const meta = await this.accounts.switchTo(id);
-      log.info(`rotating: auth.json now ${meta.label}; starting agent`);
+      log.info(`rotating: auth.json now ${meta.label}; starting Grok CLI + re-auth`);
+      // start() → connect() → initialize + authenticate(cached_token) against
+      // the freshly written auth.json. A live process would keep the old token.
       await this.acp.start();
+      log.info(`rotating: Grok CLI up on ${meta.label}`);
     } catch (e) {
       // Best-effort recover the agent so the bot stays usable even if the
       // target login was bad.

package/src/bot/handlers/accounts.ts

@@ -25,14 +25,28 @@ async function view(deps: BotDeps, note?: string): Promise<{ text: string; keybo
   const list = deps.accounts.list();
   const acct = await deps.usage.account().catch(() => undefined);
   const active = deps.accounts.activeAccountId();
+  const marked = deps.accounts.markedActiveId();
   const loggedIn = await deps.usage.isLoggedIn().catch(() => false);
+  const liveLabel = acct?.email?.trim();
+  const activeMeta = active ? deps.accounts.get(active) : undefined;
+  const markedMeta = marked && marked !== active ? deps.accounts.get(marked) : undefined;
 
   const lines = ["\u{1F465} Grok accounts", ""];
-  if (loggedIn && acct?.email && !active) {
-    lines.push(`\u{1F7E2} Signed in as ${acct.email}`);
-    lines.push("  \u2514 Not saved yet — tap \u201C\u{1F4BE} Save current login\u201D to keep it.", "");
-  } else if (!loggedIn) {
+  if (!loggedIn) {
     lines.push("\u{1F534} Not signed in — sign in via /reauth.", "");
+  } else if (liveLabel) {
+    lines.push(`\u{1F7E2} Host Grok login: ${liveLabel}`);
+    if (activeMeta) {
+      lines.push(`  \u2514 Matches saved: ${activeMeta.label}`);
+    } else {
+      lines.push("  \u2514 Not among saved accounts — tap \u201C\u{1F4BE} Save current login\u201D.");
+      if (markedMeta) {
+        lines.push(`  \u2514 App still has ${markedMeta.label} selected — different from host login.`);
+      }
+    }
+    lines.push("");
+  } else {
+    lines.push("\u{1F7E2} Signed in (identity unknown).", "");
   }
   if (list.length === 0) {
     lines.push("No saved accounts yet.", "", "Save the current login below, or sign in via /reauth.");
@@ -43,7 +57,9 @@ async function view(deps: BotDeps, note?: string): Promise<{ text: string; keybo
   lines.push(
     "",
     `\u{1F501} Auto-rotate on errors: ${rotate ? "ON" : "OFF"}`,
-    rotate ? "  \u2514 If a turn gives up, it cycles through the other accounts once." : "  \u2514 Turns stay on the active account.",
+    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).",
   );
   if (note) lines.push("", note);
 

package/src/bot/prompt-retry.ts

@@ -68,3 +68,30 @@ export function formatErrorSummary(error: Error, elapsed: string, attempts: numb
   }
   return `\u274C Gave up after ${attempts} attempts over ${elapsed}.\nLast error: ${error.message}${tip}`;
 }
+
+/**
+ * Compact, human-facing reason for an account switch (Telegram status line).
+ * Prefers a short billing/quota phrase when present; otherwise truncates.
+ */
+export function shortSwitchReason(error: Error, max = 140): string {
+  const raw = error.message.replace(/\s+/g, " ").trim();
+  const known =
+    raw.match(/Grok Build usage balance exhausted/i)?.[0] ??
+    raw.match(/usage balance exhausted/i)?.[0] ??
+    raw.match(/balance exhausted/i)?.[0] ??
+    raw.match(/Payment Required/i)?.[0] ??
+    raw.match(/quota exceeded/i)?.[0] ??
+    raw.match(/out of (?:credits|quota|balance)/i)?.[0];
+  const text = known ?? raw;
+  return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
+}
+
+/** Shown when auto-rotate swaps login mid-turn and retries on the new account. */
+export function formatAccountSwitchNotice(label: string, error: Error): string {
+  return [
+    `\u{1F504} Account switched to ${label}`,
+    `because of: ${shortSwitchReason(error)}`,
+    "",
+    "Restarting Grok CLI with the new login and retrying\u2026",
+  ].join("\n");
+}

package/src/bot/session-runtime.ts

@@ -6,7 +6,13 @@
  */
 import { basename } from "node:path";
 import { type Api, InlineKeyboard } from "grammy";
-import { type GrokClient, isContextExhaustedError, isTransientError, type SessionMetadata } from "../grok/client.js";
+import {
+  type GrokClient,
+  isAccountExhaustedError,
+  isContextExhaustedError,
+  isTransientError,
+  type SessionMetadata,
+} from "../grok/client.js";
 import type { AccountRotator } from "./account-rotator.js";
 import type { ContentBlock, PromptResult, SessionUpdate } from "../grok/types.js";
 import type { AppConfig } from "../config.js";
@@ -27,7 +33,14 @@ import type { PendingStage, SubagentInfo } from "../grok/types.js";
 import { ResponseStreamer } from "../stream/streamer.js";
 import { extractImagePaths, sendImages } from "./image-return.js";
 import { buildContentBlocks, mergeInputs } from "./prompt-content.js";
-import { backoffSchedule, fmtSeconds, formatErrorSummary, formatRetryNotice, RETRY_BASE_MS } from "./prompt-retry.js";
+import {
+  backoffSchedule,
+  fmtSeconds,
+  formatAccountSwitchNotice,
+  formatErrorSummary,
+  formatRetryNotice,
+  RETRY_BASE_MS,
+} from "./prompt-retry.js";
 import { sendMarkdownDoc } from "./telegram-io.js";
 import { TypingIndicator } from "./typing.js";
 
@@ -661,13 +674,17 @@ export class SessionRuntime {
   }
 
   /**
-   * Auto-rotate-on-give-up. When a turn has failed (retries exhausted, auto-fork
-   * didn't recover it) and nothing was streamed, cycle through the OTHER saved
-   * accounts once — switching login + restarting the agent, then retrying the
-   * same prompt on a fresh session for each. The first account that succeeds
-   * wins and stays active; if every account fails we return a single combined
-   * error listing what each one reported. Bounded to ONE pass (no infinite
+   * Auto-rotate-on-give-up. When a turn has failed (retries exhausted / billing
+   * 402 with no same-account retry, auto-fork didn't recover) and nothing was
+   * streamed, cycle through the OTHER saved accounts once — each step:
+   *   stop Grok CLI → replace ~/.grok/auth.json → start CLI + headless auth →
+   *   open a fresh session → retry the same prompt.
+   * The first account that succeeds wins and stays active; if every account
+   * fails we stop with a combined error. Bounded to ONE pass (no infinite
    * loop). No-op unless the rotator is enabled and other accounts exist.
+   *
+   * Billing/quota failures (402 balance exhausted) skip backoff retries on
+   * each account and rotate instantly so the turn continues without a long wait.
    */
   private async maybeRotateAccount(
     input: PromptInput,
@@ -685,11 +702,13 @@ export class SessionRuntime {
 
     for (const t of targets) {
       if (this.cancelled) return last;
+      const failReason = last.error ?? final.error;
       if (this.foreground) {
-        await this.notify(`\u{1F501} Auto-rotating accounts \u2014 trying ${t.label}\u2026`, { replyTo: this.turnReplyTo });
+        await this.notify(formatAccountSwitchNotice(t.label, failReason), { replyTo: this.turnReplyTo });
       }
       try {
-        await rotator.activate(t.id); // switch login + restart the shared agent
+        // stop CLI → swap auth.json → start CLI + authenticate(cached_token)
+        await rotator.activate(t.id);
       } catch (e) {
         errors.push(`\u2022 ${t.label}: couldn't switch \u2014 ${(e as Error).message}`);
         continue;
@@ -709,17 +728,23 @@ export class SessionRuntime {
         priming: transcript ? buildPriming(transcript) : undefined,
         progress: this.cfg.showProgress ? PROGRESS_DIRECTIVE : undefined,
       });
-      log.info(`chat ${this.chatId} auto-rotating to account ${t.label}`);
+      log.info(
+        `chat ${this.chatId} auto-rotating to account ${t.label}` +
+          (isAccountExhaustedError(failReason) ? " (billing/quota exhausted on previous)" : ""),
+      );
+      // runPromptWithRetries already skips backoff for 402 / balance exhausted.
       last = await this.runPromptWithRetries(content);
       if (last.result && !this.cancelled) {
-        if (this.foreground) await this.notify(`\u2705 Recovered on ${t.label}.`, { replyTo: this.turnReplyTo });
+        if (this.foreground) {
+          await this.notify(`\u2705 Recovered on ${t.label}.`, { replyTo: this.turnReplyTo });
+        }
         return last;
       }
       if (this.cancelled || (this.streamer?.hasOutput ?? false)) return last;
       errors.push(`\u2022 ${t.label}: ${last.error?.message ?? "failed"}`);
     }
 
-    // One full cycle done and still failing — stop with a combined report.
+    // One full cycle done and still failing — stop with a combined report.
     const combined = new Error(`Tried ${targets.length + 1} account(s), all failed:\n${errors.join("\n")}`);
     return { error: combined, attempts: last.attempts };
   }
@@ -748,12 +773,15 @@ export class SessionRuntime {
         const error = err as Error;
         const canRecover = !this.cancelled && !(this.streamer?.hasOutput ?? false);
         // A context-exhausted session won't recover by retrying the same
-        // oversized prompt — skip the backoff and let auto-fork compact it now.
+        // oversized prompt — skip the backoff and let auto-fork compact it now.
         const forkInstead = canRecover && this.cfg.autoForkOnError && this.isContextRelatedFailure(error);
+        // Billing/quota 402 (balance exhausted) is permanent for this login —
+        // never backoff-retry; surface immediately so auto-rotate can switch.
         const willRetry =
           attempt <= delays.length &&
           canRecover &&
           !forkInstead &&
+          !isAccountExhaustedError(error) &&
           isTransientError(error);
         if (!willRetry) return { error, attempts: attempt };
         const waitMs = delays[attempt - 1]!;

package/src/grok/client.ts

@@ -46,6 +46,14 @@ const TRANSIENT_RE =
   /internal error|high volume|experiencing|overloaded|temporar|unavailable|rate.?limit|too many requests|try again|capacity|dispatch failure|response stream|connection (?:reset|closed|refused|error)|reset by peer|broken pipe|socket hang ?up|econnreset|econnrefused|enotfound|eai_again|etimedout|\b50[234]\b|\b429\b/i;
 const CONTEXT_EXHAUSTED_RE =
   /context (?:length|window|limit|size|overflow)|maximum context|input (?:is )?too long|prompt (?:is )?too long|too many (?:input )?tokens|token limit|exceeds? (?:the )?(?:maximum|context|token)|reduce the (?:length|size)|context.{0,24}exhaust/i;
+/**
+ * Permanent-for-this-login billing/quota failures (e.g. HTTP 402 "Grok Build
+ * usage balance exhausted"). These ride inside ACP Internal error [-32603] but
+ * must NOT be backoff-retried on the same account — only account rotation can
+ * recover.
+ */
+const ACCOUNT_EXHAUSTED_RE =
+  /\b402\b|payment required|balance exhausted|usage balance|out of (?:credits|quota|balance)|insufficient (?:credits|balance|quota)|quota exceeded|no (?:remaining )?credits/i;
 
 export class GrokError extends Error {
   constructor(
@@ -58,7 +66,35 @@ export class GrokError extends Error {
   }
 }
 
+/**
+ * True when the failure is a billing/quota exhaustion for the active Grok
+ * login (HTTP 402, "balance exhausted", etc.). Same-account retries cannot
+ * help; the turn should stop (or auto-rotate to another saved account).
+ */
+export function isAccountExhaustedError(err: Error): boolean {
+  if (ACCOUNT_EXHAUSTED_RE.test(err.message)) return true;
+  const data = (err as GrokError).data;
+  if (!data || typeof data !== "object") return false;
+  const d = data as Record<string, unknown>;
+  const status = d.http_status ?? d.status ?? d.statusCode;
+  if (status === 402 || status === "402") return true;
+  if (typeof d.message === "string" && ACCOUNT_EXHAUSTED_RE.test(d.message)) return true;
+  // Nested JSON sometimes lands as a stringified payload inside `data`.
+  for (const v of Object.values(d)) {
+    if (typeof v === "string" && ACCOUNT_EXHAUSTED_RE.test(v)) return true;
+    if (v && typeof v === "object") {
+      const nested = v as Record<string, unknown>;
+      const ns = nested.http_status ?? nested.status ?? nested.statusCode;
+      if (ns === 402 || ns === "402") return true;
+      if (typeof nested.message === "string" && ACCOUNT_EXHAUSTED_RE.test(nested.message)) return true;
+    }
+  }
+  return false;
+}
+
 export function isTransientError(err: Error): boolean {
+  // Balance/quota exhaustion is permanent for this login — never backoff-retry.
+  if (isAccountExhaustedError(err)) return false;
   const code = (err as GrokError).code;
   if (typeof code === "number" && TRANSIENT_CODES.has(code)) return true;
   return TRANSIENT_RE.test(err.message);

package/scripts/_push-branch.mjs

@@ -1,79 +0,0 @@
-import { readFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-
-const files = process.argv.slice(2);
-if (files.length < 3) {
-  console.error("Usage: node scripts/_push-branch.mjs <branch> <message> <file>...");
-  process.exit(1);
-}
-const [branch, message, ...paths] = files;
-const owner = "artickc";
-const repo = "grok-telegram-bot";
-
-// eslint-disable-next-line no-control-regex
-const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
-
-function ghApi(method, path, body) {
-  const args = ["api", "-X", method, path];
-  const opts = {
-    encoding: "utf8",
-    maxBuffer: 50 * 1024 * 1024,
-    shell: false,
-    env: { ...process.env, NO_COLOR: "1", CLICOLOR: "0", FORCE_COLOR: "0", GH_FORCE_TTY: "0" },
-  };
-  if (body !== undefined) {
-    args.push("--input", "-");
-    opts.input = JSON.stringify(body);
-  }
-  const r = spawnSync("gh", args, opts);
-  if (r.status !== 0) {
-    throw new Error(`gh api ${method} ${path} failed (${r.status}): ${r.stderr || r.stdout}`);
-  }
-  const text = (r.stdout || "").replace(ANSI_RE, "").trim();
-  if (!text) return {};
-  return JSON.parse(text);
-}
-
-// Ensure branch exists from main if missing.
-try {
-  ghApi("GET", `repos/${owner}/${repo}/git/ref/heads/${branch}`);
-} catch {
-  const main = ghApi("GET", `repos/${owner}/${repo}/git/ref/heads/main`);
-  ghApi("POST", `repos/${owner}/${repo}/git/refs`, {
-    ref: `refs/heads/${branch}`,
-    sha: main.object.sha,
-  });
-  console.log("created branch", branch, "from main");
-}
-
-const ref = ghApi("GET", `repos/${owner}/${repo}/git/ref/heads/${branch}`);
-const baseSha = ref.object.sha;
-const baseCommit = ghApi("GET", `repos/${owner}/${repo}/git/commits/${baseSha}`);
-const baseTree = baseCommit.tree.sha;
-console.log("base", baseSha);
-
-const tree = [];
-for (const path of paths) {
-  const content = readFileSync(path, "utf8");
-  const blob = ghApi("POST", `repos/${owner}/${repo}/git/blobs`, {
-    content: Buffer.from(content, "utf8").toString("base64"),
-    encoding: "base64",
-  });
-  tree.push({ path: path.replace(/\\/g, "/"), mode: "100644", type: "blob", sha: blob.sha });
-  console.log("blob", path, blob.sha.slice(0, 8));
-}
-
-const newTree = ghApi("POST", `repos/${owner}/${repo}/git/trees`, {
-  base_tree: baseTree,
-  tree,
-});
-const commit = ghApi("POST", `repos/${owner}/${repo}/git/commits`, {
-  message,
-  tree: newTree.sha,
-  parents: [baseSha],
-});
-ghApi("PATCH", `repos/${owner}/${repo}/git/refs/heads/${branch}`, {
-  sha: commit.sha,
-  force: false,
-});
-console.log("updated", branch, "->", commit.sha);

package/scripts/_tag-release.mjs

@@ -1,52 +0,0 @@
-import { spawnSync } from "node:child_process";
-
-const owner = "artickc";
-const repo = "grok-telegram-bot";
-const version = process.argv[2] || "2.2.1";
-const tag = `v${version}`;
-const message = process.argv[3] || `${tag} — pin permission prompts until resolved`;
-
-// eslint-disable-next-line no-control-regex
-const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
-
-function ghApi(method, path, body) {
-  const args = ["api", "-X", method, path];
-  const opts = {
-    encoding: "utf8",
-    maxBuffer: 50 * 1024 * 1024,
-    shell: false,
-    env: { ...process.env, NO_COLOR: "1", CLICOLOR: "0", FORCE_COLOR: "0", GH_FORCE_TTY: "0" },
-  };
-  if (body !== undefined) {
-    args.push("--input", "-");
-    opts.input = JSON.stringify(body);
-  }
-  const r = spawnSync("gh", args, opts);
-  if (r.status !== 0) {
-    throw new Error(`gh api ${method} ${path} failed (${r.status}): ${r.stderr || r.stdout}`);
-  }
-  const text = (r.stdout || "").replace(ANSI_RE, "").trim();
-  if (!text) return {};
-  return JSON.parse(text);
-}
-
-const ref = ghApi("GET", `repos/${owner}/${repo}/git/ref/heads/main`);
-const sha = ref.object.sha;
-console.log("main", sha);
-
-const tagObj = ghApi("POST", `repos/${owner}/${repo}/git/tags`, {
-  tag,
-  message,
-  object: sha,
-  type: "commit",
-  tagger: {
-    name: "artickc",
-    email: "artickc@users.noreply.github.com",
-    date: new Date().toISOString(),
-  },
-});
-ghApi("POST", `repos/${owner}/${repo}/git/refs`, {
-  ref: `refs/tags/${tag}`,
-  sha: tagObj.sha,
-});
-console.log("created tag", tag, "->", sha);