switchroom 0.14.44 → 0.14.46

package/dist/cli/switchroom.js

@@ -30596,7 +30596,7 @@ function runInlinedSecretChecks(_config, deps = {}) {
   }
   let parsed;
   try {
-    parsed = import_yaml13.parse(raw);
+    parsed = import_yaml14.parse(raw);
   } catch {
     return [
       {
@@ -30624,9 +30624,9 @@ function runInlinedSecretChecks(_config, deps = {}) {
     fix: `Move it to the per-agent-ACL'd vault: \`switchroom vault set <name>\` ` + `then replace the literal with \`vault:<name>\`. Rotate the exposed ` + `value if any agent may already have read it.`
   }));
 }
-var import_yaml13, SECRET_KEY_EXACT;
+var import_yaml14, SECRET_KEY_EXACT;
 var init_doctor_inlined_secrets = __esm(() => {
-  import_yaml13 = __toESM(require_dist(), 1);
+  import_yaml14 = __toESM(require_dist(), 1);
   SECRET_KEY_EXACT = new Set([
     "bot_token",
     "client_secret",
@@ -49462,8 +49462,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.14.44";
-var COMMIT_SHA = "90836113";
+var VERSION = "0.14.46";
+var COMMIT_SHA = "df3deacf";
 
 // src/cli/agent.ts
 init_source();
@@ -72684,6 +72684,47 @@ ${childIndent}approvalAuth: ${value}`;
   return { kind: "rewritten", content: rewritten };
 }
 
+// src/cli/supergroup-setup-yaml.ts
+var import_yaml13 = __toESM(require_dist(), 1);
+function isValidSupergroupChatId(value) {
+  return /^-\d+$/.test(value);
+}
+function setAgentSupergroupChatId(yamlText, agentName, chatId) {
+  if (!isValidSupergroupChatId(chatId)) {
+    throw new Error(`setAgentSupergroupChatId: chat_id must be a negative integer string (got "${chatId}")`);
+  }
+  const doc = import_yaml13.parseDocument(yamlText);
+  const root = doc.contents;
+  if (!import_yaml13.isMap(root)) {
+    throw new Error("setAgentSupergroupChatId: YAML root is not a map");
+  }
+  const agents = root.get("agents", true);
+  if (!import_yaml13.isMap(agents)) {
+    throw new Error("setAgentSupergroupChatId: config has no `agents:` map");
+  }
+  const agent = agents.get(agentName, true);
+  if (!import_yaml13.isMap(agent)) {
+    throw new Error(`setAgentSupergroupChatId: agent "${agentName}" not found in config`);
+  }
+  const channels = agent.get("channels", true);
+  if (import_yaml13.isMap(channels)) {
+    const telegram = channels.get("telegram", true);
+    if (import_yaml13.isMap(telegram)) {
+      if (telegram.get("chat_id") === chatId)
+        return yamlText;
+      telegram.set("chat_id", chatId);
+    } else {
+      channels.set("telegram", doc.createNode({ chat_id: chatId }));
+    }
+  } else {
+    agent.set("channels", doc.createNode({ telegram: { chat_id: chatId } }));
+  }
+  const out = String(doc);
+  return out.endsWith(`
+`) ? out : out + `
+`;
+}
+
 // src/cli/setup.ts
 var STEP_PENDING = source_default.gray("\u25cb");
 var STEP_ACTIVE = source_default.blue("->");
@@ -72711,6 +72752,7 @@ function registerSetupCommand(program3) {
       if (userId && userId !== "0") {
         saveUserConfig(userId);
       }
+      await stepSupergroupMode(agentBots, switchroomConfigPath, nonInteractive);
       const forumChatId = "0";
       await stepCreateTopics(config, botToken, nonInteractive);
       await stepMemoryBackend(config, nonInteractive, switchroomConfigPath);
@@ -72966,6 +73008,59 @@ async function stepDmPairing(agentBots, nonInteractive, userIdFlag) {
     return { userId: manualId || "0", chatId: 0 };
   }
 }
+var SUPERGROUP_DOC = "docs/supergroup-mode.md";
+async function stepSupergroupMode(agentBots, configPath, nonInteractive) {
+  stepHeader(4, "Supergroup mode (optional)", STEP_ACTIVE);
+  if (nonInteractive) {
+    console.log(source_default.gray(`  ${STEP_DONE} Skipped (DM-only default). To have one agent own a forum`));
+    console.log(source_default.gray(`     supergroup, see ${SUPERGROUP_DOC}.`));
+    return;
+  }
+  console.log(source_default.gray("  Most setups stay DM-only \u2014 each agent DMs you privately. Supergroup"));
+  console.log(source_default.gray("  mode instead has ONE agent own a Telegram forum supergroup and route"));
+  console.log(source_default.gray("  its replies + automated events into per-topic threads. Opt-in."));
+  const want = await askYesNo("  Configure an agent to own a forum supergroup now?", false);
+  if (!want) {
+    console.log(source_default.gray(`  ${STEP_DONE} Staying DM-only. Enable later via ${SUPERGROUP_DOC}.`));
+    return;
+  }
+  const agentNames = Object.keys(agentBots);
+  if (agentNames.length === 0) {
+    console.log(source_default.yellow(`  No agents configured yet \u2014 skipping. See ${SUPERGROUP_DOC}.`));
+    return;
+  }
+  const agent = agentNames.length === 1 ? agentNames[0] : await askChoice("  Which agent owns the supergroup?", agentNames);
+  console.log(source_default.gray("  First create the forum supergroup in Telegram (a group with Topics"));
+  console.log(source_default.gray("  enabled) and add the agent's bot as an admin. Its id is the digits in"));
+  console.log(source_default.gray("  a message link t.me/c/<id>/\u2026 written as a negative -100\u2026 number."));
+  const chatId = await ask("  Supergroup chat_id (e.g. -1001234567890, or Enter to skip)");
+  if (!chatId) {
+    console.log(source_default.gray(`  ${STEP_DONE} Skipped \u2014 no chat_id entered. See ${SUPERGROUP_DOC}.`));
+    return;
+  }
+  if (!isValidSupergroupChatId(chatId)) {
+    console.log(source_default.yellow(`  "${chatId}" isn't a valid supergroup id (need a negative integer like`));
+    console.log(source_default.yellow(`  -1001234567890). Add it by hand later \u2014 ${SUPERGROUP_DOC}.`));
+    return;
+  }
+  try {
+    const fs4 = await import("node:fs");
+    const { atomicWriteFileSync: atomicWriteFileSync3 } = await Promise.resolve().then(() => (init_atomic(), exports_atomic));
+    const raw = fs4.readFileSync(configPath, "utf-8");
+    const after = setAgentSupergroupChatId(raw, agent, chatId);
+    let mode = 420;
+    try {
+      mode = fs4.statSync(configPath).mode & 511;
+    } catch {}
+    atomicWriteFileSync3(configPath, after, mode);
+    console.log(source_default.green(`  ${STEP_DONE} ${agent} now owns supergroup ${chatId} \u2014 replies + ops route to its topics.`));
+    console.log(source_default.gray("     Fallback topic defaults to General (1). Add default_topic_id /"));
+    console.log(source_default.gray(`     topic_aliases by hand \u2014 ${SUPERGROUP_DOC}. Run \`switchroom apply\` to activate.`));
+  } catch (err) {
+    console.log(source_default.yellow(`  Could not write chat_id: ${err.message}`));
+    console.log(source_default.gray(`  Add it by hand \u2014 see ${SUPERGROUP_DOC}.`));
+  }
+}
 async function stepCreateTopics(config, botToken, nonInteractive) {
   stepHeader(5, "Create topics", STEP_ACTIVE);
   if (config.telegram.forum_chat_id === "0") {
@@ -73143,16 +73238,16 @@ async function stepScaffoldAgents(config, agentBots, userId, nonInteractive, swi
 }
 async function ensureAuthActiveDefault(configPath) {
   const fs4 = await import("node:fs");
-  const { parseDocument: parseDocument6, isMap: isMap6 } = await Promise.resolve().then(() => __toESM(require_dist(), 1));
+  const { parseDocument: parseDocument7, isMap: isMap7 } = await Promise.resolve().then(() => __toESM(require_dist(), 1));
   const { atomicWriteFileSync: atomicWriteFileSync3 } = await Promise.resolve().then(() => (init_atomic(), exports_atomic));
   const { setAuthActive: setAuthActive2 } = await Promise.resolve().then(() => (init_auth_active_yaml(), exports_auth_active_yaml));
   const raw = fs4.readFileSync(configPath, "utf-8");
-  const doc = parseDocument6(raw);
+  const doc = parseDocument7(raw);
   const root = doc.contents;
-  if (!isMap6(root))
+  if (!isMap7(root))
     return;
   const existing = root.get("auth", true);
-  if (isMap6(existing) && existing.has("active"))
+  if (isMap7(existing) && existing.has("active"))
     return;
   const after = setAuthActive2(raw, "default");
   if (after === raw)
@@ -78222,6 +78317,32 @@ agents:
   #   admin: true
   #   system_prompt_append: |
   #     You are the fleet admin agent. Always respond concisely.
+
+  # \u2500\u2500 Supergroup mode (advanced, opt-in) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  # By default every agent DMs you privately. Supergroup mode instead
+  # has ONE agent OWN a Telegram forum supergroup: its replies and its
+  # automated events (boot, alerts, cron, approvals) route into per-
+  # topic threads inside that one group, so a busy agent's work stays
+  # organised by subject instead of flooding a single DM.
+  #
+  # \`switchroom setup\` offers this as an optional step, or add it by
+  # hand below. Setting \`chat_id\` is the minimum \u2014 \`default_topic_id\`
+  # auto-defaults to General (topic 1). Create the forum supergroup in
+  # Telegram first, add the bot as an admin, and find the numeric id
+  # (the digits after t.me/c/ in a message link, written as -100\u2026).
+  # Full guide: docs/supergroup-mode.md.
+  #
+  # social:
+  #   topic_name: "Social"
+  #   bot_token: "vault:telegram-social-bot-token"   # its own bot
+  #   channels:
+  #     telegram:
+  #       chat_id: "-1001234567890"   # the forum supergroup this agent owns
+  #       default_topic_id: 1         # fallback topic (1 = General); optional
+  #       topic_aliases:              # name \u2192 topic id, for cron + ops routing
+  #         alerts: 12                # boot / watchdog / compaction events
+  #         admin: 7                  # vault / permission / mutation events
+  #         planning: 3
 `;
 
 // examples/minimal.yaml
@@ -79839,7 +79960,7 @@ function registerAgentConfigCommands(program3) {
 }
 
 // src/cli/agent-config-write.ts
-var import_yaml15 = __toESM(require_dist(), 1);
+var import_yaml16 = __toESM(require_dist(), 1);
 
 // src/config/overlay-writer.ts
 init_paths();
@@ -80032,7 +80153,7 @@ function filterOverlaySecrets(doc, source) {
 // src/agents/reconcile-dry-run.ts
 init_overlay_schema();
 init_schema();
-var import_yaml14 = __toESM(require_dist(), 1);
+var import_yaml15 = __toESM(require_dist(), 1);
 init_lifecycle();
 var MIN_CRON_INTERVAL_SECS = 5 * 60;
 function violatesMinInterval(cron) {
@@ -80054,7 +80175,7 @@ function violatesMinInterval(cron) {
 function dryRunReconcile(input) {
   let parsed;
   try {
-    parsed = import_yaml14.parse(input.yamlText);
+    parsed = import_yaml15.parse(input.yamlText);
   } catch (err) {
     return {
       ok: false,
@@ -80360,7 +80481,7 @@ function scheduleAdd(opts) {
     ]
   };
   const yamlText = (() => {
-    const body = import_yaml15.stringify(doc);
+    const body = import_yaml16.stringify(doc);
     const header = opts.name ? `# name: ${opts.name}
 ` : "";
     return header + body;
@@ -80470,7 +80591,7 @@ function scheduleAddOrStage(opts) {
     ]
   };
   const yamlText = (opts.name ? `# name: ${opts.name}
-` : "") + import_yaml15.stringify(doc);
+` : "") + import_yaml16.stringify(doc);
   const summary = (() => {
     const parts = [`cron=${opts.cronExpr}`];
     if (opts.secrets?.length)
@@ -80520,7 +80641,7 @@ function scheduleRemove(opts) {
         break;
       }
       try {
-        const parsed = import_yaml15.parse(e.raw);
+        const parsed = import_yaml16.parse(e.raw);
         if (parsed && parsed.name === opts.name) {
           match = e;
           break;
@@ -80730,10 +80851,10 @@ function registerAgentConfigWriteCommands(program3) {
 }
 
 // src/cli/agent-config-skill-write.ts
-var import_yaml16 = __toESM(require_dist(), 1);
+var import_yaml17 = __toESM(require_dist(), 1);
 import { existsSync as existsSync78 } from "node:fs";
 init_reconcile_default_skills();
-var import_yaml17 = __toESM(require_dist(), 1);
+var import_yaml18 = __toESM(require_dist(), 1);
 import { join as join75 } from "node:path";
 var MAX_SKILLS_PER_AGENT = 20;
 var V1_ALLOWED_SOURCE_PREFIX = "bundled:";
@@ -80783,7 +80904,7 @@ function countCurrentSkills(agent, opts) {
   let total = 0;
   for (const e of entries) {
     try {
-      const doc = import_yaml17.parse(e.raw);
+      const doc = import_yaml18.parse(e.raw);
       total += (doc?.skills ?? []).length;
     } catch {}
   }
@@ -80813,7 +80934,7 @@ function skillInstall(opts) {
   if (!existsSync78(skillPath)) {
     return err("E_SKILL_NOT_FOUND", `bundled skill not found at ${skillPath}. The operator needs to ` + `place the skill at this path before the agent can opt in.`);
   }
-  const yamlText = import_yaml16.stringify({ skills: [skillName] });
+  const yamlText = import_yaml17.stringify({ skills: [skillName] });
   let path8;
   try {
     path8 = writeSkillsOverlayEntry(agent, slug, yamlText, { root: opts.root });
@@ -80992,7 +81113,7 @@ import { dirname as dirname22, join as join76, relative as relative2, resolve as
 import { spawnSync as spawnSync10 } from "node:child_process";
 
 // src/cli/skill-common.ts
-var import_yaml18 = __toESM(require_dist(), 1);
+var import_yaml19 = __toESM(require_dist(), 1);
 var MAX_FILE_BYTES = 256 * 1024;
 var MAX_SKILL_BYTES = 2 * 1024 * 1024;
 var MAX_FILES_PER_SKILL = 50;
@@ -81096,7 +81217,7 @@ function validateSkillMd(content, expectedName) {
   }
   let parsed;
   try {
-    parsed = import_yaml18.parse(fmText);
+    parsed = import_yaml19.parse(fmText);
   } catch (e) {
     return authorErr("E_SKILL_INVALID_FRONTMATTER", `frontmatter is not valid YAML: ${e.message}`);
   }
@@ -82135,7 +82256,7 @@ function registerSkillPersonalCommands(program3) {
 
 // src/cli/skill-search.ts
 init_helpers();
-var import_yaml19 = __toESM(require_dist(), 1);
+var import_yaml20 = __toESM(require_dist(), 1);
 import { existsSync as existsSync81, readdirSync as readdirSync32, readFileSync as readFileSync65, statSync as statSync31 } from "node:fs";
 import { homedir as homedir45 } from "node:os";
 import { join as join78, resolve as resolve48 } from "node:path";
@@ -82175,7 +82296,7 @@ function readSkillFrontmatter(skillDir) {
   const fmText = rest.slice(0, endIdx);
   let parsed;
   try {
-    parsed = import_yaml19.parse(fmText);
+    parsed = import_yaml20.parse(fmText);
   } catch (e) {
     return { error: `yaml parse: ${e.message}` };
   }

package/examples/switchroom.yaml

@@ -285,3 +285,29 @@ agents:
   #   admin: true
   #   system_prompt_append: |
   #     You are the fleet admin agent. Always respond concisely.
+
+  # ── Supergroup mode (advanced, opt-in) ───────────────────────────
+  # By default every agent DMs you privately. Supergroup mode instead
+  # has ONE agent OWN a Telegram forum supergroup: its replies and its
+  # automated events (boot, alerts, cron, approvals) route into per-
+  # topic threads inside that one group, so a busy agent's work stays
+  # organised by subject instead of flooding a single DM.
+  #
+  # `switchroom setup` offers this as an optional step, or add it by
+  # hand below. Setting `chat_id` is the minimum — `default_topic_id`
+  # auto-defaults to General (topic 1). Create the forum supergroup in
+  # Telegram first, add the bot as an admin, and find the numeric id
+  # (the digits after t.me/c/ in a message link, written as -100…).
+  # Full guide: docs/supergroup-mode.md.
+  #
+  # social:
+  #   topic_name: "Social"
+  #   bot_token: "vault:telegram-social-bot-token"   # its own bot
+  #   channels:
+  #     telegram:
+  #       chat_id: "-1001234567890"   # the forum supergroup this agent owns
+  #       default_topic_id: 1         # fallback topic (1 = General); optional
+  #       topic_aliases:              # name → topic id, for cron + ops routing
+  #         alerts: 12                # boot / watchdog / compaction events
+  #         admin: 7                  # vault / permission / mutation events
+  #         planning: 3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.14.44",
+  "version": "0.14.46",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -47833,6 +47833,7 @@ function buildVaultGrantApprovedInbound(opts) {
   return {
     type: "inbound",
     chatId: opts.ctx.chat_id,
+    ...opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {},
     messageId: ts,
     user: "vault-broker",
     userId: 0,
@@ -47841,6 +47842,7 @@ function buildVaultGrantApprovedInbound(opts) {
     meta: {
       source: "vault_grant_approved",
       agent: opts.ctx.agent,
+      ...opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {},
       key: opts.ctx.key,
       scope: opts.ctx.scope,
       grant_id: opts.grantId,
@@ -47854,6 +47856,7 @@ function buildVaultGrantDeniedInbound(opts) {
   return {
     type: "inbound",
     chatId: opts.ctx.chat_id,
+    ...opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {},
     messageId: ts,
     user: "vault-broker",
     userId: 0,
@@ -47862,6 +47865,7 @@ function buildVaultGrantDeniedInbound(opts) {
     meta: {
       source: "vault_grant_denied",
       agent: opts.ctx.agent,
+      ...opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {},
       key: opts.ctx.key,
       scope: opts.ctx.scope,
       stage_id: opts.stageId,
@@ -47874,6 +47878,7 @@ function buildVaultSaveCompletedInbound(opts) {
   return {
     type: "inbound",
     chatId: opts.ctx.chat_id,
+    ...opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {},
     messageId: ts,
     user: "vault-broker",
     userId: 0,
@@ -47882,6 +47887,7 @@ function buildVaultSaveCompletedInbound(opts) {
     meta: {
       source: "vault_save_completed",
       agent: opts.ctx.agent,
+      ...opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {},
       key: opts.ctx.key,
       stage_id: opts.stageId,
       operator_id: opts.operatorId
@@ -47893,6 +47899,7 @@ function buildVaultSaveFailedInbound(opts) {
   return {
     type: "inbound",
     chatId: opts.ctx.chat_id,
+    ...opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {},
     messageId: ts,
     user: "vault-broker",
     userId: 0,
@@ -47901,6 +47908,7 @@ function buildVaultSaveFailedInbound(opts) {
     meta: {
       source: "vault_save_failed",
       agent: opts.ctx.agent,
+      ...opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {},
       key: opts.ctx.key,
       stage_id: opts.stageId,
       operator_id: opts.operatorId
@@ -47912,6 +47920,7 @@ function buildVaultSaveDiscardedInbound(opts) {
   return {
     type: "inbound",
     chatId: opts.ctx.chat_id,
+    ...opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {},
     messageId: ts,
     user: "vault-broker",
     userId: 0,
@@ -47920,6 +47929,7 @@ function buildVaultSaveDiscardedInbound(opts) {
     meta: {
       source: "vault_save_discarded",
       agent: opts.ctx.agent,
+      ...opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {},
       key: opts.ctx.key,
       stage_id: opts.stageId,
       operator_id: opts.operatorId
@@ -52024,10 +52034,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.14.44";
-var COMMIT_SHA = "90836113";
-var COMMIT_DATE = "2026-06-03T02:30:59Z";
-var LATEST_PR = 2110;
+var VERSION = "0.14.46";
+var COMMIT_SHA = "df3deacf";
+var COMMIT_DATE = "2026-06-03T05:00:14Z";
+var LATEST_PR = 2116;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -54091,13 +54101,15 @@ function emitGatewayOperatorEvent(event) {
     return;
   }
   const opEventTopic = resolveAgentOutboundTopic({ kind: "compact-watchdog" });
+  const opEventSupergroup = resolveAgentSupergroupChatId();
   process.stderr.write(`telegram gateway: operator-event posting agent=${agent} kind=${kind} to ${access.allowFrom.length} chat(s)` + (opEventTopic != null ? ` topic=${opEventTopic}` : "") + `
 `);
   for (const chat_id of access.allowFrom) {
+    const opEventThread = topicForRecipient({ recipientChatId: chat_id, resolvedTopic: opEventTopic, supergroupChatId: opEventSupergroup });
     const opts = {
       parse_mode: "HTML",
       ...renderedKeyboard ? { reply_markup: renderedKeyboard } : {},
-      ...opEventTopic != null ? { message_thread_id: opEventTopic } : {}
+      ...opEventThread != null ? { message_thread_id: opEventThread } : {}
     };
     bot.api.sendMessage(chat_id, renderedText, opts).catch((e) => {
       process.stderr.write(`telegram gateway: operator-event send to ${chat_id} failed agent=${agent} kind=${kind}: ${e}
@@ -56081,6 +56093,8 @@ async function executeVaultRequestSave(args) {
   sweepPendingVaultRequestSaves();
   const text = renderVaultRequestSaveCard(pending2, agentSlug);
   const threadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined;
+  if (threadId != null)
+    pending2.threadId = threadId;
   const sent = await retryWithThreadFallback(robustApiCall, (tid) => lockedBot.api.sendMessage(chat_id, text, {
     parse_mode: "HTML",
     reply_markup: buildVaultRequestSaveKeyboard(stageId),
@@ -56155,6 +56169,8 @@ async function executeRequestSecret(args) {
   sweepSecretRequests();
   const text = renderSecretRequestCard(pending2);
   const threadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined;
+  if (threadId != null)
+    pending2.threadId = threadId;
   const sent = await retryWithThreadFallback(robustApiCall, (tid) => lockedBot.api.sendMessage(chat_id, text, {
     parse_mode: "HTML",
     reply_markup: buildSecretRequestKeyboard(stageId),
@@ -56205,12 +56221,19 @@ async function captureProvidedSecret(ctx, chat_id, msgId, value) {
     const failMsg = {
       type: "inbound",
       chatId: chat_id,
+      ...armed.threadId != null ? { threadId: armed.threadId } : {},
       messageId: fts,
       user: "vault-broker",
       userId: 0,
       ts: fts,
       text: `\u26A0\uFE0F The secret you requested for \`vault:${armed.key}\` could NOT be saved (vault write failed). Do not assume it is available; tell the operator or try request_secret again.`,
-      meta: { source: "secret_provide_failed", agent: armed.agent, key: armed.key, stage_id: armed.stageId }
+      meta: {
+        source: "secret_provide_failed",
+        agent: armed.agent,
+        ...armed.threadId != null ? { message_thread_id: String(armed.threadId) } : {},
+        key: armed.key,
+        stage_id: armed.stageId
+      }
     };
     const fdelivered = ipcServer.sendToAgent(armed.agent, failMsg);
     if (fdelivered)
@@ -56224,6 +56247,7 @@ async function captureProvidedSecret(ctx, chat_id, msgId, value) {
   const synthetic = {
     type: "inbound",
     chatId: chat_id,
+    ...armed.threadId != null ? { threadId: armed.threadId } : {},
     messageId: ts,
     user: "vault-broker",
     userId: 0,
@@ -56232,6 +56256,7 @@ async function captureProvidedSecret(ctx, chat_id, msgId, value) {
     meta: {
       source: "secret_provided",
       agent: armed.agent,
+      ...armed.threadId != null ? { message_thread_id: String(armed.threadId) } : {},
       key: armed.key,
       stage_id: armed.stageId
     }
@@ -56265,7 +56290,8 @@ async function handleSecretRequestCallback(ctx, data) {
       key: pending2.key,
       agent: pending2.agent,
       stageId,
-      armed_at: Date.now()
+      armed_at: Date.now(),
+      ...pending2.threadId != null ? { threadId: pending2.threadId } : {}
     });
     await ctx.answerCallbackQuery({ text: "Send the value now \u2014 it auto-deletes." }).catch(() => {});
     if (pending2.card_message_id != null) {
@@ -56287,12 +56313,19 @@ async function handleSecretRequestCallback(ctx, data) {
     const synthetic = {
       type: "inbound",
       chatId: pending2.chat_id,
+      ...pending2.threadId != null ? { threadId: pending2.threadId } : {},
       messageId: ts,
       user: "vault-broker",
       userId: 0,
       ts,
       text: `\uD83D\uDEAB Operator declined your request for \`vault:${pending2.key}\`. Proceed without it or ask how they'd like to handle the task.`,
-      meta: { source: "secret_declined", agent: pending2.agent, key: pending2.key, stage_id: stageId }
+      meta: {
+        source: "secret_declined",
+        agent: pending2.agent,
+        ...pending2.threadId != null ? { message_thread_id: String(pending2.threadId) } : {},
+        key: pending2.key,
+        stage_id: stageId
+      }
     };
     const delivered = ipcServer.sendToAgent(pending2.agent, synthetic);
     if (delivered)
@@ -56393,6 +56426,8 @@ async function executeVaultRequestAccess(args) {
   sweepPendingVaultRequestAccesses();
   const text = renderVaultRequestAccessCard(pending2);
   const threadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined;
+  if (threadId != null)
+    pending2.threadId = threadId;
   const sent = await retryWithThreadFallback(robustApiCall, (tid) => lockedBot.api.sendMessage(chat_id, text, {
     parse_mode: "HTML",
     reply_markup: buildVaultRequestAccessKeyboard(stageId),
@@ -57874,7 +57909,7 @@ ${preBlock(write.output)}`;
       }
     }
   }
-  bot.api.sendChatAction(chat_id, "typing").catch(() => {});
+  bot.api.sendChatAction(chat_id, "typing", messageThreadId != null ? { message_thread_id: messageThreadId } : {}).catch(() => {});
   const parsedSteer = parseSteerPrefix(text);
   const isSteerPrefix = parsedSteer.steering;
   const parsedQueue = isSteerPrefix ? { queued: false, body: parsedSteer.body } : parseQueuePrefix(text);
@@ -58381,9 +58416,10 @@ function resolveBootChatId(marker, ageMs) {
     };
   }
   const supergroupBootTopic = resolveAgentOutboundTopic({ kind: "boot" });
+  const bootSupergroup = resolveAgentSupergroupChatId();
   const envChat = process.env.SUBAGENT_OWNER_CHAT_ID;
   if (envChat)
-    return { chatId: envChat, threadId: supergroupBootTopic, ackMsgId: undefined };
+    return { chatId: envChat, threadId: topicForRecipient({ recipientChatId: envChat, resolvedTopic: supergroupBootTopic, supergroupChatId: bootSupergroup }), ackMsgId: undefined };
   if (HISTORY_ENABLED) {
     try {
       const access = loadAccess();
@@ -58391,7 +58427,7 @@ function resolveBootChatId(marker, ageMs) {
       if (ownerChatId) {
         const recent = query({ chat_id: ownerChatId, limit: 1 });
         if (recent.length > 0)
-          return { chatId: ownerChatId, threadId: supergroupBootTopic, ackMsgId: undefined };
+          return { chatId: ownerChatId, threadId: topicForRecipient({ recipientChatId: ownerChatId, resolvedTopic: supergroupBootTopic, supergroupChatId: bootSupergroup }), ackMsgId: undefined };
       }
     } catch {}
   }
@@ -60025,7 +60061,8 @@ async function performVaultAccessApproval(ctx, pending2, stageId, senderId, atte
       key: pending2.key,
       scope: pending2.scope,
       chat_id: pending2.chat_id,
-      ttl_seconds: pending2.ttl_seconds
+      ttl_seconds: pending2.ttl_seconds,
+      ...pending2.threadId != null ? { threadId: pending2.threadId } : {}
     },
     grantId: id,
     stageId,
@@ -60074,7 +60111,8 @@ async function handleVaultRequestAccessCallback(ctx, data) {
         key: pending2.key,
         scope: pending2.scope,
         chat_id: pending2.chat_id,
-        ttl_seconds: pending2.ttl_seconds
+        ttl_seconds: pending2.ttl_seconds,
+        ...pending2.threadId != null ? { threadId: pending2.threadId } : {}
       },
       stageId,
       operatorId: senderId
@@ -60169,7 +60207,12 @@ async function handleVaultRequestSaveCallback(ctx, data) {
       await ctx.api.editMessageText(pending2.chat_id, pending2.card_message_id, `\uD83D\uDEAB <i>Discarded. The secret was not written to the vault.</i>`, { parse_mode: "HTML", reply_markup: { inline_keyboard: [] } }).catch(() => {});
     }
     const discardInbound = buildVaultSaveDiscardedInbound({
-      ctx: { agent: pending2.agent, key: pending2.key, chat_id: pending2.chat_id },
+      ctx: {
+        agent: pending2.agent,
+        key: pending2.key,
+        chat_id: pending2.chat_id,
+        ...pending2.threadId != null ? { threadId: pending2.threadId } : {}
+      },
       stageId,
       operatorId: senderId
     });
@@ -60230,7 +60273,12 @@ async function handleVaultRequestSaveCallback(ctx, data) {
       const failReason = (write.output || "vault write error").split(`
 `)[0].slice(0, 200);
       const failInbound = buildVaultSaveFailedInbound({
-        ctx: { agent: pending2.agent, key: pending2.key, chat_id: pending2.chat_id },
+        ctx: {
+          agent: pending2.agent,
+          key: pending2.key,
+          chat_id: pending2.chat_id,
+          ...pending2.threadId != null ? { threadId: pending2.threadId } : {}
+        },
         stageId,
         operatorId: senderId,
         reason: failReason
@@ -60250,7 +60298,12 @@ async function handleVaultRequestSaveCallback(ctx, data) {
 <i>The agent can now reference this as <code>vault:${escapeHtmlForTg(pending2.key)}</code>.</i>`, { parse_mode: "HTML", reply_markup: { inline_keyboard: [] } }).catch(() => {});
     }
     const okInbound = buildVaultSaveCompletedInbound({
-      ctx: { agent: pending2.agent, key: pending2.key, chat_id: pending2.chat_id },
+      ctx: {
+        agent: pending2.agent,
+        key: pending2.key,
+        chat_id: pending2.chat_id,
+        ...pending2.threadId != null ? { threadId: pending2.threadId } : {}
+      },
       stageId,
       operatorId: senderId
     });

package/telegram-plugin/gateway/gateway.ts

@@ -2913,6 +2913,10 @@ interface PendingVaultRequestSave {
   chat_id: string
   /** Card message id (filled in after we send the card). */
   card_message_id?: number
+  /** Supergroup forum topic the agent was working in when it requested the
+   *  save — carried into the save-outcome inbound so the resumed reply lands
+   *  back in that topic, not General. */
+  threadId?: number
   /** Currently-suggested slug; may be renamed by the user. */
   key: string
   /** Storage shape — 'string' (default) or 'binary'. */
@@ -2954,6 +2958,10 @@ interface PendingVaultRequestAccess {
   chat_id: string
   /** Card message id (filled in after we send the card). */
   card_message_id?: number
+  /** Supergroup forum topic the agent was working in when it requested (the
+   *  card's originating thread). Carried into the grant-outcome inbound so the
+   *  resumed reply lands back in that topic, not General. */
+  threadId?: number
   /** Vault key the agent wants to read. */
   key: string
   /** 'read' (default) or 'write'. */
@@ -3537,18 +3545,24 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
   // Fleet-shared / DM agents see `undefined` → no `message_thread_id`
   // is added to the broadcast opts → behavior unchanged.
   const opEventTopic = resolveAgentOutboundTopic({ kind: 'compact-watchdog' })
+  const opEventSupergroup = resolveAgentSupergroupChatId()
 
   process.stderr.write(
     `telegram gateway: operator-event posting agent=${agent} kind=${kind} to ${access.allowFrom.length} chat(s)` +
       (opEventTopic != null ? ` topic=${opEventTopic}` : '') + '\n',
   )
   for (const chat_id of access.allowFrom) {
+    // The resolved topic is valid ONLY in the agent's supergroup — attaching
+    // it to an operator DM recipient yields 400 "message thread not found" and
+    // the event silently fails to deliver (the marko #2096 class). Guard it:
+    // DM recipients get a thread-less send; the supergroup owner gets the lane.
+    const opEventThread = topicForRecipient({ recipientChatId: chat_id, resolvedTopic: opEventTopic, supergroupChatId: opEventSupergroup })
     // grammy's Other<...> opts type is generated and stricter than our
     // call shape; runtime accepts both. Cast through unknown.
     const opts = {
       parse_mode: 'HTML' as const,
       ...(renderedKeyboard ? { reply_markup: renderedKeyboard } : {}),
-      ...(opEventTopic != null ? { message_thread_id: opEventTopic } : {}),
+      ...(opEventThread != null ? { message_thread_id: opEventThread } : {}),
     }
     // Comment-only context for the reader; the lint marker on the
     // very next line is what unlocks the raw bot.api call.
@@ -7074,6 +7088,8 @@ async function executeVaultRequestSave(args: Record<string, unknown>): Promise<{
   // crashing the tool call.
   const text = renderVaultRequestSaveCard(pending, agentSlug)
   const threadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
+  // Remember the agent's working topic so the save-outcome inbound resumes in it.
+  if (threadId != null) pending.threadId = threadId
   const sent = await retryWithThreadFallback<{ message_id: number }>(
     robustApiCall,
     (tid) =>
@@ -7114,12 +7130,16 @@ interface PendingSecretRequest {
   reason?: string
   staged_at: number
   card_message_id?: number
+  /** Supergroup forum topic the agent was working in — carried into the
+   *  provide/decline/fail outcome inbounds so the resumed reply lands back
+   *  in that topic, not General. */
+  threadId?: number
 }
 // stageId -> request (lives until tapped or TTL).
 const pendingSecretRequests = new Map<string, PendingSecretRequest>()
 // chat_id -> the armed capture: the operator's NEXT message in this chat is
 // the value for `key`. Set when [Provide securely] is tapped.
-interface ArmedSecretCapture { key: string; agent: string; stageId: string; armed_at: number }
+interface ArmedSecretCapture { key: string; agent: string; stageId: string; armed_at: number; threadId?: number }
 const armedSecretCaptures = new Map<string, ArmedSecretCapture>()
 const PENDING_SECRET_REQUEST_TTL_MS = 30 * 60_000 // card lifetime
 const ARMED_SECRET_CAPTURE_TTL_MS = 10 * 60_000   // window to send the value after tapping
@@ -7188,6 +7208,8 @@ async function executeRequestSecret(args: Record<string, unknown>): Promise<{ co
 
   const text = renderSecretRequestCard(pending)
   const threadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
+  // Remember the agent's working topic so the provide/decline/fail inbound resumes in it.
+  if (threadId != null) pending.threadId = threadId
   const sent = await retryWithThreadFallback<{ message_id: number }>(
     robustApiCall,
     (tid) =>
@@ -7263,12 +7285,19 @@ async function captureProvidedSecret(
     const failMsg: InboundMessage = {
       type: 'inbound',
       chatId: chat_id,
+      ...(armed.threadId != null ? { threadId: armed.threadId } : {}),
       messageId: fts,
       user: 'vault-broker',
       userId: 0,
       ts: fts,
       text: `⚠️ The secret you requested for \`vault:${armed.key}\` could NOT be saved (vault write failed). Do not assume it is available; tell the operator or try request_secret again.`,
-      meta: { source: 'secret_provide_failed', agent: armed.agent, key: armed.key, stage_id: armed.stageId },
+      meta: {
+        source: 'secret_provide_failed',
+        agent: armed.agent,
+        ...(armed.threadId != null ? { message_thread_id: String(armed.threadId) } : {}),
+        key: armed.key,
+        stage_id: armed.stageId,
+      },
     }
     const fdelivered = ipcServer.sendToAgent(armed.agent, failMsg)
     if (fdelivered) markClaudeBusyForInbound(failMsg)
@@ -7288,6 +7317,7 @@ async function captureProvidedSecret(
   const synthetic: InboundMessage = {
     type: 'inbound',
     chatId: chat_id,
+    ...(armed.threadId != null ? { threadId: armed.threadId } : {}),
     messageId: ts,
     user: 'vault-broker',
     userId: 0,
@@ -7299,6 +7329,7 @@ async function captureProvidedSecret(
     meta: {
       source: 'secret_provided',
       agent: armed.agent,
+      ...(armed.threadId != null ? { message_thread_id: String(armed.threadId) } : {}),
       key: armed.key,
       stage_id: armed.stageId,
     },
@@ -7339,6 +7370,7 @@ async function handleSecretRequestCallback(ctx: Context, data: string): Promise<
       agent: pending.agent,
       stageId,
       armed_at: Date.now(),
+      ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
     })
     await ctx.answerCallbackQuery({ text: 'Send the value now — it auto-deletes.' }).catch(() => {})
     if (pending.card_message_id != null) {
@@ -7371,12 +7403,19 @@ async function handleSecretRequestCallback(ctx: Context, data: string): Promise<
     const synthetic: InboundMessage = {
       type: 'inbound',
       chatId: pending.chat_id,
+      ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
       messageId: ts,
       user: 'vault-broker',
       userId: 0,
       ts,
       text: `🚫 Operator declined your request for \`vault:${pending.key}\`. Proceed without it or ask how they'd like to handle the task.`,
-      meta: { source: 'secret_declined', agent: pending.agent, key: pending.key, stage_id: stageId },
+      meta: {
+        source: 'secret_declined',
+        agent: pending.agent,
+        ...(pending.threadId != null ? { message_thread_id: String(pending.threadId) } : {}),
+        key: pending.key,
+        stage_id: stageId,
+      },
     }
     const delivered = ipcServer.sendToAgent(pending.agent, synthetic)
     if (delivered) markClaudeBusyForInbound(synthetic)
@@ -7524,6 +7563,8 @@ async function executeVaultRequestAccess(args: Record<string, unknown>): Promise
 
   const text = renderVaultRequestAccessCard(pending)
   const threadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
+  // Remember the agent's working topic so the grant-outcome inbound resumes in it.
+  if (threadId != null) pending.threadId = threadId
   // #1075: deleted-topic safe — fall back to main chat.
   const sent = await retryWithThreadFallback<{ message_id: number }>(
     robustApiCall,
@@ -10159,7 +10200,14 @@ async function handleInbound(
     // No staged entry to act on — fall through to normal handling.
   }
 
-  void bot.api.sendChatAction(chat_id, 'typing').catch(() => {})
+  // Typing indicator in the ORIGINATING topic — on a supergroup-topic inbound,
+  // an un-threaded sendChatAction shows "typing" in General, not the topic the
+  // user is in. messageThreadId is the inbound's thread (undefined in a DM).
+  void bot.api.sendChatAction(
+    chat_id,
+    'typing',
+    messageThreadId != null ? { message_thread_id: messageThreadId } : {},
+  ).catch(() => {})
 
   // Parse explicit prefixes first. `/steer ` / `/s ` opts IN to steering;
   // `/queue ` / `/q ` are legacy aliases that opt in to the new default (queued).
@@ -11088,10 +11136,14 @@ function resolveBootChatId(
   // → behavior unchanged (lands at chat-root as today). PR4b of
   // supergroup-mode rollout (docs/rfcs/supergroup-mode.md).
   const supergroupBootTopic = resolveAgentOutboundTopic({ kind: 'boot' })
+  const bootSupergroup = resolveAgentSupergroupChatId()
+  // The boot topic is valid only in the agent's supergroup — attach it per
+  // recipient so a DM owner doesn't 400 (marko #2096 class); the supergroup
+  // owner gets the boot/alerts lane, a DM gets a thread-less boot card.
 
   // 2. Env var
   const envChat = process.env.SUBAGENT_OWNER_CHAT_ID
-  if (envChat) return { chatId: envChat, threadId: supergroupBootTopic, ackMsgId: undefined }
+  if (envChat) return { chatId: envChat, threadId: topicForRecipient({ recipientChatId: envChat, resolvedTopic: supergroupBootTopic, supergroupChatId: bootSupergroup }), ackMsgId: undefined }
   // 3. Most-recent inbound from history
   if (HISTORY_ENABLED) {
     try {
@@ -11099,7 +11151,7 @@ function resolveBootChatId(
       const ownerChatId = access.allowFrom[0]
       if (ownerChatId) {
         const recent = queryHistory({ chat_id: ownerChatId, limit: 1 })
-        if (recent.length > 0) return { chatId: ownerChatId, threadId: supergroupBootTopic, ackMsgId: undefined }
+        if (recent.length > 0) return { chatId: ownerChatId, threadId: topicForRecipient({ recipientChatId: ownerChatId, resolvedTopic: supergroupBootTopic, supergroupChatId: bootSupergroup }), ackMsgId: undefined }
       }
     } catch {}
   }
@@ -14006,6 +14058,7 @@ async function performVaultAccessApproval(
       scope: pending.scope,
       chat_id: pending.chat_id,
       ttl_seconds: pending.ttl_seconds,
+      ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
     },
     grantId: id,
     stageId,
@@ -14087,6 +14140,7 @@ async function handleVaultRequestAccessCallback(ctx: Context, data: string): Pro
         scope: pending.scope,
         chat_id: pending.chat_id,
         ttl_seconds: pending.ttl_seconds,
+        ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
       },
       stageId,
       operatorId: senderId,
@@ -14261,7 +14315,12 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
     // tool returned "waiting for operator", the turn ended, and a
     // Discard left the agent silently idle forever.
     const discardInbound = buildVaultSaveDiscardedInbound({
-      ctx: { agent: pending.agent, key: pending.key, chat_id: pending.chat_id },
+      ctx: {
+        agent: pending.agent,
+        key: pending.key,
+        chat_id: pending.chat_id,
+        ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+      },
       stageId,
       operatorId: senderId,
     })
@@ -14384,7 +14443,12 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
       const failReason =
         (write.output || 'vault write error').split('\n')[0]!.slice(0, 200)
       const failInbound = buildVaultSaveFailedInbound({
-        ctx: { agent: pending.agent, key: pending.key, chat_id: pending.chat_id },
+        ctx: {
+          agent: pending.agent,
+          key: pending.key,
+          chat_id: pending.chat_id,
+          ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+        },
         stageId,
         operatorId: senderId,
         reason: failReason,
@@ -14415,7 +14479,12 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
     // task that was blocked on this credential (symmetric with the
     // vra: approve path; buffered if the bridge is mid-reconnect).
     const okInbound = buildVaultSaveCompletedInbound({
-      ctx: { agent: pending.agent, key: pending.key, chat_id: pending.chat_id },
+      ctx: {
+        agent: pending.agent,
+        key: pending.key,
+        chat_id: pending.chat_id,
+        ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+      },
       stageId,
       operatorId: senderId,
     })

package/telegram-plugin/gateway/vault-grant-inbound-builders.ts

@@ -34,6 +34,10 @@ export interface VaultGrantInboundContext {
   chat_id: string
   /** Seconds. For approved grants; ignored for deny. */
   ttl_seconds: number
+  /** Supergroup forum topic (message_thread_id) the agent was working in
+   *  when it requested the credential — so the resumed turn's reply lands
+   *  back in that topic, not General. Undefined for DM / non-topic requests. */
+  threadId?: number
 }
 
 /**
@@ -62,6 +66,7 @@ export function buildVaultGrantApprovedInbound(opts: {
   return {
     type: 'inbound',
     chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
     messageId: ts, // synthetic — no Telegram message id exists
     user: 'vault-broker',
     userId: 0,
@@ -76,6 +81,7 @@ export function buildVaultGrantApprovedInbound(opts: {
     meta: {
       source: 'vault_grant_approved',
       agent: opts.ctx.agent,
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
       key: opts.ctx.key,
       scope: opts.ctx.scope,
       grant_id: opts.grantId,
@@ -103,6 +109,7 @@ export function buildVaultGrantDeniedInbound(opts: {
   return {
     type: 'inbound',
     chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
     messageId: ts,
     user: 'vault-broker',
     userId: 0,
@@ -116,6 +123,7 @@ export function buildVaultGrantDeniedInbound(opts: {
     meta: {
       source: 'vault_grant_denied',
       agent: opts.ctx.agent,
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
       key: opts.ctx.key,
       scope: opts.ctx.scope,
       stage_id: opts.stageId,
@@ -133,6 +141,9 @@ export interface VaultSaveInboundContext {
   /** Telegram chat the save card lived in — keeps the synthesized
    *  resume-turn associated with the originating conversation. */
   chat_id: string
+  /** Supergroup forum topic the agent was working in when it requested the
+   *  save — so the resumed reply lands in that topic, not General. */
+  threadId?: number
 }
 
 /**
@@ -154,6 +165,7 @@ export function buildVaultSaveCompletedInbound(opts: {
   return {
     type: 'inbound',
     chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
     messageId: ts,
     user: 'vault-broker',
     userId: 0,
@@ -165,6 +177,7 @@ export function buildVaultSaveCompletedInbound(opts: {
     meta: {
       source: 'vault_save_completed',
       agent: opts.ctx.agent,
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
       key: opts.ctx.key,
       stage_id: opts.stageId,
       operator_id: opts.operatorId,
@@ -187,6 +200,7 @@ export function buildVaultSaveFailedInbound(opts: {
   return {
     type: 'inbound',
     chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
     messageId: ts,
     user: 'vault-broker',
     userId: 0,
@@ -200,6 +214,7 @@ export function buildVaultSaveFailedInbound(opts: {
     meta: {
       source: 'vault_save_failed',
       agent: opts.ctx.agent,
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
       key: opts.ctx.key,
       stage_id: opts.stageId,
       operator_id: opts.operatorId,
@@ -221,6 +236,7 @@ export function buildVaultSaveDiscardedInbound(opts: {
   return {
     type: 'inbound',
     chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
     messageId: ts,
     user: 'vault-broker',
     userId: 0,
@@ -234,6 +250,7 @@ export function buildVaultSaveDiscardedInbound(opts: {
     meta: {
       source: 'vault_save_discarded',
       agent: opts.ctx.agent,
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
       key: opts.ctx.key,
       stage_id: opts.stageId,
       operator_id: opts.operatorId,

package/telegram-plugin/hooks/tool-label-pretool.mjs

@@ -133,8 +133,9 @@ export function computeLabel(toolName, input) {
     }
   }
 
-  // MCP allowlist.
+  // MCP tools.
   if (typeof toolName === 'string' && toolName.startsWith('mcp__')) {
+    // Explicit labels / suppressions for the built-in servers.
     switch (toolName) {
       case 'mcp__switchroom-telegram__reply':
       case 'mcp__switchroom-telegram__stream_reply':
@@ -150,15 +151,46 @@ export function computeLabel(toolName, input) {
         return 'Searching memory'
       case 'mcp__hindsight__retain':
         return 'Saving memory'
-      // Explicit suppressions — return null so we don't emit a sidecar
-      // line at all. (Falling through to the default below produces the
-      // same effect, but listing these makes the intent obvious.)
+      // Explicit suppressions — return null so we don't emit a sidecar line.
       case 'mcp__switchroom-telegram__send_typing':
       case 'mcp__hindsight__sync_retain':
         return null
     }
-    // Any other mcp__* tool: not on the allowlist, no label.
-    return null
+    // Generic fallback for ANY other MCP tool (operator-configured servers
+    // — perplexity, webkite, gdrive, notion, …). These previously returned
+    // null → invisible in the live activity feed, so a research turn driven
+    // entirely by MCP tools read as pure silence (only a typing dot + the
+    // 👀 reaction) — the "I can't see what it's doing" report. Mirror the
+    // gateway's describeToolUse: friendly per-server labels, else a
+    // model-authored field, else a humanized tool name. NEVER label
+    // switchroom-telegram surface/control tools (they ARE the conversation).
+    const m = /^mcp__(.+?)__(.+)$/.exec(toolName)
+    if (!m) return null
+    const server = m[1].toLowerCase()
+    const tool = m[2].toLowerCase()
+    if (server === 'switchroom-telegram') return null
+    if (server === 'hindsight') return 'Working with memory'
+    if (server === 'google-workspace' || server === 'claude_ai_google_calendar')
+      return 'Checking your calendar'
+    if (server === 'claude_ai_gmail') return 'Checking your email'
+    if (server === 'claude_ai_google_drive' || server === 'gdrive')
+      return 'Looking through your files'
+    if (server === 'notion' || server === 'claude_ai_notion') return 'Checking your notes'
+    if (server === 'perplexity') {
+      const q = clip(String(i.query ?? i.description ?? ''), 60).trim()
+      return q ? `Searching the web for ${q}` : 'Searching the web'
+    }
+    if (server === 'webkite') {
+      const u = clip(urlHostPath(i.url ?? ''), 60).trim()
+      return u ? `Reading ${u}` : 'Reading the web'
+    }
+    // Unknown MCP server: prefer a model-authored field, else humanized tool.
+    const desc =
+      clip(String(i.description ?? ''), 60).trim() ||
+      clip(String(i.query ?? ''), 50).trim() ||
+      clip(String(i.title ?? ''), 50).trim()
+    if (desc) return desc
+    return `Using ${tool.replace(/[-_]+/g, ' ')}`
   }
 
   return null

package/telegram-plugin/tests/vault-grant-inbound-builders.test.ts

@@ -16,7 +16,11 @@ import { describe, it, expect } from 'vitest'
 import {
   buildVaultGrantApprovedInbound,
   buildVaultGrantDeniedInbound,
+  buildVaultSaveCompletedInbound,
+  buildVaultSaveFailedInbound,
+  buildVaultSaveDiscardedInbound,
   type VaultGrantInboundContext,
+  type VaultSaveInboundContext,
 } from '../gateway/vault-grant-inbound-builders.js'
 
 const FIXED_NOW = 1_700_000_000_000
@@ -224,3 +228,83 @@ describe('approve vs deny shape invariants', () => {
     expect(String(deny.meta?.source)).toMatch(/^vault_grant_denied$/)
   })
 })
+
+// ── Supergroup topic routing (gap #2) ──────────────────────────────────────
+//
+// When the agent requested the credential from inside a forum topic, the
+// grant/save-outcome inbound must carry that topic so the resumed turn's
+// reply lands back in it — not General. The carrier is two-fold and BOTH
+// halves are load-bearing:
+//   - top-level `threadId` → the gateway's per-topic busy-key / deliver-
+//     until-acked keying (markClaudeBusyForInbound reads it).
+//   - `meta.message_thread_id` (stringified) → rendered into the
+//     `<channel message_thread_id="…">` XML, which session-tail's
+//     parseChannelMeta re-extracts to set currentTurn.sessionThreadId, which
+//     the reply tool defaults to. Drop either and the reply mis-routes.
+//
+// DM / non-topic requests must leave BOTH absent (an empty-string or 0
+// thread is a Telegram 400 "message thread not found").
+describe('grant/save outcome topic routing', () => {
+  const SAVE_CTX: VaultSaveInboundContext = {
+    agent: 'marko',
+    key: 'brevo/api-key',
+    chat_id: '-1001234567890',
+  }
+  const THREAD = 4242
+
+  const grantBuilders = [
+    {
+      name: 'approved',
+      build: (ctx: VaultGrantInboundContext) =>
+        buildVaultGrantApprovedInbound({ ctx, grantId: 'vg_x', stageId: 's', operatorId: '1' }),
+    },
+    {
+      name: 'denied',
+      build: (ctx: VaultGrantInboundContext) =>
+        buildVaultGrantDeniedInbound({ ctx, stageId: 's', operatorId: '1' }),
+    },
+  ]
+  const saveBuilders = [
+    {
+      name: 'save-completed',
+      build: (ctx: VaultSaveInboundContext) =>
+        buildVaultSaveCompletedInbound({ ctx, stageId: 's', operatorId: '1' }),
+    },
+    {
+      name: 'save-failed',
+      build: (ctx: VaultSaveInboundContext) =>
+        buildVaultSaveFailedInbound({ ctx, stageId: 's', operatorId: '1', reason: 'disk full' }),
+    },
+    {
+      name: 'save-discarded',
+      build: (ctx: VaultSaveInboundContext) =>
+        buildVaultSaveDiscardedInbound({ ctx, stageId: 's', operatorId: '1' }),
+    },
+  ]
+
+  for (const { name, build } of grantBuilders) {
+    it(`${name}: threadId set → top-level threadId + meta.message_thread_id (stringified)`, () => {
+      const msg = build({ ...CTX_READ, threadId: THREAD })
+      expect(msg.threadId).toBe(THREAD)
+      expect(msg.meta?.message_thread_id).toBe(String(THREAD))
+    })
+    it(`${name}: threadId absent → both omitted (DM stays thread-less)`, () => {
+      const msg = build(CTX_READ)
+      expect(msg.threadId).toBeUndefined()
+      expect(msg.meta?.message_thread_id).toBeUndefined()
+    })
+  }
+
+  for (const { name, build } of saveBuilders) {
+    it(`${name}: threadId set → top-level threadId + meta.message_thread_id (stringified)`, () => {
+      const msg = build({ ...SAVE_CTX, threadId: THREAD })
+      expect(msg.threadId).toBe(THREAD)
+      expect(msg.meta?.message_thread_id).toBe(String(THREAD))
+    })
+    it(`${name}: threadId absent → both omitted (DM stays thread-less)`, () => {
+      const msg = build(SAVE_CTX)
+      expect(msg.threadId).toBeUndefined()
+      expect(msg.meta?.message_thread_id).toBeUndefined()
+    })
+  }
+})