kiro-telegram-bot 1.7.1 → 1.7.2

package/.env.example

@@ -61,6 +61,17 @@ AGENT_IMAGES_MAX=8
 # so the chat isn't silent during delegated/parallel work. true/false
 SHOW_SUBAGENTS=true
 
+# Task-progress bar. SHOW_PROGRESS asks the agent to end each message with a
+# {progress: N%} marker, which the bot hides and renders as a green 0–100% bar
+# on the live message, session cards, and the status panel.
+# That marker is only an instruction the model can ignore (common on long,
+# tool-heavy turns or weaker/free models), leaving the bar empty. PROGRESS_FALLBACK
+# then shows a bot-computed bar derived from REAL activity (completed tool calls,
+# streamed output, elapsed time) whenever the agent emits no marker, so a live bar
+# still advances. The agent's own marker, when present, always takes precedence.
+SHOW_PROGRESS=true
+PROGRESS_FALLBACK=true
+
 # When you control several sessions at once and switch between them, deliver a
 # session's "Done" summary even while that session is in the background (you're
 # viewing another one) — clearly marked "From other session" with a short

package/CHANGELOG.md

@@ -7,6 +7,93 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The latest section is published verbatim as the GitHub Release notes by
 `.github/workflows/release.yml` when a `vX.Y.Z` tag is pushed.
 
+## [1.7.2] - 2026-06-25
+
+The **"steady & solo"** release — a self-computing progress bar that never spams
+empty bubbles, a single-instance guard that clears ghost processes, a
+path-independent `~/.kiro/tg/` config home, a polished pinned status panel, and
+fixes for the false idle-timeout during subagent (translation) work and the bot
+rejecting its own pin messages as "Not authorized".
+
+### Added
+
+- **📈 Bot-computed task-progress fallback (`PROGRESS_FALLBACK`).** The
+  `{progress: N%}` bar previously depended entirely on the agent emitting the
+  marker — and that marker is only an *instruction* the model can ignore, so
+  weaker/free models and long, tool-heavy turns often emitted none, leaving the
+  bar empty for the whole turn. Now, when `SHOW_PROGRESS` is on but no marker
+  arrives, the bot renders a **computed** bar derived from **real activity**
+  (completed tool calls, streamed output, elapsed time): it starts low, climbs in
+  realistic increments via a saturating curve capped at 90 % while running, and
+  fills to 100 % when the turn completes successfully. The estimate is monotonic
+  by construction, and the agent's own marker — when present — always takes
+  precedence (the fallback stops contributing the moment a real value arrives).
+  The bar is only ever **appended to real streamed content** — it never produces
+  a standalone/empty bubble — and the live status panel shows it on its own.
+  Disable with `PROGRESS_FALLBACK=false`.
+- **🏠 Canonical, path-independent config home (`~/.kiro/tg/`).** The `.env`
+  (plus `logs/`, `data/`) now lives in `~/.kiro/tg/` by default, so the bot loads
+  the **same** configuration no matter which folder you start it from — no more
+  "works from this directory, broken from that one". Resolution order is
+  `--instance` → `KIRO_TG_DIR` → a `.env` in the current folder (so existing
+  per-folder checkouts keep working) → `~/.kiro/tg`. `kiro-tg setup` writes there
+  by default, and **`kiro-tg setup --path`** prints the resolved `.env` location.
+- **🔒 Single-instance guard, per bot token (`KIRO_TG_SINGLE_INSTANCE`).** On
+  startup the bot takes a token-scoped lock under `~/.kiro/tg/locks/`; if a
+  still-alive **ghost/duplicate** is already polling Telegram with that token, it
+  is terminated (and its child tree on Windows) so the fresh process — with your
+  current `.env` — becomes the sole `getUpdates` consumer.
+
+### Changed
+
+- **🧭 Polished status panel.** The pinned status message was redesigned for
+  readability: the redundant "Kiro — Status" header is gone, the **progress bar
+  is the first line** (so the collapsed pin preview shows how far along the
+  current task is), and the cramped space-padded columns are replaced with clean
+  emoji-led fields separated by ` | ` across three short lines — activity
+  (`state | queue | sessions | watching | subagents`), location
+  (`project | session | context`) and config (`agent | reasoning | model`).
+  Counters that don't apply (empty queue, single session) are hidden instead of
+  shown as `0`.
+- **🧹 Progress clears when a turn ends.** The task-progress value is now reset
+  when a turn finishes, stops, or errors, so the bar is removed from the status
+  panel, session cards and switch messages once the work is done (the finished
+  streamed message keeps its own frozen bar as a record).
+- **🫥 Status panel only while working.** The pinned status panel now appears
+  while a turn is running (or a follow-up is queued) and is **removed when the
+  session goes idle**, so the chat stays clean between tasks. The full state is
+  still available on demand via **Status** in the menu (`/status`).
+
+### Fixed
+
+- **⛔ Spurious "Not authorized" from the bot's own pin messages.** The auth
+  gate replied "⛔ Not authorized" to **every** update whose sender wasn't an
+  allowed user — including the bot's **own** service messages. Since the status
+  panel is pinned/unpinned, each pin emits a `pinned_message` service update
+  authored by the bot, so the gate kept rejecting itself (interleaved with
+  normal replies). The gate now ignores updates that aren't a real user action
+  (the bot's own/`is_bot` updates, service messages, and updates with no
+  `from`), and those pin service messages are deleted on arrival so they no
+  longer clutter the chat. Genuine unauthorized users still get one clear reply.
+- **⛔ Phantom "Not authorized" from a ghost process.** A leftover bot started
+  from another folder kept answering with a stale `.env` (e.g. an outdated
+  `ALLOWED_USERS`), rejecting you while the new process couldn't poll (Telegram
+  409 Conflict). The single-instance guard above clears the ghost on startup. A
+  plain `kiro-tg run` still **yields** to an already-running background service
+  rather than fighting it (no restart/kill loop).
+- **⏱️ False "No agent activity … giving up" during subagent delegation.** The
+  prompt idle-timeout tracked activity per session, but subagents (e.g. parallel
+  translation crews) stream on their own session ids, so a main turn that
+  delegated heavy work looked "silent" and was killed after ~15 min even though
+  the agent was busy — and the next message then collided with the still-running
+  turn as `-32603 … dispatch failure`. The watchdog now uses a **process-wide
+  activity clock** (any session/subagent stream, metadata, or subagent status
+  refreshes it), so a delegating turn stays alive while its subagents work; only
+  a genuinely silent agent trips it. When it does fire (idle or the hard cap),
+  the agent's turn is now **cancelled** so the session is immediately reusable.
+  `dispatch failure` and common connection/stream errors are also now classified
+  as **transient**, so they retry/auto-fork instead of surfacing as a dead end.
+
 ## [1.7.1] - 2026-06-24
 
 The **"sign in your way"** release — `/reauth` now lets you pick how you log in

package/README.md

@@ -29,7 +29,7 @@ and extended into a full multi-session client.
 | 🟢 **Connect to live sessions** | `/active` shows sessions running **right now** on your PC. Watch them live, or continue them — see below. |
 | 🛑 **Kill a session / PID** | Each live `/sessions` · `/active` card has a **🛑 Kill · pid N** button (confirm-guarded) that stops that session's process and its child tree; `/killall` stops them all. The bot's own agent is never killable. |
 | 📡 **Live watch** | Follow a running session read-only in real time (tails its event log). |
-| 🧭 **Always-visible menu** | A persistent keyboard plus a pinned status panel that always shows your current **project, agent, reasoning effort, model, session and queue**. |
+| 🧭 **Always-visible menu** | A persistent keyboard plus a pinned status panel that appears while a task runs (and clears when idle), showing your current **project, agent, reasoning effort, model, session and queue**. |
 | ⏰ **Scheduled tasks** | Create prompts that run on a schedule (once / daily / weekly / monthly / every-N-minutes) in a chosen project, delivered back to your chat. |
 | 🖼 **Multi-image prompts** | Send one or many photos (albums included) with a caption — all attached to the prompt for the agent to analyze. |
 | 📜 **History** | `/history` shows the latest messages of any session. |
@@ -81,20 +81,29 @@ the `tsx` runtime, no build step):
 npm install -g kiro-telegram-bot
 ```
 
-Everything operates on the **current folder** (its `.env`, `logs/`, `data/`), so
-keep one folder per bot:
+By default your config lives in a **canonical, path-independent home** —
+`~/.kiro/tg/` (its `.env`, `logs/`, `data/`) — so the bot loads the **same**
+`.env` no matter which folder you start it from. Run `kiro-tg setup --path` to
+print the exact location. (A `.env` in the current folder is still honoured
+first, so existing per-folder checkouts keep working.)
 
 ```bash
-mkdir my-bot && cd my-bot
-kiro-tg setup            # auto-detects kiro-cli, writes ./.env
-# edit .env: set TELEGRAM_BOT_TOKEN and ALLOWED_USERS
+kiro-tg setup            # auto-detects kiro-cli, writes ~/.kiro/tg/.env
+kiro-tg setup --path     # print the .env location
+# edit that .env: set TELEGRAM_BOT_TOKEN and ALLOWED_USERS
 kiro-tg run              # foreground …
 kiro-tg install          # … or install as a 24/7 background service
 ```
 
-Startup options: `kiro-tg setup | run | install | status | logs [n] | stop |
-restart | uninstall`. Or try it without installing: `npx kiro-telegram-bot
-setup`. See **[docs/INSTALL.md](./docs/INSTALL.md)** for the full guide.
+The bot is **single-instance per token**: starting it again terminates any
+ghost/duplicate that was still polling Telegram (the usual cause of a stale
+"⛔ Not authorized"), so the fresh process with your current `.env` wins. A
+plain `kiro-tg run` yields to an already-running background service instead.
+
+Startup options: `kiro-tg setup [--path] | run | install | status | logs [n] |
+stop | restart | uninstall`. Or try it without installing: `npx
+kiro-telegram-bot setup`. See **[docs/INSTALL.md](./docs/INSTALL.md)** for the
+full guide.
 
 ---
 
@@ -211,9 +220,11 @@ A tiny **persistent bar** sits under the message box — **☰ Menu · 🧭 Runn
 Sessions · Agent · Model · Reasoning · Tasks · Status · Usage · Stop · Kill all.
 The bar can be hidden (🙈) and restored (⌨️ Show bar or `/menu`).
 
-A **pinned status panel** at the top of the chat always shows your current
-**project, agent, reasoning effort, model, session id, context %, task progress,
-activity and queue** (and how many sessions the chat controls), updating live.
+While a task is running, a **pinned status panel** appears at the top of the chat
+showing your current **task progress, activity, queue, project, session, context
+%, agent, reasoning effort and model** (and how many sessions the chat controls),
+updating live — and it's **removed when the session goes idle** so the chat stays
+clean between tasks (use **Status** in the menu to see it on demand any time).
 Pick **Agent**, **Reasoning** or **Model** from the inline menu (reasoning steers
 how thoroughly the agent works: Minimal → Max).
 
@@ -260,6 +271,15 @@ pinned **status panel**, and on **`/running` and `/sessions` cards**. Markers ar
 also stripped from history, replays and previews, so the raw plumbing never
 shows. Turn it off with `SHOW_PROGRESS=false`.
 
+That marker is only an instruction the model can ignore — weaker/free models and
+long, tool-heavy turns often emit none, which used to leave the bar empty for the
+whole turn. So when `SHOW_PROGRESS` is on but no marker arrives, the bot falls
+back to a **computed** bar derived from real activity (completed tool calls,
+streamed output, elapsed time): it starts low, climbs as work advances, and fills
+to 100 % when the turn completes. The agent's own marker, when present, always
+takes precedence and the value never decreases. Disable the fallback with
+`PROGRESS_FALLBACK=false`.
+
 ## 🔐 Re-authenticating Kiro
 
 Run **`/reauth`** to log out and start a fresh **device-flow** login without
@@ -307,6 +327,7 @@ Resuming an **idle** session loads it directly so you continue the exact thread.
 | `ALLOWED_USERS` | recommended | *(all)* | Comma-separated Telegram user IDs. Empty = anyone (unsafe). |
 | `KIRO_CLI_PATH` | no | auto / `kiro-cli` | Path to the `kiro-cli` binary. |
 | `KIRO_WORKSPACE` | no | cwd | Default working directory. |
+| `KIRO_TG_DIR` | no | `~/.kiro/tg` | Folder holding this instance's `.env`, `logs/`, `data/`. Resolution: `--instance` → `KIRO_TG_DIR` → a `.env` in the current folder → `~/.kiro/tg`. So a `.env` created once is loaded from any startup path. |
 | `KIRO_AGENT` | no | — | Custom agent from `.kiro/agents/`. |
 | `KIRO_TRUST_ALL_TOOLS` | no | `true` | Run tools without prompts. |
 | `PROJECT_ROOTS` | no | workspace parent + home | Roots for `/projects`. |
@@ -317,10 +338,12 @@ Resuming an **idle** session loads it directly so you continue the exact thread.
 | `DIFF_MAX_LINES` | no | `120` | Max diff lines shown inline. |
 | `SHOW_SUBAGENTS` | no | `true` | Stream subagent (crew) start/work/finish while the main agent waits. |
 | `SHOW_PROGRESS` | no | `true` | Ask the agent to append a `{progress: N%}` marker to each message; the bot parses it, hides the marker, and renders a green 0–100% bar on the live message, in session cards, and in the status panel. |
+| `PROGRESS_FALLBACK` | no | `true` | When `SHOW_PROGRESS` is on but the agent emits **no** `{progress: N%}` marker (weaker/free models and long tool-heavy turns often skip it), render a **bot-computed** bar derived from real activity (completed tool calls, streamed output, elapsed time) so a live bar still advances — filling to 100% when the turn completes. The agent's own marker, when present, always takes precedence and stays monotonic. |
 | `NOTIFY_OTHER_SESSIONS` | no | `true` | Deliver a session's "Done" summary (with a short created/edited/deleted count) even when it's a background session, marked "From other session". `false` keeps background sessions silent. |
 | `MCP_PROBE_TIMEOUT_MS` | no | `8000` | Per-server timeout for the `/mcp` live health-check. |
 | `MCP_PROBE_CONCURRENCY` | no | `6` | How many MCP health probes run at once. |
 | `ACP_AUTO_RESTART` | no | `true` | Auto-restart the agent if it exits. |
+| `KIRO_TG_SINGLE_INSTANCE` | no | `true` | Enforce one running bot **per token**: on startup a still-alive ghost/duplicate (an old process polling Telegram with a stale `.env`, the usual cause of a phantom "⛔ Not authorized") is terminated so the fresh process wins. A manual `run` yields to an already-running background service instead of fighting it. |
 | `AUTO_UPDATE` | no | `true` | Hourly check npm and, when a newer version exists **and the bot is idle** (no turn/task running, no other active Kiro session), auto-update + restart + post the release notes (tagged `#update`). Global npm installs only. |
 | `UPDATE_CHECK_MS` | no | `3600000` | How often to check npm for updates (ms). |
 | `PROMPT_RETRY_ATTEMPTS` | no | `5` | Max retries for a transient agent error (e.g. high-traffic / `Internal error`) before any output streamed, with `6s → 12s → 24s → 48s → 60s` backoff. The real error shows each attempt; a summary after the last. `0` disables. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-telegram-bot",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "Control Kiro CLI from Telegram over the Agent Client Protocol (ACP). Switch projects, resume and attach to live coding sessions, stream responses with diffs, queue follow-ups, and run 24/7 as a cross-platform background service.",
   "type": "module",
   "main": "src/index.ts",

package/scripts/setup.mjs

@@ -1,24 +1,63 @@
 #!/usr/bin/env node
 /**
- * Easy setup: creates .env from .env.example, auto-detects the kiro-cli binary
- * and sensible PROJECT_ROOTS, and optionally writes the bot token / user id
- * passed as arguments:
+ * Easy setup: creates/updates the bot's .env, auto-detects the kiro-cli binary
+ * and sensible PROJECT_ROOTS, and optionally writes the bot token / user id:
  *
- *   node scripts/setup.mjs <TELEGRAM_BOT_TOKEN> [ALLOWED_USER_ID]
+ *   node scripts/setup.mjs [--path] [--instance <dir>] [<TELEGRAM_BOT_TOKEN> [ALLOWED_USER_ID]]
+ *
+ * By default the .env lives in the canonical, path-independent home
+ * `~/.kiro/tg/.env`, so the bot loads the SAME config no matter where it's
+ * started from. A `.env` already present in the current folder (an explicit
+ * per-folder checkout) is used instead. `--path` just prints the resolved .env
+ * path and exits (nothing is written).
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, dirname } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = join(dirname(fileURLToPath(import.meta.url)), "..");
-// .env lives in the instance dir (the user's folder); the template ships in the
-// package. For a cloned/zip checkout run in place these are the same folder.
-const instanceDir = process.env.KIRO_TG_CWD?.trim() || process.cwd();
-const envPath = join(instanceDir, ".env");
 const examplePath = join(root, ".env.example");
+const CANONICAL_DIR = join(homedir(), ".kiro", "tg");
+
+function expandHome(p) {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) return join(homedir(), p.slice(2));
+  return p;
+}
+
+/** Mirror of config.ts resolveInstanceDir() so setup writes EXACTLY where the
+ *  bot will read from. Keep the two in sync. */
+function resolveInstanceDir() {
+  const flag = process.argv.indexOf("--instance");
+  if (flag !== -1 && process.argv[flag + 1]) return resolve(process.argv[flag + 1]);
+  const envDir = (process.env.KIRO_TG_DIR || process.env.KIRO_TG_CWD || "").trim();
+  if (envDir) return resolve(expandHome(envDir));
+  if (existsSync(join(process.cwd(), ".env"))) return process.cwd();
+  return CANONICAL_DIR;
+}
+
+// Parse args: flags (--path, --instance <dir>) vs positional token/user.
+const argv = process.argv.slice(2);
+let pathOnly = false;
+const positionals = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "--path") pathOnly = true;
+  else if (a === "--instance") i++; // value consumed by resolveInstanceDir()
+  else positionals.push(a);
+}
+const [tokenArg, userArg] = positionals;
+
+const instanceDir = resolveInstanceDir();
+const envPath = join(instanceDir, ".env");
+
+if (pathOnly) {
+  console.log(envPath);
+  process.exit(0);
+}
 
-const [, , tokenArg, userArg] = process.argv;
+mkdirSync(instanceDir, { recursive: true });
 
 function detectKiro() {
   const candidates = [
@@ -70,6 +109,7 @@ if (userArg) {
 
 writeFileSync(envPath, env, "utf-8");
 console.log(`\n✓ .env written to ${envPath}`);
+console.log("  (loaded from here no matter which folder you start the bot in)");
 
 if (!/^TELEGRAM_BOT_TOKEN=.+/m.test(env)) {
   console.log("\nNext: open .env and paste your bot token from @BotFather, then run `kiro-tg run` (or `npm start`).");

package/src/acp/client.ts

@@ -29,7 +29,7 @@ const log = createLogger("acp:client");
 /** JSON-RPC error codes that usually mean "transient backend hiccup". */
 const TRANSIENT_CODES = new Set([-32603, -32500, -32000, 500, 502, 503, 504, 429]);
 const TRANSIENT_RE =
-  /internal error|high volume|experiencing|overloaded|temporar|unavailable|rate.?limit|too many requests|try again|capacity|\b50[234]\b|\b429\b/i;
+  /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;
 
 /** Error that preserves the agent's JSON-RPC error code and data payload. */
 export class AcpError extends Error {
@@ -120,6 +120,12 @@ export class AcpClient extends EventEmitter {
   private readonly promptMaxMs: number;
   /** Last time we saw streaming activity for a session (epoch ms). */
   private readonly lastActivity = new Map<string, number>();
+  /** Last time ANY session OR subagent produced output (epoch ms) — a
+   *  process-wide "the agent is alive" clock. The per-session map misses work
+   *  done by subagents (they stream on their own session ids), so without this
+   *  a prompt that delegates to long-running subagents (e.g. parallel
+   *  translation) trips the idle timeout while its subagents are doing the work. */
+  private lastActivityAny = 0;
   private stopped = false;
   private restartAttempts = 0;
   private restartTimer?: NodeJS.Timeout;
@@ -283,15 +289,21 @@ export class AcpClient extends EventEmitter {
       const start = Date.now();
       this.lastActivity.set(sessionId, start);
       const watch = setInterval(() => {
-        const idle = Date.now() - (this.lastActivity.get(sessionId) ?? start);
+        // Count activity from ANY session/subagent (the process-wide clock), so
+        // a turn that's delegating to long-running subagents stays alive while
+        // they work — only a genuinely silent (stuck) agent trips the timeout.
+        const last = Math.max(this.lastActivity.get(sessionId) ?? start, this.lastActivityAny);
+        const idle = Date.now() - last;
         const total = Date.now() - start;
         if (total > this.promptMaxMs) {
           this.pending.delete(id);
           clearInterval(watch);
+          void this.cancel(sessionId); // stop the runaway turn so the session is reusable
           reject(new Error(`Prompt exceeded the ${Math.round(this.promptMaxMs / 60_000)}min cap`));
         } else if (idle > this.promptIdleMs) {
           this.pending.delete(id);
           clearInterval(watch);
+          void this.cancel(sessionId); // free the session — otherwise the next prompt collides ("dispatch failure")
           reject(new Error(`No agent activity for ${Math.round(idle / 1000)}s — giving up`));
         }
       }, 15_000);
@@ -496,6 +508,17 @@ export class AcpClient extends EventEmitter {
   }
 
   private routeNotification(method: string, params: unknown): void {
+    // Any agent-work notification — the main stream, a SUBAGENT's stream, model
+    // metadata, or a subagent status change — proves the process is alive, so
+    // refresh the process-wide clock. This is what keeps a prompt delegating to
+    // long-running subagents from tripping the per-session idle timeout.
+    if (
+      method === "session/update" ||
+      method === "_kiro.dev/metadata" ||
+      method === "_kiro.dev/subagent/list_update"
+    ) {
+      this.lastActivityAny = Date.now();
+    }
     if (method === "session/update") {
       const p = params as SessionNotificationParams;
       if (p?.sessionId && p.update) {

package/src/app/instance-lock.ts

@@ -0,0 +1,139 @@
+/**
+ * Single-instance guard, keyed per bot token (NOT per folder), so the same bot
+ * can't run twice no matter which directory it's started from.
+ *
+ * Telegram allows only ONE long-polling consumer per token — a second instance
+ * triggers 409 Conflict and, worse, a leftover "ghost" process started from an
+ * old folder keeps answering with a stale `.env` (e.g. an outdated
+ * `ALLOWED_USERS`, so you get "⛔ Not authorized"). On startup we therefore
+ * take an exclusive lock: if a still-alive instance holds it, we terminate that
+ * process (and its child tree on Windows) so the fresh process — with the
+ * current config — becomes the only consumer.
+ *
+ * The lock lives under the canonical home (`~/.kiro/tg/locks/<tokenHash>.lock`)
+ * and stores only a pid + start time + whether the holder is supervised. The
+ * token itself is never written to disk (only its hash names the file).
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { createLogger } from "../logger.js";
+import { killPid } from "../sessions/process.js";
+import { isPidAlive } from "../sessions/store.js";
+
+const log = createLogger("lock");
+
+interface LockData {
+  pid: number;
+  startedAt: number;
+  /** True when the holder runs under a supervisor (systemd/launchd/Task). */
+  supervised: boolean;
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+export class InstanceLock {
+  private readonly file: string;
+  private held = false;
+
+  constructor(
+    token: string,
+    locksDir: string,
+    private readonly supervised: boolean,
+  ) {
+    const hash = createHash("sha256").update(token).digest("hex").slice(0, 16);
+    this.file = join(locksDir, `${hash}.lock`);
+  }
+
+  /**
+   * Become the sole instance for this token. Returns `false` (caller should
+   * exit) only when a *supervised* service instance is already running and this
+   * process is a plain manual start — we don't fight the background service
+   * (that would cause a restart/kill loop). Otherwise we take over: a live
+   * holder is terminated and the lock is rewritten with our pid.
+   */
+  async acquire(): Promise<boolean> {
+    const existing = this.read();
+    if (existing && existing.pid !== process.pid && isPidAlive(existing.pid)) {
+      if (existing.supervised && !this.supervised) {
+        log.warn(`a supervised service instance is already running (pid ${existing.pid}); not starting a duplicate`);
+        return false;
+      }
+      if (looksLikeNode(existing.pid)) {
+        log.warn(`another bot instance is running (pid ${existing.pid}); terminating it to take over`);
+        killPid(existing.pid);
+        for (let i = 0; i < 20 && isPidAlive(existing.pid); i++) await sleep(150); // up to ~3s
+        if (isPidAlive(existing.pid)) log.warn(`previous instance ${existing.pid} still alive after kill; continuing anyway`);
+      } else {
+        // The locked pid was recycled to an unrelated process — don't kill it,
+        // just reclaim the stale lock.
+        log.warn(`lock pid ${existing.pid} is not a node process; reclaiming stale lock`);
+      }
+    }
+    this.write();
+    this.held = true;
+    return true;
+  }
+
+  /** Release the lock if (and only if) we still own it. */
+  release(): void {
+    if (!this.held) return;
+    this.held = false;
+    try {
+      const cur = this.read();
+      if (cur?.pid === process.pid) rmSync(this.file, { force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  private write(): void {
+    const data: LockData = { pid: process.pid, startedAt: Date.now(), supervised: this.supervised };
+    try {
+      mkdirSync(join(this.file, ".."), { recursive: true });
+      writeFileSync(this.file, JSON.stringify(data), "utf-8");
+    } catch (e) {
+      log.warn(`could not write lock file ${this.file}: ${(e as Error).message}`);
+    }
+  }
+
+  private read(): LockData | undefined {
+    try {
+      const d = JSON.parse(readFileSync(this.file, "utf-8")) as Partial<LockData>;
+      if (typeof d.pid === "number" && d.pid > 0) {
+        return { pid: d.pid, startedAt: Number(d.startedAt) || 0, supervised: Boolean(d.supervised) };
+      }
+    } catch {
+      /* no/invalid lock */
+    }
+    return undefined;
+  }
+}
+
+/**
+ * Best-effort check that `pid` is a node process (our bot), to avoid killing an
+ * unrelated process that happened to reuse the pid. If the platform query can't
+ * run or be parsed, we assume it's ours (only this bot writes the lock) — better
+ * to clear a ghost than to leave one fighting over the token.
+ */
+function looksLikeNode(pid: number): boolean {
+  try {
+    if (process.platform === "win32") {
+      const out = execFileSync("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      // No matching task prints an INFO line, not a CSV row — treat as "gone".
+      if (!/^\s*"/.test(out)) return false;
+      return /node\.exe|tsx/i.test(out);
+    }
+    const out = execFileSync("ps", ["-p", String(pid), "-o", "comm="], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return /node|tsx/i.test(out);
+  } catch {
+    return true;
+  }
+}

package/src/bot/auth.ts

@@ -14,12 +14,23 @@ export function createAuthMiddleware(cfg: AppConfig) {
   }
 
   return async (ctx: Context, next: NextFunction): Promise<void> => {
-    const userId = ctx.from?.id ? String(ctx.from.id) : undefined;
-    if (allowAll || (userId && cfg.allowedUsers.has(userId))) {
+    const from = ctx.from;
+    // Only a genuine USER action is subject to (and worth replying to) the auth
+    // gate. Ignore everything else silently — most importantly the bot's OWN
+    // updates: the status panel being pinned/unpinned emits a service message
+    // whose `from` is THIS bot (is_bot), and replying "⛔ Not authorized" to
+    // that (or to any service/no-`from` update) spammed the chat with false
+    // rejections. Real unauthorized users still get one clear reply below.
+    if (!from || from.is_bot) return;
+    const m = ctx.message ?? ctx.editedMessage;
+    if (m && (m.pinned_message || m.new_chat_members || m.left_chat_member)) return;
+
+    const userId = String(from.id);
+    if (allowAll || cfg.allowedUsers.has(userId)) {
       await next();
       return;
     }
-    log.warn(`blocked unauthorized user ${userId ?? "unknown"}`);
+    log.warn(`blocked unauthorized user ${userId}`);
     if (ctx.chat) {
       await ctx.reply("\u26D4 Not authorized. Ask the bot owner to add your Telegram ID.");
     }

package/src/bot/bot.ts

@@ -119,6 +119,11 @@ export async function createBot(cfg: AppConfig, acp: AcpClient): Promise<BotBund
   const permissions = new PermissionService(bot.api, registry);
   acp.permissionHandler = (p) => permissions.handle(p);
 
+  // The bot pins/unpins the status panel, and Telegram emits a "pinned a
+  // message" service message for each pin. Delete those so the chat stays clean
+  // — registered BEFORE auth so these bot-authored updates never reach the gate.
+  bot.on("message:pinned_message", (ctx) => void ctx.deleteMessage().catch(() => {}));
+
   bot.use(createAuthMiddleware(cfg));
 
   // Keep history clean: after handling, delete the user's command (/…) and

package/src/bot/handlers/control.ts

@@ -18,8 +18,8 @@ export function registerControl(bot: Bot, deps: BotDeps): void {
       "\u{1F44B} Welcome! I bridge Telegram to Kiro CLI over ACP.",
       agent?.name ? `Connected to ${agent.name} ${agent.version ?? ""}`.trim() : "",
       "",
-      "Tap \u2630 Menu for everything. The pinned panel above always shows your",
-      "project, agent, reasoning and model. Just send a message to start.",
+      "Tap \u2630 Menu for everything. A live status panel appears while I work",
+      "(\u2630 Menu \u2192 Status shows it anytime). Just send a message to start.",
     ].filter(Boolean);
     await ctx.reply(lines.join("\n"), { reply_markup: compactKeyboard() });
     await deps.statusPanel.refresh(ctx.chat.id);

package/src/bot/menu/status-panel.ts

@@ -29,34 +29,54 @@ export class StatusPanel {
     // after switching between controlled sessions in different projects.
     const project = rt.projectName || (rt.cwd ? basename(rt.cwd) : "(none)");
     const session = rt.sessionId ? rt.sessionId.slice(0, 8) : "none";
-    const state = rt.isBusy ? "\u23F3 working" : "\u2705 idle";
-    const watch = rt.isWatching ? "  \u{1F4E1} watching" : "";
     const meta = rt.contextInfo();
-    const ctx = meta?.contextUsagePercentage !== undefined ? `${meta.contextUsagePercentage.toFixed(0)}%` : "\u2014";
+    const ctxPct = meta?.contextUsagePercentage;
     const running = this.registry.controller(chatId).count();
-    const sessionLine = running > 1 ? `${session}   \u{1F9ED} ${running} controlled` : session;
-    const lines = [
-      "\u{1F4CA} Kiro \u2014 Status",
-      `\u{1F4C1} Project:   ${project}`,
-      `\u{1F916} Agent:     ${s.agent || "default"}`,
-      `\u{1F9E0} Reasoning: ${reasoningLabel(s.reasoning)}`,
-      `\u{1F9E9} Model:     ${s.model || "default"}`,
-      `\u{1F9F5} Session:   ${sessionLine}`,
-      `\u{1F4CA} Context:   ${ctx} used`,
-      `\u2699\uFE0F State:     ${state}   \u{1F4E5} Queue: ${rt.queueLength}${watch}`,
-    ];
     const subagents = this.registry.subagentSummaryForChat(chatId);
-    if (subagents) lines.push(`\u{1F465} Subagents: ${subagents}`);
     const progress = rt.taskProgress;
-    if (progress !== undefined) lines.push(`\u{1F4C8} Progress:  ${progressBar(progress)}`);
+
+    const SEP = " | "; // pipe delimiter between inline fields
+    const lines: string[] = [];
+
+    // 1) Progress first — only while a turn is live (cleared when it ends), so
+    //    the collapsed pin preview shows how far along the current task is.
+    if (progress !== undefined) lines.push(`\u{1F4C8} ${progressBar(progress)}`);
+
+    // 2) Activity: state + only the counters that currently apply.
+    const activity: string[] = [rt.isBusy ? "\u23F3 Working" : "\u2705 Idle"];
+    if (rt.queueLength > 0) activity.push(`\u{1F4E5} ${rt.queueLength} queued`);
+    if (running > 1) activity.push(`\u{1F9ED} ${running} sessions`);
+    if (rt.isWatching) activity.push("\u{1F4E1} watching");
+    if (subagents) activity.push(`\u{1F465} ${subagents}`);
+    lines.push(activity.join(SEP));
+
+    // 3) Where: project | session | context usage.
+    const loc = [`\u{1F4C1} ${project}`, `\u{1F9F5} ${session}`];
+    if (ctxPct !== undefined) loc.push(`\u{1F4CA} ${ctxPct.toFixed(0)}% context`);
+    lines.push(loc.join(SEP));
+
+    // 4) How: agent | reasoning | model.
+    lines.push([`\u{1F916} ${s.agent || "default"}`, `\u{1F9E0} ${reasoningLabel(s.reasoning)}`, `\u{1F9E9} ${s.model || "default"}`].join(SEP));
+
     return lines.join("\n");
   }
 
   /** Refresh (or create + pin) the status message for a chat. */
   async refresh(chatId: number): Promise<void> {
-    const text = this.render(chatId);
+    const rt = this.registry.get(chatId);
     const id = this.settings.get(chatId).statusMessageId;
 
+    // The pinned panel exists only while there's live work — a running turn or a
+    // queued follow-up about to run. When the session is idle there's nothing to
+    // show, so remove the panel to keep the chat clean. (The on-demand /status
+    // still renders full state when explicitly requested.)
+    const active = rt.isBusy || rt.queueLength > 0;
+    if (!active) {
+      if (id) await this.remove(chatId, id);
+      return;
+    }
+
+    const text = this.render(chatId);
     if (id) {
       try {
         await this.api.editMessageText(chatId, id, text);
@@ -69,6 +89,20 @@ export class StatusPanel {
     await this.create(chatId, text);
   }
 
+  /** Remove the pinned panel (unpin + delete) and forget its id. */
+  private async remove(chatId: number, id: number): Promise<void> {
+    this.settings.update(chatId, { statusMessageId: undefined });
+    try {
+      await this.api.deleteMessage(chatId, id); // deleting a pinned message also unpins it
+    } catch {
+      try {
+        await this.api.unpinChatMessage(chatId, id);
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+
   private async create(chatId: number, text: string): Promise<void> {
     try {
       const msg = await this.api.sendMessage(chatId, text, { disable_notification: true });

package/src/bot/session-runtime.ts

@@ -146,10 +146,13 @@ export class SessionRuntime {
     return this.progress;
   }
 
-  /** Record a new progress value and refresh the status panel / cards. */
+  /** 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. */
   private setProgress(pct: number): void {
-    if (this.progress === pct) return;
-    this.progress = pct;
+    const next = Math.max(this.progress ?? 0, pct);
+    if (next === this.progress) return;
+    this.progress = next;
     this.changed();
   }
 
@@ -173,7 +176,7 @@ 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.streamer = new ResponseStreamer(this.api, this.chatId, this.cfg.streamThrottleMs, this.turnReplyTo, this.hashtags(), (pct) => this.setProgress(pct), this.cfg.progressFallback, this.turnStartedAt);
         this.typing.start();
       }
     } else {
@@ -459,14 +462,14 @@ export class SessionRuntime {
     // session's previous in-flight turn (avoids duplicated output).
     if (this.watchIsFollow) this.stopWatch();
     const live = this.foreground;
+    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))
+      ? new ResponseStreamer(this.api, this.chatId, this.cfg.streamThrottleMs, this.turnReplyTo, this.hashtags(), (pct) => this.setProgress(pct), this.cfg.progressFallback, startedAt)
       : undefined;
     if (live) this.typing.start();
     this.activity(true);
     this.changed();
-    const startedAt = Date.now();
-    this.turnStartedAt = startedAt;
     this.imageScanText = "";
     this.sentImagesThisTurn = new Set();
 
@@ -482,6 +485,9 @@ export class SessionRuntime {
       const recovered = await this.maybeAutoFork(input, outcome);
       const final = recovered ?? outcome;
       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).
+      if (final.result && !this.cancelled) this.streamer?.completeFallback();
       if (this.streamer) await this.streamer.finalize();
       if (this.foreground) await this.sendTurnImages();
       // Always build the completion (records `lastCompletion` so switching back
@@ -517,6 +523,10 @@ export class SessionRuntime {
       this.activity(false);
       // The in-flight turn we may have been following live is over.
       if (this.watchIsFollow) this.stopWatch();
+      // Turn ended (done / stopped / error): drop the live task-progress value so
+      // 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.changed();
     }
 

package/src/cli.ts

@@ -10,7 +10,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { INSTANCE_DIR, PROJECT_ROOT } from "./config.js";
+import { ENV_PATH, INSTANCE_DIR, PROJECT_ROOT } from "./config.js";
 import { buildLaunchSpec, getController } from "./service/index.js";
 
 const HELP = `Kiro Telegram Bot — CLI
@@ -18,7 +18,8 @@ const HELP = `Kiro Telegram Bot — CLI
 Usage: kiro-tg <command>
 
   run                 Run in the foreground
-  setup               Create/update .env in this folder (token + auto-detect)
+  setup [--path]      Create/update .env (default ~/.kiro/tg/.env, loaded from
+                      any folder); --path just prints the resolved .env location
   install             Install + start a background service (autostart on boot)
   uninstall           Stop + remove the background service
   start               Start the service
@@ -98,9 +99,9 @@ async function main(): Promise<void> {
 }
 
 function preflight(): void {
-  const envPath = join(INSTANCE_DIR, ".env");
+  const envPath = ENV_PATH;
   if (!existsSync(envPath)) {
-    console.warn("⚠ No .env found here. Run `kiro-tg setup` and set TELEGRAM_BOT_TOKEN first.");
+    console.warn(`⚠ No .env found at ${envPath}. Run \`kiro-tg setup\` and set TELEGRAM_BOT_TOKEN first.`);
     return;
   }
   const env = readFileSync(envPath, "utf-8");

package/src/config.ts

@@ -7,34 +7,44 @@ import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-loadDotenv();
-
 /** Absolute path to the installed bot code (one level above src/). For a global
  *  npm install this lives inside node_modules — code lives here, never user data. */
 export const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
+/** Canonical, path-independent home for this bot's `.env`, `logs/`, `data/` and
+ *  the single-instance locks: `~/.kiro/tg`. Used whenever the bot is started
+ *  without an explicit instance dir and there's no `.env` in the current folder,
+ *  so the SAME configuration is found no matter which directory you launch from. */
+export const CANONICAL_DIR = join(homedir(), ".kiro", "tg");
+
 /**
- * Directory holding THIS instance's `.env`, `logs/` and `data/`. Resolution:
+ * Directory holding THIS instance's `.env`, `logs/` and `data/`. Resolution
+ * (first match wins):
  *   1. `--instance <dir>` argv — set by the installed background service,
- *   2. `KIRO_TG_CWD` env — set by the `kiro-tg` launcher to the user's cwd,
- *   3. the current working directory.
- * For a cloned/zip checkout run in place this equals PROJECT_ROOT (so behaviour
- * is unchanged), while a global `npm i -g` install keeps user data in the
- * user's folder rather than inside node_modules.
+ *   2. `KIRO_TG_DIR` env — an explicit override,
+ *   3. `KIRO_TG_CWD` env — the legacy launcher variable,
+ *   4. the current folder, IF it already contains a `.env` (an explicit
+ *      per-folder bot — keeps cloned/zip checkouts working in place),
+ *   5. the canonical `~/.kiro/tg` home — the path-independent default, so a
+ *      `.env` created once is loaded no matter where the bot is started from.
  */
 export const INSTANCE_DIR = resolveInstanceDir();
 
+/** Absolute path to the `.env` this instance loads (and that `setup` writes). */
+export const ENV_PATH = join(INSTANCE_DIR, ".env");
+
 function resolveInstanceDir(): string {
   const flag = process.argv.indexOf("--instance");
   if (flag !== -1 && process.argv[flag + 1]) return resolve(process.argv[flag + 1]!);
-  const env = process.env.KIRO_TG_CWD?.trim();
-  if (env) return resolve(expandHome(env));
-  return process.cwd();
+  const envDir = process.env.KIRO_TG_DIR?.trim() || process.env.KIRO_TG_CWD?.trim();
+  if (envDir) return resolve(expandHome(envDir));
+  if (existsSync(join(process.cwd(), ".env"))) return process.cwd();
+  return CANONICAL_DIR;
 }
 
-// Re-load .env from the instance directory (the first call above also primed
-// process.env from cwd, which is the same place for an in-place checkout).
-loadDotenv({ path: join(INSTANCE_DIR, ".env") });
+// Load .env from the resolved instance directory. dotenv does NOT override
+// variables already present in the environment (the launcher/service env wins).
+loadDotenv({ path: ENV_PATH });
 
 function expandHome(p: string): string {
   if (p === "~") return homedir();
@@ -114,6 +124,9 @@ export interface AppConfig {
   showSubagents: boolean;
   /** Ask the agent to emit a `{progress: N%}` marker and render it as a bar. */
   showProgress: boolean;
+  /** When the agent emits no `{progress}` marker, show a bot-computed fallback
+   *  bar derived from real activity (tool calls, streamed output, elapsed). */
+  progressFallback: boolean;
   /** Deliver a turn's "Done" summary to the chat even when that session is in
    *  the background (you've switched to another session). */
   notifyOtherSessions: boolean;
@@ -121,6 +134,10 @@ export interface AppConfig {
   autoUpdate: boolean;
   /** How often to check npm for a newer version (ms). */
   updateCheckMs: number;
+  /** Enforce a single running instance per bot token: on startup, a still-alive
+   *  ghost/duplicate holding the lock is terminated so the fresh process (with
+   *  the current `.env`) is the only Telegram getUpdates consumer. */
+  singleInstance: boolean;
 }
 
 export function loadConfig(): AppConfig {
@@ -185,9 +202,11 @@ export function loadConfig(): AppConfig {
     mcpProbeConcurrency: num(process.env.MCP_PROBE_CONCURRENCY, 6),
     showSubagents: bool(process.env.SHOW_SUBAGENTS, true),
     showProgress: bool(process.env.SHOW_PROGRESS, true),
+    progressFallback: bool(process.env.PROGRESS_FALLBACK, true),
     notifyOtherSessions: bool(process.env.NOTIFY_OTHER_SESSIONS, true),
     autoUpdate: bool(process.env.AUTO_UPDATE, true),
     updateCheckMs: num(process.env.UPDATE_CHECK_MS, 3_600_000),
+    singleInstance: bool(process.env.KIRO_TG_SINGLE_INSTANCE, true),
   };
 
   return cfg;

package/src/index.ts

@@ -5,7 +5,9 @@
  */
 import { AcpClient } from "./acp/client.js";
 import { createBot } from "./bot/bot.js";
-import { loadConfig } from "./config.js";
+import { CANONICAL_DIR, loadConfig } from "./config.js";
+import { InstanceLock } from "./app/instance-lock.js";
+import { join } from "node:path";
 import { createLogger, enableFileLogging, setLogLevel } from "./logger.js";
 
 async function main(): Promise<void> {
@@ -17,6 +19,17 @@ async function main(): Promise<void> {
   enableFileLogging(cfg.logFile);
   const log = createLogger("main");
 
+  // Single-instance guard: kill any ghost/duplicate already polling this token
+  // (the usual cause of a stale "Not authorized" — an old process with an
+  // outdated .env). A plain manual start yields to a running background service.
+  const lock = new InstanceLock(cfg.token, join(CANONICAL_DIR, "locks"), process.env.KIRO_TG_SUPERVISED === "1");
+  if (cfg.singleInstance && !(await lock.acquire())) {
+    process.stdout.write(
+      "\u26D4 Another Kiro Telegram Bot is already running for this token (a background service). Use `kiro-tg restart`, or `kiro-tg stop` first.\n",
+    );
+    process.exit(0);
+  }
+
   log.info("starting Kiro Telegram Bot");
   log.info(`workspace: ${cfg.workspace}`);
   log.info(`kiro-cli:  ${cfg.kiroCliPath}`);
@@ -46,6 +59,7 @@ async function main(): Promise<void> {
     registry.disposeAll();
     void bot.stop().catch(() => {});
     acp.stop();
+    lock.release();
     setTimeout(() => process.exit(code), 500);
   };
 

package/src/render/progress-estimate.ts

@@ -0,0 +1,63 @@
+/**
+ * Bot-side FALLBACK task-progress estimate.
+ *
+ * The primary progress signal is the `{progress: N%}` marker the agent is asked
+ * to emit (see PROGRESS_DIRECTIVE). But that marker is only an *instruction* the
+ * model can ignore — weaker/free models and long, tool-heavy turns frequently
+ * never emit one, leaving the bar empty for the whole turn. This module gives
+ * the bot a way to show a live, advancing bar anyway, derived ONLY from real,
+ * observable work signals (never random):
+ *
+ *   • completed tool calls   — each is concrete progress, weighted most
+ *   • streamed prose chars    — the agent explaining / answering
+ *   • streamed thinking chars — reasoning volume (weighted least)
+ *   • elapsed time            — a small, slow contribution so a quiet turn still creeps
+ *
+ * The estimate is monotonic by construction (every input only grows during a
+ * turn) and asymptotically capped well below 100 while running, so the bar never
+ * claims "done" on its own — the caller pushes 100 only when the turn actually
+ * completes. The agent's own marker, when present, always takes precedence.
+ */
+
+/** Observable, monotonically-increasing signals collected during one turn. */
+export interface ActivitySignals {
+  /** Number of tool calls / subagent transitions shown this turn. */
+  toolCalls: number;
+  /** Characters of agent prose streamed this turn. */
+  outputChars: number;
+  /** Characters of agent thinking streamed this turn. */
+  thoughtChars: number;
+  /** Milliseconds since the turn started. */
+  elapsedMs: number;
+}
+
+/** Hard ceiling for the fallback while a turn is still running. The agent (or
+ *  turn completion) is the only thing allowed to take the bar to 100. */
+export const FALLBACK_RUNNING_CAP = 90;
+
+/** Minimum shown once *any* work signal is present (so the bar never sits at 0
+ *  while the agent is clearly busy). */
+const FALLBACK_FLOOR = 5;
+
+/** Controls how quickly the asymptotic curve approaches the cap. Larger = slower. */
+const CURVE_K = 6;
+
+/**
+ * Map real work signals to a 0–FALLBACK_RUNNING_CAP estimate via a saturating
+ * curve `cap * (1 - e^(-units/K))`. Tool calls dominate because each is a
+ * discrete, completed step; text volume and elapsed time add gentle, diminishing
+ * contributions so a turn that's only thinking still advances slowly.
+ */
+export function estimateProgress(s: ActivitySignals): number {
+  const units =
+    Math.max(0, s.toolCalls) * 1.0 +
+    Math.max(0, s.outputChars) / 400 +
+    Math.max(0, s.thoughtChars) / 1500 +
+    Math.max(0, s.elapsedMs) / 30_000;
+
+  if (units <= 0) return 0;
+
+  const raw = FALLBACK_RUNNING_CAP * (1 - Math.exp(-units / CURVE_K));
+  const clamped = Math.min(FALLBACK_RUNNING_CAP, Math.max(FALLBACK_FLOOR, raw));
+  return Math.round(clamped);
+}

package/src/stream/streamer.ts

@@ -14,6 +14,7 @@ import type { Api } from "grammy";
 import { chunkMarkdown } from "../render/chunk.js";
 import { toTelegramMarkdown } from "../render/markdown.js";
 import { extractProgress, progressBar } from "../render/progress.js";
+import { estimateProgress } from "../render/progress-estimate.js";
 import { safeEdit, safeSend } from "../bot/telegram-io.js";
 
 const SOFT_LIMIT = 3500;
@@ -36,6 +37,13 @@ export class ResponseStreamer {
   /** Latest task-progress % parsed from the agent's `{progress: N%}` markers
    *  (sticky across flushes; rendered as a bar on the live message). */
   private progress: number | undefined;
+  /** True once the agent emitted a real `{progress}` marker — from then on its
+   *  values are authoritative and the bot fallback stops contributing. */
+  private agentReported = false;
+  /** Real work signals for the fallback estimate (monotonic within a turn). */
+  private toolCalls = 0;
+  private outChars = 0;
+  private thoughtChars = 0;
 
   constructor(
     private readonly api: Api,
@@ -44,6 +52,10 @@ export class ResponseStreamer {
     private replyTo?: number,
     private footer?: string,
     private readonly onProgress?: (pct: number) => void,
+    /** Show a bot-computed bar when the agent emits no marker. */
+    private readonly fallbackEnabled = false,
+    /** Turn start time, used by the fallback's elapsed-time signal. */
+    private readonly turnStartedAt = Date.now(),
   ) {}
 
   /** Replace the hashtag footer (used after a logical fork swaps the session id
@@ -61,17 +73,45 @@ export class ResponseStreamer {
    *  value (sticky across flushes) and notifying the owner when it changes. */
   private captureProgress(text: string): string {
     const { value, cleaned } = extractProgress(text);
-    if (value !== undefined && value !== this.progress) {
-      this.progress = value;
-      try {
-        this.onProgress?.(value);
-      } catch {
-        /* non-fatal */
-      }
-    }
+    if (value !== undefined) this.setProgressValue(value, true);
     return cleaned;
   }
 
+  /** Record a progress value, enforcing global monotonicity (never decreases)
+   *  and notifying the owner on change. Agent markers are authoritative: once
+   *  one arrives, the bot fallback stops contributing. */
+  private setProgressValue(pct: number, fromAgent: boolean): void {
+    if (fromAgent) this.agentReported = true;
+    const next = Math.max(this.progress ?? 0, Math.round(pct));
+    if (next === this.progress) return;
+    this.progress = next;
+    try {
+      this.onProgress?.(next);
+    } catch {
+      /* non-fatal */
+    }
+  }
+
+  /** Advance the fallback estimate from real activity signals, but only while
+   *  the agent itself hasn't reported a value. No-op when fallback is off. */
+  private applyFallback(): void {
+    if (!this.fallbackEnabled || this.agentReported) return;
+    const est = estimateProgress({
+      toolCalls: this.toolCalls,
+      outputChars: this.outChars,
+      thoughtChars: this.thoughtChars,
+      elapsedMs: Date.now() - this.turnStartedAt,
+    });
+    if (est > 0) this.setProgressValue(est, false);
+  }
+
+  /** Called when the turn finishes successfully: if the agent never reported
+   *  its own progress, fill the fallback bar to 100. No-op otherwise. */
+  completeFallback(): void {
+    if (!this.fallbackEnabled || this.agentReported) return;
+    this.setProgressValue(100, false);
+  }
+
   /** reply_parameters threading EVERY message of the turn to the user's prompt,
    *  so the whole response (all bubbles, tool calls and continuations) stays in
    *  one thread — not just the first message. */
@@ -82,18 +122,21 @@ export class ResponseStreamer {
 
   appendOutput(text: string): void {
     if (!text) return;
+    this.outChars += text.length;
     this.merge("out", text);
     this.schedule();
   }
 
   appendThought(text: string): void {
     if (!text) return;
+    this.thoughtChars += text.length;
     this.merge("think", text);
     this.schedule();
   }
 
   addTool(rawMarkdown: string): void {
     if (!rawMarkdown) return;
+    this.toolCalls += 1;
     this.segs.push({ kind: "tool", text: rawMarkdown });
     this.schedule();
   }
@@ -138,11 +181,13 @@ export class ResponseStreamer {
     try {
       await this.sealOverflow();
       const base = this.captureProgress(renderSegs(this.segs.slice(this.sealedIdx)));
-      if (!base.trim() && this.progress === undefined) return;
+      this.applyFallback();
+      // Never send an empty / progress-only bubble. The bar is appended only to
+      // real streamed content; the live status panel shows the standalone bar.
+      if (!base.trim()) return;
       // The live (still-streaming) bubble carries the hashtag footer AND a fresh
       // progress bar at the bottom (sealed bubbles below get neither bar).
-      const parts: string[] = [];
-      if (base.trim()) parts.push(base);
+      const parts: string[] = [base];
       if (this.progress !== undefined) parts.push(progressBar(this.progress));
       const src = `${parts.join("\n\n")}${this.footerSuffix()}`;
       const rendered = toTelegramMarkdown(src);