@llblab/pi-kit 0.35.0 → 0.35.1

package/BACKLOG.md

@@ -4,6 +4,7 @@ Package pins, resource order and bundled runtime ownership remain authoritative
 
 ## Carried checks
 
+- **Installed 0.35.1 Telegram smoke (operator-owned):** After separately authorized kit installation/reload, verify Reroute removes an exhausted temporary tab and Restore keeps the new tab while deleting its unprotected predecessor. Confirm protected work survives. Guest PNG/JPEG, document and MP3 replacement plus staging cleanup remain explicitly deferred upstream live checks; verify unsupported OGG/Opus feedback separately. Upstream idle-leader acceptance and kit packaging checks do not certify this installation.
 - **Installed 0.35.0 Telegram smoke (operator-owned):** After separately authorized installation/reload of both peers, verify same-process follower session replacement keeps the Thread, letter slot and title without a second connected notice. Check shared `threads.displayMode` through Settings across profiles and confirm the retired profile key is ignored without migration. Package validation does not certify installed clients.
 - **Installed 0.34.3 typing smoke (operator-owned):** After separately authorized installation/reload of both peers, verify native typing during streaming, UI prompts and compaction without recurring local authorization churn. Check actual client versions, including iOS; successful HTTP issuance and synthetic tests do not prove client visibility. Use disposable sessions and preserve accepted work.
 - **Installed 0.34.2 smoke (operator-owned):** After separately authorized installation/reload, verify Pi 1.2 custom-message completions no longer raise the Telegram prompt-hook error, adjacent button matrices retain their rows and callbacks, and native Windows Codex CLI fallback works on an actual Windows host. Use disposable settings; package validation and synthetic SDK probes do not certify installed clients or authorize live fault injection.

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.35.1: Telegram Guest Media and Routing Cleanup
+
+- `Telegram cleanup`: Advances only the exact Telegram pin to `0.57.1`. Exhausted Reroute tabs and Restore's old tab are no longer blocked by unrelated targetless creation attempts, while accepted work and uncertain deletion stay protected. Fresh local menu Reroute and supported Restore hold command effects through their cleanup decision. Other pins, package membership and resource order are unchanged.
+- `Guest media`: Queued photos, documents and MP3 now replace an acknowledged Guest Mode placeholder instead of being silently skipped. Confirmed failures report errors, uncertain edits are not replayed, and unsupported OGG/Opus replacement is rejected explicitly. Guest media client acceptance remains a deferred upstream follow-up, not proof supplied by kit validation.
+
 ## 0.35.0: Telegram Thread Continuity and Shared Settings
 
 - `Telegram continuity`: Advances only the exact Telegram pin to `0.57.0`. Same-process follower session replacement preserves the Thread, letter slot and acknowledged title without a second connected notice; cross-process handoff notices use the acknowledged title. Other pins, package membership and resource order are unchanged.

package/README.md

@@ -18,7 +18,7 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.13.1` | OpenAI/legacy Codex subscription quota and Business credit status, with persistent priority Fast toggle mirrored in Telegram |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.9.0` | Visible continuation scheduling and bounded worker Skills through compiled, manifest-owned resources |
 | [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.26.4` | Scoped context/memory compiler with step-independent current memory, stable Passive/Active modes and visible blocked-state status |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.57.0` | Telegram companion with per-prompt Steer, queued controls, Reroute/Restore, recoverable connections, previews, follower Threads, files, and voice |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.57.1` | Telegram companion with per-prompt Steer, queued controls, Reroute/Restore, recoverable connections, previews, follower Threads, files, and voice |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
 Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.

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

@@ -90,7 +90,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - Foreign forwarding settles as `accepted`, `retryable`, or `terminal-rejected`. Only an authenticated acknowledgement carrying the expected `deliveryId` and `sourceUpdateId` releases leader journal authority. Negative, missing, stale, mismatched, or capacity-failed settlement remains durable; callback error answers are side effects only. Exception: the operator-approved fixed chooser deadline may discard its exact unclaimed donor pending source without a body archive or delivery-success claim. Accepted recipient queue/work and bound Threads are untouched; old donor controls and late reports cannot replay it. The lifetime and temporary cleanup contract lives in `docs/architecture.md`.
 - A forwarding delivery id is stable across registration replacement and derives from envelope kind, source `update_id`, and stable recipient binding. Runtime instance and registration generation remain separate attempt fences. Persisted message ownership carries the stable binding so replay can rebind only to its current authenticated registration.
 - A queued receipt persists its acquiring runtime instance, OS pid/process-birth identity, session generation, acquisition id, and acquisition time. Only exact authority may settle or discard it. Cached presence is not current execution proof: prepared custody must revalidate the exact queued owner/group without recovery and refuse offers or uncertain reads. Completion requires an exact removal acknowledgement, never merely `!ready`; a retained acknowledgement permits local cleanup only, not replay. Same-process session replacement may reconstruct the claim and the original process may settle after transport ownership moves; a foreign process may neither replay nor settle it through generic removal or a copied acquisition id.
-- Startup and elapsed time are not owner-death proof; queued authority has no time lease. Dead-owner cleanup groups the complete receipt and transactionally rechecks pid liveness plus process-birth identity: only an absent PID or mismatched stable Linux/macOS/Windows birth proof discards all session-owned sources without replay; a matching proof is `alive`, while inaccessible birth metadata is `unverifiable`, and both non-dead outcomes keep authority queued. Under actual `A`–`Z` allocation pressure, retirement may invoke that journal-owned CAS only for a current inactive binding after complete strict source inspection, no local work/live owner/delivery authority, whole unoffered receipt groups, and a preflight proving every grouped owner dead. It must then recapture all protection before preparing deletion; partial progress never grants deletion authority. The live-transfer contract is authenticated offer → exact-generation bounded payload staging → recipient CAS acceptance → exact receipt-and-owner ACK → donor removal → recipient readiness. The offer freezes donor settlement/recovery; controls rebuild local closures; negative/mismatched pre-acceptance ACK cancels only an unaccepted offer and retains donor work; a lost post-acceptance ACK cannot cancel recipient authority and leaves donor memory frozen for explicit reconciliation.
+- Startup and elapsed time are not owner-death proof; queued authority has no time lease. Dead-owner cleanup groups the complete receipt and transactionally rechecks pid liveness plus process-birth identity: only an absent PID or mismatched stable Linux/macOS/Windows birth proof discards all session-owned sources without replay; a matching proof is `alive`, while inaccessible birth metadata is `unverifiable`, and both non-dead outcomes keep authority queued. Under actual `A`–`Z` allocation pressure, retirement may invoke that journal-owned CAS only for a current inactive binding after complete strict source inspection, no local work/live owner/delivery authority, whole unoffered receipt groups, and a preflight proving every grouped owner dead. It must then recapture all protection before preparing deletion; partial progress never grants deletion authority. Fully resolved, positively unbound temporary-tab cleanup may independently recover historical v1 queued receipts under its profile admission and journal source serialization: complete strict namespace/reference inspection, whole unoffered receipt groups, fresh process-death proof and the existing journal CAS are required. Alive/unverifiable owners and unsupported custody remain protected; this recovery never runs from read-only protection checks, and every ordinary target/source protection is recaptured before deletion. The live-transfer contract is authenticated offer → exact-generation bounded payload staging → recipient CAS acceptance → exact receipt-and-owner ACK → donor removal → recipient readiness. The offer freezes donor settlement/recovery; controls rebuild local closures; negative/mismatched pre-acceptance ACK cancels only an unaccepted offer and retains donor work; a lost post-acceptance ACK cannot cancel recipient authority and leaves donor memory frozen for explicit reconciliation.
 - Execution failures persist bounded diagnostics and attempt state as `retry-wait`, except that an exact Telegram HTTP 400 stale/deleted-thread API failure with a proven `{chatId, threadId}` terminally settles the currently executing source after best-effort shared binding invalidation. Automatic retry continues indefinitely with exponential `1s → 2s → 4s → 8s → 16s → 32s → 60s` delay capped at 60 seconds; later independent updates continue draining, durable authority is never silently discarded, and legacy `failed` entries resume automatically at startup. Snapshot-plus-segment journals compact only after 256 unapplied revisions or 4 MiB; snapshot-first cleanup tolerates redundant segments, and empty authority may atomically rebind bot/profile identity. Missing snapshots left by the retired broad temp cleanup rebuild only from a complete provably empty segment chain, while revisionless snapshots may recover from a validated later segment predecessor; otherwise the transaction-locked reset deletes damaged segments before publishing a fresh journal, with accepted input loss and informational evidence, not a quarantine copy. Unsupported versions remain untouched; strict protection reads never reset. Startup best-effort removes obsolete current-runtime root/session `recovery/` folders without touching pre-0.52.0 storage.
 - Business connection chats are a separate namespace even when their chat/message IDs match bot-chat IDs. Default DM routing must never infer private-queue deletion intent from `deleted_business_messages`; raw companion handlers remain separate owners.
 - Clock-bearing chooser sources survive cold spending until their fixed deadline. A restarted owner revives one in place only while its saved phase is still `waiting`, its recorded chooser location is known, its tab stays unbound and live threads exist; that waiting phase is the proof no selection or effect ran. Selected, expired or bound sources keep the protective hold, and new-world forgetting preserves their positively unbound temporary frame. Expiry is a donor discard, not recipient cancellation or source execution completion. Confirmed expiry releases worker custody before UI/cleanup awaits; metadata retries retain no prompt bodies and cannot repeat an issued delete.

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

@@ -2,7 +2,12 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
-- [ ] **Connection recovery live acceptance.** Verify operator-run leader/follower reconnect after interrupted creation on updated peers. Known target reuse and unknown-target abandonment have separate local regressions; do not infer live recovery from them. Also verify a long-deleted follower tab, follower `/start` Restore with negotiated menu-alias support, and leader Restore confirmation on the first click plus separately proven old-tab cleanup. Record leftover-tab behavior, exact peer capabilities and diagnostics; local regressions and release authorization do not replace this live evidence.
+- [ ] **Routing extensions and follow-up coverage.** Preserve live/unverifiable owners, offered receipts, exact source references, session/transport fences and one-shot deletion while extending beyond the current supported handoffs.
+  - [ ] **Follower menu handoff.** Establish whether deletion-before-execution warrants a separately negotiated Reroute acceptance/release contract. Ordinary follower ACK confirms durable custody, not held execution; existing held-command RPCs belong to Restore relocation and cannot silently change ordinary forwarding. Require exact recipient generation, bounded observation and no replay after uncertain release.
+  - [ ] **Non-menu and historical-source boundary.** Resolve the intended ordering for mutating/queue-producing commands and cold/revived originals before expanding the fresh local menu path. Queue receipt acceptance and historical retention must remain authoritative; never pre-complete sources, weaken fresh-source readiness or block accepted work solely to force deletion. Preserve current behavior until a supported handoff is proven.
+  - [ ] **Protected-work live coverage.** Exercise Reroute and Restore with protected earlier work to confirm cleanup waits without losing work. Idle leader acceptance and native regressions do not prove every busy-session client scenario. No manual journal edits or deletion of live tabs to obtain evidence.
+- [ ] **Guest inline media live acceptance.** Explicitly deferred beyond 0.57.1 by operator release approval; not completed. After separately authorized reload, verify queued PNG/JPEG, documents and MP3 replace the acknowledged placeholder, with and without caption, and staging messages are removed. Confirm OGG/Opus attachment rejection and visible voice-markup explanation. Mocked Bot API coverage does not prove live-client rendering; use disposable artifacts and preserve accepted work.
+- [ ] **Connection recovery live acceptance.** Verify operator-run leader/follower reconnect after interrupted creation on updated peers. Known target reuse and unknown-target abandonment have separate local regressions; do not infer live recovery from them. Also verify a long-deleted follower tab and follower `/start` Restore with negotiated menu-alias support. Record leftover-tab behavior, exact peer capabilities and diagnostics; local regressions and release authorization do not replace this live evidence.
 - [ ] **Steer follow-up live acceptance.** Release authorization explicitly defers these checks beyond 0.56.0; do not treat automated coverage or the accepted busy-run smoke as live proof for unrun scenarios. Preserve the [queue and dispatch contract](./docs/architecture.md#queue-and-dispatch-safety).
   - [ ] **Operator scenarios.** Verify final selector/counter rendering; idle packets, native pending input, compaction, model switching, abort/Continue, complete media groups, Reroute/Restore, negotiated leader/follower transfer, reply/preview ownership and session-generation replacement. Record actual Pi/OS/Telegram versions, peer capabilities and redacted outcomes. Reload and disposable live tests require operator intent; do not manipulate runtime files to obtain acceptance.
   - [ ] **Restore recipient refusal after leadership change.** Diagnose a retained routing chooser refusing the selected current leader with unavailable recipient authority. Identify the exact context/session/Workspace mismatch before proposing recovery; do not treat an absent follower registry as the cause of a leader-target refusal, bypass fences or mutate live state.

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

@@ -4,6 +4,12 @@
 
 ## Unreleased
 
+## 0.57.1: Guest Media and Routing Cleanup
+
+- `Guest attachments`: Queued photos, documents and MP3 audio now replace the acknowledged Guest Mode placeholder instead of being silently skipped. Upload failures and confirmed edit rejections report errors; uncertain edits are not replayed or overwritten. OGG/Opus attachments are rejected before queueing on this path, and voice markup explains the limitation. Live-client media acceptance remains a deferred follow-up. Fixes #346.
+- `Routing cleanup`: Exhausted Reroute tabs and a restored instance's old tab are no longer blocked by unrelated creation attempts with unknown targets. Uncertain creation records stay intact; binding, slot, owner and concrete or recovered target conflicts still protect. Temporary cleanup can recover whole historical receipts from proven-dead owners; live/unverifiable owners, handoff offers and damaged sources remain protected. Idle leader Reroute and Restore passed operator live checks.
+- `Command ordering`: Fresh local menu Reroute waits for exact source removal and a temporary-tab cleanup attempt before rendering. Restore confirms the new binding, decides old-tab cleanup, then releases held input. Busy work retains protection, and uncertain deletion never repeats. Other Reroute commands, follower delivery and sources without fresh completion readiness retain their existing paths.
+
 ## 0.57.0: Thread Continuity and Shared Settings
 
 - `Config`: Thread display now lives in shared top-level `threads.displayMode`, beside the other Settings preferences; profiles hold only bot identity and the paired owner. The old `profiles.<name>.threadDisplayMode` key is not migrated and is ignored, so configs without the new key use the Letters default until Settings saves a choice.

package/node_modules/@llblab/pi-telegram/dist/lib/bindings.d.ts

@@ -269,7 +269,7 @@ interface TelegramLifecycleBindingDeps {
     shutdownGenerativeAppLiveSurfaces?: () => void;
     resolveAutomaticThreadCleanupEnabled?: () => boolean | Promise<boolean>;
     buttonActionStore: OutboundHandlers.TelegramButtonActionStore;
-    callMultipart: OutboundHandlers.TelegramVoiceReplySenderDeps["sendMultipart"];
+    callMultipart: (...args: Parameters<TelegramApi.TelegramBridgeApiRuntime["callMultipart"]>) => Promise<unknown>;
     sendChatAction: NonNullable<OutboundHandlers.TelegramVoiceReplySenderDeps["sendChatAction"]>;
     sendRecordVoiceAction: NonNullable<OutboundHandlers.TelegramVoiceReplySenderDeps["sendRecordVoiceAction"]>;
     sendMarkdownReply: Queue.TelegramAgentEndHookRuntimeDeps<Queue.PendingTelegramTurn, Pi.ExtensionContext, Pi.AgentEndEvent["messages"][number], Keyboard.TelegramInlineKeyboardMarkup>["sendMarkdownReply"];
@@ -278,6 +278,7 @@ interface TelegramLifecycleBindingDeps {
     onSteerTurnEnd?: TelegramQueueBindingRuntime<Pi.ExtensionContext>["onTurnEnd"];
     onPromptHandedOff?: (turn: Queue.PendingTelegramTurn, ctx: Pi.ExtensionContext) => void;
     answerGuestQuery: TelegramApi.TelegramBridgeApiRuntime["answerGuestQuery"];
+    editGuestInlineMessage?: TelegramApi.TelegramBridgeApiRuntime["editGuestInlineMessage"];
     deleteMessage: TelegramApi.TelegramBridgeApiRuntime["deleteMessage"];
     sendGuestReply: NonNullable<Queue.TelegramAgentEndHookRuntimeDeps<Queue.PendingTelegramTurn, Pi.ExtensionContext, Pi.AgentEndEvent["messages"][number], Keyboard.TelegramInlineKeyboardMarkup>["sendGuestReply"]>;
     editGuestReply?: Queue.TelegramAgentEndHookRuntimeDeps<Queue.PendingTelegramTurn, Pi.ExtensionContext, Pi.AgentEndEvent["messages"][number], Keyboard.TelegramInlineKeyboardMarkup>["editGuestReply"];
@@ -300,5 +301,5 @@ interface TelegramLifecycleBindingDeps {
     /** Settled-session hint for owners that wait on agent idleness, such as old-tab cleanup after a live rebind. */
     onSessionSettled?: (ctx: Pi.ExtensionContext) => void;
 }
-export declare function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onSteerTurnEnd, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive, getSessionGeneration, isTurnTransportActive, updateStatus, recordRuntimeEvent, onSessionSettled, }: TelegramLifecycleBindingDeps): void;
+export declare function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onSteerTurnEnd, onPromptHandedOff, answerGuestQuery, editGuestInlineMessage, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive, getSessionGeneration, isTurnTransportActive, updateStatus, recordRuntimeEvent, onSessionSettled, }: TelegramLifecycleBindingDeps): void;
 export {};

package/node_modules/@llblab/pi-telegram/dist/lib/bindings.js

@@ -657,7 +657,7 @@ export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, pe
         },
     });
 }
-export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onSteerTurnEnd, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive = () => true, getSessionGeneration, isTurnTransportActive, updateStatus, recordRuntimeEvent, onSessionSettled, }) {
+export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onSteerTurnEnd, onPromptHandedOff, answerGuestQuery, editGuestInlineMessage, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive = () => true, getSessionGeneration, isTurnTransportActive, updateStatus, recordRuntimeEvent, onSessionSettled, }) {
     const agentEndResetter = Runtime.createTelegramAgentEndResetter({
         abort,
         typing,
@@ -677,7 +677,7 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
         recordOwnership: recordMessageOwnership,
         recordRuntimeEvent,
     });
-    const sendGuestAttachment = async (turn, attachment, caption) => {
+    const sendGuestAttachment = async (turn, attachment, caption, options) => {
         const stagingTarget = proactivePushTargetGetter();
         const stagingChatId = stagingTarget?.chatId;
         if (stagingChatId === undefined) {
@@ -685,11 +685,19 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
         }
         await OutboundAttachments.deliverTelegramGuestCachedAttachment({
             guestQueryId: turn.guestQueryId,
+            guestInlineMessageId: turn.guestInlineMessageId,
+            editGuestInlineMessage,
+            isDeliveryActive: options?.isDeliveryActive,
             stagingChatId,
             stagingTarget,
             attachment,
             caption,
-            sendMultipart: callMultipart,
+            sendMultipart: (method, fields, fileField, path, name) => callMultipart(method, fields, fileField, path, name, {
+                assertAuthority() {
+                    if (options?.isDeliveryActive?.() === false)
+                        throw new Error("Guest attachment upload lost authority.");
+                },
+            }),
             answerGuestQuery: (guestQueryId, result) => answerGuestQuery(guestQueryId, undefined, { result }),
             answerGuestText: (guestQueryId, text) => answerGuestQuery(guestQueryId, text),
             fallbackText: caption ||

package/node_modules/@llblab/pi-telegram/dist/lib/bus-api.js

@@ -339,9 +339,9 @@ export function createTelegramBusAwareApiRuntime(deps) {
                 ? deps.directRuntime.answerGuestQueryForInlineMessage(guestQueryId, text, options)
                 : rejectTelegramDirectOwnership("answerGuestQueryForInlineMessage");
         },
-        editGuestInlineMessage(inlineMessageId, content) {
+        editGuestInlineMessage(inlineMessageId, content, options) {
             return deps.ownsDirect()
-                ? deps.directRuntime.editGuestInlineMessage(inlineMessageId, content)
+                ? deps.directRuntime.editGuestInlineMessage(inlineMessageId, content, options)
                 : rejectTelegramDirectOwnership("editGuestInlineMessage");
         },
         async deleteMessage(chatId, messageId) {

package/node_modules/@llblab/pi-telegram/dist/lib/commands.d.ts

@@ -627,6 +627,8 @@ export interface TelegramSelectedCommandAdmission {
     /** Independent exact recipient/target lifetime, including inside captured menu transport adapters. */
     assertRecipientCurrent(): void;
     reportCompleted(): boolean;
+    /** Optional recipient release barrier after acceptance; rejection suppresses effects without replay. */
+    beforeEffects?(): Promise<void>;
 }
 export declare function createTelegramCommandHandler<TMessage extends TelegramCommandRuntimeMessage, TContext>(deps: TelegramCommandRuntimeDeps<TMessage, TContext>): ((commandName: string | undefined, message: TMessage, ctx: TContext, commandArgs?: string) => Promise<boolean>) & {
     /** Command-only producer execution; Routing must supply the captured plan and released exact-source authority. */

package/node_modules/@llblab/pi-telegram/dist/lib/commands.js

@@ -1667,7 +1667,7 @@ export function createTelegramCommandHandler(deps) {
         const captured = { ...deps }, parsed = { ...command }, message = parsed.name === "status"
             ? copySelectedMenuCarrier(original)
             : copySelectedReplyAnchor(original);
-        const assertRecipientCurrent = admission.assertRecipientCurrent, report = admission.reportCompleted;
+        const assertRecipientCurrent = admission.assertRecipientCurrent, report = admission.reportCompleted, beforeEffects = admission.beforeEffects;
         const effects = parsed.name === "status"
             ? undefined
             : {
@@ -1693,8 +1693,13 @@ export function createTelegramCommandHandler(deps) {
                 throw new Error(`Selected ${parsed.name} plan owner is unavailable.`);
         };
         return issueSelectedOnce(assertCurrent, async () => {
-            if (plan.completion === "before-effect" && !report.call(admission))
-                return false;
+            if (plan.completion === "before-effect") {
+                if (!report.call(admission))
+                    return false;
+                if (beforeEffects)
+                    await beforeEffects();
+                assertRecipientCurrent();
+            }
             return prepared.run({
                 message,
                 command: parsed,
@@ -1720,7 +1725,7 @@ export function createTelegramCommandHandler(deps) {
             ...copySelectedReplyAnchor(original),
             from: { ...original.from },
         };
-        const assertRecipientCurrent = admission.assertRecipientCurrent, reportCompleted = admission.reportCompleted;
+        const assertRecipientCurrent = admission.assertRecipientCurrent, reportCompleted = admission.reportCompleted, beforeEffects = admission.beforeEffects;
         const assertAdmissionCurrent = createSelectedSemanticGuard(admission, () => captured.assertExecutionCurrent?.(original), false);
         const assertSemanticCurrent = () => {
             assertAdmissionCurrent();
@@ -1732,7 +1737,7 @@ export function createTelegramCommandHandler(deps) {
             persistAllowedUserId: async () => {
                 throw new Error(`Selected ${name} cannot acquire pairing authority.`);
             },
-        }, { assertSemanticCurrent, assertRecipientCurrent, reportCompleted }));
+        }, { assertSemanticCurrent, assertRecipientCurrent, reportCompleted, beforeEffects }));
     };
     const prepareSelectedConfirmation = (name) => (command, messages, ctx, admission) => {
         const original = messages[0], captured = { ...deps };
@@ -2036,7 +2041,7 @@ export function createTelegramCommandHandler(deps) {
                 typeof admission.reportCompleted !== "function")
                 return undefined;
             const assertSourceCurrent = admission.assertSourceCurrent, assertRecipientCurrent = admission.assertRecipientCurrent;
-            const reportCompleted = admission.reportCompleted, assertExecutionCurrent = deps.assertExecutionCurrent;
+            const reportCompleted = admission.reportCompleted, beforeEffects = admission.beforeEffects, assertExecutionCurrent = deps.assertExecutionCurrent;
             const assertIssuanceCurrent = () => {
                 assertSourceCurrent.call(admission);
                 assertExecutionCurrent?.call(deps, original);
@@ -2060,8 +2065,14 @@ export function createTelegramCommandHandler(deps) {
                 openSettingsMenu: menuDeps.openSettingsMenu &&
                     ((value, context) => menuDeps.openSettingsMenu(value, context, recipientOptions)),
             };
-            return issueSelectedOnce(assertIssuanceCurrent, async () => reportCompleted.call(admission) &&
-                handleTelegramCommandRuntime(name, message, ctx, recipientDeps, args));
+            return issueSelectedOnce(assertIssuanceCurrent, async () => {
+                if (!reportCompleted.call(admission))
+                    return false;
+                if (beforeEffects)
+                    await beforeEffects();
+                assertRecipientCurrent();
+                return handleTelegramCommandRuntime(name, message, ctx, recipientDeps, args);
+            });
         },
     });
 }
@@ -2157,6 +2168,8 @@ async function handleTelegramHelpCommand(commandName, message, ctx, deps, admiss
         assertSemanticCurrent();
         if (!admission.reportCompleted())
             return false;
+        if (admission.beforeEffects)
+            await admission.beforeEffects();
         admission.assertRecipientCurrent();
     }
     const assertEffectCurrent = admission?.assertRecipientCurrent ??

package/node_modules/@llblab/pi-telegram/dist/lib/extension.js

@@ -1033,6 +1033,29 @@ export default function (pi) {
         delivery: deliveryLifecycleRuntime,
         api: telegramApiTargetActivityRuntime,
     });
+    const prepareTemporaryThreadJournalInspection = function (target, requiredJournalBindingKeys, ownInputs) {
+        const binding = resolveTelegramUpdateJournalBinding();
+        const botToken = configStore.getBotToken();
+        if (!binding || !botToken)
+            return undefined;
+        const profile = configStore.getActiveProfileName() ?? "default";
+        const botIdentity = Journal.createTelegramUpdateJournalBotIdentity({ botToken, botId: getTelegramBotId() });
+        return {
+            directory: Paths.resolveTelegramTempDir(), profile, botIdentity,
+            pollingPath: telegramLeaderJournalPath.resolve(configStore.getActiveProfileName()),
+            requiredJournalBindingKeys: [binding.recoveryKey, ...requiredJournalBindingKeys],
+            ...(target.threadId !== undefined && ownInputs
+                ? { cleanup: { target: { chatId: target.chatId, threadId: target.threadId }, ownInputs } } : {}),
+            limits: { maxDirectoryEntries: 10_000, maxFiles: 4096, maxBytes: 64 * 1024 * 1024,
+                maxEntries: 10_000, maxWork: 100_000 },
+            withSourceReference(path, operation) {
+                return telegramJournalReferenceRegistry.withReference({
+                    referenceClass: "operator-disposition",
+                    recoveryKey: Journal.createTelegramUpdateJournalBindingKey({ path, profileName: profile, botIdentity }),
+                }, operation);
+            },
+        };
+    };
     const inboundRouteRuntime = Routing.createTelegramInboundRouteRuntime({
         configStore,
         callApi: callTelegramApi,
@@ -1112,53 +1135,24 @@ export default function (pi) {
             });
         },
         inspectTemporaryThreadSources(target, requiredJournalBindingKeys, ownInputs) {
-            const binding = resolveTelegramUpdateJournalBinding();
-            const botToken = configStore.getBotToken();
-            if (!binding || !botToken)
+            const input = prepareTemporaryThreadJournalInspection(target, requiredJournalBindingKeys, ownInputs);
+            if (!input)
                 return undefined;
-            const profile = configStore.getActiveProfileName() ?? "default";
-            const botIdentity = Journal.createTelegramUpdateJournalBotIdentity({
-                botToken,
-                botId: getTelegramBotId(),
-            });
             return withTelegramJournalSourceSerialization(function () {
-                return Journal.isTelegramThreadCleanupJournalNamespaceClear({
-                    directory: Paths.resolveTelegramTempDir(),
-                    profile,
-                    botIdentity,
-                    pollingPath: telegramLeaderJournalPath.resolve(configStore.getActiveProfileName()),
-                    requiredJournalBindingKeys: [
-                        binding.recoveryKey,
-                        ...requiredJournalBindingKeys,
-                    ],
-                    ...(target.threadId !== undefined && ownInputs
-                        ? {
-                            cleanup: {
-                                target: { chatId: target.chatId, threadId: target.threadId },
-                                ownInputs,
-                            },
-                        }
-                        : {}),
-                    limits: {
-                        maxDirectoryEntries: 10_000,
-                        maxFiles: 4096,
-                        maxBytes: 64 * 1024 * 1024,
-                        maxEntries: 10_000,
-                        maxWork: 100_000,
-                    },
-                    withSourceReference(path, operation) {
-                        return telegramJournalReferenceRegistry.withReference({
-                            referenceClass: "operator-disposition",
-                            recoveryKey: Journal.createTelegramUpdateJournalBindingKey({
-                                path,
-                                profileName: profile,
-                                botIdentity,
-                            }),
-                        }, operation);
-                    },
-                })
-                    ? []
-                    : undefined;
+                return Journal.isTelegramThreadCleanupJournalNamespaceClear(input) ? [] : undefined;
+            });
+        },
+        recoverTemporaryThreadDeadQueueOwners(target, requiredJournalBindingKeys, ownInputs, isCurrent) {
+            const input = prepareTemporaryThreadJournalInspection(target, requiredJournalBindingKeys, ownInputs);
+            if (!input || !isCurrent())
+                return 0;
+            return Journal.recoverTelegramThreadCleanupDeadQueueOwners({
+                ...input, isCurrent, withSourceSerialization: withTelegramJournalSourceSerialization,
+                recoveryOwner: {
+                    instanceId: telegramInstanceId, processId: telegramProcessId,
+                    processBirthId: telegramQueueProcessBirthId,
+                    sessionGeneration: telegramSessionContextStore.getGeneration(),
+                },
             });
         },
         hasWorkspaceRestoreAuthority() {
@@ -2485,6 +2479,7 @@ export default function (pi) {
         deleteMessage: deleteTelegramMessage,
         sendGuestReply,
         editGuestReply,
+        editGuestInlineMessage: telegramApiRuntime.editGuestInlineMessage,
         stopGuestPlaceholder: guestPlaceholderRuntime.stop,
         finalizeMarkdownPreview,
         preparePreviewDelivery,

package/node_modules/@llblab/pi-telegram/dist/lib/journal.d.ts

@@ -751,6 +751,13 @@ export declare function isTelegramThreadCleanupJournalNamespaceClear(input: Tele
         }[];
     };
 }): boolean;
+/** Demand-driven recovery only; caller holds temporary-cleanup admission. Never a deletion grant. */
+export declare function recoverTelegramThreadCleanupDeadQueueOwners(input: Parameters<typeof isTelegramThreadCleanupJournalNamespaceClear>[0] & {
+    recoveryOwner: TelegramUpdateJournalQueueOwnerIdentity;
+    isCurrent: () => boolean;
+    withSourceSerialization: NonNullable<TelegramUpdateJournalStoreOptions["withSourceSerialization"]>;
+    getQueueProcessLiveness?: TelegramUpdateJournalStoreOptions["getQueueProcessLiveness"];
+}): number;
 export declare function publishTelegramUpdateJournalSegment(path: string, segment: TelegramUpdateJournalSegment): TelegramUpdateJournalSegmentPublicationResult;
 export declare function createTelegramUpdateQueueHandoffToken(): string;
 export declare function createTelegramUpdateJournalBotIdentity(input: {

package/node_modules/@llblab/pi-telegram/dist/lib/journal.js

@@ -1988,6 +1988,86 @@ export function isTelegramThreadCleanupJournalNamespaceClear(input) {
     return namespace.sources.every((source) => source.evidence.kind === "absent" ||
         source.evidence.file.entries.every((entry) => isUnrelatedPlainInput(entry, source.path)));
 }
+/** Demand-driven recovery only; caller holds temporary-cleanup admission. Never a deletion grant. */
+export function recoverTelegramThreadCleanupDeadQueueOwners(input) {
+    return input.withSourceSerialization(() => {
+        const assertCurrent = () => {
+            if (!input.isCurrent())
+                throw new Error("Temporary cleanup queue recovery lost authority.");
+        };
+        assertCurrent();
+        if (!input.cleanup)
+            return 0;
+        // Validate exact references and complete namespace coverage before considering any mutation.
+        if (isTelegramThreadCleanupJournalNamespaceClear(input))
+            return 0;
+        const namespace = inspectTelegramSessionJournalNamespace(input);
+        if (namespace.retainedInputs?.some(value => value.state !== "committed") ||
+            input.requiredJournalBindingKeys.some(key => !namespace.sources.some(source => source.path === getTelegramUpdateJournalBindingPath(key) && source.evidence.kind === "present")))
+            return 0;
+        const plans = [];
+        for (const source of namespace.sources) {
+            if (source.evidence.kind !== "present")
+                continue;
+            const file = source.evidence.file;
+            if (file.version !== TELEGRAM_UPDATE_JOURNAL_VERSION)
+                continue;
+            const groups = new Map();
+            for (const entry of file.entries) {
+                if (!entry.queueReceiptId)
+                    continue;
+                const group = groups.get(entry.queueReceiptId) ?? [];
+                group.push(entry);
+                groups.set(entry.queueReceiptId, group);
+            }
+            for (const group of groups.values()) {
+                const entry = group[0];
+                if (entry.state !== "queued" || !entry.queueReceiptId || !entry.queueOwner ||
+                    !entry.queueKind || entry.queueHandoff || entry.inputClaim)
+                    continue;
+                if (group.some(value => value.state !== "queued" || value.queueHandoff || value.inputClaim ||
+                    value.queueKind !== entry.queueKind || !isDeepStrictEqual(value.queueOwner, entry.queueOwner)))
+                    continue;
+                plans.push({ path: source.path, recovery: {
+                        queueKind: entry.queueKind, receiptId: entry.queueReceiptId,
+                        sourceUpdateIds: group.map(value => value.updateId).sort((a, b) => a - b),
+                        deadOwner: cloneJournalQueueOwner(entry.queueOwner), recoveryOwner: { ...input.recoveryOwner },
+                    } });
+            }
+        }
+        const liveness = input.getQueueProcessLiveness ?? getTelegramProcessLiveness;
+        const dead = plans.filter(plan => {
+            assertCurrent();
+            const result = liveness(plan.recovery.deadOwner);
+            assertCurrent();
+            return result === "dead";
+        });
+        let removed = 0;
+        for (const plan of dead) {
+            assertCurrent();
+            removed += input.withSourceReference(plan.path, () => {
+                const journal = createTelegramUpdateJournalStore({
+                    path: plan.path, profileName: input.profile, botIdentity: input.botIdentity,
+                    queueRuntimeIdentity: input.recoveryOwner,
+                    // This private synchronous store stays inside the cross-family serializer already held above.
+                    withSourceSerialization(operation) { assertCurrent(); return operation(); },
+                    sourceAccess: { directory: dirname(plan.path), limits: input.limits },
+                    getQueueProcessLiveness(owner) {
+                        assertCurrent();
+                        const result = liveness(owner);
+                        assertCurrent();
+                        return result;
+                    },
+                    withWriterAdmission(operation) { assertCurrent(); return operation(); },
+                });
+                // The journal transaction rechecks whole-group identity, absence of handoff and fresh process-death proof.
+                return journal.recoverDeadQueueOwner(plan.recovery).recoveredUpdateIds.length;
+            });
+        }
+        assertCurrent();
+        return removed;
+    });
+}
 function cloneEntry(entry) {
     return {
         ...entry,

package/node_modules/@llblab/pi-telegram/dist/lib/outbound-attachments.d.ts

@@ -73,6 +73,7 @@ export interface TelegramQueuedOutboundAttachmentView {
 export interface TelegramOutboundAttachmentQueueTargetView {
     queuedAttachments: TelegramQueuedOutboundAttachmentView[];
     guestQueryId?: string;
+    guestInlineMessageId?: string;
 }
 export interface TelegramQueuedOutboundAttachmentTurnView extends TelegramOutboundAttachmentQueueTargetView {
     chatId: number;
@@ -161,6 +162,17 @@ export declare function queueTelegramOutboundAttachments(options: {
 }): Promise<TelegramOutboundAttachmentToolResult>;
 export declare function deliverTelegramGuestCachedAttachment(options: {
     guestQueryId: string;
+    guestInlineMessageId?: string;
+    editGuestInlineMessage?: (inlineMessageId: string, content: {
+        media: {
+            type: "photo" | "document" | "audio";
+            media: string;
+            caption?: string;
+        };
+    }, options: {
+        assertAuthority: () => void;
+    }) => Promise<void>;
+    isDeliveryActive?: () => boolean;
     stagingChatId: number;
     stagingTarget?: TelegramTarget;
     attachment: TelegramQueuedOutboundAttachmentView;

package/node_modules/@llblab/pi-telegram/dist/lib/outbound-attachments.js

@@ -375,6 +375,9 @@ export async function queueTelegramOutboundAttachments(options) {
         maxAttachmentSizeBytes: options.maxAttachmentSizeBytes,
         statPath: options.statPath,
     });
+    if (options.activeTurn.guestInlineMessageId && pendingAttachments.some((attachment) => getTelegramGuestAttachmentTransport(attachment.path).fileField === "voice")) {
+        throw new Error("Telegram Guest Mode cannot replace an inline placeholder with a voice note; no attachment was queued. Use MP3 audio or a normal bot chat.");
+    }
     options.activeTurn.queuedAttachments.push(...pendingAttachments);
     const added = pendingAttachments.map((attachment) => attachment.path);
     return {
@@ -389,6 +392,16 @@ export async function queueTelegramOutboundAttachments(options) {
 }
 export async function deliverTelegramGuestCachedAttachment(options) {
     const transport = getTelegramGuestAttachmentTransport(options.attachment.path);
+    const isActive = () => options.isDeliveryActive?.() !== false;
+    const assertActive = () => {
+        if (!isActive())
+            throw new Error("Guest attachment delivery lost authority.");
+    };
+    if (!isActive())
+        return;
+    if (options.guestInlineMessageId && (!options.editGuestInlineMessage || transport.fileField === "voice")) {
+        throw new Error("Guest inline attachment editing is unavailable for this media.");
+    }
     let stagingMessageId;
     let answerAttempted = false;
     try {
@@ -397,6 +410,8 @@ export async function deliverTelegramGuestCachedAttachment(options) {
             ...getTelegramMultipartTargetFields(options.stagingTarget),
         }, transport.fileField, options.attachment.path, options.attachment.fileName));
         stagingMessageId = message.message_id;
+        if (!isActive())
+            return;
         const caption = options.caption
             ? Array.from(options.caption).slice(0, 1024).join("")
             : undefined;
@@ -446,11 +461,26 @@ export async function deliverTelegramGuestCachedAttachment(options) {
                 ...(caption ? { caption } : {}),
             };
         }
+        if (!isActive())
+            return;
         answerAttempted = true;
-        await options.answerGuestQuery(options.guestQueryId, result);
+        if (options.guestInlineMessageId && options.editGuestInlineMessage) {
+            if (result.type === "voice")
+                throw new Error("Voice notes cannot replace inline placeholders.");
+            const media = result.type === "photo" ? result.photo_file_id
+                : result.type === "audio" ? result.audio_file_id : result.document_file_id;
+            await options.editGuestInlineMessage(options.guestInlineMessageId, {
+                media: { type: result.type, media, ...(caption ? { caption } : {}) },
+            }, { assertAuthority: assertActive });
+        }
+        else {
+            await options.answerGuestQuery(options.guestQueryId, result);
+        }
     }
     catch (error) {
-        if (!answerAttempted && options.answerGuestText && options.fallbackText) {
+        if (!isActive())
+            return;
+        if (!options.guestInlineMessageId && !answerAttempted && options.answerGuestText && options.fallbackText) {
             answerAttempted = true;
             await options.answerGuestText(options.guestQueryId, options.fallbackText);
         }
@@ -459,7 +489,7 @@ export async function deliverTelegramGuestCachedAttachment(options) {
         }
     }
     finally {
-        if (stagingMessageId !== undefined) {
+        if (stagingMessageId !== undefined && isActive()) {
             try {
                 await options.deleteMessage(options.stagingChatId, stagingMessageId);
             }

package/node_modules/@llblab/pi-telegram/dist/lib/queue.d.ts

@@ -506,10 +506,14 @@ export interface TelegramAgentEndRuntimeDeps<TTurn extends PendingTelegramTurn,
     }) => Promise<void>;
     sendGuestReply?: (guestQueryId: string, markdown: string) => Promise<void>;
     /** Replaces the early guest ACK with the final text. */
-    editGuestReply?: (inlineMessageId: string, markdown: string) => Promise<void>;
+    editGuestReply?: (inlineMessageId: string, markdown: string, options?: {
+        assertAuthority?: () => void;
+    }) => Promise<void>;
     /** Cancels the animated guest placeholder before the final edit. */
     stopGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
-    sendGuestAttachment?: (turn: TTurn, attachment: QueuedAttachment, caption?: string) => Promise<void>;
+    sendGuestAttachment?: (turn: TTurn, attachment: QueuedAttachment, caption?: string, options?: {
+        isDeliveryActive?: () => boolean;
+    }) => Promise<void>;
     sendGuestVoiceReply?: (turn: TTurn, plan: TelegramAgentEndOutboundReplyPlan<TReplyMarkup>, caption?: string) => Promise<void>;
     planOutboundReply?: (markdown: string) => TelegramAgentEndOutboundReplyPlan<TReplyMarkup>;
     sendOutboundReplyArtifacts?: (turn: TTurn, plan: TelegramAgentEndOutboundReplyPlan, options?: {