@llblab/pi-telegram 0.54.3 → 0.55.0

package/AGENTS.md

@@ -60,6 +60,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 ### 4.1 Flat Domain DAG
 
 - Cohesive domains live as flat `/lib/*.ts` modules whose local import graph is acyclic.
+- `In-memory lifecycles`: Use pure transitions and a domain-owned effect shell when competing asynchronous sources, generation/cancellation fencing or timers justify the pattern. The shared `machine` leaf owns runner mechanics only; state, events, effects and authority stay with the domain. Durable admission, custody, Workspace and IPC retain their transactional contracts.
 - `lib/extension.ts` constructs high-level runtimes and wires live ports. Domain policy, mutable state, sequencing, identity, retries, normalization, and lifecycle recovery belong to the owning `/lib` module.
 - During refactoring, add a domain only for demonstrated cross-domain reuse or a concrete dependency-direction/cycle problem. Prefer an existing cohesive owner; a closed helper cluster, independent tests or file length alone is insufficient. An acyclic validator result does not justify a new boundary. Do not atomize cohesive modules or create one-use wrappers merely to shrink `index.ts`.
 - `bindings` owns Pi-facing registration and narrow cross-domain assembly; it may connect established ports but must not absorb routing, rendering, transport, or mutable policy.
@@ -85,7 +86,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - Admission is journal-first: validate and persist the complete `getUpdates` response before one monotonic offset commit, then signal an independent worker without awaiting semantic execution. Missing cursor with a non-empty journal, malformed/foreign authority, or capacity exhaustion fails closed. “Durable” means process-crash recovery after atomic rename, not unflushed host/kernel/filesystem/device/power-loss survival.
 - Storage cutovers must reconcile actual consumer locations before correcting path adapters. Never normalize a relative historical reference into new authority or treat equal reference strings / empty canonical storage as source completeness. Exact-path preflight is lexical only; physical identity, historical coverage, writer closure and migration remain separate proofs.
 - Workspace mutations acquire cross-process admission before their shared process-local gate and hold it through asynchronous API work and durable settlement. Topic lifecycle, complete unbound/reroute target handling, manual disconnect, and session-restart cleanup use profile-wide scope; either retained retirement-fence phase rejects them before state access. Cleanup admission spans intent publication, target mutation, persistence, and successful transport release. Explicit manual disconnect may stop only its captured local transport after cleanup admission/effects fail; it must not bypass Thread mutation fences, release a replacement connection, claim unconfirmed deletion, or retry an uncertain stop. Session-restart cleanup retains its admission-required behavior. Detached reconciliation that mutates Thread state must reacquire fresh profile admission through the same gate; it cannot inherit a caller lease that ended before its timer runs. A live operation ID has one process-local caller: concurrent reuse is rejected before lease acquisition, while retry after the caller exits may resume exact durable authority.
-- Workspace retirement is capacity-pressure-only. Elapsed time and heartbeat silence never trigger deletion; only complete `A`–`Z` exhaustion may propose the oldest continuously proven inactive, fully unprotected binding. Exact deletion, durable retirement, and fence completion precede slot reuse. Authorized demand-driven rotation retries one failed fresh allocation after retirement; restore-only follower startup never evicts. Release ordinary registration/provisioning leases before acquiring the destructive fence, retain the shared mutation gate across retirement, and validate the exact permit immediately before one non-retried deletion. Persist an exact method/target-matched rejection before withdrawing its intent; release that fence only after durable withdrawal, retaining the binding. A later attempt requires fresh operation authority. Protection reads must never repair, quarantine, or reset journals. Non-destructive owner detachment must atomically retain one exact Workspace binding and its letter while removing only its uniquely matched owner record and stamping first inactivity; it never manufactures Thread-deletion evidence or clears accepted work. During authenticated follower registration, the exact Workspace claim owns the letter: a mismatched retained target record is repaired to that claim before binding commit, while any unrelated binding that owns the stale letter remains untouched. Retained prune observations are bounded, non-routing and registration/profile/epoch/runtime-fenced. One unfinished preservation operation retains its admission identity across fresh-PID-proof retries; it can never become deletion authority. Leader quit requires completed delivery/polling/worker teardown under the captured session generation, profile and epoch; reload/new/resume/fork never establish inactivity. Unknown deletion outcomes retain their fence; only confirmed durable completion permits reuse.
+- Workspace retirement is capacity-pressure-only. Elapsed time and heartbeat silence never trigger deletion; only complete `A`–`Z` exhaustion may propose the oldest continuously proven inactive, fully unprotected binding. Exact deletion, durable retirement, and fence completion precede slot reuse. Authorized demand-driven rotation retries one failed fresh allocation after retirement; restore-only follower startup never evicts. Release ordinary registration/provisioning leases before acquiring the destructive fence, retain the shared mutation gate across retirement, and validate the exact permit immediately before one non-retried deletion. Persist an exact method/target-matched rejection before withdrawing its intent; release that fence only after durable withdrawal, retaining the binding. A later attempt requires fresh operation authority. Protection reads must never repair, quarantine, or reset journals. Non-destructive owner detachment must atomically retain one exact Workspace binding and its letter while removing only its uniquely matched owner record and stamping first inactivity; it never manufactures Thread-deletion evidence or clears accepted work. During authenticated follower registration, a mismatched retained target record is repaired to the exact Workspace claim before binding commit; if same-target commit adopts the retained binding's slot, its returned binding then owns the registration result and owner-record slot. Unrelated bindings that own a stale or provisional letter remain untouched. Same-target re-keying retains historical journal keys and exact source tuples without upgrading unknown completeness. Retained prune observations are bounded, non-routing and registration/profile/epoch/runtime-fenced. One unfinished preservation operation retains its admission identity across fresh-PID-proof retries; it can never become deletion authority. Leader quit requires completed delivery/polling/worker teardown under the captured session generation, profile and epoch; reload/new/resume/fork never establish inactivity. Unknown deletion outcomes retain their fence; only confirmed durable completion permits reuse.
 - Foreign forwarding settles as `accepted`, `retryable`, or `terminal-rejected`. Only an authenticated acknowledgement carrying the expected `deliveryId` and `sourceUpdateId` releases leader journal authority. Negative, missing, stale, mismatched, or capacity-failed settlement remains durable; callback error answers are side effects only. Exception: the operator-approved fixed chooser deadline may discard its exact unclaimed donor pending source without a body archive or delivery-success claim. Accepted recipient queue/work and bound Threads are untouched; old donor controls and late reports cannot replay it. The lifetime and temporary cleanup contract lives in `docs/architecture.md`.
 - A forwarding delivery id is stable across registration replacement and derives from envelope kind, source `update_id`, and stable recipient binding. Runtime instance and registration generation remain separate attempt fences. Persisted message ownership carries the stable binding so replay can rebind only to its current authenticated registration.
 - A queued receipt persists its acquiring runtime instance, OS pid/process-birth identity, session generation, acquisition id, and acquisition time. Only exact authority may settle or discard it. Cached presence is not current execution proof: prepared custody must revalidate the exact queued owner/group without recovery and refuse offers or uncertain reads. Completion requires an exact removal acknowledgement, never merely `!ready`; a retained acknowledgement permits local cleanup only, not replay. Same-process session replacement may reconstruct the claim and the original process may settle after transport ownership moves; a foreign process may neither replay nor settle it through generic removal or a copied acquisition id.
@@ -102,8 +103,9 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - `/stop`, `/abort`, `/next`, and `/continue` respectively reset+abort, abort while preserving queue, force the next turn, and enqueue a control-lane continuation. A negative reaction to an original standalone `/continue` settles and removes only its exact waiting source-addressed continuation; positive reactions do not change its control lane. Protect the Pi-owned pending head and already-started work, preserve other queue positions, and never address synthetic model continuations by their reply anchor. Settlement failure retains the continuation. Abort-history folding applies only to Telegram-owned active turns. A busy `/next` marks only its exact active Telegram turn: terminal abort settlement attempts one explicit abort notice before the exact selected queued prompt receives its dispatch notice. Notice failure is diagnostic and cannot block dispatch; a later `/abort` or `/stop` cancels both pending transition notices before taking ownership. Target command adapters must forward these transition ports. A successful dispatch notice keeps the queued prompt's one reply-header claim across agent start, so later messages in that turn never repeat it.
 - A model selection from an authorized Telegram target may stop and continue any interruptible active agent run in that same Pi session, including local/TUI work. Queue the synthetic control-lane continuation before aborting; when no Telegram prompt owns the run, bind continuation and reply ownership to the exact model-menu chat/Thread/message. Delay abort until every active tool execution settles, and clear both selection and fallback target on cancellation, agent start, settlement, or session replacement.
 - 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.
+- In Threaded Mode, All is service/input-only. New output, previews, typing and routing UI require a concrete Thread; neither implicit fallback nor explicit aggregate delivery may write to All. Unavailable routing authority retains input without an All notice or silent settlement. Classic DM and explicit channel/business destinations remain separate; historical All output is not auto-cleaned.
 - 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. Before Telegram preview or final delivery, strip every assistant-authored HTML comment regardless of Markdown position while keeping action activation top-level-only; a comment-only result sends no text message. Preserve literal code outside comments 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. Turns that already answer as one atomic reply (voice replies, Guest Mode queries) never stream previews.
+- `preview` owns streaming lifecycle only, not assistant rendering. Finalization waits for the captured generation's preceding preview work, never later drafts blocked by that publication, and must not issue pre/post-final draft-clear calls that create transient Telegram draft UI. Reset/invalidation detaches predecessor dependencies; late settlements cannot mutate replacement state. Turns that already answer as one atomic reply (voice replies, Guest Mode queries) never stream previews.
 - 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. Compaction may stop only a typing loop it actually started; it must preserve a pre-existing agent-owned loop. Refresh only the assigned Thread on a conservative three-second cadence; do not mirror typing to aggregate `All` and multiply shared-chat flood pressure. Typing is best-effort presence only: a failed exact-target action remains a structured diagnostic and must not replace a healthy connected/leader/follower status with `error`. 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.
 - Thread display defaults to the profile-scoped Letters strategy, with Names, Directory Snake, and Directory Title as the other automatic choices; Names projects the generated dictionary name for the slot. Unsupported retained display keys resolve to Letters without rewriting persisted configuration. A durable manual Thread display name retained on its Workspace binding overrides any automatic projection until exact reset; keep generated/recovery identity separate from manual and acknowledged display fields. After leader startup, automatic display contraction waits one follower-staleness window so election and follower re-registration cannot briefly remove and restore an acknowledged same-cwd suffix; stop/start generation cancels stale reconciliation. UI labels, emoji semantics, navigation, settings controls, callback namespaces, voice behavior, command templates, and assistant markup follow the linked `/docs` contracts. Generated human-readable action labels use `emoji + space + text`; emoji-free action text is only a reasoned no-semantic-marker fallback. State/value controls follow the [button control hierarchy](./docs/ui-style.md#button-control-hierarchy), not the action-label grammar. 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.

package/BACKLOG.md

@@ -2,4 +2,4 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
-No open work.
+No open tasks.

package/CHANGELOG.md

@@ -4,6 +4,27 @@
 
 ## Unreleased
 
+## 0.55.0: Native Restore and fenced lifecycles
+
+- `Restore cleanup`: Live Restore binds the new tab and decides old-tab cleanup before native leader/follower inputs run. Protected work defers cleanup; session replacement carries no deletion grant, and unknown deletion never repeats. Follower execution targets the rebound tab without rewriting journal originals or quoting the former tab. Exact donor ACKs seal routing clocks and retire the menu. Reader/execution capabilities, source custody and detached replies stay separate; busy hints coalesce.
+- `Runtime state`: In-memory lifecycles now use isolated pure TypeScript transitions and domain-owned effect shells. A shared leaf runner drives preview, typing, model switching, grouped input, compaction and follower recovery without adding a runtime dependency; durable admission, custody, Workspace and IPC retain their existing transactional owners.
+- `Preview ordering`: A publication waits only for its preceding draft and publications, never a later draft that waits for it. New turns and sessions detach old preview dependencies, and late draft, timer or publication settlements cannot unblock or overwrite replacement work. Final replies still drain their own issued draft without post-final clearing.
+- `Model switching`: Restarting or clearing a switch now consumes its staged model and continuation together, preventing an old tool settlement from aborting the continuation again. Synchronous nested controller calls retain the outer continuation context and abort handler.
+- `Grouped input`: Albums and split text share one fenced pending-group lifecycle. Separate text batches end at a message identity rather than a mutable count, and a synchronous dispatcher failure retains the input and schedules retry instead of leaving the group permanently dispatching.
+- `Typing ownership`: Queue dispatch preserves its exact Thread; Threaded Mode refuses missing targets and stops Classic chat-only loops on mode changes. Context/generation and loop-owner fences guard starts, queued HTTP/IPC issuance, ticks and awaited lifecycle continuations without letting stale work claim replacement typing. Typing never replays HTTP or transport fallback after failure; follower callbacks stay local. Compaction retains its own loop and preserves agent-owned activity.
+- `Reconnect lifecycle`: Follower startup restores its exact session's retained Thread after proving the former runtime PID absent and no registered peer owns it; live/unknown predecessors stay protected. Connect notices use acknowledged display titles, not provisional generated names. Manual Connect/Restore retain prepared context, read-only checks, committed slots and journal history. Stale recovery cannot change a replacement connection; stopped leader startup cannot poll or publish its endpoint.
+- `Thread surfaces`: All is input-only: sends, drafts, media, forwards and activity require a concrete Thread; implicit fallback and aggregate output are refused. Routing failures retain input, not All notices. Voice/files/albums enter one routing tab. Exact Linux/macOS home displays as Home/home with normal suffixes; manual names and other modes stay unchanged. Restore publishes acknowledged titles to heartbeat/TUI without changing generated identity; late old-target title ACKs are ignored.
+
+## 0.54.4: Restored tabs take their Pi's name
+
+- `Restore title`: Restoring a Pi into a routing tab ("move Pi into this tab") now renames the tab to that Pi's Thread display title, as Workspace Restore already did; previously a live-rebind Restore left the tab named `🚦 Routing`. A failed rename is recorded and never blocks the Restore.
+- `Native routing tabs`: An `All` input now also adopts a generically named native tab (desktop `New Chat`) that its client created immediately before it, not only a tab named after the input (mobile). Desktop and Android clients, with user topic creation allowed or not, each end with exactly one routing tab; a client's own brief native name before the rename cannot be prevented.
+- `Reclaimed leader tab`: When the leader's own tab is gone (for example after deleting every tab) and a new tab from `All` is reclaimed for it, the leader's Workspace binding now moves to that tab with its slot and name instead of gaining a second slot, and the tab is renamed to its display title instead of staying `New Chat`. Restore and labels no longer point at the deleted tab.
+- `Display titles`: A Thread whose tab has no acknowledged title yet (fresh, moved or reclaimed) now shows its display-mode title, such as the directory title, in the Restore menu and after Restore, instead of falling back to its generated slot name.
+- `One-shot routing menus`: Every final routing choice now deletes its menu. A live-rebind Restore left the chooser in the tab, a Workspace Restore kept it until old-Thread cleanup, which may never come, and Cancel replaced it with a notice. A restored tab stays as the Pi's Thread; a routing tab with nothing left to route is still removed. A delivered Workspace Restore answers `Restored`, not `Restore unconfirmed`, and the Restore submenu now reads `🔁 Restore a Pi into this tab:`.
+- `Restore history`: An input sent from `All` now moves into the routing tab opened for it, on desktop and mobile alike: the tab starts with a silent forward of the input, its menu replies to it, and the original leaves `All` once the copy is confirmed. A Thread restored into that tab keeps the prompt it answers instead of losing it, since the Bot API files such inputs in `All` even when mobile first draws them in the tab.
+- `Old tab cleanup`: After a live-rebind Restore, the old tab is deleted right after Pi finishes answering the moved input, instead of at the next paced retry, which could add up to about 30 seconds and later a full minute. Cleanup still waits for an idle session; a settled agent only wakes the waiting retry early.
+
 ## 0.54.3: One routing tab on mobile
 
 - `Mobile routing tab`: Sending a command or prompt from `All` in mobile Telegram no longer leaves an extra tab named after the input. The mobile client creates that native tab itself before delivering the input to `All`; the bridge now adopts it as the routing tab and renames it, instead of creating a second tab beside it. Desktop behavior is unchanged.

package/README.md

@@ -143,7 +143,7 @@ Enable the optional capabilities the bridge needs in the [@BotFather](https://t.
 | Generative Apps | Install or explicitly replace a reviewed `.mjs` application whose generated JSON button view may mix direct `app::method` actions with ordinary model prompts. | Repeated games, controls, tutors, and adapters compile routine interaction without losing selective model interpretation, explanation, or adaptation. |
 | Callback routing | Route known callbacks to the owner extension and unknown callbacks back into Pi. | Companion extensions can build UI without polling Telegram themselves. |
 | Threaded Mode | Run one leader plus visible follower Pi instances through named private-chat threads. | One bot can host a local multi-instance Pi organism without hidden process spawning. |
-| Reroute and restore | Give unknown and command-created temporary threads explicit forward and replace/restore choices. | Forward removes the temporary tab; restore rebinds it and may remove only the replaced old tab after positive cleanup proofs. Blocked cleanup preserves the relocation and protected work. |
+| Reroute and restore | Give text, voice, files and albums sent from `All`, plus unknown threads, explicit reroute and replace/restore choices. | Forward removes the temporary tab; restore rebinds it and may remove only the replaced old tab after positive cleanup proofs. Blocked cleanup preserves the relocation and protected work. |
 | Extension sections | Add menu sections, commands, status rows, settings, callbacks, and delivery helpers from companion extensions. | `pi-telegram` becomes a platform surface for other Pi extensions. |
 | Runtime diagnostics | Use `/telegram-status` and recent runtime events for connection, role, negotiated bus protocol/build/capabilities, separate polling and inbound-worker progress, journal depth, local/foreign queue ownership, automatic retry waits, transport, and failures. | Compatible build skew, foreign semantic authority, a healthy poller, durable backoff and an infrastructure-blocked worker remain distinguishable without hidden logs. |
 | Safety and ownership | Pair one owner, lock transport, scope targets, and reject fake terminal behavior. | Remote access remains explicit, bounded, and understandable. |
@@ -196,6 +196,8 @@ Named profile identifiers contain only lowercase ASCII letters and digits (maxim
 
 ## Main Surfaces
 
+In Threaded Mode, `All` is input-only: messages enter temporary routing tabs, and Pi replies stay in bound Threads. Missing routing or delivery targets fail closed instead of sending fallback messages to All. There is no automatic cleanup of old All output. Classic DM behavior is unchanged.
+
 ### Operator Menu
 
 `/start` opens the Telegram-native control panel: status, prompt-template commands, model selection, thinking level, settings, queue controls, and extension sections. It is the primary Telegram UI; reaction shortcuts are secondary queue affordances.
@@ -248,14 +250,14 @@ Classic private DM mode is the base product mode. When Telegram private-chat Thr
 - When all `A`–`Z` slots are reserved, a new connection may reclaim the oldest inactive, unprotected Thread. **This deletes that Thread and all its messages**, not Pi session history or project files. Active or protected work blocks reclamation; restoring a remembered session does not evict another binding.
 - Telegram never launches hidden Pi processes.
 
-In Threaded Mode, open Settings → **🧵 Thread display** to choose `letters` (default), `names`, `directory-title`, or `directory-snake` for this bot profile; a retained **directories** value remains available as an unchanged legacy presentation. Fresh tabs are created with the active mode's title instead of being visibly renamed afterward. Telegram tab titles, Pi terminal status, live Thread choosers/notices, prompt attribution, and named `telegram_message` targeting use the same acknowledged display name; target IDs and live registrations still own routing. Names shows the generated dictionary name chosen for the slot, such as `Anchor` for slot `A`; the directory formats produce `api_tools` or `Api Tools` and append `_a` or ` A` only while two or more authenticated live instances share that exact directory. Dormant retained bindings do not keep those suffixes visible. After leader election, automatic title contraction waits one follower-staleness window for live registrations to settle, avoiding a temporary suffix removal and restoration during startup. `/name` sets a manual Thread display name; **Reset to automatic** restores the selected automatic projection. Switching preserves Thread IDs, slots, generated recovery identity, and queue ownership. Partial application reports an error and can be retried without recreating Threads.
+In Threaded Mode, open Settings → **🧵 Thread display** to choose `letters` (default), `names`, `directory-title`, or `directory-snake` for this bot profile. Unsupported retained values, including the retired `directories` mode, fall back to `letters` without rewriting the saved configuration. Fresh tabs are created with the active mode's title instead of being visibly renamed afterward. Telegram tab titles, Pi terminal status, live Thread choosers/notices, prompt attribution, and named `telegram_message` targeting use the same acknowledged display name; target IDs and live registrations still own routing. Names shows the generated dictionary name chosen for the slot, such as `Anchor` for slot `A`; the directory formats produce `api_tools` or `Api Tools` and append `_a` or ` A` only while two or more authenticated live instances share that exact directory. On Linux/macOS, the current user's exact home directory displays as `home` or `Home`; subdirectories keep their own names, and Windows remains unchanged. Dormant retained bindings do not keep those suffixes visible. After leader election, automatic title contraction waits one follower-staleness window for live registrations to settle, avoiding a temporary suffix removal and restoration during startup. `/name` sets a manual Thread display name; **Reset to automatic** restores the selected automatic projection. Switching preserves Thread IDs, slots, generated recovery identity, and queue ownership. Partial application reports an error and can be retried without recreating Threads.
 
 | Mode | Best for | Runtime shape |
 | --- | --- | --- |
 | Classic DM | One running Pi instance and its active session controlled from one private bot chat | One polling owner, one queue/runtime surface |
 | Threaded Mode | Several visible Pi sessions sharing one bot | One leader owns transport; each private-chat Thread retains one session-qualified Workspace binding |
 
-**Live rebinding (0.53.0):** Restore uses one same-session save/apply/release channel for prompts and supported commands/templates, with separately fenced best-effort old-Thread cleanup. Existing work and exact source/receipt custody remain protected; legacy Restore readers/receivers retain continuity with older instances. Windows runs the same paths, and CI covers it. See [Multi-Instance Bus](./docs/multi-instance-bus.md#live-rebind-channel).
+**Live rebinding:** Restore confirms the new binding, makes one old-tab cleanup decision, then releases the saved input through its native prompt, command or template owner. Negotiated followers use the same order without another queue. Earlier protected work defers cleanup; `/new` cannot carry an old-session deletion grant into its replacement. An unknown delete never repeats or blocks ordinary input on the confirmed new tab. Exact source/receipt custody remains separate from replies and model completion. Upgrade participating readers for the new metadata; older peers retain their supported legacy path. See [Multi-Instance Bus](./docs/multi-instance-bus.md#live-rebind-channel).
 
 ## Environment Configuration
 

package/dist/lib/activity.d.ts

@@ -101,11 +101,13 @@ export interface TelegramActivityDispatcher {
 }
 /** @internal */
 export declare function createTelegramActivityDispatcher(deps?: {
+    captureDrain?: () => (() => void) | undefined;
     recordFailure?: (handlerId: string, event: TelegramActivityEvent, error: unknown) => void;
 }): TelegramActivityDispatcher;
 /** @internal */
 export declare function createTelegramActivityBridgeRuntime(deps: {
     generation: string;
+    captureDrain?: () => (() => void) | undefined;
     observeEvent?: (event: TelegramActivityEvent) => void;
     recordFailure?: (handlerId: string, event: TelegramActivityEvent, error: unknown) => void;
     now?: () => number;
@@ -207,7 +209,9 @@ export interface TelegramActivityPublicationRuntime {
     hasUnconfirmed: () => boolean;
     reset: () => void;
 }
-export declare function createTelegramActivityPublicationRuntime(): TelegramActivityPublicationRuntime;
+export declare function createTelegramActivityPublicationRuntime(deps?: {
+    captureDrain?: () => (() => void) | undefined;
+}): TelegramActivityPublicationRuntime;
 export interface TelegramAssistantOutputRuntime {
     start: () => void;
     beginTurn: () => void;

package/dist/lib/activity.js

@@ -116,10 +116,28 @@ function coalesceActivityEvents(previous, next) {
     }
     return next;
 }
+/** Optional observation must not change queue/transport settlement. */
+function captureActivityDrainObserver(capture) {
+    try {
+        const notify = capture?.();
+        return () => {
+            try {
+                const emitted = notify?.();
+                if (emitted)
+                    void Promise.resolve(emitted).catch(() => undefined);
+            }
+            catch { /* Observer failure is inert. */ }
+        };
+    }
+    catch {
+        return () => { };
+    }
+}
 /** @internal */
 export function createTelegramActivityDispatcher(deps = {}) {
     const queues = new Map();
     let stopped = false;
+    const hasPending = () => Array.from(queues.values()).some(queue => queue.active && (queue.running || queue.events.length > 0));
     const drain = async (queue) => {
         if (queue.running || !queue.active)
             return;
@@ -146,10 +164,12 @@ export function createTelegramActivityDispatcher(deps = {}) {
         }
         finally {
             queue.running = false;
+            if (!stopped && !hasPending())
+                queue.notifyDrained?.();
         }
     };
     return {
-        hasPending: () => Array.from(queues.values()).some((queue) => queue.active && (queue.running || queue.events.length > 0)),
+        hasPending,
         dispatch(event) {
             if (stopped)
                 return;
@@ -164,6 +184,8 @@ export function createTelegramActivityDispatcher(deps = {}) {
                     };
                     queues.set(registration.id, queue);
                 }
+                if (!queue.running && queue.events.length === 0)
+                    queue.notifyDrained = captureActivityDrainObserver(deps.captureDrain);
                 const previous = queue.events.at(-1);
                 if (previous && canCoalesceActivityEvents(previous, event)) {
                     queue.events[queue.events.length - 1] = coalesceActivityEvents(previous, event);
@@ -198,6 +220,7 @@ export function createTelegramActivityBridgeRuntime(deps) {
             runtime = createTelegramActivityRuntime({
                 generation: `${deps.generation}:${++generationSequence}`,
                 dispatcher: createTelegramActivityDispatcher({
+                    captureDrain: deps.captureDrain,
                     recordFailure: deps.recordFailure,
                 }),
                 observeEvent: deps.observeEvent,
@@ -470,13 +493,14 @@ export function createTelegramActivityRuntime(deps) {
         },
     };
 }
-export function createTelegramActivityPublicationRuntime() {
+export function createTelegramActivityPublicationRuntime(deps = {}) {
     let generation = 0;
     let tail = Promise.resolve();
     let outstanding = 0, unconfirmed = false;
     const pending = new Set();
     const reserve = () => {
         const admittedGeneration = generation;
+        const notifyDrained = captureActivityDrainObserver(deps.captureDrain);
         let state = "pending";
         let resolve;
         const ready = new Promise((accept) => {
@@ -499,6 +523,8 @@ export function createTelegramActivityPublicationRuntime() {
         })
             .finally(() => {
             outstanding -= 1;
+            if (admittedGeneration === generation && outstanding === 0 && !unconfirmed)
+                notifyDrained();
         });
         tail = result.catch(() => { });
         return {
@@ -522,6 +548,7 @@ export function createTelegramActivityPublicationRuntime() {
         hasUnconfirmed: () => unconfirmed,
         beginWork() {
             const admittedGeneration = generation;
+            const notifyDrained = captureActivityDrainObserver(deps.captureDrain);
             let settled = false;
             outstanding += 1;
             return {
@@ -532,6 +559,8 @@ export function createTelegramActivityPublicationRuntime() {
                     outstanding -= 1;
                     if (outcome === "unconfirmed" && admittedGeneration === generation)
                         unconfirmed = true;
+                    if (admittedGeneration === generation && outstanding === 0 && !unconfirmed)
+                        notifyDrained();
                 },
             };
         },

package/dist/lib/bindings.d.ts

@@ -177,6 +177,7 @@ export interface TelegramActivityBindingRuntime {
 /** Compose public activity fanout, verbosity, and assistant output ordering. */
 export declare function createTelegramActivityBindingRuntime<TTransportStamp>(deps: {
     generation: string;
+    captureDrain?: () => (() => void) | undefined;
     assistantOutput: Omit<Parameters<typeof createTelegramAssistantOutputBindingRuntime<TTransportStamp>>[0], "waitForActivityIdle" | "enqueue">;
     activityVerbosity: Omit<Parameters<typeof ActivityVerbosity.createTelegramActivityVerbosityRuntime<TelegramAssistantOutputAuthority<TTransportStamp>>>[0], "captureAuthority" | "isAuthorityActive" | "recordFailure" | "enqueue">;
 }): TelegramActivityBindingRuntime;
@@ -288,9 +289,12 @@ interface TelegramLifecycleBindingDeps {
     }) => void;
     canSendAgentActivity: (ctx: Pi.ExtensionContext) => boolean;
     isSessionContextActive: (ctx: Pi.ExtensionContext) => boolean;
+    getSessionGeneration?: () => number;
     isTurnTransportActive?: (turn: Queue.PendingTelegramTurn) => boolean;
     updateStatus: TelegramBridgeStatusUpdater;
     recordRuntimeEvent: TelegramRuntimeEventRecorder;
+    /** Settled-session hint for owners that wait on agent idleness, such as old-tab cleanup after a live rebind. */
+    onSessionSettled?: (ctx: Pi.ExtensionContext) => void;
 }
-export declare function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive, isTurnTransportActive, updateStatus, recordRuntimeEvent, }: TelegramLifecycleBindingDeps): void;
+export declare function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive, getSessionGeneration, isTurnTransportActive, updateStatus, recordRuntimeEvent, onSessionSettled, }: TelegramLifecycleBindingDeps): void;
 export {};

package/dist/lib/bindings.js

@@ -354,7 +354,7 @@ export function createTelegramAssistantOutputBindingRuntime(deps) {
 }
 /** Compose public activity fanout, verbosity, and assistant output ordering. */
 export function createTelegramActivityBindingRuntime(deps) {
-    const publication = Activity.createTelegramActivityPublicationRuntime();
+    const publication = Activity.createTelegramActivityPublicationRuntime({ captureDrain: deps.captureDrain });
     const assistantOutputBinding = createTelegramAssistantOutputBindingRuntime({
         ...deps.assistantOutput,
         enqueue: publication.enqueue,
@@ -374,6 +374,7 @@ export function createTelegramActivityBindingRuntime(deps) {
     });
     const activityRuntime = Activity.createTelegramActivityBridgeRuntime({
         generation: deps.generation,
+        captureDrain: deps.captureDrain,
         observeEvent(event) {
             assistantOutputBinding.observeEvent(event);
             activityVerbosityRuntime.accept(event);
@@ -626,7 +627,7 @@ export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, pe
         },
     });
 }
-export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive = () => true, isTurnTransportActive, updateStatus, recordRuntimeEvent, }) {
+export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, diagnostics, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive = () => true, getSessionGeneration, isTurnTransportActive, updateStatus, recordRuntimeEvent, onSessionSettled, }) {
     const agentEndResetter = Runtime.createTelegramAgentEndResetter({
         abort,
         typing,
@@ -864,6 +865,8 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
     });
     const messageActivityTypingHooks = Lifecycle.createTelegramMessageActivityTypingHooks({
         hasActiveTurn: activeTurnRuntime.has,
+        isContextActive: isSessionContextActive,
+        getSessionGeneration,
         startTypingLoop: startActiveTurnTypingLoop,
         onMessageStart: previewRuntime.onMessageStart,
         onMessageUpdate: previewRuntime.onMessageUpdate,
@@ -955,9 +958,12 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
         async onAgentStart(event, ctx) {
             if (!isSessionContextActive(ctx))
                 return;
+            const generation = getSessionGeneration?.();
             agentWorkActive = true;
             cancelPendingFinalPublication();
             await agentStartWithDedupReset(event, ctx);
+            if (!isSessionContextActive(ctx) || (getSessionGeneration && !Object.is(getSessionGeneration(), generation)))
+                return;
             const turn = activeTurnRuntime.get();
             activityRuntime.onAgentStart(turn?.target, turn?.replyToMessageId);
             startAgentActivityTypingLoop(ctx);
@@ -1077,6 +1083,7 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
             agentWorkActive = false;
             activityRuntime.onAgentSettled();
             modelContextAvailabilityRuntime.reconcile();
+            onSessionSettled?.(ctx);
         },
         onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({
             reconcileAvailability: modelContextAvailabilityRuntime.reconcile,

package/dist/lib/bus-api.d.ts

@@ -4,8 +4,8 @@
  * Wraps the direct Telegram Bot API runtime so follower instances can route outbound calls through the bus leader
  */
 import { type TelegramBusSelectedMenuDeliveryObservation, type TelegramBusSelectedMenuTextEffect } from "./bus.ts";
-import type { TelegramBridgeApiRuntime } from "./telegram-api.ts";
-export type TelegramBusApiCall = (method: string, args: unknown[]) => Promise<unknown>;
+import type { TelegramApiCallOptions, TelegramBridgeApiRuntime } from "./telegram-api.ts";
+export type TelegramBusApiCall = (method: string, args: unknown[], localOptions?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<unknown>;
 export interface TelegramBusAwareApiRuntimeDeps {
     directRuntime: TelegramBridgeApiRuntime;
     ownsDirect: () => boolean;

package/dist/lib/bus-api.js

@@ -4,7 +4,7 @@
  * Wraps the direct Telegram Bot API runtime so follower instances can route outbound calls through the bus leader
  */
 import { markTelegramBusCrossTargetDelivery, parseTelegramBusSelectedMenuTextEffect, stripTelegramBusApiMetadata, } from "./bus.js";
-import { buildTelegramAnswerGuestQueryBody, isTelegramApiCommitUnknownError, isTelegramMessageNotModifiedError, TelegramApiAuthorityError, TelegramApiCommitUnknownError, } from "./telegram-api.js";
+import { buildTelegramAnswerGuestQueryBody, assertTelegramApiCallAuthority, isTelegramApiCommitUnknownError, isTelegramMessageNotModifiedError, TelegramApiAuthorityError, TelegramApiCommitUnknownError, } from "./telegram-api.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -142,6 +142,7 @@ export function createTelegramSelectedMenuTextApi(deps) {
 }
 /** Followers route every chat action through the leader's generic `sendChatAction` call. */
 function sendTelegramFollowerChatAction(deps, chatId, action, options) {
+    assertTelegramApiCallAuthority(options?.assertAuthority, false);
     const body = withDefaultThreadTarget({
         chat_id: chatId,
         action,
@@ -149,7 +150,11 @@ function sendTelegramFollowerChatAction(deps, chatId, action, options) {
             ? { message_thread_id: options.message_thread_id }
             : {}),
     }, deps.getDefaultTarget?.());
-    return deps.callFollowerApi("call", ["sendChatAction", body]).then(asBoolean);
+    // Only plain single-attempt policy crosses IPC; the captured assertion is a local issuance fence.
+    const args = ["sendChatAction", body, ...(action === "typing"
+            ? [{ maxAttempts: 1, retrySafety: "non-idempotent" }] : [])];
+    return deps.callFollowerApi("call", args, options?.assertAuthority
+        ? { assertAuthority: options.assertAuthority } : undefined).then(asBoolean);
 }
 export function createTelegramBusAwareApiRuntime(deps) {
     return {

package/dist/lib/bus-follower.d.ts

@@ -12,8 +12,10 @@ import { TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_APPLY, TELEGRAM_BUS_CAPABILITY_SELE
 import type { TelegramConfigStore, TelegramThreadDisplayMode } from "./config.ts";
 import { type TelegramUpdateJournalStoreOptions } from "./journal.ts";
 import { type TelegramLockEntry, type TelegramLockState } from "./locks.ts";
+import * as Machine from "./machine.ts";
 import type { TelegramQueueHandoffStageResult } from "./queue.ts";
 import { type TelegramTarget } from "./target.ts";
+import { type TelegramApiCallOptions } from "./telegram-api.ts";
 import * as Threads from "./threads.ts";
 import { type TelegramWorkspaceAdmissionLedger } from "./workspace-admission.ts";
 export declare const TELEGRAM_BUS_FOLLOWER_HEARTBEAT_TIMEOUT_MS = 8000;
@@ -343,7 +345,9 @@ export declare function createTelegramBusFollowerWorkspaceRestoreHandler<TContex
         expectedTarget?: TelegramTarget & {
             threadId: number;
         };
-        release?: (canRelease: () => boolean) => void;
+        release?: (canRelease: () => boolean, target: TelegramTarget & {
+            threadId: number;
+        }) => void;
         observeWork?: (oldTarget: TelegramTarget & {
             threadId: number;
         }) => void;
@@ -362,7 +366,7 @@ export declare function createTelegramBusFollowerWorkspaceRestoreHandler<TContex
 };
 export declare function createTelegramBusFollowerClientRuntime<TContext, TReactionUpdate, TCallbackQuery, TMessage = unknown>(deps: TelegramBusFollowerClientRuntimeDeps<TMessage>): {
     createRequestId: () => string;
-    callApi: (method: string, args: unknown[]) => Promise<unknown>;
+    callApi: (method: string, args: unknown[], localOptions?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<unknown>;
     agentMessages: {
         resolveTarget: (selector: TelegramBusAgentTargetSelector) => Promise<TelegramTarget & {
             threadId: number;
@@ -414,7 +418,7 @@ export declare function createTelegramBusFollowerSelectedMenuCaller<TContext>(de
     effect: TelegramBusSelectedMenuTextEffect;
     assertAuthority: () => void;
 }) => Promise<TelegramBusSelectedMenuDeliveryObservation>;
-export declare function createTelegramBusFollowerApiCaller(deps: TelegramBusFollowerApiCallerDeps): (method: string, args: unknown[]) => Promise<unknown>;
+export declare function createTelegramBusFollowerApiCaller(deps: TelegramBusFollowerApiCallerDeps): (method: string, args: unknown[], localOptions?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<unknown>;
 export declare function createTelegramBusFollowerSessionReplacementSuspender(deps: TelegramBusFollowerSessionReplacementSuspenderDeps): (preserveTarget?: boolean) => Promise<void>;
 export declare function createTelegramBusFollowerSessionRefreshHook<TContext>(deps: TelegramBusFollowerSessionRefreshHookDeps<TContext>): (_event: unknown, ctx: TContext) => Promise<void>;
 export declare function createTelegramBusFollowerControlState(): TelegramBusFollowerControlState;
@@ -426,6 +430,48 @@ export type TelegramBusFollowerHeartbeatRecoveryHandler<TContext> = ((error: unk
     halt: () => void;
     resume: () => void;
 };
+/** The whole recovery lifecycle state; only `transitionTelegramBusFollowerRecovery` produces a new one. */
+export interface TelegramBusFollowerRecoveryState {
+    /** Bumped by halt and resume, so a recovery or retry from before an operator stop or connect is inert. */
+    readonly epoch: number;
+    readonly halted: boolean;
+    /** One recovery runs at a time; it belongs to the epoch it started in. */
+    readonly recovering: boolean;
+    readonly retryId: number | null;
+    readonly nextRetryId: number;
+}
+export type TelegramBusFollowerRecoveryEvent = {
+    type: "recoverRequested";
+} | {
+    type: "recoverySettled";
+    epoch: number;
+} | {
+    type: "retryRequested";
+    epoch: number;
+} | {
+    type: "retryFired";
+    retryId: number;
+} | {
+    type: "halted";
+} | {
+    type: "resumed";
+};
+export type TelegramBusFollowerRecoveryEffect = {
+    type: "runRecovery";
+    epoch: number;
+} | {
+    type: "armRetry";
+    retryId: number;
+} | {
+    type: "cancelRetry";
+    retryId: number;
+};
+export declare function createTelegramBusFollowerRecoveryState(): TelegramBusFollowerRecoveryState;
+/**
+ * Pure follower-recovery lifecycle. An operator stop halts it and a connect resumes it, each in a new epoch: work
+ * from the old epoch, a recovery still awaiting or a retry still armed, can no longer register or promote.
+ */
+export declare function transitionTelegramBusFollowerRecovery(state: TelegramBusFollowerRecoveryState, event: TelegramBusFollowerRecoveryEvent): Machine.TelegramMachineStep<TelegramBusFollowerRecoveryState, TelegramBusFollowerRecoveryEffect>;
 export declare function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(deps: TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext>): TelegramBusFollowerHeartbeatRecoveryHandler<TContext>;
 export declare function createTelegramBusFollowerRegistrationRuntime<TContext extends {
     cwd?: string;