@llblab/pi-telegram 0.8.1 → 0.9.0

package/AGENTS.md

@@ -131,6 +131,7 @@ The canonical detailed ownership map lives in [`docs/architecture.md`](./docs/ar
 - For `/telegram-setup`, prefer the locally saved bot token over environment variables on repeat setup runs; env vars are the bootstrap path when no local token exists, and persisted `telegram.json` writes must remain atomic plus private because status/setup/polling paths may read it concurrently
 - Command help plus prompt-template commands and status/model/thinking/queue controls are driven through `/start`'s Telegram inline application menu and callback queries; the Queue button shows the queued-item count, model-menu scope/pagination controls stay at the top under Main menu, the model pagination indicator opens a compact page picker, and thinking-menu text stays a compact heading because the current level is marked by button state; `/status`, `/model`, `/thinking`, and `/queue` are hidden compatibility shortcuts
 - Shared inline-keyboard structure belongs to `keyboard`; application-control button labels, callback data, and callback behavior stay in `menu`/`menu-model`/`menu-thinking`/`menu-status`/`menu-queue` while core queue mechanics stay in `queue`
+- Telegram `/settings` options should open nested detail submenus by default: checkbox options show a description plus Back, On, and Off; list options show Back plus selectable values. One-shot actions such as syncing may run directly without a submenu when there is no meaningful choice or description step.
 - Inbound text/media may be transformed through configured `inboundHandlers` before queueing; legacy `attachmentHandlers` are deprecated compatibility aliases appended after `inboundHandlers`; outbound files must flow through `telegram_attach`
 - Long Telegram text split recovery belongs to `text-groups`: keep it conservative, short-debounced, same chat/user/message-id contiguous, and gated by near-limit human text so normal rapid follow-ups and slash commands stay separate
 - Inbound handlers and command-backed outbound handlers use command templates as the standard integration contract; built-in outbound buttons use inline keyboards plus callback routing because no external command execution is needed

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.9.0: Hidden Settings And Proactive Push
+
+- `[Settings Menu]` Added hidden Telegram `/settings` with a proactive push checkbox detail submenu plus `/telegram-settings` in the terminal. Impact: operators can see green/black binary flag state, use green/black/yellow On/Off checkbox controls from Telegram, and toggle the same proactive push flag locally without adding a visible bot-command entry.
+- `[Proactive Push]` `telegram.json` now supports `proactivePush`; when enabled, successful local non-Telegram π final replies are sent to the paired Telegram chat if no Telegram turn is active and the current session still owns the Telegram lock. Local prompt text stays private because the bot does not own or mirror terminal user messages. Impact: long local tasks can notify the phone with result context without leaking from stale bridge owners or failed/aborted turns.
+- `[Queue UI]` Empty queue states now use the bottom-filled `⌛` hourglass while non-empty queue states keep `⏳`. Queue item details now show the selected queue position above the raw prompt preview, preserve reaction-specific priority emoji in the heading, and use side-by-side Priority/Normal tabs that refresh the heading marker immediately. The terminal status bar now stays yellow active while Telegram-owned work still has running tools even if a queued prompt is removed by reaction. Impact: queue emptiness has a small visual easter egg, item submenus stay oriented without changing queue semantics, and queue-removal reactions no longer visually degrade active work to connected.
+- `[Model Menu]` Model rows now open a detail submenu with Back, ☑️ Activate/🟢 Active selection, and yellow/black-marked Scoped/All membership tabs. Impact: model selection remains one tap away while scoped model membership can be managed from Telegram.
+- `[Status Menu]` The main Telegram menu status row now shows `compacting` while a Telegram `/compact` run is active. Impact: the phone UI reflects the same compaction state that already blocks dispatch and appears in terminal status.
+- `[Prompt Guidance]` Telegram prompt injection now asks agents to target 37 visible cells for tables, dense list items, and compact text blocks. Impact: replies better fit narrow mobile Telegram screens, especially when emoji or wide glyphs are present.
+
+## 0.8.2: Lock-Safe Delivery
+
+- `[Lock Safety]` Active Telegram turns now re-check singleton ownership before preview flushes and final agent-end delivery. Impact: an old π instance stays silent after another instance takes the Telegram bridge lock, even if the old instance finishes a long-running prompt later.
+- `[Inbound Handlers]` The first step of an inbound composition now receives the full configured handler timeout before elapsed-time accounting starts on later steps. Impact: composition timeout behavior is deterministic and avoids one-millisecond test/runtime drift at pipeline start.
+- `[Menu UI]` Model and Thinking submenu headers now include their matching command icons (`🤖` and `🧠`). Impact: submenu headings match the Queue menu's icon-led style.
+- `[Package]` Bumped package metadata to `0.8.2` and kept the lockfile in sync.
+
 ## 0.8.1: Outbound Voice Translation Hotfix
 
 - `[Outbound Voice]` Composed voice handlers now pass the original `telegram_voice` text to the first pipeline step through stdin, then continue piping each step's stdout into the next step. Impact: translate-from-stdin voice pipelines can translate hidden voice text before TTS instead of failing with an empty first-step input.
@@ -40,7 +56,7 @@
 ## 0.7.0: Unified App Menu & Command Template Hardening
 
 - `[Commands]` Visible Telegram bot command menu now exposes `/start`, `/compact`, `/next`, `/continue`, `/abort`, and `/stop`; `/help`, `/status`, `/model`, `/thinking`, and `/queue` remain hidden compatibility shortcuts. `/start`, `/help`, and `/status` open one unified app menu containing command help, status rows, and inline controls. Command emoji are centralized as fixed adornments in the commands domain and reused by matching menu buttons (`🤖` model, `🧠` thinking); `/next` uses `⏩` and `/continue` uses `▶️`. `/continue` enqueues a priority Telegram-owned `continue` prompt instead of forcing the next queued item or requiring π to be idle. Impact: the visible command surface is cleaner while existing operator muscle memory still works and skills can react to queued `continue` prompts.
-- `[Application Menu]` `/start` opens command help plus status rows and the inline application menu; `/queue` opens the queue section directly, the status menu Queue button shows the current queued-item count, all submenus keep Back/Main menu navigation in the top row, and queued items are listed in dispatch order with numeric labels plus `⚡`/`📎` markers. Queue menu message text uses the same HTML heading style as the other inline menus; empty queue menus render bold message text with only the Main menu navigation button instead of a disabled empty-state button. Item submenus support Back, priority toggle, and Cancel, and stale item clicks refresh the live list. Impact: queued Telegram work is inspectable and mutable from the menu control surface without relying only on reactions.
+- `[Application Menu]` `/start` opens command help plus status rows and the inline application menu; `/queue` opens the queue section directly, the status menu Queue button shows the current queued-item count, all submenus keep Back/Main menu navigation in the top row, and queued items are listed in dispatch order with numeric labels plus `⚡`/`📎` markers. Queue menu message text uses the same HTML heading style as the other inline menus; empty queue menus render bold message text with only the Main menu navigation button instead of a disabled empty-state button. Item submenus support Back, Priority/Normal tabs, and Cancel, and stale item clicks refresh the live list. Impact: queued Telegram work is inspectable and mutable from the menu control surface without relying only on reactions.
 - `[Prompt Templates]` `/start` now shows a separate block for π prompt-template commands, and the Telegram bot command menu registers Telegram-safe prompt-template aliases such as `fix-tests` → `/fix_tests` when they do not conflict with built-in bridge commands or hidden shortcuts. Sending `/template_name args` from Telegram expands the matching π prompt-template file before queueing the turn. Impact: reusable π workflows are available from Telegram without duplicating prompt text manually.
 - `[Keyboard]` Shared Telegram inline-keyboard reply-markup structure was extracted to `keyboard`, while `menu` owns application-control button semantics and `outbound-handlers` owns assistant-authored button semantics. Impact: inline UI domains share one Bot API shape without centralizing feature behavior.
 - `[Domain DAG]` Source-module opening comments now include `Zones:` tags for cross-cutting responsibility areas such as Telegram transport, π agent lifecycle, TUI, and shared utilities. Impact: flat files keep folder-like orientation without adding directory nesting.

package/README.md

@@ -13,7 +13,7 @@ This repository is an actively maintained fork of [`badlogic/pi-telegram`](https
 
 ## Key Features
 
-- **Telegram Controls**: `/start` opens the inline application menu with command help, available π prompt templates, status rows, model, thinking, and queue sections; `/stop`, `/abort`, `/next`, and `/continue` provide queue-clear, queue-preserve, force-next, and queued-resume semantics respectively; model-switch continuation turns still use the control lane when a restart needs to resume safely.
+- **Telegram Controls**: `/start` opens the inline application menu with command help, available π prompt templates, status rows, model, thinking, and queue sections; the Status row reports `compacting` during Telegram `/compact`; `/stop`, `/abort`, `/next`, and `/continue` provide queue-clear, queue-preserve, force-next, and queued-resume semantics respectively; model-switch continuation turns still use the control lane when a restart needs to resume safely.
 - **Interactive UI**: Manage your session directly from Telegram. Inline buttons expose an application menu for switching models, choosing model pages from the pagination indicator, adjusting reasoning (thinking) levels, and inspecting or mutating the waiting queue; model scope/pagination controls stay at the top of the model menu, the Queue button shows the current item count, and command emoji are reused on matching controls such as model and thinking.
 - **In-flight Model Switching**: Change the active model mid-generation. The agent gracefully pauses, applies the new model, and restarts its response without losing context.
 - **Smart Message Queue**: Messages sent while the agent is busy are queued and previewed in the π status bar, and queued turns can be reprioritized or removed with Telegram reactions or the queue section of the inline application menu.
@@ -92,9 +92,9 @@ Use these inside the Telegram DM with your bot:
 
 Prompt-template commands: π prompt templates are mapped to Telegram-safe aliases (`fix-tests.md` becomes `/fix_tests`) and shown as compact command-only rows between the built-in commands and status rows in `/start`. They are not registered in the Telegram bot command menu, keeping the bot menu focused on bridge controls. Sending `/template_name args` from Telegram expands the matching π prompt-template file and queues the expanded prompt like normal Telegram work.
 
-Hidden compatibility shortcuts: `/help` and `/status` open the same main application menu, `/model` opens the model section, `/thinking` opens the thinking section, and `/queue` opens the queue section. They are intentionally not shown in the bot command menu.
+Hidden compatibility shortcuts: `/help` and `/status` open the same main application menu, `/model` opens the model section, `/thinking` opens the thinking section, `/queue` opens the queue section, and `/settings` opens hidden bridge settings. Settings rows open detail submenus with Back plus green/black/yellow option controls such as On and Off for checkboxes. These shortcuts are intentionally not shown in the bot command menu.
 
-Telegram command admission is explicit: `/compact`, `/queue`, `/stop`, `/abort`, `/next`, `/help`, `/start`, `/status`, `/model`, and `/thinking` execute immediately. `/continue` is a command shortcut that enqueues a priority Telegram prompt containing `continue`. Prompt-template commands expand before queueing and then follow normal prompt-queue rules. Synthetic model-switch continuation turns still enter the high-priority control lane so they can resume before normal queued prompts when π becomes safe to dispatch.
+Telegram command admission is explicit: `/compact`, `/queue`, `/settings`, `/stop`, `/abort`, `/next`, `/help`, `/start`, `/status`, `/model`, and `/thinking` execute immediately. `/continue` is a command shortcut that enqueues a priority Telegram prompt containing `continue`. Prompt-template commands expand before queueing and then follow normal prompt-queue rules. Synthetic model-switch continuation turns still enter the high-priority control lane so they can resume before normal queued prompts when π becomes safe to dispatch.
 
 ### Pi Commands
 
@@ -102,6 +102,7 @@ Run these inside π, not Telegram:
 
 - **`/telegram-setup`**: Configure or update the Telegram bot token.
 - **`/telegram-status`**: Check bridge status, connection, polling, execution, queue, and recent redacted runtime/API failure events.
+- **`/telegram-settings`**: Open local bridge settings and toggle proactive push using the same `telegram.json` flag as the Telegram `/settings` menu.
 - **`/telegram-connect`**: Start polling Telegram updates in the current π session, acquire the singleton lock, or interactively move ownership here from another live instance.
 - **`/telegram-disconnect`**: Stop polling in the current π session and release the singleton lock.
 
@@ -119,6 +120,8 @@ Run these inside π, not Telegram:
 
 ### Inbound Handlers
 
+`telegram.json` can set `proactivePush: true` to send successful local non-Telegram final replies to the paired Telegram chat when no Telegram turn is active. Local prompt text is not sent because the bot does not own or mirror terminal user messages. The mode is off by default, can be toggled from the hidden `/settings` menu, persists across contexts until explicitly disabled or removed from config, is gated by the current Telegram lock owner, and skips aborted or failed turns.
+
 `telegram.json` can define ordered `inboundHandlers` for Telegram → π preprocessing such as text translation, voice transcription, OCR, or PDF extraction. Matching handlers run before the Telegram turn enters the π queue. If a matching media/file handler fails, the next matching handler is tried as a fallback. Legacy `attachmentHandlers` still work as a deprecated compatibility alias and are appended after `inboundHandlers`.
 
 ```json
@@ -231,7 +234,7 @@ Rich previews are sent through editable messages because Telegram drafts are tex
 
 ## Status bar
 
-The π status bar shows the current bridge state plus queued Telegram turns as compact previews. Busy labels distinguish states such as `active`, `dispatching`, `queued`, `tool running`, `model`, and `compacting`.
+The π status bar shows the current bridge state plus queued Telegram turns as compact previews. Busy labels distinguish states such as `active`, `dispatching`, `queued`, `tool running`, `model`, and `compacting`. Telegram prompt guidance asks agents to keep tables, dense list items, and compact text blocks within about 37 visible cells when possible so mobile replies stay readable.
 
 ```text
 telegram queued +3: [⚡ write a shell script…, summarize this image…, 📎 2 attachments]

package/docs/architecture.md

@@ -33,7 +33,7 @@ Current runtime areas use these ownership boundaries:
 | `media` / `text-groups` / `turns` / `inbound-handlers` | Text/media extraction, media-group debounce, long-text split coalescing, inbound downloads, inbound text/media handler execution, turn building/editing, image reads, legacy `attachmentHandlers` compatibility |
 | `queue`                                   | Queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, session and agent/tool lifecycle sequencing |
 | `runtime`                                 | Session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, agent-end reset binding  |
-| `model` / `menu-model` / `menu-thinking` / `menu-status` / `menu` / `menu-queue` / `commands` | Model identity/thinking levels, scoped model resolution, in-flight switching, model-menu UI, thinking-menu UI, status-menu UI, inline application callback composition, queue-menu UI, slash commands, bot command registration |
+| `model` / `menu-model` / `menu-thinking` / `menu-status` / `menu` / `menu-queue` / `menu-settings` / `commands` | Model identity/thinking levels, scoped model resolution, in-flight switching, model-menu UI, thinking-menu UI, status-menu UI, inline application callback composition, queue-menu UI, hidden settings UI, slash commands, bot command registration |
 | `keyboard`                                | Shared Telegram inline-keyboard reply-markup structure; feature domains own callback semantics and button construction                                           |
 | `preview` / `replies` / `rendering`       | Preview lifecycle/transports, final reply delivery and reply parameters, Telegram HTML Markdown rendering, chunking, stable-preview snapshots                     |
 | `outbound-handlers`                       | Outbound text transformation, assistant-authored outbound comments, generated reply artifacts, inline-keyboard callbacks, and post-`agent_end` outbound action delivery |
@@ -103,7 +103,7 @@ Admission contract:
 | Priority prompt queue | A waiting prompt promoted by `👍`, `⚡️`, `❤️`, or `🕊`      | `kind: prompt`, `queueLane: priority`                                | 1             |
 | Default prompt queue  | Normal Telegram text/media turns                             | `kind: prompt`, `queueLane: default`                                 | 2             |
 
-The command action itself carries its execution mode, and the queue domain exposes lane contracts for admission mode, dispatch rank, and allowed item kinds. Queue append and planning paths validate lane admission so a malformed control/default or other invalid lane pairing fails predictably instead of silently changing priority. This lets synthetic control actions and Telegram prompts share one stable ordering model while still rendering distinctly in status output. In the π status bar, busy labels distinguish `active`, `dispatching`, `queued`, `tool running`, `model`, and `compacting`; priority prompts and priority control items are marked with `⚡`.
+The command action itself carries its execution mode, and the queue domain exposes lane contracts for admission mode, dispatch rank, and allowed item kinds. Queue append and planning paths validate lane admission so a malformed control/default or other invalid lane pairing fails predictably instead of silently changing priority. This lets synthetic control actions and Telegram prompts share one stable ordering model while still rendering distinctly in status output. In the π status bar, busy labels distinguish `active`, `dispatching`, `queued`, `tool running`, `model`, and `compacting`; priority prompts and priority control items are marked with `⚡`. If a queue mutation removes the last waiting item while Telegram-owned work still has running tools, the status remains yellow `active` instead of degrading to green `connected`.
 
 A dispatched prompt remains in the queue until `agent_start` consumes it. That keeps the active Telegram turn bound correctly for previews, attachments, abort handling, and final reply delivery.
 
@@ -115,9 +115,9 @@ Dispatch is gated by:
 - `ctx.isIdle()` being true
 - `ctx.hasPendingMessages()` being false
 
-This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. Post-agent-end dispatch retries are scheduled through a session-bound deferred dispatcher that activates on session start, cancels timers on session shutdown, and skips callbacks from older generations before they touch `ExtensionContext`. Telegram `/start` and hidden compatibility shortcuts `/status`, `/model`, `/thinking`, and `/queue` execute immediately; the dispatch controller still serializes any deferred control items so a queued control action must settle before the next queued action can dispatch.
+This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. Post-agent-end dispatch retries are scheduled through a session-bound deferred dispatcher that activates on session start, cancels timers on session shutdown, and skips callbacks from older generations before they touch `ExtensionContext`. Telegram `/start` and hidden compatibility shortcuts `/status`, `/model`, `/thinking`, `/queue`, and `/settings` execute immediately; the dispatch controller still serializes any deferred control items so a queued control action must settle before the next queued action can dispatch.
 
-`/start` opens the main application menu: visible command help, compact command-only prompt-template rows when π exposes Telegram-compatible prompt-template names, status rows (`Status`, `Usage`, `Cost`, `Context`), and top-level buttons for model, thinking, and queue sections. The Queue button includes the current queued-item count. Hidden compatibility shortcuts `/help`, `/status`, `/model`, `/thinking`, and `/queue` jump directly to their corresponding menu screens. Command emoji come from the `commands` domain map so visible command descriptions and matching menu buttons share one fixed adornment source. Prompt-template commands use a fixed `🧩` marker, map π template names to Telegram-safe aliases such as `fix-tests` → `/fix_tests`, stay visible only inside the `/start` menu, and expand before queueing because `ExtensionAPI.sendUserMessage()` intentionally bypasses π prompt-template expansion for extension-originated messages. Every submenu starts with a top Back row so navigation stays anchored near the original user message above the inline keyboard; model-menu scope and pagination controls sit directly under that top row before model choices, and tapping the pagination indicator opens a compact page picker headed by `<b>Choose a page:</b>`. `menu-model` owns model-menu state, scoped model pages, model callback planning, page-picker rendering, and model-menu rendering while `model` owns core model identity/switching semantics. `menu-thinking` owns thinking-menu text, reply markup, callback handling, and message rendering. `menu-status` owns status-menu payloads, status callback handling, and status-message rendering. `menu-queue` owns queue-menu UI only: queue items are rendered under a compact `<b>Queue:</b>` heading, top-to-bottom in dispatch order, numbered, and marked with `⚡` for priority prompts or `📎` for prompts with attachments. An empty queue renders bold message text plus the top Main menu button, not a disabled empty-state button. Selecting an item opens a submenu that displays the full queued prompt text with Back, priority toggle, and Cancel. If a callback targets an item that has already left the queue, the menu refreshes the list instead of applying a stale mutation.
+`/start` opens the main application menu: visible command help, compact command-only prompt-template rows when π exposes Telegram-compatible prompt-template names, status rows (`Status`, `Usage`, `Cost`, `Context`), and top-level buttons for model, thinking, and queue sections. The `Status` row reports `compacting` while a Telegram `/compact` run is active. The Queue button includes the current queued-item count. Hidden compatibility shortcuts `/help`, `/status`, `/model`, `/thinking`, and `/queue` jump directly to their corresponding menu screens, while `/settings` opens the hidden settings menu for bridge toggles such as proactive push. Settings options open detail submenus; checkbox-like settings use Back plus green/black/yellow On and Off controls instead of mutating directly from the list. Command emoji come from the `commands` domain map so visible command descriptions and matching menu buttons share one fixed adornment source. Prompt-template commands use a fixed `🧩` marker, map π template names to Telegram-safe aliases such as `fix-tests` → `/fix_tests`, stay visible only inside the `/start` menu, and expand before queueing because `ExtensionAPI.sendUserMessage()` intentionally bypasses π prompt-template expansion for extension-originated messages. Every submenu starts with a top Back row so navigation stays anchored near the original user message above the inline keyboard; model-menu pagination controls sit near the top, tapping the pagination indicator opens a compact page picker headed by `<b>Choose a page:</b>`, and tapping a model opens a detail submenu with Back, ☑️ Activate/🟢 Active selection, and yellow/black-marked Scoped/All membership tabs. `menu-model` owns model-menu state, scoped model pages, model detail rendering, scoped-list persistence planning, and model-menu rendering while `model` owns core model identity/switching semantics. `menu-thinking` owns thinking-menu text, reply markup, callback handling, and message rendering. `menu-status` owns status-menu payloads, status callback handling, and status-message rendering. `menu-queue` owns queue-menu UI only: queue items are rendered under a compact `<b>Queue:</b>` heading, top-to-bottom in dispatch order, numbered, and marked with `⚡` for priority prompts or `📎` for prompts with attachments. An empty queue renders bold message text with the bottom-filled `⌛` hourglass plus the top Main menu button, while non-empty queue states keep the running `⏳` hourglass. Selecting an item opens a submenu that displays the queue item number above the full queued prompt text with Back, side-by-side Priority/Normal tabs, and Cancel. If a callback targets an item that has already left the queue, the menu refreshes the list instead of applying a stale mutation.
 
 ### Abort Behavior
 
@@ -160,7 +160,9 @@ Telegram prompt responses use explicit delivery context to attach outbound text,
 
 Outbound files are sent only after the active Telegram turn completes, must be staged through the `telegram_attach` tool, are staged atomically per tool call, are checked against a default 50 MiB limit configurable through `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES`, and use file-backed multipart blobs so large sends do not require preloading whole files into memory.
 
-Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal, including fenced blocks with Markdown-valid indented closing fences. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes body text, `text="..."`, or colon shorthand through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, the default command timeout applies automatically, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text as a normal Telegram prompt turn; the `telegram_button: Label` shorthand uses the same text for label and prompt, `prompt="..."` supports explicit one-line prompts, and body-form buttons use the body as the prompt. Unknown callback data that does not match pi-telegram-owned prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`) is forwarded to π as `[callback] <data>` after built-in handlers decline it, giving layered extensions a simple namespaced button channel without separate polling; layered callback payloads should follow the [Callback Namespace Standard](./callback-namespaces.md). This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools.
+Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal, including fenced blocks with Markdown-valid indented closing fences. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes body text, `text="..."`, or colon shorthand through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, the default command timeout applies automatically, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text as a normal Telegram prompt turn; the `telegram_button: Label` shorthand uses the same text for label and prompt, `prompt="..."` supports explicit one-line prompts, and body-form buttons use the body as the prompt. Unknown callback data that does not match pi-telegram-owned prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`) is forwarded to π as `[callback] <data>` after built-in handlers decline it, giving layered extensions a simple namespaced button channel without separate polling; layered callback payloads should follow the [Callback Namespace Standard](./callback-namespaces.md). When proactive push is enabled, successful local non-Telegram final replies are sent to the paired chat. Local prompt text is not sent because the bot does not own or mirror terminal user messages. This keeps terminal-originated results visible in Telegram without changing Telegram-originated turn delivery.
+
+This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools. Telegram prompt guidance targets about 37 visible cells for tables, dense list items, and compact text blocks because emoji and other wide glyphs make raw character counts misleading on mobile screens.
 
 ## Interactive Controls
 
@@ -172,12 +174,13 @@ Current operator controls include:
 - Inline application-menu buttons for model, thinking, and queue controls, applying idle selections immediately while still respecting busy-run restart rules; model-menu inputs are cached briefly and stored inline-menu states are pruned by TTL/LRU so old keyboards expire predictably
 - Hidden `/model` and `/thinking` shortcuts for opening the model and thinking sections directly while keeping settings out of the visible bot command menu
 - `/compact` for Telegram-triggered π session compaction when the bridge is idle
-- `/queue` for opening the queue section of the inline application menu; the same section is reachable from the status/main menu and supports top-anchored Back navigation, priority toggling, and cancellation
+- `/queue` for opening the queue section of the inline application menu; the same section is reachable from the status/main menu and supports top-anchored Back navigation, Priority/Normal tabs, and cancellation
 - `/next` for dispatching the next queued turn, aborting the active run first when π is busy
 - `/continue` for enqueueing a Telegram-owned `continue` prompt, without aborting the current turn or forcing the next queued item
 - `/abort` for aborting the active Telegram-owned run while preserving queued items for manual continuation
 - `/stop` for aborting the active Telegram-owned run and clearing waiting Telegram queue items
 - `/telegram-status` for π-side diagnostics as grouped line-by-line sections separated by blank lines: connection, polling, execution, queue, and the recent redacted runtime/API event ring. These sections include polling state, last update id, active turn source ids, pending dispatch, compaction state, active tool count, pending model-switch state, total queue depth, and queue-lane counts. The event ring records transport/API, polling/update, prompt-dispatch, control-action, typing, compaction, setup, session-lifecycle, and attachment queue/delivery failures; benign unchanged edit responses and unsupported empty draft-clear attempts are filtered out so expected preview transport noise does not obscure real failures
+- `/telegram-settings` for π-side bridge settings; it currently exposes proactive push as a local toggle backed by the same `telegram.json` flag as the hidden Telegram `/settings` menu
 - Queue reactions apply to waiting text, voice, file, image, and media-group turns by matching the turn's source Telegram message ids: `👍`, `⚡️`, `❤️`, and `🕊` promote waiting prompts, while `👎`, `👻`, `💔`, and `💩` remove waiting turns because ordinary Telegram DM message deletions are not exposed through the Bot API polling path this bridge uses
 
 ## In-Flight Model Switching

package/index.ts

@@ -5,7 +5,6 @@
  */
 
 import * as Api from "./lib/api.ts";
-import * as OutboundAttachments from "./lib/outbound-attachments.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Commands from "./lib/commands.ts";
 import * as Config from "./lib/config.ts";
@@ -15,8 +14,10 @@ import * as Lifecycle from "./lib/lifecycle.ts";
 import * as Locks from "./lib/locks.ts";
 import * as Media from "./lib/media.ts";
 import * as MenuQueue from "./lib/menu-queue.ts";
+import * as MenuSettings from "./lib/menu-settings.ts";
 import * as Menu from "./lib/menu.ts";
 import * as Model from "./lib/model.ts";
+import * as OutboundAttachments from "./lib/outbound-attachments.ts";
 import * as OutboundHandlers from "./lib/outbound-handlers.ts";
 import * as Pi from "./lib/pi.ts";
 import * as Polling from "./lib/polling.ts";
@@ -48,8 +49,21 @@ export default function (pi: Pi.ExtensionAPI) {
   const bridgeRuntime = Runtime.createTelegramBridgeRuntime();
   const { abort, lifecycle, queue, setup, typing } = bridgeRuntime;
   const configStore = Config.createTelegramConfigStore();
+  const isProactivePushEnabled =
+    Config.createTelegramProactivePushChecker(configStore);
+  const setProactivePushEnabled =
+    Config.createTelegramProactivePushSetter(configStore);
+  const proactivePromptTargetStore =
+    Config.createTelegramProactivePromptTargetStore();
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
+  const lockOwnershipGuard =
+    Locks.createTelegramLockOwnershipGuard(lockRuntime);
   const activeTurnRuntime = Queue.createTelegramActiveTurnStore();
+  const proactivePushChatIdGetter =
+    Config.createTelegramProactivePushChatIdGetter({
+      getActiveTurnChatId: activeTurnRuntime.getChatId,
+      getAllowedUserId: configStore.getAllowedUserId,
+    });
   const buttonActionStore = OutboundHandlers.createTelegramButtonActionStore();
   const pendingModelSwitchStore =
     Model.createPendingModelSwitchStore<
@@ -198,6 +212,7 @@ export default function (pi: Pi.ExtensionAPI) {
     sendDraft: sendMessageDraft,
     sendMessage,
     editMessageText: editTelegramMessageText,
+    canSend: lockOwnershipGuard.ownsCurrentProcess,
     ...replyTransport,
   });
   const { finalizeMarkdownPreview } =
@@ -246,6 +261,7 @@ export default function (pi: Pi.ExtensionAPI) {
     buildStatusHtml: Commands.createTelegramAppMenuHtmlBuilder({
       buildStatusHtml: Status.createTelegramStatusHtmlBuilder({
         getActiveModel: currentModelRuntime.get,
+        isCompactionInProgress: lifecycle.isCompactionInProgress,
       }),
       getPromptTemplateCommands,
     }),
@@ -276,6 +292,16 @@ export default function (pi: Pi.ExtensionAPI) {
     updateStatusMessage: menuActions.updateStatusMessage,
     updateStatus,
   });
+  const settingsMenuRuntime = MenuSettings.createTelegramSettingsMenuRuntime({
+    getModelMenuState: getQueueMenuState,
+    getStoredModelMenuState: modelMenuRuntime.getState,
+    storeModelMenuState: modelMenuRuntime.storeState,
+    editInteractiveMessage,
+    sendInteractiveMessage,
+    answerCallbackQuery,
+    isProactivePushEnabled,
+    setProactivePushEnabled,
+  });
 
   // --- Polling ---
 
@@ -297,8 +323,11 @@ export default function (pi: Pi.ExtensionAPI) {
     currentModelRuntime,
     modelSwitchController,
     menuActions,
+    updateSettingsMenuMessage: settingsMenuRuntime.updateSettingsMenuMessage,
     openQueueMenu: queueMenuRuntime.openQueueMenu,
     queueMenuCallbackHandler: queueMenuRuntime.handleCallbackQuery,
+    openSettingsMenu: settingsMenuRuntime.openSettingsMenu,
+    settingsMenuCallbackHandler: settingsMenuRuntime.handleCallbackQuery,
     buttonActionStore,
     inboundHandlerRuntime,
     updateStatus,
@@ -310,6 +339,10 @@ export default function (pi: Pi.ExtensionAPI) {
     downloadFile: downloadTelegramBridgeFile,
     getThinkingLevel,
     setThinkingLevel,
+    persistScopedModelPatterns: Pi.createScopedModelPatternPersister({
+      createSettingsManager: Pi.createSettingsManager,
+      clearCachedModelMenuInputs: modelMenuRuntime.clearCachedInputs,
+    }),
     setModel,
     sendUserMessage,
     isIdle,
@@ -397,6 +430,8 @@ export default function (pi: Pi.ExtensionAPI) {
     startPolling: lockedPollingRuntime.start,
     stopPolling: lockedPollingRuntime.stop,
     updateStatus,
+    isProactivePushEnabled,
+    setProactivePushEnabled,
   });
 
   // --- Lifecycle Hooks ---
@@ -459,6 +494,11 @@ export default function (pi: Pi.ExtensionAPI) {
     sendQueuedAttachments: queuedAttachmentSender,
     planOutboundReply: outboundReplyPlanner,
     sendOutboundReplyArtifacts: outboundReplyArtifactSender,
+    isCurrentOwner: lockOwnershipGuard.ownsContext,
+    getDefaultChatId: proactivePushChatIdGetter,
+    consumeProactiveReplyToMessageId: proactivePromptTargetStore.consumeForChat,
+    isProactivePushEnabled,
+    recordRuntimeEvent,
     getActiveToolExecutions: lifecycle.getActiveToolExecutions,
     setActiveToolExecutions: lifecycle.setActiveToolExecutions,
     triggerPendingModelSwitchAbort: modelSwitchController.triggerPendingAbort,
@@ -472,7 +512,10 @@ export default function (pi: Pi.ExtensionAPI) {
     ...sessionLifecycleRuntime,
     ...agentLifecycleHooks,
     onAgentStart: agentStartWithDedupReset,
-    onBeforeAgentStart: Prompts.createTelegramBeforeAgentStartHook(),
+    onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({
+      isProactivePushEnabled,
+      isCurrentOwner: lockOwnershipGuard.ownsContext,
+    }),
     onModelSelect: currentModelRuntime.onModelSelect,
     onMessageStart: previewRuntime.onMessageStart,
     onMessageUpdate: previewRuntime.onMessageUpdate,

package/lib/commands.ts

@@ -135,6 +135,10 @@ export interface TelegramBridgeCommandStartPollingResult {
   owner?: string;
 }
 
+interface TelegramBridgeSettingsSelectUi {
+  select?: (title: string, items: string[]) => Promise<string | undefined>;
+}
+
 export interface TelegramBridgeCommandRegistrationDeps {
   promptForConfig: (ctx: ExtensionCommandContext) => Promise<void>;
   getStatusLines: () => string[];
@@ -149,6 +153,8 @@ export interface TelegramBridgeCommandRegistrationDeps {
     | TelegramBridgeCommandStartPollingResult;
   stopPolling: () => Promise<void | string>;
   updateStatus: (ctx: ExtensionCommandContext) => void;
+  isProactivePushEnabled?: () => boolean;
+  setProactivePushEnabled?: (enabled: boolean) => Promise<void>;
 }
 
 function formatTelegramTakeoverTitle(ctx: ExtensionCommandContext): string {
@@ -183,6 +189,36 @@ export function registerTelegramBridgeCommands(
       ctx.ui.notify(deps.getStatusLines().join("\n"), "info");
     },
   });
+  pi.registerCommand("telegram-settings", {
+    description: "Open Telegram bridge settings",
+    handler: async (_args, ctx) => {
+      if (!deps.isProactivePushEnabled || !deps.setProactivePushEnabled) {
+        ctx.ui.notify("Telegram settings are unavailable.", "warning");
+        return;
+      }
+      await deps.reloadConfig();
+      const enabled = deps.isProactivePushEnabled();
+      const nextEnabled = !enabled;
+      const label = `${enabled ? "🟢" : "⚫️"} Proactive push`;
+      const action = `${nextEnabled ? "Enable" : "Disable"} proactive push`;
+      const select = (ctx.ui as TelegramBridgeSettingsSelectUi).select;
+      if (!select) {
+        ctx.ui.notify(
+          `${label}\n${action}: /telegram-settings requires interactive mode.`,
+          "info",
+        );
+        return;
+      }
+      const selected = await select("Telegram settings", [label, "Cancel"]);
+      if (selected !== label) return;
+      await deps.setProactivePushEnabled(nextEnabled);
+      deps.updateStatus(ctx);
+      ctx.ui.notify(
+        `Proactive push ${nextEnabled ? "enabled" : "disabled"}.`,
+        "info",
+      );
+    },
+  });
   pi.registerCommand("telegram-connect", {
     description: "Start the Telegram bridge in this π session",
     handler: async (_args, ctx) => {
@@ -230,6 +266,7 @@ export const TELEGRAM_RESERVED_COMMAND_NAMES = [
   "compact",
   "model",
   "thinking",
+  "settings",
   "help",
   "start",
 ] as const;
@@ -261,6 +298,7 @@ export type TelegramCommandAction =
   | { kind: "status"; executionMode: "immediate" }
   | { kind: "model"; executionMode: "immediate" }
   | { kind: "thinking"; executionMode: "immediate" }
+  | { kind: "settings"; executionMode: "immediate" }
   | {
       kind: "help";
       commandName: "help" | "start";
@@ -279,6 +317,7 @@ export interface TelegramCommandActionDeps<TMessage, TContext> {
   handleStatus: (message: TMessage, ctx: TContext) => Promise<void>;
   handleModel: (message: TMessage, ctx: TContext) => Promise<void>;
   handleThinking: (message: TMessage, ctx: TContext) => Promise<void>;
+  handleSettings?: (message: TMessage, ctx: TContext) => Promise<void>;
   handleHelp: (
     message: TMessage,
     commandName: "help" | "start",
@@ -353,6 +392,11 @@ export interface TelegramCommandTargetRuntimeDeps<TContext> {
     replyToMessageId: number,
     ctx: TContext,
   ) => Promise<void>;
+  openSettingsMenu?: (
+    chatId: number,
+    replyToMessageId: number,
+    ctx: TContext,
+  ) => Promise<void>;
   sendTextReply: (
     chatId: number,
     replyToMessageId: number,
@@ -373,6 +417,7 @@ export interface TelegramCommandTargetRuntime<
   ) => void;
   showStatus: (message: TMessage, ctx: TContext) => Promise<void>;
   openModelMenu: (message: TMessage, ctx: TContext) => Promise<void>;
+  openSettingsMenu: (message: TMessage, ctx: TContext) => Promise<void>;
   sendTextReply: (message: TMessage, text: string) => Promise<void>;
 }
 
@@ -457,6 +502,7 @@ export function createTelegramCommandTargetQueueRuntime<
     }),
     showStatus: deps.showStatus,
     openModelMenu: deps.openModelMenu,
+    openSettingsMenu: deps.openSettingsMenu,
     sendTextReply: deps.sendTextReply,
   });
 }
@@ -485,6 +531,18 @@ export function createTelegramCommandTargetRuntime<
       const target = getTelegramCommandMessageTarget(message);
       return deps.openModelMenu(target.chatId, target.replyToMessageId, ctx);
     },
+    openSettingsMenu: async (message, ctx) => {
+      const target = getTelegramCommandMessageTarget(message);
+      if (!deps.openSettingsMenu) {
+        await deps.sendTextReply(
+          target.chatId,
+          target.replyToMessageId,
+          "Settings menu is unavailable.",
+        );
+        return;
+      }
+      await deps.openSettingsMenu(target.chatId, target.replyToMessageId, ctx);
+    },
     sendTextReply: async (message, text) => {
       const target = getTelegramCommandMessageTarget(message);
       await deps.sendTextReply(target.chatId, target.replyToMessageId, text);
@@ -541,6 +599,7 @@ export interface TelegramCommandRuntimeDeps<
   openModelMenu: (message: TMessage, ctx: TContext) => Promise<void>;
   openThinkingMenu: (message: TMessage, ctx: TContext) => Promise<void>;
   openQueueMenu: (message: TMessage, ctx: TContext) => Promise<void>;
+  openSettingsMenu?: (message: TMessage, ctx: TContext) => Promise<void>;
   getAllowedUserId: () => number | undefined;
   setAllowedUserId: (userId: number) => void;
   registerBotCommands: () => Promise<void>;
@@ -624,6 +683,7 @@ export const TELEGRAM_COMMAND_ACTIONS = {
   compact: { kind: "compact", executionMode: "immediate" },
   model: { kind: "model", executionMode: "immediate" },
   thinking: { kind: "thinking", executionMode: "immediate" },
+  settings: { kind: "settings", executionMode: "immediate" },
   help: { kind: "help", commandName: "help", executionMode: "immediate" },
   start: { kind: "help", commandName: "start", executionMode: "immediate" },
 } as const satisfies Record<TelegramReservedCommandName, TelegramCommandAction>;
@@ -830,6 +890,10 @@ export async function executeTelegramCommandAction<TMessage, TContext>(
     case "thinking":
       await deps.handleThinking(message, ctx);
       return true;
+    case "settings":
+      if (!deps.handleSettings) return false;
+      await deps.handleSettings(message, ctx);
+      return true;
     case "help":
       await deps.handleHelp(message, action.commandName, ctx);
       return true;
@@ -846,6 +910,7 @@ export interface TelegramCommandHandlerTargetRuntimeDeps<
       | "enqueueControlItem"
       | "showStatus"
       | "openModelMenu"
+      | "openSettingsMenu"
       | "sendTextReply"
       | "registerBotCommands"
     >,
@@ -877,6 +942,7 @@ export function createTelegramCommandHandlerTargetRuntime<
     dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
     showStatus: deps.showStatus,
     openModelMenu: deps.openModelMenu,
+    openSettingsMenu: deps.openSettingsMenu,
     sendTextReply: deps.sendTextReply,
   });
   return createTelegramCommandHandler({
@@ -901,6 +967,7 @@ export function createTelegramCommandHandlerTargetRuntime<
     openModelMenu: commandTargetRuntime.openModelMenu,
     openThinkingMenu: deps.openThinkingMenu,
     openQueueMenu: deps.openQueueMenu,
+    openSettingsMenu: commandTargetRuntime.openSettingsMenu,
     getAllowedUserId: deps.getAllowedUserId,
     setAllowedUserId: deps.setAllowedUserId,
     registerBotCommands: createTelegramBotCommandRegistrar({
@@ -1056,6 +1123,11 @@ async function handleTelegramCommandRuntime<
       handleThinking: async (nextMessage, commandCtx) => {
         await deps.openThinkingMenu(nextMessage, commandCtx);
       },
+      handleSettings: deps.openSettingsMenu
+        ? async (nextMessage, commandCtx) => {
+            await deps.openSettingsMenu?.(nextMessage, commandCtx);
+          }
+        : undefined,
       handleHelp: async (nextMessage, _nextCommandName, commandCtx) => {
         try {
           await deps.registerBotCommands();

package/lib/config.ts

@@ -42,6 +42,7 @@ export interface TelegramConfig {
   inboundHandlers?: TelegramInboundHandlerConfig[];
   attachmentHandlers?: TelegramInboundHandlerConfig[];
   outboundHandlers?: TelegramOutboundHandlerConfig[];
+  proactivePush?: boolean;
 }
 
 export interface TelegramConfigStore {
@@ -124,6 +125,54 @@ export function createTelegramConfigStore(
   };
 }
 
+export function createTelegramProactivePushChecker(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => boolean {
+  return () => configStore.get().proactivePush ?? false;
+}
+
+export function createTelegramProactivePushSetter(
+  configStore: Pick<TelegramConfigStore, "get" | "set" | "persist">,
+): (enabled: boolean) => Promise<void> {
+  return async (enabled) => {
+    const config = { ...configStore.get(), proactivePush: enabled };
+    configStore.set(config);
+    await configStore.persist(config);
+  };
+}
+
+export function createTelegramProactivePushChatIdGetter(deps: {
+  getActiveTurnChatId: () => number | undefined;
+  getAllowedUserId: () => number | undefined;
+}): () => number | undefined {
+  return () => deps.getActiveTurnChatId() ?? deps.getAllowedUserId();
+}
+
+export interface TelegramProactivePromptTarget {
+  chatId: number;
+  messageId: number;
+}
+
+export interface TelegramProactivePromptTargetStore {
+  set: (target: TelegramProactivePromptTarget) => void;
+  consumeForChat: (chatId: number) => number | undefined;
+}
+
+export function createTelegramProactivePromptTargetStore(): TelegramProactivePromptTargetStore {
+  let target: TelegramProactivePromptTarget | undefined;
+  return {
+    set: (nextTarget) => {
+      target = nextTarget;
+    },
+    consumeForChat: (chatId) => {
+      if (!target || target.chatId !== chatId) return undefined;
+      const messageId = target.messageId;
+      target = undefined;
+      return messageId;
+    },
+  };
+}
+
 export type TelegramAuthorizationState =
   | { kind: "pair"; userId: number }
   | { kind: "allow" }

package/lib/inbound-handlers.ts

@@ -258,6 +258,15 @@ function getRemainingTelegramInboundTimeout(
   return Math.max(1, timeout - (Date.now() - startedAt));
 }
 
+function getTelegramInboundInitialCompositionStepTimeout(
+  handler: TelegramInboundHandlerConfig,
+  step: TelegramInboundCommandTemplateConfig,
+): number {
+  const timeout = getTelegramInboundHandlerTimeout(handler);
+  const stepTimeout = getTelegramInboundHandlerConfiguredTimeout(step);
+  return stepTimeout === undefined ? timeout : Math.min(stepTimeout, timeout);
+}
+
 function getTelegramInboundCompositionStepTimeout(
   handler: TelegramInboundHandlerConfig,
   step: TelegramInboundCommandTemplateConfig,
@@ -421,7 +430,9 @@ async function executeTelegramTextHandler(
         output,
         cwd,
         deps,
-        getTelegramInboundCompositionStepTimeout(handler, step, startedAt),
+        index === 0
+          ? getTelegramInboundInitialCompositionStepTimeout(handler, step)
+          : getTelegramInboundCompositionStepTimeout(handler, step, startedAt),
       );
     } catch (error) {
       if (typeof step === "object" && step.critical) throw error;
@@ -498,7 +509,9 @@ async function executeTelegramInboundHandler(
         cwd,
         deps,
         false,
-        getTelegramInboundCompositionStepTimeout(handler, step, startedAt),
+        index === 0
+          ? getTelegramInboundInitialCompositionStepTimeout(handler, step)
+          : getTelegramInboundCompositionStepTimeout(handler, step, startedAt),
         index === 0 ? undefined : output,
       );
     } catch (error) {

package/lib/locks.ts

@@ -61,6 +61,11 @@ export interface TelegramLockRuntime<TContext extends TelegramLockContext> {
   owns: (ctx?: TelegramLockContext) => boolean;
 }
 
+export interface TelegramLockOwnershipGuard<TContext extends TelegramLockContext> {
+  ownsCurrentProcess: () => boolean;
+  ownsContext: (ctx: TContext) => boolean;
+}
+
 export interface TelegramLockRuntimeOptions {
   key?: string;
   locksPath?: string;
@@ -234,6 +239,17 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
   };
 }
 
+export function createTelegramLockOwnershipGuard<
+  TContext extends TelegramLockContext,
+>(
+  lock: TelegramLockRuntime<TContext>,
+): TelegramLockOwnershipGuard<TContext> {
+  return {
+    ownsCurrentProcess: () => lock.owns(),
+    ownsContext: (ctx) => lock.owns(ctx),
+  };
+}
+
 export function createTelegramLockedPollingRuntime<
   TContext extends TelegramLockContext,
 >(