@llblab/pi-telegram 0.22.0 → 0.23.0

package/docs/multi-instance-bus.md

@@ -153,9 +153,9 @@ Leader election is heartbeat-gated and lock-backed:
 2. If no leader exists, acquire leadership and start polling.
 3. If a live leader exists, register as follower.
 4. If the leader heartbeat is stale, attempt an atomic leadership takeover; ordinary `/telegram-connect` on a follower is not a leadership move while the leader is live.
-5. If several followers detect stale leadership, atomic compare/write lock acquisition ensures only one becomes leader.
+5. Heartbeat acknowledgements carry the authenticated live follower-slot roster. If several followers detect stale leadership, the lowest observed live slot attempts promotion immediately; higher slots defer one bounded election grace and re-check the lock. Atomic compare/write acquisition remains the final ownership authority, and a missing lower-slot follower cannot block a higher survivor beyond that grace.
 
-Followers first try to re-register after leader reload or unknown-heartbeat responses, carrying their last known target, slot, and thread name so the new leader can reuse the same binding. After the grace window they promote only when the exact observed leader lease has become stale or inactive; an unavailable IPC endpoint never authorizes replacing a still-live owner. If the exact live target is absent from persisted bindings, the leader recovers it instead of creating another Telegram thread and keeps its carried slot only when that slot is free. Every successful reuse refreshes the binding timestamp. The leader does not restore persisted followers into the live registry speculatively: after a bounded re-registration grace window it removes older follower records that still lack a live bus owner from current `state.json`, while preserving a recently refreshed binding across the brief registry gap caused by follower session replacement and never deleting Telegram tabs. This preserves real thread bindings through transient reload gaps without allowing historical records or competing pollers to masquerade as live state.
+Followers first try to re-register after leader reload or unknown-heartbeat responses, carrying their last known target, slot, and thread name so the new leader can reuse the same binding. After the grace window they promote only when the exact observed leader lease has become stale or inactive; an unavailable IPC endpoint never authorizes replacing a still-live owner. If the exact carried target is absent from persisted bindings, the leader first runs the same synchronous visibility probe: success recovers it instead of creating another Telegram thread, explicit stale evidence provisions a replacement, and ambiguous failure rejects registration. An ambiguous absent-target probe persists only non-routable `probe-required` restoration evidence, so targetless retries and leader reloads must probe that exact target again instead of activating it or provisioning a speculative replacement. A carried slot survives only when that slot remains free. Every successful reuse refreshes the binding timestamp. The leader never restores persisted followers into the live registry speculatively. Absent follower records remain durable restart hints until explicit stale, deleted, offline, or reconciliation evidence invalidates them; only fresh authenticated registration creates live routing authority. This preserves real thread bindings through reload and process-absence gaps without allowing historical records or competing pollers to masquerade as live state.
 
 ## Leader/Follower Communication
 
@@ -189,7 +189,7 @@ Manual smoke checklist:
 3. Start Pi in a second Windows terminal and run `/telegram-connect`; verify it registers as follower rather than offering takeover, creates/uses its assigned thread, terminal status shows `<ThreadName> Follower` while idle, and a follower prompt flips it to `<ThreadName> Active` while work is running.
 4. From the follower thread, send a prompt that requests inline buttons; tap a button and verify the follow-up prompt queues in the follower instance.
 5. From the follower thread, request a voice reply and/or attachment; verify upload routes through the leader transport into the follower thread.
-6. Close the follower terminal; verify heartbeat pruning, disconnected notice, and cleanup behavior match Unix-like behavior.
+6. Close the follower terminal without an explicit disconnect; verify heartbeat pruning remains silent and preserves the follower tab/binding for recovery, matching Unix-like behavior. Then reconnect and run `/telegram-disconnect`; verify the leader confirms deletion of that follower's current tab before local polling stops.
 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._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.
@@ -215,7 +215,7 @@ In Telegram private-chat Threaded Mode:
 - `All` is an aggregate view, not a process launcher. Explicit new instances use live Pi follower registration: the operator starts Pi in a terminal and runs `/telegram-connect`; owner-created empty threads are observed but not treated as a Pi instance until the user chooses a route or restore action.
 - The leader proactively creates or reclaims its own thread on startup/activation when Threaded Mode is available, so the visible leader has the same two-way binding as followers.
 - **Unbound thread detection**: when the owner writes in an unknown `message_thread_id`, the bridge checks effective Threaded Mode state. If the current leader has no active bound thread, that new thread is reclaimed for the leader and the prompt is served locally. Otherwise the bridge preserves the prompt in that Telegram thread and shows a target-thread chooser; explicit routing may later close/delete only extra confirmed source threads through `thread-reconciler`.
-- Unknown later threads and threadless prompt messages are not silently routed to the leader and never launch hidden Pi processes. The default and only operator path for a new visible instance is starting a visible second Pi process and letting it register as follower through `/telegram-connect`. Manual follower registration creates a fresh visible thread unless the same explicit binding identity already has a live binding; old offline/failed records may point at closed/deleted Telegram tabs and are not silently claimed.
+- Unknown later threads and threadless prompt messages are not silently routed to the leader and never launch hidden Pi processes. The default and only operator path for a new visible instance is starting a visible second Pi process and letting it register as follower through `/telegram-connect`. A manual follower with the same stable binding identity reclaims its current persisted thread across process restart; only an authenticated live registration becomes routing authority. Explicit stale/deleted observations invalidate that restoration hint before a fresh thread is provisioned.
 - Thread lifecycle service messages (`forum_topic_created`, `forum_topic_closed`, `forum_topic_reopened`, deletion/stale send errors) update observations and binding state. Closed/deleted leader or follower threads can be reclaimed or recreated deliberately. Leader startup also probes reused own threads with a non-visible chat action; if Telegram reports the thread closed/deleted, the binding is marked stale and a fresh leader thread is created. Unknown `forum_topic_created` service events are observation-only and are not destructive cleanup proof.
 - Bidirectional binding is a core UX requirement, not an implementation detail: Pi instances actively advertise/remember their thread identity, while the bot observes Telegram-client thread state and reflects it back into instance state. This keeps the system responsive, recognizable, and controllable even when the operator closes tabs, writes from `All`, or a follower later becomes leader.
 
@@ -224,16 +224,16 @@ In Telegram private-chat Threaded Mode:
 - The private bot DM becomes the operator's multi-instance dashboard.
 - Each live bound instance gets one visible thread.
 - Each instance has a durable single-letter slot (`A`-`Z`) assigned by the extension and a bridge-authored `threadName`.
-- New slots advance through the alphabet and wrap after `Z` only to a free slot, intentionally capping concurrent visible instances to the alphabet without duplicating occupied letters. The compact `bot.lastSlot` cursor persists while its binding remains live/recovering, including true `Z → A` wraparound. When post-grace follower compaction removes the cursor's binding, that same reconciliation pass realigns it to the newest-created remaining live binding; pending provisions and reservations still block collisions. Other explicit thread deletion paths may preserve the cursor to continue ring sequence.
-- A follower that later becomes leader keeps its existing slot and thread name; leadership changes are transport role changes, not identity resets.
+- New slots advance through the alphabet and wrap after `Z` only to a free slot, intentionally capping concurrent visible instances to the alphabet without duplicating occupied letters. The compact `bot.lastSlot` cursor persists while its binding remains live or recoverable, including true `Z → A` wraparound. Pending provisions, reservations, and retained restart bindings occupy their slots until explicit stale/deleted evidence invalidates them.
+- A follower that later becomes leader keeps its existing slot and thread name; leadership changes are transport role changes, not identity resets. Immediately after follower promotion succeeds, the new leader retains a short-lived process-local handoff bound to its exact Telegram profile owner key and refreshes it before session replacement. The replacement session consumes it only after acquiring leader authority, converts any surviving manual-follower record for that target into the current leader binding, persists the target/slot/name, and only then runs ordinary topic provisioning; this handoff is restoration evidence, never live routing authority.
 - Instance-thread names are short and recognizable. Default provisioning chooses one baked 4-6 letter single-word Latin thread name from the assigned slot's five-name palette using provisioning timestamp entropy and creates the Telegram thread with that title immediately. The slot remains internal ordering metadata and is not redundantly included in the thread name. Bare slot titles are fallback/legacy state only; do not prompt agents to self-name and do not expose a rename tool. Existing human-named threads are preserved across reloads and leadership changes when they remain the current live binding. If reload creates a new runtime instance while the previous leader thread is still alive, the new leader should take the next free slot instead of reusing the old slot immediately.
 - A thread-local `/start` opens that instance's menu.
 - Prompts typed in a thread route to the owning instance.
 - Replies, previews, files, voice, and buttons stay in that thread.
 - Queue controls and reactions affect only that instance target.
 - Telegram's native `…typing` indicator for real agent work is sent to that instance thread and mirrored to `All`; `All` is the aggregate surface and should show activity when any bound instance is running a Telegram turn, local prompt, or autonomous continuation. Terminal `Active` remains Telegram-turn-specific. Startup/connect/reload/recovery must not send activity by themselves.
-- If the instance disconnects, the leader can post/update a compact status: `Instance offline`.
-- If the same live binding identity returns, it can reclaim the thread and post a compact reconnect status.
+- Generic heartbeat pruning remains silent and preserves the thread as a restart hint; it does not post an `Instance offline` notice.
+- If the same binding identity returns, authenticated registration can reclaim the thread after the required visibility proof.
 
 ## Bot API Evidence For Private-Chat Threaded Mode
 
@@ -252,7 +252,7 @@ Remaining live-verification points:
 
 - Whether callback query messages always carry `message_thread_id` in private bot threads, or whether generated button callbacks must rely on stored message id -> target ownership.
 - Whether message-reaction updates carry thread identity in the current Bot API shape. The reference exposes chat id and message id for reactions, so routing may need stored message ownership.
-- Whether every rich draft/final/upload/chat-action path behaves identically in Telegram clients when `message_thread_id` is supplied.
+- Live client evidence now covers the probe-confirmed single-artifact multipart Rich final through both direct leader and registered follower transport: an assigned follower Telegram turn produced one reply-anchored PNG plus final text without a duplicate upload or notice. Deterministic bus tests additionally cover target-scoped multipart authorization, envelope preservation, and replacement-generation fencing.
 
 Implemented behavior stays evidence-gated: when Telegram client or Bot API behavior differs from the contract above, capture a minimized fixture or documented client caveat before changing routing.
 
@@ -349,7 +349,7 @@ Current state under the agent dir:
 - `tmp/telegram/state.json`: volatile extension+bot observable/debug snapshot, not routing authority. It writes `source: "snapshot"` and `writtenAtMs` so consumers do not confuse it with an authoritative database. Every process on one Telegram profile reads this shared path, but only the active transport lock owner may persist it; followers become writers only after promotion. Status-only persistence refreshes disk-backed bindings before serialization so an already-loaded stale view cannot erase newer leader records. It mirrors `/telegram-status`-style projections: top-level `bot` stores bot-wide capability state such as `threadMode: "unknown" | "enabled" | "disabled"`, `runtime` identifies leader/follower role and process status, `liveRoster` mirrors followers/current targets/reservations, `diagnostics` mirrors status/debug signals, `threads` stores current routeable bindings, `bot.lastSlot` stores the compact slot cursor used when all current threads are gone, and `reservations` records short-lived slot collision guards.
 - Local bus endpoints: Unix-like platforms expose stable `tmp/telegram/bus.sock` and `tmp/telegram/followers/*` symlinks backed by private generation sockets; native Windows uses deterministic named pipes under `\\.\pipe\pi-telegram-...`. These are transient IPC endpoints, not durable routing state.
 
-The bridge must not keep a durable `telegram-targets.json` history. Stale/offline/failed thread entries are reconciliation observations, not reusable source-of-truth state; persisting them increases collision risk. `sync` is event-driven assumption reconciliation, not full Telegram bot-state mirroring, because Bot API does not expose a complete topic/thread listing surface. `state.json` therefore exists for extension+bot observability, diagnostics, startup hints, and explaining reconciliation decisions; live bus/runtime state remains authoritative for routing and provisioning. Non-current routeable thread bindings are pruned during load/persist; old session records must not be retained just to compute the next slot because `bot.lastSlot` is the only durable cursor. Previous-process leader bindings are treated as occupied TTL-bounded reservations until Telegram confirms deletion: reload/startup may close/delete/probe the old thread, known reservations are retried proactively on leader startup, and if Telegram still accepts the old thread id, the new leader should provision the next free slot (`B`, `C`, …) rather than creating a duplicate same-letter tab or blocking startup on Telegram UI convergence. Routing must use live current threads/follower registry, never reservations. The bus leader provisions its own thread during bus startup/connect and provisions follower threads on `follower.register`; registered followers also live in the leader's in-memory registry and communicate over the local bus socket. The live follower registry can resolve a follower by exact `{ chatId, threadId? }`; the leader uses that target ownership to forward message and edited-message updates to followers, and the follower receiver accepts those updates in addition to callbacks and reactions. Terminal status and `[telegram|thread:name]` resolve the matching current-instance identity through the same target-aware path, preferring registered local metadata over stale shared bindings. Media album grouping and split-text coalescing keys include the thread target, queue reaction mutations can scope by chat/thread to avoid cross-target message-id collisions, active-turn target is exposed for lifecycle cleanup and local direct-tool defaults, transport reply dedup is chat/thread-scoped, stored menu state is keyed by chat/message so callback state lookup cannot collide across chats, and generated button turns plus section prompt/open actions preserve the callback thread target. `telegram_message` and immediate `telegram_attach` delivery can also carry an explicit `thread_id` with `chat_id`; when a follower is registered, their default direct-tool target is the assigned thread target and the bus-aware API runtime routes the send through the leader instead of calling Bot API transport locally.
+The bridge must not keep a separate durable `telegram-targets.json` history. `state.json` retains current stable manual-follower bindings as restart hints, but they never authorize routing without a matching authenticated live registration. Stale/offline/failed observations are not reusable delivery authority. `sync` remains event-driven assumption reconciliation rather than a full Telegram bot-state mirror because Bot API exposes no complete thread listing surface. Non-current routeable thread bindings are pruned during load/persist; old session records must not be retained just to compute the next slot because `bot.lastSlot` is the only durable cursor. Previous-process leader bindings are treated as occupied TTL-bounded reservations until Telegram confirms deletion: reload/startup may close/delete/probe the old thread, known reservations are retried proactively on leader startup, and if Telegram still accepts the old thread id, the new leader should provision the next free slot (`B`, `C`, …) rather than creating a duplicate same-letter tab or blocking startup on Telegram UI convergence. Routing must use live current threads/follower registry, never reservations. The bus leader provisions its own thread during bus startup/connect and provisions follower threads on `follower.register`; registered followers also live in the leader's in-memory registry and communicate over the local bus socket. The live follower registry can resolve a follower by exact `{ chatId, threadId? }`; the leader uses that target ownership to forward message and edited-message updates to followers, and the follower receiver accepts those updates in addition to callbacks and reactions. Terminal status and `[telegram|thread:name]` resolve the matching current-instance identity through the same target-aware path, preferring registered local metadata over stale shared bindings. Media album grouping and split-text coalescing keys include the thread target, queue reaction mutations can scope by chat/thread to avoid cross-target message-id collisions, active-turn target is exposed for lifecycle cleanup and local direct-tool defaults, transport reply dedup is chat/thread-scoped, stored menu state is keyed by chat/message so callback state lookup cannot collide across chats, and generated button turns plus section prompt/open actions preserve the callback thread target. `telegram_message` and immediate `telegram_attach` delivery can also carry an explicit `thread_id` with `chat_id`; when a follower is registered, their default direct-tool target is the assigned thread target and the bus-aware API runtime routes the send through the leader instead of calling Bot API transport locally.
 
 All files containing routing, chat ids, thread ids, or process details use private permissions and represent current state rather than historical target caches.
 
@@ -373,11 +373,12 @@ All files containing routing, chat ids, thread ids, or process details use priva
 - Leader prunes the follower from the live registry after missed heartbeats, but heartbeat pruning is only immediate liveness bookkeeping.
 - A missed heartbeat does not delete, close, mark offline, or send a disconnected notice for the follower's Telegram thread binding because the common cause may be leader reload, IPC handoff, or transient reconnect rather than a dead follower.
 - Followers treat rejected/missing heartbeat acknowledgements as registration loss: retain the last known target locally, clear registered truth, try to re-register with the current leader, wait a short leader-reload grace window, and retry. They promote only after the exact leader lease becomes stale or inactive; a live owner with an unreachable endpoint leaves the follower disconnected/retrying rather than creating a competing poller.
-- After leader reload grace expires, persisted manual-follower records without a matching live registry owner leave current `state.json`; this compaction is non-destructive and does not close/delete the Telegram thread.
-- Every successful follower registration/re-registration sends a compact connected notice in the assigned thread so recovery and reconnection are visible during live testing without confusing heartbeat suspicion with real disconnect.
+- Persisted current manual-follower bindings survive process absence as restoration hints, but cannot receive inbound or outbound work until the replacement follower authenticates and registers with a fresh generation.
+- Freshly provisioned follower registration sends a compact connected notice in the assigned thread. Cross-session restoration sends the same notice once as a visibility probe: success surfaces the reused tab, explicit stale-topic rejection provisions a monotonic replacement before registration succeeds, and ambiguous/non-stale failure records diagnostics and rejects registration without replay or speculative replacement.
+- Registration requires a present generation, and explicit disconnect requires that same exact live generation. Leader-side registration and disconnect mutations serialize per durable follower profile across old and replacement runtime instance IDs, so a replacement registration cannot overtake awaited destructive cleanup and an old disconnect cannot remove its successor's routing authority.
 - Successful forwarded updates and follower-originated API calls refresh liveness, so active followers are not pruned only because the interval heartbeat tick lagged.
-- Destructive follower thread teardown belongs to explicit `/telegram-disconnect` or confirmed reconciliation actions, not generic heartbeat pruning.
-- Historical offline thread entries are not retained as reusable source of truth.
+- Destructive follower thread teardown belongs to explicit `/telegram-disconnect` or confirmed reconciliation actions, not generic heartbeat pruning. A registered follower sends an authenticated request fenced by its exact registration generation; the active leader closes and deletes that follower's exact topic, marks its durable binding offline, removes live routing authority, and acknowledges completion before the follower stops. Cleanup counts as confirmed only after successful deletion or explicit already-gone evidence. Incomplete cleanup preserves the binding and registration for retry. A promoted leader uses its current owned leader epoch even when the inherited record still carries a historical `manual-follower` owner label.
+- Explicit stale/deleted/offline observations invalidate reuse; mere process absence does not.
 
 ### Thread is deleted
 
@@ -409,7 +410,7 @@ All files containing routing, chat ids, thread ids, or process details use priva
 - [x] Followers never call `getUpdates` for the shared bot token.
 - [x] Followers can send replies, previews, voice, attachments, menus, and chat actions through the leader transport.
 - [x] The leader can route inbound messages, edits, callbacks, reactions, media groups, and split text to the owning instance by target. Message/edit and callback/reaction routing is authorized by user id; media and split-text coalescing are target-keyed locally.
-- [x] Telegram UI thread targets can be provisioned as current state bindings; stale/deleted Telegram observations and explicit disconnect/reconciliation actions remove unusable bindings instead of persisting reusable history, while heartbeat-pruned followers preserve their thread binding so transient leader reload/reconnect gaps do not create split-brain Telegram UX.
+- [x] Telegram UI thread targets can be provisioned as current state bindings; stable manual-follower identities reclaim current bindings across process restart, authenticated registration generation gates routing, and stale/deleted observations or explicit disconnect/reconciliation remove unusable bindings.
 - [x] Leader failover promotes one remaining follower without creating competing pollers.
 - [x] Queue, active turn, preview, reply deduplication, menu, section, button, reaction, and attachment state are scoped by instance/target. Queue reaction mutations and transport reply dedup are chat/thread-scoped; active-turn target is available to lifecycle cleanup; stored menu state is chat/message-keyed; generated button turns and section prompt/open actions preserve callback targets; preview and attachment delivery already carry targets.
 - [x] Authorization prevents arbitrary Telegram users or local processes from controlling agents or receiving artifacts.
@@ -424,7 +425,7 @@ Live client and native Windows evidence gates are tracked in `BACKLOG.md`; this
 - The transport lock distinguishes live bus leadership from ordinary classic ownership through heartbeat, leader epoch, and stale takeover rules.
 - The leader records live follower registration, heartbeat, thread identity, slot, and target mapping; followers do not poll `getUpdates`.
 - Local IPC is the default internal bus. Registered followers receive normalized inbound updates and send allowlisted, target-scoped Bot API calls through the leader.
-- Thread targets are current-state bindings, not durable historical delivery addresses. Stale/offline/failed entries are reconciliation evidence only.
+- Thread targets are current-state bindings, not historical delivery addresses. Stable restart hints require a fresh authenticated follower registration before they become live routing authority; stale/offline/failed entries remain reconciliation evidence only.
 - Failover promotes a remaining follower after dead or clean-disconnected leaders without creating competing pollers; follower heartbeat recovery owns re-register → grace → promotion while preserving thread bindings across transient leader reload gaps.
 - Thread cleanup is centralized in `thread-reconciler`, fails closed without a leader epoch while leadership exists, revalidates that epoch immediately before every close/delete call and local cleanup-state mutation, and requires confirmed delete/stale evidence before state is marked deleted.
 - Stable docs/UI now describe classic mode, opt-in Threaded Mode, manual follower registration, status/diagnostics, unbound-thread reroute/restore UX, and operator recovery boundaries.

package/docs/outbound.md

@@ -6,6 +6,12 @@ Normal Telegram-turn replies are intentionally prompt-driven: the agent writes M
 
 Text handlers use the portable [Command Template Standard](./command-templates.md). Programmatic outbound handlers use `registerTelegramOutboundHandler(kind, handler)`. Voice replies can use configured command-template handlers or the provider API described in [Voice Integration](./voice.md).
 
+## Proactive Public Output
+
+Proactive projection defaults on. With `assistant.proactivePush` omitted or set to `true`, completed public assistant text blocks from local or autonomous Pi work are projected to the instance's authorized Telegram target; set it explicitly to `false` to opt out. A visible intermediate commentary/checkpoint and the final answer become separate Telegram messages in source order; this is not a final-only `agent_end` notification. The bridge consumes normalized Activity `assistant-segment` events, not raw token deltas, reasoning, or tool traffic.
+
+Proactive blocks use `assistant.rendering` independently of voice policy. Rich mode sends native Rich Markdown and HTML mode keeps the established HTML renderer; proactive projection does not synthesize voice or attach queued files merely because Rich rendering is active. The queue revalidates exact target, profile/token transport generation, leader epoch or follower registration generation, and session generation before each send. Telegram-owned turns remain on their ordinary reply path, and `commit-unknown` never permits proactive replay.
+
 ## Standard
 
 An outbound handler is selected by `type`. Text replies and assistant markup map to handler types:
@@ -18,6 +24,16 @@ 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.
 
+### Single Rich attachment result
+
+When `assistant.rendering` is `"rich"`, a Telegram-originated turn that queues exactly one probe-confirmed PNG/JPEG photo, MP4 video, or MP3 audio file through `telegram_attach` can combine that artifact with the final assistant Markdown in one multipart `sendRichMessage` result. The bridge normalizes the Markdown, adds one `tg://photo`, `tg://video`, or `tg://audio` reference, preserves the triggering-message reply anchor and assigned thread, carries assistant-authored inline buttons, and records the returned message id under the exact local/follower ownership scope.
+
+The optimization is deliberately narrow. HTML rendering, empty final text, multiple files, documents and other unsupported formats, Guest Mode, explicit `telegram_voice`, voice-preferred turns, and OGG/Opus artifacts retain their established text/attachment/voice paths. A known-safe Rich upload rejection falls back to those paths. A `commit-unknown` transport outcome or a nominally successful upload without a verifiable message id never falls back or replays because the first non-idempotent send may already have committed.
+
+This behavior does not generate media or alter voice policy. `telegram_attach` still represents an explicit assistant artifact decision, while `manual`, `mirror`, and `always` continue to decide voice synthesis independently.
+
+Core assistant output accepts only the Markdown or HTML `InputRichMessage` forms and does not construct explicit block arrays or `InputRichBlockThinking`. Telegram's Thinking block is draft-only and must never become a projection of hidden reasoning or chain-of-thought. Any future use for Activity would require an explicitly public user-visible summary rather than provider reasoning content.
+
 ### 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.

package/docs/public-api.md

@@ -41,7 +41,7 @@ Stable commands inside Pi:
 
 - `/telegram-setup` — configure/update the bot token.
 - `/telegram-connect` — start polling here and acquire external Telegram control ownership. Accepted queue/reply state stays local if ownership later moves elsewhere.
-- `/telegram-disconnect` — stop polling and release ownership without deleting or silencing accepted local queue state.
+- `/telegram-disconnect` — stop polling and release ownership without deleting or silencing accepted local queue state. In Threaded Mode it first asks for confirmation, then deletes this instance's current Telegram thread; a follower waits for its active leader to confirm generation-fenced cleanup before stopping.
 - `/telegram-status` — show connection, polling, execution, queue, and recent event diagnostics.
 
 ### Telegram commands
@@ -61,7 +61,7 @@ This command surface is a mobile companion subset, not a raw terminal-command br
 
 ### Tools and assistant-authored actions
 
-- `telegram_attach(paths, chat_id?, thread_id?, caption?)` is the stable artifact delivery tool for generated files. During Telegram turns it queues files for the active reply; outside Telegram turns it sends files directly to the paired/default chat, the registered follower's assigned thread, or an explicit `chat_id` plus optional `thread_id` when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus.
+- `telegram_attach(paths, chat_id?, thread_id?, caption?)` is the stable artifact delivery tool for generated files. During Telegram turns it queues files for the active reply; with `assistant.rendering: "rich"`, exactly one PNG/JPEG, MP4, or MP3 artifact plus non-empty final Markdown can become one reply-anchored Rich Message. HTML mode, multiple/unsupported files, Guest Mode, and voice outputs retain their established paths. Outside Telegram turns the tool sends files directly to the paired/default chat, the registered follower's assigned thread, or an explicit `chat_id` plus optional `thread_id` when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus.
 - `telegram_message(text, chat_id?, thread_id?)` sends a direct Telegram Markdown message from local/TUI-initiated work when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus. Top-level `telegram_button` comments inside `text` are parsed with the same planner used for normal replies and attached to that message; buttons are never standalone Telegram messages.
 - `telegram_help()` returns detailed agent-facing guidance for pi-telegram delivery actions, Threaded Mode, formatting, and debugging. The regular prompt only points agents at this tool instead of repeating the full guidance on every turn.
 - `telegram_voice` hidden comments request Telegram-native voice delivery.
@@ -84,10 +84,14 @@ interface TelegramConfig {
   botId?: number; // runtime-managed
   allowedUserId?: number;
   lastUpdateId?: number; // runtime-managed
-  proactivePush?: boolean;
   inboundHandlers?: TelegramInboundHandlerConfig[];
   attachmentHandlers?: TelegramInboundHandlerConfig[]; // compatibility alias
   outboundHandlers?: TelegramOutboundHandlerConfig[];
+  assistant?: {
+    draftPreviews?: boolean;
+    rendering?: "rich" | "html";
+    proactivePush?: boolean;
+  };
   voice?: {
     replyMode?: "manual" | "mirror" | "always";
     sendTranscript?: boolean;
@@ -101,11 +105,12 @@ interface TelegramConfig {
 
 Hidden/default semantics are represented by absence:
 
+- `assistant.proactivePush` defaults to `true`; omit it to keep projection enabled, or set it explicitly to `false` to disable it. When enabled, each completed public assistant text block from local or autonomous work is projected to the authorized Telegram target once and in source order. This includes visible intermediate commentary/checkpoints and the final block. It excludes token deltas, hidden reasoning, tool calls/arguments/results, Telegram-owned turns, empty blocks, and stale authority. Projection uses the configured Rich or HTML assistant renderer and binds admitted work to the exact target, profile/token transport generation, direct leader epoch or follower registration generation, and session generation. The old top-level `proactivePush` key is ignored; move the setting manually under `assistant`.
 - Voice Reply `hidden`: no `voice.replyMode` key is persisted.
 - Agent activity status is not configurable in this release. Telegram uses native `sendChatAction(typing)` / product `...active` status as the only automatic in-chat work signal before the final reply.
 - Time Injection `hidden`: no `time.injectionMode` key is persisted; if `time` becomes empty, the whole `time` object may be omitted.
 
-Assistant Markdown delivery is native: final replies are sent as `InputRichMessage.markdown` via `sendRichMessage`, and draft previews use `sendRichMessageDraft` when a structurally closed preview frame is available. Draft-frame failures are recorded and skipped rather than converted into raw plain preview messages, because partial Markdown can be temporarily invalid while the final answer remains valid. Long native replies are split at Telegram Rich Message transport limits, with oversized fenced code, display-math, and fully wrapped inline-formatting blocks rewrapped per chunk so persisted chunks remain structurally valid. Guest replies use `InputRichMessageContent` in `answerGuestQuery` results. Bridge-owned UI surfaces such as menus, status, queue controls, commands, and sections keep explicit Telegram HTML/plain rendering by default because those texts are authored by the bridge or companion extensions for Telegram UI. Companion extension sections may explicitly request `"markdown"`, `"html"`, or `"plain"` per view. There is no `telegram.json` rendering toggle for assistant delivery. The bridge sets `skip_entity_detection: true` for assistant and guest Markdown so technical text such as `/commands`, hashtags, URLs, phone numbers, and card-like numbers does not gain unintended automatic entities; explicit Markdown links still belong in the Markdown source.
+With `assistant.rendering: "rich"` (the default), assistant Markdown delivery is native: final replies are sent as `InputRichMessage.markdown` via `sendRichMessage`, and draft previews use `sendRichMessageDraft` when a structurally closed preview frame is available. Draft-frame failures are recorded and skipped rather than converted into raw plain preview messages, because partial Markdown can be temporarily invalid while the final answer remains valid. Long native replies are split at Telegram Rich Message transport limits, with oversized fenced code, display-math, and fully wrapped inline-formatting blocks rewrapped per chunk so persisted chunks remain structurally valid. Guest replies use `InputRichMessageContent` in `answerGuestQuery` results. Bridge-owned UI surfaces such as menus, status, queue controls, commands, and sections keep explicit Telegram HTML/plain rendering by default because those texts are authored by the bridge or companion extensions for Telegram UI. Companion extension sections may explicitly request `"markdown"`, `"html"`, or `"plain"` per view. `assistant.rendering: "html"` keeps the compatibility path that converts assistant Markdown to Telegram HTML before ordinary message delivery. The bridge sets `skip_entity_detection: true` for assistant and guest Markdown so technical text such as `/commands`, hashtags, URLs, phone numbers, and card-like numbers does not gain unintended automatic entities; explicit Markdown links still belong in the Markdown source.
 
 Environment variables are stable only where documented in the README: bot-token bootstrap, proxy behavior, agent root, and inbound/outbound file size limits.
 

package/index.ts

@@ -220,14 +220,11 @@ export default function (pi: Pi.ExtensionAPI) {
       scheduleSnapshotPersist: runtimeDiagnostics.scheduleSnapshotPersist,
     });
   const recordThreadReconciliationPlan = threadReconciliationRuntime.recordPlan;
-  const markTelegramConfigSyncChange =
-    telegramSyncStateRuntime.markConfigChange;
-  const persistTelegramConfigWithSync = async function (
-    nextConfig?: Config.TelegramConfig,
-  ) {
-    await configStore.persist(nextConfig);
-    markTelegramConfigSyncChange("config-persist");
-  };
+  const persistTelegramConfigWithSync =
+    Sync.createTelegramConfigSyncPersister<Config.TelegramConfig>({
+      persist: configStore.persist,
+      markConfigChange: telegramSyncStateRuntime.markConfigChange,
+    });
   const currentInstanceThreadRuntime =
     Threads.createTelegramCurrentInstanceThreadRuntime({
       instanceId: telegramInstanceId,
@@ -271,7 +268,7 @@ export default function (pi: Pi.ExtensionAPI) {
       getFollowerTarget: telegramBusFollowerRegistrationState.getTarget,
       getFollowerSlot: telegramBusFollowerRegistrationState.getSlot,
       getFollowerThreadName: telegramBusFollowerRegistrationState.getThreadName,
-      getCurrentIdentity: getCurrentInstanceThreadIdentity,
+      getCurrentIdentity: currentInstanceThreadRuntime.getRestorationIdentity,
     });
   const statusRuntime = Status.createTelegramBridgeStatusRuntime<
     Pi.ExtensionContext,
@@ -347,6 +344,9 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       getRegistrationGeneration:
         telegramBusFollowerRegistrationState.getGeneration,
+      getForwardCommentBatchPosition:
+        textGroupRuntime.getPreparedForwardingPosition,
+      recordRuntimeEvent,
       timeoutMs: 30_000,
     });
   const telegramApiRuntime = BusApi.createTelegramBusAwareApiRuntime({
@@ -445,8 +445,45 @@ export default function (pi: Pi.ExtensionAPI) {
         });
       },
     });
+  const { sendTextReply, sendMarkdownReply } =
+    Outbound.createTelegramOutboundTextReplyRuntime({
+      sendTextReply: replyRuntime.sendTextReply,
+      sendMarkdownReply: replyRuntime.sendMarkdownReply,
+      execCommand: CommandTemplates.execCommandTemplate,
+      getHandlers: configStore.getOutboundHandlers,
+      recordRuntimeEvent,
+    });
+  const assistantOutputBindingRuntime =
+    Bindings.createTelegramAssistantOutputBindingRuntime({
+      isEnabled: configControls.isProactivePushEnabled,
+      authority: {
+        getPreferredTarget: proactivePushTargetGetter,
+        getFallbackChatId: proactivePushChatIdGetter,
+        getTransportStamp: telegramTransportStampRuntime.getStamp,
+        isTransportStampActive: telegramTransportStampRuntime.isActive,
+        ownsDirect: lockRuntime.owns,
+        getDirectEpoch: lockRuntime.getOwnedLeaderEpoch,
+        isFollowerRegistered:
+          telegramBusFollowerRegistrationState.isRegistered,
+        getFollowerGeneration:
+          telegramBusFollowerRegistrationState.getGeneration,
+      },
+      sender: {
+        recordOwnership: messageOwnershipRuntime.recordLocal,
+        sendMessage,
+        sendRichMessage,
+        editMessage: editTelegramMessageText,
+        getAssistantRenderingMode: configControls.getAssistantRenderingMode,
+        execCommand: CommandTemplates.execCommandTemplate,
+        getHandlers: configStore.getOutboundHandlers,
+        recordRuntimeEvent,
+      },
+      recordRuntimeEvent,
+    });
+  const assistantOutputRuntime = assistantOutputBindingRuntime.runtime;
   const activityRuntime = Activity.createTelegramActivityBridgeRuntime({
     generation: deliveryGenerationSeed,
+    observeEvent: assistantOutputBindingRuntime.observeEvent,
     recordFailure(handlerId, event, error) {
       recordRuntimeEvent("activity", error, {
         handlerId,
@@ -455,14 +492,6 @@ export default function (pi: Pi.ExtensionAPI) {
       });
     },
   });
-  const { sendTextReply, sendMarkdownReply } =
-    Outbound.createTelegramOutboundTextReplyRuntime({
-      sendTextReply: replyRuntime.sendTextReply,
-      sendMarkdownReply: replyRuntime.sendMarkdownReply,
-      execCommand: CommandTemplates.execCommandTemplate,
-      getHandlers: configStore.getOutboundHandlers,
-      recordRuntimeEvent,
-    });
   const dispatchNextQueuedTelegramTurn =
     Queue.createTelegramQueueDispatchRuntime({
       ...telegramQueueStore,
@@ -622,9 +651,7 @@ export default function (pi: Pi.ExtensionAPI) {
       callApi: callTelegramApi,
       isTopicProvisioningActive: telegramProvisioningActivity.isActive,
       getCurrentLeaderEpoch,
-      getThreadReconciliationMachineState() {
-        return threadReconciliationRuntime.getState();
-      },
+      getThreadReconciliationMachineState: threadReconciliationRuntime.getState,
       recordThreadReconciliationPlan,
       getSyncState: telegramSyncStateRuntime.getState,
       setSyncState: telegramSyncStateRuntime.setState,
@@ -650,9 +677,7 @@ export default function (pi: Pi.ExtensionAPI) {
     recordMessageOwnership: messageOwnershipRuntime.recordRouted,
     ...inboundBusProjectionRuntime,
     getCurrentLeaderEpoch,
-    getThreadReconciliationMachineState() {
-      return threadReconciliationRuntime.getState();
-    },
+    getThreadReconciliationMachineState: threadReconciliationRuntime.getState,
     recordThreadReconciliationPlan,
     handleTelegramTopicLifecycleUpdate: topicLifecycleSync,
     handleTelegramThreadTargetObserved(_target, ctx) {
@@ -744,13 +769,13 @@ export default function (pi: Pi.ExtensionAPI) {
       receiver: {
         socketPath: getTelegramBusFollowerSocketPath,
         instanceId: telegramInstanceId,
-        getContext() {
-          return telegramSessionContextStore.get();
-        },
+        getContext: telegramSessionContextStore.get,
         getAuthSecret() {
           return telegramActiveBusAuthSecret;
         },
         ...forwardedRouteHandlers,
+        prepareForwardedMessage:
+          textGroupRuntime.prepareForwardedMessage,
         recordRuntimeEvent,
       },
       targetReplacement: {
@@ -766,17 +791,13 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       recovery: {
         registrationState: telegramBusFollowerRegistrationState,
-        getLeaderState() {
-          return lockRuntime.getState();
-        },
+        getLeaderState: lockRuntime.getState,
         setLifecyclePhase(phase) {
           telegramBusLifecycleOverridePhase = phase;
         },
         updateStatus,
         promoteToLeader: promoteTelegramBusFollowerToLeader,
-        getActiveContext() {
-          return telegramSessionContextStore.get();
-        },
+        getActiveContext: telegramSessionContextStore.get,
         recordRuntimeEvent,
       },
       registration: {
@@ -784,9 +805,7 @@ export default function (pi: Pi.ExtensionAPI) {
         getFollowerBusSocketPath: getTelegramBusFollowerSocketPath,
         getLeaderSocketPath: getTelegramBusSocketPath,
         registrationState: telegramBusFollowerRegistrationState,
-        isContextActive(ctx) {
-          return telegramSessionContextStore.isCurrent(ctx);
-        },
+        isContextActive: telegramSessionContextStore.isCurrent,
         createRequestId: telegramBusFollowerClients.createRequestId,
         getLeaderAuthSecret(owner) {
           return owner.busSecret;
@@ -794,12 +813,7 @@ export default function (pi: Pi.ExtensionAPI) {
         setActiveAuthSecret(secret) {
           telegramActiveBusAuthSecret = secret;
         },
-        getThreadName() {
-          return undefined;
-        },
-        getProfileKey() {
-          return getTelegramManualFollowerProfileKey();
-        },
+        getProfileKey: getTelegramManualFollowerProfileKey,
         recordRuntimeEvent,
       },
     });
@@ -812,6 +826,7 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteWebhook,
     getUpdates,
     persistConfig: persistTelegramConfigWithSync,
+    prepareUpdateBatch: textGroupRuntime.prepareUpdateBatch,
     handleUpdate: Updates.createTelegramUpdateHandle({
       defaultHandle: inboundRouteRuntime.handleUpdate,
     }),
@@ -819,17 +834,13 @@ export default function (pi: Pi.ExtensionAPI) {
     updateStatus,
     recordRuntimeEvent,
   });
-  const recoverStaleTelegramTopicApiError = function (
-    apiBody: unknown,
-    error: unknown,
-  ) {
-    return Sync.recoverStaleTelegramTopicApiError(apiBody, error, {
+  const recoverStaleTelegramTopicApiError =
+    Sync.createTelegramStaleTopicApiErrorRecoveryRuntime({
       topicTargetStore: threadStore,
       getSyncState: telegramSyncStateRuntime.getState,
       setSyncState: telegramSyncStateRuntime.setState,
       recordEvent: recordRuntimeEvent,
     });
-  };
   const authorizeFollowerApiCall = Bus.createTelegramFollowerApiCallAuthorizer({
     isMessageOwned: messageOwnershipRuntime.isOwnedByFollower,
   });
@@ -851,9 +862,7 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       getAllowedUserId: configStore.getAllowedUserId,
       instanceId: telegramInstanceId,
-      getCwd(ctx) {
-        return typeof ctx.cwd === "string" ? ctx.cwd : undefined;
-      },
+      getCwd: Pi.getExtensionContextCwd,
       getTelegramProfile: getActiveTelegramThreadProfile,
       shouldForceFreshUnnamed:
         telegramThreadCapabilityState.shouldForceFreshLeaderThread,
@@ -865,9 +874,7 @@ export default function (pi: Pi.ExtensionAPI) {
       downloadFile: directTelegramApiRuntime.downloadFile,
       recoverStaleTargetError: recoverStaleTelegramTopicApiError,
       getCurrentLeaderEpoch,
-      getThreadReconciliationMachineState() {
-        return threadReconciliationRuntime.getState();
-      },
+      getThreadReconciliationMachineState: threadReconciliationRuntime.getState,
       recordThreadReconciliationPlan,
       getSyncState: telegramSyncStateRuntime.getState,
       setSyncState: telegramSyncStateRuntime.setState,
@@ -937,6 +944,8 @@ export default function (pi: Pi.ExtensionAPI) {
       getCurrentLeaderEpoch,
       getLeaderTarget: telegramBusLeaderState.getTarget,
       clearLeaderTarget: telegramBusLeaderState.clear,
+      disconnectFollowerThread:
+        telegramBusFollowerRegistration.disconnectFromLeader,
       getSyncState: telegramSyncStateRuntime.getState,
       setSyncState: telegramSyncStateRuntime.setState,
       stopPolling: lockedPollingRuntime.stop,
@@ -970,6 +979,10 @@ export default function (pi: Pi.ExtensionAPI) {
         registrationRuntime: telegramBusFollowerRegistration,
         instanceId: telegramInstanceId,
         suspendPolling: lockedPollingRuntime.suspend,
+        isLeader: lockRuntime.owns,
+        getLeaderBinding: currentInstanceThreadRuntime.getRestorationIdentity,
+        getActiveContext: telegramSessionContextStore.get,
+        getActiveProfileName: getActiveTelegramThreadProfile,
         getLeaderState: lockRuntime.getState,
         updateStatus,
         recordRuntimeEvent,
@@ -1000,6 +1013,11 @@ export default function (pi: Pi.ExtensionAPI) {
     activeTurnRuntime,
     lockedPollingRuntime,
     stopPolling: disconnectTelegramAndDeleteCurrentThread,
+    getDisconnectThreadName() {
+      const record = findCurrentThreadRecord();
+      if (!record?.target.threadId) return undefined;
+      return record.threadName ?? "current Telegram thread";
+    },
     onTransportChanged: deliveryLifecycleRuntime.onSessionStart,
     getStatusLines,
     buttonActionStore,
@@ -1026,6 +1044,7 @@ export default function (pi: Pi.ExtensionAPI) {
       onModelSelect: currentModelRuntime.onModelSelect,
     },
     activityRuntime,
+    assistantOutputRuntime,
     configStore,
     abort,
     typing,
@@ -1051,12 +1070,8 @@ export default function (pi: Pi.ExtensionAPI) {
     proactivePushChatIdGetter,
     proactivePushTargetGetter,
     isProactivePushEnabled: configControls.isProactivePushEnabled,
-    canSendProactivePush(ctx) {
-      return (
-        lockOwnershipGuard.ownsContext(ctx) ||
-        telegramBusFollowerRegistrationState.isRegistered()
-      );
-    },
+    getAssistantRenderingMode: configControls.getAssistantRenderingMode,
+    recordMessageOwnership: messageOwnershipRuntime.recordLocal,
     canSendAgentActivity(ctx) {
       return (
         lockOwnershipGuard.ownsContext(ctx) ||