grok-telegram-bot 2.4.0 → 2.5.0

package/.env.example

@@ -6,8 +6,11 @@
 # REQUIRED — Telegram bot token from @BotFather (https://t.me/BotFather)
 TELEGRAM_BOT_TOKEN=
 
-# RECOMMENDED — comma-separated Telegram user IDs allowed to use the bot.
-# Get yours from @userinfobot. If empty, ANYONE can use the bot (unsafe).
+# RECOMMENDED — comma-separated Telegram user IDs allowed to use the bot
+# (private chats AND groups / forum topics). Get yours from @userinfobot.
+# Example: ALLOWED_USERS=123456789,987654321
+# If empty, ANYONE can use the bot (unsafe — especially with TOPIC_GROUP_ID).
+# Unauthorized group members are ignored silently (no ⛔ spam in the group).
 ALLOWED_USERS=
 
 # ── Grok Build CLI ───────────────────────────────────────────────────────────
@@ -96,6 +99,36 @@ NOTIFY_OTHER_SESSIONS=true
 #   2) second
 # SUGGESTIONS_AUTO_APPROVE_PCT=95
 
+# ── Forum topics (optional project workspace) ────────────────────────────────
+# Telegram forum supergroup id (negative for supergroups). When set, the bot
+# probes the group at startup / /forum_setup:
+#   • not admin (or no Manage Topics) → ignore group for topic features
+#   • Topics off → best-effort try to enable (Bot API has no official method;
+#     if it fails, enable Topics manually in group settings and re-run setup)
+#   • Topics on + admin → creates "AI Chat" + optional per-project topics
+#     (TOPIC_AUTO_CREATE), paced + 429-retried for large catalogs
+#   • pins favicon / MSIX logo when found; user topics auto-bind on exact
+#     catalog name match only (else absolute path / exact name)
+# Messages in a topic run Grok sessions in that topic's project path.
+# TOPIC_GROUP_ID=
+# TOPIC_AUTO_CREATE=true
+# TOPIC_AI_CHAT_NAME=AI Chat
+
+# ── Sibling Telegram bots (agent "MCP-like" tools via JSON actions) ──────────
+# Comma-separated usernames (with or without @) the agent may call with
+# bot_command / list_bots after the first-prompt Telegram bridge directive.
+# Example: ALLOWED_TELEGRAM_BOTS=helperbot,other_bot
+# ALLOWED_TELEGRAM_BOTS=
+# Optional command catalogs (shown by list_bots / first-prompt teaching).
+# Compact:  TELEGRAM_BOT_COMMANDS=helperbot:status,help,ping;otherbot:start|Start,info
+# JSON:     TELEGRAM_BOT_COMMANDS={"helperbot":["status","help"],"otherbot":[{"command":"start","description":"Start"}]}
+# TELEGRAM_BOT_COMMANDS=
+# Hard timeout waiting for a sibling bot after /cmd@bot (ms). Default 45000.
+# TELEGRAM_BOT_REPLY_TIMEOUT_MS=45000
+# Quiet settle after last message/edit from that bot (ms) — "typing done" for
+# streaming bots that edit one message. Default 2000.
+# TELEGRAM_BOT_SETTLE_MS=2000
+
 # ── Self-recheck (once per user prompt, gated) ───────────────────────────────
 # After a successful user turn (queue empty), the bot may run one quality pass.
 # Flow:
@@ -110,6 +143,9 @@ NOTIFY_OTHER_SESSIONS=true
 # Optional: when set AND the AI decides recheck is needed, use this template
 # instead of the AI-written recheck body ({{USER}} / {{DONE}} placeholders).
 # SELF_RECHECK_PROMPT=
+# Max wait (ms) for quiet meta prompts (recheck decision + suggestions JSON).
+# On timeout the session prompt is cancelled so ✅ Done is not blocked forever.
+# QUIET_PROMPT_TIMEOUT_MS=90000
 
 # ── MCP servers (/mcp) ───────────────────────────────────────────────────────
 # /mcp lists MCP servers the bot can discover and health-checks them. Grok Build

package/CHANGELOG.md

@@ -7,7 +7,124 @@ 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.
 
-## [Unreleased]
+## [2.5.0] - 2026-08-05
+
+Forum project topics, cross-topic Telegram bridge, prompt anchors, and a more
+reliable Done / stop path for multi-topic groups.
+
+### Added
+
+- **Forum project topics (optional).** `TOPIC_GROUP_ID` manages a Telegram forum
+  supergroup: default **AI Chat** topic (workspace), optional auto-create one
+  topic per catalog project (`TOPIC_AUTO_CREATE`), favicon/MSIX logo discovery
+  pinned in the topic, and path-binding when users create new topics. Messages
+  in a topic run sessions in that project path.
+- **Telegram bridge actions (agent JSON).** On the first prompt of a session the
+  bot injects how-to-work memory: the agent may emit a fenced `json` block with
+  `"telegram": [ actions ]` to create forum topics, search session/topic memory,
+  list allowlisted sibling bots, and call them via `/cmd@bot` (MCP-like). Results
+  are fed back as a quiet follow-up turn (not a Done). Configure bots with
+  `ALLOWED_TELEGRAM_BOTS`, optional `TELEGRAM_BOT_COMMANDS` catalogs, reply
+  timeout / settle (`TELEGRAM_BOT_REPLY_TIMEOUT_MS`, `TELEGRAM_BOT_SETTLE_MS`).
+  Sibling-bot waits only accept content from the triggered bot (prefer reply-to
+  our trigger), collect edits until idle, and timeouts continue the session.
+  Bridge plumbing stays out of the chat (no “continuing session” / queue spam);
+  only durable side-effects like topic creation are announced.
+- **Cross-topic bridge actions.** From General / AI Chat (`GROK_WORKSPACE`), the
+  agent can orchestrate other forum topics via telegram JSON:
+  - `create_topic` with optional path
+  - **`set_path`** — bind/rebind a topic to an absolute path or exact catalog name
+  - **`send_prompt`** — inject a prompt into another topic’s session (`ran`/`queued`;
+    does not wait for that turn). Optional `new_session`.
+  Multiple actions run in order (cap **9**; up to **5** `send_prompt` per turn).
+  **New project paths:** agent `create_topic` / `set_path` with an absolute path
+  that does not exist yet **creates the folder** on disk, then binds the topic.
+- **New session on the persistent bar + `/new`.** Private chat: bar is
+  ☰ Menu · 🆕 New session / 🧭 Running · ⏹ Stop (not the inline Menu message).
+  Slash command `/new` (Telegram command list) starts a fresh session. Forum
+  topics keep New on the topic inline menu because reply keyboards are unreliable.
+- **Instant command feedback.** Slash commands and bar taps are deleted
+  immediately; handlers post bot status messages (e.g. `/new` →
+  “Creating new session…”) so the chat feels alive while the CLI/ACP starts.
+- **Prompt anchors + `#prompt_<id>`.** User prompts (text, photos, docs, voice,
+  `/btw`, suggestion taps) are re-posted as bot messages with a searchable
+  `#prompt_` tag; the originals are best-effort deleted. Photos, documents, and
+  voice/audio are re-attached on the anchor via Telegram `file_id` so media is
+  not lost when the user message is removed. All AI stream bubbles, Done/error
+  notices, and queue acks for that turn reply to the anchor and carry the same
+  tag (alongside `#proj_` / `#sess_`).
+
+### Changed
+
+- **Session card comments.** Cards (`/running`, `/sessions`, `/active`, status
+  panel) now show the **last user prompt** (max 250 chars). While a session is
+  running, a second line shows the **last AI agent thinking** (max 250). Idle
+  cards no longer use last-turn assistant outcome summaries as the comment.
+- **Stronger self-recheck prompts.** Decision + default recheck briefs now push
+  production-related completeness for the same feature (e.g. water→waves,
+  auth→rate limits), **finish-all** (no “still need…” / incomplete honest
+  leftovers that force critical follow-up buttons), and a required **per-bug
+  recheck checklist** at the end of the pass. Compose always injects those
+  rules when an AI brief looks complete (headers only) but omitted them.
+  `/new`, bar **New**, and inline **New** share the same success copy.
+
+### Fixed
+
+- **Missing `✅ Done` after a turn.** Done no longer waits on suggestion JSON
+  (send Done first, then attach buttons). Quiet meta prompts (recheck decision
+  + suggestions) use `QUIET_PROMPT_TIMEOUT_MS` (default 90s) and cancel the
+  session prompt on timeout so a hung meta call cannot block Done forever
+  (does not set user-cancelled / does not kill the agent). Chat shows
+  “Checking if a quality pass is needed…” while deciding recheck. Done text is
+  rebuilt after that wait so `/stop` mid-decision shows ⏹ Stopped. `notify`
+  retries truncated/plain text if the first send fails; a finally safety net
+  forces a short Done when one was expected but never delivered.
+- **`/stop` / `/cancel` must not kill the bot or other sessions.** Stop is
+  session-scoped only: soft ACP `session/cancel`, cancel pending permissions
+  for that session, and force-complete that session’s in-flight prompt after a
+  short grace if the agent is slow — **never** kill the shared `grok agent`
+  process (which multiplexes every chat/topic). `killPid` also refuses to
+  target the bot’s own Node process.
+- **`grok-tg install|start|restart` hang on Windows.** The service VBS is a
+  forever-restart loop (`Run …, True` waits for the bot). Launching it with
+  `execFileSync` made the CLI wait forever. Startup launches now use detached
+  `spawn` so the CLI returns immediately.
+- **No silent process death.** Exit paths always log reason + code to stderr/file;
+  instance-lock conflict uses exit 1; polling classifies 429/409/401/network with
+  backoff; interactive runs recover in-process (no detach re-exec that blanks the
+  terminal); ref'd keepalive every 5m; `beforeExit` keeps the process up if the
+  event loop empties unexpectedly. Updater re-exec inherits TTY stdio.
+- **Markdown / tool path rendering.** File paths in tool cards (Edit/Read/…) are
+  no longer wrapped in bold (Windows `C:\…` paths broke MarkdownV2 and fell
+  back to plain text that clients soft-render as `**Edit C:**`). Paths use
+  inline code; plain fallback demotes `**`/fences so soft-render cannot mangle
+  them. Chunked fences preserve tick length when reopening.
+- **Group / topic stop controls.** Forum topic menu leads with **Stop** + Running;
+  `/cancel` and `/stop` work in topics; group slash-command menu is a short,
+  sorted list with cancel first (private keeps the full sorted catalog). Stop
+  confirms in-thread (not only a toast).
+- **Forum topic bind: exact name only.** New user topics auto-bind when the
+  topic title exactly matches a catalog project (case-insensitive). Path prompts
+  and first messages no longer use fuzzy/partial project search (which could
+  bind the wrong folder). Unmatched topics still accept an absolute path or an
+  exact catalog name.
+- **Forum bulk topic create.** Startup/`/forum_setup` walks the **full** project
+  catalog (not a 200-item cap), paces creates, and retries on Telegram 429
+  (`retry_after`) and transient network errors so large catalogs (1000+) can
+  finish reliably across restarts.
+- **Forum group readiness.** Setup probes the configured group: if the bot is
+  not admin (or lacks Manage Topics), the group is **ignored** for topic
+  features. If Topics are off, the bot best-effort tries to enable them (no
+  official Bot API method today), otherwise ignores the group with a clear
+  status. Re-probes on promotion via `my_chat_member`; `/forum_setup` reports
+  ready vs disabled reason.
+
+### Docs
+
+- **README** updated for forum topics, bridge, prompt anchors, suggestions,
+  self-recheck, and related config.
+- **[docs/GROUP.md](./docs/GROUP.md)** — how to set up and use a forum project
+  group (binding, bridge actions, access control, troubleshooting).
 
 ## [2.4.0] - 2026-08-01
 
@@ -814,6 +931,7 @@ from a single chat and switch between them, on a redesigned, compact menu.
   diffs, MarkdownV2 rendering, scheduled tasks, multi-image prompts, and a
   cross-platform 24/7 background service.
 
+[2.5.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.5.0
 [2.4.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.4.0
 [2.3.1]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.3.1
 [2.3.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.3.0

package/README.md

@@ -27,9 +27,15 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | Capability | What it does |
 |---|---|
 | 🗂 **Projects** | `/projects` browses your folders and runs Grok in the one you pick. |
+| 🏷 **Forum project topics** | Optional forum supergroup: one topic per project, **AI Chat** workspace, exact-name bind, `/forum_setup`. See **[docs/GROUP.md](./docs/GROUP.md)**. |
+| 🌉 **Telegram bridge** | Agent can `create_topic`, `set_path`, `send_prompt` across topics, `search_memory`, and call allowlisted sibling bots via JSON actions. |
+| 🔖 **Prompt anchors** | Each user prompt is re-posted with a searchable `#prompt_…` tag; stream/Done messages reply to that anchor (media re-attached). |
+| 🆕 **New session** | `/new` or the bar **New** button starts a fresh session; forum topics keep New on the topic menu. |
+| 💡 **Post-turn suggestions** | After Done, 1–3 scored follow-ups as buttons; high-score items can auto-queue as one multi-step prompt. |
+| 🔍 **Gated self-recheck** | After file-changing turns, an optional quality pass runs once before Done (`SELF_RECHECK`). |
 | ♻️ **Resume sessions** | `/sessions` lists recent Grok sessions; tap to resume one (`grok --session <id>`). |
 | 🟢 **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. |
+| 🛑 **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. **Stop** only cancels the current session turn — never the shared agent. |
 | 📡 **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 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. |
@@ -49,7 +55,7 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | 💬 **Quality markdown** | Converts agent markdown to Telegram **MarkdownV2** with safe escaping and code-fence-aware splitting. |
 | 🔁 **Self-healing** | Auto-restarts the Grok agent with backoff and re-binds your session. |
 | 🖥 **Runs 24/7** | 1-click install as a background service that starts on boot — Windows, Linux, macOS, auto-detected. |
-| 🔒 **Access control** | Restrict to specific Telegram user IDs. |
+| 🔒 **Access control** | Restrict to specific Telegram user IDs (private chats **and** forum groups). |
 
 ---
 
@@ -59,6 +65,8 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 |---|:---:|:---:|
 | Connect Grok CLI to Telegram (ACP) | ✅ | ✅ |
 | Switch between projects | ✅ | ❌ |
+| **Forum topics = projects** + AI Chat workspace | ✅ | ❌ |
+| **Cross-topic agent bridge** (create / bind / send_prompt) | ✅ | ❌ |
 | Resume saved sessions | ✅ | ❌ |
 | Attach to **live** PC sessions (watch / fork) | ✅ | ❌ |
 | **Kill a session by PID** (or all at once) | ✅ | ❌ |
@@ -69,6 +77,7 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | **Session auto-approve** + **pinned** interactive permissions | ✅ | ❌ |
 | Multiple isolated sessions | ✅ | ❌ (single shared) |
 | Queued follow-ups while busy | ✅ | ❌ |
+| **Post-turn suggestions** + gated self-recheck | ✅ | ❌ |
 | **Scheduled tasks** (cron-like) | ✅ | ❌ |
 | **Multi-image** prompts (albums) | ✅ | ❌ |
 | Unified **edit diffs** | ✅ | ❌ |
@@ -216,14 +225,16 @@ Logs are written to `logs/grok-telegram-bot.log` (rotated at 5 MB).
 /tasks        Manage scheduled tasks
 /newtask      Create a scheduled task (wizard)
 /history      Show recent conversation history
-/new          Start a fresh session here
+/new          Start a fresh session here (also bar: 🆕 New session)
+/forum_setup  Re-probe / create forum topics (use inside the configured group)
 /status       Current session, project & queue
 /usage        Account info & current context usage
 /btw <text>   Run it now if idle, else queue to run right after the current task
 /flush        Send queued follow-ups now
 /queue        Show queued follow-ups
 /clearqueue   Clear the queue
-/cancel       Stop the current turn
+/cancel       Stop the current turn (session-scoped — never kills the shared agent)
+/stop         Same as /cancel
 /unwatch      Stop following a live session
 /model <id>   Switch the model for this session
 /restart      Restart the Grok agent
@@ -237,13 +248,28 @@ running, your messages are queued and sent automatically when it finishes.
 
 ---
 
+## 🏷 Forum project group (optional)
+
+Drive **many projects in parallel** from one Telegram forum supergroup: each
+topic is bound to a folder, and **AI Chat** stays on `GROK_WORKSPACE` for
+orchestration. Set `TOPIC_GROUP_ID`, make the bot admin with Manage Topics, and
+run `/forum_setup`. Full walkthrough (binding rules, agent bridge, access
+control, troubleshooting):
+
+**→ [docs/GROUP.md](./docs/GROUP.md)**
+
+---
+
 ## 🧭 The menu & status panel
 
-A tiny **persistent bar** sits under the message box — **☰ Menu · 🧭 Running ·
-⏹ Stop** — so common actions are one tap away without clutter. Tap **☰ Menu**
-(or `/menu`) to open a clean, grouped **inline menu**: Project · New · Running ·
-Sessions · Agent · Model · Reasoning · Tasks · Status · Usage · Stop · Kill all.
-The bar can be hidden (🙈) and restored (⌨️ Show bar or `/menu`).
+A tiny **persistent bar** sits under the message box — **☰ Menu · 🆕 New session
+· 🧭 Running · ⏹ Stop** (while idle/busy the middle button may show Running
+instead of New) — so common actions are one tap away without clutter. Tap
+**☰ Menu** (or `/menu`) to open a clean, grouped **inline menu**: Project ·
+Running · Sessions · Agent · Model · Reasoning · Tasks · Status · Usage · Stop ·
+Kill all. Forum topics keep **New** on the topic inline menu (reply keyboards are
+unreliable there). The bar can be hidden (🙈) and restored (⌨️ Show bar or
+`/menu`).
 
 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
@@ -403,9 +429,9 @@ Resuming an **idle** session loads it directly so you continue the exact thread.
 | Variable | Required | Default | Description |
 |---|---|---|---|
 | `TELEGRAM_BOT_TOKEN` | **yes** | — | Bot token from @BotFather. |
-| `ALLOWED_USERS` | recommended | *(all)* | Comma-separated Telegram user IDs. Empty = anyone (unsafe). |
+| `ALLOWED_USERS` | recommended | *(all)* | Comma-separated Telegram user IDs for private chats **and** groups. Empty = anyone (unsafe — never leave empty with `TOPIC_GROUP_ID`). Unauthorized group members are ignored silently. |
 | `GROK_CLI_PATH` | no | auto / `grok` | Path to the `grok` binary. |
-| `GROK_WORKSPACE` | no | cwd | Default working directory. |
+| `GROK_WORKSPACE` | no | cwd | Default working directory (also AI Chat / General in a forum group). |
 | `XAI_API_KEY` | no | — | xAI API key, only for headless hosts with no browser. Normally you sign in with `grok login` (or `/reauth`) — no key needed. Exported to the agent when set. |
 | `GROK_MODEL` | no | `grok-4.5` | Default model for new sessions. |
 | `GROK_TG_DIR` | no | `~/.grok/tg` | Folder holding this instance's `.env`, `logs/`, `data/`. Resolution: `--instance` → `GROK_TG_DIR` → a `.env` in the current folder → `~/.grok/tg`. So a `.env` created once is loaded from any startup path. |
@@ -423,6 +449,18 @@ Resuming an **idle** session loads it directly so you continue the exact thread.
 | `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. |
+| `SUGGESTIONS_ENABLED` | no | `true` | After Done, quietly ask for 1–3 scored follow-ups shown as buttons. |
+| `SUGGESTIONS_AUTO_APPROVE_PCT` | no | `95` | Auto-queue suggestions with need ≥ this % as one multi-step prompt (`0` = buttons only). |
+| `SELF_RECHECK` | no | `true` | After a successful user turn that modified files, optionally run one gated quality pass before Done. Alias: `SLEF_RECHECK`. |
+| `SELF_RECHECK_PROMPT` | no | — | Optional fixed recheck template when AI decides recheck is needed (`{{USER}}` / `{{DONE}}`). |
+| `QUIET_PROMPT_TIMEOUT_MS` | no | `90000` | Max wait for quiet meta prompts (recheck decision + suggestions). Timeout cancels the meta prompt so Done is not blocked. |
+| `TOPIC_GROUP_ID` | no | — | Forum supergroup id for project topics. Bot must be admin with Manage Topics. See **[docs/GROUP.md](./docs/GROUP.md)**. |
+| `TOPIC_AUTO_CREATE` | no | `true` | When forum is ready, create one topic per catalog project (paced + 429-retried). |
+| `TOPIC_AI_CHAT_NAME` | no | `AI Chat` | Display name for the workspace topic. |
+| `ALLOWED_TELEGRAM_BOTS` | no | — | Comma-separated sibling bot usernames the agent may call via bridge `bot_command` / `list_bots`. |
+| `TELEGRAM_BOT_COMMANDS` | no | — | Optional command catalogs for sibling bots (compact or JSON; see `.env.example`). |
+| `TELEGRAM_BOT_REPLY_TIMEOUT_MS` | no | `45000` | Hard timeout waiting for a sibling bot after `/cmd@bot`. |
+| `TELEGRAM_BOT_SETTLE_MS` | no | `2000` | Quiet settle after the last message/edit from that bot. |
 | `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. |
 | `GROK_AUTO_RESTART` | no | `true` | Auto-restart the agent if it exits. |
@@ -475,11 +513,12 @@ src/
 ├── grok/                 Grok bridge: headless client, JSONL types, models, session log
 ├── sessions/             Session discovery, history parser, live tail watcher
 ├── projects/             Project directory discovery
+├── forum/                Forum topic store, path bind, project icons
 ├── mcp/                  MCP config (list/toggle) + live health probe
 ├── render/               Markdown→MarkdownV2, diffs, tool formatting, chunking
 ├── stream/               Incremental edit-streaming
 ├── service/              Cross-platform daemon (windows/linux/macos + selector)
-└── bot/                  grammY bot, per-chat runtime, handlers
+└── bot/                  grammY bot, per-chat runtime, handlers, Telegram bridge
 ```
 
 ---
@@ -549,10 +588,13 @@ user. See [SECURITY.md](./SECURITY.md) for the full model.
 - [x] Device-code `/reauth` (no host browser) + real email labels from auth.json
 - [x] Rich per-kind tool-call detail (search / edit diffs / shell / MCP / …)
 - [x] README community sections — Contributors, Top Contributors, Stars, StarMapper
+- [x] Forum project topics + AI Chat workspace (`TOPIC_GROUP_ID`)
+- [x] Cross-topic Telegram bridge (`create_topic` / `set_path` / `send_prompt` / …)
+- [x] Prompt anchors, post-turn suggestions, gated self-recheck
 - [ ] **Token & cost meter** — per-session token counts and an estimated spend tally
 - [ ] **Text-to-speech replies** — optionally speak answers back as voice notes
 - [ ] **Scheduled-task chaining & conditions** — run task B after A, or only if a command/file check passes
-- [ ] **Team mode** — multiple authorized users with per-user sessions, roles, and an audit log
+- [ ] **Team mode** — roles and audit log beyond shared `ALLOWED_USERS` + forum topics
 - [ ] Localized bot UI (i18n)
 - [ ] Docker image with `grok` preinstalled
 - [ ] Webhook mode for serverless deployment
@@ -657,8 +699,9 @@ Grab the latest packaged build from the
 release ships a clean `grok-telegram-bot-<version>.zip` (no `node_modules` or
 secrets) plus GitHub's source archives. See [CHANGELOG.md](./CHANGELOG.md) for
 what changed in each version, **[docs/INSTALL.md](./docs/INSTALL.md)** for the
-full 1-click install guide, and **[docs/UPGRADE.md](./docs/UPGRADE.md)** for how
-to update an existing install (npm, zip, or source).
+full 1-click install guide, **[docs/UPGRADE.md](./docs/UPGRADE.md)** for how to
+update an existing install (npm, zip, or source), and
+**[docs/GROUP.md](./docs/GROUP.md)** for forum project topics.
 
 ---
 

package/docs/GROUP.md

@@ -0,0 +1,225 @@
+# Forum project group
+
+Use a **Telegram forum supergroup** so each project gets its own topic. The bot
+runs Grok sessions **in the bound project path** for that topic, while the
+default **AI Chat** topic stays on your workspace (`GROK_WORKSPACE`).
+
+This is optional. Private DMs with the bot still work exactly as before.
+
+---
+
+## Prerequisites
+
+1. A **supergroup** with **Topics** enabled (Telegram group settings → Topics).
+2. The bot is an **administrator** with **Manage Topics** (and enough rights to
+   post / pin when you want icons or setup announcements).
+3. Your bot token and allowlist configured as usual:
+   - `TELEGRAM_BOT_TOKEN`
+   - **`ALLOWED_USERS`** — required for groups. Unauthorized members are
+     **ignored silently** (no ⛔ spam). Empty allowlist with a forum group is
+     unsafe (any member could drive the host).
+4. `PROJECT_ROOTS` / catalog so project names resolve (same roots as `/projects`).
+
+---
+
+## Configure
+
+In `.env` (or `~/.grok/tg/.env` for a global npm install):
+
+```ini
+# Negative Telegram chat id of the forum supergroup
+TOPIC_GROUP_ID=-100xxxxxxxxxx
+
+# Default true: create one topic per catalog project (paced + 429-retried)
+TOPIC_AUTO_CREATE=true
+
+# Display name for the workspace topic (default AI Chat)
+TOPIC_AI_CHAT_NAME=AI Chat
+
+# Workspace used in General / AI Chat
+GROK_WORKSPACE=C:\path\to\workspace
+
+# Where /projects and exact-name topic binds look for folders
+PROJECT_ROOTS=C:\path\to\Domains,H:\Lucru\Domains
+```
+
+Restart the bot after changing these. On startup the bot **probes** the group:
+
+| Probe result | Behavior |
+|---|---|
+| Not admin / no Manage Topics | Group **ignored** for topic features |
+| Topics off | Best-effort try to enable; if Telegram has no API for it, group ignored until you enable Topics manually |
+| Admin + Topics on | **Ready** — creates AI Chat (and optional project topics) |
+
+Re-run setup any time from inside the group:
+
+```
+/forum_setup
+```
+
+You get a clear **ready** vs **disabled (reason)** status and the mapped topic count.
+
+When the bot is later promoted to admin, it re-probes automatically (`my_chat_member`).
+
+---
+
+## Topic model
+
+| Topic | Working directory | Typical use |
+|---|---|---|
+| **General** / **AI Chat** | `GROK_WORKSPACE` | Orchestration, cross-project planning, agent bridge actions |
+| **Project topic** | Bound project path | All coding work for that folder |
+| **User-created topic** | Bound after name/path match | Ad-hoc projects or new folders |
+
+Messages you send **inside a topic** are prompts for a session whose `cwd` is
+that topic’s path. Menus, model/reasoning picks, `/sessions`, `/running`, and
+Stop are **topic-scoped** so one project does not steal another’s session.
+
+In topics the persistent reply keyboard is unreliable, so use the **topic
+inline menu** (Stop + Running + …) or slash commands (`/new`, `/stop`, …).
+
+---
+
+## Binding a topic to a project
+
+### Auto-bind (exact name only)
+
+If you create a topic whose title **exactly** matches a catalog project name
+(case-insensitive), the bot binds it immediately and confirms the path.
+
+Fuzzy / partial matching is **not** used (it used to pick the wrong folder).
+
+### Manual bind
+
+If there is no exact catalog match, the bot asks you to send:
+
+- an **absolute directory path**, or
+- an **exact** catalog project name
+
+Examples:
+
+```text
+H:\Lucru\Domains\MyApp
+MyApp
+```
+
+### Agent bind (Telegram bridge)
+
+From **AI Chat / General**, the agent can create topics and bind paths via a
+fenced JSON block (see [Agent bridge](#agent-bridge-cross-topic-actions)).
+Absolute paths that **do not exist yet are created on disk**, then bound
+(new-project flow).
+
+### One path, one topic
+
+A catalog path is only bound to **one** topic. If the same exact name/path is
+already used, the bot says so and asks for another path or name.
+
+---
+
+## Day-to-day usage
+
+1. Open the **project topic** (or create one and bind it).
+2. Chat normally — each message is a Grok prompt in that project.
+3. **`/new`** or the menu **New** button starts a fresh session in that topic.
+4. **Stop** / `/stop` / `/cancel` only cancels **this topic’s** in-flight turn —
+   never the shared `grok agent` process (other topics keep running).
+5. Attach photos, documents, and (with STT configured) voice the same as in DM.
+6. User prompts are re-posted as **prompt anchors** with a searchable
+   `#prompt_…` tag; replies and Done messages thread to that anchor.
+
+### Multi-project orchestration
+
+In **AI Chat**, ask the agent to open a project elsewhere, e.g. “Create a topic
+for MyApp at `H:\Projects\MyApp` and scaffold a README there.” The agent emits
+bridge actions; the bot creates the topic, binds the path, and can
+`send_prompt` into that topic without you switching threads manually.
+
+---
+
+## Agent bridge (cross-topic actions)
+
+On the **first prompt of a session** the bot teaches the agent a small protocol:
+emit a fenced `json` block with a `"telegram"` array (up to **9** actions per
+turn; up to **5** `send_prompt`). The bridge strips the fence from the chat and
+may feed results back as a quiet system turn (not a second Done).
+
+| Action | Purpose |
+|---|---|
+| `create_topic` | New forum topic; optional `path` binds immediately |
+| `set_path` | Bind/rebind topic by title or `#threadId` |
+| `send_prompt` | Inject a prompt into another topic (`ran` / `queued`; optional `new_session`) |
+| `search_memory` | Search topic + session indexes |
+| `list_bots` | List allowlisted sibling bots |
+| `bot_command` | Call `/command@bot` and wait for that bot to settle |
+
+Example (from General / AI Chat):
+
+```json
+{
+  "telegram": [
+    {
+      "action": "create_topic",
+      "name": "MyApp",
+      "path": "H:\\Projects\\MyApp"
+    },
+    {
+      "action": "send_prompt",
+      "topic": "MyApp",
+      "prompt": "1) scaffold\n2) tests\n3) README"
+    }
+  ]
+}
+```
+
+`topic` may be the exact title, `#threadId`, `general`, or `ai chat`.
+
+---
+
+## Sibling bots (optional)
+
+To let the agent call other Telegram bots you control:
+
+```ini
+ALLOWED_TELEGRAM_BOTS=helperbot,other_bot
+# Optional catalogs for list_bots / teaching:
+# TELEGRAM_BOT_COMMANDS=helperbot:status,help;otherbot:start|Start,info
+# TELEGRAM_BOT_REPLY_TIMEOUT_MS=45000
+# TELEGRAM_BOT_SETTLE_MS=2000
+```
+
+Only usernames on the allowlist can be invoked. Timeouts return `ok=false` and
+do **not** count as Done.
+
+---
+
+## Access control
+
+| Setting | Effect |
+|---|---|
+| `ALLOWED_USERS` set | Only listed user IDs can prompt (DM **and** group topics) |
+| Not allowlisted | Updates ignored **silently** in the group |
+| Empty allowlist | Anyone can use the bot — **do not combine with `TOPIC_GROUP_ID`** |
+
+---
+
+## Troubleshooting
+
+| Symptom | What to check |
+|---|---|
+| Topics never created | Bot admin + Manage Topics; Topics enabled; `TOPIC_GROUP_ID` exact (negative id); `/forum_setup` |
+| “Group ignored” | Status text from `/forum_setup` (`not_admin`, `not_forum`, …) |
+| Wrong folder bound | Title must **exactly** match catalog name; re-bind with absolute path |
+| Agent can’t create topics | Forum must be **ready**; work from AI Chat / General for orchestration |
+| Unauthorized spam / silent ignore | Confirm your id in `ALLOWED_USERS`; others are silent by design |
+| Stop kills everything | Should not — upgrade if an old build killed the shared agent; Stop is session-scoped |
+| Large catalog slow | Bulk create is paced and 429-retried; re-run `/forum_setup` to continue |
+
+---
+
+## Related
+
+- [README](../README.md) — full feature list and config table
+- [INSTALL.md](./INSTALL.md) — first-time setup
+- [UPGRADE.md](./UPGRADE.md) — updating an existing install
+- `.env.example` — all forum / bridge env vars with comments

package/docs/INSTALL.md

@@ -41,6 +41,9 @@ grok-tg run                     # run in the foreground (Ctrl-C to stop)
 
 > ⚠️ **Set `ALLOWED_USERS`** in `.env` to your Telegram user ID(s). Empty means
 > *anyone* who finds the bot can run commands on your machine.
+>
+> Optional: drive one project per **forum topic** with `TOPIC_GROUP_ID` — see
+> **[GROUP.md](./GROUP.md)** after the bot is running.
 
 ### Startup options (`grok-tg <command>`)
 

package/package.json

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

package/src/app/lifetime-flag.ts

@@ -0,0 +1,20 @@
+/**
+ * Cross-module intentional-exit flag so beforeExit keep-alive and the polling
+ * loop do not fight updater re-exec / fatal exits / SIGINT.
+ */
+let intentional = false;
+let reason = "";
+
+/** Mark that the process is exiting on purpose (do not keep-alive). */
+export function markIntentionalShutdown(why: string): void {
+  intentional = true;
+  reason = why;
+}
+
+export function isIntentionalShutdown(): boolean {
+  return intentional;
+}
+
+export function intentionalShutdownReason(): string {
+  return reason;
+}