@llblab/pi-telegram 0.20.4 → 0.20.5

package/BACKLOG.md

@@ -2,6 +2,70 @@
 
 _This backlog tracks only open release-relevant work: live promoted-follower verification, evidence-gated Telegram client/runtime follow-ups, and upstream Pi API blockers. Completed validation evidence belongs in `CHANGELOG.md`, not in this queue._
 
+## P0 — Private Guest DM Peer Attribution
+
+Evidence: live private Guest Mode produced `[telegram|guest:<owner>]` for an owner-authored DM turn even though `guest` must identify the remote conversation peer. Code inspection confirms that private guest routing falls back to `fromPeer` whenever an owner-authored message has no usable `reply_to_message`; because `from.id` then equals the configured `allowedUserId`, the owner is mislabeled as the guest. Existing coverage protects incoming guest messages and owner replies with explicit replied-guest metadata, but does not cover owner-authored private guest messages without reply context.
+
+Planned work:
+
+- [ ] Capture or minimize the raw private `guest_message` shape for owner-authored turns without reply context and identify the stable remote-peer fields supplied by Telegram (`chat` identity, username/name/id, or another explicit peer field) before choosing a resolver.
+- [ ] Centralize Guest Mode peer attribution: group turns use the group title; private non-owner turns use the sender; private owner turns use the replied guest when present and otherwise the remote private-chat peer.
+- [ ] Compare ownership by Telegram user id (`allowedUserId`), not display name or username. Never emit the configured owner as `guest`; if Telegram omits a username, fall back to the remote peer's stable name/id rather than the owner.
+- [ ] Keep `[reply|from:...]` and `[attachments|from:...]` source attribution aligned with the same resolved peer without changing the current-turn/source-context distinction.
+- [ ] Add regressions for incoming private guests, owner replies, owner-authored no-reply turns, missing usernames, username changes, and named-profile pairing identities.
+- [ ] Update the prompt-context contract/docs only after the minimized Telegram fixture establishes the actual private Guest Mode field semantics.
+
+Done when: `[telegram|guest:...]` always identifies the remote peer or group for private/group Guest Mode, never the paired owner, and reply/attachment provenance remains source-correct.
+
+## P0 — Guest Reply File And Audio Delivery
+
+Evidence: live Guest Mode accepted `telegram_attach` during an active guest turn and reported the file as queued, but delivered nothing. Code inspection confirms that guest turns use sentinel `chatId: 0`; the tool appends files to `queuedAttachments`, then the agent-end guest branch sends only `answerGuestQuery` text and returns before queued attachments or voice artifacts run. Telegram's `answerGuestQuery` accepts one `InlineQueryResult`, not ordinary `sendDocument`/`sendVoice` multipart delivery, so local artifacts require a guest-specific result plan rather than reuse of chat/thread attachment transport.
+
+Planned work:
+
+- [x] Fail closed immediately for unsupported guest attachments until guest delivery is available; never return `Queued` when the guest agent-end path cannot consume the artifact.
+- [x] Map the current Bot API `InlineQueryResult` capabilities for document, photo, audio, and voice replies, including URL versus cached `file_id`, caption limits, supported formats, and the one-result-per-guest-query constraint. `answerGuestQuery` accepts exactly one result; local multipart uploads are not accepted there. URL results require public HTTP content (documents only PDF/ZIP, audio MP3, voice OGG/OPUS, photos JPEG up to 5 MB), while cached result variants accept Telegram `document_file_id`, `photo_file_id`, `audio_file_id`, or `voice_file_id`; media captions remain limited to 0–1024 characters after entity parsing.
+- [x] Design one guest reply planner that chooses exactly one result: text article, one cached local file/media with answer text reduced to a caption, or one cached synthesized voice/audio result. Guest tool admission rejects a second attachment before mutation. A failure before the one-shot answer may degrade to one text article; an ambiguous/failing `answerGuestQuery` call must not issue a second answer that could duplicate delivery.
+- [x] Determine an evidence-backed local-file staging path. Local media must upload through the existing leader-owned multipart transport to the paired owner's bot chat, extract the returned Telegram `file_id`, answer the guest query with the matching cached result, and delete the staging message in `finally`. The staging message can briefly appear or notify the owner; this unavoidable Bot API limitation must be documented, no external hosting is introduced, and cleanup failure must be diagnosed rather than hidden.
+- [x] Extend `answerGuestQuery` and bus forwarding from hard-coded article input to the minimal typed result union required by confirmed file/audio/voice cases.
+- [x] Route `telegram_attach`, queued outbound artifacts, and `telegram_voice` through the guest planner before the guest branch returns; never call ordinary multipart methods with sentinel `chatId: 0`.
+- [x] Preserve follower operation by routing staging and `answerGuestQuery` through the transport leader without duplicate answers or leaked staging messages.
+- [x] Add regressions for unsupported fail-closed behavior, document/image/audio/voice result construction, caption fallback, staging cleanup/failure, multiple-file rejection, guest query one-shot semantics, and text fallback after media failure.
+- [ ] Capture live private and group Guest Mode evidence for one local document and one synthesized voice/audio reply before claiming support.
+
+Done when: guest turns never silently lose queued artifacts, one supported local file or audio/voice result can be delivered through `answerGuestQuery` with clear constraints, and unsupported/multi-file cases fail visibly without sending to an unrelated thread.
+
+## P1 — Compaction Status Ownership And Native Activity
+
+Context: Pi already renders its own compaction lifecycle, while pi-telegram currently overrides its terminal status row with `compacting` whenever the shared compaction flag is set. This duplicates Pi-owned state and hides the distinction between Telegram-owned activity and unrelated automatic/session compaction. Manual `/compact` already calls the typing-loop port and automatic compaction starts typing only when an active Telegram turn exists, so the reported absence of Telegram `…typing` needs transport-level and live verification rather than an assumed rewrite.
+
+Planned work:
+
+- [x] Remove `compacting` as a pi-telegram terminal status label while retaining the internal compaction flag for queue/dispatch safety and explicit diagnostics.
+- [x] Track compaction origin for status projection: confirmed Telegram `/compact` and auto-compaction inside a Telegram-owned turn render normal `Active`; local/autonomous/background compaction keeps the stable `connected`, `leader`, or `follower` role.
+- [x] Define and verify the native activity matrix: Telegram-owned compaction targets the invoking/active thread plus `All`; non-Telegram compaction uses the connected instance target plus `All` without changing terminal role semantics.
+- [x] Trace manual confirmation, `session_before_compact`, `session_compact`, completion, error, timeout, abort, and shutdown ordering to ensure one keyed typing loop remains active for the whole compaction window and always stops.
+- [x] Add transport-level regressions that assert actual `sendChatAction(typing)` targets and keepalive lifecycle, not only invocation of a mocked `startTypingLoop` callback.
+- [x] Replace status tests that currently require `compacting` with Telegram-owned `Active` and non-Telegram stable-role cases; preserve `/telegram-status` compaction diagnostics where operationally useful.
+- [ ] Capture live evidence for manual Telegram compaction, auto-compaction during a Telegram turn, and non-Telegram auto-compaction before finalizing the activity contract.
+
+Done when: Pi remains the only terminal owner of the `compacting` label, pi-telegram status reflects Telegram ownership rather than generic compaction, and Telegram native `…typing` remains visible and correctly targeted throughout every confirmed compaction class without leaking afterward.
+
+## P1 — Leader Endpoint Loss Recovery
+
+Context: live evidence showed a process retaining a fresh transport lock and active polling while its Threaded Mode Unix socket path was absent. The likely trigger was external removal of the shared Telegram temp directory while the owner process remained alive. The local server keeps listening on the unlinked Unix socket but `start()` treats its in-memory server handle as sufficient, leader health checks only Bot API transport, and a new instance therefore exhausts follower-registration retries with `ENOENT`. This is a real diagnosable recovery gap, but not yet evidence for a broad readiness protocol or automatic takeover; force-acquiring while the old owner may still run `getUpdates` would risk split-brain.
+
+Planned work:
+
+- [x] Reproduce deterministically by unlinking only the active Unix leader socket while its process, polling runtime, and in-memory server remain live. Native Windows named pipes have no equivalent filesystem path to unlink, so recovery remains Unix-specific unless separate named-pipe evidence appears.
+- [x] Let the owning Threaded Mode runtime detect an externally missing Unix endpoint during its existing health/prune cadence and restart only the local bus server without changing lock ownership, leader epoch, polling, or thread bindings.
+- [x] Make initial follower registration report `live owner / unreachable bus endpoint` after bounded retries, with direct operator guidance; do not add automatic or force takeover without separate evidence that the old owner cannot still poll.
+- [x] Keep intentional classic ownership unchanged because classic mode does not require a bus endpoint.
+- [x] Add focused regressions for Unix endpoint unlink/rebind, bounded follower diagnosis, leader reload overlap, and no duplicate `getUpdates` ownership; add Windows coverage only for behavior the named-pipe transport can reproduce.
+- [ ] Capture live recovery evidence without deleting lock/state or creating a replacement Telegram thread.
+
+Done when: the confirmed endpoint-loss scenario either self-recovers under the existing owner or produces precise safe remediation, while classic mode and single-owner polling remain unchanged.
+
 ## P1 — Promoted Follower Reload Evidence
 
 Context: deterministic coverage protects promoted follower thread preservation, and the latest live Linux smoke closed reload routing, follower Active, and reroute/restore regressions. The exact promoted-leader reload path is deliberately outside the 0.20.1 profile IPC hotfix because it is unrelated to profile transport isolation; keep it as an evidence-gated follow-up rather than blocking that release.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.20.5: Guest Media And Runtime Recovery Hotfix
+
+- `[Setup Persistence]` The setup prompt now applies the validated bot identity to its config store before invoking persistence, so adapters that serialize current store state cannot write an empty or stale `telegram.json` on first run. Persistence failure rolls the in-memory candidate back and remains ahead of success notifications and polling startup. Impact: setup from a missing file or `{}` durably writes `botToken`, `botId`, and `botUsername` on the first successful command for default and named profiles without reporting an unsaved connection.
+- `[Validation]` Added file-backed setup regressions for missing and empty config files, environment-provided tokens, named-profile isolation, and persistence-failure rollback while preserving existing cancellation, validation, polling-failure, and atomic config-write coverage. Full validation passes with 1,098 tests and one platform-only skip; typecheck and npm audit remain clean.
+- `[Guest Attachments]` `telegram_attach` now admits exactly one local file during an active Guest Mode turn and rejects a second before file inspection or queue mutation. Agent-end stages that file through the paired-owner chat, sends one cached-media guest result with final text as its caption, cleans up the staging message, and never follows an ambiguous media-answer failure with a second guest answer. Impact: a requested local file is no longer silently discarded, while Telegram's one-result constraint remains explicit.
+- `[Guest Media Transport]` `answerGuestQuery` now accepts a typed cached document/photo/audio/voice result in addition to text and Rich Markdown articles, and the bus-aware API preserves that exact result when a follower routes it through the leader. Impact: guest delivery no longer hard-codes article construction at the direct or IPC boundary, providing the minimal one-shot transport needed for staged local media without widening the follower API allowlist.
+- `[Guest Media Staging]` Added a bounded local-media staging primitive that selects document/photo/audio/voice multipart transport, extracts the returned Telegram `file_id`, emits one matching cached guest result, truncates captions safely to 1,024 code points, and deletes the staging message in `finally`. Extraction and answer failures still clean up; cleanup failures record diagnostics without retrying the one-shot guest answer. Impact: local Guest Mode artifacts have deterministic cleanup and no duplicate-answer path.
+- `[Guest Voice]` Guest agent-end now routes one explicit or policy-intercepted voice reply through the existing synthesis/handler chain, captures the generated OGG/OPUS artifact instead of sending it to sentinel chat `0`, stages it through the leader-owned multipart transport, and answers with one cached voice result. Visible answer text becomes the media caption, and multiple voice blocks reduce to the first result under Telegram's one-query/one-result contract. Impact: ordinary Guest Mode responses can include synthesized audio without bypassing ownership or emitting a separate text answer.
+- `[Leader Endpoint Recovery]` The active Threaded Mode leader now checks its Unix socket during the existing follower-health cadence. If an external cleanup unlinks the endpoint while the server and polling owner remain alive, it closes only the orphaned local server, recreates the socket and parent directory, and resumes follower reachability without restarting polling, changing leader epoch, or touching thread bindings. Named pipes and classic mode remain unchanged because they do not expose the same filesystem-loss condition. Impact: a live owner can self-heal the observed `ENOENT bus.sock` split between polling health and follower connectivity without unsafe lock takeover.
+- `[Follower Diagnostics]` When bounded registration retries fail with `ENOENT`, `ECONNREFUSED`, or `ETIMEDOUT` behind a still-live lock owner, the connection result now identifies `live owner / unreachable bus endpoint`, asks the operator to wait briefly and retry `/telegram-connect`, and explicitly rejects force takeover while the owner remains live. Impact: transient endpoint recovery no longer looks like a generic registration failure or invite split-brain remediation.
+- `[Profile Diagnostics]` Current logs use `logs.jsonl` for default and `logs.<profile>.jsonl` for named profiles; preserved logs use `logs._prev.jsonl` and `logs.<profile>._prev.jsonl`. Status and `telegram_help` resolve paths through the shared helper, old logs remain untouched as ephemeral evidence, and profile names allow only lowercase ASCII letters and digits. Impact: `_prev` remains an unmistakable lifecycle suffix because underscores and dots cannot occur in profile identifiers, while compact dotted profile filenames remain readable.
+- `[Compaction Status]` Removed pi-telegram's terminal and status-summary `compacting` projection while retaining the compaction flag in explicit bridge diagnostics and dispatch safety. A Telegram-owned active turn continues to render `active`; unrelated compaction leaves the stable connected/leader/follower role visible. Impact: Pi remains the sole owner of compaction lifecycle UI, and pi-telegram reports Telegram ownership rather than duplicating generic session state.
+- `[Compaction Activity]` Compaction now starts the same connected-instance native typing path used by agent activity instead of suppressing typing when no Telegram turn is active. Active Telegram compaction targets its thread plus `All`; local/autonomous compaction targets the instance's assigned thread plus `All`, with completion, timeout, and shutdown stopping the keyed loop. Impact: compaction remains visible in Telegram without taking ownership of Pi's terminal lifecycle label.
+
 ## 0.20.4: Thread State Ownership Hotfix
 
 - `[State Ownership]` Made the active transport lock owner the only process allowed to persist the profile-shared `state.json`; followers remain readers and acquire write authority only after promotion. Status-only persistence now refreshes disk-backed bindings before serialization. Impact: a stale follower diagnostics snapshot cannot erase newer leader-owned bindings, produce duplicate slot occupancy, or make a live follower disappear from current thread state.

package/README.md

@@ -151,6 +151,8 @@ Run these inside Pi.
 | `/telegram-disconnect` | Stop polling and release ownership |
 | `/telegram-status` | Inspect connection, mode, queue, transport, and recent diagnostics |
 
+Named profile identifiers contain only lowercase ASCII letters and digits (maximum 32 characters); `default`, `main`, and `active` remain reserved.
+
 ## Main Surfaces
 
 ### Operator Menu

package/docs/architecture.md

@@ -120,7 +120,7 @@ Deleting `locks.json` resets runtime ownership without deleting Telegram configu
 
 Telegram private-chat Threaded Mode is the public switch for multi-instance Telegram operation. Classic single-DM polling is the base mode. When Telegram private-chat threads are available for the bot, the bridge enables the local leader/follower bus automatically; when threads are unavailable or later disabled, the bridge returns to classic single-DM polling as a first-class mode.
 
-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`, previous log, 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.
+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. 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.
 
@@ -214,14 +214,14 @@ Queue and menu mutations are reachable through Telegram updates handled by the c
 
 ### Compaction And Typing Status
 
-Manual `/compact` requires inline confirmation because accidental taps are disruptive. Confirmed manual compaction and auto-compaction both set the bridge compaction flag, block queued prompt dispatch, update status to `compacting`, and clear that state on compact completion, timeout fallback, or session shutdown.
+Manual `/compact` requires inline confirmation because accidental taps are disruptive. Confirmed manual compaction and auto-compaction both set the bridge compaction flag, block queued prompt dispatch, retain that flag in explicit diagnostics, and clear it on compact completion, timeout fallback, or session shutdown. Pi owns its terminal compaction lifecycle; pi-telegram keeps `Active` scoped to Telegram-owned work and otherwise preserves the stable connected/leader/follower role.
 
-Native typing during compaction is deliberately narrower than the compaction flag:
+Native typing during compaction follows connected-instance activity rather than terminal status:
 
-- Confirmed manual `/compact` always starts a native `typing` keepalive in the command target and stops it on completion/failure.
-- Automatic/session compaction starts native `typing` only when there is an active Telegram-owned turn; it must reuse that active turn's target.
-- Startup, reload, connect/reconnect, restore, leader/follower recovery, and idle/background compaction without an active Telegram turn must not send visible typing.
-- Thread-targeted typing is sent to the concrete thread and mirrored to `All` as the aggregate activity surface.
+- Confirmed manual `/compact` starts a native `typing` keepalive in the command target and stops it on completion/failure.
+- Automatic/session compaction with an active Telegram turn reuses that turn's target.
+- Automatic/session compaction without an active Telegram turn uses the connected instance's assigned target; an unconnected instance sends nothing.
+- Thread-targeted typing is sent to the concrete thread and mirrored to `All` as the aggregate activity surface; completion, timeout, and shutdown stop the keyed loop.
 
 At every connected instance `agent_start`, the lifecycle binding starts Telegram's native `…typing` indicator in that instance's assigned target, whether the run came from Telegram, the local TUI, or an autonomous continuation such as Grow Loop. Terminal `Active` remains Telegram-turn-specific; the native indicator answers the separate question of whether the instance is doing agent work. Assistant message start/update hooks still re-arm it during Telegram-owned turns so transient provider/model errors do not leave a continuing run without activity feedback, and agent/session completion stops it.
 

package/docs/multi-instance-bus.md

@@ -192,7 +192,7 @@ Manual smoke checklist:
 6. Close the follower terminal; verify heartbeat pruning, disconnected notice, and cleanup behavior match Unix-like behavior.
 7. Reload the leader and verify status/debug output does not expose raw pipe internals except in explicit diagnostics.
 
-If any step fails, capture `telegram-status --debug`, `tmp/telegram/state.json`, `tmp/telegram/logs.jsonl`, and, after a reload, `tmp/telegram/logs.previous.jsonl`. Debug status prints local leader/follower endpoints with their active transport kind (`pipe` or `socket`), while the runtime log records request-scoped transport failures with envelope kind, request id, retry attempt, endpoint, and classified IPC error. Reloads preserve the prior JSONL log as `logs.previous.jsonl` so the evidence that caused the reload is not immediately overwritten.
+If any step fails, capture `telegram-status --debug`, `tmp/telegram/state.json`, `tmp/telegram/logs.jsonl`, and, after a reload, `tmp/telegram/logs._prev.jsonl`. Debug status prints local leader/follower endpoints with their active transport kind (`pipe` or `socket`), while the runtime log records request-scoped transport failures with envelope kind, request id, retry attempt, endpoint, and classified IPC error. Reloads preserve the prior JSONL log as `logs._prev.jsonl` so the evidence that caused the reload is not immediately overwritten.
 
 ### Native Windows Assumption Audit
 

package/docs/outbound.md

@@ -18,6 +18,12 @@ An outbound handler is selected by `type`. Text replies and assistant markup map
 
 The voice pipeline is detailed below: configured `type: "voice"` handlers first, then programmatic handlers, then registered synthesis providers.
 
+### Guest Mode media boundary
+
+A Guest Mode reply is one `answerGuestQuery` call carrying exactly one `InlineQueryResult`; it is not a normal chat target and cannot receive `sendDocument`/`sendVoice` multipart uploads through sentinel `chatId: 0`. `telegram_attach` therefore admits at most one file during a guest turn and rejects additional files before queue mutation.
+
+Telegram accepts public URLs or existing Telegram `file_id` values for inline media results, but pi-telegram does not publish local artifacts to external hosting. A local guest document, photo, MP3 audio, or OGG/OPUS voice therefore uses a temporary upload to the paired owner's bot chat, extraction of the returned `file_id`, one cached-media guest answer, and best-effort deletion of the staging message. That message can briefly appear or notify the owner. One guest query can carry only one media item, and its answer text must fit the media caption limit rather than a separate full Rich Markdown message.
+
 Configured text handlers provide `template`. A string is one command; an array is ordered composition. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values. The command-template default timeout applies automatically. Use `template: [...]` for composition; the old local `pipe` alias is removed in 0.13.0.
 
 ## Text Handler Config

package/index.ts

@@ -24,6 +24,7 @@ import * as Menu from "./lib/menu.ts";
 import * as Model from "./lib/model.ts";
 import * as Outbound from "./lib/outbound.ts";
 import * as Ownership from "./lib/ownership.ts";
+import * as Paths from "./lib/paths.ts";
 import * as Pi from "./lib/pi.ts";
 import * as Polling from "./lib/polling.ts";
 import * as Preview from "./lib/preview.ts";
@@ -309,6 +310,7 @@ export default function (pi: Pi.ExtensionAPI) {
   >({
     getConfig: configStore.get,
     getActiveProfileName: configStore.getActiveProfileName,
+    getDiagnosticPaths: Paths.getTelegramDiagnosticsDisplayPaths,
     isPollingActive: Polling.createTelegramPollingActivityReader(
       pollingControllerState,
     ),
@@ -1318,6 +1320,7 @@ export default function (pi: Pi.ExtensionAPI) {
     sendTextReply,
     dispatchNextQueuedTelegramTurn,
     answerGuestQuery,
+    deleteMessage: deleteTelegramMessage,
     sendGuestReply,
     finalizeMarkdownPreview,
     proactivePushChatIdGetter,

package/lib/bindings.ts

@@ -127,22 +127,29 @@ export function registerTelegramCommandsAndTools({
         });
         setupConfigStore.activateProfile(profileName);
         persistSetupConfig = async () => {
+          try {
+            configStore.activateProfile(undefined);
+            configStore.set({
+              ...storedConfig,
+              profiles: {
+                ...(storedConfig.profiles ?? {}),
+                [profileName]: storedConfig.profiles?.[profileName] ?? {
+                  botToken: "",
+                },
+              },
+            });
+            configStore.activateProfile(profileName);
+            configStore.set(setupConfigStore.get());
+            await persistConfig();
+          } catch (error) {
+            configStore.activateProfile(undefined);
+            configStore.set(storedConfig);
+            configStore.activateProfile(previousProfileName);
+            throw error;
+          }
           if (previousProfileName !== profileName) {
             await (stopPolling ?? lockedPollingRuntime.stop)();
           }
-          configStore.activateProfile(undefined);
-          configStore.set({
-            ...storedConfig,
-            profiles: {
-              ...(storedConfig.profiles ?? {}),
-              [profileName]: storedConfig.profiles?.[profileName] ?? {
-                botToken: "",
-              },
-            },
-          });
-          configStore.activateProfile(profileName);
-          configStore.set(setupConfigStore.get());
-          await persistConfig();
         };
       }
       const runSetup = Setup.createTelegramSetupPromptRuntime({
@@ -242,14 +249,8 @@ interface TelegramLifecycleBindingDeps {
   >["sendTextReply"] &
     NonNullable<OutboundHandlers.TelegramVoiceReplySenderDeps["sendTextReply"]>;
   dispatchNextQueuedTelegramTurn: (ctx: Pi.ExtensionContext) => void;
-  answerGuestQuery: NonNullable<
-    Queue.TelegramAgentEndHookRuntimeDeps<
-      Queue.PendingTelegramTurn,
-      Pi.ExtensionContext,
-      Pi.AgentEndEvent["messages"][number],
-      Keyboard.TelegramInlineKeyboardMarkup
-    >["answerGuestQuery"]
-  >;
+  answerGuestQuery: TelegramApi.TelegramBridgeApiRuntime["answerGuestQuery"];
+  deleteMessage: TelegramApi.TelegramBridgeApiRuntime["deleteMessage"];
   sendGuestReply: NonNullable<
     Queue.TelegramAgentEndHookRuntimeDeps<
       Queue.PendingTelegramTurn,
@@ -295,6 +296,7 @@ export function registerTelegramLifecycleRuntimeHooks({
   sendTextReply,
   dispatchNextQueuedTelegramTurn,
   answerGuestQuery,
+  deleteMessage,
   sendGuestReply,
   finalizeMarkdownPreview,
   proactivePushChatIdGetter,
@@ -319,18 +321,107 @@ export function registerTelegramLifecycleRuntimeHooks({
       sendTextReply,
       recordRuntimeEvent,
     });
-  const outboundReplyPlanner =
-    OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore);
-  const outboundReplyArtifactSender =
-    OutboundHandlers.createTelegramOutboundReplyArtifactSender({
-      execCommand: CommandTemplates.execCommandTemplate,
+  const sendGuestAttachment = async (
+    turn: Queue.PendingTelegramTurn,
+    attachment: Queue.QueuedAttachment,
+    caption?: string,
+  ): Promise<void> => {
+    const stagingTarget = proactivePushTargetGetter();
+    const stagingChatId = stagingTarget?.chatId ?? proactivePushChatIdGetter();
+    if (stagingChatId === undefined) {
+      throw new Error("Guest attachment staging requires a paired Telegram chat");
+    }
+    await OutboundAttachments.deliverTelegramGuestCachedAttachment({
+      guestQueryId: turn.guestQueryId!,
+      stagingChatId,
+      stagingTarget,
+      attachment,
+      caption,
       sendMultipart: callMultipart,
-      sendTextReply,
-      sendChatAction,
-      sendRecordVoiceAction,
-      getHandlers: configStore.getOutboundHandlers,
+      answerGuestQuery: (guestQueryId, result) =>
+        answerGuestQuery(guestQueryId, undefined, { result }),
+      answerGuestText: (guestQueryId, text) =>
+        answerGuestQuery(guestQueryId, text),
+      fallbackText:
+        caption || "Telegram bridge could not deliver the requested attachment.",
+      deleteMessage,
       recordRuntimeEvent,
     });
+  };
+  const outboundReplyPlanner =
+    OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore);
+  const voiceReplySenderDeps = {
+    execCommand: CommandTemplates.execCommandTemplate,
+    sendMultipart: callMultipart,
+    sendTextReply,
+    sendChatAction,
+    sendRecordVoiceAction,
+    getHandlers: configStore.getOutboundHandlers,
+    recordRuntimeEvent,
+  };
+  const outboundReplyArtifactSender =
+    OutboundHandlers.createTelegramOutboundReplyArtifactSender(
+      voiceReplySenderDeps,
+    );
+  const sendGuestVoiceReply = async (
+    turn: Queue.PendingTelegramTurn,
+    plan: OutboundHandlers.TelegramOutboundReplyPlan,
+    caption?: string,
+  ): Promise<void> => {
+    const stagingTarget = proactivePushTargetGetter();
+    const stagingChatId = stagingTarget?.chatId ?? proactivePushChatIdGetter();
+    if (stagingChatId === undefined) {
+      throw new Error("Guest voice staging requires a paired Telegram chat");
+    }
+    const guestVoiceSender =
+      OutboundHandlers.createTelegramOutboundReplyArtifactSender({
+        ...voiceReplySenderDeps,
+        sendChatAction: undefined,
+        sendRecordVoiceAction: undefined,
+        sendMultipart: async (
+          _method,
+          _fields,
+          _fileField,
+          filePath,
+          fileName,
+        ) => {
+          try {
+            await OutboundAttachments.deliverTelegramGuestCachedAttachment({
+              guestQueryId: turn.guestQueryId!,
+              stagingChatId,
+              stagingTarget,
+              attachment: { path: filePath, fileName },
+              caption,
+              sendMultipart: callMultipart,
+              answerGuestQuery: (guestQueryId, result) =>
+                answerGuestQuery(guestQueryId, undefined, { result }),
+              answerGuestText: (guestQueryId, text) =>
+                answerGuestQuery(guestQueryId, text),
+              fallbackText:
+                caption || "Telegram bridge could not deliver the voice reply.",
+              deleteMessage,
+              recordRuntimeEvent,
+            });
+          } catch (error) {
+            recordRuntimeEvent("delivery", error, {
+              phase: "guest-voice-answer",
+              guestQueryId: turn.guestQueryId,
+            });
+          }
+          return {};
+        },
+      });
+    await guestVoiceSender(
+      turn,
+      {
+        ...plan,
+        ...(plan.voiceReplies?.length
+          ? { voiceReplies: [plan.voiceReplies[0]!] }
+          : {}),
+      },
+      { replyToPrompt: false },
+    );
+  };
   const agentLifecycleHooks = Queue.createTelegramAgentLifecycleHooks<
     Queue.PendingTelegramTurn,
     Pi.ExtensionContext,
@@ -383,6 +474,8 @@ export function registerTelegramLifecycleRuntimeHooks({
     sendQueuedAttachments: queuedAttachmentSender,
     answerGuestQuery,
     sendGuestReply,
+    sendGuestAttachment,
+    sendGuestVoiceReply,
     planOutboundReply: outboundReplyPlanner,
     sendOutboundReplyArtifacts: outboundReplyArtifactSender,
     getDefaultChatId: proactivePushChatIdGetter,
@@ -398,8 +491,8 @@ export function registerTelegramLifecycleRuntimeHooks({
   const agentStartWithDedupReset = Lifecycle.createAgentStartDedupHook(
     agentLifecycleHooks.onAgentStart,
   );
-  const startAgentActivityTypingLoop = (ctx: Pi.ExtensionContext): void => {
-    if (!canSendAgentActivity(ctx)) return;
+  const startAgentActivityTypingLoop = (ctx: Pi.ExtensionContext): boolean => {
+    if (!canSendAgentActivity(ctx)) return false;
     const turn = activeTurnRuntime.get();
     const target = turn?.target ?? proactivePushTargetGetter();
     promptDispatchRuntime.startTypingLoop(
@@ -407,6 +500,7 @@ export function registerTelegramLifecycleRuntimeHooks({
       turn?.chatId ?? target?.chatId ?? proactivePushChatIdGetter(),
       { target },
     );
+    return true;
   };
   const startActiveTurnTypingLoop = (ctx: Pi.ExtensionContext): void => {
     const turn = activeTurnRuntime.get();
@@ -417,9 +511,8 @@ export function registerTelegramLifecycleRuntimeHooks({
   const compactionObserver = Lifecycle.createTelegramCompactionObserverRuntime({
     setCompactionInProgress: lifecycle.setCompactionInProgress,
     updateStatus,
-    startTypingLoop: startActiveTurnTypingLoop,
+    startTypingLoop: startAgentActivityTypingLoop,
     stopTypingLoop: typing.stop,
-    shouldStartTypingLoop: activeTurnRuntime.has,
     requestDeferredDispatchNextQueuedTelegramTurn:
       deferredQueueDispatchRuntime.request,
     dispatchNextQueuedTelegramTurn,

package/lib/bus-api.ts

@@ -5,10 +5,10 @@
  */
 
 import type {
+  TelegramAnswerGuestQueryOptions,
   TelegramApiCallOptions,
   TelegramBridgeApiRuntime,
   TelegramEditMessageTextBody,
-  TelegramInputRichMessage,
   TelegramSendMessageBody,
   TelegramSendMessageDraftBody,
   TelegramSendRichMessageBody,
@@ -273,14 +273,16 @@ export function createTelegramBusAwareApiRuntime(
     async answerGuestQuery(
       guestQueryId: string,
       text?: string,
-      options?: { parseMode?: string; richMessage?: TelegramInputRichMessage },
+      options?: TelegramAnswerGuestQueryOptions,
     ): Promise<void> {
       if (deps.ownsDirect()) {
         await deps.directRuntime.answerGuestQuery(guestQueryId, text, options);
         return;
       }
       const body: Record<string, unknown> = { guest_query_id: guestQueryId };
-      if (text !== undefined || options?.richMessage) {
+      if (options?.result) {
+        body.result = options.result;
+      } else if (text !== undefined || options?.richMessage) {
         const inputContent: Record<string, unknown> = options?.richMessage
           ? { rich_message: options.richMessage }
           : { message_text: text };

package/lib/bus-leader.ts

@@ -1199,6 +1199,13 @@ export function createTelegramBusLeaderRuntime<TContext>(
     followerRealityTimer.unref?.();
   };
   const pruneFollowers = async () => {
+    try {
+      await localServer.ensureEndpoint();
+    } catch (error) {
+      deps.recordRuntimeEvent?.("bus", error, {
+        phase: "leader-endpoint-recovery",
+      });
+    }
     const removed = deps.followerRegistry.pruneStale(
       getNowMs(),
       followerStaleAfterMs,

package/lib/bus.ts

@@ -165,6 +165,7 @@ export function isTelegramFollowerApiCallAllowed(input: {
     "sendRichMessageDraft",
   ]);
   const allowedMultipartMethods = new Set([
+    "sendAudio",
     "sendDocument",
     "sendMediaGroup",
     "sendPhoto",
@@ -384,6 +385,7 @@ export function parseTelegramBusEnvelope(
 export interface TelegramBusLocalServer {
   start: () => Promise<void>;
   stop: () => Promise<void>;
+  ensureEndpoint: () => Promise<boolean>;
 }
 
 export type TelegramBusSocketPathSource = string | (() => string);
@@ -610,12 +612,14 @@ export function createTelegramBusLocalServer(
 ): TelegramBusLocalServer {
   let server: Server | undefined;
   let activeSocketPath: string | undefined;
+  let endpointRecovery: Promise<boolean> | undefined;
+  let stopGeneration = 0;
   const sockets = new Set<Socket>();
   const closeSocket = (socket: Socket) => {
     sockets.delete(socket);
     socket.destroy();
   };
-  return {
+  const runtime: TelegramBusLocalServer = {
     start: async () => {
       if (server) return;
       const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
@@ -679,6 +683,7 @@ export function createTelegramBusLocalServer(
       if (!usesWindowsPipe) chmodSync(socketPath, 0o600);
     },
     stop: async () => {
+      stopGeneration += 1;
       const activeServer = server;
       const socketPath = activeSocketPath;
       server = undefined;
@@ -703,7 +708,44 @@ export function createTelegramBusLocalServer(
         );
       }
     },
+    ensureEndpoint: async () => {
+      const socketPath = activeSocketPath;
+      if (
+        !server ||
+        !socketPath ||
+        isTelegramBusPipePath(socketPath) ||
+        existsSync(socketPath)
+      ) {
+        return false;
+      }
+      if (endpointRecovery) return endpointRecovery;
+      endpointRecovery = (async () => {
+        deps.recordTransportEvent?.(
+          "server-endpoint-missing",
+          getTelegramBusEndpointDiagnostics(socketPath),
+        );
+        const recoveryStopGeneration = stopGeneration + 1;
+        await runtime.stop();
+        if (stopGeneration !== recoveryStopGeneration) return false;
+        await runtime.start();
+        if (stopGeneration !== recoveryStopGeneration) {
+          await runtime.stop();
+          return false;
+        }
+        deps.recordTransportEvent?.(
+          "server-endpoint-recovered",
+          getTelegramBusEndpointDiagnostics(socketPath),
+        );
+        return true;
+      })();
+      try {
+        return await endpointRecovery;
+      } finally {
+        endpointRecovery = undefined;
+      }
+    },
   };
+  return runtime;
 }
 
 function getTelegramBusEnvelopeDiagnostics(

package/lib/config.ts

@@ -85,8 +85,8 @@ export interface TelegramBotProfile {
   lastUpdateId?: number;
 }
 
-/** Profile names must be lowercase letters, digits, hyphens, underscores; max 32 chars. */
-const TELEGRAM_PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+/** Profile names must contain only lowercase ASCII letters and digits; max 32 chars. */
+const TELEGRAM_PROFILE_NAME_PATTERN = /^[a-z0-9]{1,32}$/;
 const TELEGRAM_RESERVED_PROFILE_NAMES: ReadonlySet<string> = new Set([
   "default",
   "main",

package/lib/lifecycle.ts

@@ -153,9 +153,8 @@ function unrefTelegramLifecycleTimer(timer: TelegramLifecycleTimer): void {
 export interface TelegramCompactionObserverRuntimeDeps<TContext> {
   setCompactionInProgress: (inProgress: boolean) => void;
   updateStatus: (ctx: TContext) => void;
-  startTypingLoop?: (ctx: TContext) => void;
+  startTypingLoop?: (ctx: TContext) => boolean | void;
   stopTypingLoop?: () => void;
-  shouldStartTypingLoop?: () => boolean;
   requestDeferredDispatchNextQueuedTelegramTurn: (
     dispatch: (ctx: TContext) => void,
   ) => void;
@@ -196,8 +195,9 @@ export function createTelegramCompactionObserverRuntime<TContext>(
   return {
     onSessionBeforeCompact: (_event, ctx) => {
       deps.setCompactionInProgress(true);
-      typingStartedByObserver = deps.shouldStartTypingLoop?.() ?? true;
-      if (typingStartedByObserver) deps.startTypingLoop?.(ctx);
+      const typingStartResult = deps.startTypingLoop?.(ctx);
+      typingStartedByObserver =
+        !!deps.startTypingLoop && typingStartResult !== false;
       deps.updateStatus(ctx);
       clearFallbackTimer();
       fallbackTimer = setTimer(() => {

package/lib/locks.ts

@@ -203,6 +203,17 @@ export function formatTelegramLockEntry(lock: TelegramLockEntry): string {
   return lock.cwd ? `pid ${lock.pid}, cwd ${lock.cwd}` : `pid ${lock.pid}`;
 }
 
+function formatTelegramFollowerRegistrationFailure(message: string): string {
+  if (/\b(?:ENOENT|ECONNREFUSED|ETIMEDOUT)\b/u.test(message)) {
+    return (
+      `live owner / unreachable bus endpoint after bounded retries (${message}); ` +
+      "wait briefly for owner recovery, then retry /telegram-connect. " +
+      "Do not force takeover while the owner remains live"
+    );
+  }
+  return message;
+}
+
 function getLockState(
   lock: TelegramLockEntry | undefined,
   pid: number,
@@ -509,7 +520,7 @@ export function createTelegramLockedPollingRuntime<
               ok: false,
               canTakeover: false,
               owner,
-              message: `Telegram bridge is active in another Pi instance (${owner}); follower registration failed: ${failureMessage}.`,
+              message: `Telegram bridge is active in another Pi instance (${owner}); follower registration failed: ${formatTelegramFollowerRegistrationFailure(failureMessage)}.`,
             };
           }
         }

package/lib/logs.ts

@@ -65,7 +65,7 @@ export function getTelegramPreviousRuntimeLogPath(
 ): string {
   return resolveTelegramProfileTempFilePath(
     "logs",
-    "previous.jsonl",
+    "_prev.jsonl",
     agentDir,
     profileName,
   );
@@ -91,7 +91,7 @@ export function createTelegramRuntimeJsonlLog(
   const resolvePreviousPath = () => {
     if (typeof options.previousPath === "function") return options.previousPath();
     if (options.previousPath) return options.previousPath;
-    return resolvePath().replace(/\.jsonl$/u, ".previous.jsonl");
+    return resolvePath().replace(/\.jsonl$/u, "._prev.jsonl");
   };
   const maxBytes = options.maxBytes ?? DEFAULT_MAX_LOG_BYTES;
   const getNowMs = options.getNowMs ?? Date.now;

package/lib/outbound-attachments.ts

@@ -88,6 +88,7 @@ export interface TelegramQueuedOutboundAttachmentView {
 
 export interface TelegramOutboundAttachmentQueueTargetView {
   queuedAttachments: TelegramQueuedOutboundAttachmentView[];
+  guestQueryId?: string;
 }
 
 export interface TelegramQueuedOutboundAttachmentTurnView extends TelegramOutboundAttachmentQueueTargetView {
@@ -96,6 +97,42 @@ export interface TelegramQueuedOutboundAttachmentTurnView extends TelegramOutbou
   target?: TelegramTarget;
 }
 
+export type TelegramGuestCachedAttachmentResult =
+  | {
+      type: "document";
+      id: string;
+      title: string;
+      document_file_id: string;
+      caption?: string;
+    }
+  | {
+      type: "photo";
+      id: string;
+      photo_file_id: string;
+      caption?: string;
+    }
+  | {
+      type: "audio";
+      id: string;
+      audio_file_id: string;
+      caption?: string;
+    }
+  | {
+      type: "voice";
+      id: string;
+      voice_file_id: string;
+      title: string;
+      caption?: string;
+    };
+
+interface TelegramGuestStagingMessage {
+  message_id?: number;
+  document?: { file_id?: string };
+  photo?: Array<{ file_id?: string; file_size?: number }>;
+  audio?: { file_id?: string };
+  voice?: { file_id?: string };
+}
+
 function isTelegramOutboundPhotoAttachmentPath(path: string): boolean {
   const normalized = path.toLowerCase();
   return (
@@ -107,6 +144,27 @@ function isTelegramOutboundPhotoAttachmentPath(path: string): boolean {
   );
 }
 
+function getTelegramGuestAttachmentTransport(path: string): {
+  method: "sendDocument" | "sendPhoto" | "sendAudio" | "sendVoice";
+  fileField: "document" | "photo" | "audio" | "voice";
+} {
+  const normalized = path.toLowerCase();
+  if (
+    normalized.endsWith(".jpg") ||
+    normalized.endsWith(".jpeg") ||
+    normalized.endsWith(".png")
+  ) {
+    return { method: "sendPhoto", fileField: "photo" };
+  }
+  if (normalized.endsWith(".ogg") || normalized.endsWith(".opus")) {
+    return { method: "sendVoice", fileField: "voice" };
+  }
+  if (normalized.endsWith(".mp3")) {
+    return { method: "sendAudio", fileField: "audio" };
+  }
+  return { method: "sendDocument", fileField: "document" };
+}
+
 function formatTelegramOutboundAttachmentSizeLimitError(
   size: number,
   maxSize: number,
@@ -388,6 +446,14 @@ export async function queueTelegramOutboundAttachments(options: {
       statPath: options.statPath,
     });
   }
+  if (
+    options.activeTurn.guestQueryId &&
+    options.activeTurn.queuedAttachments.length + options.paths.length > 1
+  ) {
+    throw new Error(
+      "Telegram Guest Mode supports one attachment per reply; no attachment was queued",
+    );
+  }
   if (
     options.activeTurn.queuedAttachments.length + options.paths.length >
     options.maxAttachmentsPerTurn
@@ -414,6 +480,110 @@ export async function queueTelegramOutboundAttachments(options: {
   };
 }
 
+export async function deliverTelegramGuestCachedAttachment(options: {
+  guestQueryId: string;
+  stagingChatId: number;
+  stagingTarget?: TelegramTarget;
+  attachment: TelegramQueuedOutboundAttachmentView;
+  caption?: string;
+  sendMultipart: TelegramQueuedOutboundAttachmentDeliveryDeps["sendMultipart"];
+  answerGuestQuery: (
+    guestQueryId: string,
+    result: TelegramGuestCachedAttachmentResult,
+  ) => Promise<void>;
+  answerGuestText?: (guestQueryId: string, text: string) => Promise<void>;
+  fallbackText?: string;
+  deleteMessage: (chatId: number, messageId: number) => Promise<void>;
+  recordRuntimeEvent?: TelegramOutboundAttachmentRuntimeEventRecorderPort["recordRuntimeEvent"];
+}): Promise<void> {
+  const transport = getTelegramGuestAttachmentTransport(options.attachment.path);
+  let stagingMessageId: number | undefined;
+  let answerAttempted = false;
+  try {
+    const message = (await options.sendMultipart(
+      transport.method,
+      {
+        chat_id: String(options.stagingChatId),
+        ...getTelegramMultipartTargetFields(options.stagingTarget),
+      },
+      transport.fileField,
+      options.attachment.path,
+      options.attachment.fileName,
+    )) as TelegramGuestStagingMessage;
+    stagingMessageId = message.message_id;
+    const caption = options.caption
+      ? Array.from(options.caption).slice(0, 1024).join("")
+      : undefined;
+    let result: TelegramGuestCachedAttachmentResult;
+    if (transport.fileField === "photo") {
+      const photo = [...(message.photo ?? [])]
+        .sort((left, right) => (left.file_size ?? 0) - (right.file_size ?? 0))
+        .at(-1);
+      if (!photo?.file_id) throw new Error("Guest staging upload returned no photo file_id");
+      result = {
+        type: "photo",
+        id: "attachment-1",
+        photo_file_id: photo.file_id,
+        ...(caption ? { caption } : {}),
+      };
+    } else if (transport.fileField === "audio") {
+      if (!message.audio?.file_id)
+        throw new Error("Guest staging upload returned no audio file_id");
+      result = {
+        type: "audio",
+        id: "attachment-1",
+        audio_file_id: message.audio.file_id,
+        ...(caption ? { caption } : {}),
+      };
+    } else if (transport.fileField === "voice") {
+      if (!message.voice?.file_id)
+        throw new Error("Guest staging upload returned no voice file_id");
+      result = {
+        type: "voice",
+        id: "attachment-1",
+        voice_file_id: message.voice.file_id,
+        title: options.attachment.fileName,
+        ...(caption ? { caption } : {}),
+      };
+    } else {
+      if (!message.document?.file_id)
+        throw new Error("Guest staging upload returned no document file_id");
+      result = {
+        type: "document",
+        id: "attachment-1",
+        title: options.attachment.fileName,
+        document_file_id: message.document.file_id,
+        ...(caption ? { caption } : {}),
+      };
+    }
+    answerAttempted = true;
+    await options.answerGuestQuery(options.guestQueryId, result);
+  } catch (error) {
+    if (
+      !answerAttempted &&
+      options.answerGuestText &&
+      options.fallbackText
+    ) {
+      answerAttempted = true;
+      await options.answerGuestText(options.guestQueryId, options.fallbackText);
+    } else {
+      throw error;
+    }
+  } finally {
+    if (stagingMessageId !== undefined) {
+      try {
+        await options.deleteMessage(options.stagingChatId, stagingMessageId);
+      } catch (error) {
+        options.recordRuntimeEvent?.("attachment", error, {
+          phase: "guest-staging-cleanup",
+          chatId: options.stagingChatId,
+          messageId: stagingMessageId,
+        });
+      }
+    }
+  }
+}
+
 export async function sendTelegramOutboundMessage(options: {
   text: string;
   chatId?: number;

package/lib/paths.ts

@@ -76,9 +76,10 @@ export function getTelegramDiagnosticsDisplayPaths(profileName?: string): {
   logs: string;
 } {
   const suffix = getTelegramProfilePathSuffix(profileName);
+  const profileSlug = suffix.slice(1);
   return {
     state: `~/.pi/agent/tmp/telegram/state${suffix}.json`,
-    logs: `~/.pi/agent/tmp/telegram/logs${suffix}.jsonl`,
+    logs: `~/.pi/agent/tmp/telegram/logs${profileSlug ? `.${profileSlug}` : ""}.jsonl`,
   };
 }
 

package/lib/queue.ts

@@ -899,6 +899,16 @@ export interface TelegramAgentEndRuntimeDeps<
     options?: { parseMode?: string },
   ) => Promise<void>;
   sendGuestReply?: (guestQueryId: string, markdown: string) => Promise<void>;
+  sendGuestAttachment?: (
+    turn: TTurn,
+    attachment: QueuedAttachment,
+    caption?: string,
+  ) => Promise<void>;
+  sendGuestVoiceReply?: (
+    turn: TTurn,
+    plan: TelegramAgentEndOutboundReplyPlan<TReplyMarkup>,
+    caption?: string,
+  ) => Promise<void>;
   planOutboundReply?: (
     markdown: string,
   ) => TelegramAgentEndOutboundReplyPlan<TReplyMarkup>;
@@ -958,6 +968,8 @@ export interface TelegramAgentEndHookRuntimeDeps<
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
   answerGuestQuery?: TelegramAgentEndRuntimeDeps<TTurn>["answerGuestQuery"];
   sendGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestReply"];
+  sendGuestAttachment?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestAttachment"];
+  sendGuestVoiceReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestVoiceReply"];
   planOutboundReply?: TelegramAgentEndRuntimeDeps<
     TTurn,
     TReplyMarkup
@@ -1083,6 +1095,8 @@ export function createTelegramAgentEndHook<
       sendQueuedAttachments: deps.sendQueuedAttachments,
       answerGuestQuery: deps.answerGuestQuery,
       sendGuestReply: deps.sendGuestReply,
+      sendGuestAttachment: deps.sendGuestAttachment,
+      sendGuestVoiceReply: deps.sendGuestVoiceReply,
       planOutboundReply: deps.planOutboundReply,
       sendOutboundReplyArtifacts: deps.sendOutboundReplyArtifacts,
       getDefaultChatId: deps.getDefaultChatId,
@@ -1181,7 +1195,38 @@ export async function handleTelegramAgentEndRuntime<
       if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
       return;
     }
-    if (finalText) {
+    const [guestAttachment] = turn.queuedAttachments;
+    if (guestAttachment && deps.sendGuestAttachment) {
+      try {
+        await deps.sendGuestAttachment(
+          turn,
+          guestAttachment,
+          finalText || undefined,
+        );
+      } catch (error) {
+        deps.recordRuntimeEvent?.("delivery", error, {
+          phase: "guest-attachment",
+          guestQueryId: turn.guestQueryId,
+        });
+      }
+    } else if (
+      outboundReply &&
+      (outboundReply.voiceText || outboundReply.voiceReplies?.length) &&
+      deps.sendGuestVoiceReply
+    ) {
+      try {
+        await deps.sendGuestVoiceReply(
+          turn,
+          outboundReply,
+          finalText || undefined,
+        );
+      } catch (error) {
+        deps.recordRuntimeEvent?.("delivery", error, {
+          phase: "guest-voice",
+          guestQueryId: turn.guestQueryId,
+        });
+      }
+    } else if (finalText) {
       if (deps.sendGuestReply) {
         await deps.sendGuestReply(turn.guestQueryId, finalText);
       } else {

package/lib/setup.ts

@@ -197,8 +197,14 @@ export function createTelegramSetupPromptRuntime<
         promptEditor: (label, value) => ctx.ui.editor(label, value),
         getMe: deps.getMe,
         persistConfig: async (config) => {
-          await deps.persistConfig(config);
+          const previousConfig = deps.getConfig();
           deps.setConfig(config);
+          try {
+            await deps.persistConfig(config);
+          } catch (error) {
+            deps.setConfig(previousConfig);
+            throw error;
+          }
         },
         notify: (message, level) => ctx.ui.notify(message, level),
         startPolling: () => deps.startPolling(ctx),

package/lib/status.ts

@@ -181,6 +181,7 @@ export interface TelegramBridgeStatusLineState {
   hasBotToken?: boolean;
   botUsername?: string;
   activeProfileName?: string;
+  diagnosticPaths?: { state: string; logs: string };
   allowedUserId?: number;
   botThreadMode?: "unknown" | "enabled" | "disabled";
   botThreadModeUpdatedAtMs?: number;
@@ -259,6 +260,9 @@ export interface TelegramBridgeStatusRuntimeDeps<
   statusKey?: string;
   getConfig: () => TelegramBridgeStatusConfig;
   getActiveProfileName?: () => string | undefined;
+  getDiagnosticPaths?: (
+    profileName?: string,
+  ) => { state: string; logs: string };
   isPollingActive: () => boolean;
   getActiveSourceMessageIds: () => number[] | undefined;
   hasActiveTurn: () => boolean;
@@ -620,10 +624,12 @@ export function createTelegramBridgeStatusRuntime<
     getBridgeStatusLineState: () => {
       const config = deps.getConfig();
       const botThreadMode = deps.getBotThreadMode?.();
+      const activeProfileName = deps.getActiveProfileName?.();
       return {
         hasBotToken: Boolean(config.botToken),
         botUsername: config.botUsername,
-        activeProfileName: deps.getActiveProfileName?.(),
+        activeProfileName,
+        diagnosticPaths: deps.getDiagnosticPaths?.(activeProfileName),
         allowedUserId: config.allowedUserId,
         botThreadMode: botThreadMode?.threadMode,
         botThreadModeUpdatedAtMs: botThreadMode?.updatedAtMs,
@@ -774,9 +780,6 @@ export function buildTelegramStatusBarText(
     return `${label} ${theme.fg("warning", "electing")}${queued}`;
   if (!state.pollingActive && state.busRole !== "follower")
     return `${theme.fg("accent", "telegram")} ${theme.fg("muted", "disconnected")}${queued}`;
-  if (state.compactionInProgress) {
-    return `${label} ${theme.fg("warning", "compacting")}${queued}`;
-  }
   if (state.processing) {
     const processingStatus = state.queuedStatus
       ? "active"
@@ -1058,19 +1061,18 @@ function buildTelegramBridgeCompactStatusLines(
       ? ` (control=${controlQueueCount}, priority=${priorityQueueCount}, default=${defaultQueueCount})`
       : ""
   }`;
-  const executionState = state.compactionInProgress
-    ? "compacting"
-    : state.pendingDispatch
-      ? "pending dispatch"
-      : state.activeSourceMessageIds?.length
-        ? "active"
-        : "idle";
+  const executionState = state.pendingDispatch
+    ? "pending dispatch"
+    : state.activeSourceMessageIds?.length
+      ? "active"
+      : "idle";
   const profileSuffix = state.activeProfileName
     ? `.${state.activeProfileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`
     : "";
-  const diagnosticsPaths = {
+  const profileSlug = profileSuffix.slice(1);
+  const diagnosticsPaths = state.diagnosticPaths ?? {
     state: `~/.pi/agent/tmp/telegram/state${profileSuffix}.json`,
-    logs: `~/.pi/agent/tmp/telegram/logs${profileSuffix}.jsonl`,
+    logs: `~/.pi/agent/tmp/telegram/logs${profileSlug ? `.${profileSlug}` : ""}.jsonl`,
   };
   return [
     "connection:",
@@ -1251,7 +1253,6 @@ function buildContextSummary(
 }
 
 function buildStatusSummary(ctx: TelegramStatusContext): string {
-  if (ctx.isCompactionInProgress?.()) return "compacting";
   if (ctx.hasPendingMessages?.()) return "pending";
   if (ctx.isIdle?.() === false) return "active";
   if (ctx.isIdle?.() === true) return "idle";

package/lib/telegram-api.ts

@@ -287,6 +287,44 @@ export interface TelegramFileDownloadOptions {
   maxFileSizeBytes?: number;
 }
 
+export type TelegramGuestCachedMediaResult =
+  | {
+      type: "document";
+      id: string;
+      title: string;
+      document_file_id: string;
+      caption?: string;
+      parse_mode?: string;
+    }
+  | {
+      type: "photo";
+      id: string;
+      photo_file_id: string;
+      caption?: string;
+      parse_mode?: string;
+    }
+  | {
+      type: "audio";
+      id: string;
+      audio_file_id: string;
+      caption?: string;
+      parse_mode?: string;
+    }
+  | {
+      type: "voice";
+      id: string;
+      voice_file_id: string;
+      title: string;
+      caption?: string;
+      parse_mode?: string;
+    };
+
+export interface TelegramAnswerGuestQueryOptions {
+  parseMode?: string;
+  richMessage?: TelegramInputRichMessage;
+  result?: TelegramGuestCachedMediaResult;
+}
+
 export interface TelegramAnswerCallbackQueryOptions {
   recordRuntimeEvent?: (
     kind: "api",
@@ -322,7 +360,7 @@ export interface TelegramApiClient {
   answerGuestQuery?: (
     guestQueryId: string,
     text?: string,
-    options?: { parseMode?: string; richMessage?: TelegramInputRichMessage },
+    options?: TelegramAnswerGuestQueryOptions,
   ) => Promise<void>;
 }
 
@@ -401,7 +439,7 @@ export interface TelegramBridgeApiRuntime {
   answerGuestQuery: (
     guestQueryId: string,
     text?: string,
-    options?: { parseMode?: string; richMessage?: TelegramInputRichMessage },
+    options?: TelegramAnswerGuestQueryOptions,
   ) => Promise<void>;
   deleteMessage: (chatId: number, messageId: number) => Promise<void>;
   prepareTempDir: () => Promise<number>;
@@ -1312,12 +1350,12 @@ export function createTelegramBridgeApiRuntime(
     answerGuestQuery: (
       guestQueryId: string,
       text: string | undefined,
-      options:
-        | { parseMode?: string; richMessage?: TelegramInputRichMessage }
-        | undefined,
+      options: TelegramAnswerGuestQueryOptions | undefined,
     ) => {
       const body: Record<string, unknown> = { guest_query_id: guestQueryId };
-      if (text !== undefined || options?.richMessage) {
+      if (options?.result) {
+        body.result = options.result;
+      } else if (text !== undefined || options?.richMessage) {
         const inputContent: Record<string, unknown> = options?.richMessage
           ? { rich_message: options.richMessage }
           : { message_text: text };

package/package.json

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