@llblab/pi-telegram 0.23.1 → 0.23.3

package/AGENTS.md

@@ -87,7 +87,7 @@ The core product loop is mobile continuation: start or supervise work in the ter
 - Instance slots are extension-owned ring-order metadata. Allocate fresh slots from the `bot.lastSlot` cursor as `A` → `B` → ... → `Z` → `A`, allowing the cursor to move to lower letters after wraparound. Only current live/recovering bindings plus unexpired pending provisions and explicit reservations occupy slots; historical records must not block allocation indefinitely. Preserve a slot on ordinary current binding/thread reuse without advancing or rewinding the fresh-allocation cursor. Follower bindings survive process absence as stable restoration hints until explicit stale/deleted/offline evidence invalidates them. Successful target reuse must refresh the binding timestamp and replacement runtime identity; generic leader startup or heartbeat pruning must not erase the target merely because no follower registration is currently live. An authenticated live follower whose carried exact target is missing from current persisted bindings should recover that target instead of creating another Telegram thread; preserve a carried slot only when it does not collide with another current record. Preserve a cursor that belongs to a live or recoverable binding and continue skipping retained restart hints plus unexpired pending/reserved slots. Explicit stale/deleted/offline reconciliation may release that slot; generic process absence may not. The alphabet cap is a feature — compact single-letter tabs are scannable.
 - Instance thread names are provisioner-authored identity metadata, not model-authored output. Fresh Threaded Mode threads select one of five curated compact 4-6 letter Latin names for the assigned slot letter using provisioning timestamp entropy, then create the Telegram thread with that thread name immediately. The title is the thread name itself, not `{slot} {threadName}` or `{slot} — {threadName}`. Do not register or reintroduce an agent-facing thread rename tool; removing the extra rename prompt/tool turn is an intentional simplicity constraint. Thread names must mirror into terminal status, live diagnostics, and `[telegram|thread:name]` through one target-aware current-instance identity resolver. Registered follower/leader metadata takes precedence over a stale shared record for the same target, with the record used only as fallback; do not hide a valid baked/custom thread name behind old slot-prefix validation. A follower that later becomes leader keeps its existing name; leadership changes are transport role changes, not identity resets.
 - Telegram private-chat Threaded Mode treats `All` as an aggregate/control surface, not a durable `General` thread or process launcher, and leader activation proactively creates or reuses its private-DM thread. When the owner writes in an unknown thread, the leader reclaims and routes the first one only if it lacks an active binding; later unknown threads remain intact and receive an in-thread chooser to reroute the captured prompt or restore a stale binding. Destructive cleanup requires explicit confirmation through `thread-reconciler`; another Pi instance still requires a manually started process followed by `/telegram-connect`. Without Threaded Mode, process the message through classic routing.
-- Telegram extension work should not hold Pi's core agent lifecycle hostage once Pi has produced the semantic result. For Telegram-originated turns, final Telegram delivery, attachment upload, and transport cleanup are extension-owned side effects; schedule them off the critical `agent_end` path when ordering can still be preserved, record failures as runtime events, and keep dispatch of the next Telegram turn behind the delivery task when needed to avoid interleaving previews/finals. Public activity handlers run through isolated asynchronous per-handler queues; lifecycle hooks enqueue normalized events and never await consumer work. Proactive push defaults enabled and requires explicit `assistant.proactivePush: false` to opt out. While enabled, core delivery projects each completed Pi-visible assistant text block from local/autonomous work once and in order; bind admitted blocks to the exact target, profile/token transport stamp, direct leader epoch or follower registration generation, and session generation. Token deltas, hidden reasoning, tool traffic, stale authority, and Telegram-owned turns never enter that projection.
+- Telegram extension work should not hold Pi's core agent lifecycle hostage once Pi has produced the semantic result. For Telegram-originated turns, final Telegram delivery, attachment upload, and transport cleanup are extension-owned side effects; schedule them off the critical `agent_end` path when ordering can still be preserved, record failures as runtime events, and keep dispatch of the next Telegram turn behind the delivery task when needed to avoid interleaving previews/finals. Treat a low-level error `agent_end` as retryable while its Telegram turn remains active; only a later successful `agent_end` or Pi's `agent_settled` boundary may finalize and release that turn. Public activity handlers run through isolated asynchronous per-handler queues; lifecycle hooks enqueue normalized events and never await consumer work. Proactive push defaults enabled and requires explicit `assistant.proactivePush: false` to opt out. While enabled, core delivery projects each completed Pi-visible assistant text block from local/autonomous work once and in order; bind admitted blocks to the exact target, profile/token transport stamp, direct leader epoch or follower registration generation, and session generation. Token deltas, hidden reasoning, tool traffic, stale authority, and Telegram-owned turns never enter that projection.
 - Telegram runtime state should be treated as event-driven reconciliation of extension assumptions against observable Telegram signals, not as a full Telegram bot read-model and not as a reason to query Telegram on every action. Keep a local assumption model for bot identity/capabilities, pairing assumptions, thread support, known thread lifecycle, bound instance targets, reservations, and transport health. Invalidate and reconcile the relevant slice on meaningful events: startup/reload, lifecycle service messages, stale-send/API errors, setup/pairing changes, follower register/prune, explicit status/debug requests, and bounded low-frequency leader health ticks. `lib/sync.ts` owns sync slices, observation intake, invalidation triggers, status/debug freshness, and reconciliation scheduling; it must not promise complete bot-state mirroring because Bot API lacks a complete topic listing surface. `lib/thread-reconciler.ts` owns pure Threaded Mode lifecycle planning and should become the only policy authority for destructive thread cleanup decisions. `threads` owns current Telegram UI thread/tab binding primitives and thread-name helpers mapped to Bot API topic transport, `status` renders projections, and `index.ts` only wires ports. `tmp/telegram/logs.jsonl` is a session-local redacted runtime evidence stream for race debugging and resets on extension start / runtime scope changes; it is diagnostics only, not routing/provisioning authority. `state.json` should be an observable/debug snapshot aligned with `/telegram-status` (extension runtime, bot capabilities including `bot.lastSlot`, runtime role, live roster projection, reservations, diagnostics), not routing/provisioning authority. Because every process on one Telegram profile shares this file, only the active transport lock owner may persist it; followers read current state and gain write authority only after promotion. Status-only writes must refresh disk-backed bindings before serialization so a stale loaded snapshot cannot erase newer leader state. Live bus/runtime state is authoritative; file reservations and fresh capability observations may be startup hints/collision guards only; stale snapshots must re-probe before suppressing bus/topic behavior. Do not persist stale/offline/failed thread target history as source of truth.
 - Thread bindings are bidirectional. From the Pi-instance side, an instance knows and preserves its target, slot, thread name, lifecycle state, and direct-delivery defaults. From the Telegram-client/bot side, the bridge observes thread creation/close/reopen/stale-send signals and reconciles them into instance binding state. Lifecycle transitions that affect operator understanding should be Telegram-visible when a live transport remains: every successful follower registration/re-registration gets a compact connected notice in the assigned thread, while heartbeat pruning stays silent because it is only liveness suspicion. These notices should use the instance thread name when known and fall back to the slot letter only while the thread is still unnamed. New unknown threads (owner writing in `All`) are preserved until the user explicitly chooses a reroute/restore/new-instance action that makes cleanup eligible; any destructive cleanup must go through `thread-reconciler`. Unknown `forum_topic_created` service events are observations, not destructive cleanup proof.
 - The multi-instance bus uses private bot DMs with Telegram private-chat Threaded Mode enabled for the bot. No supergroup, group, or forum configuration is needed; the thread chat is always the private chat with the paired owner. Threaded capability checks must use bot/private-chat evidence such as `getMe.has_topics_enabled`, incoming `message_thread_id`, and topic operation success/failure; do not use group chat metadata as the control-plane truth for Telegram private-chat Threaded Mode.
@@ -116,12 +116,12 @@ The core product loop is mobile continuation: start or supervise work in the ter
 - `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, a registered follower's assigned target, or explicit `chat_id` plus optional `thread_id` for explicit local/TUI delivery requests only when this Pi instance owns `/telegram-connect` or is registered with the Threaded Mode multi-instance bus. `telegram_message` is the first-class direct Telegram Markdown text tool for local/TUI prompts and follows the same ownership-or-bus-registration gate; 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 prompt guidance is layered and context-frugal: unconfigured sessions receive no bridge suffix, configured sessions receive compact direct-delivery/help guidance, and Telegram-originated turns receive only the minimal per-turn contract. Detailed voice/button/direct-delivery/Threaded Mode/formatting/debug guidance belongs in the agent-facing `telegram_help` tool instead of being repeated in every prompt.
 - Telegram inbound prompt topology keeps current user material contiguous: `[outputs]` produced from current attachments follows `[attachments]` immediately, then independent `[reply]` or forwarded-source context follows the complete current-user block. Forwarded Rich Message media belongs under source-attributed `[attachments|from:<identity>]` immediately after its `[forward|from:<identity>]` block and remains available as model image content. Do not place source context between an attachment and its transcription or handler output.
-- Forward-comment grouping uses a bounded one-second candidate window for ordinary short human text so an adjacent same-sender/chat/thread forward can join across polling responses; a matching forward flushes immediately. Commands, bots, captions, media groups, target/sender mismatches, reversed ids, and distant message ids bypass grouping. Preserve the grouped candidate across session replacement and follower forwarding without weakening exact routing-generation authority.
+- Forward-annotation grouping distinguishes two semantic layers: the forward owns its source text/caption/media, while an optional separate owner-authored annotation normally arrives immediately before it. Use a bounded one-second candidate window in both transport orders: ordinary short human text may wait for an adjacent same-sender/chat/thread forward, and a forwarded message—including a media-only forward with no source caption—may wait for one adjacent owner annotation. A matching opposite-kind message flushes immediately; same-kind messages, commands, bots, ordinary non-forward captions, media groups, target/sender mismatches, reversed ids, and distant ids stay separate. Preserve the candidate across session replacement and follower forwarding without weakening exact routing-generation authority.
 - `telegram_voice` and `telegram_button` are not Pi 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
+- Voice reply policy and prompt context are owned by pi-telegram's `telegram.json` `voice.replyMode`: missing, invalid, `hidden`, and legacy `manual` config resolve to `hidden` and add no `[voice]` context; `mirror` adds `[voice] delivery: automatic voice` only for voice/audio input, while `always` adds that same single factual line to every Telegram turn. Place voice context after `[outputs]` when handler output exists, otherwise after `[attachments]`; provider prompt contributions are optional provider-specific additions, not the default policy or delivery-composition 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.
 - Agent activity status is native-only for the release path: Telegram uses `sendChatAction(typing)` and renders its native `…typing` indicator as the automatic work signal. When a connected instance starts any real agent run, send that indicator to the instance's own thread (and aggregate `All` surface), including Telegram turns, local/TUI prompts, and autonomous continuations such as Grow Loop; stop it at agent/session completion. This signal is independent from terminal `Active`, which remains scoped to Telegram-owned turns. Confirmed manual `/compact` and automatic compaction tied to an active Telegram turn also use native activity. Do not send activity merely for startup/connect/reload/recovery or add extra in-chat work surfaces without a new explicit design decision.
-- Voice reply mode Settings UI standard: the top-level Settings row is `👄 Voice reply: hidden|manual|mirror|always`; `hidden` is the true default and means no valid `voice.replyMode` is persisted, behavior is manual, and no voice policy is added to prompt context; explicit `manual` behaves the same operationally but renders reply-mode context. The submenu title is `👄 Voice reply mode:`; choice buttons use lowercase labels with a model-style active dot (`🟢 hidden`, `🟢 mirror`) rather than per-mode emoji; the explanatory submenu body uses compact HTML-code bullets such as `<code>-</code> <code>hidden</code> (default): ...`. Preserve this wording/icons unless the operator explicitly asks to redesign it
+- Voice reply mode Settings UI standard: the top-level Settings row is `👄 Voice reply: hidden|mirror|always`; `hidden` is the true default, persists no `voice.replyMode`, adds no voice context, and still allows explicit agent-authored `telegram_voice`; `mirror` activates automatic voice context only for voice/audio input, and `always` activates it for every Telegram turn. The submenu title is `👄 Voice reply mode:`; choice buttons use lowercase labels with a model-style active dot (`🟢 hidden`, `🟢 mirror`) rather than per-mode emoji; the explanatory submenu body uses compact HTML-code bullets such as `<code>-</code> <code>hidden</code> (default): ...`. Preserve this wording/icons unless the operator explicitly asks to redesign it
 - Outbound voice delivery is one fallback pipeline: configured `outboundHandlers` with `type: "voice"` run first in `telegram.json` order, then programmatic voice handlers, then registered voice synthesis providers as zero-config progressive fallbacks; provider extensions must not override operator-configured handlers
 - `telegram_voice` text is arbitrary TTS-target text and the prompt should show only forms that include text to speak: `<!-- telegram_voice text="Short summary" -->` or `<!-- telegram_voice: Short summary -->`. Avoid raw Markdown/code/tables in voice text.
 - `telegram_button` has three canonical forms: `<!-- telegram_button: OK -->` for label-only buttons, `<!-- telegram_button label=Continue prompt="Continue with the current plan." -->` for one-line prompts, or `<!-- telegram_button label="Show risks"\nList the main risks first.\n-->` for multiline prompts. Do not author JSON button specs, inline-after-text comments, standalone button tools, or comments inside code/quotes/lists/indented examples; write normal Markdown plus top-level hidden comments, and add visible parent text when buttons would otherwise be the only output
@@ -149,7 +149,7 @@ The core product loop is mobile continuation: start or supervise work in the ter
 
 - Treat queue handling, compaction interaction, and lifecycle-hook state transitions as regression-prone areas; validate them after changing dispatch logic
 - Keep the standard `npm run typecheck` gate strict about unused locals and parameters so stale imports and abandoned adapters fail validation instead of accumulating silently
-- Route important runtime failures through the recent runtime event recorder so `/telegram-status` remains useful for post-mortem debugging, not just transient status-bar errors
+- Route important runtime failures through the recent runtime event recorder so `/telegram-status` remains useful for post-mortem debugging. Keep the compact TUI status bar bounded to the generic `error` state; detailed error messages belong only in diagnostics/logs, never inline beside the status label.
 - Treat remaining Markdown-to-HTML rendering as Telegram UI/compat output work, not generic Markdown rendering or assistant reply delivery
 - Preserve literal code content in Telegram rendering
 - Avoid HTML chunk splits that break tags

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.23.3: Thread-Scoped Settings Hotfix
+
+- `Thread-Scoped Settings Rehydration`: Preserved `message_thread_id` when rebuilding full Settings menu state after session reload or TTL expiry. Impact: a stale Settings message in Threaded Mode retains its exact Telegram target when later callbacks reopen menus or cross into model/status controls.
+- `Composition Root Hygiene`: Sorted the local domain imports in `index.ts` and normalized adjacent wrapping without changing runtime composition. Impact: the entrypoint remains easier to scan and review while preserving the existing dependency graph and behavior.
+
+## 0.23.2: Voice Policy And Turn Delivery Hotfix
+
+- `Settings Persistence Race`: Rebuilt expired Settings callback state from the live model-menu context before applying mutations. Polling now persists only its monotonic `lastUpdateId` into the current config-store snapshot instead of later submitting the detached full config object captured when polling started. Impact: a subsequent Telegram update can no longer erase freshly persisted `voice.replyMode`, `assistant.proactivePush`, or other Settings values and return the menu to stale defaults.
+- `Compact Error Status`: Reduced pi-telegram's TUI error projection to the single `error` state while retaining detailed failures in runtime diagnostics and logs. Impact: provider and transport messages no longer consume the status line or displace the surrounding model/session indicators.
+- `Forward Annotation Pairing`: Extended the bounded one-second coalescer so one optional owner-authored annotation and adjacent forward join in either transport order, including photo-only forwards without their own source caption. Prompt construction keeps the layers distinct: owner annotation first, then `[forward|from:...]` with the forward's own source text/caption, then source-attributed media; same-kind messages and existing command/sender/target/id-gap exclusions remain separate. Impact: Telegram forwarding gestures no longer split the user's explanation from the forwarded source or conflate it with the forward's own content.
+- `Voice Reply Policy`: Collapsed the redundant explicit `manual` mode into the silent `hidden` default, kept `mirror` automatic only for voice/audio input, and kept `always` automatic for every Telegram turn. Active automatic turns now carry exactly `[voice] delivery: automatic voice`; the per-turn system suffix only points to `telegram_help`, explicit `telegram_voice` remains an agent-authored override, and legacy `manual` config resolves to `hidden`. Impact: models receive one effective delivery fact instead of a noisy mode matrix, while providers remain responsible for synthesis rather than text/voice composition.
+- `Provider Retry Delivery`: Retained an active Telegram turn across low-level `agent_end` errors until Pi either produced a successful retry result or emitted `agent_settled`. Retry recovery now delivers the eventual semantic result once to the original target, while an exhausted retry finalizes the retained error once and releases queue state; redacted diagnostics distinguish retention, recovery, and settled failure. Impact: transient provider transport failures can no longer orphan a later successful reply from its originating Telegram turn.
+
 ## 0.23.1: Context Budget And Runtime Simplification
 
 - `Bus Runtime Simplification`: Removed the no-op follower-binding recovery timer and grace configuration, the unused disconnected-announcement helper, and the duplicate follower-prune callback. Heartbeat pruning now emits one accurate diagnostic while preserving durable thread bindings. Impact: leader/follower recovery carries less dormant state and cannot imply offline cleanup that never occurs.

package/README.md

@@ -92,7 +92,7 @@ The first Telegram user to message the bot becomes the allowed owner. Other user
 
 | Surface | What you can do | Why it matters |
 | --- | --- | --- |
-| Prompt intake | Send text, replies, edits, images, files, albums, voice notes, and handler output into Pi. | Telegram becomes a real mobile input surface with file/context references, not just a text tunnel. |
+| Prompt intake | Send text, replies, edits, images, files, albums, voice notes, forwards with adjacent comments, and handler output into Pi. | Telegram becomes a real mobile input surface; one forward-plus-comment gesture stays one attributed prompt even for photo-only forwards. |
 | Queue control | Inspect waiting turns, delete stale work, promote important prompts, continue, abort, stop, or force the next queued item. | Long Pi tasks keep running while new mobile prompts stay visible and controllable instead of interrupting or disappearing. |
 | Operator menu | Use `/start` for status, prompt templates, model, thinking, settings, queue, extension sections, and diagnostics. | The bot is an operator panel, not a command cheat sheet. |
 | Prompt templates | Run Pi prompt templates as Telegram-safe commands such as `/fix_tests`. | Reusable local workflows become phone-accessible without exposing arbitrary terminal commands. |
@@ -104,7 +104,7 @@ The first Telegram user to message the bot becomes the allowed owner. Other user
 | Inbound files | Download inbound files to the Pi agent temp directory with size limits. | Screenshots, PDFs, datasets, and artifacts enter Pi as inspectable local files. |
 | Outbound artifacts | Return generated files through `telegram_attach` during active turns or explicit direct delivery. | Agents send real artifacts as files, not pasted blobs. |
 | Voice input | Route audio through configured command-template handlers, programmatic handlers, or STT providers. | Voice notes become usable prompt context. |
-| Voice output | Use `telegram_voice`, reply modes, configured voice handlers, and TTS providers. | Replies can become Telegram voice messages when the workflow calls for it. |
+| Voice output | Choose `hidden`, `mirror`, or `always`; active automatic turns carry one compact `[voice] delivery: automatic voice` line, while explicit `telegram_voice` remains available. | Voice policy stays dynamic and model-legible without duplicating the full action contract in every prompt. |
 | Buttons | Turn top-level `telegram_button` comments into inline buttons. | Assistant-authored choices become native Telegram interactions. |
 | Callback routing | Route known callbacks to the owner extension and unknown callbacks back into Pi. | Companion extensions can build UI without polling Telegram themselves. |
 | Threaded Mode | Run one leader plus visible follower Pi instances through named private-chat threads. | One bot can host a local multi-instance Pi organism without hidden process spawning. |
@@ -165,7 +165,7 @@ Named profile identifiers contain only lowercase ASCII letters and digits (maxim
 
 ### Queue Runtime
 
-Messages sent while Pi is busy become queued turns. Priority lanes support control actions and model-switch continuations. Queue controls let you inspect, delete, promote, and dispatch work from Telegram without touching the terminal.
+Messages sent while Pi is busy become queued turns. Priority lanes support control actions and model-switch continuations. Queue controls let you inspect, delete, promote, and dispatch work from Telegram without touching the terminal. If Pi automatically retries a transient provider failure, the active Telegram turn stays bound until the successful reply arrives or Pi confirms that the run has settled.
 
 ### Native Rich Markdown
 

package/docs/architecture.md

@@ -135,7 +135,7 @@ Telegram private-chat Threaded Mode is the public switch for multi-instance Tele
 
 Named Telegram profiles are orthogonal to Threaded Mode. The selected profile chooses the bot/session slice (`botToken`, `botId`, `botUsername`, `allowedUserId`, `lastUpdateId`) and scopes singleton locks, diagnostics logs, state files, thread/bus owner keys, and leader/follower IPC endpoints; it must not change the Threaded Mode rules. Within one selected profile, leader/follower election, bus transport, thread provisioning, routing, ownership forwarding, cleanup, and runtime diagnostics behave exactly as they do for the default profile. A different selected profile is a parallel bot runtime: its locks, `tmp/telegram/state.<profile>.json`, `tmp/telegram/logs.<profile>.jsonl`, `tmp/telegram/logs.<profile>._prev.jsonl`, thread bindings, Unix sockets, and Windows named pipes are isolated from the default profile and from other named profiles while shared bridge settings remain top-level/global. The default profile preserves legacy state, log, socket, and named-pipe paths for compatibility.
 
-Profile reality follows three explicit storage classes. `telegram.json` shared settings and extension registries are process-global platform configuration; profile bot/session fields and observable transport/routing authority are profile-scoped; queues, active turns, ownership caches, menu state, and runtime controllers are session-local memory. Config persistence serializes cross-process writers and applies each recursive mutation delta to the latest disk snapshot, so named-profile offsets and unrelated global/profile updates do not stale-replace one another. Runtime profile switching follows stop-old/commit-new ordering: reload keeps the selected identity stable, old polling/lock/bus teardown finishes while all dynamic resolvers still point at the old profile, and only then may activation expose the new token, lock key, state path, target namespace, and IPC endpoint. Downloaded attachments use UUID-prefixed names in the shared Telegram scratch directory and are session artifacts rather than identity or routing authority, so cross-profile cleanup is limited to stale scratch files and cannot redirect live traffic.
+Profile reality follows three explicit storage classes. `telegram.json` shared settings and extension registries are process-global platform configuration; profile bot/session fields and observable transport/routing authority are profile-scoped; queues, active turns, ownership caches, menu state, and runtime controllers are session-local memory. Config persistence serializes cross-process writers and applies each recursive mutation delta to the latest disk snapshot, so named-profile offsets and unrelated global/profile updates do not stale-replace one another. Polling publishes only its monotonic `lastUpdateId` into the current config-store snapshot; it never persists the detached full config object captured at poll start, which would interpret newer Settings fields as deletions. Runtime profile switching follows stop-old/commit-new ordering: reload keeps the selected identity stable, old polling/lock/bus teardown finishes while all dynamic resolvers still point at the old profile, and only then may activation expose the new token, lock key, state path, target namespace, and IPC endpoint. Downloaded attachments use UUID-prefixed names in the shared Telegram scratch directory and are session artifacts rather than identity or routing authority, so cross-profile cleanup is limited to stale scratch files and cannot redirect live traffic.
 
 When Threaded Mode is active, the current polling owner is also the Telegram bus leader. The leader owns the local bus endpoint (Unix-domain socket on Unix-like platforms, named pipe on native Windows), polls `getUpdates`, performs direct Bot API calls, records follower heartbeats, prunes stale followers, and provisions Telegram UI thread targets through live runtime/bus state. Follower liveness is intentionally fast because heartbeat traffic is local IPC: followers heartbeat every `1s`, the leader treats them as stale after `2s`, and the prune loop runs every `1s` so stopped followers are detected promptly while active forwarded updates/API calls still refresh liveness. Heartbeat pruning is silent liveness bookkeeping: it preserves the follower thread binding and does not send a Telegram-visible disconnected notice, because the common cause may be leader reload or IPC handoff rather than a dead follower. Successful follower target reuse refreshes the binding's recovery timestamp. Absent follower bindings remain durable restoration hints until explicit stale, deleted, offline, or reconciliation evidence invalidates them; process absence and heartbeat pruning alone do not remove them. If an authenticated live follower carries an exact target that is absent from current bindings, the leader recovers it only behind a synchronous visibility probe: success activates it, explicit stale evidence provisions a replacement, and ambiguous failure rejects registration. A carried slot is restored only when it is not already occupied. `tmp/telegram/logs.jsonl` is a session-local redacted runtime evidence stream for race debugging; it resets on extension start and runtime scope changes, and must not become routing/provisioning authority. `tmp/telegram/state.json` is an extension+bot observable/debug snapshot aligned with status diagnostics: `source: "snapshot"` and `writtenAtMs` mark it as observational, not authoritative. All instances on one Telegram profile read the same snapshot, but only the active transport lock owner persists it; followers become writers only after promotion. Status-only persistence reloads current disk bindings before serialization, preventing a stale follower/status view from erasing newer leader-owned targets. Fresh capability observations may skip redundant startup probes, but stale snapshots re-probe before suppressing bus/thread behavior. Top-level `bot` mirrors bot-wide capabilities such as thread mode, `runtime` describes process role/status, `liveRoster` mirrors followers/current targets/reservations, `diagnostics` mirrors recent status/debug signals including the latest thread-reconciler phase/counts, `threads` stores current routeable bindings, TTL-bounded reservations explain short-lived slot collision guards, and TTL-pruned `pendingProvisions` protects in-flight topic creation slots from cleanup/allocation races. Fresh provisioning writes pending state before the Bot API create call, adds the returned target to the pending record, persists a `starting` binding, then promotes it to `active` and clears pending state. If final binding persistence fails after Telegram returns a thread id, the targeted pending provision remains as cleanup/retry evidence. Once targeted pending provisions expire, they are retained for `thread-reconciler` close/delete cleanup and pending scratchpad removal after a successful cleanup apply; untargeted expired pending records can prune without cleanup because no Telegram thread id exists. Runtime events coalesce status-snapshot writes so transient bus/API/update failures remain inspectable even when the operator has not opened `/telegram-status`. The bridge must not keep a durable `telegram-targets.json` target history; stale/offline/failed thread observations are pruned instead of reused. Previous-process leader bindings that still probe alive become reservations/collision guards, not routeable active threads, so a reloaded leader can take the next free slot without duplicating the same visible tab name. The thread chat is always the private bot DM with the paired owner (`allowedUserId`). In Telegram private-chat Threaded Mode, the leader creates/reuses its own thread before polling — it is a real bound instance, not a dispatcher. Followers authenticate bus envelopes with the leader-minted capability secret stored in the active lock entry. Leader lock entries also carry a stable `leaderEpoch` minted on acquisition and preserved across heartbeat refreshes; leader-owned cleanup/provisioning plans stamp that epoch, and Thread Reconciler apply skips destructive work if leadership has moved on before side effects run. Followers own their own Pi session state, queue, active turns, previews, menus, and lifecycle hooks, but route allowlisted, target-scoped Telegram API calls through the leader. When a follower promotes after heartbeat loss, status/state diagnostics expose only the transient `electing` lifecycle phase; stable `leader`/`follower` identity stays in the bus role so diagnostics do not duplicate role state. The TUI status bar and `/telegram-status` report `leader` or `follower` role so a registered follower is not shown as generically disconnected. Terminal status identity and the `[telegram|thread:name]` prompt label use the same target-aware current-instance resolver: registered local metadata wins over a stale shared binding for the matching target, while the binding remains a fallback for partial metadata.
 
@@ -167,7 +167,7 @@ All inbound updates are gated by the configured authorized user id.
 2. Persist update offsets only after successful handling; repeated handler failures are bounded.
 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, likely split long text, and a short human comment followed by an adjacent forwarded message when needed.
+5. Coalesce media groups, likely split long text, and one adjacent forward-plus-comment pair in either order when needed.
 6. Download files into `~/.pi/agent/tmp/telegram` with size limits and partial-download cleanup.
 7. Run configured/programmatic inbound handlers in order, appending successful stdout under `[outputs]`.
 8. Add local attachments under `[attachments]`, optional voice context, and optional final `[time]` context.
@@ -175,7 +175,7 @@ All inbound updates are gated by the configured authorized user id.
 10. Handle `edited_message` updates separately while the original turn is still queued.
 11. Dispatch only when all safety gates are clear.
 
-Long-text split recovery remains conservative: only human text at or above the near-limit threshold opens its debounce window. A separate bounded one-second comment window applies to ordinary short human text so a forwarded message arriving in the next polling response can join the same Pi turn; an adjacent matching forward flushes immediately. Commands, bots, captions, media groups, different senders/targets, reversed ids, and distant message ids do not enter this pairing path.
+Long-text split recovery remains conservative: only human text at or above the near-limit threshold opens its debounce window. Forward annotation has two semantic layers: the forward owns its source text/caption/media, while an optional separate owner-authored annotation normally precedes it. A bounded one-second pairing window joins that annotation and adjacent forward in either transport order, including a media-only forward without source caption text; the matching opposite-kind message flushes immediately. Same-kind rapid messages, commands, bots, ordinary non-forward captions, media groups, different senders/targets, reversed ids, and distant message ids do not enter this pairing path. Prompt construction always places the owner annotation first, followed by `[forward|from:...]` with the forward's own source text/caption, then source-attributed forwarded attachments, regardless of arrival order.
 
 ### Queue And Dispatch Safety
 
@@ -200,7 +200,7 @@ Dispatch requires:
 - `ctx.isIdle()` is true.
 - `ctx.hasPendingMessages()` is false.
 
-A dispatched prompt remains queued until `agent_start` consumes it. This keeps the active Telegram turn bound for previews, attachments, aborts, and final replies.
+A dispatched prompt remains queued until `agent_start` consumes it. This keeps the active Telegram turn bound for previews, attachments, aborts, and final replies. A low-level `agent_end` error also retains that active turn because Pi may retry automatically; a later successful `agent_end` delivers through the original target and metadata, while `agent_settled` proves that an unrecovered error can be finalized once before queue dispatch resumes.
 
 Post-agent-end queue dispatch uses a session-bound deferred dispatcher. It is activated on session start, clears timers on shutdown, and skips callbacks from older generations before touching `ExtensionContext`. Dispatch stays session-bound after polling ownership moves elsewhere. When a queued Telegram prompt is forwarded into Pi, it uses a normal `sendUserMessage(content)` turn after the bridge's idle/dispatch guards pass; it does not use Pi's `followUp` delivery option or inject terminal input.
 
@@ -299,11 +299,11 @@ Status rendering distinguishes connected, active, dispatching, queued, tool-runn
 
 Queue reactions are shortcut controls for waiting turns. Promotion reactions (`👍`, `⚡️`, `❤️`, `🕊`, `🔥`) move prompts to priority; removal reactions (`👎`, `👻`, `💔`, `💩`, `🗑`) remove waiting turns because ordinary Telegram DM deletions are not exposed through Bot API polling.
 
-`/telegram-status` records grouped diagnostics for transport/API, polling/update, prompt dispatch, controls, typing, compaction, setup, session lifecycle, attachment queue/delivery, and recent redacted runtime events. Expected preview noise such as unchanged edit responses is filtered out.
+`/telegram-status` records grouped diagnostics for transport/API, polling/update, prompt dispatch, controls, typing, compaction, setup, session lifecycle, attachment queue/delivery, and recent redacted runtime events. Expected preview noise such as unchanged edit responses is filtered out. The compact TUI status renders only `error`; detailed failure text remains in diagnostics and profile-scoped logs instead of expanding the status line.
 
 When `assistant.proactivePush` is enabled and this instance has exact direct or follower transport authority, completed public assistant text blocks from local/autonomous work are sent once and in source order to the instance's authorized target. Visible commentary/checkpoints and the final block use the configured Rich or HTML renderer. Hidden reasoning, tool traffic, token deltas, local prompt text, Telegram-owned turns, and stale generations are not mirrored. Each admitted block remains fenced to its exact target, profile/token stamp, leader epoch or follower registration generation, and session generation; non-idempotent acknowledgement ambiguity never authorizes replay.
 
-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.
+Telegram prompt guidance is context-aware. Unconfigured sessions receive no bridge suffix. Local/TUI prompts receive only explicit direct-delivery guidance. Telegram-originated turns receive a compact pointer to `telegram_help` plus dynamic prompt blocks such as `[voice] delivery: automatic voice`; full voice/button/direct-delivery/Threaded Mode syntax stays in the help tool rather than every system prompt.
 
 ## In-Flight Model Switching
 

package/docs/outbound.md

@@ -30,7 +30,7 @@ When `assistant.rendering` is `"rich"`, a Telegram-originated turn that queues e
 
 The optimization is deliberately narrow. HTML rendering, empty final text, multiple files, documents and other unsupported formats, Guest Mode, explicit `telegram_voice`, voice-preferred turns, and OGG/Opus artifacts retain their established text/attachment/voice paths. A known-safe Rich upload rejection falls back to those paths. A `commit-unknown` transport outcome or a nominally successful upload without a verifiable message id never falls back or replays because the first non-idempotent send may already have committed.
 
-This behavior does not generate media or alter voice policy. `telegram_attach` still represents an explicit assistant artifact decision, while `manual`, `mirror`, and `always` continue to decide voice synthesis independently.
+This behavior does not generate media or alter voice policy. `telegram_attach` still represents an explicit assistant artifact decision, while `hidden`, `mirror`, and `always` continue to decide voice synthesis independently.
 
 Core assistant output accepts only the Markdown or HTML `InputRichMessage` forms and does not construct explicit block arrays or `InputRichBlockThinking`. Telegram's Thinking block is draft-only and must never become a projection of hidden reasoning or chain-of-thought. Any future use for Activity would require an explicitly public user-visible summary rather than provider reasoning content.
 

package/docs/public-api.md

@@ -93,7 +93,7 @@ interface TelegramConfig {
     proactivePush?: boolean;
   };
   voice?: {
-    replyMode?: "manual" | "mirror" | "always";
+    replyMode?: "hidden" | "mirror" | "always";
     sendTranscript?: boolean;
   };
   time?: {
@@ -106,7 +106,7 @@ interface TelegramConfig {
 Hidden/default semantics are represented by absence:
 
 - `assistant.proactivePush` defaults to `true`; omit it to keep projection enabled, or set it explicitly to `false` to disable it. When enabled, each completed public assistant text block from local or autonomous work is projected to the authorized Telegram target once and in source order. This includes visible intermediate commentary/checkpoints and the final block. It excludes token deltas, hidden reasoning, tool calls/arguments/results, Telegram-owned turns, empty blocks, and stale authority. Projection uses the configured Rich or HTML assistant renderer and binds admitted work to the exact target, profile/token transport generation, direct leader epoch or follower registration generation, and session generation. The old top-level `proactivePush` key is ignored; move the setting manually under `assistant`.
-- Voice Reply `hidden`: no `voice.replyMode` key is persisted.
+- Voice Reply `hidden`: no `voice.replyMode` key is persisted; legacy `manual` resolves to this silent default. `mirror` adds `[voice] delivery: automatic voice` only to voice/audio-input turns, while `always` adds the same effective line to every Telegram turn.
 - Agent activity status is not configurable in this release. Telegram uses native `sendChatAction(typing)` / product `...active` status as the only automatic in-chat work signal before the final reply.
 - Time Injection `hidden`: no `time.injectionMode` key is persisted; if `time` becomes empty, the whole `time` object may be omitted.
 

package/docs/ui-style.md

@@ -171,8 +171,8 @@ Rules:
 
 Examples:
 
+- `hidden`
 - `🟢 mirror`
-- `manual`
 - `always`
 
 ## Navigation

package/docs/voice.md

@@ -33,14 +33,13 @@ Voice provider extensions can also register STT backends with `registerTelegramV
 
 ## Voice Reply Policy
 
-The bridge decides **when** to reply with voice from `voice.replyMode` in `TelegramConfig` (stored in `telegram.json`). If config does not set a valid mode, the bridge uses the `hidden` default: manual behavior without adding voice policy text to the prompt context.
+The bridge decides **when** to reply with voice from `voice.replyMode` in `TelegramConfig` (stored in `telegram.json`). Missing, invalid, `hidden`, and legacy `manual` values resolve to the silent `hidden` default.
 
 ### Modes
 
-- **`hidden` (default):** no `voice.replyMode` is stored; same behavior as manual, no prompt voice context.
-- **`manual`:** only reply with voice when the agent authors `<!-- telegram_voice -->` markup; explicit prompt context is added.
-- **`mirror`:** reply with voice when the inbound message was a voice note or audio file. Text input stays on the manual path where explicit `telegram_voice` markup still works.
-- **`always`:** always reply with voice.
+- **`hidden` (default):** no `voice.replyMode` is stored and no automatic voice context is added; explicit agent-authored `telegram_voice` actions still work.
+- **`mirror`:** voice/audio input activates automatic voice delivery. Text input follows `hidden` behavior.
+- **`always`:** every Telegram turn activates automatic voice delivery.
 
 **Warning:** In `always` mode, the bridge transparently intercepts ALL text replies and converts them to voice on success. Users will only receive voice messages when voice generation succeeds. If voice generation fails, the bridge falls back to sending the planned text reply.
 
@@ -97,7 +96,7 @@ Registration returns a disposer function for cleanup. Stable provider registrati
 
 ## Outbound Voice Handlers
 
-Users can also configure `outboundHandlers` with `type: "voice"` in `telegram.json`. This is the command-template path for TTS without a provider extension. Reply modes (`manual`, `mirror`, `always`) affect these handlers the same way they affect providers: explicit `telegram_voice` blocks and automatic mirror/always interception both produce a voice reply plan, then delivery tries configured outbound voice handlers first and registered synthesis providers as progressive fallbacks.
+Users can also configure `outboundHandlers` with `type: "voice"` in `telegram.json`. This is the command-template path for TTS without a provider extension. Reply modes (`hidden`, `mirror`, `always`) affect these handlers the same way they affect providers: explicit `telegram_voice` blocks and automatic mirror/always interception both produce a voice reply plan, then delivery tries configured outbound voice handlers first and registered synthesis providers as progressive fallbacks.
 
 Voice handlers receive the text on stdin in composed pipelines and can use `{text}`, `{lang}`, `{rate}`, `{mp3}`, and `{ogg}` placeholders. Set `output` to `"ogg"` or another placeholder name when the template writes to a known path:
 
@@ -167,7 +166,7 @@ Voice provider extensions can register a Voice Extension Section (settings UI) v
 
 ## Prompt Guidance
 
-The bridge keeps voice prompt context compact and policy-owned. It adds `[voice] reply mode: ...` only when `telegram.json` explicitly contains a valid `voice.replyMode`. `hidden`/no configured mode behaves like manual, but prompts stay silent. When explicit, voice-originated `manual` turns add `[voice] reply mode: manual`, voice-originated `mirror` turns add `[voice] reply mode: mirror`, and `always` mode adds `[voice] reply mode: always` for every turn. If voice context later contains multiple fields, the bridge renders it as a `[voice]` list. The marker is appended after `[outputs]` when handler output exists, otherwise after `[attachments]`. Voice inputs also appear in `[attachments]` with their downloaded file names, MIME data, and handler output, so agents can infer concrete voice-file context from attachment metadata.
+The bridge keeps voice prompt context compact, effective, and policy-owned. `hidden` and text-originated `mirror` turns add no voice line. Voice/audio-originated `mirror` turns and every `always` turn add exactly `[voice] delivery: automatic voice`, describing the current delivery environment without exposing the underlying mode matrix or an instruction list. The marker is appended after `[outputs]` when handler output exists, otherwise after `[attachments]`. Voice inputs also appear in `[attachments]` with their downloaded file names, MIME data, and handler output, so agents can infer concrete voice-file context from attachment metadata.
 
 Voice synthesis providers can supply prompt guidance through `getVoicePromptContribution(view)`, but provider text should stay optional and provider-specific. Reply-mode context belongs to pi-telegram.
 
@@ -204,12 +203,12 @@ Voice synthesis providers can supply prompt guidance through `getVoicePromptCont
 ```json
 {
   "voice": {
-    "replyMode": "manual"
+    "replyMode": "mirror"
   }
 }
 ```
 
-Valid stored values: `"manual"`, `"mirror"`, `"always"`. Missing or invalid values are shown in Settings as `hidden`, behave like manual, and stay silent in prompt context.
+Valid modes are `"hidden"`, `"mirror"`, and `"always"`; selecting `hidden` removes the key. Missing, invalid, and legacy `"manual"` values resolve to `hidden` and stay silent in prompt context.
 
 The bridge reads `voice.replyMode` from the config when building a turn.
 

package/index.ts

@@ -7,18 +7,18 @@
 import * as Activity from "./lib/activity.ts";
 import * as Bindings from "./lib/bindings.ts";
 import * as BusApi from "./lib/bus-api.ts";
-import * as Bus from "./lib/bus.ts";
 import * as BusFollower from "./lib/bus-follower.ts";
 import * as BusLeader from "./lib/bus-leader.ts";
 import * as BusTransport from "./lib/bus-transport.ts";
+import * as Bus from "./lib/bus.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Commands from "./lib/commands.ts";
 import * as Config from "./lib/config.ts";
 import * as Delivery from "./lib/delivery.ts";
-import * as Threads from "./lib/threads.ts";
 import * as Inbound from "./lib/inbound.ts";
 import * as Lifecycle from "./lib/lifecycle.ts";
 import * as Locks from "./lib/locks.ts";
+import * as Logs from "./lib/logs.ts";
 import * as Media from "./lib/media.ts";
 import * as MenuQueue from "./lib/menu-queue.ts";
 import * as MenuSettings from "./lib/menu-settings.ts";
@@ -35,13 +35,13 @@ import * as Queue from "./lib/queue.ts";
 import * as Replies from "./lib/replies.ts";
 import * as Routing from "./lib/routing.ts";
 import * as Runtime from "./lib/runtime.ts";
-import * as Logs from "./lib/logs.ts";
 import * as Sections from "./lib/sections.ts";
 import * as Status from "./lib/status.ts";
 import * as Sync from "./lib/sync.ts";
 import * as TelegramApi from "./lib/telegram-api.ts";
 import * as TextGroups from "./lib/text-groups.ts";
 import * as ThreadReconciler from "./lib/thread-reconciler.ts";
+import * as Threads from "./lib/threads.ts";
 import * as TimeInjection from "./lib/time-injection.ts";
 import * as Updates from "./lib/updates.ts";
 import * as Voice from "./lib/voice.ts";
@@ -222,6 +222,11 @@ export default function (pi: Pi.ExtensionAPI) {
       persist: configStore.persist,
       markConfigChange: telegramSyncStateRuntime.markConfigChange,
     });
+  const persistTelegramPollingOffset =
+    Config.createTelegramPollingOffsetPersister(
+      configStore,
+      persistTelegramConfigWithSync,
+    );
   const currentInstanceThreadRuntime =
     Threads.createTelegramCurrentInstanceThreadRuntime({
       instanceId: telegramInstanceId,
@@ -460,8 +465,7 @@ export default function (pi: Pi.ExtensionAPI) {
         isTransportStampActive: telegramTransportStampRuntime.isActive,
         ownsDirect: lockRuntime.owns,
         getDirectEpoch: lockRuntime.getOwnedLeaderEpoch,
-        isFollowerRegistered:
-          telegramBusFollowerRegistrationState.isRegistered,
+        isFollowerRegistered: telegramBusFollowerRegistrationState.isRegistered,
         getFollowerGeneration:
           telegramBusFollowerRegistrationState.getGeneration,
       },
@@ -771,8 +775,7 @@ export default function (pi: Pi.ExtensionAPI) {
           return telegramActiveBusAuthSecret;
         },
         ...forwardedRouteHandlers,
-        prepareForwardedMessage:
-          textGroupRuntime.prepareForwardedMessage,
+        prepareForwardedMessage: textGroupRuntime.prepareForwardedMessage,
         recordRuntimeEvent,
       },
       targetReplacement: {
@@ -822,7 +825,7 @@ export default function (pi: Pi.ExtensionAPI) {
     hasBotToken: configStore.hasBotToken,
     deleteWebhook,
     getUpdates,
-    persistConfig: persistTelegramConfigWithSync,
+    persistConfig: persistTelegramPollingOffset,
     prepareUpdateBatch: textGroupRuntime.prepareUpdateBatch,
     handleUpdate: Updates.createTelegramUpdateHandle({
       defaultHandle: inboundRouteRuntime.handleUpdate,

package/lib/bindings.ts

@@ -36,9 +36,7 @@ type TelegramRuntimeEventRecorder = (
 type TelegramBridgeStatusUpdater =
   Status.TelegramStatusRuntime<Pi.ExtensionContext>["updateStatus"];
 
-export interface TelegramAssistantOutputBindingRuntime<
-  TTransportStamp,
-> {
+export interface TelegramAssistantOutputBindingRuntime<TTransportStamp> {
   runtime: Activity.TelegramAssistantOutputRuntime;
   observeEvent: (event: Activity.TelegramActivityEvent) => void;
   authority: Routing.TelegramAssistantOutputAuthorityRuntime<TTransportStamp>;
@@ -49,7 +47,9 @@ export function createTelegramAssistantOutputBindingRuntime<
 >(deps: {
   isEnabled: () => boolean;
   authority: {
-    getPreferredTarget: () => OutboundAttachments.TelegramQueuedOutboundAttachmentTurnView["target"] | undefined;
+    getPreferredTarget: () =>
+      | OutboundAttachments.TelegramQueuedOutboundAttachmentTurnView["target"]
+      | undefined;
     getFallbackChatId: () => number | undefined;
     getTransportStamp: () => TTransportStamp;
     isTransportStampActive: (stamp: TTransportStamp) => boolean;
@@ -63,8 +63,9 @@ export function createTelegramAssistantOutputBindingRuntime<
   >[0];
   recordRuntimeEvent: TelegramRuntimeEventRecorder;
 }): TelegramAssistantOutputBindingRuntime<TTransportStamp> {
-  const authority =
-    Routing.createTelegramAssistantOutputAuthorityRuntime(deps.authority);
+  const authority = Routing.createTelegramAssistantOutputAuthorityRuntime(
+    deps.authority,
+  );
   const send =
     OutboundHandlers.createTelegramAssistantOutputSender<TTransportStamp>(
       deps.sender,
@@ -640,6 +641,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     },
     async onSessionShutdown(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
+      agentLifecycleHooks.clearRetainedAgentEnd();
       activityRuntime.onSessionShutdown();
       assistantOutputRuntime.stop();
       compactionObserver.onSessionShutdown();
@@ -706,8 +708,9 @@ export function registerTelegramLifecycleRuntimeHooks({
       activityRuntime.onAgentEnd();
       await agentLifecycleHooks.onAgentEnd(event, ctx);
     },
-    onAgentSettled(_event, ctx) {
+    async onAgentSettled(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
+      await agentLifecycleHooks.onAgentSettled(event, ctx);
       activityRuntime.onAgentSettled();
     },
     onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({

package/lib/config.ts

@@ -17,8 +17,8 @@ import {
 import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
 import { resolveAgentDir, resolveTelegramConfigPath } from "./paths.ts";
 
-import type { TelegramInboundHandlerConfig } from "./inbound.ts";
 import type { CommandTemplateObjectConfig } from "./command-templates.ts";
+import type { TelegramInboundHandlerConfig } from "./inbound.ts";
 import { withTelegramFileTransaction } from "./locks.ts";
 
 const CONFIG_RUNTIME_KEY = "__piTelegramConfigRuntime__";
@@ -72,7 +72,7 @@ export interface TelegramConfig {
   /** @deprecated use assistant.rendering */
   assistantRendering?: TelegramAssistantRenderingMode;
   voice?: {
-    replyMode?: "manual" | "mirror" | "always";
+    replyMode?: "hidden" | "mirror" | "always";
     /** Whether to attach the provider's transcriptText as caption on voice messages */
     sendTranscript?: boolean;
   };
@@ -543,6 +543,27 @@ export function createTelegramConfigStore(
   };
 }
 
+export function createTelegramPollingOffsetPersister(
+  configStore: Pick<TelegramConfigStore, "get" | "set" | "persist">,
+  persist: () => Promise<void> = () => configStore.persist(),
+): (pollingConfig: { lastUpdateId?: number }) => Promise<void> {
+  return async (pollingConfig) => {
+    const nextOffset = pollingConfig.lastUpdateId;
+    if (typeof nextOffset === "number") {
+      const current = configStore.get();
+      const currentOffset = current.lastUpdateId;
+      configStore.set({
+        ...current,
+        lastUpdateId:
+          typeof currentOffset === "number"
+            ? Math.max(currentOffset, nextOffset)
+            : nextOffset,
+      });
+    }
+    await persist();
+  };
+}
+
 export function createTelegramProactivePushChecker(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => boolean {
@@ -625,12 +646,10 @@ export function createTelegramAssistantRenderingModeSetter(
 
 export function createTelegramVoiceReplyModeGetter(
   configStore: Pick<TelegramConfigStore, "get">,
-): () => "manual" | "mirror" | "always" {
+): () => "hidden" | "mirror" | "always" {
   return () => {
     const mode = configStore.get().voice?.replyMode;
-    return mode === "mirror" || mode === "always" || mode === "manual"
-      ? mode
-      : "manual";
+    return mode === "mirror" || mode === "always" ? mode : "hidden";
   };
 }
 
@@ -639,17 +658,17 @@ export function createTelegramVoiceReplyModeConfiguredChecker(
 ): () => boolean {
   return () => {
     const mode = configStore.get().voice?.replyMode;
-    return mode === "mirror" || mode === "always" || mode === "manual";
+    return mode === "mirror" || mode === "always";
   };
 }
 
 export function createTelegramVoiceReplyModeSetter(
   configStore: TelegramMutableConfigStore,
-): (replyMode: "manual" | "mirror" | "always" | undefined) => Promise<void> {
+): (replyMode: "hidden" | "mirror" | "always" | undefined) => Promise<void> {
   return async (replyMode) => {
     await loadLatestTelegramConfig(configStore);
     const current = configStore.get();
-    if (replyMode === undefined) {
+    if (replyMode === undefined || replyMode === "hidden") {
       const { replyMode: _replyMode, ...remainingVoice } = current.voice ?? {};
       const next = { ...current };
       if (Object.keys(remainingVoice).length > 0) next.voice = remainingVoice;

package/lib/menu-settings.ts

@@ -4,10 +4,6 @@
  * Owns hidden settings-menu rendering, settings callbacks, and persisted toggle wiring
  */
 
-import {
-  getTelegramExtensionSettingsRows,
-  type TelegramSectionRegistry,
-} from "./sections.ts";
 import type {
   TelegramAssistantRenderingMode,
   TelegramTimeMode,
@@ -15,6 +11,10 @@ import type {
 import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
 import type { TelegramModelMenuState } from "./menu-model.ts";
 import type { MenuModel } from "./model.ts";
+import {
+  getTelegramExtensionSettingsRows,
+  type TelegramSectionRegistry,
+} from "./sections.ts";
 import type { TelegramVoiceReplyMode } from "./voice.ts";
 
 export type TelegramSettingsMenuReplyMarkup = TelegramInlineKeyboardMarkup;
@@ -74,7 +74,11 @@ export interface TelegramSettingsMenuRuntime<TContext> {
     query: {
       id: string;
       data?: string;
-      message?: { message_id?: number; chat?: { id?: number } };
+      message?: {
+        message_id?: number;
+        message_thread_id?: number;
+        chat?: { id?: number };
+      };
     },
     ctx: TContext,
   ) => Promise<boolean>;
@@ -98,6 +102,7 @@ export interface TelegramSettingsMenuRuntimeDeps<
   getModelMenuState: (
     chatId: number,
     ctx: TContext,
+    threadId?: number,
   ) => Promise<TelegramModelMenuState<TModel>>;
   getStoredModelMenuState: (
     messageId: number | undefined,
@@ -201,10 +206,9 @@ export function buildVoiceReplyModeSettingsText(
     "",
     "Controls when pi-telegram converts assistant text replies into Telegram voice messages.",
     "",
-    "<code>-</code> <code>hidden</code> (default): same behavior as 'manual', but no voice policy is added to prompt context.",
-    "<code>-</code> <code>manual</code>: agent decides; explicit 'telegram_voice' markup still works and reply mode is visible in prompt context.",
-    "<code>-</code> <code>mirror</code>: voice input prefers a voice reply; text input gracefully follows 'manual' behavior.",
-    "<code>-</code> <code>always</code>: every reply is converted to voice when delivery succeeds.",
+    "<code>-</code> <code>hidden</code> (default): add no automatic voice context; explicit 'telegram_voice' actions still work.",
+    "<code>-</code> <code>mirror</code>: voice input activates automatic voice delivery; text input follows 'hidden' behavior.",
+    "<code>-</code> <code>always</code>: activate automatic voice delivery for every reply.",
   ].join("\n");
 }
 
@@ -225,18 +229,19 @@ export function buildTimeInjectionModeSettingsText(
 export function buildTelegramSettingsMenuReplyMarkup(
   proactivePushEnabled: boolean,
   draftPreviewsEnabled: boolean,
-  assistantRenderingModeOrVoiceReplyMode: TelegramAssistantRenderingMode | TelegramVoiceReplyMode,
+  assistantRenderingModeOrVoiceReplyMode:
+    TelegramAssistantRenderingMode | TelegramVoiceReplyMode,
   voiceReplyModeOrTimeInjectionMode: TelegramVoiceReplyMode | TelegramTimeMode,
-  timeInjectionModeOrSectionRegistry?: TelegramTimeMode | TelegramSectionRegistry,
+  timeInjectionModeOrSectionRegistry?:
+    TelegramTimeMode | TelegramSectionRegistry,
   sectionRegistryOrVoiceReplyModeConfigured?: TelegramSectionRegistry | boolean,
   voiceReplyModeConfigured = true,
 ): TelegramSettingsMenuReplyMarkup {
   const hasRenderingMode =
     assistantRenderingModeOrVoiceReplyMode === "rich" ||
     assistantRenderingModeOrVoiceReplyMode === "html";
-  const assistantRenderingMode: TelegramAssistantRenderingMode = hasRenderingMode
-    ? assistantRenderingModeOrVoiceReplyMode
-    : "rich";
+  const assistantRenderingMode: TelegramAssistantRenderingMode =
+    hasRenderingMode ? assistantRenderingModeOrVoiceReplyMode : "rich";
   const voiceReplyMode = hasRenderingMode
     ? (voiceReplyModeOrTimeInjectionMode as TelegramVoiceReplyMode)
     : (assistantRenderingModeOrVoiceReplyMode as TelegramVoiceReplyMode);
@@ -245,9 +250,9 @@ export function buildTelegramSettingsMenuReplyMarkup(
     : (voiceReplyModeOrTimeInjectionMode as TelegramTimeMode);
   const sectionRegistry = hasRenderingMode
     ? (sectionRegistryOrVoiceReplyModeConfigured as
-        | TelegramSectionRegistry
-        | undefined)
-    : (timeInjectionModeOrSectionRegistry as TelegramSectionRegistry | undefined);
+        TelegramSectionRegistry | undefined)
+    : (timeInjectionModeOrSectionRegistry as
+        TelegramSectionRegistry | undefined);
   const effectiveVoiceReplyModeConfigured = hasRenderingMode
     ? voiceReplyModeConfigured
     : typeof sectionRegistryOrVoiceReplyModeConfigured === "boolean"
@@ -268,7 +273,10 @@ export function buildTelegramSettingsMenuReplyMarkup(
       {
         text: `👄 Voice reply: ${getTelegramSettingsStateValueLabel(
           getVoiceReplyModeLabel(
-            getVoiceReplyModeSetting(voiceReplyMode, effectiveVoiceReplyModeConfigured),
+            getVoiceReplyModeSetting(
+              voiceReplyMode,
+              effectiveVoiceReplyModeConfigured,
+            ),
           ),
         )}`,
         callback_data: "settings:open:voice-reply",
@@ -361,7 +369,7 @@ export function buildDraftPreviewsSettingsReplyMarkup(
         },
         {
           text: enabled ? "⚫️ Off" : "🟡 Off",
-          callback_data: "settings:set:draft-previews:off"
+          callback_data: "settings:set:draft-previews:off",
         },
       ],
     ],
@@ -407,12 +415,7 @@ export function buildVoiceReplyModeSettingsReplyMarkup(
   configured = true,
 ): TelegramSettingsMenuReplyMarkup {
   const activeMode = getVoiceReplyModeSetting(mode, configured);
-  const modes: TelegramVoiceReplyModeSetting[] = [
-    "hidden",
-    "manual",
-    "mirror",
-    "always",
-  ];
+  const modes: TelegramVoiceReplyModeSetting[] = ["hidden", "mirror", "always"];
   return {
     inline_keyboard: [
       [{ text: "⬆️ Back", callback_data: "settings:list" }],
@@ -511,7 +514,10 @@ export async function handleTelegramSettingsMenuCallbackAction(
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
-  if (data === "settings:open:draft-previews" || data === "settings:open:rich-drafts") {
+  if (
+    data === "settings:open:draft-previews" ||
+    data === "settings:open:rich-drafts"
+  ) {
     await updateDraftPreviewsSettingsMessage(deps);
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
@@ -536,12 +542,7 @@ export async function handleTelegramSettingsMenuCallbackAction(
   }
   if (data.startsWith("settings:set:voice-reply:")) {
     const mode = data.slice("settings:set:voice-reply:".length);
-    if (
-      mode === "hidden" ||
-      mode === "manual" ||
-      mode === "mirror" ||
-      mode === "always"
-    ) {
+    if (mode === "hidden" || mode === "mirror" || mode === "always") {
       await deps.setVoiceReplyMode(mode === "hidden" ? undefined : mode);
       await updateVoiceReplyModeSettingsMessage(deps);
       await deps.answerCallbackQuery(
@@ -663,79 +664,27 @@ export function createTelegramSettingsMenuRuntime<
         },
         sectionRegistry,
       ),
-    handleCallbackQuery: async (query) => {
+    handleCallbackQuery: async (query, ctx) => {
       if (!query.data?.startsWith("settings:")) return false;
-      const state = deps.getStoredModelMenuState(
-        query.message?.message_id,
-        query.message?.chat?.id,
-      );
+      const messageId = query.message?.message_id;
+      const chatId = query.message?.chat?.id;
+      let state = deps.getStoredModelMenuState(messageId, chatId);
       if (!state) {
-        const voiceMode = query.data.slice("settings:set:voice-reply:".length);
-        if (
-          query.data.startsWith("settings:set:voice-reply:") &&
-          (voiceMode === "hidden" ||
-            voiceMode === "manual" ||
-            voiceMode === "mirror" ||
-            voiceMode === "always")
-        ) {
-          await deps.setVoiceReplyMode(
-            voiceMode === "hidden" ? undefined : voiceMode,
-          );
-          await deps.answerCallbackQuery(
-            query.id,
-            `Voice reply mode: ${voiceMode}`,
-          );
-          return true;
-        }
-        if (
-          query.data === "settings:set:draft-previews:on" ||
-          query.data === "settings:set:draft-previews:off" ||
-          query.data === "settings:set:rich-drafts:on" ||
-          query.data === "settings:set:rich-drafts:off"
-        ) {
-          const enabled = query.data.endsWith(":on");
-          await deps.setDraftPreviewsEnabled(enabled);
-          await deps.answerCallbackQuery(
-            query.id,
-            `Draft previews ${enabled ? "enabled" : "disabled"}`,
-          );
-          return true;
-        }
-        if (query.data.startsWith("settings:set:assistant-rendering:")) {
-          const mode = query.data.slice("settings:set:assistant-rendering:".length);
-          if (mode === "rich" || mode === "html") {
-            await deps.setAssistantRenderingMode(mode);
-            await deps.answerCallbackQuery(query.id, `Rendering: ${mode}`);
-            return true;
-          }
-        }
-        const hasTimeInjectionPrefix = query.data.startsWith(
-          "settings:set:time-injection:",
-        );
-        const timeMode = hasTimeInjectionPrefix
-          ? query.data.slice("settings:set:time-injection:".length)
-          : query.data.slice("settings:set:time:".length);
-        if (
-          (hasTimeInjectionPrefix ||
-            query.data.startsWith("settings:set:time:")) &&
-          (timeMode === "off" ||
-            timeMode === "hidden" ||
-            timeMode === "always" ||
-            timeMode === "interval")
-        ) {
-          const normalizedMode = timeMode === "off" ? "hidden" : timeMode;
-          await deps.setTimeInjectionMode(normalizedMode);
+        if (typeof messageId !== "number" || typeof chatId !== "number") {
           await deps.answerCallbackQuery(
             query.id,
-            `Time injection: ${normalizedMode}`,
+            "Interactive message expired.",
           );
           return true;
         }
-        await deps.answerCallbackQuery(
-          query.id,
-          "Interactive message expired.",
+        state = await deps.getModelMenuState(
+          chatId,
+          ctx,
+          query.message?.message_thread_id,
         );
-        return true;
+        state.messageId = messageId;
+        state.mode = "settings";
+        deps.storeModelMenuState(state);
       }
       return handleTelegramSettingsMenuCallbackAction(query.id, query.data, {
         isProactivePushEnabled: deps.isProactivePushEnabled,

package/lib/prompts.ts

@@ -16,7 +16,7 @@ Telegram bridge available. Do not use it from local/TUI prompts unless explicitl
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram turn note: If context was compacted or you need the pi-telegram bridge contract, call tool \`telegram_help\`; hidden comments are valid only for explicit \`telegram_voice\` or \`telegram_button\` actions with payload. For voice use a top-level HTML action: \`<!-- telegram_voice: Speak this. -->\`, multiline \`<!-- telegram_voice lang=ru\nSpeak this.\n-->\`, or paired \`<!-- telegram_voice lang=ru -->\nSpeak this.\n<!-- /telegram_voice -->\`.`;
+Telegram turn note: Call \`telegram_help\` if you need the pi-telegram bridge action contract.`;
 
 function buildTelegramHelpText(profileName?: string): string {
   const diagnosticsPaths = getTelegramDiagnosticsDisplayPaths(profileName);
@@ -26,7 +26,8 @@ How to understand Telegram turns:
 - \`[telegram|thread:name|from:user|guest:group]\` marks Telegram origin and attributes.
 - \`thread\` is the visible Thread identity in Threaded Mode; it is not a bus role.
 - \`[reply]\` is quoted context only; act on the user's current instruction.
-- \`[attachments]\` are local files; \`[outputs]\` are handler results/transcripts; \`[time]\` is wall-clock context; \`[voice]\` gives reply-mode policy.
+- \`[attachments]\` are local files; \`[outputs]\` are handler results/transcripts; \`[time]\` is wall-clock context.
+- \`[voice] delivery: automatic voice\` means pi-telegram will synthesize ordinary assistant text for this turn; no \`[voice]\` line means no automatic voice policy.
 
 How to answer Telegram turns:
 - Reply in concise, scannable mobile Telegram Rich Markdown.
@@ -41,6 +42,7 @@ Assistant-authored Telegram actions:
 - Keep the complete action at top level and include a non-empty voice payload.
 - Keep voice text TTS-friendly; avoid raw Markdown, code, and tables in voice text.
 - Voice delivery generates and attaches OGG automatically; do not also call \`telegram_attach\` for the same audio.
+- Voice reply modes are compact: \`hidden\` emits no automatic context, \`mirror\` emits it for voice/audio input, and \`always\` emits it for every Telegram turn. Explicit \`telegram_voice\` remains available for an intentionally distinct spoken payload.
 - Button forms: \`<!-- telegram_button: OK -->\`, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\`, or multiline \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\`.
 - If hidden comments would be the whole reply, add visible text such as \`Choose one:\`.
 

package/lib/queue.ts

@@ -850,14 +850,55 @@ export function createTelegramAgentLifecycleHooks<
     TReplyMarkup
   >,
 ) {
+  const onAgentStart = createTelegramAgentStartHook<TTurn, TContext>(deps);
+  const deliverAgentEnd = createTelegramAgentEndHook<
+    TTurn,
+    TContext,
+    TMessage,
+    TReplyMarkup
+  >(deps);
+  let retainedErrorEvent: TelegramAgentEndHookEvent<TMessage> | undefined;
   return {
-    onAgentStart: createTelegramAgentStartHook<TTurn, TContext>(deps),
-    onAgentEnd: createTelegramAgentEndHook<
-      TTurn,
-      TContext,
-      TMessage,
-      TReplyMarkup
-    >(deps),
+    onAgentStart,
+    async onAgentEnd(
+      event: TelegramAgentEndHookEvent<TMessage>,
+      ctx: TContext,
+    ): Promise<void> {
+      const turn = deps.getActiveTurn();
+      const assistant = turn ? deps.extractAssistant(event.messages) : {};
+      if (turn && assistant.stopReason === "error") {
+        retainedErrorEvent = event;
+        deps.recordRuntimeEvent?.(
+          "provider-retry",
+          new Error("Retained Telegram turn after retryable agent error"),
+          { phase: "retained", hasFinalText: !!assistant.text?.trim() },
+        );
+        return;
+      }
+      if (retainedErrorEvent) {
+        retainedErrorEvent = undefined;
+        deps.recordRuntimeEvent?.(
+          "provider-retry",
+          new Error("Recovered retained Telegram turn after agent retry"),
+          { phase: "recovered" },
+        );
+      }
+      await deliverAgentEnd(event, ctx, assistant);
+    },
+    async onAgentSettled(_event: unknown, ctx: TContext): Promise<void> {
+      const event = retainedErrorEvent;
+      if (!event) return;
+      retainedErrorEvent = undefined;
+      deps.recordRuntimeEvent?.(
+        "provider-retry",
+        new Error("Finalized retained Telegram turn after agent settled"),
+        { phase: "settled-failure" },
+      );
+      await deliverAgentEnd(event, ctx);
+    },
+    clearRetainedAgentEnd(): void {
+      retainedErrorEvent = undefined;
+    },
     ...createTelegramToolExecutionHooks<TContext>(deps),
   };
 }
@@ -1132,13 +1173,16 @@ export function createTelegramAgentEndHook<
   return async (
     event: TelegramAgentEndHookEvent<TMessage>,
     ctx: TContext,
+    assistantOverride?: TelegramAgentEndAssistantResult,
   ): Promise<void> => {
     await deps.loadConfig?.();
     if (deps.isSessionActive && !deps.isSessionActive(ctx)) return;
     const turn = deps.getActiveTurn();
     await handleTelegramAgentEndRuntime({
       turn,
-      assistant: turn ? deps.extractAssistant(event.messages) : {},
+      assistant:
+        assistantOverride ??
+        (turn ? deps.extractAssistant(event.messages) : {}),
       foldQueuedPromptsIntoHistory: deps.getFoldQueuedPromptsIntoHistory(),
       resetRuntimeState: deps.resetRuntimeState,
       isSessionActive: () => deps.isSessionActive?.(ctx) ?? true,

package/lib/routing.ts

@@ -9,7 +9,6 @@ import { basename, dirname } from "node:path";
 import * as Bus from "./bus.ts";
 import * as Commands from "./commands.ts";
 import type { TelegramConfigStore } from "./config.ts";
-import type { TelegramSectionRegistry } from "./sections.ts";
 import type { TelegramInboundHandlerRuntime } from "./inbound.ts";
 import * as Media from "./media.ts";
 import * as Menu from "./menu.ts";
@@ -18,12 +17,13 @@ import * as OutboundHandlers from "./outbound.ts";
 import * as PromptTemplates from "./prompt-templates.ts";
 import * as Queue from "./queue.ts";
 import type { TelegramBridgeRuntime } from "./runtime.ts";
+import type { TelegramSectionRegistry } from "./sections.ts";
 import * as TextGroups from "./text-groups.ts";
+import * as ThreadReconciler from "./thread-reconciler.ts";
 import type {
   TelegramInstanceThreadIdentityCandidate,
   TelegramTopicTargetRecord,
 } from "./threads.ts";
-import * as ThreadReconciler from "./thread-reconciler.ts";
 import * as Turns from "./turns.ts";
 
 interface TelegramPromptPeerView {
@@ -408,10 +408,10 @@ function formatTelegramUnboundRerouteChooserText(
     : [formatTelegramUnboundTopicGuidance(), "", rerouteText].join("\n");
 }
 
-import { getTelegramVoiceReplyMode } from "./voice.ts";
-import type { TelegramUser } from "./updates.ts";
 import * as Threads from "./threads.ts";
+import type { TelegramUser } from "./updates.ts";
 import * as Updates from "./updates.ts";
+import { getTelegramVoiceReplyMode } from "./voice.ts";
 
 async function deleteReservedTelegramTopicThroughReconciler(
   deps: {
@@ -1524,13 +1524,8 @@ export function createTelegramInboundRouteRuntime<
     resolveTimeLine: deps.resolveTimeLine,
     getAllowedUserId: deps.configStore.getAllowedUserId,
 
-    // Voice policy for the current turn. Missing config still behaves as manual,
-    // but only explicit telegram.json voice.replyMode is shown in prompt context.
+    // Voice policy resolves missing, invalid, and legacy manual config to hidden.
     getVoiceReplyMode: () => getTelegramVoiceReplyMode(deps.configStore.get()),
-    isVoiceReplyModeConfigured: () => {
-      const mode = deps.configStore.get().voice?.replyMode;
-      return mode === "manual" || mode === "mirror" || mode === "always";
-    },
     getTelegramThreadLabel(message) {
       if (!deps.threadStore) return undefined;
       const chatId = message.chat.id;
@@ -2490,7 +2485,9 @@ export interface TelegramAssistantOutputAuthorityRuntime<TTransportStamp> {
   canDeliver: () => boolean;
 }
 
-export function createTelegramAssistantOutputAuthorityRuntime<TTransportStamp>(deps: {
+export function createTelegramAssistantOutputAuthorityRuntime<
+  TTransportStamp,
+>(deps: {
   getPreferredTarget: () => Queue.TelegramQueueTarget | undefined;
   getFallbackChatId: () => number | undefined;
   getTransportStamp: () => TTransportStamp;
@@ -2509,9 +2506,7 @@ export function createTelegramAssistantOutputAuthorityRuntime<TTransportStamp>(d
   return {
     captureAuthority() {
       const target = getCurrentTarget();
-      const directEpoch = deps.ownsDirect()
-        ? deps.getDirectEpoch()
-        : undefined;
+      const directEpoch = deps.ownsDirect() ? deps.getDirectEpoch() : undefined;
       const followerGeneration = deps.isFollowerRegistered()
         ? deps.getFollowerGeneration()
         : undefined;
@@ -2540,8 +2535,7 @@ export function createTelegramAssistantOutputAuthorityRuntime<TTransportStamp>(d
       }
       if (authority.route === "direct") {
         return (
-          deps.ownsDirect() &&
-          deps.getDirectEpoch() === authority.directEpoch
+          deps.ownsDirect() && deps.getDirectEpoch() === authority.directEpoch
         );
       }
       if (authority.route === "follower") {

package/lib/status.ts

@@ -767,7 +767,7 @@ export function buildTelegramStatusBarText(
 ): string {
   const label = theme.fg("accent", getTelegramStatusBarLabel(state));
   if (state.error) {
-    return `${label} ${theme.fg("error", "error")} ${theme.fg("muted", state.error)}`;
+    return `${label} ${theme.fg("error", "error")}`;
   }
   const queued = state.queuedStatus
     ? theme.fg("success", state.queuedStatus)

package/lib/text-groups.ts

@@ -39,7 +39,7 @@ export interface TelegramTextGroupState<TMessage, TContext = unknown> {
   suspended?: boolean;
   reschedule?: (delayMs?: number) => void;
   dispatchLimit?: number;
-  forwardCommentCandidate?: boolean;
+  forwardPairCandidate?: TelegramForwardCommentBatchPosition;
 }
 
 export type TelegramForwardCommentBatchPosition = "comment" | "forward";
@@ -131,7 +131,12 @@ function getTelegramTextGroupKey(
 ): string | undefined {
   if (message.media_group_id) return undefined;
   if (!message.from || message.from.is_bot) return undefined;
-  if (!extractTelegramTextGroupText(message)) return undefined;
+  if (
+    !extractTelegramTextGroupText(message) &&
+    !isTelegramForwardedMessage(message)
+  ) {
+    return undefined;
+  }
   const threadKey =
     typeof message.message_thread_id === "number"
       ? `thread:${message.message_thread_id}`
@@ -160,7 +165,7 @@ function canAppendTelegramTextGroupMessage<
     message.message_id > previous.message_id &&
     message.message_id <=
       previous.message_id + TELEGRAM_TEXT_GROUP_MAX_MESSAGE_ID_GAP &&
-    text.length > 0 &&
+    (text.length > 0 || isTelegramForwardedMessage(message)) &&
     !isTelegramTextGroupCommand(text)
   );
 }
@@ -182,7 +187,7 @@ export function queueTelegramTextGroupMessage<
   ) => unknown | Promise<unknown>;
   forceStart?: boolean;
   dispatchImmediately?: boolean;
-  forwardCommentCandidate?: boolean;
+  forwardPairCandidate?: TelegramForwardCommentBatchPosition;
   delayMs?: number;
 }): boolean {
   const key = getTelegramTextGroupKey(options.message);
@@ -202,7 +207,7 @@ export function queueTelegramTextGroupMessage<
   const state = existing ?? { messages: [] };
   state.messages.push(options.message);
   state.context = options.context;
-  state.forwardCommentCandidate = options.forwardCommentCandidate;
+  state.forwardPairCandidate = options.forwardPairCandidate;
   const dispatchQueued = (): void => {
       state.flushTimer = undefined;
       const queued = options.groups.get(key);
@@ -335,21 +340,30 @@ export function createTelegramTextGroupController<
         if (existing.flushTimer) clearTimer(existing.flushTimer);
         groups.delete(key!);
       }
+      const candidatePosition: TelegramForwardCommentBatchPosition = forwarded
+        ? "forward"
+        : "comment";
+      const existingCandidate = existing?.forwardPairCandidate;
+      const pairCompleted =
+        existingCandidate !== undefined &&
+        existingCandidate !== candidatePosition;
       const separateFromCandidate =
-        !!existing?.forwardCommentCandidate &&
-        !forwarded &&
+        existingCandidate === candidatePosition &&
         !isTelegramTextGroupCommand(text);
-      if (separateFromCandidate) {
+      if (separateFromCandidate && existing) {
         existing.dispatchLimit = existing.messages.length;
       }
       const forceStart =
         plannedStart ||
         (forwardCommentWaitMs !== false &&
-          !forwarded &&
           !!key &&
-          typeof message.text === "string" &&
-          !isTelegramTextGroupCommand(extractTelegramTextGroupText(message)));
+          (forwarded ||
+            (typeof message.text === "string" &&
+              !isTelegramTextGroupCommand(
+                extractTelegramTextGroupText(message),
+              ))));
       const dispatchImmediately =
+        pairCompleted ||
         separateFromCandidate ||
         plannedForwardCommentEnds.delete(identity) ||
         (forwarded && !!key && groups.has(key));
@@ -364,10 +378,10 @@ export function createTelegramTextGroupController<
         dispatchMessages,
         forceStart,
         dispatchImmediately,
-        forwardCommentCandidate:
-          forceStart &&
-          !forwarded &&
-          !canStartTelegramTextGroup(message, minSplitLength),
+        forwardPairCandidate:
+          forceStart && !canStartTelegramTextGroup(message, minSplitLength)
+            ? candidatePosition
+            : undefined,
         delayMs:
           forceStart && !canStartTelegramTextGroup(message, minSplitLength)
             ? forwardCommentWaitMs === false

package/lib/turns.ts

@@ -13,9 +13,9 @@ import {
   collectTelegramMessageIds,
   downloadTelegramMessageFiles,
   extractTelegramForwardContextText,
-  extractTelegramMessageText,
   extractTelegramMessagesPromptText,
   extractTelegramMessagesText,
+  extractTelegramMessageText,
   formatTelegramHistoryText,
   guessMediaType,
   type DownloadedTelegramMessageFile,
@@ -59,14 +59,19 @@ export interface TelegramTurnMessage {
 
 export type DownloadedTelegramTurnFile = DownloadedTelegramMessageFile;
 
-function getTelegramTurnTarget(message: TelegramTurnMessage): TelegramTurnTarget {
+function getTelegramTurnTarget(
+  message: TelegramTurnMessage,
+): TelegramTurnTarget {
   return Number.isInteger(message.message_thread_id)
     ? { chatId: message.chat.id, threadId: message.message_thread_id }
     : { chatId: message.chat.id };
 }
 
 function formatTelegramPrefixAttributeValue(value: string): string {
-  return value.replace(/[\]\n\r|]+/g, " ").replace(/\s+/g, " ").trim();
+  return value
+    .replace(/[\]\n\r|]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
 }
 
 export function createTelegramTurnPrefix(
@@ -142,7 +147,6 @@ function appendTelegramSourceContext(
   return text ? `${text}\n\n${sourceContext}` : sourceContext;
 }
 
-
 function buildTelegramForwardContextBlock(options: {
   context: string;
   text: string;
@@ -411,7 +415,6 @@ export interface BuildTelegramPromptTurnOptions {
   readBinaryFile: (path: string) => Promise<Uint8Array>;
   inferImageMimeType: (path: string) => string | undefined;
   voiceReplyMode?: TelegramVoiceReplyMode;
-  voiceReplyModeConfigured?: boolean;
   voicePromptContribution?: string;
 }
 
@@ -435,9 +438,11 @@ export interface TelegramPromptTurnRuntimeBuilderDeps<
   }>;
   resolveTimeLine?: (chatId: number) => string | null;
   getVoiceReplyMode?: () => TelegramVoiceReplyMode;
-  isVoiceReplyModeConfigured?: () => boolean;
   /** Returns the visible thread label for a message target, used to add thread context to the prompt prefix. */
-  getTelegramThreadLabel?: (message: { chat: { id: number }; message_thread_id?: number }) => string | undefined;
+  getTelegramThreadLabel?: (message: {
+    chat: { id: number };
+    message_thread_id?: number;
+  }) => string | undefined;
   getAllowedUserId?: () => number | undefined;
 }
 
@@ -475,9 +480,7 @@ export function createTelegramPromptTurnRuntimeBuilder<
               text: extractTelegramMessageText(message),
               message,
               fileNames: new Set(
-                collectTelegramFileInfos(message.rich_message ? [message] : []).map(
-                  (file) => file.fileName,
-                ),
+                collectTelegramFileInfos([message]).map((file) => file.fileName),
               ),
             },
           ]
@@ -567,7 +570,6 @@ export function createTelegramPromptTurnRuntimeBuilder<
       timeLine,
       inferImageMimeType: guessMediaType,
       voiceReplyMode,
-      voiceReplyModeConfigured: deps.isVoiceReplyModeConfigured?.(),
       voicePromptContribution: computeVoicePromptContribution(
         voiceReplyMode,
         files,
@@ -581,9 +583,13 @@ function getTelegramVoicePromptContext(
   voiceReplyMode: TelegramVoiceReplyMode,
   hasVoiceFile: boolean,
 ): Record<string, string> | undefined {
-  if (voiceReplyMode === "always") return { "reply mode": "always" };
-  if (!hasVoiceFile) return undefined;
-  return { "reply mode": voiceReplyMode };
+  if (
+    voiceReplyMode !== "always" &&
+    !(voiceReplyMode === "mirror" && hasVoiceFile)
+  ) {
+    return undefined;
+  }
+  return { delivery: "automatic voice" };
 }
 
 export async function buildTelegramPromptTurn(
@@ -597,8 +603,6 @@ export async function buildTelegramPromptTurn(
     (f) => f.kind === "voice" || f.kind === "audio",
   );
   const voiceReplyMode = options.voiceReplyMode ?? getTelegramVoiceReplyMode();
-  const showVoiceContext =
-    options.voiceReplyModeConfigured ?? options.voiceReplyMode !== undefined;
   const content: TelegramPromptContent[] = [
     {
       type: "text",
@@ -615,9 +619,10 @@ export async function buildTelegramPromptTurn(
         sourceContext: options.sourceContext,
         historyTurns: options.historyTurns,
         timeLine: options.timeLine,
-        voiceContext: showVoiceContext
-          ? getTelegramVoicePromptContext(voiceReplyMode, hasVoiceFile)
-          : undefined,
+        voiceContext: getTelegramVoicePromptContext(
+          voiceReplyMode,
+          hasVoiceFile,
+        ),
       }),
     },
   ];
@@ -634,8 +639,7 @@ export async function buildTelegramPromptTurn(
   }
   if (options.voicePromptContribution?.trim()) {
     const textItem = content.find((c) => c.type === "text") as
-      | { type: "text"; text: string }
-      | undefined;
+      { type: "text"; text: string } | undefined;
     if (textItem) {
       textItem.text = `${textItem.text}\n\n${options.voicePromptContribution.trim()}`;
     }

package/lib/voice.ts

@@ -38,7 +38,7 @@ function getNextAvailableProviderId<T>(
   return id;
 }
 
-export type TelegramVoiceReplyMode = "mirror" | "always" | "manual";
+export type TelegramVoiceReplyMode = "hidden" | "mirror" | "always";
 
 export type TelegramVoiceSynthesisProviderResult =
   | string
@@ -67,9 +67,7 @@ export interface TelegramVoiceSynthesisProvider {
 }
 
 export type TelegramVoiceTranscriptionProviderResult =
-  | string
-  | { text: string; language?: string }
-  | undefined;
+  string | { text: string; language?: string } | undefined;
 
 export interface TelegramVoiceTranscriptionFile {
   path: string;
@@ -217,16 +215,17 @@ export function clearTelegramVoiceTranscriptionProviders(): void {
 // --- Voice Reply Modes ---
 
 export const TELEGRAM_VOICE_REPLY_MODES = [
+  "hidden",
   "mirror",
   "always",
-  "manual",
 ] as const;
 
 /**
  * Returns the active voice reply mode for the current session.
  *
  * Pi-telegram owns reply-mode policy through telegram.json. If
- * config.voice.replyMode is missing or invalid, the safe default is manual.
+ * config.voice.replyMode is missing, invalid, or legacy `manual`, the effective
+ * mode is hidden.
  */
 export function getTelegramVoiceReplyMode(config?: {
   voice?: { replyMode?: string };
@@ -238,7 +237,7 @@ export function getTelegramVoiceReplyMode(config?: {
   ) {
     return configMode as TelegramVoiceReplyMode;
   }
-  return "manual";
+  return "hidden";
 }
 
 /**

package/package.json

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