grok-telegram-bot 2.3.1 → 2.5.0

package/src/bot/session-runtime.ts

@@ -4,7 +4,7 @@
  * and per-chat preferences (project, agent, model, reasoning). State persists
  * to the settings store so it survives restarts.
  */
-import { basename } from "node:path";
+import { basename, join } from "node:path";
 import { type Api, InlineKeyboard } from "grammy";
 import {
   type GrokClient,
@@ -15,26 +15,80 @@ import {
   type SessionMetadata,
 } from "../grok/client.js";
 import type { AccountRotator } from "./account-rotator.js";
-import type { ContentBlock, PromptResult, SessionUpdate } from "../grok/types.js";
+import { contentText, type ContentBlock, type PromptResult, type SessionUpdate } from "../grok/types.js";
 import type { AppConfig } from "../config.js";
 import { reasoningDirective } from "../app/reasoning.js";
 import type { SettingsStore } from "../app/settings-store.js";
 import { type PromptInput, type ReasoningEffort, textPrompt } from "../app/types.js";
 import { createLogger } from "../logger.js";
-import { buildTranscript } from "../sessions/history.js";
+import { buildTranscript, readHistory } from "../sessions/history.js";
 import { sessionHashtags } from "../render/hashtags.js";
 import { PROGRESS_DIRECTIVE } from "../render/progress.js";
 import { buildPriming, recentTranscript } from "./session-fork.js";
 import { TailWatcher } from "../sessions/tail.js";
 import type { HistoryEntry } from "../sessions/types.js";
 import { formatToolCall } from "../render/tool-call.js";
-import { type FileOp, fileOpFromUpdate, mergeFileOp, summarizeFileOps, summarizeFileOpsShort } from "../render/file-summary.js";
+import {
+  mergeToolSnapshot,
+  snapshotHasDetail,
+  type ToolSnapshot,
+} from "../render/tool-call-merge.js";
+import {
+  type FileOp,
+  cloneFileOps,
+  fileOpFromUpdate,
+  mergeFileOp,
+  summarizeFileOps,
+  summarizeFileOpsShort,
+  summarizeFileOpsSplit,
+} from "../render/file-summary.js";
 import { isActiveStatus, renderSubagentTransition, statusKey } from "../render/subagent.js";
 import type { PendingStage, SubagentInfo } from "../grok/types.js";
 import { ResponseStreamer } from "../stream/streamer.js";
 import { IMAGE_OUTPUT_DIRECTIVE } from "../render/image-output.js";
 import { collectTurnImagePaths, sendImages } from "./image-return.js";
 import { buildContentBlocks, mergeInputs } from "./prompt-content.js";
+import { wrapAutoComplexityPrompt } from "./complexity-gate.js";
+import {
+  autoApproveSuggestions,
+  buildSelfRecheckDecisionPrompt,
+  buildSelfRecheckPrompt,
+  buildSuggestionsPrompt,
+  composeSelfRecheckTurn,
+  formatBatchedSuggestionsPrompt,
+  isSelfRecheckPrompt,
+  parseSelfRecheckDecision,
+  parseSuggestions,
+  type Suggestion,
+  suggestionsKeyboard,
+} from "./suggestions.js";
+import type { ForumManager } from "../forum/manager.js";
+import type { SessionStore } from "../sessions/store.js";
+import type { TelegramBotService } from "./telegram-bots.js";
+import { executeTelegramActions } from "./telegram-actions.js";
+import {
+  buildTelegramBridgeDirective,
+  buildTelegramBridgeResultsPrompt,
+  extractTelegramActions,
+  isTelegramBridgeResultsPrompt,
+  wrapTelegramBridgePrompt,
+} from "../render/telegram-bridge.js";
+import {
+  parsePlanUpdate,
+  renderPlanMarkdown,
+  renderPlanOneLine,
+  type PlanEntry,
+} from "../render/plan.js";
+import {
+  buildSessionCardComment,
+  clampThinking,
+  cleanCommentLine,
+  cleanUserPreview,
+  COMMENT_MAX,
+  stepFromThought,
+  stepFromToolUpdate,
+  stripDirectiveWrappers,
+} from "../render/session-comment.js";
 import {
   backoffSchedule,
   fmtSeconds,
@@ -85,6 +139,8 @@ export class SessionRuntime {
   private streamer: ResponseStreamer | undefined;
   private readonly typing: TypingIndicator;
   private shownToolIds = new Set<string>();
+  /** toolCallId → merged snapshot so completed updates keep title/args. */
+  private toolCallCache = new Map<string, ToolSnapshot>();
   /** Files touched this turn (path -> operation), tracked even in background so
    *  the completion message can summarise what changed. */
   private fileOps = new Map<string, FileOp>();
@@ -101,6 +157,8 @@ export class SessionRuntime {
   private turnCount = 0;
   /** Telegram message id of the current turn's prompt, so replies thread to it. */
   private turnReplyTo: number | undefined;
+  /** Short id for `#prompt_<id>` on all AI messages of this turn. */
+  private turnPromptId: string | undefined;
   private imageScanText = "";
   private sentImagesThisTurn = new Set<string>();
   /** Monotonic count used to reject ACP "success" responses with no turn updates. */
@@ -127,6 +185,90 @@ export class SessionRuntime {
   /** Optional multi-account rotator: when a turn gives up, cycle through the
    *  other saved logins once and retry on each. Injected by the registry. */
   accountRotator: AccountRotator | undefined;
+  /** Session ids that already received the first-prompt auto-complexity directive. */
+  private complexitySteered = new Set<string>();
+  /** Session ids that already received the first-prompt Telegram bridge directive. */
+  private telegramBridgeSteered = new Set<string>();
+  /**
+   * How many TELEGRAM BRIDGE RESULTS follow-ups are chained after the current
+   * user turn. Caps infinite list_bots/bot_command loops; reset on real user work.
+   */
+  private bridgeResultDepth = 0;
+  /** Max sequential bridge result turns per user request. */
+  private static readonly BRIDGE_CHAIN_MAX = 4;
+  /**
+   * Optional Telegram bridge services (forum / session store / sibling bots).
+   * Injected by the registry after construct.
+   */
+  bridge?: {
+    store: SessionStore;
+    forum?: ForumManager;
+    bots: TelegramBotService;
+    /** Cross-topic prompt dispatch (create_topic → send_prompt orchestration). */
+    submitTopicPrompt?: import("./telegram-actions.js").SubmitTopicPromptFn;
+  };
+  /** Last credits total reported for this session (for per-turn delta accounting). */
+  private lastReportedCredits = 0;
+  /** Live "what is happening now" line while a turn is in flight (tools/plan). */
+  private liveStep: string | undefined;
+  /**
+   * Card comment on disk / idle: last user prompt (≤ COMMENT_MAX).
+   * While busy, {@link cardComment} also appends last agent thinking.
+   */
+  private sessionComment: string | undefined;
+  /** Cleaned last user prompt for cards (not overwritten by self-recheck meta). */
+  private cardUserPrompt: string | undefined;
+  /** Accumulated agent_thought_chunk text for the current turn (card display). */
+  private cardThinking = "";
+  /** User text of the turn currently running (for local card-comment fallback). */
+  private turnUserText = "";
+  /** Assistant prose streamed this turn — used for suggestions / completion. */
+  private turnAssistantText = "";
+  /** Quiet meta capture (suggestions) — never stream to Telegram. */
+  private capturingQuiet = false;
+  private quietCaptureBuf = "";
+  /**
+   * Done delivery bookkeeping for this turn: expect a loud Done ping, and whether
+   * one was successfully sent (finally forces a short Done if expected but missing).
+   */
+  private turnExpectDone = false;
+  private turnDonePinged = false;
+  /** Batches of post-turn suggestions for inline-button callbacks. */
+  private suggestionBatches = new Map<number, Suggestion[]>();
+  private suggestionBatchSeq = 0;
+  /**
+   * Last successful Done's suggestions — kept so a background "Done from other
+   * session" can carry buttons, and so switching back to this session re-shows
+   * them even if the user missed the notify (or notify was off).
+   */
+  private pendingSuggestions:
+    | { batchId: number; suggestions: Suggestion[]; banner: string }
+    | undefined;
+  /** Live ACP plan board for the current turn (done / in-progress / pending). */
+  private planEntries: PlanEntry[] | undefined;
+  /** True while the active turn is the automatic one-shot self-recheck pass. */
+  private isSelfRecheckTurn = false;
+  /**
+   * Original user prompt (and first-pass assistant text) for suggestions after
+   * a self-recheck turn, so follow-ups stay grounded in the real user request.
+   */
+  private suggestionUserText = "";
+  private preRecheckAssistantText = "";
+  /** File ops from the first turn, frozen before the self-recheck pass. */
+  private preRecheckFileOps = new Map<string, FileOp>();
+  /**
+   * When true, this turn must not schedule a self-recheck (meta / auto-queue /
+   * already-recheck). Set from PromptInput.skipSelfRecheck or recheck marker.
+   */
+  private skipSelfRecheck = false;
+
+  /**
+   * Forum topic thread id (message_thread_id). When set, all outbound messages
+   * for this runtime are posted into that topic.
+   */
+  readonly messageThreadId: number | undefined;
+  /** Settings storage key (`chatId` or `chatId:t{threadId}`). */
+  readonly settingsKey: string;
 
   constructor(
     private readonly api: Api,
@@ -134,14 +276,22 @@ export class SessionRuntime {
     private readonly acp: GrokClient,
     private readonly cfg: AppConfig,
     private readonly settings: SettingsStore,
-    init?: { cwd: string; projectName?: string; sessionId?: string },
+    init?: {
+      cwd: string;
+      projectName?: string;
+      sessionId?: string;
+      messageThreadId?: number;
+      settingsKey?: string;
+    },
   ) {
+    this.messageThreadId = init?.messageThreadId;
+    this.settingsKey = init?.settingsKey ?? String(chatId);
     if (init) {
       this.cwd = init.cwd;
       this.projectName = init.projectName;
       this.sessionId = init.sessionId;
     } else {
-      const s = settings.get(chatId);
+      const s = settings.getKey(this.settingsKey);
       this.cwd = s.projectPath ?? cfg.workspace;
       this.projectName = s.projectName;
       this.sessionId = s.sessionId;
@@ -176,11 +326,62 @@ export class SessionRuntime {
     return this.lastCompletion;
   }
 
-  /** Latest task-completion % (0–100) parsed this turn, or undefined if none. */
+  /** Latest task-completion % (0–100) parsed this turn, or undefined if none. */
   get taskProgress(): number | undefined {
     return this.progress;
   }
 
+  /**
+   * Full plan board for the live stream / status panel (above the progress bar).
+   * Empty when no plan is active this turn.
+   */
+  get planBoard(): string | undefined {
+    if (!this.planEntries?.length) return undefined;
+    return renderPlanMarkdown(this.planEntries);
+  }
+
+  /** One-line plan summary for compact cards. */
+  get planSummary(): string | undefined {
+    if (!this.planEntries?.length) return undefined;
+    return renderPlanOneLine(this.planEntries);
+  }
+
+  /**
+   * Pending post-turn suggestions for switch replay / Done markup.
+   * Returns text + keyboard without clearing (taps still resolve via batch id).
+   */
+  peekPendingSuggestions():
+    | { text: string; markup: InlineKeyboard; batchId: number }
+    | undefined {
+    const p = this.pendingSuggestions;
+    if (!p?.suggestions.length) return undefined;
+    return {
+      text: p.banner,
+      markup: suggestionsKeyboard(p.batchId, p.suggestions),
+      batchId: p.batchId,
+    };
+  }
+
+  /**
+   * Session card comment:
+   *   always — last user prompt (≤250)
+   *   busy   — plus last AI agent thinking on the next line (≤250)
+   */
+  get cardComment(): string | undefined {
+    const user =
+      this.cardUserPrompt ||
+      this.sessionComment ||
+      (this.sessionId ? this.acp.sessionComment(this.sessionId) : undefined) ||
+      cleanUserPreview(this.suggestionUserText || this.turnUserText || "", COMMENT_MAX) ||
+      undefined;
+    const built = buildSessionCardComment({
+      userPrompt: user,
+      thinking: this.busy && this.cardThinking ? this.cardThinking : undefined,
+      busy: this.busy,
+    });
+    return built || undefined;
+  }
+
   /** Record a new progress value and refresh the status panel / cards. The bar
    *  is monotonic within a turn (it's reset to undefined when a new turn starts),
    *  so a streamer recreated mid-turn can't make it jump backwards. */
@@ -191,6 +392,62 @@ export class SessionRuntime {
     this.changed();
   }
 
+  /** Update the live step (tools/plan) — kept for diagnostics; cards use user+thinking. */
+  private setLiveStep(step: string | undefined): void {
+    const next = step?.trim() ? cleanCommentLine(step) : undefined;
+    if (next === this.liveStep) return;
+    this.liveStep = next;
+    this.changed();
+  }
+
+  /** Append thought text and refresh cards when the display line changes. */
+  private appendCardThinking(chunk: string): void {
+    const piece = chunk.replace(/\s+/g, " ").trim();
+    if (!piece) return;
+    const prevShown = this.cardThinking ? clampThinking(this.cardThinking, COMMENT_MAX) : "";
+    this.cardThinking = this.cardThinking ? `${this.cardThinking} ${piece}` : piece;
+    const nextShown = clampThinking(this.cardThinking, COMMENT_MAX);
+    if (nextShown !== prevShown) this.changed();
+  }
+
+  /** Persist last user prompt (disk + memory) so /running and /sessions see it. */
+  private setSessionComment(comment: string | undefined): void {
+    const next = comment?.trim()
+      ? cleanUserPreview(comment, COMMENT_MAX) || cleanCommentLine(comment, COMMENT_MAX)
+      : undefined;
+    if (next === this.sessionComment) return;
+    this.sessionComment = next;
+    if (next && this.sessionId) {
+      try {
+        this.acp.setSessionComment(this.sessionId, next);
+      } catch {
+        /* non-fatal */
+      }
+    }
+    this.changed();
+  }
+
+  /** Keep disk/memory comment = last real user prompt after a turn ends. */
+  private persistCardUserPrompt(): void {
+    const prompt =
+      this.cardUserPrompt ||
+      cleanUserPreview(this.suggestionUserText || this.turnUserText || "", COMMENT_MAX);
+    if (prompt) {
+      this.cardUserPrompt = prompt;
+      this.setSessionComment(prompt);
+    }
+  }
+
+  /** Hydrate last user prompt from disk after bind/resume. */
+  private loadPersistedComment(): void {
+    if (!this.sessionId) return;
+    const c = this.acp.sessionComment(this.sessionId);
+    if (c) {
+      this.sessionComment = c;
+      if (!this.cardUserPrompt) this.cardUserPrompt = cleanUserPreview(c, COMMENT_MAX) || c;
+    }
+  }
+
   /** Searchable hashtag footer for this session (project В· session В· model В·
    *  reasoning) — appended to every AI-output surface for this session. */
   get tags(): string {
@@ -211,7 +468,21 @@ export class SessionRuntime {
       if (this.busy && !this.streamer) {
         // Any transient follow-watch of this session is now superseded.
         if (this.watchIsFollow) this.stopWatch();
-        this.streamer = new ResponseStreamer(this.api, this.chatId, this.cfg.streamThrottleMs, this.turnReplyTo, this.hashtags(), (pct) => this.setProgress(pct), this.cfg.progressFallback, this.turnStartedAt);
+        this.streamer = new ResponseStreamer(
+          this.api,
+          this.chatId,
+          this.cfg.streamThrottleMs,
+          this.turnReplyTo,
+          this.hashtags(),
+          (pct) => this.setProgress(pct),
+          this.cfg.progressFallback,
+          this.turnStartedAt,
+          this.messageThreadId,
+        );
+        // Restore the live plan board so steps stay visible above the progress bar.
+        if (this.planEntries?.length) {
+          this.streamer.setPlan(renderPlanMarkdown(this.planEntries));
+        }
         this.typing.start();
       }
     } else {
@@ -228,13 +499,16 @@ export class SessionRuntime {
     this.changed();
   }
   get reasoning(): ReasoningEffort {
-    return this.settings.get(this.chatId).reasoning;
+    return this.settings.getKey(this.settingsKey).reasoning;
   }
   get agent(): string | undefined {
-    return this.settings.get(this.chatId).agent;
+    return this.settings.getKey(this.settingsKey).agent;
   }
   get model(): string | undefined {
-    return this.settings.get(this.chatId).model;
+    return this.settings.getKey(this.settingsKey).model;
+  }
+  get preferredAccountId(): string | undefined {
+    return this.settings.getKey(this.settingsKey).preferredAccountId;
   }
 
   /** Latest context-usage % / effort / credits for the current session. */
@@ -274,6 +548,12 @@ export class SessionRuntime {
     this.rebindPending = false;
     this.cwd = cwd;
     this.projectName = projectName;
+    this.turnCount = 0;
+    this.lastReportedCredits = 0;
+    this.liveStep = undefined;
+    this.sessionComment = undefined;
+    this.cardUserPrompt = undefined;
+    this.cardThinking = "";
     await this.applySessionPrefs();
     this.persist();
     this.sessionChanged();
@@ -298,6 +578,7 @@ export class SessionRuntime {
     this.rebindPending = false;
     this.cwd = cwd;
     this.projectName = projectName;
+    this.loadPersistedComment();
     this.persist();
     log.info(`chat ${this.chatId} -> resumed session ${sessionId} @ ${cwd}`);
     this.changed();
@@ -320,6 +601,18 @@ export class SessionRuntime {
     }
   }
 
+  /**
+   * Start a brand-new Grok session primed with a full foreign transcript
+   * (import from Kiro / OpenCode / Claude / Codex). Priming is applied on the
+   * next {@link submit} so the imported context becomes part of Grok's history.
+   */
+  async startImportedSession(cwd: string, projectName: string | undefined, priming: string): Promise<void> {
+    await this.startNewSession(cwd, projectName);
+    if (priming.trim()) this.primingContext = priming;
+    // Imported transcripts already have context — skip first-prompt directives.
+    this.markFirstPromptSteered();
+  }
+
   startWatch(jsonlPath: string, follow = false): void {
     this.stopWatch();
     this.watchIsFollow = follow;
@@ -340,7 +633,7 @@ export class SessionRuntime {
   async setModelPref(modelId: string): Promise<{ ok: boolean; error?: string }> {
     // Persist the choice always; only talk to Grok when a session is live in
     // the current process (set_model on an unloaded session crashes the agent).
-    this.settings.update(this.chatId, { model: modelId });
+    this.settings.updateKey(this.settingsKey, { model: modelId });
     if (modelId && this.sessionLive && this.sessionId) {
       if (!this.acp.hasModel(modelId)) return { ok: false, error: `unknown model: ${modelId}` };
       try {
@@ -355,7 +648,7 @@ export class SessionRuntime {
   }
 
   async setAgentPref(agent: string): Promise<void> {
-    this.settings.update(this.chatId, { agent });
+    this.settings.updateKey(this.settingsKey, { agent });
     if (agent && this.sessionLive && this.sessionId && this.acp.hasMode(agent)) {
       try {
         await this.acp.setMode(this.sessionId, agent);
@@ -367,22 +660,29 @@ export class SessionRuntime {
   }
 
   setReasoningPref(effort: ReasoningEffort): void {
-    this.settings.update(this.chatId, { reasoning: effort });
+    this.settings.updateKey(this.settingsKey, { reasoning: effort });
+    this.changed();
+  }
+
+  setPreferredAccountId(id: string | undefined): void {
+    this.settings.updateKey(this.settingsKey, { preferredAccountId: id || undefined });
+    // Force re-apply on next ensureSession when user changes preference.
+    this.preferredAccountApplied = undefined;
     this.changed();
   }
 
   private async applySessionPrefs(): Promise<void> {
-    const s = this.settings.get(this.chatId);
+    const s = this.settings.getKey(this.settingsKey);
     // Drop any persisted model the agent doesn't actually offer (an unknown id
     // is silently accepted by set_model but then breaks the next prompt).
     if (s.model && !this.acp.hasModel(s.model)) {
-      log.warn(`clearing invalid persisted model "${s.model}" for chat ${this.chatId}`);
-      this.settings.update(this.chatId, { model: "" });
+      log.warn(`clearing invalid persisted model "${s.model}" for scope ${this.settingsKey}`);
+      this.settings.updateKey(this.settingsKey, { model: "" });
     }
-    const cur = this.settings.get(this.chatId);
+    const cur = this.settings.getKey(this.settingsKey);
     // Adopt the session's current agent (mode) when the user hasn't chosen one.
     if (!cur.agent && this.acp.currentModeId) {
-      this.settings.update(this.chatId, { agent: this.acp.currentModeId });
+      this.settings.updateKey(this.settingsKey, { agent: this.acp.currentModeId });
     } else if (this.sessionId && cur.agent && this.acp.hasMode(cur.agent) && cur.agent !== this.acp.currentModeId) {
       try {
         await this.acp.setMode(this.sessionId, cur.agent);
@@ -399,7 +699,7 @@ export class SessionRuntime {
     }
   }
 
-  // в”Ђв”Ђ prompting в”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђв”Ђ
+  // ── prompting ────────────────────────────────────────────────────────────
 
   async submit(input: PromptInput): Promise<"ran" | "queued"> {
     await this.ensureSession();
@@ -408,13 +708,82 @@ export class SessionRuntime {
       this.changed();
       return "queued";
     }
+    // First-prompt steering is applied inside runTurn so queued first messages
+    // (and flushQueue) get the same complexity + telegram bridge directives.
     void this.runTurn(input);
     return "ran";
   }
 
+  private markFirstPromptSteered(): void {
+    if (!this.sessionId) return;
+    this.complexitySteered.add(this.sessionId);
+    this.telegramBridgeSteered.add(this.sessionId);
+  }
+
+  private telegramBridgeDirective(): string {
+    return buildTelegramBridgeDirective({
+      forumReady: !!this.bridge?.forum?.isReady,
+      topicGroupId: this.cfg.topicGroupId,
+      allowedBots: this.cfg.allowedTelegramBots,
+      botCommands: this.cfg.telegramBotCommands,
+    });
+  }
+
+  /**
+   * Complexity + telegram bridge teaching on the first prompt of a brand-new
+   * conversation only (no prior user turns in this process / session jsonl).
+   */
+  private applyFirstPromptSteering(input: PromptInput): PromptInput {
+    if (!this.shouldSteerFirstPrompt(input)) return input;
+    let toRun = wrapAutoComplexityPrompt(input);
+    toRun = wrapTelegramBridgePrompt(toRun, this.telegramBridgeDirective());
+    this.markFirstPromptSteered();
+    log.info(`chat ${this.chatId}: first-prompt complexity + telegram bridge applied`);
+    return toRun;
+  }
+
+  /**
+   * Apply first-prompt directives only on a brand-new conversation (no prior
+   * user turns in this process / session jsonl).
+   */
+  private shouldSteerFirstPrompt(input: PromptInput): boolean {
+    if (!this.sessionId) return false;
+    if (this.complexitySteered.has(this.sessionId) && this.telegramBridgeSteered.has(this.sessionId)) {
+      return false;
+    }
+    if (this.turnCount > 0) return false;
+    // Never wrap meta follow-ups even if somehow first.
+    if (
+      input.skipSelfRecheck ||
+      isSelfRecheckPrompt(input.text) ||
+      isTelegramBridgeResultsPrompt(input.text)
+    ) {
+      return false;
+    }
+    try {
+      const path = join(this.cfg.sessionsDir, `${this.sessionId}.jsonl`);
+      const hist = readHistory(path, 8);
+      if (hist.some((e) => e.role === "user" && e.text.trim().length > 0)) {
+        this.complexitySteered.add(this.sessionId);
+        this.telegramBridgeSteered.add(this.sessionId);
+        return false;
+      }
+    } catch {
+      /* treat as fresh */
+    }
+    return true;
+  }
+
+  /**
+   * Stop the current turn for this runtime only.
+   * Soft ACP cancel + session-scoped force-complete; never kills the shared
+   * agent (that would stop every multiplexed chat and take the bot offline).
+   */
   async cancel(): Promise<boolean> {
     if (!this.busy || !this.sessionId) return false;
     this.cancelled = true;
+    // Clear queue of follow-ups for this turn? No — only stop the active turn;
+    // queued user messages remain so the user can flush later if they want.
     await this.acp.cancel(this.sessionId);
     return true;
   }
@@ -435,6 +804,7 @@ export class SessionRuntime {
     // Account rotation restarts the process globally. Do not bind a new chat
     // to a candidate account until the owner has finished probing it.
     await this.accountRotator?.waitForIdle();
+    await this.applyPreferredAccount();
     if (this.rebindPending && this.sessionId) {
       // The ACP process is frequently mid-restart the first time we re-bind
       // (auto-restart after a crash, or a fresh bot boot), so a single attempt
@@ -459,13 +829,46 @@ export class SessionRuntime {
     if (!this.sessionId) await this.startNewSession(this.cwd, this.projectName);
   }
 
+  /** Last preferred account we successfully aligned to (avoids activate thrash). */
+  private preferredAccountApplied?: string;
+
+  /**
+   * If this scope prefers a saved account and the process is on another login,
+   * switch before binding the session. Skips when another turn is in flight
+   * (account switch restarts the agent) or we already applied this preference.
+   */
+  private async applyPreferredAccount(): Promise<void> {
+    const preferred = this.preferredAccountId;
+    const rotator = this.accountRotator;
+    if (!preferred || !rotator) return;
+    const st = rotator.state();
+    if (st.activeId === preferred) {
+      this.preferredAccountApplied = preferred;
+      return;
+    }
+    // User cleared or changed preference — allow one more activate.
+    if (this.preferredAccountApplied === preferred) return;
+    if (this.acp.hasInflightPrompt()) {
+      log.debug(`scope ${this.settingsKey}: skip preferred account (turn in flight)`);
+      return;
+    }
+    try {
+      await rotator.activate(preferred);
+      this.preferredAccountApplied = preferred;
+      log.info(`scope ${this.settingsKey}: activated preferred account ${preferred.slice(0, 8)}`);
+    } catch (e) {
+      log.debug(`preferred account activate failed: ${(e as Error).message}`);
+    }
+  }
+
   /** Reload a persisted session, retrying flaky failures with a short backoff.
    *  Returns true once loaded, false after the attempts are exhausted. */
   private async rebindWithRetries(sessionId: string, attempts = 4): Promise<boolean> {
-    const delays = [400, 1200, 3000]; // ≈4.6s total before giving up
+    const delays = [400, 1200, 3000]; // ~4.6s total before giving up
     for (let i = 0; i < attempts; i++) {
       try {
         await this.acp.loadSession(sessionId, this.cwd);
+        this.loadPersistedComment();
         return true;
       } catch (err) {
         log.warn(
@@ -498,13 +901,63 @@ export class SessionRuntime {
   }
 
   private async runTurn(input: PromptInput): Promise<void> {
+    // Apply before any turn bookkeeping so card previews / logs see the wrapped
+    // text the same way the agent does (also covers flushQueue first messages).
+    input = this.applyFirstPromptSteering(input);
+
     this.busy = true;
     this.cancelled = false;
     this.turnReplyTo = input.replyTo;
+    this.turnPromptId = input.promptId;
+    this.turnUserText = input.text;
+    this.turnAssistantText = "";
+    this.cardThinking = "";
+    this.turnExpectDone = false;
+    this.turnDonePinged = false;
+    this.isSelfRecheckTurn = isSelfRecheckPrompt(input.text);
+    // Meta turns (recheck, bridge results, auto-suggestion batches) never arm another recheck.
+    const isBridgeResults = isTelegramBridgeResultsPrompt(input.text);
+    this.skipSelfRecheck =
+      !!input.skipSelfRecheck ||
+      this.isSelfRecheckTurn ||
+      isBridgeResults;
+    // Fresh user work resets bridge-chain depth + suggestion anchors.
+    if (!this.isSelfRecheckTurn && !isBridgeResults) {
+      this.bridgeResultDepth = 0;
+    }
+    // Fresh user work resets suggestion anchors; recheck / bridge results keep the original ask.
+    // Strip complexity/reply wrappers so suggestions + recheck see the real ask.
+    if (!this.isSelfRecheckTurn && !isBridgeResults) {
+      this.suggestionUserText = stripDirectiveWrappers(input.text) || input.text;
+      this.preRecheckAssistantText = "";
+      this.preRecheckFileOps = new Map();
+      // Card comment: last real user prompt (not self-recheck / empty meta).
+      const preview = input.text.trim()
+        ? cleanUserPreview(input.text, COMMENT_MAX)
+        : input.images.length
+          ? "Attached image(s)"
+          : "";
+      if (preview) {
+        this.cardUserPrompt = preview;
+        this.setSessionComment(preview);
+      }
+    }
     this.shownToolIds = new Set();
+    this.toolCallCache = new Map();
     this.fileOps = new Map();
     this.subagentShown = new Map();
     this.progress = undefined; // a new turn = a new task; clear the old bar
+    this.planEntries = undefined; // plan board is per-turn
+    this.pendingSuggestions = undefined; // new work supersedes previous Done suggestions
+    this.setLiveStep(
+      this.isSelfRecheckTurn
+        ? "Self-recheck: hunting bugs / incomplete logic\u2026"
+        : input.text.trim()
+          ? `Working: ${cleanUserPreview(input.text, 110)}`
+          : input.images.length
+            ? "Working on attached image(s)\u2026"
+            : "Working\u2026",
+    );
     // A new streamed turn supersedes any transient "follow" watch of this same
     // session's previous in-flight turn (avoids duplicated output).
     if (this.watchIsFollow) this.stopWatch();
@@ -512,7 +965,17 @@ export class SessionRuntime {
     const startedAt = Date.now();
     this.turnStartedAt = startedAt;
     this.streamer = live
-      ? new ResponseStreamer(this.api, this.chatId, this.cfg.streamThrottleMs, this.turnReplyTo, this.hashtags(), (pct) => this.setProgress(pct), this.cfg.progressFallback, startedAt)
+      ? new ResponseStreamer(
+          this.api,
+          this.chatId,
+          this.cfg.streamThrottleMs,
+          this.turnReplyTo,
+          this.hashtags(),
+          (pct) => this.setProgress(pct),
+          this.cfg.progressFallback,
+          startedAt,
+          this.messageThreadId,
+        )
       : undefined;
     if (live) this.typing.start();
     this.activity(true);
@@ -545,40 +1008,292 @@ export class SessionRuntime {
       if (resumed) final = resumed;
       const streamedOutput = this.streamer?.hasOutput ?? false;
       // On a successful, non-cancelled turn, top the fallback bar up to 100 (a
-      // no-op when the agent reported its own progress — its value is kept).
+      // no-op when the agent reported its own progress — its value is kept).
       if (final.result && !this.cancelled) this.streamer?.completeFallback();
       if (this.streamer) await this.streamer.finalize();
       if (this.foreground) await this.sendTurnImages();
+
+      // Telegram bridge actions (JSON fences in the agent reply). Process on
+      // normal turns AND bridge-results follow-ups so multi-step bot_command /
+      // search chains work; depth cap prevents infinite loops.
+      let queuedBridgeResults = false;
+      if (final.result && !this.cancelled) {
+        queuedBridgeResults = await this.processTelegramBridgeActions();
+      }
+
       // Always build the completion (records `lastCompletion` so switching back
       // to this session can replay its Done + summary). Only PING the chat for
       // the foreground turn, or a background turn when NOTIFY_OTHER_SESSIONS is on.
       const canPing = this.foreground || this.cfg.notifyOtherSessions;
       // A background session about to run a queued follow-up shouldn't ping its
-      // interim "Done" — only the final, queue-empty turn announces completion.
+      // interim "Done" — only the final, queue-empty turn announces completion.
       const hasQueued = this.queue.length > 0;
       const switchKb = this.switchKeyboard();
-      if (final.result && !this.cancelled) this.turnCount++;
+      if (final.result && !this.cancelled) {
+        this.turnCount++;
+        // Persist real per-account usage (turns + reported credits) for /accounts and /usage.
+        this.recordAccountUsage();
+        // Card comment: last user prompt (thinking cleared when idle).
+        this.persistCardUserPrompt();
+        this.cardThinking = "";
+        // Keep live step while bridge/sibling-bot results are still queued —
+        // clearing here made "Waiting for bot" vanish before the interim notify.
+        if (!queuedBridgeResults) this.setLiveStep(undefined);
+      } else if (this.cancelled) {
+        this.persistCardUserPrompt();
+        this.cardThinking = "";
+        this.setLiveStep(undefined);
+      } else if (final.error) {
+        this.persistCardUserPrompt();
+        this.cardThinking = "";
+        this.setLiveStep(undefined);
+      }
       if (final.result || this.cancelled) {
-        const live = this.completionMessage(final.result?.stopReason, startedAt, streamedOutput);
-        const pingDone = canPing && (this.foreground || !hasQueued);
-        if (pingDone) await this.notify(live, { loud: true, replyTo: this.turnReplyTo, replyMarkup: switchKb });
+        // Bridge results in the queue mean "not Done yet" — never treat as a
+        // completion ping even in the foreground. Do not post bridge status
+        // spam to the chat (live step / status panel only).
+        const pingDone =
+          canPing && (this.foreground || !hasQueued) && !queuedBridgeResults;
+        // Expect a Done this turn unless we defer for recheck (bridge already excluded).
+        this.turnExpectDone = pingDone;
+
+        // One-shot self-recheck: only after a real *user* turn (not meta/auto),
+        // with idle queue. skipSelfRecheck blocks loops after recheck / auto-batch.
+        // Also skipped when no files were modified, or when a quiet AI decision
+        // refuses (simple tasks, pure build, nothing worth re-verifying).
+        // Delay recheck/Done when bridge results are queued (like self-recheck).
+        const wantSelfRecheck =
+          !!final.result &&
+          !this.cancelled &&
+          !hasQueued &&
+          !queuedBridgeResults &&
+          this.cfg.selfRecheckEnabled &&
+          !this.skipSelfRecheck &&
+          !this.isSelfRecheckTurn;
+
+        let queuedRecheck = false;
+        if (wantSelfRecheck) {
+          this.preRecheckAssistantText = this.turnAssistantText;
+          // Strip COMPLEXITY wrapper so recheck + suggestions see the real ask.
+          this.suggestionUserText = stripDirectiveWrappers(this.turnUserText) || this.turnUserText;
+          this.preRecheckFileOps = cloneFileOps(this.fileOps);
+          this.setLiveStep("Deciding if self-recheck is needed\u2026");
+          this.changed();
+          // Visible chat status so stream-complete is not mistaken for a silent exit.
+          if (pingDone) {
+            await this.notify(
+              "\u{1F50D} Checking if a quality pass is needed\u2026",
+              { loud: true, replyTo: this.turnReplyTo },
+            );
+          }
+          const recheck = await this.maybePlanSelfRecheck();
+          this.setLiveStep(undefined);
+          // User may cancel during the quiet decision call — first turn still
+          // succeeded; never queue a recheck after cancel.
+          if (this.cancelled) {
+            this.preRecheckFileOps = new Map();
+            this.preRecheckAssistantText = "";
+          } else if (recheck) {
+            queuedRecheck = true;
+            this.turnExpectDone = false; // final Done comes after the recheck turn
+            // Front of queue; mark skip so the recheck turn never re-arms itself.
+            this.queue.unshift(
+              textPrompt(recheck, this.turnReplyTo, undefined, {
+                skipSelfRecheck: true,
+                promptId: this.turnPromptId,
+              }),
+            );
+            this.changed();
+            if (pingDone) {
+              // Interim status + first-turn file list (final Done comes after recheck).
+              const firstFiles = summarizeFileOps(this.preRecheckFileOps, this.cwd);
+              await this.notify(
+                `\u{1F50D} Self-recheck \u2014 bugs, logic gaps, related follow-through (once)\u2026\n\n` +
+                  `\u{1F4C1} After first turn\n${firstFiles}`,
+                { loud: true, replyTo: this.turnReplyTo, replyMarkup: switchKb },
+              );
+            }
+          } else {
+            // No recheck — clear frozen first-turn ops (nothing to split later).
+            this.preRecheckFileOps = new Map();
+            this.preRecheckAssistantText = "";
+          }
+        }
+
+        if (!queuedRecheck && !queuedBridgeResults) {
+          // Build Done text *now* (after quiet decision) so a cancel during the
+          // recheck-decision wait shows ⏹ Stopped, not a stale ✅ Done head.
+          let doneText = this.isSelfRecheckTurn
+            ? this.completionMessageSplit(final.result?.stopReason, startedAt, streamedOutput)
+            : this.completionMessage(final.result?.stopReason, startedAt, streamedOutput);
+          // 1) Always send Done FIRST — never block the completion ping on the
+          // quiet suggestions prompt (which can hang and look like "no Done").
+          let doneMsgId: number | undefined;
+          if (pingDone) {
+            doneMsgId = await this.notify(doneText, {
+              loud: true,
+              replyTo: this.turnReplyTo,
+              replyMarkup: switchKb,
+            });
+            if (doneMsgId !== undefined) this.turnDonePinged = true;
+          }
+          // 2) Suggestions after Done: edit the Done message (or send a follow-up).
+          if (final.result && !this.cancelled && !hasQueued) {
+            try {
+              const sug = await this.collectAndApplySuggestions(doneText, switchKb, {
+                // Only auto-queue high-need follow-ups when the user is watching;
+                // background sessions store buttons for the Done ping / switch replay.
+                autoQueue: this.foreground,
+              });
+              // Only enhance when suggestions actually changed the Done body.
+              if (pingDone && sug.text !== doneText) {
+                await this.enhanceDoneMessage(doneMsgId, sug.text, sug.markup ?? switchKb);
+              }
+            } catch (e) {
+              log.debug(`suggestions after Done failed: ${(e as Error).message}`);
+            }
+          }
+          // Clear frozen first-turn ops after final Done (recheck path done).
+          if (this.isSelfRecheckTurn) this.preRecheckFileOps = new Map();
+        }
+        // queuedBridgeResults: stay quiet in chat — agent gets results via queue.
       } else if (final.error) {
-        const transient = isTransientError(final.error);
-        const live = this.errorMessage(final.error, startedAt, final.attempts, transient);
-        if (canPing) await this.notify(live, { loud: true, replyTo: this.turnReplyTo, replyMarkup: switchKb });
+        // If the self-recheck pass itself failed, still surface Done for the
+        // original work (split files + suggestions) so the user is not stuck.
+        if (this.isSelfRecheckTurn && !hasQueued) {
+          const switchKb = this.switchKeyboard();
+          const pingDone = canPing && (this.foreground || !hasQueued);
+          this.turnExpectDone = pingDone;
+          let doneText =
+            this.completionMessageSplit(undefined, startedAt, streamedOutput) +
+            `\n\n\u26A0\uFE0F Self-recheck failed: ${final.error.message}`;
+          let doneMsgId: number | undefined;
+          if (pingDone) {
+            doneMsgId = await this.notify(doneText, {
+              loud: true,
+              replyTo: this.turnReplyTo,
+              replyMarkup: switchKb,
+            });
+            if (doneMsgId !== undefined) this.turnDonePinged = true;
+          }
+          if (!this.cancelled) {
+            try {
+              const sug = await this.collectAndApplySuggestions(doneText, switchKb, {
+                autoQueue: this.foreground,
+              });
+              if (pingDone && sug.text !== doneText) {
+                await this.enhanceDoneMessage(doneMsgId, sug.text, sug.markup ?? switchKb);
+              }
+            } catch (e) {
+              log.debug(`suggestions after recheck-fail Done failed: ${(e as Error).message}`);
+            }
+          }
+          this.preRecheckFileOps = new Map();
+        } else {
+          const transient = isTransientError(final.error);
+          const liveMsg = this.errorMessage(final.error, startedAt, final.attempts, transient);
+          this.turnExpectDone = canPing;
+          if (canPing) {
+            const id = await this.notify(liveMsg, {
+              loud: true,
+              replyTo: this.turnReplyTo,
+              replyMarkup: switchKb,
+            });
+            if (id !== undefined) this.turnDonePinged = true;
+          }
+        }
       }
     } catch (err) {
       // Unexpected failure outside the prompt path (e.g. while finalizing).
       await this.streamer?.finalize().catch(() => {});
-      const msg = `\u274C Error after ${fmtDuration(Date.now() - startedAt)}: ${(err as Error).message}`;
-      this.lastCompletion = msg;
-      if (this.foreground || this.cfg.notifyOtherSessions) {
-        const from = this.foreground ? "" : `\u{1F4E8} From other session ${this.sessionTag()}\n`;
-        await this.notify(`${from}${msg}`, { loud: true, replyTo: this.turnReplyTo, replyMarkup: this.switchKeyboard() });
+      const errMsg = (err as Error).message;
+      this.persistCardUserPrompt();
+      this.cardThinking = "";
+      this.setLiveStep(undefined);
+      // If the self-recheck pass itself blew up, still surface Done for the
+      // original work (split files + suggestions) so the user is not stuck.
+      if (this.isSelfRecheckTurn && this.queue.length === 0) {
+        const switchKb = this.switchKeyboard();
+        const canPing = this.foreground || this.cfg.notifyOtherSessions;
+        this.turnExpectDone = canPing;
+        let doneText =
+          this.completionMessageSplit(undefined, startedAt, this.streamer?.hasOutput ?? false) +
+          `\n\n\u26A0\uFE0F Self-recheck failed: ${errMsg}`;
+        try {
+          let doneMsgId: number | undefined;
+          if (canPing) {
+            doneMsgId = await this.notify(doneText, {
+              loud: true,
+              replyTo: this.turnReplyTo,
+              replyMarkup: switchKb,
+            });
+            if (doneMsgId !== undefined) this.turnDonePinged = true;
+          }
+          if (!this.cancelled) {
+            try {
+              const sug = await this.collectAndApplySuggestions(doneText, switchKb, {
+                autoQueue: this.foreground,
+              });
+              if (canPing && sug.text !== doneText) {
+                await this.enhanceDoneMessage(doneMsgId, sug.text, sug.markup ?? switchKb);
+              }
+            } catch (e2) {
+              log.debug(`suggestions after recheck catch failed: ${(e2 as Error).message}`);
+            }
+          }
+        } catch (e2) {
+          log.debug(`recheck catch recovery failed: ${(e2 as Error).message}`);
+          if (canPing && !this.turnDonePinged) {
+            const id = await this.notify(doneText, {
+              loud: true,
+              replyTo: this.turnReplyTo,
+              replyMarkup: switchKb,
+            });
+            if (id !== undefined) this.turnDonePinged = true;
+          }
+        }
+        this.preRecheckFileOps = new Map();
+      } else {
+        const msg = `\u274C Error after ${fmtDuration(Date.now() - startedAt)}: ${errMsg}`;
+        this.lastCompletion = msg;
+        const canPing = this.foreground || this.cfg.notifyOtherSessions;
+        this.turnExpectDone = canPing;
+        if (canPing) {
+          const from = this.foreground ? "" : `\u{1F4E8} From other session ${this.sessionTag()}\n`;
+          const id = await this.notify(`${from}${msg}`, {
+            loud: true,
+            replyTo: this.turnReplyTo,
+            replyMarkup: this.switchKeyboard(),
+          });
+          if (id !== undefined) this.turnDonePinged = true;
+        }
       }
     } finally {
+      // Safety net: turn completed with an expected Done ping that never landed
+      // (notify failed, hung path, etc.). Never block queue flush on this.
+      if (this.turnExpectDone && !this.turnDonePinged) {
+        const fallback =
+          this.lastCompletion?.trim() ||
+          `\u2705 Done \u00B7 ${fmtDuration(Date.now() - startedAt)}`;
+        const short =
+          fallback.length > 3500 ? fallback.slice(0, 3499) + "\u2026" : fallback;
+        try {
+          const id = await this.notify(short, {
+            loud: true,
+            replyTo: this.turnReplyTo,
+            replyMarkup: this.switchKeyboard(),
+          });
+          if (id !== undefined) this.turnDonePinged = true;
+          else log.warn(`chat ${this.chatId}: Done safety-net notify failed`);
+        } catch (e) {
+          log.warn(`chat ${this.chatId}: Done safety-net error: ${(e as Error).message}`);
+        }
+      }
+      this.turnExpectDone = false;
       this.typing.stop();
       this.streamer = undefined;
+      this.capturingQuiet = false;
+      this.quietCaptureBuf = "";
       this.busy = false;
       this.activity(false);
       // The in-flight turn we may have been following live is over.
@@ -587,6 +1302,10 @@ export class SessionRuntime {
       // the bar is removed from the status panel, session cards and switch
       // messages. The finished streamed bubble keeps its own (frozen) bar.
       this.progress = undefined;
+      this.planEntries = undefined;
+      // Idle cards show last user prompt only (clear live step / thinking).
+      this.cardThinking = "";
+      if (!this.liveStep || this.sessionComment) this.liveStep = undefined;
       this.changed();
     }
 
@@ -601,6 +1320,320 @@ export class SessionRuntime {
     }
   }
 
+  /**
+   * Parse telegram JSON actions from the assistant reply, execute them, notify
+   * the user, and queue a results follow-up for the agent when useful.
+   * Returns true when a results prompt was queued (delay Done/recheck).
+   */
+  private async processTelegramBridgeActions(): Promise<boolean> {
+    const { actions, cleaned } = extractTelegramActions(this.turnAssistantText);
+    if (cleaned !== this.turnAssistantText) {
+      this.turnAssistantText = cleaned;
+    }
+    if (actions.length === 0) return false;
+    if (!this.bridge) {
+      log.warn(`chat ${this.chatId}: telegram actions present but bridge not wired`);
+      return false;
+    }
+
+    const botCmds = actions.filter((a) => a.action === "bot_command");
+    // bot_command means Grok ended its turn early to wait on a sibling bot —
+    // this is NOT a Done. Keep busy; status panel live-step only (no chat spam).
+    if (botCmds.length > 0) {
+      const labels = botCmds
+        .map((a) =>
+          a.action === "bot_command" ? `@${a.bot} /${a.command}` : "",
+        )
+        .filter(Boolean)
+        .join(", ");
+      this.setLiveStep(`Waiting for sibling bot: ${labels}`);
+    } else {
+      this.setLiveStep("Running Telegram bridge actions\u2026");
+    }
+    this.changed();
+    log.info(`chat ${this.chatId}: executing ${actions.length} telegram bridge action(s)`);
+
+    const results = await executeTelegramActions(actions, {
+      api: this.api,
+      cfg: this.cfg,
+      chatId: this.chatId,
+      messageThreadId: this.messageThreadId,
+      forum: this.bridge.forum,
+      store: this.bridge.store,
+      bots: this.bridge.bots,
+      submitTopicPrompt: this.bridge.submitTopicPrompt,
+    });
+
+    // Only announce durable side-effects in chat (topic create/bind/cross-prompt).
+    // search_memory / list_bots / bot wait status stay silent — results go to the agent.
+    const durableActions = new Set(["create_topic", "set_path", "send_prompt"]);
+    const notes = results
+      .filter((r) => durableActions.has(r.action) && r.userNote?.trim())
+      .map((r) => r.userNote!)
+      .filter(Boolean);
+    if (notes.length > 0 && this.foreground) {
+      await this.notify(notes.join("\n"), {
+        loud: true,
+        replyTo: this.turnReplyTo,
+      });
+    }
+
+    // Cap chained result turns so a model that re-emits list_bots forever cannot
+    // block Done. Side-effects already ran; user notes were sent above.
+    // Still queue once when we have bot_command errors so the agent can recover.
+    if (this.bridgeResultDepth >= SessionRuntime.BRIDGE_CHAIN_MAX) {
+      log.warn(
+        `chat ${this.chatId}: telegram bridge chain depth ${this.bridgeResultDepth} — not re-queuing results`,
+      );
+      return false;
+    }
+
+    // Feed results back so the agent can use search hits / bot replies / errors.
+    const prompt = buildTelegramBridgeResultsPrompt(
+      results.map((r) => ({
+        action: r.action,
+        ok: r.ok,
+        data: r.data,
+        error: r.error,
+      })),
+    );
+    this.bridgeResultDepth++;
+    this.queue.unshift(
+      textPrompt(prompt, this.turnReplyTo, undefined, {
+        skipSelfRecheck: true,
+        promptId: this.turnPromptId,
+      }),
+    );
+    this.setLiveStep("Feeding sibling-bot / bridge results to the agent\u2026");
+    this.changed();
+    return true;
+  }
+
+  /**
+   * Quietly ask for 1–3 follow-ups, attach buttons to the Done text, store them
+   * for switch-replay, and optionally queue auto-approved items as **one**
+   * numbered multi-step prompt (`1) …\n2) …`).
+   */
+  private async collectAndApplySuggestions(
+    doneText: string,
+    switchKb: InlineKeyboard | undefined,
+    opts?: { autoQueue?: boolean },
+  ): Promise<{ text: string; markup?: InlineKeyboard }> {
+    if (!this.cfg.suggestionsEnabled || !this.sessionId) {
+      return { text: doneText, markup: switchKb };
+    }
+    let suggestions: Suggestion[] = [];
+    try {
+      suggestions = await this.fetchSuggestionsQuiet();
+    } catch (e) {
+      log.debug(`suggestions fetch failed: ${(e as Error).message}`);
+    }
+    if (suggestions.length === 0) return { text: doneText, markup: switchKb };
+
+    const batchId = ++this.suggestionBatchSeq;
+    this.suggestionBatches.set(batchId, suggestions);
+    // Bound memory: keep last ~20 batches.
+    if (this.suggestionBatches.size > 20) {
+      const oldest = [...this.suggestionBatches.keys()].sort((a, b) => a - b)[0]!;
+      this.suggestionBatches.delete(oldest);
+    }
+
+    const thr = this.cfg.suggestionsAutoApprovePct;
+    const autoQueue = opts?.autoQueue !== false;
+    const auto = autoQueue ? autoApproveSuggestions(suggestions, thr) : [];
+    let text = doneText;
+    let banner: string;
+    if (auto.length > 0) {
+      const batched = formatBatchedSuggestionsPrompt(auto);
+      const lines = auto.map((s, i) => `  ${i + 1}) ${s.need}% \u2014 ${s.text}`);
+      const autoBlock =
+        `\n\n\u{1F4A1} Auto-running ${auto.length} suggestion${auto.length === 1 ? "" : "s"}` +
+        ` as one prompt (\u2265 ${thr}% need):\n${lines.join("\n")}`;
+      text += autoBlock;
+      banner = `\u{1F4A1} Suggestions (auto-running ${auto.length} as one prompt):\n${lines.join("\n")}`;
+      // Single queue entry — agent executes 1) 2) 3) in one turn.
+      // skipSelfRecheck: auto-follow-ups must not arm another recheck cycle.
+      this.queue.push(
+        textPrompt(batched, this.turnReplyTo, undefined, {
+          skipSelfRecheck: true,
+          promptId: this.turnPromptId,
+        }),
+      );
+      this.changed();
+    } else {
+      text += "\n\n\u{1F4A1} Suggestions \u2014 tap one to continue:";
+      banner = "\u{1F4A1} Suggestions \u2014 tap one to continue:";
+    }
+
+    // Keep for switch-to-session replay (and for Done pings that already include
+    // the same keyboard). Cleared when a new turn starts.
+    this.pendingSuggestions = { batchId, suggestions, banner };
+
+    const markup = suggestionsKeyboard(batchId, suggestions, switchKb);
+    return { text, markup };
+  }
+
+  /**
+   * Decide whether to queue a self-recheck turn.
+   * - Hard skip when no files were modified this turn.
+   * - Quiet AI decision: refuse (simple / not needed) or write recheck prompt.
+   * - Returns the full recheck turn text, or undefined to skip.
+   */
+  private async maybePlanSelfRecheck(): Promise<string | undefined> {
+    if (this.fileOps.size === 0) {
+      log.info(`chat ${this.chatId}: self-recheck skipped (no files modified)`);
+      return undefined;
+    }
+    if (this.cancelled) return undefined;
+    const user =
+      this.suggestionUserText ||
+      stripDirectiveWrappers(this.turnUserText) ||
+      this.turnUserText;
+    const did = this.turnAssistantText;
+    const files = summarizeFileOpsShort(this.fileOps);
+
+    let decision;
+    try {
+      decision = await this.fetchSelfRecheckDecisionQuiet(user, did, files);
+    } catch (e) {
+      log.debug(`self-recheck decision failed: ${(e as Error).message}; skipping`);
+      return undefined;
+    }
+    if (this.cancelled) return undefined;
+    if (!decision.needed) {
+      log.info(
+        `chat ${this.chatId}: self-recheck skipped by agent` +
+          (decision.reason ? ` (${decision.reason})` : ""),
+      );
+      return undefined;
+    }
+
+    // Optional env template overrides the AI-written body when set.
+    if (this.cfg.selfRecheckPrompt) {
+      return buildSelfRecheckPrompt(user, did, this.cfg.selfRecheckPrompt);
+    }
+    if (decision.prompt.trim()) {
+      return composeSelfRecheckTurn(decision.prompt, user, did);
+    }
+    // needed=true but empty prompt — fall back to built-in default template.
+    return buildSelfRecheckPrompt(user, did);
+  }
+
+  /** Quiet JSON: should we recheck, and if so what prompt? Never streams. */
+  private async fetchSelfRecheckDecisionQuiet(
+    user: string,
+    did: string,
+    filesSummary: string,
+  ): Promise<ReturnType<typeof parseSelfRecheckDecision>> {
+    if (!this.sessionId) return { needed: false, reason: "no session" };
+    const prompt = buildSelfRecheckDecisionPrompt(user, did, filesSummary);
+    try {
+      const raw = await this.runQuietPrompt(prompt);
+      return parseSelfRecheckDecision(raw);
+    } catch (e) {
+      log.debug(`self-recheck decision quiet prompt failed: ${(e as Error).message}`);
+      return { needed: false, reason: "decision prompt failed" };
+    }
+  }
+
+  /** Quiet JSON suggestion turn — never streams to Telegram. */
+  private async fetchSuggestionsQuiet(): Promise<Suggestion[]> {
+    if (!this.sessionId) return [];
+    // Prefer the original user ask (before self-recheck) so need scores stay honest.
+    const user =
+      this.suggestionUserText ||
+      stripDirectiveWrappers(this.turnUserText) ||
+      this.turnUserText;
+    const didParts = [this.preRecheckAssistantText, this.turnAssistantText].filter((s) => s?.trim());
+    const did = didParts.join("\n") || this.turnAssistantText;
+    const prompt = buildSuggestionsPrompt(user, did);
+    try {
+      const raw = await this.runQuietPrompt(prompt);
+      return parseSuggestions(raw);
+    } catch (e) {
+      log.debug(`suggestions quiet prompt failed: ${(e as Error).message}`);
+      return [];
+    }
+  }
+
+  /**
+   * Run a quiet meta ACP prompt (JSON only) with a hard timeout.
+   * On timeout: session/cancel so the shared agent is not stuck holding the
+   * session (which would block Done forever). Does NOT set this.cancelled
+   * (user /stop is separate). Timed-out / partial capture is discarded.
+   */
+  private async runQuietPrompt(text: string): Promise<string> {
+    if (!this.sessionId) return "";
+    const ms = Math.max(5_000, this.cfg.quietPromptTimeoutMs || 90_000);
+    this.capturingQuiet = true;
+    this.quietCaptureBuf = "";
+    let timedOut = false;
+    let settled = false;
+    const timer = setTimeout(() => {
+      // Ignore timer if the prompt already settled (avoids discarding a good JSON
+      // reply that finished in the same tick as the timeout).
+      if (settled) return;
+      timedOut = true;
+      log.warn(
+        `chat ${this.chatId}: quiet meta prompt timed out after ${ms}ms — cancelling session prompt`,
+      );
+      // Session-scoped cancel only — never kill the shared agent process.
+      void this.acp.cancel(this.sessionId!);
+    }, ms);
+    let buf = "";
+    try {
+      await this.acp.prompt(this.sessionId, [{ type: "text", text }]);
+      settled = true;
+      clearTimeout(timer);
+      buf = this.quietCaptureBuf;
+    } catch (e) {
+      settled = true;
+      clearTimeout(timer);
+      buf = this.quietCaptureBuf;
+      if (!timedOut) throw e;
+      log.debug(`quiet prompt ended after timeout: ${(e as Error).message}`);
+    } finally {
+      clearTimeout(timer);
+      this.capturingQuiet = false;
+      this.quietCaptureBuf = "";
+    }
+    // Timed-out meta replies are often half-JSON — skip rather than act on garbage.
+    // If we settled successfully before the timer fired, timedOut stays false.
+    if (timedOut) return "";
+    return buf;
+  }
+
+  /** Resolve a tapped suggestion button; returns the prompt text or undefined. */
+  takeSuggestion(batchId: number, index: number): string | undefined {
+    const batch = this.suggestionBatches.get(batchId);
+    if (!batch) return undefined;
+    const s = batch[index];
+    if (!s) return undefined;
+    return s.text;
+  }
+
+  /** Attribute a finished turn's credits/context to the active saved account. */
+  private recordAccountUsage(): void {
+    const meta = this.contextInfo();
+    // Grok's metadata credits are typically a running session total — store the
+    // per-turn delta so /accounts totals stay accurate across many turns.
+    let turnCredits: number | undefined;
+    if (typeof meta?.credits === "number" && Number.isFinite(meta.credits)) {
+      const delta = meta.credits - this.lastReportedCredits;
+      turnCredits = delta > 0 ? delta : meta.credits > 0 && this.lastReportedCredits === 0 ? meta.credits : undefined;
+      if (meta.credits >= this.lastReportedCredits) this.lastReportedCredits = meta.credits;
+      else this.lastReportedCredits = meta.credits; // reset if agent restarted counters
+    }
+    try {
+      this.accountRotator?.recordTurnUsage({
+        credits: turnCredits,
+        contextPct: meta?.contextUsagePercentage,
+      });
+    } catch {
+      /* non-fatal */
+    }
+  }
+
   /**
    * Show subagent ("crew") status transitions for the given (already
    * chat-attributed) subagents, so the user sees progress while the main agent
@@ -874,6 +1907,11 @@ export class SessionRuntime {
       try {
         const updatesBeforePrompt = this.sessionUpdateCount;
         const result = await this.acp.prompt(this.sessionId!, content);
+        // User /stop force-complete or agent honouring session/cancel often
+        // returns cancelled with zero session/update chunks — that is success.
+        if (this.cancelled || result?.stopReason === "cancelled") {
+          return { result: result ?? { stopReason: "cancelled" }, attempts: attempt };
+        }
         // A healthy ACP turn emits at least one session/update (text, thought,
         // or tool event) before resolving session/prompt. Grok can otherwise
         // report a successful end-turn after an upstream model failure; never
@@ -999,6 +2037,7 @@ export class SessionRuntime {
         already: this.sentImagesThisTurn,
         max: this.cfg.agentImagesMax,
         replyTo: this.turnReplyTo,
+        messageThreadId: this.messageThreadId,
       });
       if (n > 0) log.info(`chat ${this.chatId}: sent ${n} agent image file(s)`);
     } catch {
@@ -1022,6 +2061,28 @@ export class SessionRuntime {
     return `\u{1F4E8} From other session ${this.sessionTag()}\n${head}\n${summarizeFileOpsShort(this.fileOps)}\n\n${tags}`;
   }
 
+  /**
+   * Final Done after a self-recheck: head + split file lists (first turn vs recheck).
+   */
+  private completionMessageSplit(
+    stopReason: string | undefined,
+    startedAt: number,
+    streamedOutput: boolean,
+  ): string {
+    const head = this.doneHead(stopReason, startedAt, streamedOutput);
+    const tags = this.hashtags();
+    const files = summarizeFileOpsSplit(this.preRecheckFileOps, this.fileOps, this.cwd);
+    const base = `${head}\n${files}`;
+    this.lastCompletion = `${base}\n\n${tags}`;
+    if (this.foreground) {
+      return streamedOutput ? base : `${base}\n\n${tags}`;
+    }
+    return (
+      `\u{1F4E8} From other session ${this.sessionTag()}\n${head}\n` +
+      `${summarizeFileOpsShort(this.preRecheckFileOps)} \u2192 recheck ${summarizeFileOpsShort(this.fileOps)}\n\n${tags}`
+    );
+  }
+
   /** The compact one-line status of a finished turn (no "end_turn" noise). */
   private doneHead(stopReason: string | undefined, startedAt: number, streamedOutput: boolean): string {
     const elapsed = fmtDuration(Date.now() - startedAt);
@@ -1066,19 +2127,35 @@ export class SessionRuntime {
   }
 
   /** Searchable Telegram hashtags so you can pull up every message of a session
-   *  or project by tapping the tag. */
+   *  or project (and this turn's prompt) by tapping the tag. */
   private hashtags(): string {
     return sessionHashtags({
       projectName: this.projectName,
       cwd: this.cwd,
       sessionId: this.sessionId,
+      promptId: this.turnPromptId,
     });
   }
 
   private async flushQueue(): Promise<void> {
     if (this.queue.length === 0 || this.busy) return;
-    const batch = mergeInputs(this.queue.splice(0, this.queue.length));
-    if (this.foreground) await this.notify("\u25B6\uFE0F Processing queued message\u2026");
+    // Meta / system turns (self-recheck, auto-suggestion batches) must run
+    // alone: merging them with user messages corrupts the prompt and can drop
+    // the one-shot skipSelfRecheck guard via text concatenation.
+    const head = this.queue[0]!;
+    const isMeta =
+      !!head.skipSelfRecheck ||
+      isSelfRecheckPrompt(head.text) ||
+      isTelegramBridgeResultsPrompt(head.text);
+    const batch = isMeta
+      ? this.queue.shift()!
+      : mergeInputs(this.queue.splice(0, this.queue.length));
+    // Real user follow-ups only — never spam chat for bridge/recheck meta turns.
+    if (this.foreground && !isMeta) {
+      await this.notify("\u25B6\uFE0F Processing queued message\u2026", {
+        replyTo: batch.replyTo,
+      });
+    }
     void this.runTurn(batch);
   }
 
@@ -1087,36 +2164,76 @@ export class SessionRuntime {
     this.sessionUpdateCount++;
     const kind = update.sessionUpdate;
 
+    // Quiet meta turns (follow-up suggestions): capture prose only, never stream.
+    if (this.capturingQuiet) {
+      if (kind === "agent_message_chunk") {
+        const text = contentText(update.content);
+        if (text) this.quietCaptureBuf += text;
+      }
+      return;
+    }
+
     // Accumulate the turn's file-change summary + image-scan text even when this
     // session is in the background (its output isn't streamed here, but the
     // completion message still reports what changed / which images were made).
     if (kind === "tool_call" || kind === "tool_call_update") {
-      if (update.rawInput) this.imageScanText += " " + JSON.stringify(update.rawInput);
-      if (update.title) this.imageScanText += " " + update.title;
-      // Tool results often carry the saved path only in content_blocks (Imagine).
-      if (Array.isArray(update.content_blocks)) {
-        this.imageScanText += " " + JSON.stringify(update.content_blocks);
+      // Merge early so background live-step + file ops use full title/args.
+      const tid = update.toolCallId || "";
+      const mergedEarly = mergeToolSnapshot(tid ? this.toolCallCache.get(tid) : undefined, update);
+      if (tid) this.toolCallCache.set(tid, mergedEarly);
+
+      if (mergedEarly.rawInput) this.imageScanText += " " + JSON.stringify(mergedEarly.rawInput);
+      if (mergedEarly.title) this.imageScanText += " " + mergedEarly.title;
+      if (Array.isArray(mergedEarly.content_blocks)) {
+        this.imageScanText += " " + JSON.stringify(mergedEarly.content_blocks);
       }
-      // Some agents put free-form result text on `content`.
-      if (update.content?.text) this.imageScanText += " " + update.content.text;
-      const fo = fileOpFromUpdate(update);
+      const ct = contentText(mergedEarly.content);
+      if (ct) this.imageScanText += " " + ct;
+      const fo = fileOpFromUpdate(mergedEarly);
       if (fo) this.fileOps.set(fo.path, mergeFileOp(this.fileOps.get(fo.path), fo.op));
+      // Live card step — always, even for background sessions.
+      const step = stepFromToolUpdate(mergedEarly);
+      if (step) this.setLiveStep(step);
     } else if (kind === "agent_message_chunk") {
-      const text = update.content?.text;
-      if (typeof text === "string") this.imageScanText += text;
+      const text = contentText(update.content);
+      if (text) {
+        this.imageScanText += text;
+        this.turnAssistantText += text;
+      }
+    } else if (kind === "agent_thought_chunk") {
+      const text = contentText(update.content);
+      if (text?.trim()) {
+        this.appendCardThinking(text);
+        this.setLiveStep(stepFromThought(text));
+      }
+    } else if (kind === "plan") {
+      // Always track plan entries (background too) so switch-to-live restores the board.
+      const entries = parsePlanUpdate(update);
+      if (entries?.length) {
+        this.planEntries = entries;
+        const one = renderPlanOneLine(entries);
+        if (one) this.setLiveStep(one);
+        this.changed();
+      }
     }
 
     // Only the live foreground turn streams to Telegram.
     if (!this.foreground || !this.streamer) return;
 
+    if (kind === "plan") {
+      if (this.planEntries?.length) {
+        this.streamer.setPlan(renderPlanMarkdown(this.planEntries));
+      }
+      return;
+    }
     if (kind === "agent_message_chunk") {
-      const text = update.content?.text;
-      if (typeof text === "string") this.streamer.appendOutput(text);
+      const text = contentText(update.content);
+      if (text) this.streamer.appendOutput(text);
       return;
     }
     if (kind === "agent_thought_chunk") {
-      const text = update.content?.text;
-      if (typeof text === "string") this.streamer.appendThought(text);
+      const text = contentText(update.content);
+      if (text) this.streamer.appendThought(text);
       return;
     }
     if (kind === "tool_call" || kind === "tool_call_update") {
@@ -1124,37 +2241,46 @@ export class SessionRuntime {
       const id = update.toolCallId || "";
       const status = (update.status || "").toLowerCase();
 
-      if (kind === "tool_call_update") {
-        // Skip "in_progress"/"pending" duplicates of an already-shown initial call.
-        if (status === "pending" || status === "in_progress") {
-          const hasNewContent =
-            Array.isArray(update.content_blocks) && update.content_blocks.length > 0;
-          if (!hasNewContent) return;
-        }
-        // For completed/failed: show once (so the user sees the final status).
-        const doneKey = (id || update.title || "") + ":done";
-        if (status === "completed" || status === "failed") {
-          if (this.shownToolIds.has(doneKey)) return;
-          this.shownToolIds.add(doneKey);
-        }
-      } else {
-        // Initial tool_call: dedupe by id to avoid double-showing.
-        const shownKey = id || `tool_call:${update.title ?? ""}`;
-        if (this.shownToolIds.has(shownKey)) return;
-        this.shownToolIds.add(shownKey);
+      // Snapshot already merged above for file-ops / live step.
+      const merged = (id && this.toolCallCache.get(id)) || mergeToolSnapshot(undefined, update);
+
+      // Skip hollow shells with nothing useful yet.
+      if (!snapshotHasDetail(merged) && status !== "completed" && status !== "failed") {
+        return;
       }
 
-      const md = formatToolCall(update, {
+      // Status-only mid-flight patches (no new content/input): skip if we already
+      // painted this tool once — upsert would be a no-op anyway.
+      if (kind === "tool_call_update" && (status === "pending" || status === "in_progress")) {
+        const hasNewContent =
+          (Array.isArray(update.content_blocks) && update.content_blocks.length > 0) ||
+          (Array.isArray(update.content) && (update.content as unknown[]).length > 0) ||
+          (!!update.rawInput && Object.keys(update.rawInput).length > 0) ||
+          update.rawOutput !== undefined;
+        const key = id || `tool_call:${update.title ?? ""}`;
+        if (!hasNewContent && this.shownToolIds.has(key)) return;
+      }
+
+      const md = formatToolCall(merged, {
         showDiffs: this.cfg.showEditDiffs,
         diffMaxLines: this.cfg.diffMaxLines,
       });
-      if (md) this.streamer.addTool(md);
+      if (!md) return;
+
+      // One live card per toolCallId: replace in place as output streams
+      // (no spam of new code sections). Session/agent context keeps full output.
+      const key = id || `tool_call:${merged.title ?? merged.name ?? ""}`;
+      this.shownToolIds.add(key);
+      if (status === "completed" || status === "failed") {
+        this.shownToolIds.add(key + ":done");
+      }
+      this.streamer.upsertTool(id || undefined, md);
     }
   }
 
   private persist(): void {
     if (!this.foreground) return; // only the foreground session is the chat's restored default
-    this.settings.update(this.chatId, {
+    this.settings.updateKey(this.settingsKey, {
       projectPath: this.cwd,
       projectName: this.projectName,
       sessionId: this.sessionId,
@@ -1177,20 +2303,61 @@ export class SessionRuntime {
     }
   }
 
+  /**
+   * Send a chat message. Returns Telegram message_id on success.
+   * On failure, retries once truncated (~3500) without reply_markup so a long
+   * Done / markup error cannot silently drop the completion ping.
+   */
   private async notify(
     text: string,
     opts?: { loud?: boolean; replyTo?: number; replyMarkup?: InlineKeyboard },
+  ): Promise<number | undefined> {
+    const send = async (body: string, withMarkup: boolean): Promise<number | undefined> => {
+      try {
+        const extra: Record<string, unknown> = opts?.loud ? { disable_notification: false } : {};
+        if (this.messageThreadId !== undefined) extra.message_thread_id = this.messageThreadId;
+        if (opts?.replyTo !== undefined) {
+          extra.reply_parameters = { message_id: opts.replyTo, allow_sending_without_reply: true };
+        }
+        if (withMarkup && opts?.replyMarkup) extra.reply_markup = opts.replyMarkup;
+        const msg = await this.api.sendMessage(this.chatId, body, extra);
+        return msg.message_id;
+      } catch (e) {
+        log.debug("notify failed:", (e as Error).message);
+        return undefined;
+      }
+    };
+    const id = await send(text, true);
+    if (id !== undefined) return id;
+    const short = text.length > 3500 ? text.slice(0, 3499) + "\u2026" : text;
+    return send(short, false);
+  }
+
+  /**
+   * After Done was already sent, attach suggestion text + buttons by editing
+   * that message (or sending a follow-up if edit fails / no message id).
+   */
+  private async enhanceDoneMessage(
+    messageId: number | undefined,
+    text: string,
+    markup: InlineKeyboard | undefined,
   ): Promise<void> {
-    try {
-      const extra: Record<string, unknown> = opts?.loud ? { disable_notification: false } : {};
-      if (opts?.replyTo !== undefined) {
-        extra.reply_parameters = { message_id: opts.replyTo, allow_sending_without_reply: true };
+    if (messageId !== undefined) {
+      try {
+        const extra: Record<string, unknown> = {};
+        if (this.messageThreadId !== undefined) extra.message_thread_id = this.messageThreadId;
+        if (markup) extra.reply_markup = markup;
+        await this.api.editMessageText(this.chatId, messageId, text, extra);
+        return;
+      } catch (e) {
+        log.debug("enhanceDoneMessage edit failed:", (e as Error).message);
       }
-      if (opts?.replyMarkup) extra.reply_markup = opts.replyMarkup;
-      await this.api.sendMessage(this.chatId, text, extra);
-    } catch {
-      /* non-fatal */
     }
+    await this.notify(text, {
+      loud: false,
+      replyTo: this.turnReplyTo,
+      replyMarkup: markup,
+    });
   }
 
   private async onWatchEntries(entries: HistoryEntry[]): Promise<void> {
@@ -1203,7 +2370,11 @@ export class SessionRuntime {
       })
       .filter(Boolean)
       .join("\n\n");
-    if (body.trim()) await sendMarkdownDoc(this.api, this.chatId, `${body}\n\n${this.tags}`);
+    if (body.trim()) {
+      await sendMarkdownDoc(this.api, this.chatId, `${body}\n\n${this.tags}`, {
+        messageThreadId: this.messageThreadId,
+      });
+    }
   }
 }