@llblab/pi-kit 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.1.9 - 2026-08-24
+
+- `Telegram Release`: Advances `@llblab/pi-telegram` to `0.38.0`, presenting the default voice mode as `manual`, retaining legacy `hidden` compatibility, and removing the redundant transcript-caption configuration and provider contract.
+
 ## 0.1.8 - 2026-08-23
 
 - `Telegram Releases`: Advances `@llblab/pi-telegram` to `0.37.1`, bringing journal-owned polling admission state from `0.37.0` plus the settings-manager compatibility hotfix for `/start`, model, and queue menus.

package/README.md

@@ -9,7 +9,7 @@
 | `@llblab/pi-actors` | `0.50.0` | Extension and Skills |
 | `@llblab/pi-codex-usage` | `0.9.3` | Extension |
 | `@llblab/pi-grow-loop` | `0.7.2` | Extension and Skills |
-| `@llblab/pi-telegram` | `0.37.1` | Extension and Skills |
+| `@llblab/pi-telegram` | `0.38.0` | Extension and Skills |
 
 Versions are exact by design. Updating an extension does not change an installed kit until this repository explicitly advances that dependency and publishes a new kit version.
 

package/node_modules/@llblab/pi-telegram/BACKLOG.md

@@ -2,6 +2,7 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
+- [ ] `Coherent voice reply policy`: Release the validated `manual`, `mirror`, and `always` policy cleanup as `0.38.0`, then reconcile issue #235 and open exact migration issues for `johnlam1968/pi-voice-telegram` and `luxus/pi-xai-voice`, whose TTS providers still consume the removed transcript-caption API.
 - [ ] `Operator-confirmed pairing`: Replace first-contact automatic ownership with an explicit pending request that the trusted Pi interface can allow or reject before `allowedUserId` is persisted or any Telegram prompt executes; retain manual preconfiguration, bound pending-request lifetime and multiplicity, fail closed across session/transport replacement, and cover unauthorized-first-contact races.
 - [ ] `Environment-backed bot tokens`: Let each profile store an exact Pi-native `$ENV_VAR` or `${ENV_VAR}` reference in `telegram.json` instead of copying the resolved secret; preserve the originating alias when `/telegram-setup` prefills from a supported environment variable, resolve only at validation/activation boundaries, fail closed with a redacted named-variable diagnostic when unresolved, retain literal-token compatibility, and cover named profiles, reload, persistence, status, and secret-redaction paths.
 - [ ] [`Inference bypass Generative Apps`](./docs/generative-apps.md): Let the agent install and bind one managed JavaScript app owner for a generated-prompt prefix so deterministic controls can bypass model inference without creating another button grammar.

package/node_modules/@llblab/pi-telegram/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.38.0: Coherent Voice Reply Policy
+
+- `Voice Reply Policy`: Renames the default user-facing `hidden` mode to `manual` while retaining `hidden` as a read-only configuration and callback compatibility alias. `manual`, `mirror`, and `always` remain the complete policy set: explicit `telegram_voice`, modality mirroring, or automatic voice replacement.
+- `Voice Provider Contract`: Removes the redundant `voice.sendTranscript` configuration, `getTelegramVoiceSendTranscript()` public helper, provider-returned `transcriptText`, and voice-caption path. Synthesis providers now return only an OGG/Opus path or `undefined`; text-plus-voice remains an explicit agent composition rather than a parallel automatic policy.
+
+## 0.37.2: Follower Recovery Delivery Hotfix
+
+- `Follower Recovery Delivery`: Holds follower Bot API calls behind a bounded registration wait when heartbeat recovery temporarily clears local authority, then sends once with the restored exact generation. Calls still fail closed if registration is not restored, and acknowledgement ambiguity remains non-retryable.
+
 ## 0.37.1: Settings Manager Compatibility Hotfix
 
 - `Menu Compatibility`: Keeps `/start`, model, and queue menu rendering compatible with Pi settings-manager implementations that do not expose `reload()`. Hosts with reload retain explicit refresh behavior; other hosts use the freshly constructed settings snapshot instead of failing with `settingsManager.reload is not a function`.

package/node_modules/@llblab/pi-telegram/README.md

@@ -130,7 +130,7 @@ Enable the optional capabilities the bridge needs in the [@BotFather](https://t.
 | 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 | 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. |
+| Voice output | Choose `manual`, `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. |
 | Generative Apps | Install or explicitly replace a reviewed `.mjs` application whose generated JSON button view may mix direct `app::method` actions with ordinary model prompts. | Repeated games, controls, tutors, and adapters compile routine interaction without losing selective model interpretation, explanation, or adaptation. |
 | Callback routing | Route known callbacks to the owner extension and unknown callbacks back into Pi. | Companion extensions can build UI without polling Telegram themselves. |
@@ -218,7 +218,7 @@ Inbound files land under `<agent-dir>/tmp/telegram` and default to a 50 MiB limi
 
 ### Voice And Media
 
-Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. Configure provider-neutral local/API pipelines and ordered fallbacks through [`telegram.json` command templates](./docs/voice.md#choose-an-integration-path). The default `hidden` reply mode still supports intentional voice delivery through explicit `telegram_voice` actions; `mirror` and `always` add automatic voice policy. Explicit actions accept either a JSON object or compact double-quoted attributes, with equivalent `text` and `value` payload keys and one colon-free action marker.
+Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. Configure provider-neutral local/API pipelines and ordered fallbacks through [`telegram.json` command templates](./docs/voice.md#choose-an-integration-path). The default `manual` reply mode still supports intentional voice delivery through explicit `telegram_voice` actions; `mirror` and `always` add automatic voice policy. Explicit actions accept either a JSON object or compact double-quoted attributes, with equivalent `text` and `value` payload keys and one colon-free action marker.
 
 ### Buttons And Callbacks
 

package/node_modules/@llblab/pi-telegram/api/voice.ts

@@ -9,7 +9,6 @@ export {
   computeVoicePromptContribution,
   computeVoiceTurnFlags,
   getTelegramVoiceReplyMode,
-  getTelegramVoiceSendTranscript,
   isVoiceTurn,
   registerTelegramVoiceSynthesisProvider,
   registerTelegramVoiceTranscriptionProvider,

package/node_modules/@llblab/pi-telegram/docs/multi-instance-bus.md

@@ -157,7 +157,7 @@ Leader election is heartbeat-gated and lock-backed. The polling owner checks exa
 4. If the leader heartbeat is stale, attempt an atomic leadership takeover; ordinary `/telegram-connect` on a follower is not a leadership move while the leader is live.
 5. Heartbeat acknowledgements carry the authenticated live follower-slot roster. If several followers detect stale leadership, the lowest observed live slot attempts promotion immediately; higher slots defer one bounded election grace and re-check the lock. Atomic compare/write acquisition remains the final ownership authority, and a missing lower-slot follower cannot block a higher survivor beyond that grace.
 
-Followers first try to re-register after leader reload or unknown-heartbeat responses, carrying their last known target, slot, and thread name so the new leader can reuse the same binding. After the grace window they promote only when the exact observed leader lease has become stale or inactive; an unavailable IPC endpoint never authorizes replacing a still-live owner. If the exact carried target is absent from persisted bindings, the leader first runs the same synchronous visibility probe: success recovers it instead of creating another Telegram thread, explicit stale evidence provisions a replacement, and ambiguous failure rejects registration. An ambiguous absent-target probe persists only non-routable `probe-required` restoration evidence, so targetless retries and leader reloads must probe that exact target again instead of activating it or provisioning a speculative replacement. A carried slot survives only when that slot remains free. Every successful reuse refreshes the binding timestamp. The leader never restores persisted followers into the live registry speculatively. Absent follower records remain durable restart hints until explicit stale, deleted, offline, or reconciliation evidence invalidates them; only fresh authenticated registration creates live routing authority. This preserves real thread bindings through reload and process-absence gaps without allowing historical records or competing pollers to masquerade as live state.
+Followers first try to re-register after leader reload or unknown-heartbeat responses, carrying their last known target, slot, and thread name so the new leader can reuse the same binding. Follower Bot API calls already admitted by the active Pi turn wait for that bounded re-registration and capture its new exact generation before entering transport; they do not fail merely because recovery temporarily cleared local registration, and they never replay after an ambiguous transport commit. After the grace window followers promote only when the exact observed leader lease has become stale or inactive; an unavailable IPC endpoint never authorizes replacing a still-live owner. If the exact carried target is absent from persisted bindings, the leader first runs the same synchronous visibility probe: success recovers it instead of creating another Telegram thread, explicit stale evidence provisions a replacement, and ambiguous failure rejects registration. An ambiguous absent-target probe persists only non-routable `probe-required` restoration evidence, so targetless retries and leader reloads must probe that exact target again instead of activating it or provisioning a speculative replacement. A carried slot survives only when that slot remains free. Every successful reuse refreshes the binding timestamp. The leader never restores persisted followers into the live registry speculatively. Absent follower records remain durable restart hints until explicit stale, deleted, offline, or reconciliation evidence invalidates them; only fresh authenticated registration creates live routing authority. This preserves real thread bindings through reload and process-absence gaps without allowing historical records or competing pollers to masquerade as live state.
 
 ## Leader/Follower Communication
 
@@ -314,7 +314,7 @@ Every outbound request carries its target. The leader injects `message_thread_id
 Threaded Mode should make follower threads behave like normal Telegram instance surfaces, with the leader acting only as transport owner. Any feature in the matrix below that works for the leader must either work for followers or have an explicit documented exception.
 
 | Surface                          | Leader behavior                                                                                                                                                                                                                                       | Follower requirement                                                                                                                                                                                                                                            | Routing/ownership invariant                                                                                                                                                                                                                         | Regression evidence                                                                                                       |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| --- | --- | --- | --- | --- |
 | Prompt intake                    | Thread prompt queues locally                                                                                                                                                                                                                          | Thread prompt is forwarded and queued by the owning follower                                                                                                                                                                                                    | Target ownership routes by `{ chatId, threadId }` before local handling                                                                                                                                                                             | Routing tests for foreign target message forwarding                                                                       |
 | Queued-message removal reactions | 👎/👻/💔/💩/🗑 marks a pending prompt/media turn for deletion when it reaches dispatch                                                                                                                                                                            | Same reaction on a queued follower prompt marks that follower's pending turn for deletion before model dispatch                                                                                                                                                                  | When the leader forwards a prompt to a follower, it records `chatId/messageId -> follower instance` because Bot API reaction updates expose chat/message but not thread id                                                                          | Update runtime regression records forwarded message ownership and forwards the later reaction                             |
 | Queue priority reactions         | 👍/⚡/❤/🕊/🔥 prioritizes queued prompts                                                                                                                                                                                                               | Same reactions prioritize follower queued prompts                                                                                                                                                                                                               | Reaction forwarding uses stored message ownership, then follower mutates its local queue                                                                                                                                                            | Reaction mutation tests plus forwarded-reaction coverage                                                                  |

package/node_modules/@llblab/pi-telegram/docs/outbound.md

@@ -119,14 +119,13 @@ import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/voic
 
 const dispose = registerTelegramVoiceSynthesisProvider(
   async (text, options) => {
-    const audioPath = await synthesizeToOggOpus(text, options);
-    return { audioPath, transcriptText: text };
+    return await synthesizeToOggOpus(text, options);
   },
   { id: "my-extension/tts" },
 );
 ```
 
-Synthesis providers receive the extracted `telegram_voice` text plus optional `lang`/`rate` hints. Stable registrations pass a durable `id`; omitted ids remain a compatibility path for older providers. Providers own translation, TTS, speech rewriting, transcript choice, and OGG/Opus conversion. The bridge validates that the returned file ends in `.ogg` or `.opus`, sends it through Telegram `sendVoice`, and falls back to planned text if delivery fails before any visible text was delivered. Providers run after configured and programmatic voice handlers in the priority chain above.
+Synthesis providers receive the extracted `telegram_voice` text plus optional `lang`/`rate` hints. Stable registrations pass a durable `id`; omitted ids remain a compatibility path for older providers. Providers own translation, TTS, speech rewriting, and OGG/Opus conversion. The bridge validates that the returned file ends in `.ogg` or `.opus`, sends it through Telegram `sendVoice`, and falls back to planned text if delivery fails before any visible text was delivered. Providers run after configured and programmatic voice handlers in the priority chain above.
 
 ## Voice Markup
 

package/node_modules/@llblab/pi-telegram/docs/public-api.md

@@ -99,8 +99,7 @@ interface TelegramConfig {
     timeInjection?: "hidden" | "always" | "interval";
   };
   voice?: {
-    replyMode?: "hidden" | "mirror" | "always";
-    sendTranscript?: boolean;
+    replyMode?: "manual" | "mirror" | "always";
   };
   time?: {
     interval?: number;
@@ -409,16 +408,13 @@ const offStt = registerTelegramVoiceTranscriptionProvider(
 
 const offTts = registerTelegramVoiceSynthesisProvider(
   async (text, options) => {
-    const audioPath = await synthesizeOggOpus(text, options);
-    return getTelegramVoiceSendTranscript(getCurrentTelegramConfigView())
-      ? { audioPath, transcriptText: text }
-      : { audioPath };
+    return await synthesizeOggOpus(text, options);
   },
   { id: "@scope/my-extension/tts" },
 );
 ```
 
-Stable voice-provider registrations pass a durable `id`. Omitting `id` is a compatibility path for older providers and receives a generated session-local id. Providers return `undefined` to pass. TTS providers must return `.ogg` or `.opus` files for native Telegram voice notes. `voice.sendTranscript` is the bridge-owned transcript preference; providers that expose captions should gate `transcriptText` with `getTelegramVoiceSendTranscript(config)` instead of defining a second reply-policy toggle.
+Stable voice-provider registrations pass a durable `id`. Omitting `id` is a compatibility path for older providers and receives a generated session-local id. Providers return `undefined` to pass. TTS providers must return `.ogg` or `.opus` files for native Telegram voice notes.
 
 Full behavior: [Voice Integration](./voice.md).
 
@@ -525,7 +521,6 @@ export default function demoOutbound(pi: ExtensionAPI) {
 ```ts
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
-  getTelegramVoiceSendTranscript,
   registerTelegramVoiceSynthesisProvider,
   registerTelegramVoiceTranscriptionProvider,
 } from "@llblab/pi-telegram/voice";
@@ -533,16 +528,12 @@ import {
 export default function demoVoice(pi: ExtensionAPI) {
   let unregisterTts: (() => void) | undefined;
   let unregisterStt: (() => void) | undefined;
-  let currentConfig: { voice?: { sendTranscript?: boolean } } = {};
   pi.on("session_start", async () => {
     unregisterTts?.();
     unregisterStt?.();
     unregisterTts = registerTelegramVoiceSynthesisProvider(
       async (text) => {
-        const audioPath = await synthesizeDemoOgg(text);
-        return getTelegramVoiceSendTranscript(currentConfig)
-          ? { audioPath, transcriptText: text }
-          : { audioPath };
+        return await synthesizeDemoOgg(text);
       },
       { id: "demo-voice/tts" },
     );

package/node_modules/@llblab/pi-telegram/docs/voice.md

@@ -43,12 +43,12 @@ 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`). Missing, invalid, `hidden`, and legacy `manual` values resolve to the silent `hidden` default.
+The bridge decides **when** to reply with voice from `voice.replyMode` in `TelegramConfig` (stored in `telegram.json`). Missing and invalid values resolve to the `manual` default; the former `hidden` value remains a read-only compatibility alias for `manual`.
 
 ### Modes
 
-- **`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.
+- **`manual` (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 `manual` 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.
@@ -70,7 +70,7 @@ A voice extension may combine three public seams:
 
 - `registerTelegramVoiceTranscriptionProvider()` for inbound STT fallback on voice/audio files
 - `registerTelegramVoiceSynthesisProvider()` for outbound TTS/synthesis fallback to Telegram voice messages
-- `registerTelegramSection()` for provider-specific Telegram UI such as voice, language, style, transcript, or provider on/off controls
+- `registerTelegramSection()` for provider-specific Telegram UI such as voice, language, style, or provider on/off controls
 
 The reply policy itself remains a built-in pi-telegram setting (`voice.replyMode`) rather than a provider-owned menu.
 
@@ -81,10 +81,8 @@ Voice synthesis provider extensions register themselves through `registerTelegra
 - Text optimisation / speech-style rewriting
 - Adding speech tags (when desired)
 - Running TTS + ffmpeg conversion to OGG/Opus
-- Deciding whether to return `transcriptText` at all based on the bridge-owned `voice.sendTranscript` preference when the provider has access to the current Telegram config
-- `transcriptText` (when returned) is attached by the bridge as the voice message **caption** only. Separate transcript messages are no longer sent.
 
-The bridge shows a `record_voice` action while delivering and sends the final audio with Telegram `sendVoice`. When a provider returns `transcriptText`, the bridge attaches it as the voice caption.
+The bridge shows a `record_voice` action while delivering and sends the final audio with Telegram `sendVoice`.
 
 Providers can implement `getVoicePromptContribution(view)` to inject voice-specific instructions into voice-tagged prompts (for example: "Reply only with the spoken text"). The bridge appends the first non-empty provider contribution when `mirror` or `always` mode tags the turn.
 
@@ -95,7 +93,6 @@ The provider receives the raw agent text plus optional `{ lang?, rate? }`.
 It must return one of:
 
 - `string` — path to a ready `.ogg` or `.opus` file
-- `{ audioPath: string, transcriptText?: string }` — `audioPath` must be OGG/Opus. When `transcriptText` is present it is attached as the voice message **caption**. Providers should treat pi-telegram's `voice.sendTranscript` as the bridge-owned transcript preference instead of inventing a second reply-policy UI.
 - `undefined` — skip this text block
 
 **Important:** Providers are fully responsible for producing a clean, TTS-optimised native voice file. The bridge may also run configured outbound voice command templates for users who prefer process-boundary handlers instead of provider extensions.
@@ -106,7 +103,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 (`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.
+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.
 
 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:
 
@@ -128,31 +125,6 @@ Voice handlers receive the text on stdin in composed pipelines and can use `{tex
 
 Priority for outbound voice delivery is: configured `outboundHandlers` with `type: "voice"` in their `telegram.json` order, then programmatic `voice` outbound handlers, then registered voice synthesis providers. Provider extensions are the zero-config tail of the same pipeline: they handle voice when no explicit configured handler succeeds, but they do not override operator-configured handlers. If multiple providers are registered, only one handles a given voice reply: the first provider that returns a valid `.ogg`/`.opus` artifact wins. Providers that return `undefined` explicitly pass to the next provider; providers that throw or return invalid output are recorded and the next fallback is tried.
 
-### Provider with transcript caption (controlled by user toggle)
-
-When the user's "Send Transcript" toggle is ON, return the clean spoken text as `transcriptText`. The bridge attaches it as the caption on the voice message. When the toggle is OFF, return only the audio path (no `transcriptText`).
-
-```typescript
-import {
-  getTelegramVoiceSendTranscript,
-  registerTelegramVoiceSynthesisProvider,
-} from "@llblab/pi-telegram/voice";
-
-registerTelegramVoiceSynthesisProvider(
-  async (text, options) => {
-    const rewritten = rewriteWithSpeechTags(text);
-    const audioPath = await myTTS(rewritten, { language: options?.lang });
-    const sendTranscript = getTelegramVoiceSendTranscript(
-      getCurrentTelegramConfigView(),
-    );
-    return sendTranscript ? { audioPath, transcriptText: text } : { audioPath };
-  },
-  { id: "my-voice-provider/tts" },
-);
-```
-
-`getCurrentTelegramConfigView()` represents whatever current `TelegramConfig` view your extension already owns or receives; pi-telegram does not require providers to read config directly. The bridge never sends a separate transcript message. Caption-only is the "ON" behavior.
-
 ### Surfacing provider diagnostics
 
 Voice provider extensions can record runtime events that appear in `/telegram-status` alongside pi-telegram's own events:
@@ -170,13 +142,13 @@ recordTelegramRuntimeEvent("voice-provider", new Error("TTS failed"), {
 
 ## Voice Extension Section
 
-Voice provider extensions can register a Voice Extension Section (settings UI) via `registerTelegramSection`. The section can expose provider-specific controls such as TTS voice, language, speech style, transcript behavior, or STT/TTS enablement. Reply mode is a core pi-telegram setting and belongs in the built-in Settings menu.
+Voice provider extensions can register a Voice Extension Section (settings UI) via `registerTelegramSection`. The section can expose provider-specific controls such as TTS voice, language, speech style, or STT/TTS enablement. Reply mode is a core pi-telegram setting and belongs in the built-in Settings menu.
 
 **Note on resume:** Because the previous automatic persistent re-registration system has been removed, extensions are responsible for re-registering their Voice Extension Section on `session_start` if they want the menu to survive a `pi resume`. See `registerTelegramSection` from `@llblab/pi-telegram/sections`.
 
 ## Prompt Guidance
 
-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.
+The bridge keeps voice prompt context compact, effective, and policy-owned. `manual` 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.
 
@@ -224,4 +196,4 @@ The bridge reads `voice.replyMode` from the config when building a turn.
 
 ### Provider config
 
-Provider-specific settings (voice ID, language, speech style, transcript behavior, STT/TTS enablement) are owned by the voice provider extension. Reply mode is owned by pi-telegram's `voice.replyMode` and configured from the built-in pi-telegram Settings menu, not duplicated in provider UIs.
+Provider-specific settings (voice ID, language, speech style, STT/TTS enablement) are owned by the voice provider extension. Reply mode is owned by pi-telegram's `voice.replyMode` and configured from the built-in pi-telegram Settings menu, not duplicated in provider UIs.

package/node_modules/@llblab/pi-telegram/index.ts

@@ -415,6 +415,8 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       getRegistrationGeneration:
         telegramBusFollowerRegistrationState.getGeneration,
+      waitForRegistrationGeneration:
+        telegramBusFollowerRegistrationState.waitForGeneration,
       getForwardCommentBatchPosition:
         textGroupRuntime.getPreparedForwardingPosition,
       recordRuntimeEvent,

package/node_modules/@llblab/pi-telegram/lib/bus-follower.ts

@@ -47,6 +47,7 @@ import {
 export const TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS = 2_500;
 export const TELEGRAM_FOLLOWER_SESSION_HANDOFF_TTL_MS = 30_000;
 export const TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS = 30_000;
+export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_WAIT_MS = 30_000;
 export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_ATTEMPTS =
   TELEGRAM_BUS_REGISTRATION_RETRY.attempts;
 export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_DELAY_MS =
@@ -167,6 +168,9 @@ export interface TelegramBusFollowerRegistrationState {
   getSlot: () => string | undefined;
   getThreadName: () => string | undefined;
   getGeneration: () => string | undefined;
+  beginRecovery: () => number;
+  cancelRecovery: () => void;
+  waitForGeneration: (timeoutMs?: number) => Promise<string | undefined>;
   getLeaderProtocol: () => TelegramBusProtocolIdentity | undefined;
   getEligibleElectionSlots: () => readonly string[];
   setEligibleElectionSlots: (slots: readonly string[]) => void;
@@ -214,6 +218,9 @@ export interface TelegramBusFollowerClientRuntimeDeps<TMessage = unknown> {
   getApiAuthSecret?: () => string | undefined;
   getForwardingAuthSecret?: () => string | undefined;
   getRegistrationGeneration: () => string | undefined;
+  waitForRegistrationGeneration?: (
+    timeoutMs?: number,
+  ) => Promise<string | undefined>;
   getForwardCommentBatchPosition?: (
     message: TMessage,
   ) => "comment" | "forward" | undefined;
@@ -231,6 +238,9 @@ export interface TelegramBusFollowerApiCallerDeps {
   createRequestId: () => string;
   getAuthSecret?: () => string | undefined;
   getRegistrationGeneration: () => string | undefined;
+  waitForRegistrationGeneration?: (
+    timeoutMs?: number,
+  ) => Promise<string | undefined>;
   getNowMs?: () => number;
   timeoutMs?: number;
 }
@@ -417,6 +427,7 @@ export interface TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext> {
     | "getSlot"
     | "getThreadName"
     | "getEligibleElectionSlots"
+    | "beginRecovery"
     | "setRegistered"
   >;
   getRegistrationRuntime: () => TelegramBusFollowerRegistrationRuntime<TContext>;
@@ -638,6 +649,7 @@ export function createTelegramBusFollowerClientRuntime<
     socketPath: deps.socketPath,
     createRequestId,
     timeoutMs,
+    waitForRegistrationGeneration: deps.waitForRegistrationGeneration,
   };
   return {
     createRequestId,
@@ -695,14 +707,14 @@ export function createTelegramBusFollowerQueueHandoffClient(
   const timeoutMs =
     deps.timeoutMs ?? TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS;
   return async (input) => {
-    const registrationGeneration = deps.getRegistrationGeneration();
-    if (!registrationGeneration) {
-      throw new Error("Telegram bus follower is not registered.");
-    }
+    const registration = await resolveTelegramBusFollowerRegistration(
+      deps,
+      timeoutMs,
+    );
     const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
     const response = await sendTelegramBusLocalEnvelope({
       socketPath,
-      timeoutMs,
+      timeoutMs: registration.remainingTimeoutMs,
       retry: getTelegramBusTransportRetryPolicy({
         endpoint: socketPath,
         operation: "operation",
@@ -712,7 +724,7 @@ export function createTelegramBusFollowerQueueHandoffClient(
         requestId: deps.createRequestId(),
         auth: deps.getAuthSecret?.(),
         instanceId: deps.instanceId,
-        registrationGeneration,
+        registrationGeneration: registration.generation,
         ...input,
         sentAtMs: getNowMs(),
       },
@@ -770,11 +782,12 @@ export function createTelegramBusAgentMessageClient(
     envelope:
       | Extract<TelegramBusEnvelope, { kind: "follower.resolveAgentTarget" }>
       | Extract<TelegramBusEnvelope, { kind: "follower.routeAgentMessage" }>,
+    requestTimeoutMs = timeoutMs,
   ): Promise<unknown> => {
     const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
     const response = await sendTelegramBusLocalEnvelope({
       socketPath,
-      timeoutMs,
+      timeoutMs: requestTimeoutMs,
       retry: getTelegramBusTransportRetryPolicy({
         endpoint: socketPath,
         operation: "operation",
@@ -788,26 +801,30 @@ export function createTelegramBusAgentMessageClient(
         : "Telegram bus agent message did not return an acknowledgement.",
     );
   };
-  const registrationFields = () => {
-    const registrationGeneration = deps.getRegistrationGeneration();
-    if (!registrationGeneration) {
-      throw new Error("Telegram bus follower is not registered.");
-    }
+  const registrationFields = async () => {
+    const registration = await resolveTelegramBusFollowerRegistration(
+      deps,
+      timeoutMs,
+    );
     return {
-      auth: deps.getAuthSecret?.(),
-      instanceId: deps.instanceId,
-      registrationGeneration,
+      fields: {
+        auth: deps.getAuthSecret?.(),
+        instanceId: deps.instanceId,
+        registrationGeneration: registration.generation,
+      },
+      remainingTimeoutMs: registration.remainingTimeoutMs,
     };
   };
   return {
     async resolveTarget(selector) {
+      const registration = await registrationFields();
       const result = await request({
         kind: "follower.resolveAgentTarget",
         requestId: deps.createRequestId(),
-        ...registrationFields(),
+        ...registration.fields,
         selector,
         sentAtMs: getNowMs(),
-      });
+      }, registration.remainingTimeoutMs);
       if (!result || typeof result !== "object" || Array.isArray(result)) {
         throw new Error("Telegram bus returned an invalid agent target.");
       }
@@ -821,13 +838,14 @@ export function createTelegramBusAgentMessageClient(
       return { chatId: target.chatId, threadId: target.threadId };
     },
     async routeMessage(message) {
+      const registration = await registrationFields();
       await request({
         kind: "follower.routeAgentMessage",
         requestId: deps.createRequestId(),
-        ...registrationFields(),
+        ...registration.fields,
         message,
         sentAtMs: getNowMs(),
-      });
+      }, registration.remainingTimeoutMs);
     },
   };
 }
@@ -839,16 +857,16 @@ export function createTelegramBusFollowerApiCaller(
   const timeoutMs =
     deps.timeoutMs ?? TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS;
   return async (method, args) => {
+    const registration = await resolveTelegramBusFollowerRegistration(
+      deps,
+      timeoutMs,
+    );
     const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
-    const registrationGeneration = deps.getRegistrationGeneration();
-    if (!registrationGeneration) {
-      throw new Error("Telegram bus follower is not registered.");
-    }
     let response: TelegramBusEnvelope | undefined;
     try {
       response = await sendTelegramBusLocalEnvelope({
         socketPath,
-        timeoutMs,
+        timeoutMs: registration.remainingTimeoutMs,
         retry: getTelegramBusTransportRetryPolicy({
           endpoint: socketPath,
           operation: "operation",
@@ -858,7 +876,7 @@ export function createTelegramBusFollowerApiCaller(
           requestId: deps.createRequestId(),
           auth: deps.getAuthSecret?.(),
           instanceId: deps.instanceId,
-          registrationGeneration,
+          registrationGeneration: registration.generation,
           method,
           args,
           sentAtMs: getNowMs(),
@@ -893,6 +911,29 @@ export function createTelegramBusFollowerApiCaller(
   };
 }
 
+async function resolveTelegramBusFollowerRegistration(
+  deps: Pick<
+    TelegramBusFollowerApiCallerDeps,
+    | "getRegistrationGeneration"
+    | "waitForRegistrationGeneration"
+    | "getNowMs"
+  >,
+  timeoutMs: number,
+): Promise<{ generation: string; remainingTimeoutMs: number }> {
+  const current = deps.getRegistrationGeneration();
+  if (current) return { generation: current, remainingTimeoutMs: timeoutMs };
+  const getNowMs = deps.getNowMs ?? Date.now;
+  const startedAtMs = getNowMs();
+  const restored = await deps.waitForRegistrationGeneration?.(
+    timeoutMs,
+  );
+  const remainingTimeoutMs = Math.max(0, timeoutMs - (getNowMs() - startedAtMs));
+  if (restored && remainingTimeoutMs > 0) {
+    return { generation: restored, remainingTimeoutMs };
+  }
+  throw new Error("Telegram bus follower is not registered.");
+}
+
 function isTelegramStaleContextError(error: unknown): boolean {
   return (
     error instanceof Error &&
@@ -1046,12 +1087,52 @@ export function createTelegramBusFollowerRegistrationState(
   let generation: string | undefined;
   let leaderProtocol: TelegramBusProtocolIdentity | undefined;
   let eligibleElectionSlots: string[] = [];
+  let recoveryEpoch = 0;
+  let activeRecoveryEpoch: number | undefined;
+  const generationWaiters = new Set<{
+    epoch: number;
+    settle: (value: string | undefined) => void;
+  }>();
+  const settleGenerationWaiters = (
+    value: string | undefined,
+    epoch?: number,
+  ) => {
+    for (const waiter of [...generationWaiters]) {
+      if (epoch === undefined || waiter.epoch === epoch) waiter.settle(value);
+    }
+  };
   return {
     isRegistered: () => registered,
     getTarget: () => (target ? { ...target } : undefined),
     getSlot: () => slot,
     getThreadName: () => threadName,
     getGeneration: () => generation,
+    beginRecovery: () => {
+      if (activeRecoveryEpoch !== undefined) return activeRecoveryEpoch;
+      activeRecoveryEpoch = ++recoveryEpoch;
+      return activeRecoveryEpoch;
+    },
+    cancelRecovery: () => {
+      const epoch = activeRecoveryEpoch;
+      activeRecoveryEpoch = undefined;
+      if (epoch !== undefined) settleGenerationWaiters(undefined, epoch);
+    },
+    waitForGeneration: (timeoutMs = TELEGRAM_BUS_FOLLOWER_REGISTRATION_WAIT_MS) => {
+      if (generation) return Promise.resolve(generation);
+      const epoch = activeRecoveryEpoch;
+      if (epoch === undefined) return Promise.resolve(undefined);
+      return new Promise((resolve) => {
+        let timer: NodeJS.Timeout | undefined;
+        const settle = (value: string | undefined) => {
+          generationWaiters.delete(waiter);
+          if (timer) clearTimeout(timer);
+          resolve(value);
+        };
+        const waiter = { epoch, settle };
+        generationWaiters.add(waiter);
+        timer = setTimeout(() => settle(undefined), Math.max(0, timeoutMs));
+      });
+    },
     getLeaderProtocol: () =>
       leaderProtocol
         ? { ...leaderProtocol, capabilities: [...leaderProtocol.capabilities] }
@@ -1077,6 +1158,10 @@ export function createTelegramBusFollowerRegistrationState(
             }
           : undefined;
       if (availabilityChanged) options.onAvailabilityChanged?.();
+      if (generation) {
+        activeRecoveryEpoch = undefined;
+        settleGenerationWaiters(generation);
+      }
     },
   };
 }
@@ -1253,6 +1338,7 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
   ): Promise<void> => {
     if (promotionPending) return;
     promotionPending = true;
+    deps.registrationState.beginRecovery();
     try {
       const initialBinding = carriedBinding ?? snapshotBinding();
       const state = deps.getLeaderState();
@@ -1366,6 +1452,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
     heartbeatPromise = undefined;
     heartbeatPromiseGeneration = undefined;
     deps.setActiveAuthSecret?.(undefined);
+    deps.registrationState?.cancelRecovery();
     deps.registrationState?.setRegistered(false);
     lastKnownTarget = undefined;
     lastKnownSlot = undefined;

package/node_modules/@llblab/pi-telegram/lib/config.ts

@@ -118,9 +118,8 @@ export interface TelegramConfig {
   /** @deprecated use assistant.rendering */
   assistantRendering?: TelegramAssistantRenderingMode;
   voice?: {
-    replyMode?: "hidden" | "mirror" | "always";
-    /** Whether to attach the provider's transcriptText as caption on voice messages */
-    sendTranscript?: boolean;
+    /** `hidden` is a read-only compatibility alias for the former manual mode. */
+    replyMode?: "manual" | "hidden" | "mirror" | "always";
   };
   time?: TelegramTimeConfig;
   threads?: {
@@ -845,10 +844,10 @@ export function createTelegramActivityVerbositySetter(
 
 export function createTelegramVoiceReplyModeGetter(
   configStore: Pick<TelegramConfigStore, "get">,
-): () => "hidden" | "mirror" | "always" {
+): () => "manual" | "mirror" | "always" {
   return () => {
     const mode = configStore.get().voice?.replyMode;
-    return mode === "mirror" || mode === "always" ? mode : "hidden";
+    return mode === "mirror" || mode === "always" ? mode : "manual";
   };
 }
 
@@ -863,11 +862,15 @@ export function createTelegramVoiceReplyModeConfiguredChecker(
 
 export function createTelegramVoiceReplyModeSetter(
   configStore: TelegramMutableConfigStore,
-): (replyMode: "hidden" | "mirror" | "always" | undefined) => Promise<void> {
+): (replyMode: "manual" | "hidden" | "mirror" | "always" | undefined) => Promise<void> {
   return async (replyMode) => {
     await loadLatestTelegramConfig(configStore);
     const current = configStore.get();
-    if (replyMode === undefined || replyMode === "hidden") {
+    if (
+      replyMode === undefined ||
+      replyMode === "manual" ||
+      replyMode === "hidden"
+    ) {
       const { replyMode: _replyMode, ...remainingVoice } = current.voice ?? {};
       const next = { ...current };
       if (Object.keys(remainingVoice).length > 0) next.voice = remainingVoice;

package/node_modules/@llblab/pi-telegram/lib/menu-settings.ts

@@ -149,9 +149,7 @@ export const TIME_INJECTION_MODE_SETTINGS_TITLE =
   "<b>🕒 Time injection mode:</b>";
 export const VOICE_REPLY_MODE_SETTINGS_TITLE = "<b>👄 Voice reply mode:</b>";
 
-type TelegramVoiceReplyModeSetting = TelegramVoiceReplyMode | "hidden";
-
-function getVoiceReplyModeLabel(mode: TelegramVoiceReplyModeSetting): string {
+function getVoiceReplyModeLabel(mode: TelegramVoiceReplyMode): string {
   return mode;
 }
 
@@ -162,8 +160,8 @@ function getTelegramSettingsStateValueLabel(value: string): string {
 function getVoiceReplyModeSetting(
   mode: TelegramVoiceReplyMode,
   configured: boolean,
-): TelegramVoiceReplyModeSetting {
-  return configured ? mode : "hidden";
+): TelegramVoiceReplyMode {
+  return configured ? mode : "manual";
 }
 
 export function buildTelegramSettingsMenuText(): string {
@@ -246,8 +244,8 @@ export function buildVoiceReplyModeSettingsText(
     "",
     "Controls when pi-telegram converts assistant text replies into Telegram voice messages.",
     "",
-    "<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>manual</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 'manual' behavior.",
     "<code>-</code> <code>always</code>: activate automatic voice delivery for every reply.",
   ].join("\n");
 }
@@ -502,7 +500,7 @@ export function buildVoiceReplyModeSettingsReplyMarkup(
   configured = true,
 ): TelegramSettingsMenuReplyMarkup {
   const activeMode = getVoiceReplyModeSetting(mode, configured);
-  const modes: TelegramVoiceReplyModeSetting[] = ["hidden", "mirror", "always"];
+  const modes: TelegramVoiceReplyMode[] = ["manual", "mirror", "always"];
   return {
     inline_keyboard: [
       [{ text: "⬆️ Back", callback_data: "settings:list" }],
@@ -661,12 +659,18 @@ export async function handleTelegramSettingsMenuCallbackAction(
   }
   if (data.startsWith("settings:set:voice-reply:")) {
     const mode = data.slice("settings:set:voice-reply:".length);
-    if (mode === "hidden" || mode === "mirror" || mode === "always") {
-      await deps.setVoiceReplyMode(mode === "hidden" ? undefined : mode);
+    if (
+      mode === "manual" ||
+      mode === "hidden" ||
+      mode === "mirror" ||
+      mode === "always"
+    ) {
+      const normalizedMode = mode === "hidden" ? "manual" : mode;
+      await deps.setVoiceReplyMode(normalizedMode);
       await updateVoiceReplyModeSettingsMessage(deps);
       await deps.answerCallbackQuery(
         callbackQueryId,
-        `Voice reply mode: ${mode}`,
+        `Voice reply mode: ${normalizedMode}`,
       );
       return true;
     }

package/node_modules/@llblab/pi-telegram/lib/outbound-voice.ts

@@ -100,17 +100,6 @@ async function ensureTelegramVoiceFileFormat(
   );
 }
 
-function extractVoiceResult(result: any): {
-  filePath: string;
-  transcriptText?: string;
-} {
-  if (typeof result === "string") return { filePath: result };
-  return {
-    filePath: result.audioPath,
-    transcriptText: result.transcriptText,
-  };
-}
-
 async function sendVoiceChatAction(
   deps: TelegramVoiceReplySenderDeps,
   chatId: number,
@@ -132,7 +121,6 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
     options?: {
       replyToPrompt?: boolean;
       replyMarkup?: unknown;
-      transcriptText?: string;
     },
   ): Promise<void> => {
     const voiceFilePath = await ensureTelegramVoiceFileFormat(filePath);
@@ -148,7 +136,6 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
       "sendVoice",
       {
         chat_id: String(turn.chatId),
-        ...(options?.transcriptText ? { caption: options.transcriptText } : {}),
         ...(replyParameters ? { reply_parameters: replyParameters } : {}),
         ...(turn.target
           ? Object.fromEntries(
@@ -257,13 +244,11 @@ export function createTelegramVoiceReplySender<THandler = unknown>(
           continue;
         }
 
-        const { filePath, transcriptText } = extractVoiceResult(providerResult);
-        voiceFilePath = filePath;
-        originalFilePath = filePath;
-        await uploadVoiceFile(turn, filePath, {
+        voiceFilePath = providerResult;
+        originalFilePath = providerResult;
+        await uploadVoiceFile(turn, providerResult, {
           replyToPrompt: options?.replyToPrompt,
           replyMarkup: options?.replyMarkup,
-          transcriptText,
         });
         return;
       } catch (error) {

package/node_modules/@llblab/pi-telegram/lib/voice.ts

@@ -38,15 +38,9 @@ function getNextAvailableProviderId<T>(
   return id;
 }
 
-export type TelegramVoiceReplyMode = "hidden" | "mirror" | "always";
+export type TelegramVoiceReplyMode = "manual" | "mirror" | "always";
 
-export type TelegramVoiceSynthesisProviderResult =
-  | string
-  | {
-      audioPath: string;
-      transcriptText?: string;
-    }
-  | undefined;
+export type TelegramVoiceSynthesisProviderResult = string | undefined;
 
 export interface TelegramVoiceTurnView {
   voiceReplyPreferred?: boolean;
@@ -215,7 +209,7 @@ export function clearTelegramVoiceTranscriptionProviders(): void {
 // --- Voice Reply Modes ---
 
 export const TELEGRAM_VOICE_REPLY_MODES = [
-  "hidden",
+  "manual",
   "mirror",
   "always",
 ] as const;
@@ -224,33 +218,15 @@ export const TELEGRAM_VOICE_REPLY_MODES = [
  * 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, invalid, or legacy `manual`, the effective
- * mode is hidden.
+ * config.voice.replyMode is missing, invalid, or legacy `hidden`, the effective
+ * mode is manual.
  */
 export function getTelegramVoiceReplyMode(config?: {
   voice?: { replyMode?: string };
 }): TelegramVoiceReplyMode {
   const configMode = config?.voice?.replyMode;
-  if (
-    configMode &&
-    (TELEGRAM_VOICE_REPLY_MODES as readonly string[]).includes(configMode)
-  ) {
-    return configMode as TelegramVoiceReplyMode;
-  }
-  return "hidden";
-}
-
-/**
- * Returns whether the user wants the voice synthesis provider's transcript attached
- * as a caption on the voice message.
- *
- * Reads from `config.voice.sendTranscript`.
- * Default: false (no transcript text sent at all).
- */
-export function getTelegramVoiceSendTranscript(config?: {
-  voice?: { sendTranscript?: boolean };
-}): boolean {
-  return !!config?.voice?.sendTranscript;
+  if (configMode === "mirror" || configMode === "always") return configMode;
+  return "manual";
 }
 
 // --- Voice Turn Helpers ---

package/node_modules/@llblab/pi-telegram/package.json

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

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/SKILL.md

@@ -122,7 +122,7 @@ Prefer no-code command-template configuration in `telegram.json` before adding a
 - `outboundHandlers` transforms final replies.
 - Voice transcription handlers can match `type: "voice"` or `mime: "audio/*"`; stdout becomes `[outputs]`.
 
-When asked to configure voice rather than merely operate it, follow the provider-neutral contracts in `docs/voice.md`, `docs/inbound.md`, `docs/outbound.md`, and `docs/command-templates.md` from the pi-telegram package or repository. Inspect the available Skill catalog and trusted local executables for STT, TTS, and media conversion capabilities; check only whether required environment variables exist, never reveal their values. Preserve unrelated `telegram.json` fields, order multiple matching inbound handlers as fallbacks, require OGG/Opus output for native voice delivery, and validate each stage before a live Telegram smoke test. Keep `voice.replyMode` at its existing value unless the user requests a policy change: the default `hidden` mode is fully functional because explicit top-level `telegram_voice` actions still use the configured synthesis pipeline.
+When asked to configure voice rather than merely operate it, follow the provider-neutral contracts in `docs/voice.md`, `docs/inbound.md`, `docs/outbound.md`, and `docs/command-templates.md` from the pi-telegram package or repository. Inspect the available Skill catalog and trusted local executables for STT, TTS, and media conversion capabilities; check only whether required environment variables exist, never reveal their values. Preserve unrelated `telegram.json` fields, order multiple matching inbound handlers as fallbacks, require OGG/Opus output for native voice delivery, and validate each stage before a live Telegram smoke test. Keep `voice.replyMode` at its existing value unless the user requests a policy change: the default `manual` mode is fully functional because explicit top-level `telegram_voice` actions still use the configured synthesis pipeline.
 
 When configuration is insufficient, use documented `@llblab/pi-telegram/*` public API subpaths. Never import package-private `lib/*`, start another polling loop, or bypass bridge ownership with raw Bot API access.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -43,7 +43,7 @@
     "@llblab/pi-actors": "0.50.0",
     "@llblab/pi-codex-usage": "0.9.3",
     "@llblab/pi-grow-loop": "0.7.2",
-    "@llblab/pi-telegram": "0.37.1"
+    "@llblab/pi-telegram": "0.38.0"
   },
   "bundledDependencies": [
     "@llblab/pi-actors",