@llblab/pi-telegram 0.39.5 → 0.41.0

package/AGENTS.md

@@ -92,9 +92,9 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - Telegram extension side effects must not hold Pi's core lifecycle hostage after semantic completion. Preserve ordering in extension-owned background work, record failures, and fence target/profile/transport/session authority.
 - Complete assistant/guest model answers use Telegram-native Rich Markdown. Harness-owned menus, status, diagnostics, thinking, and tool evidence remain explicit HTML/plain or their documented native surface. Preserve literal code and structurally safe chunking; never split invalid markup.
 - `preview` owns streaming lifecycle only, not assistant rendering. Finalization waits for active preview flushes and must not issue pre/post-final draft-clear calls that create transient Telegram draft UI.
-- Native `sendChatAction(typing)` is the automatic activity signal. Do not invent extra in-chat work indicators or emit activity for startup/connect/reload/recovery alone.
-- Public activity handlers and companion delivery are asynchronous, target-bound, generation-fenced surfaces. Token deltas, hidden reasoning, unknown sources, and stale authority never enter public projection.
-- UI labels, emoji semantics, navigation, settings controls, callback namespaces, voice behavior, command templates, and assistant markup follow the linked `/docs` contracts; do not restate those evolving details here.
+- Native `sendChatAction(typing)` is the automatic activity signal for unsettled agent and compaction work while Telegram transport is authorized. Extension-owned blocking UI prompts pause it and completion resumes it while either work owner remains active. Do not invent extra in-chat work indicators or emit activity for startup/connect/reload/recovery alone.
+- Public activity handlers and connected companion delivery are asynchronous, target-bound, generation-fenced surfaces. Connected companion projection has no independent opt-out: disconnect or authority loss is its boundary. Token deltas, hidden reasoning, unknown sources, and stale authority never enter public projection.
+- UI labels, emoji semantics, navigation, settings controls, callback namespaces, voice behavior, command templates, and assistant markup follow the linked `/docs` contracts. Generated human-readable prompt-button labels use `emoji + space + text`; emoji-free text is only a reasoned no-semantic-marker fallback. Non-spatial generated controls default to top-level vertical cells, with nested rows reserved for unmistakably compact peers. Do not restate other evolving UI details here.
 
 ## 5. Domain Ownership Index
 
@@ -125,7 +125,7 @@ The detailed map is canonical in [`docs/architecture.md`](./docs/architecture.md
 - Keep interfaces consistent with their owning exported contract. Use local structural `*Like`/view types only for deliberate narrow projections, not duplicate source-of-truth models.
 - Remove dead code immediately. Reachability from composition roots, public exports, tests, registered surfaces, and documented APIs—not recent usefulness—determines whether code is live.
 - Treat every meaningful `index.ts` edit as a composition-pressure check, but keep one-off live adapter wiring there when extraction would only hide cross-domain state.
-- Follow [`docs/ui-style.md`](./docs/ui-style.md) for interface copy, emoji, buttons, menus, and dialogs. Update the registry before assigning a new UI emoji meaning. Standalone notices use one fully bold emoji-led heading with terminal punctuation; callback alerts preserve equivalent emoji-led plain text because Telegram does not support rich formatting there.
+- Follow [`docs/ui-style.md`](./docs/ui-style.md) for interface copy, emoji, buttons, menus, and dialogs. Update the registry before assigning a new UI emoji meaning. Standalone notices use one fully bold emoji-led sentence with a terminal period; menu or chooser headings use the same hierarchy with a terminal colon. Material names may add nested italic emphasis without breaking the outer bold span. Callback alerts preserve equivalent emoji-led plain text because Telegram does not support rich formatting there.
 - Markdown tables use compact source formatting with `---` separator cells and one surrounding space per cell. Preserve vendored references unchanged.
 - Treat Windows filesystem, named-pipe, lock, heartbeat, and atomic-rename reports as high-signal evidence; reduce them to regressions or explicit platform caveats.
 - Route significant runtime failures through the redacted recent-event recorder. Keep the compact TUI status at generic `error`; details belong in diagnostics.

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.41.0: Connected Companion Presence
+
+- `Always-On Projection`: Treats authorized Telegram connection as the public-output boundary for local, autonomous, and unclassified Pi work, always delivering completed visible blocks in order instead of exposing an independent proactive-push opt-out.
+- `Configuration`: Removes Proactive Push from Telegram Settings and the public config contract, atomically drops retired `assistant.proactivePush` values during normalization, and routes stale pre-upgrade callbacks back to the current Settings surface with an explanatory notice.
+- `Work Presence`: Keeps native Telegram typing aligned with unsettled agent and compaction work, pauses it only while extension-owned local UI prompts await the operator, and resumes it after those prompts even when compaction begins after low-level `agent_end`.
+- `Compaction Notices`: Preserves observed `Compaction started` and terminal notices across Pi 0.84.4's post-`agent_end` automatic-compaction order, flushing them after the final-answer delivery tail at `agent_settled`.
+- `Generated Controls`: Requires semantic emoji-led human-readable labels and defaults non-spatial controls to full-width vertical cells, reserving nested horizontal rows for unmistakably compact peers while retaining reasoned no-marker and genuine spatial-grammar exceptions.
+- `Thread Presence`: Aligns the Threaded Mode instance-connected notice with the common information hierarchy by bolding the complete emoji-led sentence while adding nested bold-italic emphasis to the instance name.
+- `Status Parity`: Renames the ambiguous Usage row to Tokens and mirrors Pi's compact terminal telemetry in one line, including inline `R`/`W` cache tokens and `CH` for the latest request's cache-hit rate rather than a cumulative-session approximation.
+- `Voice Setup`: Links maintained Groq Whisper, Mistral Voxtral, and keyless Edge TTS Skills from the voice guide, documenting their environment requirements and direct `telegram.json` command-template path without a companion extension or local speech model.
+
+## 0.40.0: Pi 0.84.4 Lifecycle Alignment
+
+- `Pi Compatibility`: Requires `@earendil-works/pi-coding-agent`, `pi-agent-core`, and `pi-ai` 0.84.4 or newer, aligning the bridge and its validation runtime with native compaction-failure, mid-run compaction, message-finalization, and UI-prompt lifecycle contracts.
+- `Compaction Failure`: Handles `session_compact_failed` immediately by clearing compacting state, stopping observer-owned typing, releasing deferred queue work, abandoning stale activity, and reporting automatic failure or cancellation without duplicating manual `/compact` errors.
+- `Compaction Chronology`: Distinguishes terminal assistant output awaiting Telegram delivery from mid-run tool continuation. Post-answer notices remain ordered after the final reply, while tool-result threshold compaction is reported in place before the next assistant response.
+- `Local UI Waiting`: Pauses Telegram typing while Pi waits on extension-owned local select, confirm, input, editor, or custom prompts and emits coalesced `ui-prompt-start` / `ui-prompt-end` Activity boundaries before resuming active-turn typing.
+- `Inbound Context`: Raises successful inbound handler and built-in text attachment output from 12,000 to 24,000 characters while retaining the 1 MB built-in file admission ceiling and explicit truncation evidence.
+
 ## 0.39.5: Auto-Compaction Notice Chronology Hotfix
 
 - `Turn Chronology`: Defers observed automatic-compaction notices while a Telegram turn is still active, preserving the same causal order shown by the terminal: final answer, compaction started, then compaction completed. Abandoned compactions and session shutdown discard deferred notices instead of leaking them into a later turn.

package/README.md

@@ -8,7 +8,7 @@
 
 It is a **runtime adapter**, not a remote terminal. Start or supervise work in the Pi TUI, then continue from Telegram while away from the keyboard. Each Telegram destination follows a running Pi instance and sends prompts into that instance's currently active session; it is not permanently bound to one session file or session identity. The bridge preserves Pi session semantics instead of pretending Telegram is a PTY, shell, process launcher, or session browser. That boundary is the product: Telegram gets safe runtime handles, not raw terminal power.
 
-Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. Proactive push is enabled by default for local, autonomous, and unclassified extension follow-up work: `assistant.proactivePush` projects visible checkpoints and the final answer to the authorized Telegram target once and in order, preserving assistant-authored `telegram_button` comments as interactive prompt buttons; set it explicitly to `false` to disable only that local/autonomous projection. Neither path mirrors local prompts, thinking, tool traffic, token deltas, or stale-generation work. The separate `Activity` setting defaults to `verbose` so new installations discover collapsed provider-exposed thinking and tool evidence immediately; operators can narrow it to one class or choose `quiet`. See [Outbound](docs/outbound.md#public-assistant-output) and the [configuration reference](docs/public-api.md#configuration-api).
+Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. While Telegram is connected, local, autonomous, and unclassified extension follow-up work also projects visible checkpoints and the final answer to the authorized Telegram target once and in order, preserving assistant-authored `telegram_button` comments as interactive prompt buttons. This connected companion projection is always active rather than configurable. Neither path mirrors local prompts, thinking, tool traffic, token deltas, or stale-generation work. The separate `Activity` setting defaults to `verbose` so new installations discover collapsed provider-exposed thinking and tool evidence immediately; operators can narrow it to one class or choose `quiet`. See [Outbound](docs/outbound.md#public-assistant-output) and the [configuration reference](docs/public-api.md#configuration-api).
 
 This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
 

package/docs/activity.md

@@ -96,7 +96,7 @@ Source classification follows evidence, not guesses:
 
 Automatic retries, overflow compaction retries, and tool continuations inherit the current activity identity/source until `agent_settled`. A new unrelated `agent_start` after settlement allocates a new activity id.
 
-A standalone compaction owns a temporary activity only until `session_compact`. Pi does not expose a sibling-extension cancellation/failure callback after `session_before_compact`, so pi-telegram abandons that temporary identity at the first provable fallback boundary: the next `agent_start`, a replacement compaction start, session shutdown, or the existing five-minute compaction-observer timeout. A late `session_compact` after abandonment is ignored and cannot attach to the next run. Compaction inside an existing agent activity never clears that agent's identity.
+A standalone compaction owns a temporary activity until `session_compact` or `session_compact_failed`. Native failure or cancellation immediately abandons that identity, clears compacting state, releases deferred queue work, and stops observer-owned typing; the five-minute observer timeout remains a compatibility fallback for a host that never emits a terminal compaction event. A late `session_compact` after abandonment is ignored and cannot attach to the next run. Compaction inside an existing agent activity never clears that agent's identity.
 
 ## Event Contract
 
@@ -151,6 +151,12 @@ export type TelegramActivityEvent = TelegramActivityEnvelope & (
       type: "compaction-end";
       reason: "manual" | "threshold" | "overflow" | "unknown";
     }
+  | {
+      type: "ui-prompt-start";
+      kind: "select" | "confirm" | "input" | "editor" | "custom";
+      title?: string;
+    }
+  | { type: "ui-prompt-end" }
   | { type: "agent-end" }
   | { type: "agent-settled" }
 );
@@ -236,7 +242,7 @@ The Delivery API independently serializes concrete Telegram operations per targe
 
 ### Core assistant-output projection
 
-Activity's built-in assistant-output projection uses the same normalized `assistant-segment` boundary exposed to public handlers. For `telegram` activity it always projects complete `intermediate` commentary to the immutable originating target, while final and terminal-partial segments remain with active-turn settlement. For `local`, `autonomous`, or unclassified extension follow-up activity, `assistant.proactivePush` enables projection of every completed public block, including intermediate commentary/checkpoints and the final block. This closes actor-follow-up delivery without reclassifying it as direct user input. It never projects text token deltas, reasoning events, tool events or payloads, or empty text.
+Activity's built-in assistant-output projection uses the same normalized `assistant-segment` boundary exposed to public handlers. For `telegram` activity it always projects complete `intermediate` commentary to the immutable originating target, while final and terminal-partial segments remain with active-turn settlement. For `local`, `autonomous`, or unclassified extension follow-up activity, every completed public block—including intermediate commentary/checkpoints and the final block—is projected whenever this Pi instance retains authorized connected transport. This closes actor-follow-up delivery without reclassifying it as direct user input, and the connected companion contract has no projection opt-out. It never projects text token deltas, reasoning events, tool events or payloads, or empty text.
 
 The projection does not delay Activity dispatch or Pi lifecycle. Its ordered admission tail deduplicates normalized event identity, while existing routing and outbound owners revalidate the immutable admission-time target, profile/token transport generation, direct leader epoch or follower registration generation, and session generation immediately before each send. Active-turn final delivery waits for admitted commentary inside its existing background task. A replacement or stale owner drops queued work rather than rerouting it, and an already-started non-idempotent Bot API mutation follows the normal `commit-unknown` no-replay contract.
 
@@ -250,9 +256,10 @@ The bridge maps Pi hooks as follows:
 - `agent_start`: allocate or reuse activity identity and emit `agent-start` after Telegram queue consumption establishes active-turn ownership.
 - `message_update.assistantMessageEvent`: normalize text/reasoning/provider boundaries.
 - `tool_execution_start/update/end`: emit executed tool events.
-- `session_before_compact` / `session_compact`: emit compaction boundaries and preserve activity identity across retry compaction; abandon an unterminated standalone compaction at the next lifecycle boundary or observer timeout rather than merging it into another run. A missing or unrecognized reason maps to `unknown` rather than guessing.
-- `agent_end`: emit low-level run completion but keep identity alive for retry/follow-up work.
-- `agent_settled`: emit terminal settlement, flush pending terminal segments, and release activity identity.
+- `session_before_compact` / `session_compact` / `session_compact_failed`: emit successful compaction boundaries, abandon failed or cancelled work immediately, and preserve activity identity across retry compaction. Mid-run threshold compaction stays between tool results and the next assistant response, while terminal assistant output awaiting transport keeps later notices behind its final reply. A missing or unrecognized reason maps to `unknown` rather than guessing.
+- `ui_prompt_start` / `ui_prompt_end`: emit one coalesced waiting span for extension-owned local UI, pause Telegram typing while Pi waits for the operator, and resume typing when the prompt closes if agent or compaction work remains unsettled.
+- `agent_end`: emit low-level run completion but keep identity and connected work presence alive for retry, compaction, or follow-up work.
+- `agent_settled`: emit terminal settlement, flush pending terminal segments, release activity identity, and end agent-owned connected work presence.
 - `session_shutdown`: stop dispatch, clear pending normalization state, and invalidate delivery generation through the existing delivery lifecycle.
 
 ## Diagnostics

package/docs/architecture.md

@@ -79,7 +79,7 @@ The repository uses a **Flat Domain DAG**:
 - `keyboard`: shared inline-keyboard reply-markup shape only; feature domains own labels, callback data, and behavior.
 - `preview` / `replies` / `rendering`: throttled native Rich Markdown draft delivery, native final reply delivery, reply parameters, transport-limit chunking, and remaining Telegram HTML rendering for bridge-owned UI/compatibility surfaces.
 - `delivery`: public extension operational-view delivery, active-turn/instance/aggregate/authorized target policy, logical chunk handles, per-target ordering, runtime generation fencing, and the process-local runtime membrane. Its bridge adapter composes the established UI/compat reply renderer with narrow bus-aware Telegram API and ownership ports; it never exposes bot clients or Pi contexts.
-- `activity`: public normalized Pi lifecycle registration, activity/source identity, assistant segment and reasoning normalization, executed-tool events, non-blocking per-handler queues, delivery contexts, compatibility adapters, and shutdown fencing. The same domain extends assistant-output observation for proactive push: eligible completed local/autonomous public segments retain source order and deduplicate event identity. `bindings` assembles observation, authority, sender, and failure-projection ports; routing owns exact delivery authority, outbound composes established transformations and reply delivery, and Bot API domains implement transport. No separate proactive state-machine domain exists.
+- `activity`: public normalized Pi lifecycle registration, activity/source identity, assistant segment and reasoning normalization, executed-tool events, non-blocking per-handler queues, delivery contexts, compatibility adapters, and shutdown fencing. The same domain extends assistant-output observation for connected companion projection: eligible completed local/autonomous public segments retain source order and deduplicate event identity. `bindings` assembles observation, authority, sender, and failure-projection ports; routing owns exact delivery authority, outbound composes established transformations and reply delivery, and Bot API domains implement transport. No separate proactive state-machine domain exists.
 - `outbound-markup`: top-level assistant action comment parsing, attribute parsing, voice reply planning, and preview/delivery stripping.
 - `outbound`: outbound text transformations, voice/button artifact delivery, and generated callback actions.
 - `generative-apps`: managed deterministic application identity, canonical installation and explicit replacement, content-addressed module loading, state timelines, cross-process transition serialization, bounded executable-plus-argv adaptation, `telegram_bind`, and pre-model-queue `app::method` invocation. It does not own Telegram transport, arbitrary shell execution, or the external application adapted by one Generative App.
@@ -315,14 +315,15 @@ Queue and menu mutations are reachable through Telegram updates handled by the c
 
 ### Compaction And Typing Status
 
-Manual `/compact` requires inline confirmation because accidental taps are disruptive. Confirmed manual compaction and auto-compaction both set the bridge compaction flag, block queued prompt dispatch, retain that flag in explicit diagnostics, and clear it on compact completion, timeout fallback, or session shutdown. Pi owns its terminal compaction lifecycle; pi-telegram keeps `Active` scoped to Telegram-owned work and otherwise preserves the stable connected/leader/follower role.
+Manual `/compact` requires inline confirmation because accidental taps are disruptive. Confirmed manual compaction and auto-compaction both set the bridge compaction flag, block queued prompt dispatch, retain that flag in explicit diagnostics, and clear it on native compact completion or failure, timeout fallback, or session shutdown. Pi owns its terminal compaction lifecycle; pi-telegram keeps `Active` scoped to Telegram-owned work and otherwise preserves the stable connected/leader/follower role. Mid-run threshold compaction reports notices in place between tool output and the next assistant response; compaction observed after terminal assistant output waits for final Telegram delivery so transport chronology matches the terminal.
 
 Native typing during compaction follows connected-instance activity rather than terminal status:
 
 - Confirmed manual `/compact` starts a native `typing` keepalive in the command target and stops it on completion/failure.
 - Automatic/session compaction with an active Telegram turn reuses that turn's target.
 - Automatic/session compaction without an active Telegram turn uses the connected instance's assigned target; an unconnected instance sends nothing.
-- Thread-targeted typing is sent to the concrete thread and mirrored to `All` as the aggregate activity surface; completion, timeout, and shutdown stop the keyed loop.
+- Thread-targeted typing is sent to the concrete thread and mirrored to `All` as the aggregate activity surface; completion, native failure, timeout, and shutdown stop the keyed loop.
+- Pi `ui_prompt_start` pauses typing while an extension-owned local prompt waits for the operator; `ui_prompt_end` emits the matching Activity boundary and resumes typing whenever agent or compaction work remains unsettled.
 
 At every connected instance `agent_start`, the lifecycle binding starts Telegram's native `…typing` indicator in that instance's assigned target, whether the run came from Telegram, the local TUI, or an autonomous continuation such as Grow Loop. Terminal `Active` remains Telegram-turn-specific; the native indicator answers the separate question of whether the instance is doing agent work. Each loop keeps one action in flight, while the leader API runtime coalesces identical chat/thread/action calls across local and follower traffic for two seconds; expired gates prune opportunistically and at most 256 currently active keys are retained. A Telegram 429 response opens the exact action's shared `retry_after` suppression window without scheduling delayed retries or projecting expected activity throttling as a terminal status error. Assistant message start/update hooks still re-arm it during Telegram-owned turns so transient provider/model errors do not leave a continuing run without activity feedback, and agent/session completion stops it.
 
@@ -389,13 +390,13 @@ The bridge does not mirror arbitrary `ctx.ui.confirm/input/select/custom` prompt
 
 ## Diagnostics And Operational Behavior
 
-Status rendering distinguishes connected, active, dispatching, queued, tool-running, model-switching, and compacting states; the Telegram status menu gives compaction precedence over generic active or pending work. Observed automatic compaction sends the same start and completion notices as the manual command without duplicating notices for command-owned compaction. If a queue mutation removes the last waiting item while Telegram-owned work still has running tools, status remains active instead of degrading to connected.
+Status rendering distinguishes connected, active, dispatching, queued, tool-running, model-switching, and compacting states; the Telegram status menu gives compaction precedence over generic active or pending work. Its Tokens row mirrors Pi's terminal footer, including inline `R` cache-read tokens, `W` cache-write tokens, and `CH` for the latest assistant request's cache-read share of prompt tokens rather than a misleading cumulative-session ratio; the label remains distinct from companion-provided usage limits. Observed automatic compaction sends the same start and completion notices as the manual command without duplicating notices for command-owned compaction. If a queue mutation removes the last waiting item while Telegram-owned work still has running tools, status remains active instead of degrading to connected.
 
 Queue reaction behavior, lane-tail transitions, Keep/Skip independence, multi-reaction precedence, and the Bot API reaction-removal limitation are defined in [Priority, Reactions, Keep, and Skip](#priority-reactions-keep-and-skip). Reaction changes first flush a matching delayed text or media group so the governed turn exists before mutation, and dropping marked heads cannot leave status permanently queued.
 
 `/telegram-status` records grouped diagnostics for transport/API, polling/update, prompt dispatch, controls, typing, compaction, setup, session lifecycle, attachment queue/delivery, and recent redacted runtime events. Polling diagnostics expose the exact phase, phase start, current update, last successful `getUpdates` response, and stop reason; outbound success never substitutes for inbound progress. Expected preview noise such as unchanged edit responses is filtered out. The compact TUI status renders only `error`; detailed failure text remains in diagnostics and profile-scoped logs instead of expanding the status line.
 
-Complete intermediate assistant text blocks from Telegram-originated activity are sent once to the immutable originating target before active-turn final delivery; final and terminal-partial segments stay with settlement so replies are not duplicated. When `assistant.proactivePush` is enabled and this instance has exact direct or follower transport authority, completed public blocks from local/autonomous work are also sent once and in source order to the instance's authorized target. Both paths use the configured Rich or HTML renderer and exclude reasoning, tool traffic, token deltas, local prompt text, unknown sources, and stale generations. Each admitted block remains fenced to its exact target, profile/token stamp, leader epoch or follower registration generation, and session generation; non-idempotent acknowledgement ambiguity never authorizes replay.
+Complete intermediate assistant text blocks from Telegram-originated activity are sent once to the immutable originating target before active-turn final delivery; final and terminal-partial segments stay with settlement so replies are not duplicated. While this instance has exact direct or follower transport authority, completed public blocks from local/autonomous work are always sent once and in source order to the instance's authorized target. Connected companion projection is not configurable; disconnect or authority loss is its boundary. Both paths use the configured Rich or HTML renderer and exclude reasoning, tool traffic, token deltas, local prompt text, unknown sources, and stale generations. Each admitted block remains fenced to its exact target, profile/token stamp, leader epoch or follower registration generation, and session generation; non-idempotent acknowledgement ambiguity never authorizes replay.
 
 `assistant.activity` is an independent bridge-owned projection over normalized Activity events. Each process reloads the shared file-backed setting at `agent-start` before activity admission, so multi-instance mode cannot continue projecting a stale broader process-local selection. Omitted values resolve to `verbose`, while invalid values fail closed to `quiet`; `thinking` and `tools` select one technical class, while `verbose` enables both. Provider-exposed thinking uses persistent ordinary HTML containing only a standard expandable blockquote with a bounded redacted latest-text window and inline Markdown rendered as Telegram HTML. Completed executed tools use native Rich Messages: each closed `<Tool>: <status>` root details node renders snake-case names as title words while preserving an uppercase two- or three-letter repeated prefix per word, then the native disclosure chevron reveals an open-by-default `arguments` child plus closed retained `update N` and `result`/`error` child details with lowercase monospaced, marker-free summaries and JSON pre blocks; known-safe Rich rejections fall back to the previous HTML disclosure. The projection captures the exact target and transport stamp at activity admission, serializes updates, preserves tool-start order, closes coalescing across assistant/thinking boundaries, bounds retained text/update memory plus edit frames and message/tool size, disables previews and HTTP(S) auto-link recognition inside technical evidence, and never replays a possibly committed send. Session generations own independent queues, so replacement drops queued old work without waiting on an old call. Both proactive prose and active-turn final delivery wait for the admitted activity queue inside their extension-owned delivery tasks, preserving technical-before-semantic ordering without delaying Pi lifecycle completion. Settlement, replacement, disconnect, failure, or stale authority clears only local ownership; already-sent activity messages remain in chat.
 
@@ -418,7 +419,7 @@ This is limited to Telegram-owned runs. If Pi is busy with non-Telegram work, th
 
 Non-critical timers are `unref()`ed so print/headless processes are not kept alive only by Telegram housekeeping. This includes typing keepalive intervals, bounded typing-idle waits, deferred queue dispatch, media/text-group debounce windows, preview flush timers, and polling retry sleeps. Polling retry sleep is abort-aware, so shutdown does not wait for the normal retry delay after a polling error.
 
-Non-interactive `pi -p` runs must remain passive unless Pi provides a live Telegram session lifecycle. Loading the extension with `telegram.json`, proactive push settings, or existing lock state must not by itself keep the print-mode process alive or let a non-owner send proactive Telegram output.
+Non-interactive `pi -p` runs must remain passive unless Pi provides a live Telegram session lifecycle. Loading the extension with `telegram.json` or existing lock state must not by itself keep the print-mode process alive or let a non-owner send companion Telegram output.
 
 ## Related
 

package/docs/outbound.md

@@ -8,9 +8,9 @@ Text handlers use the portable [Command Template Standard](./command-templates.m
 
 ## Public Assistant Output
 
-Every completed `assistant-segment` with `placement: "intermediate"` from a Telegram-originated turn is delivered as its own message to the immutable originating target before the ordinary active-turn final reply. This commentary path always applies; `assistant.proactivePush` does not disable it. Final and terminal-partial Telegram segments remain owned by active-turn settlement so the final answer, voice, buttons, previews, and artifacts are not duplicated.
+Every completed `assistant-segment` with `placement: "intermediate"` from a Telegram-originated turn is delivered as its own message to the immutable originating target before the ordinary active-turn final reply. Final and terminal-partial Telegram segments remain owned by active-turn settlement so the final answer, voice, buttons, previews, and artifacts are not duplicated.
 
-Proactive projection defaults on for local, autonomous, and unclassified extension follow-up Pi work. With `assistant.proactivePush` omitted or set to `true`, every completed public block—including visible commentary/checkpoints and the final answer—is projected to the instance's authorized target in source order; set it explicitly to `false` to opt out of only this local/autonomous projection. Both paths consume normalized complete Activity segments rather than raw token deltas, reasoning, or tool traffic.
+While Telegram is connected, local, autonomous, and unclassified extension follow-up Pi work always projects every completed public block—including visible commentary/checkpoints and the final answer—to the instance's authorized target in source order. There is no projection setting or opt-out: disconnecting Telegram is the boundary that stops this companion surface. Both paths consume normalized complete Activity segments rather than raw token deltas, reasoning, or tool traffic.
 
 Projected blocks use `assistant.rendering` independently of voice policy. Rich mode sends native Rich Markdown and HTML mode keeps the established HTML renderer; assistant-authored `telegram_button` comments are planned into prompt buttons before either renderer runs, while projection does not synthesize voice or attach queued files merely because Rich rendering is active. Ordered admission revalidates the exact target, profile/token transport generation, leader epoch or follower registration generation, and session generation before each send. Active-turn final delivery waits for admitted commentary inside its existing background delivery task, preserving commentary-before-final order without blocking Pi lifecycle completion. A `commit-unknown` outcome never permits replay.
 

package/docs/public-api.md

@@ -94,7 +94,6 @@ interface TelegramConfig {
   assistant?: {
     draftPreviews?: boolean;
     rendering?: "rich" | "html";
-    proactivePush?: boolean;
     activity?: "quiet" | "thinking" | "tools" | "verbose";
     timeInjection?: "hidden" | "always" | "interval";
   };
@@ -117,10 +116,10 @@ The file is global across Pi instances and contains configuration only. The per-
 Hidden/default semantics are represented by absence:
 
 - `threads.automaticCleanup` defaults to `true`; graceful Pi quit deletes the instance's bound Threaded Mode tab without prompting but preserves the owner slot as independent restart intent. Set it to `false`, or use `🧹 Thread cleanup` in Telegram Settings, to preserve the tab too. A confirmed `/telegram-disconnect`, unlike quit, clears restart ownership. Settings views and cleanup reload shared config before evaluating this switch, so another live Pi instance's update takes effect without restarting. Confirmed leader/follower teardown persists an exact target/runtime-generation cleanup intent before Telegram deletion; an interrupted attempt remains retryable by the current or successor leader under current authority and clears only after confirmed deletion. A same-profile replacement leader first adopts any still-active binding and cancels its superseded cleanup, so startup never deletes and recreates a reusable thread. If a follower's graceful envelope is missed, the leader may create the same fenced cleanup only after its heartbeat is stale, the OS confirms the exact registered PID no longer exists, cleanup remains enabled, and no replacement registration can overtake deletion. Heartbeat loss alone, live/unknown process liveness, IPC failure, and auth failure remain non-destructive. Invalid-config recovery makes the setting unresolved and therefore skips destructive cleanup. Manual `/telegram-disconnect` keeps its confirmation and teardown behavior regardless of this setting.
-- Every complete intermediate assistant text block from a Telegram-originated turn is delivered once to its immutable target before the existing final reply. This active-turn commentary path remains enabled when `assistant.proactivePush` is `false`; final and terminal-partial segments stay with settlement to prevent duplicate replies. `assistant.proactivePush` defaults to `true` only for local/autonomous work: omit it to project every completed public block, including commentary and the final block, or set it explicitly to `false` to disable that projection. Both paths exclude token deltas, hidden reasoning, tool calls/arguments/results, empty blocks, unknown sources, 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`.
+- Every complete intermediate assistant text block from a Telegram-originated turn is delivered once to its immutable target before the existing final reply; final and terminal-partial segments stay with settlement to prevent duplicate replies. While Telegram transport remains authorized, local/autonomous work also projects every completed public block, including commentary and the final block. This connected companion projection is always active and excludes token deltas, hidden reasoning, tool calls/arguments/results, empty blocks, unknown sources, 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. Retired top-level and `assistant.proactivePush` keys are ignored; the nested key is removed during config normalization.
 - `assistant.activity` accepts exactly `"quiet"`, `"thinking"`, `"tools"`, or `"verbose"`; omitted values default to `"verbose"`, explicit values remain unchanged, and invalid values fail closed to `"quiet"`. Each Pi process reloads the shared file-backed value at `agent-start`, so multi-instance activity isolation never relies on a stale process-local config snapshot. `thinking` shows only provider-exposed thinking, `tools` shows only completed tool activity, and `verbose` shows both. Thinking uses persistent ordinary HTML `sendMessage`/`editMessageText` disclosure with a standard expandable blockquote, a `🧠` header carrying the current Pi thinking level, and bounded redacted text whose inline Markdown renders as Telegram HTML. Tools use native Rich Messages with one header followed by separate closed details and JSON pre blocks for bounded redacted arguments, retained updates, and results/errors. Thinking disables link previews on every HTML send/edit and neutralizes HTTP(S) auto-link detection; Rich tool output disables automatic entity detection, with the same protections retained by its HTML fallback. Consecutive tools coalesce only inside the same ordered activity segment and bounded message. Legacy `assistant.activityVerbosity` is read only when `assistant.activity` is absent and is removed by the next Activity Settings write.
 - Voice Reply `hidden`: no `voice.replyMode` key is persisted; legacy `manual` resolves to this silent default. `mirror` adds `[voice] delivery: automatic voice` only to voice/audio-input turns, while `always` adds the same effective line to every Telegram turn.
-- Agent activity status is not configurable in this release. Telegram uses native `sendChatAction(typing)` / product `...active` status as the only automatic in-chat work signal before the final reply.
+- Agent activity status is not configurable. While Telegram transport remains authorized, Telegram uses native `sendChatAction(typing)` / product `...active` status as the automatic in-chat work signal for unsettled agent and compaction work. Extension-owned blocking UI prompts pause it and completion resumes it while either work owner remains active.
 - `assistant.timeInjection` accepts `hidden`, `always`, or `interval` and defaults to `interval` when absent without migrating an explicit stored value. Settings writes the selected value there, including `hidden`; the old `time.injectionMode` key is ignored and is not migrated. `time.interval` remains the optional interval duration in milliseconds.
 
 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.
@@ -337,7 +336,7 @@ Contract:
 - Providers are synchronous because `/start` status text is rendered inline with the menu.
 - Return `undefined` when the line is not relevant for the active model.
 - Provider failures are isolated and skipped so optional companion status cannot break the core Telegram menu.
-- The bridge renders rows as `<Label>: <value>` in the same HTML status block as Status, Usage, Cost, and Context, capitalizing the first label character for Telegram UI consistency.
+- The bridge renders rows as `<Label>: <value>` in the same HTML status block as Status, Tokens, Cost, and Context, capitalizing the first label character for Telegram UI consistency. Tokens mirrors Pi's footer telemetry: `↑` input, `↓` output, `R` cache-read tokens, `W` cache-write tokens, and `CH` for the latest assistant request's `cacheRead / (input + cacheRead + cacheWrite)`, shown to one decimal place only after the session reports cache activity. The precise Tokens label avoids conflating token telemetry with companion-provided usage-limit rows.
 
 ## Updates
 

package/docs/ui-style.md

@@ -32,7 +32,6 @@ Use emoji as stable semantic markers, not decoration. Emoji carry transportable
 | `🧩` | Extension-provided surface | Extension command examples, extension section examples | Companion extensions may choose their own emoji, but `🧩` means generic extension/plugin. |
 | `👄` | Voice reply policy | Voice reply settings row and detail card | Not a generic audio attachment marker. |
 | `🕒` | Time injection / wall-clock context | Time injection settings row and detail card | Clock-face marker with hands; not a generic duration/progress marker. |
-| `📌` | Proactive push / pinned behavior | Proactive push settings row and detail card | Not generic active/selected state. |
 | `🔬` | Activity / technical detail | Activity settings row and detail card | Chooses quiet, thinking, tools, or verbose bridge activity; not a generic diagnostics marker. |
 | `🧠` | Model thinking controls | Thinking menus and status rows | Thinking activity quotes omit this icon and their header entirely to minimize chat height. |
 | `📎` | Attachment | Attachment summaries, queue rows for attachment-only turns | Not for thread binding. |
@@ -138,7 +137,6 @@ Rules:
 Examples:
 
 - `🟢 Active` — model detail, navigates back to model list
-- `📌 Proactive push: On` — settings row, opens the toggle submenu
 - `👄 Voice reply: Mirror` — settings row, opens the option list
 
 ## Boolean Toggles
@@ -199,7 +197,7 @@ Examples:
 
 ## Generated Prompt Buttons
 
-A button-only assistant reply uses the standard Rich Markdown heading `☑️ **Choose an option:**`: semantic icon first, one space, bold heading text, and a final colon. Assistant-generated prompt buttons use the default app style before selection. After queue admission, edit only the selected button to its agent-configured `selected_style`: `primary` (default/blue), `success` (green), or `danger` (red). Preserve its agent-authored text and emoji, leave other choices at their default style, and always queue the selected prompt regardless of color. The callback acknowledgement remains the compatibility fallback when a client does not render button styles.
+A button-only assistant reply uses the standard Rich Markdown heading `☑️ **Choose an option:**`: semantic icon first, one space, bold heading text, and a final colon. Every generated human-readable action label starts with the most semantically appropriate emoji, one ASCII space, then concise action text. Emoji selection is part of authoring the control, including compact label-equals-prompt forms. Emoji-free text remains a syntax-compatible fallback only when no honest semantic marker exists after considering the action, domain, and state—not merely for convenience or label pressure; genuine coordinate and symbolic spatial controls retain their established grammar. Generated non-spatial controls default to vertical full-width buttons represented as top-level matrix cells. Nested row arrays are a compact-peer exception only when every label is unmistakably short—roughly 15 visible characters or fewer including emoji and space; this is a judgment heuristic rather than a mechanical count, and any plausible ellipsis or wrapping risk returns the controls to vertical rows. Assistant-generated prompt buttons use the default app style before selection. After queue admission, edit only the selected button to its agent-configured `selected_style`: `primary` (default/blue), `success` (green), or `danger` (red). Preserve its agent-authored text and emoji, leave other choices at their default style, and always queue the selected prompt regardless of color. The callback acknowledgement remains the compatibility fallback when a client does not render button styles.
 
 ## Navigation
 
@@ -225,8 +223,9 @@ Message cards and standalone informational notices sent by the bot should start
 Rules:
 
 - Start with a bold heading or, for dialogs, a bold question.
-- Format standalone notices as one fully bold line: relevant emoji, one space, concise sentence, and terminal period or colon.
-- Apply the same hierarchy to success, progress, empty, busy, unavailable, cancellation, and failure notices; do not bold only a fragment of a standalone notice.
+- Format standalone notices as one fully bold line: relevant emoji, one space, concise sentence, and terminal period. Menu or chooser headings use the same fully bold form but end in a colon when controls or detail follow.
+- Keep the emoji and complete sentence or heading inside the single bold span; do not bold only a fragment. A material name or phrase may receive nested italic emphasis without breaking the outer bold hierarchy—for example `<b>📡 Instance <i>Cedar</i> connected.</b>`.
+- Apply the same hierarchy to success, progress, empty, busy, unavailable, cancellation, and failure notices.
 - Callback alerts remain plain text because Telegram does not support rich text there, but still keep the relevant emoji and concise sentence.
 - Setting detail cards may include an emoji in the heading, then a colon and the current value in `<code>`.
 - Explain what the setting does and what the options mean only as much as needed.

package/docs/voice.md

@@ -1,6 +1,6 @@
 # Voice Integration
 
-Voice messages flow through an **inbound transcription → outbound voice reply** pipeline. This document describes the bridge's role in that pipeline; provider-specific mechanics (TTS/STT backends, voice IDs, languages) are owned by voice provider extensions. This is a first-class extension surface: one companion extension can provide STT fallbacks for inbound voice/audio files and TTS fallbacks for outbound Telegram voice replies without owning a second bot polling loop.
+Voice messages flow through an **inbound transcription → outbound voice reply** pipeline. This document describes the bridge's role in that pipeline; provider-specific mechanics (TTS/STT backends, voice IDs, languages) are owned by configured handler scripts or voice provider extensions. This is a first-class extension surface: one companion extension can provide STT fallbacks for inbound voice/audio files and TTS fallbacks for outbound Telegram voice replies without owning a second bot polling loop.
 
 ## Overview
 
@@ -18,7 +18,17 @@ Use the smallest path that fits the operator's available capabilities:
 2. **Companion extension:** Register programmatic STT/TTS providers when installation, provider-owned settings, lifecycle integration, or zero-config reuse justifies code.
 3. **Hybrid:** Keep explicit operator command templates first and let installed providers supply progressive fallbacks.
 
-pi-telegram does not catalog speech providers. Configuration agents should discover applicable Skills or trusted local executables, verify required environment variables by presence without exposing values, preserve unrelated `telegram.json` state, ensure TTS ends as OGG/Opus, and test each stage before the live Telegram path. `hidden` remains the safe and useful default: it disables only automatic voice replies, while explicit `telegram_voice` actions continue to use the configured synthesis pipeline.
+pi-telegram does not maintain a built-in or exhaustive speech-provider catalog. Configuration agents should discover applicable Skills or trusted local executables, verify required environment variables by presence without exposing values, preserve unrelated `telegram.json` state, ensure TTS ends as OGG/Opus, and test each stage before the live Telegram path. `hidden` remains the safe and useful default: it disables only automatic voice replies, while explicit `telegram_voice` actions continue to use the configured synthesis pipeline.
+
+### Ready-made command-template examples
+
+The public [`llblab/skills`](https://github.com/llblab/skills) repository provides three maintained Skills with standalone scripts that can be wired directly into `telegram.json`; no additional Pi extension or local inference engine is required:
+
+- [`groq-stt`](https://github.com/llblab/skills/tree/main/groq-stt) — Groq Whisper speech-to-text through `scripts/transcribe.sh`. It outputs plain transcript text and requires `GROQ_API_KEY` in the Pi process environment.
+- [`mistral-stt`](https://github.com/llblab/skills/tree/main/mistral-stt) — Mistral Voxtral speech-to-text through `scripts/transcribe.sh`. It outputs plain transcript text and requires `MISTRAL_API_KEY` in the Pi process environment.
+- [`edge-tts`](https://github.com/llblab/skills/tree/main/edge-tts) — Microsoft Edge neural text-to-speech through `scripts/say.sh`. It requires internet access but no account or API key and can write MP3 output for the outbound pipeline.
+
+The two hosted STT options avoid running a local transcription model and offer useful free-tier capacity after provider registration; provider limits and terms may change. Install or clone the Skill repository, verify the required API-key variable by presence without printing its value, and point the matching `inboundHandlers` template at the Skill's transcription script. For Edge TTS, point an `outboundHandlers` voice pipeline at `say.sh --file - --write-media {mp3}`, then convert `{mp3}` to `{ogg}` with ffmpeg as shown in [Outbound Voice Handlers](#outbound-voice-handlers), because Telegram native voice notes require OGG/Opus. Read each linked Skill's current `SKILL.md` for its exact CLI, defaults, dependencies, and optional language/model controls.
 
 ## Voice Detection
 

package/index.ts

@@ -548,7 +548,6 @@ export default function (pi: Pi.ExtensionAPI) {
   } = Bindings.createTelegramActivityBindingRuntime({
     generation: deliveryGenerationSeed,
     assistantOutput: {
-      isEnabled: configControls.isProactivePushEnabled,
       authority: {
         getPreferredTarget: proactivePushTargetGetter,
         getFallbackChatId: proactivePushChatIdGetter,

package/lib/activity.ts

@@ -85,6 +85,12 @@ export type TelegramActivityPayload =
         type: "compaction-end";
         reason: "manual" | "threshold" | "overflow" | "unknown";
       }
+    | {
+        type: "ui-prompt-start";
+        kind: "select" | "confirm" | "input" | "editor" | "custom";
+        title?: string;
+      }
+    | { type: "ui-prompt-end" }
     | { type: "agent-end" }
   | { type: "agent-settled" };
 
@@ -440,6 +446,12 @@ export function createTelegramActivityBridgeRuntime(deps: {
     onCompactionAbandoned() {
       getRuntime()?.onCompactionAbandoned();
     },
+    onUiPromptStart(kind, title) {
+      getRuntime()?.onUiPromptStart(kind, title);
+    },
+    onUiPromptEnd() {
+      getRuntime()?.onUiPromptEnd();
+    },
     onAgentEnd() {
       getRuntime()?.onAgentEnd();
     },
@@ -502,6 +514,11 @@ export interface TelegramActivityRuntime {
     reason: "manual" | "threshold" | "overflow" | "unknown",
   ) => void;
   onCompactionAbandoned: () => void;
+  onUiPromptStart: (
+    kind: "select" | "confirm" | "input" | "editor" | "custom",
+    title?: string,
+  ) => void;
+  onUiPromptEnd: () => void;
   onAgentEnd: () => void;
   onAgentSettled: () => void;
   onSessionShutdown: () => void;
@@ -533,6 +550,7 @@ export function createTelegramActivityRuntime(deps: {
   let pendingAssistantSegment: PendingAssistantSegment | undefined;
   let compactionInProgress = false;
   let compactionOwnedActivity = false;
+  let uiPromptInProgress = false;
   const ensureActivity = (
     activeTelegramTarget?: TelegramActivityTarget,
   ): string => {
@@ -592,6 +610,7 @@ export function createTelegramActivityRuntime(deps: {
     pendingAssistantSegment = undefined;
     compactionInProgress = false;
     compactionOwnedActivity = false;
+    uiPromptInProgress = false;
   };
   const abandonCompaction = (): void => {
     if (!compactionInProgress) return;
@@ -685,6 +704,16 @@ export function createTelegramActivityRuntime(deps: {
     onCompactionAbandoned() {
       abandonCompaction();
     },
+    onUiPromptStart(kind, title) {
+      if (!activityId || uiPromptInProgress) return;
+      uiPromptInProgress = true;
+      emit({ type: "ui-prompt-start", kind, title });
+    },
+    onUiPromptEnd() {
+      if (!activityId || !uiPromptInProgress) return;
+      uiPromptInProgress = false;
+      emit({ type: "ui-prompt-end" });
+    },
     onAgentEnd() {
       if (activityId) emit({ type: "agent-end" });
     },
@@ -712,7 +741,6 @@ export interface TelegramAssistantOutputRuntime {
 }
 
 export function createTelegramAssistantOutputRuntime<TAuthority = undefined>(deps: {
-  isEnabled: () => boolean;
   captureAuthority?: () => TAuthority;
   isAuthorityActive?: (authority: TAuthority) => boolean;
   canDeliver: (event: TelegramAssistantSegmentEvent) => boolean;
@@ -732,10 +760,9 @@ export function createTelegramAssistantOutputRuntime<TAuthority = undefined>(dep
   const admitted = new Set<string>();
   const isEligibleEvent = (event: TelegramAssistantSegmentEvent): boolean =>
     (event.source === "telegram" && event.placement === "intermediate") ||
-    ((event.source === "local" ||
-      event.source === "autonomous" ||
-      event.source === "unknown") &&
-      deps.isEnabled());
+    event.source === "local" ||
+    event.source === "autonomous" ||
+    event.source === "unknown";
 
   return {
     start() {

package/lib/bindings.ts

@@ -337,7 +337,6 @@ export interface TelegramAssistantOutputBindingRuntime<TTransportStamp> {
 export function createTelegramAssistantOutputBindingRuntime<
   TTransportStamp,
 >(deps: {
-  isEnabled: () => boolean;
   authority: {
     getPreferredTarget: () =>
       | OutboundAttachments.TelegramQueuedOutboundAttachmentTurnView["target"]
@@ -364,7 +363,6 @@ export function createTelegramAssistantOutputBindingRuntime<
       deps.sender,
     );
   const runtime = Activity.createTelegramAssistantOutputRuntime({
-    isEnabled: deps.isEnabled,
     ...authority,
     async send(event, authority, isAuthorityActive) {
       await deps.waitForActivityIdle?.();
@@ -1012,8 +1010,9 @@ export function registerTelegramLifecycleRuntimeHooks({
   const agentStartWithDedupReset = Lifecycle.createAgentStartDedupHook(
     agentLifecycleHooks.onAgentStart,
   );
+  let uiPromptActive = false;
   const startAgentActivityTypingLoop = (ctx: Pi.ExtensionContext): boolean => {
-    if (!canSendAgentActivity(ctx)) return false;
+    if (uiPromptActive || !canSendAgentActivity(ctx)) return false;
     const turn = activeTurnRuntime.get();
     const target = turn?.target ?? proactivePushTargetGetter();
     promptDispatchRuntime.startTypingLoop(ctx, turn?.chatId ?? target?.chatId, {
@@ -1022,12 +1021,15 @@ export function registerTelegramLifecycleRuntimeHooks({
     return true;
   };
   const startActiveTurnTypingLoop = (ctx: Pi.ExtensionContext): void => {
+    if (uiPromptActive) return;
     const turn = activeTurnRuntime.get();
     promptDispatchRuntime.startTypingLoop(ctx, turn?.chatId, {
       target: turn?.target,
     });
   };
   let observedAutomaticCompaction = false;
+  let agentWorkActive = false;
+  let terminalAssistantMessagePendingDelivery = false;
   const deferredAutomaticCompactionNotices: string[] = [];
   const sendCompactionNotice = async (text: string): Promise<void> => {
     const turn = activeTurnRuntime.get();
@@ -1094,6 +1096,9 @@ export function registerTelegramLifecycleRuntimeHooks({
       activityVerbosityRuntime?.reset();
       assistantOutputRuntime.stop();
       observedAutomaticCompaction = false;
+      agentWorkActive = false;
+      terminalAssistantMessagePendingDelivery = false;
+      uiPromptActive = false;
       deferredAutomaticCompactionNotices.length = 0;
       compactionObserver.onSessionShutdown();
       if (event.reason === "quit" && disconnectOnQuit) {
@@ -1116,7 +1121,7 @@ export function registerTelegramLifecycleRuntimeHooks({
       activityRuntime.onCompactionStart(Pi.getSessionCompactionReason(event));
       compactionObserver.onSessionBeforeCompact(event, ctx);
       if (shouldNotify) {
-        if (activeTurnRuntime.has()) {
+        if (terminalAssistantMessagePendingDelivery) {
           deferredAutomaticCompactionNotices.push(
             Commands.TELEGRAM_COMPACTION_STARTED_MARKDOWN,
           );
@@ -1135,10 +1140,7 @@ export function registerTelegramLifecycleRuntimeHooks({
       compactionObserver.onSessionCompact(event, ctx);
       if (observedAutomaticCompaction) {
         observedAutomaticCompaction = false;
-        if (
-          activeTurnRuntime.has() ||
-          deferredAutomaticCompactionNotices.length > 0
-        ) {
+        if (deferredAutomaticCompactionNotices.length > 0) {
           deferredAutomaticCompactionNotices.push(
             Commands.TELEGRAM_COMPACTION_COMPLETED_MARKDOWN,
           );
@@ -1149,8 +1151,27 @@ export function registerTelegramLifecycleRuntimeHooks({
         }
       }
     },
+    async onSessionCompactFailed(event, ctx) {
+      if (!isSessionContextActive(ctx)) return;
+      const shouldNotify = observedAutomaticCompaction;
+      const deferredNotices = deferredAutomaticCompactionNotices.splice(0);
+      const shouldDefer =
+        deferredNotices.length > 0 || terminalAssistantMessagePendingDelivery;
+      compactionObserver.onSessionCompactFailed(event, ctx);
+      if (!shouldNotify) return;
+      const notice = event.aborted
+        ? "**⚠️ Compaction cancelled.**"
+        : "**⚠️ Compaction failed.**";
+      if (shouldDefer) {
+        deferredAutomaticCompactionNotices.push(...deferredNotices, notice);
+      } else {
+        await sendCompactionNotice(notice);
+      }
+    },
     async onAgentStart(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
+      agentWorkActive = true;
+      terminalAssistantMessagePendingDelivery = false;
       await agentStartWithDedupReset(event, ctx);
       activityRuntime.onAgentStart(activeTurnRuntime.get()?.target);
       startAgentActivityTypingLoop(ctx);
@@ -1195,19 +1216,45 @@ export function registerTelegramLifecycleRuntimeHooks({
       }
       await messageActivityHooks.onMessageUpdate(event, ctx);
     },
+    onMessageEnd(event, ctx) {
+      if (!isSessionContextActive(ctx)) return;
+      terminalAssistantMessagePendingDelivery =
+        event.message.role === "assistant" &&
+        event.message.stopReason !== "toolUse" &&
+        event.message.stopReason !== "error" &&
+        event.message.stopReason !== "aborted";
+    },
+    onUiPromptStart(event, ctx) {
+      if (!isSessionContextActive(ctx)) return;
+      uiPromptActive = true;
+      typing.stop();
+      activityRuntime.onUiPromptStart(event.kind, event.title);
+      updateStatus(ctx);
+    },
+    onUiPromptEnd(_event, ctx) {
+      if (!isSessionContextActive(ctx)) return;
+      uiPromptActive = false;
+      activityRuntime.onUiPromptEnd();
+      if (agentWorkActive || lifecycle.isCompactionInProgress()) {
+        startAgentActivityTypingLoop(ctx);
+      }
+      updateStatus(ctx);
+    },
     async onAgentEnd(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
       activityRuntime.onAgentEnd();
       await agentLifecycleHooks.onAgentEnd(event, ctx);
+    },
+    async onAgentSettled(event, ctx) {
+      if (!isSessionContextActive(ctx)) return;
+      await agentLifecycleHooks.onAgentSettled(event, ctx);
       if (deferredAutomaticCompactionNotices.length > 0) {
         await waitForActiveTurnDelivery();
         if (!isSessionContextActive(ctx)) return;
         await flushDeferredAutomaticCompactionNotices();
       }
-    },
-    async onAgentSettled(event, ctx) {
-      if (!isSessionContextActive(ctx)) return;
-      await agentLifecycleHooks.onAgentSettled(event, ctx);
+      terminalAssistantMessagePendingDelivery = false;
+      agentWorkActive = false;
       activityRuntime.onAgentSettled();
       modelContextAvailabilityRuntime.reconcile();
     },

package/lib/bus-leader.ts

@@ -335,7 +335,7 @@ export function createTelegramBusInstanceLifecycleAnnouncement(input: {
 }): TelegramBusFollowerLifecycleAnnouncement {
   return {
     target: { ...input.target },
-    text: `📡 Instance <b>${formatTelegramBusInstanceLabel(input)}</b> ${input.state}.`,
+    text: `<b>📡 Instance <i>${formatTelegramBusInstanceLabel(input)}</i> ${input.state}.</b>`,
     parseMode: "HTML",
   };
 }

package/lib/config.ts

@@ -105,7 +105,6 @@ export interface TelegramConfig {
   assistant?: {
     draftPreviews?: boolean;
     rendering?: TelegramAssistantRenderingMode;
-    proactivePush?: boolean;
     activity?: TelegramActivityVerbosity;
     timeInjection?: TelegramTimeMode;
     /** @deprecated use activity */
@@ -454,10 +453,32 @@ function omitTelegramRootProfileFields(config: TelegramConfig): TelegramConfig {
   return sharedConfig;
 }
 
+function omitRetiredProactivePush(config: TelegramConfig): {
+  config: TelegramConfig;
+  changed: boolean;
+} {
+  const assistant = config.assistant as
+    | (NonNullable<TelegramConfig["assistant"]> & { proactivePush?: unknown })
+    | undefined;
+  if (!assistant || !Object.hasOwn(assistant, "proactivePush")) {
+    return { config, changed: false };
+  }
+  const { proactivePush: _proactivePush, ...remainingAssistant } = assistant;
+  const next = { ...config };
+  if (Object.keys(remainingAssistant).length > 0) {
+    next.assistant = remainingAssistant;
+  } else {
+    delete next.assistant;
+  }
+  return { config: next, changed: true };
+}
+
 export function normalizeTelegramDefaultProfileConfig(config: TelegramConfig): {
   config: TelegramConfig;
   changed: boolean;
 } {
+  const retiredProactivePush = omitRetiredProactivePush(config);
+  config = retiredProactivePush.config;
   const hasLegacyRootProfile = [
     "botToken",
     "botUsername",
@@ -465,7 +486,9 @@ export function normalizeTelegramDefaultProfileConfig(config: TelegramConfig): {
     "allowedUserId",
     "lastUpdateId",
   ].some((field) => Object.hasOwn(config, field));
-  if (!hasLegacyRootProfile) return { config, changed: false };
+  if (!hasLegacyRootProfile) {
+    return { config, changed: retiredProactivePush.changed };
+  }
   const canonicalProfile = config.profiles?.[TELEGRAM_DEFAULT_PROFILE_NAME];
   const legacyToken = config.botToken?.trim();
   if (Object.hasOwn(config, "botToken") && !legacyToken) {
@@ -712,27 +735,6 @@ export function createTelegramConfigStore(
   };
 }
 
-export function createTelegramProactivePushChecker(
-  configStore: Pick<TelegramConfigStore, "get">,
-): () => boolean {
-  return () => configStore.get().assistant?.proactivePush ?? true;
-}
-
-export function createTelegramProactivePushSetter(
-  configStore: TelegramMutableConfigStore,
-): (enabled: boolean) => Promise<void> {
-  return async (enabled) => {
-    await loadLatestTelegramConfig(configStore);
-    const current = configStore.get();
-    const config: TelegramConfig = {
-      ...current,
-      assistant: { ...current.assistant, proactivePush: enabled },
-    };
-    configStore.set(config);
-    await configStore.persist(config);
-  };
-}
-
 export function createTelegramDraftPreviewsChecker(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => boolean {
@@ -1019,8 +1021,6 @@ export function createTelegramConfigControls(
   configStore: TelegramMutableConfigStore,
 ) {
   return {
-    isProactivePushEnabled: createTelegramProactivePushChecker(configStore),
-    setProactivePushEnabled: createTelegramProactivePushSetter(configStore),
     areDraftPreviewsEnabled: createTelegramDraftPreviewsChecker(configStore),
     setDraftPreviewsEnabled: createTelegramDraftPreviewsSetter(configStore),
     getAssistantRenderingMode:

package/lib/inbound.ts

@@ -19,7 +19,7 @@ import { getTelegramVoiceTranscriptionProviders } from "./voice.ts";
 
 const DEFAULT_INBOUND_HANDLER_TIMEOUT_MS = 120_000;
 const INBOUND_HANDLER_REGISTRY_KEY = "__piTelegramInboundHandlers__";
-const MAX_INBOUND_HANDLER_OUTPUT_LENGTH = 12_000;
+const MAX_INBOUND_HANDLER_OUTPUT_LENGTH = 24_000;
 const MAX_INBOUND_HANDLER_FAILURE_STREAM_LENGTH = 4_000;
 
 type TelegramInboundCommandTemplateConfig =

package/lib/lifecycle.ts

@@ -16,13 +16,17 @@ import type {
   ExtensionAPI,
   ExtensionContext,
   InputEvent,
+  MessageEndEvent,
   SessionBeforeCompactEvent,
   SessionCompactEvent,
+  SessionCompactFailedEvent,
   SessionShutdownEvent,
   SessionStartEvent,
   ToolExecutionEndEvent,
   ToolExecutionStartEvent,
   ToolExecutionUpdateEvent,
+  UIPromptEndEvent,
+  UIPromptStartEvent,
 } from "./pi.ts";
 
 let resetTransportReplyDedupFn: (() => void) | undefined;
@@ -78,6 +82,10 @@ export interface TelegramLifecycleRegistrationDeps {
     event: SessionCompactEvent,
     ctx: ExtensionContext,
   ) => Promise<void> | void;
+  onSessionCompactFailed?: (
+    event: SessionCompactFailedEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void> | void;
   onBeforeAgentStart: (
     event: TelegramBeforeAgentStartEvent,
     ctx: ExtensionContext,
@@ -113,6 +121,18 @@ export interface TelegramLifecycleRegistrationDeps {
     },
     ctx: ExtensionContext,
   ) => Promise<void>;
+  onMessageEnd?: (
+    event: MessageEndEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void> | void;
+  onUiPromptStart?: (
+    event: UIPromptStartEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void> | void;
+  onUiPromptEnd?: (
+    event: UIPromptEndEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void> | void;
   onAgentEnd: (event: AgentEndEvent, ctx: ExtensionContext) => Promise<void>;
   onAgentSettled?: (
     event: AgentSettledEvent,
@@ -416,6 +436,10 @@ export interface TelegramCompactionObserverRuntime<TContext> {
     ctx: TContext,
   ) => void;
   onSessionCompact: (event: SessionCompactEvent, ctx: TContext) => void;
+  onSessionCompactFailed: (
+    event: SessionCompactFailedEvent,
+    ctx: TContext,
+  ) => void;
   onSessionShutdown: () => void;
 }
 
@@ -471,6 +495,16 @@ export function createTelegramCompactionObserverRuntime<TContext>(
       deps.updateStatus(ctx);
       requestDispatch();
     },
+    onSessionCompactFailed: (_event, ctx) => {
+      clearFallbackTimer();
+      if (deps.isContextActive && !deps.isContextActive(ctx)) return;
+      deps.setCompactionInProgress(false);
+      if (typingStartedByObserver) deps.stopTypingLoop?.();
+      typingStartedByObserver = false;
+      deps.updateStatus(ctx);
+      deps.onCompactionAbandoned?.();
+      requestDispatch();
+    },
     onSessionShutdown: () => {
       clearFallbackTimer();
       if (typingStartedByObserver) deps.stopTypingLoop?.();
@@ -590,6 +624,10 @@ export function registerTelegramLifecycleHooks(
     if (!isActive(ctx)) return;
     await deps.onSessionCompact?.(event, ctx);
   });
+  pi.on("session_compact_failed", async (event, ctx) => {
+    if (!isActive(ctx)) return;
+    await deps.onSessionCompactFailed?.(event, ctx);
+  });
   // The Pi SDK still types this result as a string; compatible runtimes may
   // preserve ordered system prompt blocks through the same public hook.
   const registerBeforeAgentStart = pi.on.bind(pi) as unknown as (
@@ -630,6 +668,18 @@ export function registerTelegramLifecycleHooks(
     if (!isActive(ctx)) return;
     await deps.onMessageUpdate(event, ctx);
   });
+  pi.on("message_end", async (event, ctx) => {
+    if (!isActive(ctx)) return;
+    await deps.onMessageEnd?.(event, ctx);
+  });
+  pi.on("ui_prompt_start", async (event, ctx) => {
+    if (!isActive(ctx)) return;
+    await deps.onUiPromptStart?.(event, ctx);
+  });
+  pi.on("ui_prompt_end", async (event, ctx) => {
+    if (!isActive(ctx)) return;
+    await deps.onUiPromptEnd?.(event, ctx);
+  });
   pi.on("agent_end", async (event, ctx) => {
     if (!isActive(ctx)) return;
     await deps.onAgentEnd(event, ctx);

package/lib/menu-settings.ts

@@ -21,7 +21,6 @@ import type { TelegramVoiceReplyMode } from "./voice.ts";
 export type TelegramSettingsMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 
 export interface TelegramSettingsStateDeps {
-  isProactivePushEnabled: () => boolean;
   areDraftPreviewsEnabled: () => boolean;
   getAssistantRenderingMode: () => TelegramAssistantRenderingMode;
   getActivityVerbosity: () => TelegramActivityVerbosity;
@@ -32,7 +31,6 @@ export interface TelegramSettingsStateDeps {
 }
 
 export interface TelegramSettingsMutationDeps extends TelegramSettingsStateDeps {
-  setProactivePushEnabled: (enabled: boolean) => Promise<void>;
   setDraftPreviewsEnabled: (enabled: boolean) => Promise<void>;
   setAssistantRenderingMode: (
     mode: TelegramAssistantRenderingMode,
@@ -139,7 +137,6 @@ export interface TelegramSettingsMenuRuntimeDeps<
 export const SETTINGS_MENU_TITLE = "<b>⚙️ Settings:</b>";
 export const AUTOMATIC_THREAD_CLEANUP_SETTINGS_TITLE =
   "<b>🧹 Thread cleanup:</b>";
-export const PROACTIVE_PUSH_SETTINGS_TITLE = "<b>📌 Proactive push:</b>";
 export const DRAFT_PREVIEWS_SETTINGS_TITLE = "<b>📝 Draft previews:</b>";
 export const ASSISTANT_RENDERING_SETTINGS_TITLE =
   "<b>🧾 Assistant rendering:</b>";
@@ -181,19 +178,6 @@ export function buildAutomaticThreadCleanupSettingsText(
   ].join("\n");
 }
 
-export function buildProactivePushSettingsText(
-  proactivePushEnabled: boolean,
-): string {
-  return [
-    `${PROACTIVE_PUSH_SETTINGS_TITLE} <code>${proactivePushEnabled ? "on" : "off"}</code>`,
-    "",
-    "Control whether public assistant output from local/autonomous work is projected to Telegram.",
-    "",
-    "<code>-</code> <code>on</code> (default): send each completed public block, including visible checkpoints and the final answer, while connected.",
-    "<code>-</code> <code>off</code>: keep local/autonomous assistant blocks in Pi; Telegram-originated replies still use their normal delivery path.",
-  ].join("\n");
-}
-
 export function buildDraftPreviewsSettingsText(enabled: boolean): string {
   return [
     `${DRAFT_PREVIEWS_SETTINGS_TITLE} <code>${enabled ? "on" : "off"}</code>`,
@@ -265,7 +249,6 @@ export function buildTimeInjectionModeSettingsText(
 }
 
 export function buildTelegramSettingsMenuReplyMarkup(
-  proactivePushEnabled: boolean,
   draftPreviewsEnabled: boolean,
   assistantRenderingModeOrVoiceReplyMode:
     TelegramAssistantRenderingMode | TelegramVoiceReplyMode,
@@ -325,10 +308,6 @@ export function buildTelegramSettingsMenuReplyMarkup(
       text: `🔬 Activity: ${activityVerbosity}`,
       callback_data: "settings:open:activity-verbosity",
     },
-    {
-      text: `📌 Proactive push: ${proactivePushEnabled ? "on" : "off"}`,
-      callback_data: "settings:open:proactive",
-    },
     {
       text: `🕒 Time injection: ${getTelegramSettingsStateValueLabel(timeInjectionMode)}`,
       callback_data: "settings:open:time-injection",
@@ -362,7 +341,6 @@ export async function openTelegramSettingsMenu<
     state,
     buildTelegramSettingsMenuText(),
     buildTelegramSettingsMenuReplyMarkup(
-      deps.isProactivePushEnabled(),
       deps.areDraftPreviewsEnabled(),
       deps.getAssistantRenderingMode(),
       deps.getVoiceReplyMode(),
@@ -399,26 +377,6 @@ export function buildAutomaticThreadCleanupSettingsReplyMarkup(
   };
 }
 
-export function buildProactivePushSettingsReplyMarkup(
-  proactivePushEnabled: boolean,
-): TelegramSettingsMenuReplyMarkup {
-  return {
-    inline_keyboard: [
-      [{ text: "⬆️ Back", callback_data: "settings:list" }],
-      [
-        {
-          text: proactivePushEnabled ? "🟢 On" : "⚫️ On",
-          callback_data: "settings:set:proactive:on",
-        },
-        {
-          text: proactivePushEnabled ? "⚫️ Off" : "🟡 Off",
-          callback_data: "settings:set:proactive:off",
-        },
-      ],
-    ],
-  };
-}
-
 export function buildDraftPreviewsSettingsReplyMarkup(
   enabled: boolean,
 ): TelegramSettingsMenuReplyMarkup {
@@ -521,7 +479,6 @@ export async function updateTelegramSettingsMenuMessage(
   await deps.updateSettingsMessage(
     buildTelegramSettingsMenuText(),
     buildTelegramSettingsMenuReplyMarkup(
-      deps.isProactivePushEnabled(),
       deps.areDraftPreviewsEnabled(),
       deps.getAssistantRenderingMode(),
       deps.getVoiceReplyMode(),
@@ -544,16 +501,6 @@ export async function updateAutomaticThreadCleanupSettingsMessage(
   );
 }
 
-export async function updateProactivePushSettingsMessage(
-  deps: TelegramSettingsMenuCallbackDeps,
-): Promise<void> {
-  const proactivePushEnabled = deps.isProactivePushEnabled();
-  await deps.updateSettingsMessage(
-    buildProactivePushSettingsText(proactivePushEnabled),
-    buildProactivePushSettingsReplyMarkup(proactivePushEnabled),
-  );
-}
-
 export async function updateDraftPreviewsSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
@@ -621,9 +568,16 @@ export async function handleTelegramSettingsMenuCallbackAction(
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
-  if (data === "settings:open:proactive") {
-    await updateProactivePushSettingsMessage(deps);
-    await deps.answerCallbackQuery(callbackQueryId);
+  if (
+    data === "settings:open:proactive" ||
+    data === "settings:set:proactive:on" ||
+    data === "settings:set:proactive:off"
+  ) {
+    await updateTelegramSettingsMenuMessage(deps, deps.sectionRegistry);
+    await deps.answerCallbackQuery(
+      callbackQueryId,
+      "Public assistant output is always delivered while Telegram is connected.",
+    );
     return true;
   }
   if (
@@ -751,19 +705,6 @@ export async function handleTelegramSettingsMenuCallbackAction(
     );
     return true;
   }
-  if (
-    data === "settings:set:proactive:on" ||
-    data === "settings:set:proactive:off"
-  ) {
-    const enabled = data.endsWith(":on");
-    await deps.setProactivePushEnabled(enabled);
-    await updateProactivePushSettingsMessage(deps);
-    await deps.answerCallbackQuery(
-      callbackQueryId,
-      `Proactive push ${enabled ? "enabled" : "disabled"}`,
-    );
-    return true;
-  }
   await deps.answerCallbackQuery(callbackQueryId);
   return true;
 }
@@ -781,7 +722,6 @@ export function createTelegramSettingsMenuRuntime<
       return openTelegramSettingsMenu(
         {
           getModelMenuState: () => deps.getModelMenuState(chatId, ctx),
-          isProactivePushEnabled: deps.isProactivePushEnabled,
           areDraftPreviewsEnabled: deps.areDraftPreviewsEnabled,
           getAssistantRenderingMode: deps.getAssistantRenderingMode,
           getActivityVerbosity: deps.getActivityVerbosity,
@@ -805,7 +745,6 @@ export function createTelegramSettingsMenuRuntime<
       await deps.reloadConfig?.();
       return updateTelegramSettingsMenuMessage(
         {
-          isProactivePushEnabled: deps.isProactivePushEnabled,
           areDraftPreviewsEnabled: deps.areDraftPreviewsEnabled,
           getAssistantRenderingMode: deps.getAssistantRenderingMode,
           getActivityVerbosity: deps.getActivityVerbosity,
@@ -849,7 +788,6 @@ export function createTelegramSettingsMenuRuntime<
         deps.storeModelMenuState(state);
       }
       return handleTelegramSettingsMenuCallbackAction(query.id, query.data, {
-        isProactivePushEnabled: deps.isProactivePushEnabled,
         areDraftPreviewsEnabled: deps.areDraftPreviewsEnabled,
         getAssistantRenderingMode: deps.getAssistantRenderingMode,
         getActivityVerbosity: deps.getActivityVerbosity,
@@ -857,7 +795,6 @@ export function createTelegramSettingsMenuRuntime<
         isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
         getTimeInjectionMode: deps.getTimeInjectionMode,
         isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
-        setProactivePushEnabled: deps.setProactivePushEnabled,
         setDraftPreviewsEnabled: deps.setDraftPreviewsEnabled,
         setAssistantRenderingMode: deps.setAssistantRenderingMode,
         setActivityVerbosity: deps.setActivityVerbosity,

package/lib/pi.ts

@@ -14,11 +14,14 @@ import {
   type ExtensionCommandContext,
   type ExtensionContext,
   type InputEvent,
+  type MessageEndEvent,
   type SessionBeforeCompactEvent,
   type SessionCompactEvent,
   type SessionShutdownEvent,
   type SessionStartEvent,
   type SlashCommandInfo,
+  type UIPromptEndEvent,
+  type UIPromptStartEvent,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 
@@ -32,13 +35,25 @@ export type {
   ExtensionCommandContext,
   ExtensionContext,
   InputEvent,
+  MessageEndEvent,
   SessionBeforeCompactEvent,
   SessionCompactEvent,
   SessionShutdownEvent,
   SessionStartEvent,
   SlashCommandInfo,
+  UIPromptEndEvent,
+  UIPromptStartEvent,
 };
 
+export interface SessionCompactFailedEvent {
+  type: "session_compact_failed";
+  reason: "manual" | "threshold" | "overflow";
+  errorMessage?: string;
+  aborted: boolean;
+  willRetry: boolean;
+  fromExtension: boolean;
+}
+
 export interface ToolExecutionStartEvent {
   type: "tool_execution_start";
   toolCallId: string;

package/lib/status.ts

@@ -14,6 +14,7 @@ export interface TelegramUsageStats {
   totalCacheRead: number;
   totalCacheWrite: number;
   totalCost: number;
+  latestCacheHitRate?: number;
 }
 
 interface TelegramUsageMessage {
@@ -1473,6 +1474,9 @@ function collectUsageStats(ctx: TelegramStatusContext): TelegramUsageStats {
     stats.totalCacheRead += usage.cacheRead;
     stats.totalCacheWrite += usage.cacheWrite;
     stats.totalCost += usage.cost.total;
+    const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+    stats.latestCacheHitRate =
+      promptTokens > 0 ? (usage.cacheRead / promptTokens) * 100 : undefined;
   }
   return stats;
 }
@@ -1494,6 +1498,12 @@ function buildUsageSummary(stats: TelegramUsageStats): string | undefined {
     tokenParts.push(`R${formatTokens(stats.totalCacheRead)}`);
   if (stats.totalCacheWrite)
     tokenParts.push(`W${formatTokens(stats.totalCacheWrite)}`);
+  if (
+    (stats.totalCacheRead > 0 || stats.totalCacheWrite > 0) &&
+    stats.latestCacheHitRate !== undefined
+  ) {
+    tokenParts.push(`CH${stats.latestCacheHitRate.toFixed(1)}%`);
+  }
   return tokenParts.length > 0 ? tokenParts.join(" ") : undefined;
 }
 
@@ -1549,7 +1559,7 @@ export function buildStatusHtml(
   const usageSummary = buildUsageSummary(stats);
   const costSummary = buildCostSummary(stats, usesSubscription);
   if (usageSummary) {
-    lines.push(buildStatusRow("Usage", usageSummary));
+    lines.push(buildStatusRow("Tokens", usageSummary));
   }
   if (costSummary) {
     lines.push(buildStatusRow("Cost", costSummary));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.39.5",
+  "version": "0.41.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -71,9 +71,9 @@
     "image": "https://raw.githubusercontent.com/llblab/pi-telegram/main/screenshot.png"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.80.6",
-    "@earendil-works/pi-ai": ">=0.80.6",
-    "@earendil-works/pi-coding-agent": ">=0.80.6",
+    "@earendil-works/pi-agent-core": ">=0.84.4",
+    "@earendil-works/pi-ai": ">=0.84.4",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
     "@sinclair/typebox": "*"
   },
   "devDependencies": {

package/skills/generated-control-surface/SKILL.md

@@ -136,11 +136,11 @@ Use the transport's canonical prompt-button syntax. For pi-telegram, one top-lev
 
 Model the control surface as an ordered ragged sequence of independently sized rows, not as a rectangular matrix to fill. Rectangular grids are one specialization for genuinely spatial or coordinate-bearing state; most interfaces should vary row width according to hierarchy, grouping, label pressure, and action priority.
 
-- Default to one full-width button per row for non-spatial controls. Put controls in one compact row only when they are genuine peers that answer the same local question or form one coherent toolbar/navigation group **and** their rendered labels comfortably fit a narrow phone-width chat.
+- Default to one full-width button per row for non-spatial controls. In pi-telegram matrix syntax, emit these vertical controls as top-level cells without wrapping them in a nested row array. A nested array explicitly opts into horizontal grouping and is justified only when the controls are genuine peers and every label is unmistakably compact—roughly no more than 15 visible characters including its emoji and space. This is a judgment heuristic, not a request to mechanically count characters: if fit is uncertain, wording is multi-phrase, or truncation is plausible, keep top-level vertical buttons.
 - Use a singleton full-width row for a structurally independent, pinned, primary, summary, or high-consequence action, and whenever label length makes horizontal grouping cramped or ambiguous.
 - Vary row widths intentionally—for example `1 → 2 → 4 → 1 → 2`—and never pad a row with empty, duplicate, or no-op controls merely to produce uniform dimensions.
 - Preserve reading order across rows: orientation and structural navigation first, primary content or choices next, secondary controls afterward, and destructive actions visibly separated when present.
-- Treat two columns as an earned compact mode, not the default: a pair normally fits when each label is no more than one emoji plus roughly two average-length words. If either label has more words, unusually long words, qualifiers, or likely wrapping, place each button on its own row. Use at most two columns for readable text labels; move additional peer choices into more semantic rows rather than compressing textual buttons across a phone-width line. Three through five columns are for short symbols, glyphs, coordinates, or compact codes whose position carries meaning. Six through eight may be used only for single-glyph or similarly minimal position-bearing labels whose grouping materially improves the interaction; a row of emoji-only controls may therefore legitimately use up to eight columns. Eight is the phone-width UX maximum: never generate a row of nine or more controls even though the parser has no artificial width cap. Never shorten necessary wording merely to increase row density; regroup or use full-width rows when labels need explanation, wrap ambiguously, or lose meaning without prose.
+- Treat two columns as an earned compact exception, never the default: a pair normally fits only when each label is unmistakably short—approximately one emoji plus one or two short words and roughly 15 visible characters or fewer. Do not count mechanically to justify density. If either label has more words, unusually long words, qualifiers, or any plausible wrapping or ellipsis risk, place each button on its own top-level row. Use at most two columns for readable text labels; move additional peer choices into more semantic rows rather than compressing textual buttons across a phone-width line. Three through five columns are for short symbols, glyphs, coordinates, or compact codes whose position carries meaning. Six through eight may be used only for single-glyph or similarly minimal position-bearing labels whose grouping materially improves the interaction; a row of emoji-only controls may therefore legitimately use up to eight columns. Eight is the phone-width UX maximum: never generate a row of nine or more controls even though the parser has no artificial width cap. Never shorten necessary wording merely to increase row density; regroup or use full-width rows when labels need explanation, wrap ambiguously, or lose meaning without prose.
 
 Treat vertical extent independently from horizontal density. A genuinely spatial surface may retain many rows—such as an `8×16` field—when vertical continuity, coordinates, and one-glance topology matter; do not paginate merely to make its height match its width. For non-spatial collections, however, a tall button wall should yield to semantic grouping, progressive disclosure, or pagination. Keep compact state and instructions above a tall surface, preserve stable coordinates across regeneration, and avoid repeating prose between rows.
 
@@ -187,7 +187,7 @@ Button prompts must:
 - Request fresh inspection when state may have changed.
 - Avoid embedding volatile output that should be rediscovered.
 
-Labels stay short, distinct, and scannable. Prefer an explicit `label` over exposing a long prompt as button text. Emoji are explicitly allowed and encouraged when one consistent semantic marker improves scanning or expressiveness; keep their meaning consistent across sibling controls, avoid decorative noise, and do not rely on emoji or color alone. If buttons are unavailable, render the same control surface as a numbered choice list.
+Labels stay short, distinct, and scannable. Prefer an explicit `label` over exposing a long prompt as button text. Every generated human-readable action label must start with the most semantically appropriate emoji, followed by one ASCII space and concise action text; selecting that emoji is a required design step, not optional polish. When label and prompt are intentionally identical, use the same emoji-prefixed value rather than dropping the marker through compact syntax. Keep emoji meaning consistent across sibling controls, avoid decorative noise, and do not rely on emoji or color alone. An emoji-free text label remains a transport-compatible fallback only when no honest semantic emoji can be identified after considering the action, domain, and state; convenience, label pressure, or uncertainty between several reasonable candidates is not sufficient. Genuine coordinates, established symbolic controls, and intentionally emoji-only spatial cells keep their domain grammar. If buttons are unavailable, render the same control surface as a numbered choice list.
 
 ## Capability Adapters
 
@@ -243,6 +243,8 @@ Before sending a surface, verify:
 - Complete versus filtered or adapted output is labeled honestly.
 - No secret appears in visible text or button payloads.
 - Every button carries a valid self-contained next intent and measurably shortens likely feedback.
+- Every human-readable action label uses `emoji + space + text`; an emoji-free fallback has an explicit semantic reason rather than mere convenience.
+- Non-spatial action buttons are top-level vertical cells by default; every nested row has an obvious compact-peer justification with no plausible truncation risk.
 - The surface preserves free-form feedback when choices are not exhaustive.
 - High-impact operations route through confirmation.
 - Back/Up and Refresh appear only when useful.