@llblab/pi-telegram 0.52.2 → 0.53.1

package/docs/multi-instance-bus.md

@@ -271,7 +271,7 @@ Followers first try to re-register after leader reload or unknown-heartbeat resp
 
 The session-native local wire contract has protocol version `2`, independent from the npm package version. Follower registration and the leader acknowledgement carry `{ protocolVersion, runtimeBuild, capabilities }`. Capability names are canonical, unique, and sorted. A leader rejects missing or mismatched protocol identity before provisioning a target or publishing the follower into live routing; a strict follower likewise rejects an acknowledgement without compatible leader identity. Different package builds remain compatible when their protocol versions agree. `durable-follower-admission-v1` gates source forwarding, while `queue-handoff-v1` independently gates live semantic queue transfer; every participant in a routed handoff must advertise it. `workspace-follower-auto-connect-v1` gates restore-only startup admission. Session identity is part of protocol v2 rather than an optional capability. Every cwd-scoped v2 registration carries the exact bounded session ID; missing identity is rejected before provisioning or publication. Reconnect, replacement, and promotion preserve it. Protocol-v1 peers are rejected by the base version check, avoiding mixed semantic branches. `thread-display-mode-v1` gates exact-generation follower display-setting requests and Letters/Directories require compatible connected followers; returning to Names allows legacy peers. Registration checks the current display-mode requirement before provisioning and again before live publication. The leader serializes config persistence and title application. `workspace-thread-rename-v1` independently gates follower rename requests whose exact registration generation is checked before the leader mutates Telegram and persists the Workspace binding. `session-replacement-intent-v1` gates Telegram `/new` from a follower Thread: followers never write `state.json`, so `follower.publishSessionReplacement` asks the leader to CAS-publish the durable intent only when the live registration generation, leader epoch, Profile, exact `cwd`, source session, Thread target, and the leader's own Workspace binding slot/name all match, with a bounded unexpired TTL. The intent records the source runtime instance; only a successor registration from that instance or its authenticated same-process handoff (`previousInstanceId`) may re-key the binding, and `follower.settleSessionReplacement` claims it once only after the leader's store shows that successor session bound to the same target. A missing capability, stale generation, or mismatch fails the command closed.
 
-The candidate advertises `workspace-restore-v1`; all participating peers and potential leader successors must be upgraded before operator-controlled use. The retired `leader.replaceFollowerTarget` envelope is no longer parsed or produced, even with current authentication and registration generation. Its `leader.workspaceRestore` envelope carries only an operation ID, exact recipient registration generation and `apply`/`inspect` mode; the receiver derives binding and destination from the retained intent, not caller-supplied target data. Authentication and an explicitly enabled receiver are mandatory. The controller checks both peers' capability and protocol compatibility, captures live registration/session/slot/endpoint authority, sends once without transport retry, then validates the request, operation, recipient, observed target, slot and boolean readiness against the current registration. A lost response leaves the durable issuance consumed; a separate read-only inspection can prove readiness without applying again. Neither the controller nor receiver settles source input or writes follower-owned canonical state. A successor registration/process may inspect only its actual same-session canonical binding and local target; readiness records the new observer separately without changing the original issuance. An old local target cannot be repaired through inspection, and successor apply is rejected. Interrupted startup, terminal source/cleanup settlement and live behavior were accepted in the operator's 0.52.0 live smoke.
+The current root advertises `workspace-restore-v1`; all participating peers and potential leader successors must be upgraded before operator-controlled use. The retired `leader.replaceFollowerTarget` envelope is no longer parsed or produced, even with current authentication and registration generation. Its `leader.workspaceRestore` envelope carries only an operation ID, exact recipient registration generation and `apply`/`inspect` mode; the receiver derives binding and destination from the retained intent, not caller-supplied target data. Authentication and an explicitly enabled receiver are mandatory. The controller checks both peers' capability and protocol compatibility, captures live registration/session/slot/endpoint authority, sends once without transport retry, then validates the request, operation, recipient, observed target, slot and boolean readiness against the current registration. A lost response leaves the durable issuance consumed; a separate read-only inspection can prove readiness without applying again. Neither the controller nor receiver settles source input or writes follower-owned canonical state. A successor registration/process may inspect only its actual same-session canonical binding and local target; readiness records the new observer separately without changing the original issuance. An old local target cannot be repaired through inspection, and successor apply is rejected. Interrupted startup, terminal source/cleanup settlement and live behavior were accepted in the operator's 0.52.0 live smoke.
 
 Negotiated identities remain on the live follower registry and appear in `/telegram-status --debug` plus the observational state snapshot. The Threaded Mode capability monitor owns one in-flight probe across lifecycle generations: stop/restart invalidates a late read, and a replacement monitor waits for the previous request to settle instead of creating overlapping transport transitions. Durable follower admission is authorized only when both peers advertise `durable-follower-admission-v1`, never inferred from package version: a capable runtime rejects missing support before provisioning, inbound routing, or election-roster eligibility. Authentication and exact registration generation remain mandatory independently of protocol compatibility. `follower.register` is the explicit bootstrap request and may provision; capability-gated `follower.restoreWorkspace` is startup-only and may claim, probe, or replace a remembered binding but returns `workspace-binding-unavailable` without allocating when no binding or claim-fenced legacy exact-`cwd` record exists. Both carry a fresh generation; every later request is exact-generation-fenced against the live registry entry. `bus.ack` is response-only and is rejected if submitted as a server request. Leader forwarding never synthesizes authority for an unknown recipient and preserves the follower's exact durable receipt end to end.
 
@@ -285,7 +285,17 @@ Live-process handoff combines journal CAS with authenticated bounded bus payload
 
 As part of staging, the exact recipient presents the token and atomically receives a fresh acquisition carrying the handoff digest; donor settlement is then stale, and the donor trusts only an ACK carrying that accepted owner. Registration carries recipient process-birth and session generation so journal authority matches the live runtime exactly. The coordinator contract shares one ordering across leader→follower and follower→follower paths: offer, route bounded payload, require the exact staged-and-accepted receipt-and-owner ACK, remove donor work, then publish recipient dispatch readiness. Negative or mismatched acknowledgement cancels the still-unaccepted offer and retains donor work. A lost acknowledgement after recipient acceptance cannot revoke the accepted owner; cancellation fails closed and donor memory remains frozen for exact accepted-owner reconciliation. Repeated exact acceptance is idempotent; a different token cannot claim the accepted receipt. Queue authority has no elapsed-time lease: only exact handoff, owner action, or transaction-rechecked PID/process-birth death proof may move it.
 
-Implemented transport:
+### Live-Rebind Channel
+
+The 0.53.0 channel preserves protocol v2 and negotiates live rebinding independently from package version. Release 0.53.0 advertises the following capabilities; an instance still running an older build does not acquire them until it is reloaded. Compatible package versions alone cannot supply missing capabilities:
+
+- `live-thread-rebind-save-v1`, `live-thread-rebind-apply-v1`, `live-thread-rebind-settle-v1`: Exact recipient save/apply/release and source settlement through the shared channel.
+- `live-thread-rebind-command-set-v1`: One `selectedCommand: { name, target }` descriptor and `observe-command` / `command-observed` completion observation, rather than separate status/control wire forms. Retired descriptors and capability names refuse without a compatibility shim.
+- `selected-menu-delivery-v1`: Restricted captured-recipient text/menu effects, independently fenced from source settlement; it is not a generic guarded follower API or arbitrary Bot API grant.
+
+Every participating peer must negotiate the required capabilities and retain current authentication, registration generation, Pi context/session, journal binding and exact recipient authority. The wire validates syntax; Commands' captured registry decides availability before hold/append. Supported built-ins and registered prompt templates reuse one plan set across compatible leader selections and held followers; extension commands/groups/legacy registrations do not gain follower execution. Continue keeps its control lane, while expanded templates are ordinary default-lane prompts even when their text starts with a slash.
+
+Semantic reports, queued receipts, completion observation and delivery remain separate. Native exact ACK and donor CAS still own source disposition; lost or mismatched evidence retains uncertainty without handler replay, another queue or fallback admission. This section owns the unified command-channel policy; [architecture](./architecture.md#live-rebind-module-map) owns the module map. Existing Workspace Restore receivers/readers and queue-handoff retain their custody contracts; the new loaded root prefers live rebinding rather than using legacy Restore as an uncertain-input fallback. Source-enabled bounded cleanup is not proof of an actual deletion or client acceptance. Windows runs the same strict paths, exercised by the CI matrix; actual Pi/client acceptance and release are not inferred from supplied IPC fixtures.
 
 ### Local IPC endpoint with bounded native paths
 
@@ -530,7 +540,7 @@ All files containing routing, chat ids, thread ids, or process details use priva
 
 ### Follower heartbeat is missed
 
-- Leader tolerates up to 15 seconds without a follower heartbeat before pruning it from the live registry, so short local event-loop or IPC stalls do not create false routing gaps. Follower heartbeat requests use a dedicated eight-second response deadline aligned with leader stale-liveness policy rather than the generic one-second local-RPC default. The deadline also defers its final timeout through one socket poll phase: an acknowledgement already buffered while the Pi/TUI event loop was blocked wins, while a genuinely silent peer still fails in the same event-loop turn. Heartbeat pruning remains liveness bookkeeping. One leader generation owns at most one prune operation; stop makes late endpoint, policy, and cleanup settlement inert, while durable-profile mutation serialization prevents replacement registration from crossing confirmed-dead cleanup.
+- Leader tolerates up to 15 seconds without a follower heartbeat before pruning it from the live registry, so short local event-loop or IPC stalls do not create false routing gaps. Follower heartbeat requests use a dedicated eight-second response deadline aligned with leader stale-liveness policy rather than the generic one-second local-RPC default; leader-to-follower Workspace Restore and live-rebind control requests share that window, so a follower busy with journal work or a slower Windows named pipe is not a lost recipient. The deadline also defers its final timeout through one socket poll phase: an acknowledgement already buffered while the Pi/TUI event loop was blocked wins, while a genuinely silent peer still fails in the same event-loop turn. Heartbeat pruning remains liveness bookkeeping. One leader generation owns at most one prune operation; stop makes late endpoint, policy, and cleanup settlement inert, while durable-profile mutation serialization prevents replacement registration from crossing confirmed-dead cleanup.
 - A missed heartbeat does not delete, close, mark offline, or send a disconnected notice for the follower's Telegram thread binding because the common cause may be leader reload, IPC handoff, or transient reconnect rather than a dead follower.
 - After removal from live routing, the current leader retains at most 26 volatile preservation observations with exact registered PID, generation, target, profile and leader epoch. The existing prune loop rechecks alive/unverifiable PIDs and retries non-destructive publication only after fresh explicit absence and a known disabled-cleanup policy. Missing identity or overflow stays protected. Observations never answer heartbeat/API/forwarding requests, launch processes, or authorize deletion. Enabling cleanup cancels deferred preservation rather than promoting it into destructive work; the existing first-prune cleanup path is not retried by this mechanism.
 - Registry registration invalidates overlapping instance/profile-owner/target observations, even if that replacement is removed before the next prune. Admitted same-instance provisioning cancels the old observation before its store writes can precede live registration. Profile/epoch drift, registry clear and leader stop invalidate it; late old completion cannot erase a replacement runtime's observation. No observation survives leader restart, reconstructs a PID from an opaque instance ID, or invents legacy inactivity.
@@ -553,6 +563,8 @@ Local regression evidence covers continuity and cleanup authority; operator-coor
 
 ### Restore controls and cleanup
 
+This section records the conservative pre-0.53.0 runtime that Workspace Restore keeps for continuity with older instances. The 0.53.0 [live Thread rebinding channel](#live-rebind-channel) replaces native-reader parity research with one same-session workflow. Its explicit historical-protection reduction is limited to the new live cleanup origin, not temporary-tab cleanup, retirement, session adoption or legacy journal proofs.
+
 Operator-confirmed client flow: send ordinary text from the **All** tab; Telegram creates a new thread containing that text. Choose **Replace/restore thread…** and the existing Pi instance. Successful leader Restore binds and renames the new thread, dispatches the original message to the same Pi, and removes the old thread. The resulting prompt's thread-name label reflects the restored destination, not proof that the user typed in the old thread. A threadless `/start` is not equivalent to this ordinary-text flow.
 
 Unselected All-tab command choosers expire 60 minutes after the original Telegram message timestamp. Expiry reports terminal settlement only for the exact still-deferred update and makes its callback inert; it does not execute the command or discard an accepted queue receipt. A valid destination selection pauses expiry during dispatch and suppresses concurrent repeat clicks. Failed attempts return to the original deadline without extending it, matching the replay expiry policy after restart. Successful local command dispatch settles a still-deferred source without waiting for background menu delivery; an accepted Pi queue receipt retains its own settlement contract. Follower command forwarding retires a still-deferred source only after confirmed acceptance; thrown or retryable transfer outcomes retain it. Expired replay completes without recreating the chooser. Worker stop invalidates pending chooser authority even without a usable timestamp. The expiry timer rechecks and rearms against its original deadline after backward wall-clock changes. Missing/invalid timestamps are not guessed, and `/thread`, bound-thread messages, ordinary prompts, and classic mode do not use this policy. Journal-write failure preserves the source for recovery; an expired visible chooser may remain, but its button cannot route the command. At pending capacity, new chooser admission fails retryably rather than silently evicting unresolved All commands.

package/docs/outbound.md

@@ -84,7 +84,7 @@ A Guest Mode reply is one `answerGuestQuery` call carrying exactly one `InlineQu
 
 Telegram accepts public URLs or existing Telegram `file_id` values for inline media results, but pi-telegram does not publish local artifacts to external hosting. A local guest document, photo, MP3 audio, or OGG/OPUS voice therefore uses a temporary upload to the paired owner's bot chat, extraction of the returned `file_id`, one cached-media guest answer, and best-effort deletion of the staging message. That message can briefly appear or notify the owner. One guest query can carry only one media item, and its answer text must fit the media caption limit rather than a separate full Rich Markdown message.
 
-Configured text handlers provide `template`. A string is one command; an array is ordered composition. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values. The command-template default timeout applies automatically. Use `template: [...]` for composition; the old local `pipe` alias is removed in 0.13.0.
+Configured text handlers provide `template`. A string is one command; an array is ordered composition. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values. The command-template default timeout applies automatically. Use `template: [...]` for composition; the old local `pipe` alias is removed in 0.13.0. A falsy root `when` skips that handler: inbound and voice selection continue with the next matching handler, while a text transform passes its input through unchanged. A falsy `when` on a composed step, or on any enclosing composition node, skips that step and passes the previous output on. `recover` runs only between failed `retry` attempts of the node that declares it; its output is ignored and a recovery failure stops further retries. `parallel` and `delay` are not executed by these handlers.
 
 ## Text Handler Config
 

package/docs/public-api.md

@@ -62,7 +62,7 @@ Hidden compatibility shortcuts may open sections directly: `/help`, `/status`, `
 
 This command surface is a mobile companion subset, not a raw terminal-command bridge or session browser. A Telegram destination follows its assigned Pi instance and sends prompts into that instance's currently active session; it is not permanently bound to one session identity. Compaction and new-session replacement operate on the current session; resume, fork, tree navigation, session switching, TUI transcript clearing, and arbitrary slash-command dispatch stay out of the stable Telegram API unless Pi exposes safe public extension hooks for them.
 
-An eligible single-text unbound Thread chooser offers **⛔️ Cancel routing** to the current paired owner. It retains the original privately without sending it to Pi or deleting its Telegram message/Thread. This is not `/abort` or `/stop`: already selected, partially forwarded, queued or running work cannot be cancelled here. Failed cancellation or chooser updates retain the same button for exact retry. When the current leader has protected attempts, **Status → ❌ Pending cancellations** opens owner-only review with up to five supported inputs per page. Finish cancellation preserves the original and starts no new delivery; previously accepted work may continue. Refresh, navigation, reload and ownership changes invalidate old controls. Unsupported source kinds are withheld, and corrupt retention evidence stays protected without implicit repair. Inputs already present in the worker's first validated startup snapshot cannot acquire fresh Cancel routing authority merely by recreating their chooser. Existing retained attempts remain recoverable. Historical unbound startup text is still held before default routing, but the Historical inputs menu entry and its review/Stop retrying submenu are removed. Previously published historical callbacks are answered as unavailable; they neither reopen the view nor authorize routing or abandonment. Hiding this technical state does not establish non-delivery or cancel independently accepted work. Confirmed eligible unbound prompt choosers now retain a fixed 60-minute deadline from first positive publication acknowledgement; refresh/restart does not renew it. Validated selection freezes expiry before effects; browsing or unavailable targets does not. Expiry retains the exact unselected original privately before pending-journal removal and invalidates stale controls, without Thread deletion, Pi stop or task-completion reporting. Selected/accepted/uncertain work and historical or unconfirmed clocks remain protected; no tab-disappearance signal is required. The journal lifetime capability and carrier hooks are package-private, not a new companion API. Live acceptance passed in the operator's 0.52.0 live smoke.
+An unbound Thread chooser offers **⛔️ Cancel routing** to the current paired owner for any input it routes: text, commands, any attachment kind and albums alike. The only condition is that every source supports exact private retention. It retains the original privately without sending it to Pi or deleting its Telegram message/Thread. This is not `/abort` or `/stop`: already selected, partially forwarded, queued or running work cannot be cancelled here. Failed cancellation or chooser updates retain the same button for exact retry. When the current leader has protected attempts, **Status → ❌ Pending cancellations** opens owner-only review with up to five supported inputs per page. Finish cancellation preserves the original and starts no new delivery; previously accepted work may continue. Refresh, navigation, reload and ownership changes invalidate old controls. Corrupt retention evidence stays protected without implicit repair. After a restart, an input still waiting for its choice gets its original chooser back, with working buttons and the same deadline, while its tab is unbound; inputs whose choice was already made stay protected until their deadline. Existing retained attempts remain recoverable. Historical unbound startup text is still held before default routing, but the Historical inputs menu entry and its review/Stop retrying submenu are removed. Previously published historical callbacks are answered as unavailable; they neither reopen the view nor authorize routing or abandonment. Hiding this technical state does not establish non-delivery or cancel independently accepted work. Confirmed eligible unbound prompt choosers now retain a fixed 60-minute deadline from first positive publication acknowledgement; refresh/restart does not renew it. Validated selection freezes expiry before effects; browsing or unavailable targets does not. Expiry retains the exact unselected original privately before pending-journal removal and invalidates stale controls, without Thread deletion, Pi stop or task-completion reporting. Selected/accepted/uncertain work and historical or unconfirmed clocks remain protected; no tab-disappearance signal is required. The journal lifetime capability and carrier hooks are package-private, not a new companion API. Live acceptance passed in the operator's 0.52.0 live smoke.
 
 ### Tools and assistant-authored actions
 
@@ -250,6 +250,34 @@ Contract:
 - The command context currently provides `name`, `args`, `reply(text)`, and `enqueuePrompt(prompt)`. Use `enqueuePrompt()` when a command should create normal queued Pi work rather than perform immediate Telegram-side handling.
 - Handler failures are isolated: the bridge records a `telegram-command` runtime diagnostic, sends a compact failure reply, and keeps Telegram polling/routing alive.
 
+### Selected Preparation (Staged 0.53.0 Contract)
+
+Registrations may additionally opt in with `selected.prepare(input)`. Exported types are `SelectedPreparationInput`, `SelectedCommandExecution` and `PreparedSelectedCommand`:
+
+```ts
+interface SelectedPreparationInput {
+  readonly name: string;
+  readonly args: string;
+}
+interface SelectedCommandExecution {
+  assertCurrent(): void;
+  reportCompleted(): boolean;
+  reply(text: string): void;
+}
+type PreparedSelectedCommand =
+  | { kind: "command-only"; execute(ctx: SelectedCommandExecution): void | Promise<void> }
+  | { kind: "generated-prompt"; prompt: string };
+// selected.prepare(input) returns a plan or undefined, synchronously or asynchronously.
+```
+
+Preparation is a trusted side-effect-free producer contract, not a sandbox. It receives only frozen name/args copies: no ordinary reply/enqueue ports, raw update or Pi context. Return `undefined` to refuse. Plans must contain exactly the branch fields above; generated text must be nonblank. The bridge captures the exact registration/callback and a frozen plan, checking source, recipient and registration before/after preparation and plan copying. Errors, invalid plans or stale authority refuse without handler/template fallback.
+
+The approved execution contract calls `execute` once after release. Producers recheck `assertCurrent()` before mutations and after awaits, and explicitly `reportCompleted()` after required semantics. Acceptance is not exact worker removal ACK, delivery success or cleanup authority; returns/errors/replies never auto-complete. The generated branch has no execution callback: the bridge owns one exact normal prompt receipt and selected no-fold admission. Detached replies use independent recipient/registration authority after original disposal; lost reports, receipts or delivery never permit blind replay.
+
+**Implementation boundary:** Public types, Commands preparation and both single-message leader producer branches are locally composed behind the negotiated root gate, advertised since 0.53.0. Command-only execution/source-ACK and detached replies remain separate. Generated input captures its existing worker admission/receipt owner before binding, admits the frozen text once after release through Queue/Turns without raw command media/inbound transforms or history folding, and confirms only exact original/acquiring-owner/recipient/prepared-payload receipt proof. The same warm worker may positively resolve durable readback without another enqueue; missing proof remains unconfirmed. No producer receipt/enqueue port is added. Ordinary dispatch still invokes `handler` only. Legacy registrations, extension groups (including command captions entering prompt coalescing), control input and follower execution remain unsupported. Channel policy and negotiated capabilities live in [Multi-Instance Bus](./multi-instance-bus.md#live-rebind-channel).
+
+The staged core [unified command channel](./multi-instance-bus.md#live-rebind-channel) is package-private and does not widen this registration contract. Its supported built-ins/templates use captured registry plans for compatible leader selections and held followers; that is not follower opt-in for extension producers. Held/selected preparation, queue completion scopes and native journal ACK readers are not public commands/updates exports. Release 0.53.0 advertises the live-rebind capabilities. Neither a matching package version nor `selected.prepare` registration alone supplies negotiated peer/recipient authority, and the running Pi is not reloaded by this source change.
+
 Core commands stay reserved for bridge lifecycle, transport ownership, queue safety, and essential operator controls. Opinionated workflow commands should live in companion extensions through this registry.
 
 ## Sections

package/docs/ui-style.md

@@ -20,7 +20,8 @@ Use emoji as stable semantic markers, not decoration. Emoji carry transportable
 
 | Emoji | Meaning | Canonical surfaces | Notes |
 | --- | --- | --- | --- |
-| `🧵` | Telegram/Pi thread routing | Thread chooser headings, unbound-thread warnings, thread lifecycle/status copy | Canonical thread marker. Do not add it to every concrete target button; target buttons use the acknowledged display title or stable-name fallback. |
+| `🧵` | Telegram/Pi thread | Unbound-thread warnings, thread lifecycle/status copy, and concrete thread target buttons in the Reroute and Restore submenus | Canonical thread marker. In route submenus the action lives in the heading and every target button is a thread, so each one carries `🧵` before its acknowledged display title or stable-name fallback. |
+| `🚦` | Routing decision | Root route chooser heading in unbound or temporary tabs (`🚦 Route this message:`) | The heading only asks for a decision; the buttons name each available action. |
 | `📡` | Telegram transport / bridge connection | Instance connected notices, polling/transport role, bridge online copy | Transport is not thread identity; use `🧵` for thread concepts. |
 | `📊` | Status / overview | `/status` command description, status cards or status rows | Use for status summaries, not queue priority. |
 | `🤖` | Model selection | `/model`, model menu headings, model status rows | Keep model-control surfaces visually distinct from thinking. |
@@ -50,11 +51,10 @@ Use emoji as stable semantic markers, not decoration. Emoji carry transportable
 | `🟥` | Destructive stop command | `/stop` command description | Strong warning at the command/action entrypoint; standalone results use the more precise idle or abort state icon. |
 | `🆕` | New session / fresh start | `/new`, session replacement notices | `/new` replaces the active Pi session while preserving the current classic chat or Thread target; use it only for a real session reset. |
 | `🔄` | Refresh | Queue refresh row and future refresh buttons | Re-fetch/re-render current surface, not transport reconnect. |
-| `↪️` | Reroute to an existing target | Thread chooser buttons that send a captured command/message from one thread to another live thread | Curved arrow means the message arrived here but bends to another target. |
-| `🔁` | Replace/restore mode | Thread replace/restore chooser entrypoints | Opens a second step for moving a Pi instance binding to the current source thread. |
-| `➡️` | Choose replacement target | Thread replace/restore target buttons that select which Pi instance should move to the current thread | Use inside the second replace/restore chooser, not for ordinary reroutes. |
+| `🔀` | Reroute to an existing target | Root `🔀 Reroute: send it to a Pi thread` button, the `🔀 Reroute … to:` submenu heading | Crossing arrows mean the held message branches off to another live thread; its target buttons use `🧵`. |
+| `🔁` | Replace/restore mode | Root `🔁 Restore: move a Pi into this tab` button and the `🔁 Restore into this tab & send …:` submenu heading | Same marker for the action at both levels, like `🔀` for Reroute; its target buttons use `🧵`. |
 | `☑️` | Activate / choose this item | Model detail activation action, generated button-only choice heading | Positive selection cue; use `🟢 Active` for already-current state. |
-| `⛔️` | Cancel source routing | `⛔️ Cancel routing` chooser action and confirmed `⛔️ Routing cancelled.` feedback | Not an abort of active Pi work. Private retention remains mandatory; disposable-tab removal must be stated in the chooser and bound to exact eligible target authority. |
+| `⛔️` | Cancel source routing | `⛔️ Cancel routing` chooser action and confirmed `⛔️ Routing cancelled.` feedback | Not an abort of active Pi work. Private retention remains mandatory; disposable-tab removal stays bound to exact eligible target authority and follows only once every input in the tab is resolved. |
 | `❌` | No / cancel / terminal failure | Confirmation cancel buttons and terminal failure notices | Do not use for a recoverable operation failure that leaves session state intact. |
 | `🗑` | Delete / defer removal | Destructive confirmations and removal reaction | In the queue menu, reversible Keep/Skip selectors replace immediate deletion. |
 
@@ -64,7 +64,7 @@ Use emoji as stable semantic markers, not decoration. Emoji carry transportable
 | --- | --- | --- | --- |
 | `💤` | Nothing active | No-active-turn notices | Neutral idle result, not an error. |
 | `✅` | Completed successfully | Compaction and other completion notices | Use only after the operation has completed. |
-| `🚫` | Unavailable, denied, or cancelled operation | Missing capability/auth notices, access denial, and compaction cancellation | Callback alerts use the same emoji without bold markup. |
+| `🚫` | Unavailable, denied, or cancelled operation | Missing capability/auth notices, access denial, and compaction cancellation | Callback toasts carry no emoji. |
 | `⚠️` | Recoverable operation failure | Compaction failure notice | The attempted operation failed, but the original session state remains usable. |
 
 ### State Indicators And Button Grammars
@@ -108,7 +108,7 @@ The menu may clear internal Skip but cannot remove a reaction created by the use
 
 Some emoji are intentionally local examples or decorative variants, not global semantics. Empty-queue rotating messages (`🫙`, `🍃`, `🕳`, `🦗`, `🌙`, `🧘`, `🪐`, `🧺`, `🔭`, `🫧`, `🛸`) are copy flavor only and must not become controls. The Guest Mode placeholder frames (`🌎`, `🌍`, `🌏` stepping every second with dots growing once every two seconds) are the same kind of decorative copy: they complete whole 6-frame cycles over at least a ~20 s rotation while a guest answer is pending and then hold the cycle's final frame (a 26 s safety bound caps slow streams), never become controls, and must not carry another meaning. Example extension icons such as `🧪`, `🔧`, and `🗂` are documentation fixtures for companion extensions, not built-in pi-telegram meanings.
 
-Thread UI rule: when a message heading, chooser, or status line is specifically about Telegram/Pi threads or target thread selection, start the heading with `🧵`. Button labels for concrete thread targets should stay clean (`threadName` or slot fallback) and should not add `🧵` to every target button unless the row would otherwise be ambiguous.
+Thread UI rule: thread lifecycle and status copy starts with `🧵`. Route choosers lead with their action instead: `🚦` asks for the routing decision at the root, the `🔀`/`🔁` submenu headings name the chosen action, and the concrete thread target buttons beneath them carry `🧵`, so the same marker always means "a thread".
 
 ## Button Control Hierarchy
 
@@ -232,10 +232,24 @@ Examples:
 - Main menu → Settings: first row is `⬆️ Main menu`.
 - Settings → Voice reply mode: first row is `⬆️ Back`.
 
+## Route Chooser
+
+A message (or All-tab command) held in an unbound or temporary tab gets one route chooser.
+
+- Root text: bold heading `🚦 Route this message:` (or `🚦 Route <code>/start</code>:` for a command), a blank line, then the italic note `The choice expires in 60 minutes.` When Reroute is the only possible action (an All-tab command without a temporary tab), the italic note says `To restore a Pi instead, send a message in a new tab.` instead.
+- Root buttons, one per row and only when available: `🔀 Reroute: send it to a Pi thread`, `🔁 Restore: move a Pi into this tab`, `⛔️ Cancel routing`. The `🚦` heading echoes these three choices, with `⛔️` as the red stop.
+- Submenus start with `⬆️ Back`, which restores the root with its exact original text. Headings name the same subject as the root: bold `🔀 Reroute this message to:` / `🔀 Reroute <code>/start</code> to:`, and `🔁 Restore into this tab & send this message:` / `🔁 Restore into this tab & send <code>/start</code>:`. Every target button below is a thread, written `🧵 <display title>`.
+- Cancel appears only at the root. A confirmed cancellation replaces the chooser with bold `⛔️ Routing cancelled.` and an empty keyboard.
+- Old or expired controls answer `⌛ Routing choice expired.`
+- Tab name: every temporary routing tab is named `🚦 Routing`, whether the bot created it (menu command or threadless prompt) or adopted the `New Chat` tab Telegram opened for a typed input. It is never renamed after its first input.
+- Status → `❌ Pending cancellations` lists one row per protected original: its text, or `📎` plus the caption, file name or the message field carrying Telegram's `file_id`.
+
 ## Pi Connection Notices
 
 Pi TUI connection notices use plain text: a short known cause and one recovery action. Unknown failures use a generic connection-failed notice with `/telegram-status --debug`; never interpolate raw exceptions, credentials, stack traces or Pi lifecycle guidance. Technical evidence belongs in the redacted runtime recorder. Failed disconnect must retain the instruction to keep Pi open; do not also rethrow the same error as a second Pi banner. These TUI notices are distinct from Telegram bot message cards below.
 
+The compact TUI status bar preserves the acknowledged Thread display title and its casing, including manual `/name` overrides. Names equal to `Telegram`, `Leader` or `Follower` are ordinary titles, not fallback markers. Connection states, including disconnected and error, do not replace a supplied title; only an absent or empty title uses the generic `telegram` label.
+
 ## Message Cards
 
 Message cards and standalone informational notices sent by the bot should start with a strong heading.
@@ -244,10 +258,13 @@ 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. Menu or chooser headings use the same fully bold form but end in a colon when controls or detail follow. Empty-queue headings are the deliberate exception: fully bold, with no trailing period or colon.
+- List items in bot-authored messages and cards start with `<code>-</code>` and a space, the same marker rendered Markdown lists use; never `•`.
 - 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.
 - Once an action has settled, describe only the completed result in completed-state language. Do not append transitional copy such as “returning” or “starting”; use a separate progress surface only while work is genuinely still pending.
-- Transient callback toasts remain plain text with the relevant emoji and concise wording, without a terminal sentence period. The shared typed callback-answer boundary applies this on direct and follower delivery while preserving question/exclamation marks and ellipses. In-chat notices, headings, blocking alerts and explicit raw API payloads retain their own punctuation contracts.
+- Distinguish the two surfaces. An in-chat notice stays in the conversation (a sent message or an edited chooser/menu/card) and uses the bold, period-terminated form above. A callback toast is the client's fleeting tooltip that vanishes after a couple of seconds: concise plain text with no emoji and no terminal sentence period; question/exclamation marks and ellipses stay. Every toast follows this one form, so emoji meanings in the registry apply to messages, headings and buttons, never to toasts.
+- Write every notice and toast in its final form where it is used. No delivery boundary rewrites punctuation, so text shared by both surfaces is two separate strings, each in its own form; companion `ctx.answerCallback` text likewise reaches the client exactly as written.
+- Navigation answers silently: opening a submenu or going Back, in the main menu and in temporary routing tabs alike, edits the message and acknowledges the tap without a toast. The edited message is the feedback.
 - 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.
 - Order setting value descriptions exactly like the chooser: rows top-to-bottom and values in a shared row left-to-right. Keep `(default)` on the actual default wherever it falls; default status never changes order.

package/lib/activity-verbosity.ts

@@ -4,11 +4,15 @@
  * Owns persistent bounded thinking and tool disclosures; excludes activity normalization, assistant answer rendering, and transport authority policy
  */
 
-import type { TelegramActivityEvent, TelegramActivityPublicationRuntime } from "./activity.ts";
+import type {
+  TelegramActivityEvent,
+  TelegramActivityPublicationRuntime,
+} from "./activity.ts";
+import { escapeHtml, renderTelegramInlineMarkdownHtml } from "./rendering.ts";
 import {
-  escapeHtml,
-  renderTelegramInlineMarkdownHtml,
-} from "./rendering.ts";
+  areTelegramTargetsEqual as targetEquals,
+  type TelegramTarget,
+} from "./target.ts";
 import type {
   TelegramEditMessageTextBody,
   TelegramInputRichBlock,
@@ -17,7 +21,6 @@ import type {
   TelegramSendRichMessageBody,
   TelegramSentMessage,
 } from "./telegram-api.ts";
-import { areTelegramTargetsEqual as targetEquals, type TelegramTarget } from "./target.ts";
 
 const TELEGRAM_ACTIVITY_DETAIL_MAX_CHARS = 1_200;
 const TELEGRAM_ACTIVITY_MESSAGE_MAX_CHARS = 3_900;
@@ -55,10 +58,7 @@ interface ReasoningMessage {
 function redactActivityText(text: string): string {
   return text
     .replace(/\b\d{8,12}:[A-Za-z0-9_-]{30,}\b/g, "[REDACTED_BOT_TOKEN]")
-    .replace(
-      /\b(Bearer\s+)[A-Za-z0-9._~+/=-]{16,}\b/gi,
-      "$1[REDACTED]",
-    )
+    .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/=-]{16,}\b/gi, "$1[REDACTED]")
     .replace(
       /(["']?(?:api[_-]?key|token|password|secret)["']?\s*[:=]\s*["']?)[^"',\s}]+/gi,
       "$1[REDACTED]",
@@ -89,9 +89,7 @@ function formatActivityJson(value: unknown, depth = 0): string[] {
             lines[lines.length - 1] += ",";
           }
         });
-        lines.push(
-          index < value.length - 1 ? `${indent}}, {` : `${indent}}]`,
-        );
+        lines.push(index < value.length - 1 ? `${indent}}, {` : `${indent}}]`);
       });
       return lines;
     }
@@ -130,17 +128,14 @@ function serializeActivityValue(value: unknown): string {
   let text: string;
   try {
     const normalized =
-      JSON.stringify(
-        value,
-        (_key, nested) => {
-          if (typeof nested === "bigint") return nested.toString();
-          if (nested && typeof nested === "object") {
-            if (seen.has(nested)) return "[Circular]";
-            seen.add(nested);
-          }
-          return nested;
-        },
-      ) ?? JSON.stringify(String(value));
+      JSON.stringify(value, (_key, nested) => {
+        if (typeof nested === "bigint") return nested.toString();
+        if (nested && typeof nested === "object") {
+          if (seen.has(nested)) return "[Circular]";
+          seen.add(nested);
+        }
+        return nested;
+      }) ?? JSON.stringify(String(value));
     text = formatActivityJson(JSON.parse(normalized)).join("\n");
   } catch {
     text = JSON.stringify(String(value));
@@ -185,18 +180,12 @@ function renderToolActivityHtml(tool: ToolActivity): string {
     evidence.push(`… [${tool.droppedUpdates} earlier updates omitted]`);
   }
   tool.updates.forEach((update, index) => {
-    evidence.push(
-      `"update ${tool.droppedUpdates + index + 1}": ${update}`,
-    );
+    evidence.push(`"update ${tool.droppedUpdates + index + 1}": ${update}`);
   });
   if (tool.complete && tool.result !== undefined) {
     evidence.push(`"${tool.isError ? "error" : "result"}": ${tool.result}`);
   }
-  const status = tool.complete
-    ? tool.isError
-      ? "failed"
-      : "done"
-    : "running";
+  const status = tool.complete ? (tool.isError ? "failed" : "done") : "running";
   return [
     `<b>${escapeHtml(formatToolActivityLabel(tool.name))}:</b> <code>${status}</code>`,
     `<blockquote expandable>${escapeActivityEvidenceHtml(evidence.join("\n\n"))}</blockquote>`,
@@ -225,11 +214,7 @@ function createToolActivityDetail(
 function renderToolActivityRichBlocks(
   tool: ToolActivity,
 ): TelegramInputRichBlock[] {
-  const status = tool.complete
-    ? tool.isError
-      ? "failed"
-      : "done"
-    : "running";
+  const status = tool.complete ? (tool.isError ? "failed" : "done") : "running";
   const evidenceBlocks: TelegramInputRichBlock[] = [
     createToolActivityDetail("arguments", tool.args, true),
   ];
@@ -278,7 +263,9 @@ function toolMessageSize(tools: readonly ToolActivity[]): number {
 }
 
 function isKnownSafeRichActivityRejection(error: unknown): boolean {
-  return error instanceof Error && /HTTP 400: Bad Request:/i.test(error.message);
+  return (
+    error instanceof Error && /HTTP 400: Bad Request:/i.test(error.message)
+  );
 }
 
 export function renderTelegramThinkingActivityHtml(text: string): string {
@@ -292,32 +279,6 @@ export interface TelegramActivityVerbosityRuntime {
   waitForIdle: () => Promise<void>;
 }
 
-export interface TelegramActivityVerbosityBinding
-  extends TelegramActivityVerbosityRuntime {
-  bind: (runtime: TelegramActivityVerbosityRuntime) => void;
-}
-
-export function createTelegramActivityVerbosityBinding(): TelegramActivityVerbosityBinding {
-  let runtime: TelegramActivityVerbosityRuntime | undefined;
-  return {
-    bind(next) {
-      runtime = next;
-    },
-    accept(event) {
-      runtime?.accept(event);
-    },
-    reset() {
-      runtime?.reset();
-    },
-    stop() {
-      runtime?.stop();
-    },
-    waitForIdle() {
-      return runtime?.waitForIdle() ?? Promise.resolve();
-    },
-  };
-}
-
 export function createTelegramActivityVerbosityRuntime<TAuthority>(deps: {
   enqueue?: TelegramActivityPublicationRuntime["enqueue"];
   getActivityMode: () => "quiet" | "thinking" | "tools" | "verbose";
@@ -391,8 +352,14 @@ export function createTelegramActivityVerbosityRuntime<TAuthority>(deps: {
   };
   const hasAuthority = (): boolean =>
     authority !== undefined && deps.isAuthorityActive(authority);
-  const isCurrent = (acceptedGeneration: number, admittedAuthority: TAuthority | undefined): boolean =>
-    active && generation === acceptedGeneration && admittedAuthority !== undefined && deps.isAuthorityActive(admittedAuthority);
+  const isCurrent = (
+    acceptedGeneration: number,
+    admittedAuthority: TAuthority | undefined,
+  ): boolean =>
+    active &&
+    generation === acceptedGeneration &&
+    admittedAuthority !== undefined &&
+    deps.isAuthorityActive(admittedAuthority);
   const ensureActivity = (
     event: TelegramActivityEvent,
     admittedTarget: TelegramTarget | undefined,
@@ -433,7 +400,9 @@ export function createTelegramActivityVerbosityRuntime<TAuthority>(deps: {
       );
       body = renderTelegramThinkingActivityHtml(text);
       if (body.length <= TELEGRAM_ACTIVITY_MESSAGE_MAX_CHARS) break;
-      retained = retained.slice(-Math.max(1, Math.floor(retained.length * 0.75)));
+      retained = retained.slice(
+        -Math.max(1, Math.floor(retained.length * 0.75)),
+      );
     } while (retained.length > 1);
     const canEdit =
       reasoningMessage && targetEquals(reasoningMessage.target, target);
@@ -481,9 +450,8 @@ export function createTelegramActivityVerbosityRuntime<TAuthority>(deps: {
     acceptedGeneration: number,
   ) => {
     if (reasoningFlushTimer || reasoningBlocked) return;
-    const elapsed = reasoningMessageFrames === 0
-      ? 0
-      : getNowMs() - lastReasoningPublishMs;
+    const elapsed =
+      reasoningMessageFrames === 0 ? 0 : getNowMs() - lastReasoningPublishMs;
     const delayMs = Math.max(0, TELEGRAM_REASONING_MIN_INTERVAL_MS - elapsed);
     const schedule = deps.setReasoningTimeout ?? setTimeout;
     reasoningFlushTimer = schedule(() => {
@@ -493,10 +461,12 @@ export function createTelegramActivityVerbosityRuntime<TAuthority>(deps: {
         if (
           !isCurrent(acceptedGeneration, admittedAuthority) ||
           reasoningChars <= lastReasoningMessageChars
-        ) return;
+        )
+          return;
         await publishReasoning(event, acceptedGeneration);
       };
-      const enqueue = deps.enqueue ?? ((next: () => Promise<void>) => tail.then(next));
+      const enqueue =
+        deps.enqueue ?? ((next: () => Promise<void>) => tail.then(next));
       tail = enqueue(task).catch((error) => {
         deps.recordFailure?.("reasoning-send", event, error);
       });
@@ -721,10 +691,7 @@ export function createTelegramActivityVerbosityRuntime<TAuthority>(deps: {
     }
     if (event.type === "agent-end" || event.type === "agent-settled") {
       clearReasoningFlushTimer();
-      if (
-        reasoningChars > lastReasoningMessageChars &&
-        !reasoningBlocked
-      ) {
+      if (reasoningChars > lastReasoningMessageChars && !reasoningBlocked) {
         await publishReasoning(event, acceptedGeneration);
       }
       if (!isCurrent(acceptedGeneration, admittedAuthority)) return;
@@ -738,14 +705,24 @@ export function createTelegramActivityVerbosityRuntime<TAuthority>(deps: {
       const resolvedTarget = deps.resolveTarget(event);
       const admittedTarget = resolvedTarget ? { ...resolvedTarget } : undefined;
       const admittedAuthority = deps.captureAuthority();
-      const enqueue = deps.enqueue ?? ((task: () => Promise<void>) => tail.then(task));
+      const enqueue =
+        deps.enqueue ?? ((task: () => Promise<void>) => tail.then(task));
       tail = enqueue(async () => {
-          if (!active || generation !== acceptedGeneration || !deps.isAuthorityActive(admittedAuthority)) return;
-          await process(event, acceptedGeneration, admittedTarget, admittedAuthority);
-        })
-        .catch((error) => {
-          deps.recordFailure?.("tool-send", event, error);
-        });
+        if (
+          !active ||
+          generation !== acceptedGeneration ||
+          !deps.isAuthorityActive(admittedAuthority)
+        )
+          return;
+        await process(
+          event,
+          acceptedGeneration,
+          admittedTarget,
+          admittedAuthority,
+        );
+      }).catch((error) => {
+        deps.recordFailure?.("tool-send", event, error);
+      });
     },
     reset() {
       generation += 1;