@llblab/pi-telegram 0.27.3 → 0.27.5

package/AGENTS.md

@@ -82,7 +82,7 @@ The core product loop is mobile continuation: start or supervise work in the ter
 - `/telegram-connect` is the bounded liveness-recovery boundary for unclean-shutdown corruption in disposable `tmp/telegram` state. It may quarantine only classifier-approved malformed `owners.json`, active-profile `state*.json`, and `owners.json.transaction` after serializing recoverers and revalidating under ownership fencing; it must preserve `telegram.json`, diagnostics, unrelated artifacts, and every verifiable live owner/transaction holder. Stale heartbeats older than eight seconds do not gain protection through PID reuse. Require confirmed local polling suspension before quarantine mutation; a suspension failure blocks recovery, while an ownership-release failure may continue only into final guarded live-owner revalidation. Use the established bounded Windows sharing-violation rename retries. Retry polling exactly once after recovery, preserve unrelated startup errors, and replace blocked/repeated recovery failure with one explicit restart instruction rather than broad `tmp/` deletion or an automatic loop.
 - Telegram profiles are parallel bot/runtime realities, not merely alternate credentials. Persist every bot/session field (`botToken`, `botUsername`, `botId`, `allowedUserId`, `lastUpdateId`) under `telegram.json` `profiles.<name>`, including `profiles.default`; keep shared handlers and assistant/voice/time/thread-lifecycle settings top-level. Bare and explicit `default` setup/connect commands address the same profile. Legacy root identity may normalize atomically only when unambiguous; conflicts fail closed without mutation. Any owner slot, IPC endpoint, state snapshot, diagnostics log, thread/bus binding, runtime cache, ownership map, or operator-visible status surface that could mix bot identities must be deliberately classified as global, session-local, or profile-scoped. Use the `default` owner slot for the default profile and validated profile names for named slots; give named profiles isolated observable surfaces unless there is an explicit top-level shared-config reason not to.
 - Telegram private-chat Threaded Mode is the public switch for the local multi-instance bus. There is no separate public `telegram.json` bus switch: classic/private-chat singleton DM behavior is the base product mode, and when Telegram reports Threaded Mode available for the bot the bridge enables leader/follower bus behavior. If Telegram reports Threaded Mode unavailable or thread operations prove it unavailable, the bridge returns to classic singleton behavior as a first-class mode. During a live Threaded Mode downgrade, the current transport leader keeps the singleton classic polling role and followers disconnect instead of taking over or offering takeover while active thread bindings prove this is a downgrade from a live bus organism. Do not inject slot/thread rename guidance in classic mode. Blocked instances should not silently register as followers unless the effective runtime mode is Threaded Mode.
-- In Threaded Mode, exactly one live leader owns `getUpdates` and direct Telegram Bot API calls for one bot token. `/telegram-connect` means join the local Telegram organism: if no live leader exists the instance becomes leader; if a live leader exists the terminal-visible instance registers as follower; ordinary connect must not offer manual takeover while the leader heartbeat is live. Leadership is an ephemeral transport role, not permanent ownership by the first terminal-visible Pi instance. Heartbeat acknowledgements carry the authenticated live follower-slot roster: on leader loss, the lowest observed live slot attempts the atomic lock first, while higher slots defer for one bounded grace and then re-check so a missing lower follower cannot block recovery indefinitely. Followers must be started by the operator as real Pi processes, register over the local bus, heartbeat, receive only their routed inbound updates, and send outbound replies/previews/files/chat-actions through the leader transport; Telegram must not spawn hidden Pi processes, launch follower subprocesses, or expose a slash command that creates a new local Pi instance. If a leader reloads while followers stay alive, followers must treat rejected/unknown/unauthorized heartbeats as a registration-loss signal and optimistically re-register with the currently active leader before considering promotion; after a short grace window without successful re-registration, a live follower may promote only through an atomic expected-owner transition after the exact observed leader lease becomes stale or inactive. An unreachable IPC endpoint does not authorize replacing a still-live lock owner; remain disconnected/retrying rather than creating split-brain polling. Terminal status must not remain `follower` while the leader registry can no longer route that follower's thread. Heartbeat pruning is liveness bookkeeping, not permission by itself to delete, mark offline, or send a Telegram-visible disconnected notice for a follower's thread; preserve active follower tabs/bindings across transient reload/reconnect incidents and reserve destructive teardown/offline transitions for confirmed manual disconnect, graceful Pi quit, or confirmed reconciliation cases. A stale follower may become a confirmed reconciliation case only when Thread cleanup is enabled, the OS reports the exact registered PID absent, and cleanup serializes ahead of replacement registration; live/unknown PID state remains non-destructive. If the leader dies, a live follower should eventually be able to take over through stale-leader election/recovery so the local multi-instance organism keeps running. Explicit `/telegram-disconnect` retains destructive confirmation; graceful Pi `quit` invokes the same teardown without prompting when top-level `threads.automaticCleanup` is enabled (default), while disabling it and `reload`, `new`, `resume`, or `fork` preserve the binding through safe handoff/suspension. A leader deletes its own bound thread before releasing transport ownership, while a follower sends an authenticated exact-registration-generation disconnect envelope and waits for the leader to delete its assigned thread, mark the durable binding offline, and remove live routing authority before unregistering. Cleanup must be confirmed by successful deletion or explicit already-gone evidence. Confirmed leader/follower teardown persists an exact target/runtime-generation cleanup intent before destructive API work; interruption preserves that intent for the current or successor leader to replay under its own epoch, while leader startup must first adopt a still-active same-profile binding and cancel its superseded cleanup before any destructive API call. Confirmation removes both the binding and intent atomically from the next persisted snapshot. Silence, heartbeat expiry, process absence, IPC failure, and auth mismatch create no cleanup intent by themselves; only stale heartbeat combined with enabled cleanup and OS-confirmed absence of the exact registered follower PID may authorize fallback intent. Incomplete manual cleanup preserves binding/routing state, keeps the session open, and returns actionable retry guidance. A promoted leader authorizes inherited follower-thread cleanup by its current leader epoch rather than the historical owner label. Status is reactive to the effective runtime role and bot capability: classic/non-thread mode shows ordinary `telegram connected`, active bus leadership shows `telegram leader`, and registered followers show `telegram follower`; stable multi-instance truth belongs in the bus role (`leader`/`follower`), while lifecycle is reserved for transient recovery state such as `electing` and must not duplicate stable roles with labels like `leader-active`. When leadership or Threaded Mode availability changes at runtime, the status line and `/telegram-status` must converge promptly instead of preserving a stale role label.
+- In Threaded Mode, exactly one live leader owns `getUpdates` and direct Telegram Bot API calls for one bot token. `/telegram-connect` means join the local Telegram organism: if no live leader exists the instance becomes leader; if a live leader exists the terminal-visible instance registers as follower; ordinary connect must not offer manual takeover while the leader heartbeat is live. Leadership is an ephemeral transport role, not permanent ownership by the first terminal-visible Pi instance. Heartbeat acknowledgements carry the authenticated live follower-slot roster: on leader loss, the lowest observed live slot attempts the atomic lock first, while higher slots defer for one bounded grace and then re-check so a missing lower follower cannot block recovery indefinitely. Followers must be started by the operator as real Pi processes, register over the local bus, heartbeat, receive only their routed inbound updates, and send outbound replies/previews/files/chat-actions through the leader transport; Telegram must not spawn hidden Pi processes, launch follower subprocesses, or expose a slash command that creates a new local Pi instance. If a leader reloads while followers stay alive, followers must treat rejected/unknown/unauthorized heartbeats as a registration-loss signal and optimistically re-register with the currently active leader before considering promotion; after a short grace window without successful re-registration, a live follower may promote only through an atomic expected-owner transition after the exact observed leader lease becomes stale or inactive. An unreachable IPC endpoint does not authorize replacing a still-live lock owner; remain disconnected/retrying rather than creating split-brain polling. Terminal status must not remain `follower` while the leader registry can no longer route that follower's thread. Heartbeat pruning is liveness bookkeeping, not permission by itself to delete, mark offline, or send a Telegram-visible disconnected notice for a follower's thread; preserve active follower tabs/bindings across transient reload/reconnect incidents and reserve destructive teardown/offline transitions for confirmed manual disconnect, graceful Pi quit, or confirmed reconciliation cases. A stale follower may become a confirmed reconciliation case only when Thread cleanup is enabled, the OS reports the exact registered PID absent, and cleanup serializes ahead of replacement registration; live/unknown PID state remains non-destructive. If the leader dies, a live follower should eventually be able to take over through stale-leader election/recovery so the local multi-instance organism keeps running. Explicit `/telegram-disconnect` retains destructive confirmation; graceful Pi `quit` invokes the same teardown without prompting when top-level `threads.automaticCleanup` is enabled (default), while disabling it and `reload`, `new`, `resume`, or `fork` preserve the binding through safe handoff/suspension. A leader persists cleanup intent and attempts to delete its own bound thread before releasing transport ownership, while a follower sends an authenticated exact-registration-generation disconnect envelope and waits for the leader to delete its assigned thread, mark the durable binding offline, and remove live routing authority before unregistering. Successful cleanup still requires confirmed deletion or explicit already-gone evidence, but an incomplete manual leader cleanup must not retain the transport lock: release leadership, preserve the binding plus intent, and let the successor replay it. Confirmed leader/follower teardown persists an exact target/runtime-generation cleanup intent before destructive API work; interruption preserves that intent for the current or successor leader to replay under its own epoch, while leader startup must first adopt a still-active same-profile binding and cancel its superseded cleanup before any destructive API call. Confirmation removes both the binding and intent atomically from the next persisted snapshot. Silence, heartbeat expiry, process absence, IPC failure, and auth mismatch create no cleanup intent by themselves; only stale heartbeat combined with enabled cleanup and OS-confirmed absence of the exact registered follower PID may authorize fallback intent. Incomplete manual follower cleanup preserves binding/routing state and returns actionable retry guidance; incomplete leader or promoted-leader cleanup preserves the durable intent but disconnects and releases leadership with a warning so cleanup failure cannot pin election. A promoted leader authorizes inherited follower-thread cleanup by its current leader epoch rather than the historical owner label. Status is reactive to the effective runtime role and bot capability: classic/non-thread mode shows ordinary `telegram connected`, active bus leadership shows `telegram leader`, and registered followers show `telegram follower`; stable multi-instance truth belongs in the bus role (`leader`/`follower`), while lifecycle is reserved for transient recovery state such as `electing` and must not duplicate stable roles with labels like `leader-active`. When leadership or Threaded Mode availability changes at runtime, the status line and `/telegram-status` must converge promptly instead of preserving a stale role label.
 - Runtime routing binds to a live `instanceId` plus its exact follower registration generation; current thread identity should use explicit owner records (`leader`, `manual-follower`, `pending-topic`) rather than hiding ownership direction in legacy string keys. Persisted manual-follower records may act as stable restart hints, but only an authenticated live registry entry authorizes inbound forwarding or outbound transport; stale session records must not be treated as live owners. A live instance owns at most one active bound thread; provisioning a new target for the same `instanceId` must remove older current-state bindings and close duplicate Telegram threads when possible. A reload creates a new runtime `instanceId`; if the previous leader slot is still known/alive, keep it occupied in reservations and assign the new leader the next free slot instead of creating a duplicate same-letter tab or blocking startup on Telegram UI convergence.
 - Follower registration readiness should stay on the smallest critical path that makes the follower routable: create or reuse the Telegram target, persist the active binding, mark target-bindings fresh, and return the target to the follower. Registration requires a present exact generation. Cross-session target reuse and any carried target absent from current bindings require one synchronous visibility probe: explicit stale evidence may provision a replacement, while ambiguous/non-stale failure must reject registration without replay, binding invalidation, or speculative replacement. Persist an ambiguously observed absent target only as non-routable `probe-required` restoration evidence so targetless retries and leader reloads must probe the exact target again before activation or replacement. Registration and explicit disconnect mutations for one durable follower profile must serialize across awaited cleanup so an old runtime's disconnect cannot delete or unregister a replacement generation. Manual follower identity must survive a Pi process reload in the same terminal so reload is not treated as a new follower/thread; derive stable process-birth identity from OS metadata where available, and carry a fresh authenticated previous-runtime-plus-exact-target handoff through initial registration so a changed identity migrates rather than provisions. Do not key durable follower ownership only by the short-lived Pi process id. Telegram-visible connected notices, duplicate/replaced thread cleanup, and other reconciliation work are important but non-critical; run them after registration and record slow/failing background steps as runtime events rather than delaying follower usability.
 - Instance slots are extension-owned ring-order metadata. Allocate fresh slots from the `bot.lastSlot` cursor as `A` → `B` → ... → `Z` → `A`, allowing the cursor to move to lower letters after wraparound. Only current live/recovering bindings plus unexpired pending provisions and explicit reservations occupy slots; historical records must not block allocation indefinitely. Preserve a slot on ordinary current binding/thread reuse without advancing or rewinding the fresh-allocation cursor. Follower bindings survive process absence as stable restoration hints unless enabled Thread cleanup turns stale heartbeat plus exact-PID death confirmation into fenced cleanup authority; otherwise only explicit stale/deleted/offline evidence invalidates them. Successful target reuse must refresh the binding timestamp and replacement runtime identity; generic leader startup or heartbeat pruning alone must not erase the target merely because no follower registration is currently live. An authenticated live follower whose carried exact target is missing from current persisted bindings should recover that target instead of creating another Telegram thread; preserve a carried slot only when it does not collide with another current record. Preserve a cursor that belongs to a live or recoverable binding and continue skipping retained restart hints plus unexpired pending/reserved slots. Explicit stale/deleted/offline reconciliation may release that slot; generic process absence may not. The alphabet cap is a feature — compact single-letter tabs are scannable.

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.27.5: Cross-Instance Agent Turns
+
+- `Live Thread Addressing`: `telegram_message` now accepts `thread` as a case-insensitive live thread name or numeric id. Resolution uses leader-owned live registrations and rejects unknown, ambiguous, same-target, offline, and cross-chat destinations before visible Telegram mutation.
+- `Agent Turn Routing`: A successful targeted send routes the same text through the authenticated, generation-fenced bus into the owning Pi instance as `[agent|from-thread:<name>]`, preserving one visible Telegram message without impersonating direct user input. Leader and follower targets share the ordinary inbound queue path, request deduplication, rendering, buttons, and authority fencing.
+- `Compatibility and Coverage`: Existing default and `chat_id` / `thread_id` behavior remains compatible; active-turn cross-thread sends gain agent routing when available. Regressions cover protocol parsing, stale generations, name resolution, ambiguity, attribution, preflight ordering, and tool delivery.
+
+## 0.27.4: Disconnect Leadership Release Hotfix
+
+- `Leadership Release`: Manual disconnect now treats thread deletion as a durable cleanup side effect rather than a prerequisite for relinquishing transport leadership. A leader or promoted follower persists the exact cleanup intent, attempts close/delete under its epoch, and then stops polling and releases the owner lock even when Telegram rejects cleanup or the epoch changes. Impact: `Telegram Error` after `/telegram-disconnect` can no longer leave a live process pinning leadership and force newly connected instances to become followers.
+- `Successor Recovery`: Incomplete leader cleanup remains recorded with its binding and exact generation for the next elected leader to replay; the disconnect returns a warning instead of throwing before lock release. Successful cleanup behavior remains unchanged, and manual followers still require authenticated live-leader teardown. Impact: thread safety and retryability survive without sacrificing leadership liveness.
+- `Regression Coverage`: Added exact promoted-leader and epoch-loss disconnect regressions proving cleanup diagnostics remain visible while `stopPolling` still runs. Impact: future cleanup hardening cannot silently restore the lock-hostage failure mode.
+
 ## 0.27.3: Follower Cross-Thread Delivery Hotfix
 
 - `Follower Cross-Thread Delivery`: The bus-aware Telegram API runtime now marks sends whose target differs from the follower's assigned thread, and the leader authorizes that internal marker only for a different target inside the same paired chat before stripping it from the Bot API request. Impact: `telegram_message` can fulfill explicit inter-thread delivery from follower instances without opening arbitrary cross-chat or generic follower API access.

package/docs/multi-instance-bus.md

@@ -281,6 +281,8 @@ Follower instances receive normalized events, not raw Telegram transport interna
 
 Followers do not call Telegram Bot API directly for routed Telegram work. Instead, they call a leader-owned transport port:
 
+Explicit `telegram_message(..., thread)` delivery also uses the bus as an agent-message plane. The leader resolves the case-insensitive name or numeric id against live leader/follower registrations, rejects ambiguous, stale, same-instance, cross-chat, and replayed requests, then coordinates visible Bot API delivery with one source-attributed synthetic turn routed through the destination instance's ordinary queue. The destination sees `[agent|from-thread:<name>]`, not an impersonated user message. Generation fencing and request-ledger deduplication apply to both resolution and routing.
+
 ```text
 follower reply/preview/upload/chat-action/download/callback-answer -> leader IPC -> Telegram API
 ```
@@ -439,7 +441,7 @@ Live client and native Windows evidence gates are tracked in `BACKLOG.md`; this
 - Local IPC is the default internal bus. Registered followers receive normalized inbound updates and send allowlisted, target-scoped Bot API calls through the leader.
 - Thread targets are current-state bindings, not historical delivery addresses. Stable restart hints require a fresh authenticated follower registration before they become live routing authority; stale/offline/failed entries remain reconciliation evidence only.
 - Failover promotes a remaining follower after dead or clean-disconnected leaders without creating competing pollers; follower heartbeat recovery owns re-register → grace → promotion while preserving thread bindings across transient leader reload gaps.
-- Thread cleanup is centralized in `thread-reconciler`, fails closed without a leader epoch while leadership exists, revalidates that epoch immediately before every close/delete call and local cleanup-state mutation, and requires confirmed delete/stale evidence before state is marked deleted.
+- Thread cleanup is centralized in `thread-reconciler`, fails closed without a leader epoch while leadership exists, revalidates that epoch immediately before every close/delete call and local cleanup-state mutation, and requires confirmed delete/stale evidence before state is marked deleted. Manual leader and promoted-leader disconnect persist cleanup intent first but always stop polling and release the owner lock even when Telegram cleanup is incomplete; the successor replays the retained intent, so a Bot API or epoch failure cannot pin leadership. Manual followers still require a live leader acknowledgement for destructive teardown.
 - Stable docs/UI now describe classic mode, opt-in Threaded Mode, manual follower registration, status/diagnostics, unbound-thread reroute/restore UX, and operator recovery boundaries.
 
 ## Evidence Gates

package/docs/outbound.md

@@ -2,7 +2,7 @@
 
 `pi-telegram` maps hidden assistant-authored HTML comments to Telegram-native outbound actions.
 
-Normal Telegram-turn replies are intentionally prompt-driven: the agent writes Markdown plus small hidden top-level blocks, and the bridge performs transport after `agent_end`. `telegram_voice` and `telegram_button` are not Pi tools. For local/TUI-initiated work where the user explicitly asks to send something to Telegram, the bridge also exposes direct tools: `telegram_message` for Markdown text and `telegram_attach` for file delivery when no Telegram turn is active. In classic mode, direct local/TUI delivery requires this Pi instance to own `/telegram-connect`; in Threaded Mode, a registered follower may route direct-tool sends through the leader-owned bus transport. During an active Telegram turn, `telegram_message` rejects an implicit or same-turn target so ordinary final delivery remains the sole current-target response, but an explicit different chat/thread target remains available for requested cross-target delivery. If transport authority is absent, the tools fail instead of bypassing singleton ownership. Explicit thread delivery uses `chat_id` plus `thread_id`; registered followers default to their assigned thread target. Outbound behavior combines assistant prompt markup, text command-template handlers, registered voice synthesis providers, generated artifacts, direct Telegram tools, and reply delivery. Direct `telegram_message` text is planned through the same reply markup path, so embedded top-level `telegram_button` comments become buttons attached to that text message.
+Normal Telegram-turn replies are intentionally prompt-driven: the agent writes Markdown plus small hidden top-level blocks, and the bridge performs transport after `agent_end`. `telegram_voice` and `telegram_button` are not Pi tools. For local/TUI-initiated work where the user explicitly asks to send something to Telegram, the bridge also exposes direct tools: `telegram_message` for Markdown text and `telegram_attach` for file delivery when no Telegram turn is active. In classic mode, direct local/TUI delivery requires this Pi instance to own `/telegram-connect`; in Threaded Mode, a registered follower may route direct-tool sends through the leader-owned bus transport. During an active Telegram turn, `telegram_message` rejects an implicit or same-turn target so ordinary final delivery remains the sole current-target response. Its `thread` argument accepts a case-insensitive live thread name or numeric id: the bridge preflights one live owner, sends visibly, then admits the text as a source-attributed turn in that instance. Unknown, ambiguous, same-target, offline, and cross-chat destinations fail before sending. Existing `chat_id` plus `thread_id` targeting stays compatible; registered followers use authenticated, generation-fenced bus routing. Outbound behavior combines assistant prompt markup, text command-template handlers, registered voice synthesis providers, generated artifacts, direct Telegram tools, and reply delivery. Direct `telegram_message` text is planned through the same reply markup path, so embedded top-level `telegram_button` comments become buttons attached to that text message.
 
 Text handlers use the portable [Command Template Standard](./command-templates.md). Programmatic outbound handlers use `registerTelegramOutboundHandler(kind, handler)`. Voice replies can use configured command-template handlers or the provider API described in [Voice Integration](./voice.md).
 

package/index.ts

@@ -5,6 +5,7 @@
  */
 
 import * as Activity from "./lib/activity.ts";
+import * as AgentMessages from "./lib/agent-messages.ts";
 import * as ActivityVerbosity from "./lib/activity-verbosity.ts";
 import * as Bindings from "./lib/bindings.ts";
 import * as BusApi from "./lib/bus-api.ts";
@@ -811,6 +812,17 @@ export default function (pi: Pi.ExtensionAPI) {
       handleAuthorizedReactionUpdate:
         inboundRouteRuntime.handleAuthorizedReactionUpdate,
     });
+  const agentMessageRuntime = AgentMessages.createTelegramAgentMessageRuntime({
+    instanceId: telegramInstanceId,
+    getAllowedChatId: configStore.getAllowedUserId,
+    getLeaderTarget: telegramBusLeaderState.getTarget,
+    getLeaderThreadName() {
+      return findCurrentThreadRecord()?.threadName;
+    },
+    followerRegistry: telegramBusFollowerRegistry,
+    getContext: telegramSessionContextStore.get,
+    handleUpdate: inboundRouteRuntime.handleUpdate,
+  });
   const telegramBusFollowerAssemblyDeps =
     BusFollower.createTelegramBusFollowerRuntimeAssemblyDeps<
       Pi.ExtensionContext,
@@ -898,6 +910,16 @@ export default function (pi: Pi.ExtensionAPI) {
         startPolling: pollingRuntime.start,
         stopPolling: pollingRuntime.stop,
         authorizeFollowerApiCall,
+        resolveAgentTarget(follower, selector) {
+          return agentMessageRuntime.resolveTarget(selector, follower.target);
+        },
+        routeAgentMessage(follower, message) {
+          return agentMessageRuntime.route({
+            sourceTarget: follower.target,
+            sourceThreadName: follower.threadName,
+            message,
+          });
+        },
         isFollowerProcessAlive: Locks.isProcessAlive,
         shouldCleanupConfirmedDeadFollower:
           configControls.resolveAutomaticThreadCleanupEnabled,
@@ -1094,6 +1116,32 @@ export default function (pi: Pi.ExtensionAPI) {
     callMultipart,
     getDefaultChatId: proactivePushChatIdGetter,
     getDefaultTarget: proactivePushTargetGetter,
+    async resolveAgentTarget(selector) {
+      if (lockRuntime.owns()) {
+        const target = agentMessageRuntime.resolveTarget(
+          selector,
+          proactivePushTargetGetter(),
+        );
+        if (!target) {
+          throw new Error(
+            "Telegram agent target is unavailable, ambiguous, or not live.",
+          );
+        }
+        return target;
+      }
+      return telegramBusFollowerClients.agentMessages.resolveTarget(selector);
+    },
+    async routeAgentMessage(message) {
+      if (lockRuntime.owns()) {
+        await agentMessageRuntime.route({
+          sourceTarget: proactivePushTargetGetter(),
+          sourceThreadName: findCurrentThreadRecord()?.threadName,
+          message,
+        });
+        return;
+      }
+      await telegramBusFollowerClients.agentMessages.routeMessage(message);
+    },
     canSendDirect() {
       return (
         ownsTelegramDirectDelivery() ||

package/lib/agent-messages.ts

@@ -0,0 +1,116 @@
+/**
+ * Cross-instance Telegram agent message resolution and turn injection
+ * Zones: multi-instance bus, inbound routing, operational delivery
+ * Owns live target resolution, source attribution, same-target fencing, and synthetic turn construction; excludes Bot API delivery and bus transport.
+ */
+
+import type {
+  TelegramBusAgentMessage,
+  TelegramBusAgentTargetSelector,
+  TelegramBusFollowerRegistry,
+} from "./bus.ts";
+import type { TelegramRoutedMessage } from "./routing.ts";
+import type { TelegramTarget } from "./target.ts";
+
+export interface TelegramAgentMessageRuntimeDeps<TContext, TUpdate> {
+  instanceId: string;
+  getAllowedChatId: () => number | undefined;
+  getLeaderTarget: () => TelegramTarget | undefined;
+  getLeaderThreadName: () => string | undefined;
+  followerRegistry: TelegramBusFollowerRegistry;
+  getContext: () => TContext | undefined;
+  handleUpdate: (update: TUpdate, ctx: TContext) => Promise<void>;
+  getNowMs?: () => number;
+}
+
+export function createTelegramAgentMessageRuntime<TContext, TUpdate>(
+  deps: TelegramAgentMessageRuntimeDeps<TContext, TUpdate>,
+) {
+  const getNowMs = deps.getNowMs ?? Date.now;
+  const sameTarget = (left?: TelegramTarget, right?: TelegramTarget) =>
+    left?.chatId === right?.chatId && left?.threadId === right?.threadId;
+  const listLiveTargets = () => {
+    const targets: Array<{
+      target: TelegramTarget & { threadId: number };
+      threadName?: string;
+    }> = [];
+    const leaderTarget = deps.getLeaderTarget();
+    if (leaderTarget?.threadId) {
+      targets.push({
+        target: { chatId: leaderTarget.chatId, threadId: leaderTarget.threadId },
+        threadName: deps.getLeaderThreadName(),
+      });
+    }
+    for (const follower of deps.followerRegistry.list()) {
+      if (!follower.target?.threadId) continue;
+      targets.push({
+        target: {
+          chatId: follower.target.chatId,
+          threadId: follower.target.threadId,
+        },
+        threadName: follower.threadName,
+      });
+    }
+    return targets;
+  };
+  const resolveTarget = (
+    selector: TelegramBusAgentTargetSelector,
+    sourceTarget?: TelegramTarget,
+  ): (TelegramTarget & { threadId: number }) | undefined => {
+    const allowedChatId = deps.getAllowedChatId();
+    const chatId = selector.chatId ?? allowedChatId;
+    if (chatId === undefined || chatId !== allowedChatId) return undefined;
+    const matches = listLiveTargets().filter((candidate) => {
+      if (candidate.target.chatId !== chatId) return false;
+      if (selector.threadId !== undefined) {
+        return candidate.target.threadId === selector.threadId;
+      }
+      const requestedName = selector.threadName?.trim().toLocaleLowerCase();
+      return (
+        requestedName !== undefined &&
+        requestedName.length > 0 &&
+        candidate.threadName?.trim().toLocaleLowerCase() === requestedName
+      );
+    });
+    if (matches.length !== 1) return undefined;
+    return sameTarget(matches[0]!.target, sourceTarget)
+      ? undefined
+      : matches[0]!.target;
+  };
+  return {
+    resolveTarget,
+    async route(input: {
+      sourceTarget?: TelegramTarget;
+      sourceThreadName?: string;
+      message: TelegramBusAgentMessage;
+    }): Promise<void> {
+      const target = resolveTarget(
+        {
+          chatId: input.message.target.chatId,
+          threadId: input.message.target.threadId,
+        },
+        input.sourceTarget,
+      );
+      if (!target) throw new Error("Telegram agent target is no longer live.");
+      const allowedChatId = deps.getAllowedChatId();
+      const ctx = deps.getContext();
+      if (allowedChatId === undefined || !ctx) {
+        throw new Error("Telegram agent turn routing is unavailable.");
+      }
+      const sourceLabel =
+        input.sourceThreadName
+          ?.replace(/[\r\n\[\]]+/g, " ")
+          .trim()
+          .slice(0, 64) || "Pi";
+      const message = {
+        message_id: input.message.messageId,
+        date: Math.floor(getNowMs() / 1000),
+        chat: { id: target.chatId, type: "private" as const },
+        from: { id: allowedChatId, is_bot: false, first_name: "Pi Agent" },
+        message_thread_id: target.threadId,
+        text: `[agent|from-thread:${sourceLabel}]\n\n${input.message.text}`,
+      } as TelegramRoutedMessage;
+      await deps.handleUpdate({ message } as TUpdate, ctx);
+    },
+  };
+}

package/lib/bindings.ts

@@ -121,6 +121,8 @@ interface TelegramCommandsAndToolsBindingDeps {
   callMultipart: OutboundHandlers.TelegramVoiceReplySenderDeps["sendMultipart"];
   getDefaultChatId: () => number | undefined;
   getDefaultTarget?: () => OutboundAttachments.TelegramQueuedOutboundAttachmentTurnView["target"];
+  resolveAgentTarget?: OutboundAttachments.TelegramOutboundMessageToolRegistrationDeps["resolveAgentTarget"];
+  routeAgentMessage?: OutboundAttachments.TelegramOutboundMessageToolRegistrationDeps["routeAgentMessage"];
   canSendDirect: () => boolean;
   updateStatus: TelegramBridgeStatusUpdater;
   recordRuntimeEvent: TelegramRuntimeEventRecorder;
@@ -143,6 +145,8 @@ export function registerTelegramCommandsAndTools({
   callMultipart,
   getDefaultChatId,
   getDefaultTarget,
+  resolveAgentTarget,
+  routeAgentMessage,
   canSendDirect,
   recordRuntimeEvent,
   updateStatus,
@@ -159,6 +163,8 @@ export function registerTelegramCommandsAndTools({
     getDefaultChatId,
     getDefaultTarget,
     getActiveTurn: activeTurnRuntime.get,
+    resolveAgentTarget,
+    routeAgentMessage,
     canSendDirect,
     planMessage:
       OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),

package/lib/bus-follower.ts

@@ -25,6 +25,8 @@ import {
   getTelegramBusSocketPath,
   resolveTelegramBusSocketPath,
   sendTelegramBusLocalEnvelope,
+  type TelegramBusAgentMessage,
+  type TelegramBusAgentTargetSelector,
   type TelegramBusEnvelope,
   type TelegramBusSocketPathSource,
 } from "./bus.ts";
@@ -736,6 +738,12 @@ export function createTelegramBusFollowerClientRuntime<
       getAuthSecret: deps.getApiAuthSecret,
       getRegistrationGeneration: deps.getRegistrationGeneration,
     }),
+    agentMessages: createTelegramBusAgentMessageClient({
+      ...sharedClientDeps,
+      instanceId: deps.instanceId,
+      getAuthSecret: deps.getApiAuthSecret,
+      getRegistrationGeneration: deps.getRegistrationGeneration,
+    }),
     foreignOwnedUpdateForwarder: createTelegramBusForeignOwnedUpdateForwarder<
       TContext,
       TReactionUpdate,
@@ -755,6 +763,79 @@ export function createTelegramBusFollowerClientRuntime<
   };
 }
 
+export function createTelegramBusAgentMessageClient(
+  deps: TelegramBusFollowerApiCallerDeps,
+): {
+  resolveTarget: (
+    selector: TelegramBusAgentTargetSelector,
+  ) => Promise<TelegramTarget & { threadId: number }>;
+  routeMessage: (message: TelegramBusAgentMessage) => Promise<void>;
+} {
+  const getNowMs = deps.getNowMs ?? Date.now;
+  const timeoutMs =
+    deps.timeoutMs ?? TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS;
+  const request = async (
+    envelope:
+      | Extract<TelegramBusEnvelope, { kind: "follower.resolveAgentTarget" }>
+      | Extract<TelegramBusEnvelope, { kind: "follower.routeAgentMessage" }>,
+  ): Promise<unknown> => {
+    const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
+    const response = await sendTelegramBusLocalEnvelope({
+      socketPath,
+      timeoutMs,
+      retry: getTelegramBusTransportRetryPolicy({
+        endpoint: socketPath,
+        operation: "operation",
+      }),
+      envelope,
+    });
+    if (response?.kind === "bus.ack" && response.ok) return response.result;
+    throw new Error(
+      response?.kind === "bus.ack"
+        ? response.message ?? "Telegram bus agent message failed."
+        : "Telegram bus agent message did not return an acknowledgement.",
+    );
+  };
+  const registrationFields = () => ({
+    auth: deps.getAuthSecret?.(),
+    instanceId: deps.instanceId,
+    ...(deps.getRegistrationGeneration?.()
+      ? { registrationGeneration: deps.getRegistrationGeneration?.() }
+      : {}),
+  });
+  return {
+    async resolveTarget(selector) {
+      const result = await request({
+        kind: "follower.resolveAgentTarget",
+        requestId: deps.createRequestId(),
+        ...registrationFields(),
+        selector,
+        sentAtMs: getNowMs(),
+      });
+      if (!result || typeof result !== "object" || Array.isArray(result)) {
+        throw new Error("Telegram bus returned an invalid agent target.");
+      }
+      const target = result as Record<string, unknown>;
+      if (
+        typeof target.chatId !== "number" ||
+        typeof target.threadId !== "number"
+      ) {
+        throw new Error("Telegram bus returned an invalid agent target.");
+      }
+      return { chatId: target.chatId, threadId: target.threadId };
+    },
+    async routeMessage(message) {
+      await request({
+        kind: "follower.routeAgentMessage",
+        requestId: deps.createRequestId(),
+        ...registrationFields(),
+        message,
+        sentAtMs: getNowMs(),
+      });
+    },
+  };
+}
+
 export function createTelegramBusFollowerApiCaller(
   deps: TelegramBusFollowerApiCallerDeps,
 ): (method: string, args: unknown[]) => Promise<unknown> {

package/lib/bus-leader.ts

@@ -258,6 +258,20 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
     args: unknown[];
   }) => boolean;
   recordFollowerMessageOwnership?: TelegramBusFollowerMessageOwnershipRecorder;
+  resolveAgentTarget?: (
+    follower: TelegramBusFollowerView,
+    selector: Extract<
+      TelegramBusEnvelope,
+      { kind: "follower.resolveAgentTarget" }
+    >["selector"],
+  ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
+  routeAgentMessage?: (
+    follower: TelegramBusFollowerView,
+    message: Extract<
+      TelegramBusEnvelope,
+      { kind: "follower.routeAgentMessage" }
+    >["message"],
+  ) => Promise<void> | void;
   provisionFollowerTarget?: (
     registration: TelegramBusInstanceRegistration,
   ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
@@ -1024,6 +1038,20 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
     args: unknown[];
   }) => boolean;
   recordFollowerMessageOwnership?: TelegramBusFollowerMessageOwnershipRecorder;
+  resolveAgentTarget?: (
+    follower: TelegramBusFollowerView,
+    selector: Extract<
+      TelegramBusEnvelope,
+      { kind: "follower.resolveAgentTarget" }
+    >["selector"],
+  ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
+  routeAgentMessage?: (
+    follower: TelegramBusFollowerView,
+    message: Extract<
+      TelegramBusEnvelope,
+      { kind: "follower.routeAgentMessage" }
+    >["message"],
+  ) => Promise<void> | void;
   provisionFollowerTarget?: (
     registration: TelegramBusInstanceRegistration,
   ) =>
@@ -1044,6 +1072,67 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
   const getNowMs = deps.getNowMs ?? Date.now;
   const runFollowerMutation =
     deps.runFollowerMutation ?? createTelegramBusFollowerMutationRunner();
+  const handleAgentRequest = async (
+    envelope: Extract<
+      TelegramBusEnvelope,
+      {
+        kind:
+          | "follower.resolveAgentTarget"
+          | "follower.routeAgentMessage";
+      }
+    >,
+  ): Promise<TelegramBusEnvelope> => {
+    const follower = deps.followerRegistry.get(envelope.instanceId);
+    if (!follower) {
+      return {
+        kind: "bus.ack",
+        requestId: envelope.requestId,
+        ok: false,
+        message: "Unknown Telegram bus follower instance.",
+      };
+    }
+    if (
+      follower.registrationGeneration &&
+      envelope.registrationGeneration !== follower.registrationGeneration
+    ) {
+      return {
+        kind: "bus.ack",
+        requestId: envelope.requestId,
+        ok: false,
+        message: "Stale Telegram bus follower registration generation.",
+      };
+    }
+    deps.followerRegistry.heartbeat(envelope.instanceId, getNowMs());
+    if (envelope.kind === "follower.resolveAgentTarget") {
+      const target = await deps.resolveAgentTarget?.(
+        follower,
+        envelope.selector,
+      );
+      return target
+        ? {
+            kind: "bus.ack",
+            requestId: envelope.requestId,
+            ok: true,
+            result: target,
+          }
+        : {
+            kind: "bus.ack",
+            requestId: envelope.requestId,
+            ok: false,
+            message: "Telegram agent target is unavailable or ambiguous.",
+          };
+    }
+    if (!deps.routeAgentMessage) {
+      return {
+        kind: "bus.ack",
+        requestId: envelope.requestId,
+        ok: false,
+        message: "Telegram agent message routing is unavailable.",
+      };
+    }
+    await deps.routeAgentMessage(follower, envelope.message);
+    return { kind: "bus.ack", requestId: envelope.requestId, ok: true };
+  };
   const forwardToFollower = async (
     envelope: Extract<
       TelegramBusEnvelope,
@@ -1251,6 +1340,9 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
               message: "Unknown Telegram bus follower instance.",
             };
       }
+      case "follower.resolveAgentTarget":
+      case "follower.routeAgentMessage":
+        return handleAgentRequest(envelope);
       case "leader.forwardCallback":
       case "leader.forwardReaction":
       case "leader.forwardMessage":
@@ -1619,6 +1711,8 @@ export function createTelegramBusLeaderRuntime<TContext>(
       callApi: deps.callApi,
       authorizeFollowerApiCall: deps.authorizeFollowerApiCall,
       recordFollowerMessageOwnership: deps.recordFollowerMessageOwnership,
+      resolveAgentTarget: deps.resolveAgentTarget,
+      routeAgentMessage: deps.routeAgentMessage,
       provisionFollowerTarget: deps.provisionFollowerTarget,
       onFollowerDisconnected: deps.onFollowerDisconnected,
       getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,

package/lib/bus.ts

@@ -448,6 +448,18 @@ export function createTelegramFollowerApiCallAuthorizer(deps: {
     });
 }
 
+export interface TelegramBusAgentTargetSelector {
+  chatId?: number;
+  threadId?: number;
+  threadName?: string;
+}
+
+export interface TelegramBusAgentMessage {
+  target: TelegramTarget & { threadId: number };
+  messageId: number;
+  text: string;
+}
+
 export type TelegramBusEnvelope = (
   | {
       kind: "follower.register";
@@ -511,6 +523,22 @@ export type TelegramBusEnvelope = (
       reason: "thread-restore";
       sentAtMs: number;
     }
+  | {
+      kind: "follower.resolveAgentTarget";
+      requestId: string;
+      instanceId: string;
+      registrationGeneration?: string;
+      selector: TelegramBusAgentTargetSelector;
+      sentAtMs: number;
+    }
+  | {
+      kind: "follower.routeAgentMessage";
+      requestId: string;
+      instanceId: string;
+      registrationGeneration?: string;
+      message: TelegramBusAgentMessage;
+      sentAtMs: number;
+    }
   | {
       kind: "follower.callApi";
       requestId: string;
@@ -605,6 +633,12 @@ export function parseTelegramBusEnvelope(
     case "leader.replaceFollowerTarget":
       envelope = parseReplaceFollowerTargetEnvelope(value, requestId);
       break;
+    case "follower.resolveAgentTarget":
+      envelope = parseResolveAgentTargetEnvelope(value, requestId);
+      break;
+    case "follower.routeAgentMessage":
+      envelope = parseRouteAgentMessageEnvelope(value, requestId);
+      break;
     case "follower.callApi":
       envelope = parseCallApiEnvelope(value, requestId);
       break;
@@ -1582,6 +1616,86 @@ function parseReplaceFollowerTargetEnvelope(
   };
 }
 
+function parseResolveAgentTargetEnvelope(
+  value: Record<string, unknown>,
+  requestId: string,
+): TelegramBusEnvelope | undefined {
+  const selectorValue = isRecord(value.selector) ? value.selector : undefined;
+  if (
+    typeof value.instanceId !== "string" ||
+    !selectorValue ||
+    typeof value.sentAtMs !== "number"
+  ) {
+    return undefined;
+  }
+  const chatId =
+    typeof selectorValue.chatId === "number" &&
+    Number.isInteger(selectorValue.chatId)
+      ? selectorValue.chatId
+      : undefined;
+  const threadId =
+    typeof selectorValue.threadId === "number" &&
+    Number.isInteger(selectorValue.threadId) &&
+    selectorValue.threadId > 0
+      ? selectorValue.threadId
+      : undefined;
+  const threadName =
+    typeof selectorValue.threadName === "string" &&
+    selectorValue.threadName.trim()
+      ? selectorValue.threadName.trim()
+      : undefined;
+  if ((threadId === undefined) === (threadName === undefined)) return undefined;
+  return {
+    kind: "follower.resolveAgentTarget",
+    requestId,
+    instanceId: value.instanceId,
+    ...(typeof value.registrationGeneration === "string"
+      ? { registrationGeneration: value.registrationGeneration }
+      : {}),
+    selector: {
+      ...(chatId !== undefined ? { chatId } : {}),
+      ...(threadId !== undefined ? { threadId } : {}),
+      ...(threadName !== undefined ? { threadName } : {}),
+    },
+    sentAtMs: value.sentAtMs,
+  };
+}
+
+function parseRouteAgentMessageEnvelope(
+  value: Record<string, unknown>,
+  requestId: string,
+): TelegramBusEnvelope | undefined {
+  const messageValue = isRecord(value.message) ? value.message : undefined;
+  const target = parseThreadTarget(messageValue?.target);
+  if (
+    typeof value.instanceId !== "string" ||
+    !messageValue ||
+    !target ||
+    typeof messageValue.messageId !== "number" ||
+    !Number.isInteger(messageValue.messageId) ||
+    messageValue.messageId <= 0 ||
+    typeof messageValue.text !== "string" ||
+    !messageValue.text.trim() ||
+    typeof value.sentAtMs !== "number"
+  ) {
+    return undefined;
+  }
+  return {
+    kind: "follower.routeAgentMessage",
+    requestId,
+    instanceId: value.instanceId,
+    ...(typeof value.registrationGeneration === "string"
+      ? { registrationGeneration: value.registrationGeneration }
+      : {}),
+    message: {
+      target,
+      messageId: messageValue.messageId,
+      text: messageValue.text,
+    },
+    sentAtMs: value.sentAtMs,
+  };
+}
+
 function parseCallApiEnvelope(
   value: Record<string, unknown>,
   requestId: string,

package/lib/outbound-attachments.ts

@@ -9,6 +9,10 @@ import { basename } from "node:path";
 
 import { Type } from "@sinclair/typebox";
 
+import type {
+  TelegramBusAgentMessage,
+  TelegramBusAgentTargetSelector,
+} from "./bus.ts";
 import type { ExtensionAPI } from "./pi.ts";
 import {
   TELEGRAM_ATTACH_PROMPT_GUIDELINES,
@@ -84,6 +88,10 @@ export interface TelegramOutboundMessageToolRegistrationDeps extends TelegramOut
   getActiveTurn?: () =>
     | { chatId: number; target?: TelegramTarget }
     | undefined;
+  resolveAgentTarget?: (
+    selector: TelegramBusAgentTargetSelector,
+  ) => Promise<TelegramTarget & { threadId: number }>;
+  routeAgentMessage?: (message: TelegramBusAgentMessage) => Promise<void>;
   canSendDirect: () => boolean;
   planMessage: (markdown: string) => TelegramOutboundMessagePlan;
   sendMarkdownMessage: (
@@ -515,6 +523,12 @@ export function registerTelegramOutboundMessageTool(
           description: "Optional Telegram topic thread id with chat_id",
         }),
       ),
+      thread: Type.Optional(
+        Type.Union([Type.String(), Type.Number()], {
+          description:
+            "Optional live Pi thread name or numeric id for visible delivery plus a target-agent turn",
+        }),
+      ),
     }),
     async execute(_toolCallId, params) {
       try {
@@ -522,9 +536,12 @@ export function registerTelegramOutboundMessageTool(
           text: params.text,
           chatId: params.chat_id,
           threadId: params.thread_id,
+          agentThread: params.thread,
           getDefaultChatId: deps.getDefaultChatId,
           getDefaultTarget: deps.getDefaultTarget,
           getActiveTurn: deps.getActiveTurn,
+          resolveAgentTarget: deps.resolveAgentTarget,
+          routeAgentMessage: deps.routeAgentMessage,
           canSendDirect: deps.canSendDirect,
           planMessage: deps.planMessage,
           sendMarkdownMessage: deps.sendMarkdownMessage,
@@ -736,12 +753,17 @@ export async function sendTelegramOutboundMessage(options: {
   text: string;
   chatId?: number;
   threadId?: number;
+  agentThread?: string | number;
   target?: TelegramTarget;
   getDefaultChatId?: () => number | undefined;
   getDefaultTarget?: () => TelegramTarget | undefined;
   getActiveTurn?: () =>
     | { chatId: number; target?: TelegramTarget }
     | undefined;
+  resolveAgentTarget?: (
+    selector: TelegramBusAgentTargetSelector,
+  ) => Promise<TelegramTarget & { threadId: number }>;
+  routeAgentMessage?: (message: TelegramBusAgentMessage) => Promise<void>;
   canSendDirect: () => boolean;
   planMessage: (markdown: string) => TelegramOutboundMessagePlan;
   sendMarkdownMessage: (
@@ -754,17 +776,41 @@ export async function sendTelegramOutboundMessage(options: {
   details: { chatId: number; messageId?: number };
 }> {
   assertTelegramDirectDeliveryAllowed(options.canSendDirect);
+  const activeTurn = options.getActiveTurn?.();
+  const requestedAgentSelector: TelegramBusAgentTargetSelector | undefined =
+    options.agentThread !== undefined
+      ? typeof options.agentThread === "number"
+        ? { chatId: options.chatId, threadId: options.agentThread }
+        : { chatId: options.chatId, threadName: options.agentThread }
+      : activeTurn &&
+          options.resolveAgentTarget &&
+          options.routeAgentMessage &&
+          ((options.target?.threadId !== undefined) ||
+            (options.chatId !== undefined && options.threadId !== undefined))
+        ? {
+            chatId: options.target?.chatId ?? options.chatId,
+            threadId: options.target?.threadId ?? options.threadId,
+          }
+        : undefined;
+  let agentTarget: (TelegramTarget & { threadId: number }) | undefined;
+  if (requestedAgentSelector) {
+    if (!options.resolveAgentTarget || !options.routeAgentMessage) {
+      throw new Error("Telegram agent turn routing is unavailable.");
+    }
+    agentTarget = await options.resolveAgentTarget(requestedAgentSelector);
+  }
   const { chatId, target } = resolveTelegramOutboundTarget({
-    chatId: options.chatId,
-    threadId: options.threadId,
-    target: options.target,
+    chatId: agentTarget?.chatId ?? options.chatId,
+    threadId: agentTarget?.threadId ?? options.threadId,
+    target: agentTarget ?? options.target,
     getDefaultChatId: options.getDefaultChatId,
     getDefaultTarget: options.getDefaultTarget,
   });
-  const activeTurn = options.getActiveTurn?.();
   if (activeTurn) {
     const hasExplicitTarget =
-      options.chatId !== undefined || options.target !== undefined;
+      options.chatId !== undefined ||
+      options.target !== undefined ||
+      options.agentThread !== undefined;
     const activeTarget = activeTurn.target ?? { chatId: activeTurn.chatId };
     const requestedTarget = target ?? { chatId };
     const targetsMatch =
@@ -781,6 +827,18 @@ export async function sendTelegramOutboundMessage(options: {
     replyMarkup: plan.replyMarkup,
     target,
   });
+  if (agentTarget) {
+    if (messageId === undefined) {
+      throw new Error(
+        "Telegram message was sent but no message id was returned for agent routing.",
+      );
+    }
+    await options.routeAgentMessage!({
+      target: agentTarget,
+      messageId,
+      text: options.text,
+    });
+  }
   return {
     content: [
       {

package/lib/prompts.ts

@@ -29,9 +29,9 @@ export const TELEGRAM_MESSAGE_PROMPT_SNIPPET =
   "Send direct Telegram Markdown text when the user explicitly asks for Telegram delivery outside the normal reply flow.";
 export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
   "Use telegram_message only when the user explicitly asks to send a message to Telegram from the local/TUI side, or names a concrete Telegram delivery target.",
-  "For an explicit thread target, provide chat_id plus thread_id; registered multi-instance followers default to their assigned thread target.",
+  "For a live Pi thread target, provide thread as its case-insensitive name or numeric id; the bridge sends visibly and admits one attributed turn to that live instance. Unknown, ambiguous, same, or offline targets fail before sending.",
   "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
-  "During an active Telegram turn, omit telegram_message for the current target and answer normally; use it only with an explicit different chat_id/thread_id when the user requests cross-target delivery.",
+  "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread.",
 ] as const;
 
 const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([

package/lib/sync.ts

@@ -167,6 +167,7 @@ export function createTelegramManualThreadDisconnectHandler<
 >(deps: TelegramManualThreadDisconnectDeps<TSyncState>): () => Promise<string> {
   return async () => {
     const currentRecord = deps.getCurrentThreadRecord();
+    let cleanupPending = false;
     if (currentRecord?.target.threadId) {
       const isManualFollower = currentRecord.owner?.kind === "manual-follower";
       const leaderEpoch = deps.getCurrentLeaderEpoch?.();
@@ -228,11 +229,7 @@ export function createTelegramManualThreadDisconnectHandler<
             recordRuntimeEvent: deps.recordRuntimeEvent,
           },
         );
-        if (cleanup.incompleteActions?.length) {
-          throw new Error(
-            "Telegram thread deletion was not confirmed; inspect /telegram-status --debug and retry /telegram-disconnect.",
-          );
-        }
+        cleanupPending = Boolean(cleanup.incompleteActions?.length);
       }
       const leaderTarget = deps.getLeaderTarget();
       if (
@@ -248,7 +245,10 @@ export function createTelegramManualThreadDisconnectHandler<
         }) as TSyncState,
       );
     }
-    return deps.stopPolling();
+    const stopped = await deps.stopPolling();
+    return cleanupPending
+      ? `${stopped} Telegram thread cleanup remains pending for the next leader.`
+      : stopped;
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.27.3",
+  "version": "0.27.5",
   "private": false,
   "publishConfig": {
     "access": "public"