grok-telegram-bot 2.5.0 → 2.7.0

package/.env.example

@@ -40,6 +40,19 @@ GROK_TRUST_ALL_TOOLS=true
 # Approve/Deny buttons in Telegram.
 AUTO_APPROVE_PERMISSIONS=true
 
+# Auto-approve Grok plan-mode exit (no Approve / Request changes / Abandon).
+# Default true so 24/7 unattended bots never wait. Set false for Telegram review.
+# AUTO_APPROVE_PLAN=true
+
+# Optional Grok agent env (applied on process start / after /restart).
+# GROK_SANDBOX=workspace-safe
+# GROK_MEMORY=
+# GROK_AGENT_PROFILE=
+# GROK_PLUGIN_DIR=
+
+# Named instance slug (same as grok-tg --name). Optional.
+# GROK_TG_NAME=
+
 # Comma-separated roots the /projects browser is allowed to list.
 # Supports ~ for home directory. Defaults to GROK_WORKSPACE's parent + home.
 # Example: H:\Lucru\Domains,C:\Lucru\Domains

package/CHANGELOG.md

@@ -7,6 +7,110 @@ 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.
 
+## [2.7.0] - 2026-08-30
+
+Contributor batch from [@vincenthehna](https://github.com/vincenthehna) (PRs
+#6–#8), ported onto current main and credited here. PR #9 (one process / many
+tokens) was **not** merged: it conflicts with forum General + `TOPIC_GROUP_ID`
+(which bot owns the group?) and with the named-instance model.
+
+### Added
+
+- **Grok Build slash catalog on Telegram** (PR #6 / #7). `/goal`, `/plan`,
+  `/compact`, `/workflow(s)`, `/deep_research`, memory/imagine commands, and
+  other ACP-useful shell builtins are advertised (menu ≤100) and forwarded into
+  the active session (`executeCommand` then prompt fallback). Underscores map
+  to Grok hyphens; collision aliases (`/grok_new`, `/memory_flush`, …) keep
+  bot-owned bare names. `/goal` is refused in **General** (use a project topic
+  or AI Chat). Catch-all forwards unknown Grok/skills slashes.
+- **Named instances** (PR #8). `grok-tg --name work setup|install|status`
+  gives each BotFather token its own `~/.grok/tg/instances/<slug>/` and unique
+  OS service (`grok-telegram-bot-work`). `grok-tg instances` lists them. Default
+  bot and `TELEGRAM_BOT_TOKEN` are unchanged.
+- **Optional interactive plan review** (PR #7). `AUTO_APPROVE_PLAN=false`
+  shows Approve / Request changes / Abandon (timeout still unblocks). Default
+  remains auto-approve so 24/7 unattended bots never wait. `ask_user_question`
+  gets Telegram buttons unless auto-skip is on.
+- **`/sandbox`** plus spawn env: `GROK_SANDBOX`, `GROK_MEMORY`,
+  `--agent-profile`, `--plugin-dir`. `session/new` sets `_meta.yoloMode` when
+  tools are trusted.
+- **CI workflow** (`typecheck` job) so `main` can require status checks.
+
+### Docs
+
+- README / INSTALL: several bots on one host via `--name`.
+- AGENTS.md: CLI instances.
+
+## [2.6.0] - 2026-08-30
+
+General becomes a chat-like **manager** for the forum group: memory-first
+routing, `send_prompt` into project topics with job report-back, and **visible
+short replies** (the previous notify-only quiet path looked like the bot was
+dead). Also bumps runtime deps (`tsx`, `grammy`).
+
+### Added
+
+- **General manager mode.** The forum **General** topic (`thread id 1`) is an
+  OpenClaw-style orchestrator, not a coding workspace. It keeps user messages,
+  starts a **new parallel session** per message (reply-to continues the same
+  session), streams **prose only** (no tools / progress / Done spam), and
+  dispatches real work into project topics.
+- **Manager directive + auto context.** First General prompt injects how to
+  behave (delegate, memory-first, no git-first). Every user turn also gets a
+  capped **MANAGER CONTEXT** block: topic catalog, recent General chat, ranked
+  memory hits, and in-process manager jobs.
+- **Manager jobs + work reports.** `send_prompt` from General registers a job
+  (`list_jobs`). When the child topic turn finishes, General is woken with a
+  structured `MANAGER WORK REPORT` so the manager can tell you done / failed.
+- **Bridge: `notify`, `list_topics`, `list_jobs`, `session_id`.**
+  - `notify` — optional extra ping (not required in General; prose is shown).
+  - `list_topics` / `list_jobs` — catalog and dispatch status for the agent.
+  - `send_prompt.session_id` — resume a **specific** Grok session (full UUID or
+    short prefix from memory). Topic may be omitted; path → forum topic is
+    inferred. Placeholder topics (`…`) are rejected / inferred from memory.
+- **Group memory ranking.** `search_memory` scores **relevance + recency**
+  (newest session per project path wins) so “last modifications” does not
+  surface stale Done notes. Hits include `[Xm/h/d ago]` stamps.
+- **Outbound General thread helper.** Telegram rejects `message_thread_id: 1`.
+  Sends/edits to General omit that field (`outboundThreadExtra`); inbound
+  routing still treats missing thread id as General.
+
+### Changed
+
+- **General UX.** User messages are **kept** (not replaced by prompt anchors).
+  Replies thread to the user message. A `Starting…` / `Thinking…` bubble is
+  edited in place into the short answer. Independent General messages no longer
+  coalesce into one queued turn.
+- **Prose is the user-facing channel.** The manager is told the user **sees**
+  free-form chat text. `notify` is optional. Bridge-result follow-ups (after
+  `search_memory` / `list_topics`) stream the real answer instead of staying
+  silent. If the model emits no prose, the Thinking bubble is replaced with a
+  short fallback — never deleted leaving an empty chat.
+- **Streamer prose-only mode.** General streams agent text only (no thoughts,
+  tools, plan board, or progress bar), seeded on the Thinking placeholder.
+- **Forum send path.** `sendMessage` / stream edits / auth deny / prompt
+  anchors / photos / docs use `outboundThreadExtra` so General posts succeed.
+- **Dependencies.** `tsx` `^4.19.2` → `^4.23.13`; `grammy` and `@types/node`
+  updated to current 1.x / 22.x wanted versions.
+
+### Fixed
+
+- **Bot not responding in General after manager-mode work.** Notify-only +
+  deleting `Thinking…` when `search_memory` chained made every answer vanish.
+  General now streams short prose, keeps the status bubble across bridge
+  follow-ups, and never drops the placeholder without a visible line.
+- **`message_thread_id: 1` rejected by Telegram** (“message thread not found”)
+  on General sends — omit the field for General; keep it for real topics.
+- **Manager context path trap.** Recent General history no longer treats every
+  session under the workspace root as General chat (title + exact cwd only).
+
+### Docs
+
+- **[docs/GROUP.md](./docs/GROUP.md)** — General = manager, memory-first
+  dispatch, `session_id`, `list_jobs`, prose vs `notify`.
+- **AGENTS.md** — General manager conventions for future changes.
+- **README** — General manager + expanded bridge actions.
+
 ## [2.5.0] - 2026-08-05
 
 Forum project topics, cross-topic Telegram bridge, prompt anchors, and a more
@@ -931,6 +1035,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.
 
+[2.7.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.7.0
+[2.6.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.6.0
 [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

package/README.md

@@ -27,8 +27,9 @@ 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. |
+| 🏷 **Forum project topics** | Optional forum supergroup: **General** manager, **AI Chat** workspace, one topic per project, exact-name bind, `/forum_setup`. See **[docs/GROUP.md](./docs/GROUP.md)**. |
+| 🎛 **General manager** | Forum General is a chat-like orchestrator: memory-first, short replies, `send_prompt` into project topics, report-back when child work finishes. |
+| 🌉 **Telegram bridge** | Agent can `create_topic`, `set_path`, `send_prompt` (optional `session_id`), `notify`, `search_memory`, `list_topics` / `list_jobs`, 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. |
@@ -66,7 +67,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) | ✅ | ❌ |
+| **General manager** (memory-first, dispatch + report-back) | ✅ | ❌ |
+| **Cross-topic agent bridge** (create / bind / send_prompt / session_id) | ✅ | ❌ |
 | Resume saved sessions | ✅ | ❌ |
 | Attach to **live** PC sessions (watch / fork) | ✅ | ❌ |
 | **Kill a session by PID** (or all at once) | ✅ | ❌ |
@@ -118,8 +120,21 @@ 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 `grok-tg run` yields to an already-running background service instead.
 
-Startup options: `grok-tg setup [--path] | run | install | status | logs [n] |
-stop | restart | uninstall`. Or try it without installing: `npx
+Want a **second Telegram bot** (one private chat per project) without switching
+sessions? Create another bot in @BotFather and:
+
+```bash
+grok-tg --name work setup <NEW_BOT_TOKEN> <YOUR_USER_ID>
+grok-tg --name work install
+grok-tg instances
+```
+
+Each named instance has its own `~/.grok/tg/instances/<slug>/` and unique
+service (`grok-telegram-bot-work`). The default bot is unchanged.
+
+Startup options: `grok-tg [--name <slug>] setup [--path] | run | install |
+status | logs [n] | stop | restart | uninstall | instances`. Or try it without
+installing: `npx
 grok-telegram-bot setup`. See **[docs/INSTALL.md](./docs/INSTALL.md)** for the
 full guide.
 

package/docs/GROUP.md

@@ -67,11 +67,24 @@ When the bot is later promoted to admin, it re-probes automatically (`my_chat_me
 
 | Topic | Working directory | Typical use |
 |---|---|---|
-| **General** / **AI Chat** | `GROK_WORKSPACE` | Orchestration, cross-project planning, agent bridge actions |
+| **General** | `GROK_WORKSPACE` | **Manager chat** (OpenClaw-style): routes work, memory-first, no coding spam |
+| **AI Chat** | `GROK_WORKSPACE` | Normal coding/conversation in the workspace |
 | **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
+### General = manager
+
+Messages in **General** drive a chat-like orchestrator, not a coding agent:
+
+1. User asks in General (e.g. “fix login in MyApp”).
+2. Bot uses **memory + topic catalog** (auto-injected) and may call `search_memory` / `list_topics`.
+3. It replies briefly (“OK — I’ll start … in **MyApp**”) with **no progress bars / tool dumps**.
+4. It **dispatches** via `create_topic` / `set_path` / `send_prompt` into the right project topic.
+5. When that child turn finishes, the bridge **wakes General** with a `MANAGER WORK REPORT` so the manager summarizes success/fail for you.
+
+Real implementation stays in **project topics**. General should not edit app code.
+
+Messages you send **inside a project 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.
 
@@ -148,8 +161,11 @@ may feed results back as a quiet system turn (not a second Done).
 |---|---|
 | `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 |
+| `send_prompt` | Inject a prompt into another topic (`ran` / `queued`; optional `new_session`, **`session_id`** to resume a specific session) |
+| `notify` | Optional extra ping. In **General** the user already sees short chat prose; `notify` is not required. |
+| `search_memory` | Search topic + session indexes (memory-first) |
+| `list_topics` | List mapped forum topics (name, `#id`, path) |
+| `list_jobs` | List recent General → project dispatches |
 | `list_bots` | List allowlisted sibling bots |
 | `bot_command` | Call `/command@bot` and wait for that bot to settle |
 
@@ -174,6 +190,25 @@ Example (from General / AI Chat):
 
 `topic` may be the exact title, `#threadId`, `general`, or `ai chat`.
 
+To **resume a related session** found via memory (not the topic's currently open session):
+
+```json
+{
+  "telegram": [
+    {
+      "action": "send_prompt",
+      "topic": "MyApp",
+      "session_id": "019fc9ec",
+      "prompt": "Continue: apply the follow-up fix."
+    }
+  ]
+}
+```
+
+`session_id` may be a full UUID or a short prefix from memory hits. Without it, the bridge uses the topic's foreground session.
+
+`topic` must be an **exact** mapped title or `#threadId` (never placeholders like `…`). If only the session is known, omit `topic` — the bridge maps `session.cwd` → forum topic.
+
 ---
 
 ## Sibling bots (optional)

package/docs/INSTALL.md

@@ -56,6 +56,8 @@ grok-tg run                     # run in the foreground (Ctrl-C to stop)
 | `grok-tg logs [n]` | Tail the last `n` log lines (default 100). |
 | `grok-tg stop` / `restart` / `start` | Control the running service. |
 | `grok-tg uninstall` | Stop + remove the background service. |
+| `grok-tg --name <slug> …` | Same commands for a **second Telegram bot** (own token, own chat, own service). |
+| `grok-tg instances` | List the default bot and every named instance. |
 | `grok-tg help` | Show all commands. |
 
 The background service is **user-level** and auto-detected per platform — a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-telegram-bot",
-  "version": "2.5.0",
+  "version": "2.7.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",
@@ -60,15 +60,15 @@
   "dependencies": {
     "diff": "^7.0.0",
     "dotenv": "^16.4.7",
-    "grammy": "^1.30.0",
-    "tsx": "^4.19.2"
+    "grammy": "^1.46.0",
+    "tsx": "^4.23.13"
   },
   "optionalDependencies": {
     "@homebridge/node-pty-prebuilt-multiarch": "0.13.1"
   },
   "devDependencies": {
     "@types/diff": "^7.0.0",
-    "@types/node": "^22.10.0",
+    "@types/node": "^22.20.1",
     "typescript": "^5.7.2"
   }
 }

package/scripts/setup.mjs

@@ -3,7 +3,8 @@
  * Easy setup: creates/updates the bot's .env, auto-detects the `grok` binary
  * and sensible PROJECT_ROOTS, and optionally writes the bot token / user id:
  *
- *   node scripts/setup.mjs [--path] [--instance <dir>] [<TELEGRAM_BOT_TOKEN> [ALLOWED_USER_ID]]
+ *   node scripts/setup.mjs [--path] [--instance <dir>] [--name <slug>]
+ *                          [<TELEGRAM_BOT_TOKEN> [ALLOWED_USER_ID]]
  *
  * By default the .env lives in the canonical, path-independent home
  * `~/.grok/tg/.env`, so the bot loads the SAME config no matter where it's
@@ -29,8 +30,23 @@ function expandHome(p) {
 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.GROK_TG_DIR || process.env.GROK_TG_CWD || "").trim();
+  const nameEq = process.argv.find((a) => a.startsWith("--name="));
+  const nameFlag = process.argv.indexOf("--name");
+  const name = nameEq
+    ? nameEq.slice("--name=".length)
+    : nameFlag !== -1
+      ? process.argv[nameFlag + 1]
+      : process.env.GROK_TG_NAME;
+  if (name && String(name).trim()) {
+    return join(CANONICAL_DIR, "instances", String(name).trim().toLowerCase());
+  }
+  const envDir = (process.env.GROK_TG_DIR || "").trim();
   if (envDir) return resolve(expandHome(envDir));
+  const cwdHint = (process.env.GROK_TG_CWD || "").trim();
+  if (cwdHint) {
+    const hint = resolve(expandHome(cwdHint));
+    if (existsSync(join(hint, ".env"))) return hint;
+  }
   if (existsSync(join(process.cwd(), ".env"))) return process.cwd();
   return CANONICAL_DIR;
 }
@@ -41,7 +57,8 @@ const positionals = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a === "--path") pathOnly = true;
-  else if (a === "--instance") i++;
+  else if (a === "--instance" || a === "--name") i++;
+  else if (a.startsWith("--instance=") || a.startsWith("--name=")) continue;
   else positionals.push(a);
 }
 const [tokenArg, userArg] = positionals;

package/src/app/instance.ts

@@ -0,0 +1,223 @@
+/**
+ * Named bot instances: each Telegram bot token gets its own directory
+ * (`.env`, `logs/`, `data/`) and a unique OS service name so several bots
+ * can run 24/7 on one host without overwriting each other.
+ *
+ * The unnamed default stays at `~/.grok/tg` with the original service id.
+ * `grok-tg --name work …` uses `~/.grok/tg/instances/work` and
+ * `grok-telegram-bot-work`.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+
+/** Canonical home for the default (unnamed) instance. */
+export const CANONICAL_DIR = join(homedir(), ".grok", "tg");
+export const INSTANCES_SUBDIR = "instances";
+
+export const DEFAULT_SERVICE_ID = "grok-telegram-bot";
+export const DEFAULT_WINDOWS_TASK = "GrokTelegramBot";
+export const DEFAULT_MACOS_LABEL = "com.grok.telegrambot";
+
+const RESERVED = new Set(["default", "instances", "locks", "logs", "data"]);
+const SLUG_RE = /^[a-z][a-z0-9-]{0,31}$/;
+
+export interface InstanceFlags {
+  instanceDir?: string;
+  name?: string;
+}
+
+export interface ServiceIdentity {
+  id: string;
+  displayName: string;
+  windowsTaskName: string;
+  macosLabel: string;
+  slug?: string;
+}
+
+export interface KnownInstance {
+  /** `(default)` or the instance slug. */
+  name: string;
+  dir: string;
+  slug?: string;
+  identity: ServiceIdentity;
+}
+
+export function expandHome(p: string): string {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) return join(homedir(), p.slice(2));
+  return p;
+}
+
+export function parseInstanceFlags(argv: string[]): InstanceFlags {
+  const out: InstanceFlags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a) continue;
+    if ((a === "--instance" || a === "--name") && argv[i + 1]) {
+      const value = argv[++i]!;
+      if (a === "--instance") out.instanceDir = value;
+      else out.name = value;
+      continue;
+    }
+    if (a.startsWith("--instance=")) out.instanceDir = a.slice("--instance=".length);
+    else if (a.startsWith("--name=")) out.name = a.slice("--name=".length);
+  }
+  return out;
+}
+
+/** Drop `--instance` / `--name` (and their values) so the CLI command remains first. */
+export function stripInstanceFlags(argv: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a) continue;
+    if (a === "--instance" || a === "--name") {
+      i++;
+      continue;
+    }
+    if (a.startsWith("--instance=") || a.startsWith("--name=")) continue;
+    out.push(a);
+  }
+  return out;
+}
+
+export function parseInstanceSlug(raw: string): string {
+  const slug = raw.trim().toLowerCase();
+  if (!SLUG_RE.test(slug)) {
+    throw new Error(
+      `Invalid instance name "${raw}". Use 1–32 characters: start with a letter, then letters, digits or hyphens (e.g. work, home, coding).`,
+    );
+  }
+  if (RESERVED.has(slug)) {
+    throw new Error(`Instance name "${slug}" is reserved. Pick another name.`);
+  }
+  return slug;
+}
+
+export function namedInstanceDir(name: string, canonicalDir = CANONICAL_DIR): string {
+  return join(canonicalDir, INSTANCES_SUBDIR, parseInstanceSlug(name));
+}
+
+/**
+ * Resolve this process's instance directory.
+ *
+ * Order: `--instance` → `--name` / `GROK_TG_NAME` → `GROK_TG_DIR` → a
+ * `GROK_TG_CWD` or cwd that already contains `.env` → `~/.grok/tg`.
+ *
+ * `GROK_TG_CWD` is only a "user launched from here" hint (the `grok-tg`
+ * launcher always sets it). It must not override `--name`, otherwise a
+ * named instance could never be selected.
+ */
+export function resolveInstanceDir(opts: {
+  argv?: string[];
+  envDir?: string;
+  nameEnv?: string;
+  cwdHint?: string;
+  cwd?: string;
+  canonicalDir?: string;
+} = {}): string {
+  const canonicalDir = opts.canonicalDir ?? CANONICAL_DIR;
+  const cwd = opts.cwd ?? process.cwd();
+  const flags = parseInstanceFlags(opts.argv ?? process.argv);
+  if (flags.instanceDir?.trim()) return resolve(expandHome(flags.instanceDir.trim()));
+  const name = flags.name?.trim() || opts.nameEnv?.trim();
+  if (name) return namedInstanceDir(name, canonicalDir);
+  if (opts.envDir?.trim()) return resolve(expandHome(opts.envDir.trim()));
+  const hinted = opts.cwdHint?.trim();
+  if (hinted) {
+    const hint = resolve(expandHome(hinted));
+    if (existsSync(join(hint, ".env"))) return hint;
+  }
+  if (existsSync(join(cwd, ".env"))) return cwd;
+  return canonicalDir;
+}
+
+/**
+ * OS service names for this instance.
+ *
+ * Unique names are used only for `--name` / `~/.grok/tg/instances/<slug>` so
+ * an existing default install (`grok-telegram-bot.service`) is unchanged.
+ * A random folder with a `.env` keeps the default service id.
+ */
+export function serviceIdentity(
+  instanceDir: string,
+  name?: string,
+  canonicalDir = CANONICAL_DIR,
+): ServiceIdentity {
+  const slug = name?.trim()
+    ? parseInstanceSlug(name)
+    : inferNamedInstanceSlug(instanceDir, canonicalDir);
+  if (!slug) {
+    return {
+      id: DEFAULT_SERVICE_ID,
+      displayName: "Grok Telegram Bot",
+      windowsTaskName: DEFAULT_WINDOWS_TASK,
+      macosLabel: DEFAULT_MACOS_LABEL,
+    };
+  }
+  return {
+    id: `${DEFAULT_SERVICE_ID}-${slug}`,
+    displayName: `Grok Telegram Bot (${slug})`,
+    windowsTaskName: `${DEFAULT_WINDOWS_TASK}-${slug}`,
+    macosLabel: `${DEFAULT_MACOS_LABEL}.${slug}`,
+    slug,
+  };
+}
+
+export function listKnownInstances(canonicalDir = CANONICAL_DIR): KnownInstance[] {
+  const out: KnownInstance[] = [];
+  if (existsSync(join(canonicalDir, ".env"))) {
+    out.push({
+      name: "(default)",
+      dir: canonicalDir,
+      identity: serviceIdentity(canonicalDir, undefined, canonicalDir),
+    });
+  }
+  const root = join(canonicalDir, INSTANCES_SUBDIR);
+  if (!existsSync(root)) return out;
+  let names: string[] = [];
+  try {
+    names = readdirSync(root, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+      .sort();
+  } catch {
+    return out;
+  }
+  for (const name of names) {
+    const dir = join(root, name);
+    if (!existsSync(join(dir, ".env"))) continue;
+    out.push({
+      name,
+      dir,
+      slug: name,
+      identity: serviceIdentity(dir, undefined, canonicalDir),
+    });
+  }
+  return out;
+}
+
+/** Basename when `instanceDir` is a direct child of `<canonical>/instances`. */
+function namedChildName(instanceDir: string, canonicalDir: string): string | undefined {
+  const resolved = resolve(instanceDir);
+  const parent = resolve(join(resolved, ".."));
+  const root = resolve(join(canonicalDir, INSTANCES_SUBDIR));
+  if (parent !== root) return undefined;
+  return basename(resolved);
+}
+
+function inferNamedInstanceSlug(instanceDir: string, canonicalDir: string): string | undefined {
+  const child = namedChildName(instanceDir, canonicalDir);
+  if (!child) return undefined;
+  try {
+    return parseInstanceSlug(child);
+  } catch {
+    const fallback = child
+      .toLowerCase()
+      .replace(/[^a-z0-9-]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 32);
+    return fallback && SLUG_RE.test(fallback) && !RESERVED.has(fallback) ? fallback : "extra";
+  }
+}

package/src/app/types.ts

@@ -78,13 +78,43 @@ export interface PromptInput {
    * trigger another self-recheck — only real user prompts do (once each).
    */
   skipSelfRecheck?: boolean;
+  /**
+   * Manager dispatch metadata for this prompt only (General → project).
+   * Carried through the queue so concurrent send_prompt jobs do not steal
+   * each other's report-back. Shape matches bot/manager-jobs ReportBackMeta.
+   */
+  reportBack?: {
+    jobId: string;
+    originChatId: number;
+    originThreadId: number;
+    userAskPreview: string;
+    targetName: string;
+    targetPath: string;
+    dispatchPrompt: string;
+  };
+  /**
+   * Pre-posted status bubble (General: "Starting…") that the turn edits to
+   * "Thinking…" then streams the agent reply into.
+   */
+  seedMessageId?: number;
+  /**
+   * Grok Build slash command (`/goal`, `/compact`, …). Must stay the first
+   * line of the prompt — skip manager/complexity wrappers.
+   */
+  rawSlashCommand?: boolean;
 }
 
 export function textPrompt(
   text: string,
   replyTo?: number,
   quotedText?: string,
-  opts?: { skipSelfRecheck?: boolean; promptId?: string },
+  opts?: {
+    skipSelfRecheck?: boolean;
+    promptId?: string;
+    reportBack?: PromptInput["reportBack"];
+    seedMessageId?: number;
+    rawSlashCommand?: boolean;
+  },
 ): PromptInput {
   return {
     text,
@@ -94,5 +124,8 @@ export function textPrompt(
     promptId: opts?.promptId,
     quotedText,
     skipSelfRecheck: opts?.skipSelfRecheck,
+    reportBack: opts?.reportBack,
+    seedMessageId: opts?.seedMessageId,
+    rawSlashCommand: opts?.rawSlashCommand,
   };
 }