@llblab/pi-telegram 0.16.4 → 0.16.6

package/AGENTS.md

@@ -7,12 +7,15 @@
 - `Boundary Clarity`: Separate Telegram transport concerns, π integration concerns, rendering behavior, and release/documentation state
 - `Progressive Enhancement + Graceful Degradation`: Prefer behavior that upgrades automatically when richer runtime context exists, but always preserves a useful fallback path when it does not
 - `Runtime Safety`: Prefer queue and rendering behavior that fails predictably over clever behavior that can desynchronize the Telegram bridge from π session state
+- `Mobile Companion Boundary`: `pi-telegram` extends a live Pi session for phone use; it is not a remote terminal, PTY supervisor, or process launcher. Do not add terminal-control tricks to make Telegram pretend to be the TUI.
 - `Pi-Native Extensibility`: `pi-telegram` should inherit π's own extension philosophy. It is not only a Telegram adapter; it should become a small, convenient, composable Telegram shell for π extensions, where new capabilities plug into stable contracts instead of forking polling, transport, or menu ownership.
 
 ## 1. Concept
 
 `pi-telegram` is a Telegram runtime adapter for π: a session-local operator console that turns a private Telegram DM into a runtime surface for prompt intake, streaming previews, queue management, model/thinking/settings controls, inbound/outbound handler pipelines, voice/buttons, artifacts, and extension callback interop. Treat it as a Telegram membrane around π, not a narrow message pipe.
 
+The core product loop is mobile continuation: start or supervise work in the terminal, then continue from Telegram while away from the keyboard. Telegram controls should be a safe extension-facing subset of the live session, not a replacement for Pi's interactive TUI.
+
 ## 2. Identity & Naming Contract
 
 - `Telegram turn`: One unit of Telegram input processed by π; this may represent one message or a coalesced media group
@@ -67,6 +70,7 @@
 - Command/menu emoji are fixed UI adornments owned by the `commands` map; do not add a persisted emoji toggle or Settings menu until there is a real setting to own
 - Telegram `reply_to_message` context is prompt-only and must not affect slash-command parsing
 - Long-lived timers, pollers, watchers, and deferred queue dispatch must be session-bound and avoid stale live π contexts after session replacement
+- Do not add Telegram commands that imitate Pi interactive session replacement, navigation, or TUI rendering through private internals, ANSI terminal clearing, raw TTY injection, or a shadow `pi` subprocess. Features such as a real Telegram `/new` require a public Pi API that runs the same session-replacement path as the terminal command.
 - In-flight `/model` switching is limited to Telegram-owned active turns; if a tool call is active, abort is delayed until the tool finishes
 
 ## 5.3 Telegram Delivery Semantics
@@ -75,6 +79,7 @@
 - Real code blocks must stay literal and escaped
 - `telegram_attach` is the canonical outbound file-delivery path for Telegram-originated requests; outside active Telegram turns it may send immediately to the paired/default chat for explicit local/TUI delivery requests only when this π instance owns `/telegram-connect`. `telegram_message` is the first-class direct Telegram Markdown text tool for local/TUI prompts and is also gated by `/telegram-connect`; neither direct tool replaces normal active-turn replies. It reuses top-level `telegram_button` comments for inline buttons; buttons must be attached to a text message, never sent as standalone actions
 - Telegram delivery strips top-level HTML comments from preview/final text; column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks are special outbound comments handled after `agent_end` without requiring agent-side transport tool calls, while comments inside code, quotes, lists, or indented examples stay literal
+- Telegram prompt guidance is layered: unconfigured sessions receive no bridge suffix, local/TUI prompts receive only explicit direct-delivery guidance, and Telegram-originated turns receive the full inbound/phone-width/output-action contract
 - `telegram_voice` and `telegram_button` are not π tools; keep prompts/docs explicit that agents should author markup while voice synthesis provider extensions own TTS/OGG conversion, and pi-telegram owns button routing plus Telegram delivery
 - Voice reply policy and prompt context are owned by pi-telegram's `telegram.json` `voice.replyMode`: missing/invalid config behaves as `manual` but does not add a `[voice]` prompt-context block; only an explicit valid `voice.replyMode` renders context. Render a single voice field as `[voice] reply mode: manual|mirror|always`, and render multiple fields as a `[voice]` list; place voice context after `[outputs]` when handler output exists, otherwise after `[attachments]`; provider prompt contributions are optional provider-specific additions, not the default policy channel
 - Optional `telegram.json` `time` may add `[time] YYYY-MM-DD HH:mm:ss <timezone>` to Telegram-originated prompts for wall-clock context. It is hidden by default, uses `time.injectionMode` values `hidden|always|interval`, stores `time.interval` in milliseconds, uses the system timezone, and should render last after `[attachments]`, `[outputs]`, and `[voice]` sections. The Settings row `🕒 Time injection: hidden|always|interval` controls `time.injectionMode` only.

package/BACKLOG.md

@@ -1,3 +1,8 @@
 # Project Backlog
 
-No open work.
+- [ ] Track a public Pi session-replacement hook before adding Telegram `/new`.
+  - Context: `pi-telegram` is an extension/mobile companion, not a PTY supervisor. A soft `/new` that mutates session internals or filters context without TUI/runtime parity breaks the product boundary.
+  - Requirement: only add Telegram `/new` when Pi exposes a safe public API that invokes the same session-replacement path as terminal `/new`, including lifecycle, active-run handling, and TUI rerender semantics.
+  - Rejected for this extension: raw TTY injection, ANSI terminal clearing, private TUI container mutation, or running a shadow `pi` subprocess to control the current session.
+
+- [ ] Consider splitting `lib/bindings.ts` if lifecycle/tool wiring grows further.

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## Unreleased
+
+## 0.16.6: Telegram Review Hardening Hotfix
+
+- `[Guest Mode]` Deny `guest_message` updates until the bridge already has a paired Telegram user. Impact: guest mode can no longer become the first pairing surface or trigger guest file/handler processing before explicit DM pairing.
+- `[Lifecycle]` Unref the compaction observer fallback timer when the host timer supports it. Impact: headless or shutdown paths are less likely to linger until the 5-minute safety timeout.
+- `[Shutdown]` Stop polling before clearing active-turn/abort state, keep the abort controller visible until the polling promise settles, and record typing-cleanup failures without skipping polling abort. Impact: session shutdown and polling cleanup ordering is more deterministic.
+- `[Replies]` Scope transport-level reply deduplication by chat id. Impact: equal Telegram message ids in different chats no longer suppress valid reply metadata for each other.
+- `[Buttons]` Consume one-shot `telegram_button` callback actions after the first successful resolve. Impact: repeated taps on an old assistant-authored button no longer enqueue duplicate prompts.
+- `[Buttons]` Centralized Telegram `callback_data` byte-limit guards for generated inline keyboards outside the section helper path. Impact: oversized generated button callbacks fail locally before Telegram rejects the message.
+- `[Diagnostics]` Record `answerCallbackQuery` transport failures in runtime API diagnostics while keeping callback handling non-fatal. Impact: `/telegram-status` can explain failed Telegram callback acknowledgements instead of losing the signal silently.
+- `[Tests]` Added regressions for shutdown during pending control, long-text, and media-group dispatch, for settings menu callbacks persisting voice/time changes to `telegram.json`, for malformed/boundary Markdown rendering, and for runtime outbound delivery retrying a transient Telegram API failure. Impact: high-risk queue/timer/settings/rendering/API paths are pinned at the bridge boundary.
+- `[Docs]` Documented which environment-driven transport defaults should be set before launch because module-load constants intentionally capture them.
+- `[Backlog]` Captured and narrowed the non-blocking 2026-06 review-swarm follow-ups for lifecycle shutdown hardening, reply/callback/button state cleanup, validation coverage, and bindings maintainability.
+
+## 0.16.5: Context-Aware Prompt Guidance Hotfix
+
+- `[Prompt Guidance]` Made before-agent-start Telegram guidance context-aware: unconfigured sessions receive no bridge suffix, local/TUI prompts receive only explicit direct-delivery guidance, and Telegram-originated turns keep the full inbound, phone-width, voice, and button contract. Impact: ordinary local replies no longer get raw Telegram action-comment syntax unless the current turn actually comes from Telegram.
+- `[Docs]` Recorded the product boundary that `pi-telegram` is a mobile companion for a live Pi session, not a remote terminal, PTY supervisor, or process launcher. Telegram controls should stay within Pi's extension-facing APIs; true session replacement such as Telegram `/new` should wait for a public Pi hook that preserves interactive runtime and TUI semantics.
+
 ## 0.16.4: Follow-Up And Runtime Mode Hotfix
 
 - `[Runtime]` Feature-detect Pi `ctx.mode` and keep `print`/`json` runs passive by blocking polling start/resume in those modes. Impact: CLI/headless sessions can finish local work without inheriting Telegram polling, while `tui`/`rpc` and older Pi runtimes keep existing behavior.
@@ -23,7 +43,7 @@
 
 ## 0.16.0: Telegram Extension Commands
 
-- `[API]` Added `registerTelegramCommand()` on the public `/commands` subpath so companion extensions can explicitly provide Telegram-native slash commands without adding workflow-specific commands to core. Built-in bridge commands stay reserved, extension command names must be Bot API safe, duplicate extension names are rejected, commands stay hidden unless `showInMenu` is enabled, visible commands must provide an emoji used in `/start` help and Bot API descriptions, extension-command descriptions are shown in `/start`, visible extension commands are inserted after `/compact` before queue-control commands, prompt-template commands remain separated in `/start`, handler failures are isolated with runtime diagnostics, and routing precedence is built-ins → extension commands → prompt-template aliases. Impact: commands such as fresh-session controls can live in companion extensions while `pi-telegram` remains a lightweight Telegram shell.
+- `[API]` Added `registerTelegramCommand()` on the public `/commands` subpath so companion extensions can explicitly provide Telegram-native slash commands without adding workflow-specific commands to core. Built-in bridge commands stay reserved, extension command names must be Bot API safe, duplicate extension names are rejected, commands stay hidden unless `showInMenu` is enabled, visible commands must provide an emoji used in `/start` help and Bot API descriptions, extension-command descriptions are shown in `/start`, visible extension commands are inserted after `/compact` before queue-control commands, prompt-template commands remain separated in `/start`, handler failures are isolated with runtime diagnostics, and routing precedence is built-ins → extension commands → prompt-template aliases. Impact: workflow-specific controls can live in companion extensions while `pi-telegram` remains a lightweight Telegram shell.
 
 ## 0.15.1: Typing Keepalive Cadence
 

package/README.md

@@ -6,6 +6,8 @@
 
 `pi-telegram` turns a private Telegram DM into a session-local operator console for π. It admits work, preserves context, streams readable replies, keeps busy sessions usable through queues, lets other extensions share one bot, and turns assistant-authored intent into native Telegram artifacts. It is also a voice-provider platform: companion extensions can supply Telegram transcription and synthesis providers while `pi-telegram` keeps ownership of transport, queueing, and reply policy.
 
+The product shape is a mobile companion for a live Pi session: start work in the terminal, then continue from Telegram on the couch or outside. It is not a remote terminal, PTY supervisor, or process launcher, and it intentionally avoids pretending to own Pi's interactive TUI.
+
 This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
 
 ## Install
@@ -47,7 +49,7 @@ Paste your bot token when prompted. If a bot token is already saved in `~/.pi/ag
 /telegram-connect
 ```
 
-The adapter is session-local: only one π instance polls Telegram at a time. `/telegram-connect` records only external control/polling ownership in `~/.pi/agent/locks.json`; live ownership moves require confirmation, inherited child sessions do not start polling unless they take ownership, and `/new` plus same-`cwd` restarts resume automatically. Local queue and reply state stay per Pi instance, so an instance that loses Telegram control still finishes work it already accepted.
+The adapter is session-local: only one π instance polls Telegram at a time. `/telegram-connect` records only external control/polling ownership in `~/.pi/agent/locks.json`; live ownership moves require confirmation, inherited child sessions do not start polling unless they take ownership, and same-`cwd` restarts resume automatically. Local queue and reply state stay per Pi instance, so an instance that loses Telegram control still finishes work it already accepted.
 
 ### 4. Pair your Telegram account
 
@@ -66,12 +68,15 @@ Most day-to-day controls live in the Telegram menu or π commands. A few importa
 - **Inbound file limit**: `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES` or `TELEGRAM_MAX_FILE_SIZE_BYTES` changes the default 50 MiB Telegram download limit.
 - **Outbound attachment limit**: `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES` changes the default 50 MiB `telegram_attach` delivery limit.
 
+Set these variables before launching π. Some transport defaults (notably Telegram temp directory and inbound/outbound byte-limit constants) are intentionally captured when the extension modules load, while setup-token defaults and agent-dir lookups used by config/locks are read through their runtime helpers.
+
 ## Use
 
 Once paired, chat with your bot in Telegram. Text, images, files, replies, edits, media groups, and configured handler output are forwarded into π as Telegram-originated turns.
 
 What it feels like:
 
+- Start work in the terminal, walk away, and keep supervising the same live π session from Telegram.
 - Open `/start` and get a Telegram control panel for the running π session: status, prompt templates, model, thinking, settings, and queue.
 - Fire off three tasks while π is busy. They become visible queue items instead of terminal noise.
 - Open Queue from the menu, inspect waiting work, delete stale prompts, or move important work forward.
@@ -82,7 +87,7 @@ What it feels like:
 
 ### Telegram controls
 
-Use these inside the Telegram DM with your bot. The main entrypoint is `/start`: it opens the operator menu and exposes many of the important agent controls that normally live in the CLI, adapted for Telegram.
+Use these inside the Telegram DM with your bot. The main entrypoint is `/start`: it opens the operator menu and exposes many of the important agent controls that can be safely adapted through Pi's extension APIs. The bot does not forward arbitrary terminal slash commands or emulate TUI-only session controls.
 
 - **`/start`**: Pair the first Telegram user when needed, register bot commands, and open the inline application menu with command help, prompt-template commands, status rows, model controls, thinking controls, settings, and queue controls.
 - **`/compact`**: Ask for inline confirmation, then start session compaction when the session is idle; Telegram shows the native typing indicator while manual or automatic compaction is running.
@@ -170,6 +175,8 @@ A practical voice setup is simple: Telegram `.ogg` arrives, STT runs locally or
 
 Assistant replies can include hidden outbound blocks. `telegram_voice` and `telegram_button` are not π tools; they are assistant-authored HTML comments that the adapter removes from Telegram text and handles after `agent_end`. Recognized blocks must start at column zero on a top-level line outside fenced code, quotes, lists, and indented examples. Do not use JSON button specs, inline comments after visible text, or standalone button tool calls; write normal Markdown plus hidden comments, and add visible parent text if buttons would otherwise be the only output.
 
+Prompt guidance is context-aware: unconfigured sessions receive no Telegram suffix, local/TUI prompts only get explicit direct-delivery guidance, and Telegram-originated turns get the full phone-width output and action-comment contract.
+
 ```md
 Full technical answer stays readable as text.
 
@@ -209,7 +216,7 @@ Unknown inline-button callbacks are forwarded to π as `[callback] <data>` when
 
 ### Extension Sections
 
-Ordinary pi extensions can register Telegram-native slash commands, structured UI sections, and compact status lines without owning a second polling loop. Slash commands use explicit opt-in registration from `@llblab/pi-telegram/commands`, so workflow-specific commands such as a fresh-session control can live in companion extensions instead of expanding the core bridge command set. UI sections appear in the main Telegram menu and Settings submenu, while status lines allow widgets such as quota indicators to appear beside Status, Usage, Cost, and Context only when relevant to the active model. Each section gets a narrow typed context with `edit`, `open`, `enqueuePrompt`, `answerCallback`, and `callbackData()` — enough to build interactive Telegram-native surfaces while `pi-telegram` owns transport, callback routing, navigation hierarchy, and diagnostics.
+Ordinary pi extensions can register Telegram-native slash commands, structured UI sections, and compact status lines without owning a second polling loop. Slash commands use explicit opt-in registration from `@llblab/pi-telegram/commands`, so workflow-specific commands can live in companion extensions instead of expanding the core bridge command set. UI sections appear in the main Telegram menu and Settings submenu, while status lines allow widgets such as quota indicators to appear beside Status, Usage, Cost, and Context only when relevant to the active model. Each section gets a narrow typed context with `edit`, `open`, `enqueuePrompt`, `answerCallback`, and `callbackData()` — enough to build interactive Telegram-native surfaces while `pi-telegram` owns transport, callback routing, navigation hierarchy, and diagnostics.
 
 Import `registerTelegramSection()` from `@llblab/pi-telegram/sections` and return a disposer on shutdown. Sections can send interactive messages directly into the chat via `ctx.open()` — confirmation dialogs, approve/deny gates, and multi-step forms live outside the menu hierarchy while callbacks route through the same typed handler. See [`@llblab/pi-telegram-extension-demo`](https://github.com/llblab/pi-telegram-extension-demo) for a working reference and the [Extension Sections Standard](./docs/sections.md) for the full contract.
 

package/docs/architecture.md

@@ -9,6 +9,8 @@
 - Stream previews and deliver final π responses back to Telegram.
 - Provide Telegram-native controls for queueing, model/thinking/settings menus, compaction, abort/stop, prompt templates, reactions, and outbound artifacts.
 
+The bridge is a mobile companion for a live Pi session, not a remote terminal. It should let an operator start work in the TUI and continue supervising from Telegram, while staying inside Pi's extension-facing contracts.
+
 This document is the architectural map. Focused behavior standards live in sibling docs:
 
 - [Public API](./public-api.md) — stable commands, config, package entrypoints, assistant markup, extension APIs, and compatibility boundaries.
@@ -23,6 +25,17 @@ This document is the architectural map. Focused behavior standards live in sibli
 
 `index.ts` is the only composition root. It wires live π ports, Telegram Bot API ports, session-local stores, lifecycle hooks, and domain runtimes. Reusable logic lives in flat `/lib/*.ts` domain modules rather than a deep local module tree.
 
+### Extension Boundary Vs Supervisor Control
+
+`pi-telegram` runs inside the current Pi process as an extension. That gives it safe access to public extension APIs such as aborting work, compacting, sending follow-up prompts, observing lifecycle events, and rendering Telegram-native controls. It does not own the terminal, the interactive-mode chat transcript, or the process lifecycle.
+
+Keep this boundary explicit:
+
+- Do not use raw TTY injection, ANSI terminal clearing, private TUI container mutation, or a shadow `pi` subprocess to simulate interactive commands.
+- Do not treat Telegram as a generic remote shell for every Pi slash command.
+- Commands that require interactive session replacement or TUI rerendering, such as a true Telegram `/new`, need a public Pi API that invokes the same runtime path as the terminal command.
+- A separate PTY supervisor or daemon could choose to own those risks, but that would be a different product mode rather than this extension's runtime contract.
+
 The repository uses a **Flat Domain DAG**:
 
 - Local imports must form a directed acyclic graph.
@@ -104,7 +117,7 @@ Deleting `locks.json` resets runtime ownership without deleting Telegram configu
 
 1. Poll updates through `getUpdates`.
 2. Persist update offsets only after successful handling; repeated handler failures are bounded.
-3. Filter to the paired private user.
+3. Filter to the paired private user; guest-mode updates require an existing paired user and cannot establish first pairing.
 4. Dispatch owned callbacks and controls before fallback prompt forwarding.
 5. Coalesce media groups and likely split long text when needed.
 6. Download files into `~/.pi/agent/tmp/telegram` with size limits and partial-download cleanup.
@@ -230,7 +243,7 @@ Queue reactions are shortcut controls for waiting turns. Promotion reactions (`
 
 When proactive push is enabled and this instance owns the Telegram lock, successful local non-Telegram final replies are sent to the paired chat. Non-owners skip proactive delivery and record a runtime diagnostic. Local prompt text is not mirrored because the bot does not own terminal user messages.
 
-Telegram prompt guidance asks assistants to keep dense mobile-visible text around 37 display cells where possible, because emoji and wide Unicode make raw character counts misleading.
+Telegram prompt guidance is context-aware. Unconfigured sessions receive no bridge suffix. Local/TUI prompts receive only explicit direct-delivery guidance so ordinary terminal replies do not learn raw Telegram action-comment syntax. Telegram-originated turns receive the full inbound context, phone-width output, and native action contract, including the 37-display-cell mobile readability hint.
 
 ## In-Flight Model Switching
 

package/docs/outbound.md

@@ -132,12 +132,14 @@ Buttons are built in and do not need a command template because they are pure Te
 
 ## Prompt Contract
 
-The extension injects Telegram-specific system prompt guidance so agents know the fast path:
+The extension injects prompt guidance by context:
 
-- Write the full technical answer as normal Markdown.
+- If no bot token is configured, no Telegram bridge suffix is injected.
+- For ordinary local/TUI prompts, the agent only sees explicit direct-delivery guidance: use `telegram_attach` or `telegram_message` when the user asks to send something to Telegram, and otherwise answer locally as normal.
+- For Telegram-originated turns, write the full technical answer as normal Markdown.
 - Add `telegram_voice` when a Telegram-native voice message is useful; use body text, `text="..."`, or colon shorthand for the text to synthesize. A companion summary is optional, no specific summary format is required.
 - Add `telegram_button: ...` when label equals prompt, `telegram_button label="..." prompt="..."` for one-line prompts, or `telegram_button label="..."` with a body for multiline prompts. If the reply contains only button/voice comment blocks, add a short visible marker (for example `Choose one:`) before them so Telegram always has a visible parent message for attachment.
 - For ordinary Telegram-turn replies, do not call transport tools for voice or buttons; the bridge owns delivery, while registered voice synthesis providers own TTS and OGG/Opus conversion. For explicit local/TUI direct sends, `telegram_message` may include top-level `telegram_button` comments in its Markdown text because those buttons are attached to that text message.
 - Never send buttons without visible parent text. If the answer would contain only hidden comments, add a compact line such as `Choose one:` first.
 
-This keeps the agent focused on semantics and lets the bridge handle low-latency Telegram adaptation.
+This keeps the agent focused on semantics, prevents Telegram action syntax from leaking into normal local replies, and lets the bridge handle low-latency Telegram adaptation.

package/docs/public-api.md

@@ -53,6 +53,8 @@ Stable commands inside the paired Telegram DM:
 
 Hidden compatibility shortcuts may open sections directly: `/help`, `/status`, `/model`, `/thinking`, `/queue`, and `/settings`.
 
+This command surface is a mobile companion subset, not a raw terminal-command bridge. Commands that depend on Pi's interactive runtime owning session replacement, TUI transcript clearing, or arbitrary slash-command dispatch stay out of the stable Telegram API unless Pi exposes a safe public extension hook for them.
+
 ### Tools and assistant-authored actions
 
 - `telegram_attach(paths, chat_id?, caption?)` is the stable artifact delivery tool for generated files. During Telegram turns it queues files for the active reply; outside Telegram turns it sends files directly to the paired/default chat or explicit `chat_id` when this π instance owns `/telegram-connect`.
@@ -60,6 +62,8 @@ Hidden compatibility shortcuts may open sections directly: `/help`, `/status`, `
 - `telegram_voice` hidden comments request Telegram-native voice delivery.
 - `telegram_button` hidden comments create inline buttons whose taps enqueue prompts. Use top-level column-zero comments outside code, quotes, lists, and indented examples; do not emit JSON button specs or standalone button actions.
 
+Prompt guidance is context-aware: local/TUI prompts see only explicit direct-delivery guidance, while Telegram-originated turns receive the full action-comment syntax and phone-width output contract.
+
 See [Outbound Handlers](./outbound.md) for exact markup forms.
 
 ## Configuration API
@@ -143,12 +147,12 @@ Import from `@llblab/pi-telegram/commands`. This registers Telegram slash comman
 
 ```ts
 const off = registerTelegramCommand({
-  name: "new",
-  description: "Start fresh",
+  name: "review",
+  description: "Review queued work",
   showInMenu: true,
-  emoji: "🆕",
+  emoji: "🧩",
   handler: async (ctx) => {
-    await ctx.reply("Starting a fresh session is handled by my extension.");
+    await ctx.enqueuePrompt(`Review this work: ${ctx.args}`);
   },
 });
 ```

package/lib/bindings.ts

@@ -113,7 +113,10 @@ interface TelegramLifecycleBindingDeps {
     Lifecycle.TelegramLifecycleRegistrationDeps,
     "onSessionStart" | "onSessionShutdown" | "onModelSelect"
   >;
-  configStore: Pick<Config.TelegramConfigStore, "getOutboundHandlers">;
+  configStore: Pick<
+    Config.TelegramConfigStore,
+    "getOutboundHandlers" | "hasBotToken"
+  >;
   abort: Runtime.TelegramRuntimeAbortPort;
   typing: Runtime.TelegramRuntimeTypingPort;
   lifecycle: Runtime.TelegramRuntimeLifecyclePort;
@@ -317,6 +320,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     onSessionCompact: compactionObserver.onSessionCompact,
     onAgentStart: agentStartWithDedupReset,
     onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({
+      isConfigured: configStore.hasBotToken,
       isProactivePushEnabled,
       isCurrentOwner: lockOwnershipGuard.ownsContext,
     }),

package/lib/keyboard.ts

@@ -12,3 +12,42 @@ export interface TelegramInlineKeyboardButton {
 export interface TelegramInlineKeyboardMarkup {
   inline_keyboard: TelegramInlineKeyboardButton[][];
 }
+
+export const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
+
+export function getTelegramCallbackDataByteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+export function assertTelegramCallbackData(
+  callbackData: string,
+  context = "Telegram callback_data",
+): string {
+  const byteLength = getTelegramCallbackDataByteLength(callbackData);
+  if (byteLength > TELEGRAM_CALLBACK_DATA_MAX_BYTES) {
+    throw new Error(
+      `${context} exceeds ${TELEGRAM_CALLBACK_DATA_MAX_BYTES} bytes (${byteLength}). Use a shorter action/payload or store state behind a compact key.`,
+    );
+  }
+  return callbackData;
+}
+
+export function assertTelegramInlineKeyboardCallbackData(
+  replyMarkup: unknown,
+  context = "Telegram inline keyboard callback_data",
+): void {
+  if (!replyMarkup || typeof replyMarkup !== "object") return;
+  const keyboard = (replyMarkup as { inline_keyboard?: unknown })
+    .inline_keyboard;
+  if (!Array.isArray(keyboard)) return;
+  for (const row of keyboard) {
+    if (!Array.isArray(row)) continue;
+    for (const button of row) {
+      if (!button || typeof button !== "object") continue;
+      const callbackData = (button as { callback_data?: unknown })
+        .callback_data;
+      if (typeof callbackData !== "string") continue;
+      assertTelegramCallbackData(callbackData, context);
+    }
+  }
+}

package/lib/lifecycle.ts

@@ -138,6 +138,11 @@ export function createTelegramSessionContextTracker(
 
 type TelegramLifecycleTimer = number | ReturnType<typeof setTimeout>;
 
+function unrefTelegramLifecycleTimer(timer: TelegramLifecycleTimer): void {
+  if (!timer || typeof timer !== "object") return;
+  if (typeof timer.unref === "function") timer.unref();
+}
+
 export interface TelegramCompactionObserverRuntimeDeps<TContext> {
   setCompactionInProgress: (inProgress: boolean) => void;
   updateStatus: (ctx: TContext) => void;
@@ -196,6 +201,7 @@ export function createTelegramCompactionObserverRuntime<TContext>(
         );
         requestDispatch();
       }, timeoutMs);
+      unrefTelegramLifecycleTimer(fallbackTimer);
     },
     onSessionCompact: (_event, ctx) => {
       clearFallbackTimer();

package/lib/outbound-attachments.ts

@@ -474,6 +474,7 @@ export async function sendQueuedTelegramOutboundAttachments(
       const method = isPhoto ? "sendPhoto" : "sendDocument";
       const fieldName = isPhoto ? "photo" : "document";
       const replyParameters = buildTelegramMultipartReplyParameters(
+        turn.chatId,
         turn.replyToMessageId,
       );
       await deps.sendMultipart(

package/lib/outbound-buttons.ts

@@ -135,6 +135,7 @@ export function createTelegramButtonActionStore(
       cleanup(currentTime);
       const action = actions.get(callbackData);
       if (!action) return undefined;
+      actions.delete(callbackData);
       return { text: action.text, prompt: action.prompt };
     },
   };

package/lib/outbound-voice.ts

@@ -7,6 +7,7 @@
 import { unlink } from "node:fs/promises";
 import { basename, extname } from "node:path";
 
+import { assertTelegramInlineKeyboardCallbackData } from "./keyboard.ts";
 import { getTelegramVoiceSynthesisProviders } from "./voice.ts";
 
 export interface TelegramVoiceReplyTurnView {
@@ -125,6 +126,7 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
     },
   ): Promise<void> {
     const voiceFilePath = await ensureTelegramVoiceFileFormat(filePath);
+    assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
     await sendVoiceChatAction(deps, turn.chatId);
     const replyParameters = buildVoiceReplyParameters(
       options?.replyToPrompt,

package/lib/polling.ts

@@ -187,11 +187,21 @@ export function shouldStartTelegramPolling(
 export async function stopTelegramPollingRuntime<TContext>(
   deps: TelegramPollingRuntimeDeps<TContext>,
 ): Promise<void> {
-  deps.stopTypingLoop();
-  deps.getPollingController()?.abort();
-  deps.setPollingController(undefined);
-  await deps.getPollingPromise()?.catch(() => undefined);
-  deps.setPollingPromise(undefined);
+  const pollingPromise = deps.getPollingPromise();
+  const pollingController = deps.getPollingController();
+  try {
+    deps.stopTypingLoop();
+  } catch (error) {
+    deps.recordRuntimeEvent?.("polling", error, { phase: "typing-stop" });
+  }
+  pollingController?.abort();
+  await pollingPromise?.catch(() => undefined);
+  if (deps.getPollingPromise() === pollingPromise) {
+    deps.setPollingPromise(undefined);
+  }
+  if (deps.getPollingController() === pollingController) {
+    deps.setPollingController(undefined);
+  }
 }
 
 function updateTelegramPollingStatusSafely<TContext>(
@@ -224,9 +234,12 @@ export function startTelegramPollingRuntime<TContext>(
   }
   const controller = deps.createAbortController?.() ?? new AbortController();
   deps.setPollingController(controller);
-  const promise = deps.runPollLoop(ctx, controller.signal).finally(() => {
-    deps.setPollingPromise(undefined);
-    deps.setPollingController(undefined);
+  let promise: Promise<void>;
+  promise = deps.runPollLoop(ctx, controller.signal).finally(() => {
+    if (deps.getPollingPromise() === promise) deps.setPollingPromise(undefined);
+    if (deps.getPollingController() === controller) {
+      deps.setPollingController(undefined);
+    }
     updateTelegramPollingStatusSafely(deps.updateStatus, ctx, {
       recordRuntimeEvent: deps.recordRuntimeEvent,
     });

package/lib/preview.ts

@@ -241,6 +241,7 @@ export interface TelegramPreviewMessageTransportDeps {
   sendMessage: (body: TelegramSendMessageBody) => Promise<TelegramSentMessage>;
   editMessageText: (body: TelegramEditMessageTextBody) => Promise<unknown>;
   buildReplyParameters?: (
+    chatId: number,
     replyToMessageId: number | undefined,
   ) => TelegramReplyParameters | undefined;
 }
@@ -252,7 +253,7 @@ export function createTelegramPreviewMessageTransport(
     deps.buildReplyParameters ?? buildTelegramReplyParameters;
   return {
     sendMessage: (chatId, text, options, replyToMessageId) => {
-      const replyParameters = getReplyParameters(replyToMessageId);
+      const replyParameters = getReplyParameters(chatId, replyToMessageId);
       return deps.sendMessage({
         chat_id: chatId,
         text,

package/lib/prompts.ts

@@ -7,11 +7,19 @@
 import type { BeforeAgentStartEvent } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
-const SYSTEM_PROMPT_SUFFIX = `
+const LOCAL_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram bridge extension is active.
+Telegram bridge extension is available.
 
-Inbound context:
+Local/TUI Telegram delivery:
+- Answer ordinary local prompts normally; do not add Telegram action comments unless the user explicitly asks for Telegram delivery.
+- For explicit Telegram file delivery, call \`telegram_attach(local_path)\`. For explicit Telegram text delivery, call \`telegram_message(...)\`.
+- Direct local/TUI Telegram delivery requires this π instance to own \`/telegram-connect\`; if ownership is elsewhere, connect/take over first instead of bypassing the lock.
+`;
+
+const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
+
+Telegram-originated turn context:
 - \`[telegram]\` marks Telegram-originated messages. Suffixes \`|from:user\` (sender) and \`|guest:group\` (guest mode — message from another chat where the bot is not a member) may be present; the bot sees the message as if forwarded from that user/chat.
 - \`[reply]\` is quoted context from the replied-to message, not a new instruction by itself. Suffix \`|from:user\` identifies the original author in guest-mode replies. Use it to resolve references like "this", "it", or "that message"; the actual instruction is before [reply] unless it explicitly asks to act on the quote.
 - \`[attachments]\` gives a base directory plus relative local files; resolve and read them as needed. \`[outputs]\` contains inbound-handler stdout such as transcriptions or extracted text for those attachments.
@@ -27,7 +35,7 @@ Telegram-visible output:
 
 Native outbound actions:
 - Use normal Markdown for visible text. Use top-level column-zero hidden Markdown comments outside code, quotes, and lists only for native actions; the bridge strips them after agent_end and turns them into Telegram-native artifacts/reply_markup. Do not render button JSON, do not invent standalone button tools, and do not call/register transport/TTS/text-to-OGG tools for ordinary Telegram-turn voice/buttons.
-- \`telegram_voice\`: text is synthesized by the registered voice synthesis provider and delivered by pi-telegram. Use body text for multiline voice, \`<!-- telegram_voice text="Short summary" -->\` for explicit one-line voice, or \`<!-- telegram_voice: Short summary -->\` for one-line voice with no attributes. A companion summary is optional, no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
+- \`telegram_voice\`: text is synthesized by the registered voice synthesis provider and delivered by pi-telegram. Use body text for multiline voice, \`<!-- telegram_voice text="Short summary" -->\` for explicit one-line text, or \`<!-- telegram_voice: Short summary -->\` for one-line text with no attributes. A companion summary is optional, no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
 - \`telegram_button\`: callback prompt is routed back as a normal Telegram turn. Use \`<!-- telegram_button: OK -->\` when prompt equals label, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\` for one-line prompts, or body form \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\` for multiline prompts. Do not put button comments inline after visible text, inside code fences, block quotes, lists, or indented examples; those are literal Markdown, not buttons.
 - If only hidden action comments would remain, add visible parent text like "Choose one:" so Telegram has a message to attach buttons to.
 `;
@@ -36,19 +44,25 @@ export function buildTelegramBridgeSystemPrompt(options: {
   prompt: string;
   systemPrompt: string;
   telegramPrefix?: string;
-  systemPromptSuffix: string;
+  localSystemPromptSuffix: string;
+  telegramTurnSystemPromptSuffix: string;
 }): { systemPrompt: string } {
   const telegramPrefix = options.telegramPrefix ?? TELEGRAM_PREFIX;
-  const suffix = options.prompt.trimStart().startsWith(telegramPrefix)
-    ? `${options.systemPromptSuffix}\n- The current user message came from Telegram.`
-    : options.systemPromptSuffix;
-  return { systemPrompt: options.systemPrompt + suffix };
+  const telegramTurn = options.prompt.trimStart().startsWith(telegramPrefix);
+  const telegramSuffix = telegramTurn
+    ? `${options.telegramTurnSystemPromptSuffix}\n- The current user message came from Telegram.`
+    : "";
+  return {
+    systemPrompt:
+      options.systemPrompt + options.localSystemPromptSuffix + telegramSuffix,
+  };
 }
 
 export function createTelegramBeforeAgentStartHook(
   options: {
     telegramPrefix?: string;
-    systemPromptSuffix?: string;
+    localSystemPromptSuffix?: string;
+    telegramTurnSystemPromptSuffix?: string;
   } = {},
 ): (event: BeforeAgentStartEvent) => { systemPrompt: string } {
   return (event) =>
@@ -56,12 +70,17 @@ export function createTelegramBeforeAgentStartHook(
       prompt: event.prompt,
       systemPrompt: event.systemPrompt,
       telegramPrefix: options.telegramPrefix,
-      systemPromptSuffix: options.systemPromptSuffix ?? SYSTEM_PROMPT_SUFFIX,
+      localSystemPromptSuffix:
+        options.localSystemPromptSuffix ?? LOCAL_SYSTEM_PROMPT_SUFFIX,
+      telegramTurnSystemPromptSuffix:
+        options.telegramTurnSystemPromptSuffix ??
+        TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX,
     });
 }
 
 export interface TelegramProactivePromptHookDeps<TContext> {
   baseHook?: (event: BeforeAgentStartEvent) => { systemPrompt: string };
+  isConfigured: () => boolean;
   isProactivePushEnabled: () => boolean;
   isCurrentOwner: (ctx: TContext) => boolean;
 }
@@ -74,6 +93,7 @@ export function createTelegramProactiveBeforeAgentStartHook<TContext>(
 ) => Promise<{ systemPrompt: string }> {
   const baseHook = deps.baseHook ?? createTelegramBeforeAgentStartHook();
   return async function onBeforeAgentStart(event, ctx) {
+    if (!deps.isConfigured()) return { systemPrompt: event.systemPrompt };
     const result = baseHook(event);
     if (!deps.isProactivePushEnabled()) return result;
     if (!deps.isCurrentOwner(ctx)) return result;

package/lib/queue.ts

@@ -1439,6 +1439,7 @@ export async function shutdownTelegramSessionRuntime<TQueueItem>(
   deps: TelegramSessionShutdownRuntimeDeps<TQueueItem>,
 ): Promise<void> {
   deps.unbindDeferredDispatchContext?.();
+  await deps.stopPolling();
   deps.applyState(buildTelegramSessionShutdownState<TQueueItem>());
   deps.clearPendingMediaGroups();
   deps.clearModelMenuState();
@@ -1448,7 +1449,6 @@ export async function shutdownTelegramSessionRuntime<TQueueItem>(
   }
   deps.clearActiveTurn();
   deps.clearAbort();
-  await deps.stopPolling();
 }
 
 export type TelegramSessionLifecycleRuntimeDeps<

package/lib/replies.ts

@@ -4,6 +4,7 @@
  * Owns rendered-message delivery, reply transport wiring, and plain or markdown final replies
  */
 
+import { assertTelegramInlineKeyboardCallbackData } from "./keyboard.ts";
 import type {
   TelegramReplyParameters,
   TelegramSentMessage,
@@ -50,25 +51,29 @@ export function createReplyDedupRuntime(): ReplyDedupRuntime {
 
 // --- Transport-level dedup ---
 
-let lastRepliedToMessageId: number | undefined;
+const lastRepliedToMessageIdByChat = new Map<number, number>();
 
 export function resetTransportReplyDedup(): void {
-  lastRepliedToMessageId = undefined;
+  lastRepliedToMessageIdByChat.clear();
 }
 
 export function buildTelegramReplyParameters(
+  chatId: number,
   messageId: number | undefined,
 ): TelegramReplyParameters | undefined {
   if (messageId === undefined) return undefined;
-  if (messageId === lastRepliedToMessageId) return undefined;
-  lastRepliedToMessageId = messageId;
+  if (lastRepliedToMessageIdByChat.get(chatId) === messageId) {
+    return undefined;
+  }
+  lastRepliedToMessageIdByChat.set(chatId, messageId);
   return { message_id: messageId, allow_sending_without_reply: true };
 }
 
 export function buildTelegramMultipartReplyParameters(
+  chatId: number,
   messageId: number | undefined,
 ): string | undefined {
-  const parameters = buildTelegramReplyParameters(messageId);
+  const parameters = buildTelegramReplyParameters(chatId, messageId);
   return parameters ? JSON.stringify(parameters) : undefined;
 }
 
@@ -178,11 +183,12 @@ export async function sendTelegramRenderedChunks<TReplyMarkup>(
   deps: TelegramReplyDeliveryDeps<TReplyMarkup>,
   options?: { replyMarkup?: TReplyMarkup; replyToMessageId?: number },
 ): Promise<number | undefined> {
+  assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
   let lastMessageId: number | undefined;
   for (const [index, chunk] of chunks.entries()) {
     const replyParameters =
       index === 0
-        ? buildTelegramReplyParameters(options?.replyToMessageId)
+        ? buildTelegramReplyParameters(chatId, options?.replyToMessageId)
         : undefined;
     const sent = await deps.sendMessage({
       chat_id: chatId,
@@ -204,6 +210,7 @@ export async function editTelegramRenderedMessage<TReplyMarkup>(
   deps: TelegramReplyDeliveryDeps<TReplyMarkup>,
   options?: { replyMarkup?: TReplyMarkup },
 ): Promise<number | undefined> {
+  assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
   if (chunks.length === 0) return messageId;
   const [firstChunk, ...remainingChunks] = chunks;
   await deps.editMessage({

package/lib/sections.ts

@@ -4,10 +4,12 @@
  * Owns section registration, global registry binding, token mapping, main-menu/settings row injection, and section callback dispatch
  */
 
-import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
+import {
+  assertTelegramCallbackData,
+  type TelegramInlineKeyboardMarkup,
+} from "./keyboard.ts";
 
 const SECTION_REGISTRY_KEY = "__piTelegramSectionRegistry__";
-const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
 
 // --- Core Types ---
 
@@ -301,10 +303,6 @@ const BACK_NAV_ROW = {
   text: "⬆️ Back",
 } as const;
 
-function getUtf8ByteLength(value: string): number {
-  return new TextEncoder().encode(value).byteLength;
-}
-
 function sectionErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -317,13 +315,7 @@ function buildTelegramSectionCallbackData(
   const data = payload
     ? `section:${token}:${action}:${payload}`
     : `section:${token}:${action}`;
-  const byteLength = getUtf8ByteLength(data);
-  if (byteLength > TELEGRAM_CALLBACK_DATA_MAX_BYTES) {
-    throw new Error(
-      `Telegram section callback_data exceeds ${TELEGRAM_CALLBACK_DATA_MAX_BYTES} bytes (${byteLength}). Use a shorter action/payload or store state behind a compact key.`,
-    );
-  }
-  return data;
+  return assertTelegramCallbackData(data, "Telegram section callback_data");
 }
 
 function prependBackRow(

package/lib/telegram-api.ts

@@ -234,6 +234,14 @@ export interface TelegramFileDownloadOptions {
   maxFileSizeBytes?: number;
 }
 
+export interface TelegramAnswerCallbackQueryOptions {
+  recordRuntimeEvent?: (
+    kind: "api",
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+}
+
 export interface TelegramApiClient {
   call: <TResponse>(
     method: string,
@@ -664,6 +672,7 @@ export async function answerTelegramCallbackQuery(
   botToken: string | undefined,
   callbackQueryId: string,
   text?: string,
+  options: TelegramAnswerCallbackQueryOptions = {},
 ): Promise<void> {
   try {
     await callTelegram<boolean>(
@@ -673,8 +682,10 @@ export async function answerTelegramCallbackQuery(
         ? { callback_query_id: callbackQueryId, text }
         : { callback_query_id: callbackQueryId },
     );
-  } catch {
-    // ignore
+  } catch (error) {
+    options.recordRuntimeEvent?.("api", error, {
+      method: "answerCallbackQuery",
+    });
   }
 }
 
@@ -705,7 +716,9 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
   recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];
 }): TelegramBridgeApiRuntime {
   return createTelegramBridgeApiRuntime({
-    client: createTelegramApiClient(deps.getBotToken),
+    client: createTelegramApiClient(deps.getBotToken, {
+      recordRuntimeEvent: deps.recordRuntimeEvent,
+    }),
     tempDir: getTelegramApiTempDir(),
     maxFileSizeBytes: TELEGRAM_INBOUND_FILE_MAX_BYTES,
     tempFileMaxAgeMs: TELEGRAM_TEMP_FILE_MAX_AGE_MS,
@@ -834,8 +847,14 @@ export function createTelegramBridgeApiRuntime(
         throw error;
       }
     },
-    answerCallbackQuery: (callbackQueryId, text) => {
-      return deps.client.answerCallbackQuery(callbackQueryId, text);
+    answerCallbackQuery: async (callbackQueryId, text) => {
+      try {
+        await deps.client.answerCallbackQuery(callbackQueryId, text);
+      } catch (error) {
+        deps.recordRuntimeEvent("api", error, {
+          method: "answerCallbackQuery",
+        });
+      }
     },
     answerGuestQuery: (
       guestQueryId: string,
@@ -876,6 +895,7 @@ export function createTelegramBridgeApiRuntime(
  */
 export function createTelegramApiClient(
   getBotToken: () => string | undefined,
+  options: TelegramAnswerCallbackQueryOptions = {},
 ): TelegramApiClient {
   return {
     call: async (method, body, options) => {
@@ -909,7 +929,12 @@ export function createTelegramApiClient(
       );
     },
     answerCallbackQuery: async (callbackQueryId, text) => {
-      await answerTelegramCallbackQuery(getBotToken(), callbackQueryId, text);
+      await answerTelegramCallbackQuery(
+        getBotToken(),
+        callbackQueryId,
+        text,
+        options,
+      );
     },
   };
 }

package/lib/updates.ts

@@ -406,7 +406,8 @@ export function buildTelegramUpdateExecutionPlan<
       return {
         kind: "guest",
         guestMessage: action.guestMessage,
-        shouldDeny: action.authorization.kind === "deny",
+        // Guest mode is an extension of an already paired bridge, not a pairing surface.
+        shouldDeny: action.authorization.kind !== "allow",
       };
   }
 }

package/package.json

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