kiro-telegram-bot 1.6.0 → 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,190 @@ 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
+(Builder ID, Google, GitHub or IAM Identity Center) on one tidy status card, and
+the live task-progress bar climbs steadily instead of appearing only at the end.
+
+### Added
+
+- **🔐 `/reauth` login-method picker.** Re-authentication now opens with a
+  **picker** — **Builder ID** (free), **Google**, **GitHub**, or **IAM Identity
+  Center** (Pro) — driven on a **single, self-animated status message** with
+  inline **Cancel · Retry · Change method · Restart agent** controls, so the chat
+  no longer fills with raw spinner frames. **IAM Identity Center** sign-in is now
+  fully supported: the bot asks for your **start URL + region** and drives the
+  CLI's interactive prompts inside a pseudo-terminal (optional
+  `@homebridge/node-pty-prebuilt-multiarch` dependency; a clear message tells you
+  to run `npm install` if it's missing). The device-verification URL + code still
+  stream to the chat for every method. Power users can skip the picker by passing
+  flags directly, e.g. `/reauth --license pro --identity-provider <url> --region <region>`.
+
+### Changed
+
+- **📈 Stricter, steadier task-progress reporting.** The agent instruction behind
+  the `{progress: N%}` marker is now far more rigorous: a marker is required on
+  **every** message (not only the last), the number must be **computed from real
+  step completion** and is **monotonic** (never decreases within a task), and
+  **100 %** is reserved for work that is fully complete *and verified*. The bar
+  now advances in realistic increments instead of jumping to a value at the very
+  end.
+
+### Fixed
+
+- **🔁 `/reauth` agent-restart race** (`agent restart failed: kiro-cli acp exited
+  (code null)`). Logging out and restarting could let the **old** agent process's
+  exit fail the **new** connection's `initialize` and even trigger a competing
+  auto-restart. The ACP client now **fully tears down** the previous process
+  (ignoring the exit of a process it has already replaced) **before** spawning a
+  fresh one, and `/reauth` takes the agent down and **waits** before logging out —
+  so a deliberate restart is clean and the new identity sticks.
+- **🪪 Stale identity after re-login.** On logout the bot now also **clears Kiro's
+  cached auth token** (`~/.aws/sso/cache/kiro-auth-token.json`), so the next login
+  performs a genuine device-flow authentication instead of silently reusing the
+  previous account's refreshable token.
+
+## [1.7.0] - 2026-06-23
+
+The **"take control"** release — stop a runaway session by PID, re-authenticate
+Kiro from your phone, watch a live task-progress bar, and install on Windows
+without admin.
+
+### Added
+
+- **🛑 Kill a session / PID from its card (`/sessions`, `/active`).** Every
+  **live** session card now has a **`🛑 Kill · pid N`** button that terminates
+  that session's process — and its whole child tree on Windows (`taskkill /T`).
+  It's guarded by an inline **confirm** (Kill / Cancel) since it's destructive,
+  the bot's **own** agent process is never offered (killing it would take the
+  bot down), and the session state is re-read at every step so a session that
+  already stopped reports "no longer running" instead of a phantom kill. The
+  existing `/killall` (stop every active session at once) is unchanged and now
+  shares the same kill logic.
+- **🔐 Re-authenticate Kiro from Telegram (`/reauth`).** Logs out
+  (`kiro-cli logout`) and starts a fresh **device-flow** login
+  (`kiro-cli login --use-device-flow`) — the verification URL + code are
+  **streamed into the chat** so you complete it on your own device — then
+  **restarts the agent** so it picks up the new credentials. Refused while a
+  turn is in flight (logging out would break it) and serialised so two runs
+  can't overlap. Pass-through flags are supported, e.g.
+  `/reauth --license free` or `/reauth --license pro --region <r> --identity-provider <url>`.
+- **📈 Live task-progress bar (`SHOW_PROGRESS`, on by default).** The agent is
+  asked to end each message with a `{progress: N%}` marker; the bot **parses and
+  hides** it and renders a **green 0–100 % loading bar** (`🟩🟩🟩⬜⬜⬜ 50%`,
+  all-green ✅ at 100 %) at the bottom of the **live message**, in the pinned
+  **status panel**, and on **`/running` and `/sessions` cards** — so you can see
+  how far along the current task is. Markers (and the instruction) are also
+  stripped from history, unread replays, previews and fork-priming, so the raw
+  plumbing never shows. Disable with `SHOW_PROGRESS=false`.
+- **🔀 "Switch to this session" on background pings.** A **`📨 From other
+  session`** Done/error notification now carries a **🔀 Switch to this session**
+  button that brings that session to the foreground in one tap.
+
+### Changed
+
+- **🪟 Windows install no longer needs admin.** `kiro-tg install` used to fail
+  with **`schtasks create failed: ERROR: Access is denied`** for a normal user,
+  because registering a **logon-triggered** Scheduled Task is a privileged
+  operation. The installer now falls back to a hidden per-user **Startup-folder**
+  launcher (runs at logon, **no elevation**) when the task can't be created; an
+  **elevated** run still uses the nicer hidden Scheduled Task. `install`,
+  `start`, `stop`, `status` and `uninstall` understand both mechanisms, and a
+  pre-launch running-check prevents a **double-launch** (two pollers on one bot
+  token would otherwise trigger Telegram 409 Conflict).
+- **🔕 No interim "Done" ping from a busy background session.** A background
+  ("other session") turn that still has **queued follow-ups** no longer pings an
+  intermediate "Done" — only the final, queue-empty turn announces completion,
+  so a session working through a queue doesn't spam you between steps.
+
 ## [1.6.0] - 2026-06-23
 
 The **"always-on & self-healing"** release — the bot keeps itself up to date,
@@ -300,6 +484,8 @@ from a single chat and switch between them, on a redesigned, compact menu.
   diffs, MarkdownV2 rendering, scheduled tasks, multi-image prompts, and a
   cross-platform 24/7 background service.
 
+[1.7.1]: https://github.com/artickc/kiro-telegram-bot/releases/tag/v1.7.1
+[1.7.0]: https://github.com/artickc/kiro-telegram-bot/releases/tag/v1.7.0
 [1.6.0]: https://github.com/artickc/kiro-telegram-bot/releases/tag/v1.6.0
 [1.5.1]: https://github.com/artickc/kiro-telegram-bot/releases/tag/v1.5.1
 [1.5.0]: https://github.com/artickc/kiro-telegram-bot/releases/tag/v1.5.0

package/README.md

@@ -27,13 +27,16 @@ and extended into a full multi-session client.
 | 🗂 **Projects** | `/projects` browses your folders and runs Kiro in the one you pick. |
 | ♻️ **Resume sessions** | `/sessions` lists recent Kiro sessions; tap to resume via ACP `session/load`. |
 | 🟢 **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. |
 | 🧩 **MCP control** | `/mcp` lists MCP servers, **health-checks** them (which connected / failed and why), and **enables/disables** them — then restarts the agent to apply. |
 | 👥 **Subagent visibility** | When Kiro delegates to subagents and waits on them, you see each one **start / work / finish** plus a live `🤖 N running` summary — and subagent permission prompts route to your chat. |
+| 📈 **Task progress bar** | The agent appends a `{progress: N%}` marker; the bot hides it and shows a **green 0–100% loading bar** on the live message, in the status panel, and on session cards (`SHOW_PROGRESS`). |
+| 🔐 **Re-auth from chat** | `/reauth` logs out and runs a device-flow login (URL + code streamed to your chat), then restarts the agent — no terminal needed. |
 | ⌨️ **Typing indicator** | Stays on for the whole turn, even through long tool chains. |
 | 📥 **Queued follow-ups** | Message while Kiro is busy — it's queued and runs next. `/btw` runs it ASAP (now if idle, else right after the current task); `/flush` runs the queue now. |
 | ✏️ **Edit diffs** | File edits show as unified `diff` blocks with `+N -M` stats. |
@@ -52,6 +55,9 @@ and extended into a full multi-session client.
 | Switch between projects | ✅ | ❌ |
 | Resume saved sessions | ✅ | ❌ |
 | Attach to **live** PC sessions (watch / fork) | ✅ | ❌ |
+| **Kill a session by PID** (or all at once) | ✅ | ❌ |
+| **Live task-progress bars** (`{progress: N%}`) | ✅ | ❌ |
+| **Re-authenticate from chat** (`/reauth`, device flow) | ✅ | ❌ |
 | Multiple isolated sessions | ✅ | ❌ (single shared) |
 | Queued follow-ups while busy | ✅ | ❌ |
 | **Scheduled tasks** (cron-like) | ✅ | ❌ |
@@ -75,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.
 
 ---
 
@@ -139,10 +154,16 @@ The platform is auto-detected:
 
 | OS | Mechanism | Starts on |
 |---|---|---|
-| Windows | Hidden Scheduled Task | logon |
+| Windows | Hidden Scheduled Task (elevated) · per-user **Startup folder** (no admin) | logon |
 | Linux | systemd **user** service (+ linger) | boot |
 | macOS | launchd LaunchAgent | login |
 
+On Windows, registering a logon-triggered Scheduled Task needs admin, so from a
+normal terminal `kiro-tg install` falls back to a hidden launcher in your
+per-user **Startup folder** (starts at logon, no elevation). Run it from an
+**elevated** terminal to use the Scheduled Task instead; either way `status`,
+`stop`, `restart` and `uninstall` work the same.
+
 ```bash
 npm run install:service     # install + start, enable autostart
 npm run service -- status   # show install + running state
@@ -182,6 +203,7 @@ Logs are written to `logs/kiro-telegram-bot.log` (rotated at 5 MB).
 /unwatch      Stop following a live session
 /model <id>   Switch the model for this session
 /restart      Restart the Kiro agent
+/reauth       Log out & log in to Kiro (device flow) · /reauth --license free|pro …
 /help         Show help
 ```
 
@@ -198,11 +220,13 @@ 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 %, activity and
-queue** (and how many sessions the chat controls), updating live. Pick **Agent**,
-**Reasoning** or **Model** from the inline menu (reasoning steers how thoroughly
-the agent works: Minimal → Max).
+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).
 
 ## ⏰ Scheduled tasks
 
@@ -237,6 +261,34 @@ prompt. Configure any OpenAI/Whisper-compatible endpoint via `STT_API_URL` in
 `.env`; leave `STT_LANGUAGE` blank for automatic detection (English, Russian,
 Romanian/Moldovan, and ~100 more).
 
+## 📈 Task progress
+
+The bot asks the agent to end each message with a `{progress: N%}` marker, then
+**hides the marker** and renders a **green loading bar** from 0–100 %
+(`🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜ 50%`, all-green ✅ at 100 %) so you can see how far along the
+current task is. The bar appears at the bottom of the **live message**, in the
+pinned **status panel**, and on **`/running` and `/sessions` cards**. Markers are
+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
+touching a terminal: the verification URL + code are streamed into the chat
+(open them on any device), and once you're logged in the agent is restarted to
+pick up the new credentials. It's refused while a turn is running, and you can
+pass login flags through, e.g. `/reauth --license free` or
+`/reauth --license pro --region <r> --identity-provider <url>`.
+
 ---
 
 ## 🧭 Working on several sessions at once
@@ -248,7 +300,8 @@ while the others keep working quietly. When you switch to a session you see its
 recent context and **every message that arrived while you were away** (its
 unread, recovered from the session log). Leave a task running in A, hop to B,
 reply, and come back to A to read what it did. Close a session with ✖ (it isn't
-killed — see `/killall` for that).
+killed) — or tap **🛑 Kill · pid N** on its `/sessions` · `/active` card to stop
+its process (and `/killall` to stop them all).
 
 ## 🔗 Connecting to live sessions
 
@@ -274,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`. |
@@ -283,10 +337,13 @@ Resuming an **idle** session loads it directly so you continue the exact thread.
 | `SHOW_EDIT_DIFFS` | no | `true` | Show unified diffs for edits. |
 | `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.6.0",
+  "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",
@@ -63,6 +63,9 @@
     "grammy": "^1.30.0",
     "tsx": "^4.19.2"
   },
+  "optionalDependencies": {
+    "@homebridge/node-pty-prebuilt-multiarch": "0.13.1"
+  },
   "devDependencies": {
     "@types/diff": "^7.0.0",
     "@types/node": "^22.10.0",

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`).");